Skip to content

Commit af49cfa

Browse files
gracefullightgracefullight
committed
docs: add star history chart to README
1 parent 58c4528 commit af49cfa

7 files changed

Lines changed: 496 additions & 280 deletions

File tree

‎.agent/skills/_shared/clarification-protocol.md‎

Lines changed: 158 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -1,55 +1,142 @@
11
# Clarification Protocol
22

3-
When requirements are ambiguous, "assuming and proceeding" usually leads to the wrong direction.
4-
Follow this protocol to secure clear requirements before execution.
3+
요구사항이 모호할 때 "가정하고 진행"하면 대부분 잘못된 방향으로 간다.
4+
이 프로토콜을 따라 명확한 요구사항을 확보한 후 실행한다.
5+
6+
> **핵심 원칙**: "Agents learn when to ask for help rather than blindly attempting every task" - Ask early, ask often.
7+
8+
---
9+
10+
## 불확실성 레벨 정의 (Uncertainty Levels)
11+
12+
| 레벨 | 상태 | 행동 | 예시 |
13+
|------|------|------|------|
14+
| **LOW** | 명확함 | 기본값 적용 후 진행, 가정 기록 | "TODO 앱 만들어줘" |
15+
| **MEDIUM** | 일부 모호 | 2-3개 옵션 제시 + 사용자 선택 요청 | "사용자 관리 시스템 만들어줘" |
16+
| **HIGH** | 매우 모호 | **진행 불가**, 반드시 질문 | "좋은 앱 만들어줘" |
17+
18+
---
19+
20+
## 불확실성 트리거 (Uncertainty Triggers)
21+
22+
다음 상황에서 자동으로 MEDIUM/HIGH 레벨로 분류:
23+
24+
### HIGH (반드시 질문)
25+
- [ ] 비즈니스 로직 결정 필요 (가격 정책, 승인 워크플로우 등)
26+
- [ ] 보안/인증 관련 결정 (OAuth provider, 권한 모델 등)
27+
- [ ] 기존 코드와 충돌 가능성 있음
28+
- [ ] 요구사항이主관적 ("좋은", "빠른", "예쁜")
29+
- [ ] 범위가 무제한으로 느껴짐
30+
31+
### MEDIUM (옵션 제시)
32+
- [ ] 기술 스택 선택 가능성 2개 이상
33+
- [ ] 구현 방식에 대한 trade-off 존재
34+
- [ ] 우선순위가 불명확한 다중 기능
35+
- [ ] 외부 API/서비스 선택 필요
36+
37+
---
38+
39+
## 에스컬레이션 템플릿 (Escalation Templates)
40+
41+
### LOW → 진행 (Assumed)
42+
```
43+
⚠️ Assumptions applied:
44+
- JWT authentication included
45+
- PostgreSQL database
46+
- REST API
47+
- MVP scope (CRUD only)
48+
49+
Proceeding with these defaults. Override if needed.
50+
```
51+
52+
### MEDIUM → 선택 요청 (Options)
53+
```
54+
🔍 Uncertainty detected: {specific issue}
55+
56+
Option A: {approach}
57+
✅ Pros: {benefits}
58+
❌ Cons: {drawbacks}
59+
💰 Effort: {low/medium/high}
60+
61+
Option B: {approach}
62+
✅ Pros: {benefits}
63+
❌ Cons: {drawbacks}
64+
💰 Effort: {low/medium/high}
65+
66+
Option C: {approach}
67+
✅ Pros: {benefits}
68+
❌ Cons: {drawbacks}
69+
💰 Effort: {low/medium/high}
70+
71+
Which approach do you prefer? (A/B/C)
72+
```
73+
74+
### HIGH → 차단 (Blocked)
75+
```
76+
❌ Cannot proceed: Requirements too ambiguous
77+
78+
Specific uncertainty: {what is unclear}
79+
80+
Questions needed:
81+
1. {specific question}
82+
2. {specific question}
83+
3. {specific question}
84+
85+
Impact of proceeding blindly: {what could go wrong}
86+
87+
Status: BLOCKED (awaiting clarification)
88+
```
589

690
---
791

