---
description: 현재 기능 명세서에서 미명세 영역을 식별하고 최대 5개의 타겟 명확화 질문을 하여 답변을 명세서에 인코딩합니다.
handoffs:
  - label: 기술 계획 작성
    agent: speckit.plan
    prompt: 명세서에 대한 계획을 작성해주세요. 제가 구축하려는 것은...
---

## 언어 설정

모든 출력과 사용자와의 대화는 **한국어**로 진행합니다.

## 사용자 입력

```text
$ARGUMENTS
```

입력이 비어있지 않다면 진행하기 전에 **반드시** 사용자 입력을 고려해야 합니다.

## 개요

목표: 활성 기능 명세서에서 모호성이나 누락된 결정 지점을 감지하고 줄이며 명확화 내용을 명세서 파일에 직접 기록합니다.

참고: 이 명확화 워크플로우는 `/speckit.plan`을 호출하기 전에 실행(및 완료)되어야 합니다. 사용자가 명확화를 건너뛴다고 명시적으로 말하면(예: 탐색적 스파이크) 진행할 수 있지만, 후속 재작업 위험이 증가한다고 경고해야 합니다.

실행 단계:

1. 저장소 루트에서 `.specify/scripts/bash/check-prerequisites.sh --json --paths-only`를 **한 번** 실행합니다(결합된 `--json --paths-only` 모드). 최소 JSON 페이로드 필드 파싱:
   - `FEATURE_DIR`
   - `FEATURE_SPEC`
   - (선택적으로 향후 연결된 흐름을 위해 `IMPL_PLAN`, `TASKS` 캡처.)
   - JSON 파싱이 실패하면 중단하고 사용자에게 `/speckit.specify`를 다시 실행하거나 기능 브랜치 환경을 확인하도록 안내합니다.
   - "I'm Groot"와 같이 인수에 작은따옴표가 있는 경우 이스케이프 구문 사용: 예: 'I'\''m Groot' (또는 가능하면 큰따옴표: "I'm Groot").

2. 현재 명세서 파일을 로드합니다. 이 분류법을 사용하여 구조화된 모호성 및 범위 스캔을 수행합니다. 각 카테고리에 대해 상태 표시: 명확 / 부분 / 누락. 우선순위 지정에 사용되는 내부 범위 맵 생성(질문이 없으면 원시 맵을 출력하지 않음).

   기능 범위 및 동작:
   - 핵심 사용자 목표 및 성공 기준
   - 명시적 범위 외 선언
   - 사용자 역할/페르소나 구분

   도메인 및 데이터 모델:
   - 엔티티, 속성, 관계
   - 아이덴티티 및 고유성 규칙
   - 라이프사이클/상태 전환
   - 데이터 볼륨/규모 가정

   상호작용 및 UX 흐름:
   - 중요한 사용자 여정/시퀀스
   - 오류/빈/로딩 상태
   - 접근성 또는 현지화 참고사항

   비기능 품질 속성:
   - 성능(지연 시간, 처리량 목표)
   - 확장성(수평/수직, 제한)
   - 안정성 및 가용성(가동 시간, 복구 기대치)
   - 관찰 가능성(로깅, 메트릭, 추적 신호)
   - 보안 및 개인정보(인증/인가, 데이터 보호, 위협 가정)
   - 컴플라이언스/규제 제약사항(있는 경우)

   통합 및 외부 의존성:
   - 외부 서비스/API 및 실패 모드
   - 데이터 가져오기/내보내기 형식
   - 프로토콜/버전 관리 가정

   엣지 케이스 및 실패 처리:
   - 부정적 시나리오
   - 속도 제한/스로틀링
   - 충돌 해결(예: 동시 편집)

   제약사항 및 트레이드오프:
   - 기술적 제약사항(언어, 스토리지, 호스팅)
   - 명시적 트레이드오프 또는 거부된 대안

   용어 및 일관성:
   - 표준 용어집 용어
   - 피해야 할 동의어/더 이상 사용되지 않는 용어

   완료 신호:
   - 인수 기준 테스트 가능성
   - 측정 가능한 완료 정의 스타일 지표

   기타/플레이스홀더:
   - TODO 마커/해결되지 않은 결정
   - 정량화가 없는 모호한 형용사("견고한", "직관적인")

   부분 또는 누락 상태인 각 카테고리에 대해 후보 질문 기회 추가(단,):
   - 명확화가 구현 또는 검증 전략을 실질적으로 변경하지 않는 경우
   - 정보가 계획 단계로 연기하는 것이 더 나은 경우(내부적으로 기록)

