| name | clarify |
| description | Adaptive requirements clarification with auto-depth routing.
Shallow (Q&A) for simple tasks, Deep (exploration + DRAFT + PLAN) for complex ones.
Escalates automatically when ambiguity persists.
|
| required_context | [".claude/ai-context/architecture.md",".claude/ai-context/conventions.md"] |
| allowed-tools | ["Read","Grep","Glob","Task","Write","AskUserQuestion"] |
/clarify — Adaptive Requirements Clarification
Chain (MUST)
| 이전 | 현재 | 다음 |
|---|
| 세션 시작 | /clarify | EnterPlanMode() → /implement |
Core Model
/clarify → 복잡도 측정 → 충분히 명확?
├─ Yes → EnterPlanMode()
└─ No → 더 깊은 clarify (탐색, 분석, DRAFT...)
→ 재측정 → 반복
종료 조건: "이 정보로 구현 가능한가?"
Step 0: Route — Complexity Assessment
요청 수신 즉시 내부적으로 복잡도를 측정한다 (사용자에게 노출하지 않음).
Complexity Signals
| Signal | LOW | HIGH |
|---|
| 요청 길이 | 짧고 구체적 | 길거나 모호 |
| 키워드 | "추가", "수정", "고쳐줘" | "설계", "마이그레이션", "처음부터" |
| 불확실성 표현 | 없음 | "잘 모르겠는데", "어떻게 해야 할지" |
| 영향 범위 | 단일 파일/모듈 | 크로스커팅, 여러 서비스 |
| 리스크 | 낮음 (UI, 텍스트) | 높음 (DB, 인증, 브레이킹 API) |
| 기존 패턴 | 명확히 존재 | 없거나 낯선 스택 |
- LOW → Shallow Path (이 파일 내에서 완결)
- HIGH → Deep Path (
deep/DEEP.md 참조)
- 애매하면 → Shallow로 시작, 에스컬레이션 조건 감시
Shallow Path (Low Complexity)
빠른 Q&A로 모호함만 제거하고 바로 Plan Mode로 진입.
Execution
- Record: 원본 요청 기록 + 모호한 부분 식별
- Question:
AskUserQuestion (구체적 옵션, 2-3라운드)
- Escalation Check: 에스컬레이션 조건 확인 (아래 참조)
- Summary: Before/After 비교 (Goal, Scope, Constraints, Success Criteria)
- Auto Plan:
EnterPlanMode() 즉시 호출
Rules
- 가정 금지 → 질문
- TDD 가능 수준까지 구체화
- 3라운드 내 해결 목표
Escalation → Deep Path
다음 중 하나라도 감지되면 Deep Path로 전환:
- 질문 3라운드 후에도 스코프 미확정
- 사용자 답변에서 새로운 불확실성 계속 등장
- 영향 범위가 초기 예상보다 확대 (단일 → 다중 모듈)
- 리스크 지표 발견 (DB 스키마, 인증, 브레이킹 변경)
- 사용자가 접근 방식 자체를 모름 ("어떻게 해야 할지 모르겠어")
전환 시: "스코프가 예상보다 복잡합니다. 코드베이스를 먼저 탐색하겠습니다." 안내 후 deep/DEEP.md의 프로세스를 따른다.
Deep Path
복잡도 HIGH이거나 Shallow에서 에스컬레이션된 경우.
전체 프로세스는 deep/DEEP.md를 참조한다.
요약:
- Intent 분류 (7종) → 전략 결정
- 병렬 탐색 에이전트 3개 → 코드베이스 이해
- DRAFT 생성 → 인터뷰 → 지속 업데이트
- 사용자 명시 요청 시 → 분석 에이전트 → PLAN 생성 → Reviewer 루프
- 승인 후 →
EnterPlanMode()
DECISIONS.md 기록 (MUST)
Plan 확정 전 .dev/DECISIONS.md에 결정사항 기록:
| 상황 | 기록 필수 |
|---|
| 새 기능 설계 | 결정 배경, 대안, 이유 |
| 아키텍처 선택 | 고려한 옵션, 선택 이유 |
| 트레이드오프 | 무엇을 포기하고 무엇을 얻었는지 |
## YYYY-MM-DD: {feature-name}
- **결정**: 무엇을 결정했는가
- **이유**: 왜 이 선택을 했는가
- **대안**: 고려했으나 선택하지 않은 옵션
- **참조**: .dev/specs/{feature-name}/PLAN.md (있으면)
계획서 필수 포함 사항
Plan 파일에는 반드시 다음을 포함해야 함:
/implement 스킬로 구현 진행 명시- 검증 방법 (테스트 실행)
.dev/DECISIONS.md 기록 완료 확인
중요: /implement를 사용하지 않는 계획서는 승인되지 않음.
NEXT STEP (자동 실행)
Plan 승인 시 즉시 /implement 호출. "구현할까요?" 묻지 말 것.