8-
## Required Confirmation Items
9-
10-
If any of the items below are unclear, **do not assume** — explicitly document them.
11-
12-
### Common to All Agents
13-
| Item | Confirmation Question | Default (when assuming) |
14-
|------|----------------------|------------------------|
15-
| Target Users | Who will use this service? | General web users |
16-
| Core Features | What are the 3 must-have features? | Infer from task description |
17-
| Tech Stack | Are there specific framework constraints? | Project default stack |
18-
| Authentication | Is login required? | Include JWT auth |
19-
| Scope | Is this MVP or full feature? | MVP |
20-
21-
### Backend Agent Additional Confirmations
22-
| Item | Confirmation Question | Default |
23-
|------|----------------------|---------|
24-
| DB Choice | PostgreSQL? MongoDB? SQLite? | PostgreSQL |
25-
| API Style | REST? GraphQL? | REST |
26-
| Auth Method | JWT? Session? OAuth? | JWT (access + refresh) |
27-
| File Upload | Required? Size limit? | Not required |
28-
29-
### Frontend Agent Additional Confirmations
30-
| Item | Confirmation Question | Default |
31-
|------|----------------------|---------|
32-
| SSR/CSR | Server-side rendering needed? | Next.js App Router (SSR) |
33-
| Dark Mode | Support required? | Supported |
34-
| i18n | Multi-language support? | Not required |
35-
| Existing Design System | UI library to use? | shadcn/ui |
36-
37-
### Mobile Agent Additional Confirmations
38-
| Item | Confirmation Question | Default |
39-
|------|----------------------|---------|
40-
| Platform | iOS only? Android only? Both? | Both |
41-
| Offline | Offline support needed? | Not required |
42-
| Push Notifications | Required? | Not required |
43-
| Minimum OS | iOS/Android minimum version? | iOS 14+, Android API 24+ |
92+
## 필수 확인 항목
93+
94+
아래 항목 중 하나라도 불명확하면 **가정하지 말고** 명시적으로 기록한다.
95+
96+
### 모든 에이전트 공통
97+
| 항목 | 확인 질문 | 기본값 (가정 시) | 불확실성 |
98+
|------|----------|-----------------|----------|
99+
| 대상 사용자 | 누가 쓰는 서비스인가? | 일반 웹 사용자 | LOW |
100+
| 핵심 기능 | 반드시 포함해야 할 기능 3가지는? | 태스크 설명에서 추론 | MEDIUM |
101+
| 기술 스택 | 특정 프레임워크 제약이 있는가? | 프로젝트 기본 스택 | LOW |
102+
| 인증 | 로그인이 필요한가? | JWT 인증 포함 | MEDIUM |
103+
| 범위 | MVP인가 완전한 기능인가? | MVP | LOW |
104+
105+
### Backend Agent 추가 확인
106+
| 항목 | 확인 질문 | 기본값 | 불확실성 |
107+
|------|----------|--------|----------|
108+
| DB 선택 | PostgreSQL? MongoDB? SQLite? | PostgreSQL | MEDIUM |
109+
| API 스타일 | REST? GraphQL? gRPC? | REST | MEDIUM |
110+
| 인증 방식 | JWT? Session? OAuth? | JWT (access + refresh) | HIGH |
111+
| 파일 업로드 | 필요한가? 크기 제한은? | 불필요 | LOW |
112+
| 배포 환경 | Serverless? Container? VM? | Container | MEDIUM |
113+
114+
### Frontend Agent 추가 확인
115+
| 항목 | 확인 질문 | 기본값 | 불확실성 |
116+
|------|----------|--------|----------|
117+
| SSR/CSR | Server-side rendering 필요? | Next.js App Router (SSR) | MEDIUM |
118+
| 다크모드 | 지원 필요? | 지원 | LOW |
119+
| 국제화 | 다국어 지원? | 불필요 | LOW |
120+
| 기존 디자인 시스템 | 사용할 UI 라이브러리? | shadcn/ui | MEDIUM |
121+
| 상태 관리 | Context? Redux? Zustand? | Zustand | MEDIUM |
122+
123+
### Mobile Agent 추가 확인
124+
| 항목 | 확인 질문 | 기본값 | 불확실성 |
125+
|------|----------|--------|----------|
126+
| 플랫폼 | iOS만? Android만? 둘 다? | 둘 다 | MEDIUM |
127+
| 오프라인 | 오프라인 지원 필요? | 불필요 | LOW |
128+
| 푸시 알림 | 필요한가? | 불필요 | LOW |
129+
| 최소 OS | iOS/Android 최소 버전? | iOS 14+, Android API 24+ | LOW |
130+
| 아키텍처 | MVC? MVVM? Clean? | MVVM | MEDIUM |
44131

45132
---
46133

47-
## Response by Ambiguity Level
134+
## 모호함 수준별 대응 (상세)
48135