3. 후보 명확화 질문의 우선순위 대기열을 (내부적으로) 생성합니다(최대 5개). 한 번에 모두 출력하지 마세요. 다음 제약사항을 적용:
    - 전체 세션에서 최대 10개의 총 질문.
    - 각 질문은 다음 중 하나로 답변 가능해야 함:
       - 짧은 객관식 선택(2-5개의 구별되고 상호 배타적인 옵션), 또는
       - 한 단어/짧은 구문 답변(명시적으로 제한: "5단어 이하로 답변").
    - 아키텍처, 데이터 모델링, 작업 분해, 테스트 설계, UX 동작, 운영 준비도 또는 컴플라이언스 검증에 실질적으로 영향을 미치는 질문만 포함.
    - 카테고리 범위 균형 보장: 가장 영향력 있는 미해결 카테고리를 먼저 다루려고 시도; 단일 고영향 영역(예: 보안 태세)이 미해결 상태일 때 두 개의 저영향 질문을 피함.
    - 이미 답변된 질문, 사소한 스타일 선호도 또는 계획 수준 실행 세부사항(정확성을 차단하지 않는 한) 제외.
    - 후속 재작업 위험을 줄이거나 잘못 정렬된 인수 테스트를 방지하는 명확화 선호.
    - 5개 이상의 카테고리가 미해결 상태로 남아있으면 (영향 * 불확실성) 휴리스틱으로 상위 5개 선택.

4. 순차적 질문 루프(대화형):
    - 한 번에 정확히 하나의 질문만 제시.
    - 객관식 질문의 경우:
       - **모든 옵션을 분석**하고 다음을 기반으로 **가장 적합한 옵션**을 결정:
          - 프로젝트 유형에 대한 모범 사례
          - 유사한 구현의 일반적인 패턴
          - 위험 감소(보안, 성능, 유지보수성)
          - 명세서에 보이는 명시적 프로젝트 목표 또는 제약사항과의 정렬
       - 명확한 이유와 함께 **추천 옵션을 맨 위에 눈에 띄게 제시**(이것이 최선의 선택인 이유를 설명하는 1-2문장).
       - 형식: `**추천:** 옵션 [X] - <이유>`
       - 그런 다음 모든 옵션을 마크다운 테이블로 렌더링:

       | 옵션 | 설명 |
       |------|------|
       | A | <옵션 A 설명> |
       | B | <옵션 B 설명> |
       | C | <옵션 C 설명> (필요에 따라 최대 5개까지 D/E 추가) |
       | 직접 | 다른 짧은 답변 제공(5단어 이하) (자유 형식 대안이 적절한 경우에만 포함) |

       - 테이블 후 추가: `옵션 문자로 답변할 수 있습니다(예: "A"), "예" 또는 "추천"이라고 말하여 추천을 수락하거나, 직접 짧은 답변을 제공할 수 있습니다.`
    - 짧은 답변 스타일(의미 있는 개별 옵션이 없는 경우):
       - 모범 사례와 컨텍스트를 기반으로 **제안된 답변** 제공.
       - 형식: `**제안:** <제안된 답변> - <간단한 이유>`
       - 그런 다음 출력: `형식: 짧은 답변(5단어 이하). "예" 또는 "제안"이라고 말하여 제안을 수락하거나, 직접 답변을 제공할 수 있습니다.`
    - 사용자가 답변한 후:
       - 사용자가 "예", "추천" 또는 "제안"으로 답변하면 이전에 명시된 추천/제안을 답변으로 사용.
       - 그렇지 않으면 답변이 하나의 옵션에 매핑되거나 5단어 이하 제약에 맞는지 검증.
       - 모호하면 빠른 명확화 요청(카운트는 같은 질문에 속함; 진행하지 않음).
       - 만족스러우면 작업 메모리에 기록(아직 디스크에 쓰지 않음)하고 다음 대기 중인 질문으로 이동.
    - 다음 경우 추가 질문 중지:
       - 모든 중요한 모호성이 조기에 해결됨(나머지 대기 항목이 불필요해짐), 또는
       - 사용자가 완료 신호("완료", "좋아요", "더 없어요"), 또는
       - 5개 질문에 도달.
    - 미래 대기 중인 질문을 미리 공개하지 않음.
    - 시작 시 유효한 질문이 없으면 중요한 모호성이 없다고 즉시 보고.

