11# Clarification Protocol
22
3- 요구사항이 모호할 때 "가정하고 진행"하면 대부분 잘못된 방향으로 간다 .
4- 이 프로토콜을 따라 명확한 요구사항을 확보한 후 실행한다 .
3+ When requirements are ambiguous, "assuming and proceeding" usually leads in the wrong direction .
4+ Follow this protocol to secure clear requirements before execution .
55
6- > ** 핵심 원칙 ** : "Agents learn when to ask for help rather than blindly attempting every task" - Ask early, ask often.
6+ > ** Core Principle ** : "Agents learn when to ask for help rather than blindly attempting every task" - Ask early, ask often.
77
88---
99
10- ## 불확실성 레벨 정의 ( Uncertainty Levels)
10+ ## Uncertainty Level Definitions
1111
12- | 레벨 | 상태 | 행동 | 예시 |
13- | ------| ------| ------| ------|
14- | ** LOW** | 명확함 | 기본값 적용 후 진행, 가정 기록 | "TODO 앱 만들어줘 " |
15- | ** MEDIUM** | 일부 모호 | 2-3개 옵션 제시 + 사용자 선택 요청 | "사용자 관리 시스템 만들어줘 " |
16- | ** HIGH** | 매우 모호 | ** 진행 불가 ** , 반드시 질문 | "좋은 앱 만들어줘 " |
12+ | Level | State | Action | Example |
13+ | ------- | ------- | -------- | --- ------|
14+ | ** LOW** | Clear | Apply defaults and proceed, record assumptions | "Create a TODO app " |
15+ | ** MEDIUM** | Partially ambiguous | Present 2-3 options + request user selection | "Create a user management system " |
16+ | ** HIGH** | Very ambiguous | ** Cannot proceed ** , must ask questions | "Create a good app " |
1717
1818---
1919
20- ## 불확실성 트리거 ( Uncertainty Triggers)
20+ ## Uncertainty Triggers
2121
22- 다음 상황에서 자동으로 MEDIUM/HIGH 레벨로 분류 :
22+ Automatically classify as MEDIUM/HIGH level in the following situations :
2323
24- ### HIGH (반드시 질문 )
25- - [ ] 비즈니스 로직 결정 필요 (가격 정책, 승인 워크플로우 등 )
26- - [ ] 보안/인증 관련 결정 (OAuth provider, 권한 모델 등 )
27- - [ ] 기존 코드와 충돌 가능성 있음
28- - [ ] 요구사항이主관적 ("좋은 ", "빠른 ", "예쁜 ")
29- - [ ] 범위가 무제한으로 느껴짐
24+ ### HIGH (Must Ask )
25+ - [ ] Business logic decisions needed (pricing policy, approval workflow, etc. )
26+ - [ ] Security/authentication decisions (OAuth provider, permission model, etc. )
27+ - [ ] Possible conflict with existing code
28+ - [ ] Requirements are subjective ("good ", "fast ", "pretty ")
29+ - [ ] Scope feels unlimited
3030
31- ### MEDIUM (옵션 제시 )
32- - [ ] 기술 스택 선택 가능성 2개 이상
33- - [ ] 구현 방식에 대한 trade-off 존재
34- - [ ] 우선순위가 불명확한 다중 기능
35- - [ ] 외부 API/서비스 선택 필요
31+ ### MEDIUM (Present Options )
32+ - [ ] 2+ technology stack choices possible
33+ - [ ] Trade-offs exist for implementation approach
34+ - [ ] Multiple features with unclear priority
35+ - [ ] External API/service selection needed
3636
3737---
3838
39- ## 에스컬레이션 템플릿 ( Escalation Templates)
39+ ## Escalation Templates
4040
41- ### LOW → 진행 (Assumed)
41+ ### LOW → Proceed (Assumed)
4242```
4343⚠️ Assumptions applied:
4444- JWT authentication included
4949Proceeding with these defaults. Override if needed.
5050```
5151
52- ### MEDIUM → 선택 요청 (Options)
52+ ### MEDIUM → Request Selection (Options)
5353```
5454🔍 Uncertainty detected: {specific issue}
5555
@@ -71,7 +71,7 @@ Option C: {approach}
7171Which approach do you prefer? (A/B/C)
7272```
7373
74- ### HIGH → 차단 ( Blocked)
74+ ### HIGH → Blocked
7575```
7676❌ Cannot proceed: Requirements too ambiguous
7777
@@ -89,54 +89,54 @@ Status: BLOCKED (awaiting clarification)
8989
9090---
9191
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 |
92+ ## Required Verification Items
93+
94+ If any of the items below are unclear, ** do not assume ** — explicitly record them .
95+
96+ ### Common to All Agents
97+ | Item | Verification Question | Default (if assumed ) | Uncertainty |
98+ | ------| ---------------------- | --------------------- | --- ----------|
99+ | Target users | Who will use this service ? | General web users | LOW |
100+ | Core features | What are the 3 must-have features ? | Infer from task description | MEDIUM |
101+ | Tech stack | Are there specific framework constraints ? | Project default stack | LOW |
102+ | Authentication | Is login required ? | JWT authentication included | MEDIUM |
103+ | Scope | MVP or full-featured ? | MVP | LOW |
104+
105+ ### Backend Agent Additional Verification
106+ | Item | Verification Question | Default | Uncertainty |
107+ | ------| ---------------------- | --------- | --- ----------|
108+ | DB selection | PostgreSQL? MongoDB? SQLite? | PostgreSQL | MEDIUM |
109+ | API style | REST? GraphQL? gRPC? | REST | MEDIUM |
110+ | Auth method | JWT? Session? OAuth? | JWT (access + refresh) | HIGH |
111+ | File upload | Needed? Size limit ? | Not needed | LOW |
112+ | Deployment environment | Serverless? Container? VM? | Container | MEDIUM |
113+
114+ ### Frontend Agent Additional Verification
115+ | Item | Verification Question | Default | Uncertainty |
116+ | ------| ---------------------- | --------- | --- ----------|
117+ | SSR/CSR | Server-side rendering needed ? | Next.js App Router (SSR) | MEDIUM |
118+ | Dark mode | Support needed ? | Supported | LOW |
119+ | Internationalization | Multi-language support ? | Not needed | LOW |
120+ | Existing design system | UI library to use ? | shadcn/ui | MEDIUM |
121+ | State management | Context? Redux? Zustand? | Zustand | MEDIUM |
122+
123+ ### Mobile Agent Additional Verification
124+ | Item | Verification Question | Default | Uncertainty |
125+ | ------| ---------------------- | --------- | --- ----------|
126+ | Platform | iOS only? Android only? Both? | Both | MEDIUM |
127+ | Offline | Offline support needed ? | Not needed | LOW |
128+ | Push notifications | Needed ? | Not needed | LOW |
129+ | Minimum OS | iOS/Android minimum versions ? | iOS 14+, Android API 24+ | LOW |
130+ | Architecture | MVC? MVVM? Clean? | MVVM | MEDIUM |
131131
132132---
133133
134- ## 모호함 수준별 대응 (상세)
134+ ## Detailed Response by Ambiguity Level
135135
136- ### Level 1 (LOW): 약간 모호 (핵심은 명확, 세부사항 부족 )
137- 예 : "TODO 앱 만들어줘 "
136+ ### Level 1 (LOW): Slightly ambiguous (core is clear, details lacking )
137+ Example : "Create a TODO app "
138138
139- ** 대응 ** : 기본값을 적용하고, 가정 목록을 result에 기록
139+ ** Response ** : Apply defaults and record assumption list in result
140140```
141141⚠️ Assumptions:
142142- JWT authentication included
@@ -145,10 +145,10 @@ Status: BLOCKED (awaiting clarification)
145145- MVP scope (CRUD only)
146146```
147147
148- ### Level 2 (MEDIUM): 상당히 모호 (핵심 기능이 불명확 )
149- 예 : "사용자 관리 시스템 만들어줘 "
148+ ### Level 2 (MEDIUM): Considerably ambiguous (core features unclear )
149+ Example : "Create a user management system "
150150
151- ** 대응 ** : 핵심 기능을 3가지로 좁혀서 명시하고 진행
151+ ** Response ** : Narrow scope to 3 core features, specify and proceed
152152```
153153⚠️ Interpreted scope (3 core features):
1541541. User registration + login (JWT)
@@ -161,10 +161,10 @@ NOT included (would need separate task):
161161- Email verification
162162```
163163
164- ### Level 3 (HIGH): 매우 모호 (방향 자체가 불명확 )
165- 예 : "좋은 앱 만들어줘 ", "이거 개선해줘 "
164+ ### Level 3 (HIGH): Very ambiguous (direction itself unclear )
165+ Example : "Create a good app ", "Improve this "
166166
167- ** 대응 ** : 진행하지 말고 구체화 요청을 result에 기록
167+ ** Response ** : Do not proceed, record clarification request in result
168168```
169169❌ Cannot proceed: Requirements too ambiguous
170170
@@ -179,39 +179,39 @@ Status: blocked (awaiting clarification)
179179
180180---
181181
182- ## PM Agent 전용: 요구사항 구체화 프레임워크
182+ ## PM Agent Only: Requirements Specification Framework
183183
184- PM Agent는 모호한 요청을 받으면 아래 프레임워크로 구체화한다 :
184+ PM Agent uses the framework below to specify ambiguous requests :
185185
186186```
187- === 요구사항 구체화 ===
187+ === Requirements Specification ===
188188
189- 원본 요청 : "{사용자 원문 }"
189+ Original request : "{user's original text }"
190190
191- 1. 핵심 목표 : {한 문장으로 정의 }
192- 2. 사용자 스토리 :
191+ 1. Core goal : {define in one sentence }
192+ 2. User stories :
193193 - "As a {user}, I want to {action} so that {benefit}"
194- - (최소 3개 )
195- 3. 기능 범위 :
196- - Must-have: {목록 }
197- - Nice-to-have: {목록 }
198- - Out-of-scope: {목록 }
199- 4. 기술 제약 :
200- - {기존 코드 / 스택 / 호환성 }
201- 5. 성공 기준 :
202- - {측정 가능한 조건 }
194+ - (minimum 3 )
195+ 3. Feature scope :
196+ - Must-have: {list }
197+ - Nice-to-have: {list }
198+ - Out-of-scope: {list }
199+ 4. Technical constraints :
200+ - {existing code / stack / compatibility }
201+ 5. Success criteria :
202+ - {measurable conditions }
203203```
204204
205205---
206206
207- ## 서브에이전트 모드에서의 적용
207+ ## Application in Subagent Mode
208208
209- CLI 서브에이전트는 사용자에게 직접 질문할 수 없다 .
210- 따라서 :
209+ CLI subagents cannot ask users directly .
210+ Therefore :
211211
212- 1 . ** Level 1** : 기본값 적용 + 가정 기록 → 진행
213- 2 . ** Level 2** : 범위를 좁혀서 해석 + 명시 → 진행
214- 3 . ** Level 3** : ` Status: blocked ` + 질문 목록 → 진행하지 않음
212+ 1 . ** Level 1** : Apply defaults + record assumptions → Proceed
213+ 2 . ** Level 2** : Narrow and interpret scope + specify → Proceed
214+ 3 . ** Level 3** : ` Status: blocked ` + question list → Do not proceed
215215
216- Orchestrator는 Level 3 결과를 받으면 사용자에게 질문을 전달하고,
217- 답변을 받은 후 해당 에이전트를 재실행한다 .
216+ When Orchestrator receives Level 3 result, it relays questions to user
217+ and re-runs that agent after receiving answers .
0 commit comments