49-
### Level 1: Slightly Ambiguous (Core is clear, details missing)
50-
Example: "Create a TODO app"
136+
### Level 1 (LOW): 약간 모호 (핵심은 명확, 세부사항 부족)
137+
예: "TODO 앱 만들어줘"
51138

52-
**Response**: Apply defaults and record assumptions in result
139+
**대응**: 기본값을 적용하고, 가정 목록을 result에 기록
53140
```
54141
⚠️ Assumptions:
55142
- JWT authentication included
@@ -58,10 +145,10 @@ Example: "Create a TODO app"
58145
- MVP scope (CRUD only)
59146
```
60147

61-
### Level 2: Considerably Ambiguous (Core features unclear)
62-
Example: "Create a user management system"
148+
### Level 2 (MEDIUM): 상당히 모호 (핵심 기능이 불명확)
149+
예: "사용자 관리 시스템 만들어줘"
63150

64-
**Response**: Narrow down to 3 core features and proceed
151+
**대응**: 핵심 기능을 3가지로 좁혀서 명시하고 진행
65152
```
66153
⚠️ Interpreted scope (3 core features):
67154
1. User registration + login (JWT)
@@ -74,10 +161,10 @@ NOT included (would need separate task):
74161
- Email verification
75162
```
76163

77-
### Level 3: Highly Ambiguous (Direction itself unclear)
78-
Example: "Make a good app", "Improve this"
164+
### Level 3 (HIGH): 매우 모호 (방향 자체가 불명확)
165+
예: "좋은 앱 만들어줘", "이거 개선해줘"
79166

80-
**Response**: Do not proceed, record clarification request in result
167+
**대응**: 진행하지 말고 구체화 요청을 result에 기록
81168
```
82169
❌ Cannot proceed: Requirements too ambiguous
83170
@@ -92,39 +179,39 @@ Status: blocked (awaiting clarification)
92179

93180
---
94181

95-
## PM Agent Exclusive: Requirements Specification Framework
182+
## PM Agent 전용: 요구사항 구체화 프레임워크
96183

97-
When PM Agent receives an ambiguous request, use this framework to clarify:
184+
PM Agent는 모호한 요청을 받으면 아래 프레임워크로 구체화한다:
98185

99186
```
100-
=== Requirements Specification ===
187+
=== 요구사항 구체화 ===
101188
102-
Original Request: "{user's original text}"
189+
원본 요청: "{사용자 원문}"
103190
104-
1. Core Goal: {define in one sentence}
105-
2. User Stories:
191+
1. 핵심 목표: {한 문장으로 정의}
192+
2. 사용자 스토리:
106193
- "As a {user}, I want to {action} so that {benefit}"
107-
- (minimum 3)
108-
3. Feature Scope:
109-
- Must-have: {list}
110-
- Nice-to-have: {list}
111-
- Out-of-scope: {list}
112-
4. Technical Constraints:
113-
- {existing code / stack / compatibility}
114-
5. Success Criteria:
115-
- {measurable conditions}
194+
- (최소 3개)
195+
3. 기능 범위:
196+
- Must-have: {목록}
197+
- Nice-to-have: {목록}
198+
- Out-of-scope: {목록}
199+
4. 기술 제약:
200+
- {기존 코드 / 스택 / 호환성}
201+
5. 성공 기준:
202+
- {측정 가능한 조건}
116203
```
117204

118205
---
119206

120-
## Application in Subagent Mode
207+
## 서브에이전트 모드에서의 적용
121208

122-
CLI subagents cannot ask questions directly to users.
123-
Therefore:
209+
CLI 서브에이전트는 사용자에게 직접 질문할 수 없다.
210+
따라서:
124211

125-
1. **Level 1**: Apply defaults + record assumptions → proceed
126-
2. **Level 2**: Narrow and interpret scope + document → proceed
127-
3. **Level 3**: `Status: blocked` + question list → do not proceed
212+
1. **Level 1**: 기본값 적용 + 가정 기록 → 진행
213+
2. **Level 2**: 범위를 좁혀서 해석 + 명시 → 진행
214+
3. **Level 3**: `Status: blocked` + 질문 목록 → 진행하지 않음
128215

129-
When Orchestrator receives a Level 3 result, it forwards the questions to the user,
130-
and after receiving answers, re-runs the agent.
216+
Orchestrator는 Level 3 결과를 받으면 사용자에게 질문을 전달하고,
217+
답변을 받은 후 해당 에이전트를 재실행한다.

0 commit comments

Comments
 (0)