5. 각 수락된 답변 후 통합(점진적 업데이트 접근 방식):
    - 명세서의 인메모리 표현(시작 시 한 번 로드됨) + 원시 파일 내용 유지.
    - 이 세션에서 첫 번째 통합된 답변:
       - `## 명확화` 섹션이 있는지 확인(없으면 명세서 템플릿에 따라 가장 높은 수준의 컨텍스트/개요 섹션 바로 뒤에 생성).
       - 그 아래에 (없으면) 오늘 날짜의 `### 세션 YYYY-MM-DD` 소제목 생성.
    - 수락 직후 불릿 라인 추가: `- Q: <질문> → A: <최종 답변>`.
    - 그런 다음 가장 적절한 섹션에 명확화를 즉시 적용:
       - 기능적 모호성 → 기능 요구사항에서 불릿 업데이트 또는 추가.
       - 사용자 상호작용/행위자 구분 → 명확화된 역할, 제약사항 또는 시나리오로 사용자 스토리 또는 행위자 하위 섹션(있는 경우) 업데이트.
       - 데이터 형태/엔티티 → 데이터 모델 업데이트(필드, 유형, 관계 추가) 순서 유지; 추가된 제약사항을 간결하게 기록.
       - 비기능 제약사항 → 비기능/품질 속성 섹션에 측정 가능한 기준 추가/수정(모호한 형용사를 지표 또는 명시적 목표로 변환).
       - 엣지 케이스/부정적 흐름 → 엣지 케이스/오류 처리 아래에 새 불릿 추가(또는 템플릿이 플레이스홀더를 제공하면 해당 하위 섹션 생성).
       - 용어 충돌 → 명세서 전체에서 용어 정규화; 필요한 경우에만 한 번 `(이전에는 "X"로 불림)`을 추가하여 원래 유지.
    - 명확화가 이전의 모호한 진술을 무효화하면 중복 대신 해당 진술 교체; 구식 모순 텍스트를 남기지 않음.
    - 컨텍스트 손실 위험을 최소화하기 위해 각 통합 후 명세서 파일 저장(원자적 덮어쓰기).
    - 포맷팅 유지: 관련 없는 섹션 재정렬하지 않음; 제목 계층 구조 유지.
    - 삽입된 각 명확화를 최소화하고 테스트 가능하게 유지(서술적 드리프트 방지).

6. 검증(각 쓰기 후 + 최종 패스 수행):
   - 명확화 세션에 수락된 답변당 정확히 하나의 불릿 포함(중복 없음).
   - 총 질문 횟수(수락됨) ≤ 5.
   - 업데이트된 섹션에 새 답변이 해결하려던 모호한 플레이스홀더가 남아있지 않음.
   - 이제 무효인 이전 진술이 남아있지 않음(제거된 대안 선택 스캔).
   - 마크다운 구조 유효; 허용되는 새 제목만: `## 명확화`, `### 세션 YYYY-MM-DD`.
   - 용어 일관성: 모든 업데이트된 섹션에서 동일한 표준 용어 사용.

7. 업데이트된 명세서를 `FEATURE_SPEC`에 다시 씁니다.

8. 완료 보고(질문 루프 종료 또는 조기 종료 후):
   - 질문한 횟수 및 답변한 횟수.
   - 업데이트된 명세서 경로.
   - 터치된 섹션(이름 목록).
   - 각 분류 카테고리의 상태를 나열하는 범위 요약 테이블: 해결됨(부분/누락이었고 처리됨), 연기됨(질문 할당량 초과 또는 계획에 더 적합), 명확(이미 충분), 미해결(여전히 부분/누락이지만 저영향).
   - 미해결 또는 연기된 것이 남아있으면 `/speckit.plan`으로 진행할지 또는 계획 후에 `/speckit.clarify`를 다시 실행할지 권장.
   - 제안된 다음 명령.

동작 규칙:

- 의미 있는 모호성이 발견되지 않으면(또는 모든 잠재적 질문이 저영향이면) 다음과 같이 응답: "공식 명확화가 필요한 중요한 모호성이 감지되지 않았습니다." 그리고 진행을 제안.
- 명세서 파일이 없으면 사용자에게 먼저 `/speckit.specify`를 실행하도록 안내(여기서 새 명세서를 생성하지 않음).
- 총 5개의 질문을 초과하지 않음(단일 질문에 대한 명확화 재시도는 새 질문으로 계산되지 않음).
- 기능적 명확성을 차단하지 않는 한 추측적 기술 스택 질문을 피함.
- 사용자 조기 종료 신호 존중("중지", "완료", "진행").
- 전체 범위로 인해 질문이 없으면 간결한 범위 요약(모든 카테고리 명확) 출력 후 진행 제안.
- 미해결 고영향 카테고리가 남아있는 상태에서 할당량에 도달하면 근거와 함께 연기됨 아래에 명시적으로 플래그 지정.

우선순위 지정 컨텍스트: $ARGUMENTS
