사용자 입력
$ARGUMENTS
진행하기 전에 사용자 입력을 반드시 고려해야 합니다(비어 있지 않은 경우).
사전 실행 검사
확장 훅 확인 (질문 전):
- 프로젝트 루트에
.specify/extensions.yml파일이 있는지 확인합니다. - 파일이 있으면,
hooks.before_clarify키 아래의 항목을 읽습니다. - YAML을 구문 분석할 수 없거나 유효하지 않은 경우, 무시하지 않고
.specify/extensions.yml파일을 읽을 수 없다는 메시지(파서 오류 포함)와 함께 어떤 훅도 확인되지 않았으며, 여기에 등록된 필수(optional: false) 훅도 확인되지 않았음을 사용자에게 알린 후 정상적으로 계속 진행합니다. enabled가 명시적으로false인 훅은 필터링합니다.enabled필드가 없는 훅은 기본적으로 활성화된 것으로 간주합니다.- 나머지 각 훅에 대해, 훅
condition표현식을 해석하거나 평가하려고 시도하지 않습니다:- 훅에
condition필드가 없거나 null/비어 있으면, 훅을 실행 가능한 것으로 간주합니다. - 훅에 비어 있지 않은
condition이 정의되어 있으면, 해당 훅을 건너뛰고 조건 평가는 HookExecutor 구현에 맡깁니다.
- 훅에
- 훅 명령어 이름에서 점(.)을 하이픈(-)으로 바꾸어 명령어 호출을 구성합니다. 예를 들어,
speckit.git.commit→/speckit-git-commit과 같습니다. - 실행 가능한 각 훅에 대해,
optional플래그에 따라 다음을 출력합니다:- 선택적 훅 (
optional: true):## 확장 훅 **선택적 사전 훅**: {extension} 명령어: `/{command}` 설명: {description} 프롬프트: {prompt} 실행하려면: `/{command}` - 필수 훅 (
optional: false):
위 블록을 출력한 후에는 실제로 훅을 호출하고 계속 진행하기 전에 완료될 때까지 기다려야 합니다. 이 에이전트/세션에서 명령어를 직접 실행하는 것과 동일한 방식으로 실행합니다(호출 방식은 위에 표시된 리터럴## 확장 훅 **자동 사전 훅**: {extension} 실행 중: `/{command}` 명령어 실행: {command} 개요로 진행하기 전에 훅 명령어의 결과를 기다리십시오.{command}ID와 다를 수 있습니다. 예를 들어, skills-mode 에이전트는/skill:speckit-...또는$speckit-...형식으로 실행합니다). 블록만 출력하는 것으로는 훅이 실행되지 않습니다.
- 선택적 훅 (
- 등록된 훅이 없거나
.specify/extensions.yml파일이 존재하지 않으면, 조용히 건너뜁니다.
개요
목표: 활성 기능 명세서의 모호함이나 누락된 결정 지점을 감지하고 줄여 명확하게 한 내용을 명세 파일에 직접 기록합니다.
참고: 이 명확화 워크플로우는 /speckit-plan을 호출하기 전에 실행(및 완료)되어야 합니다. 사용자가 명확화를 생략하겠다고 명시적으로 밝히는 경우(예: 탐색적 스파이크), 진행할 수 있지만 다운스트림 재작업 위험이 증가한다고 경고해야 합니다.
실행 단계:
-
저장소 루트에서
.specify/scripts/bash/check-prerequisites.sh --json --paths-only를 한 번 실행합니다(결합된--json --paths-only모드 /-Json -PathsOnly). 최소 JSON 페이로드 필드를 구문 분석합니다:FEATURE_DIRFEATURE_SPEC- (선택적으로 향후 연결된 흐름을 위해
IMPL_PLAN,TASKS를 캡처합니다.) - JSON 구문 분석에 실패하면 중단하고 사용자에게
/speckit-specify를 다시 실행하거나 기능 브랜치 환경을 확인하도록 안내합니다. - "I'm Groot"와 같은 인수에 작은따옴표가 포함된 경우, 이스케이프 구문을 사용합니다(예: 'I'''m Groot' 또는 가능하면 큰따옴표 사용: "I'm Groot").
-
존재하는 경우: 프로젝트 원칙 및 거버넌스 제약 조건을 위해
.specify/memory/constitution.md를 로드합니다. -
현재 명세 파일을 로드합니다. 다음 분류 체계를 사용하여 구조화된 모호성 및 범위 검사를 수행합니다. 각 범주에 대해 상태를 표시합니다: 명확 / 부분적 / 누락. 우선 순위 지정에 사용되는 내부 범위 맵을 생성합니다(질문이 없을 경우 원시 맵을 출력하지 않음).
기능 범위 및 동작:
- 핵심 사용자 목표 및 성공 기준
- 명시적인 범위 외 선언
- 사용자 역할 / 페르소나 차별화
도메인 및 데이터 모델:
- 엔티티, 속성, 관계
- ID 및 고유성 규칙
- 수명 주기/상태 전환
- 데이터 볼륨/규모 가정
상호 작용 및 UX 흐름:
- 중요한 사용자 여정/시퀀스
- 오류/빈/로딩 상태
- 접근성 또는 현지화 참고 사항
비기능적 품질 속성:
- 성능(지연 시간, 처리량 목표)
- 확장성(수평/수직, 제한)
- 신뢰성 및 가용성(가동 시간, 복구 기대치)
- 관찰 가능성(로깅, 메트릭, 추적 신호)
- 보안 및 개인 정보 보호(인증/권한 부여, 데이터 보호, 위협 가정)
- 규정 준수/규제 제약 조건(해당하는 경우)
통합 및 외부 종속성:
- 외부 서비스/API 및 실패 모드
- 데이터 가져오기/내보내기 형식
- 프로토콜/버전 관리 가정
에지 케이스 및 오류 처리:
- 부정적 시나리오
- 속도 제한/스로틀링
- 충돌 해결(예: 동시 편집)
제약 조건 및 트레이드오프:
- 기술적 제약 조건(언어, 스토리지, 호스팅)
- 명시적인 트레이드오프 또는 거부된 대안
용어 및 일관성:
- 표준 용어집 용어
- 피해야 할 동의어/더 이상 사용되지 않는 용어
완료 신호:
- 승인 기준 테스트 가능성
- 측정 가능한 완료 정의 스타일 지표
기타 / 자리 표시자:
- TODO 마커 / 해결되지 않은 결정
- 정량화가 부족한 모호한 형용사("강력한", "직관적인")
상태가 부분적 또는 누락인 각 범주에 대해 후보 질문 기회를 추가합니다. 단, 다음의 경우는 제외합니다:
- 명확화가 구현 또는 검증 전략에 실질적으로 영향을 미치지 않는 경우
- 해당 항목이 구체적으로 구현 방법, 기술 스택 비교 또는 작업 분류에 관한 경우(내부적으로 기록)
-
후보 명확화 질문의 우선 순위 대기열을 (내부적으로) 생성합니다(최대 5개). 한 번에 모두 출력하지 않습니다. 다음 제약 조건을 적용합니다:
- 전체 세션 동안 총 5개의 질문으로 제한합니다.
- 각 질문은 다음 중 하나로 답변할 수 있어야 합니다:
- 짧은 다중 선택(2~5개의 상호 배타적인 옵션), 또는
- 한 단어/짧은 구문 답변(명시적으로 제한: "5단어 이내로 답변").
- 아키텍처, 데이터 모델링, 작업 분류, 테스트 설계, UX 동작, 운영 준비 상태 또는 규정 준수 검증에 실질적인 영향을 미치는 질문만 포함합니다.
- 범주 범위 균형을 유지합니다: 먼저 가장 영향력이 큰 해결되지 않은 범주를 다루려고 시도합니다. 보안 태세와 같은 단일 고영향 영역이 해결되지 않은 상태에서 낮은 영향의 질문 두 개를 묻는 것을 피합니다.
- 이미 답변된 질문, 사소한 스타일 선호도, 또는 계획 수준의 실행 세부 사항(정확성을 차단하지 않는 한)은 제외합니다.
- 다운스트림 재작업 위험을 줄이거나 잘못 정렬된 승인 테스트를 방지하는 명확화를 선호합니다.
- 5개 이상의 범주가 해결되지 않은 상태로 남아 있으면, (영향 * 불확실성) 휴리스틱에 따라 상위 5개를 선택합니다.
-
순차적 질문 루프(대화형):
-
한 번에 정확히 하나의 질문을 제시합니다.
-
질문 작성 품질(모든 질문, MC 또는 단답형에 적용):
**질문:**으로 시작하고?로 끝나는 완전한 의문문을 사용합니다.?앞의 질문 텍스트는 그 자체로 의미가 있어야 합니다.- 절대 주제 레이블, 섹션 제목 또는 요구 사항 ID를 질문 자체로 사용하지 마십시오. 예를 들어,
수락 장치/런타임 매트릭스 (FR-023)은(는) 유효하지 않습니다. 레이블일 뿐 질문이 아닙니다. ?뒤에는 선택적 괄호로 묶인 요구 사항/질문 ID만 허용됩니다. 정확한 형식:**질문:** <의문문>?또는**질문:** <의문문>? (FR-023). ID를?앞에 절대 배치하지 말고, ID를 (단독으로 또는 주제 레이블과 함께) 전체 프롬프트로 사용하지 마십시오.- 질문 줄 바로 다음에, 추천/옵션 앞에 하나의 평이한 언어로 된 "중요한 이유" 문장(수락 또는 출시에 대한 이해 관계)을 추가합니다.
- 일상적인 표현을 사용합니다. 전문 용어는 같은 문장에서 정의된 경우에만 도입합니다. 자체 점검: Spec Kit을 모르는 독자가 질문 줄만으로 답변할 수 있어야 합니다. 간결해도 괜찮습니다. 암호 같은 레이블은 안 됩니다.
-
객관식 질문의 경우:
- 모든 옵션을 분석하고 다음을 기반으로 가장 적합한 옵션을 결정합니다:
- 프로젝트 유형에 대한 모범 사례
- 유사한 구현에서의 일반적인 패턴
- 위험 감소(보안, 성능, 유지 보수성)
- 명세에 표시된 명시적인 프로젝트 목표 또는 제약 조건과의 정렬
- 추천 옵션을 맨 위에 눈에 띄게 명확한 근거와 함께 제시합니다(이것이 최선의 선택인 이유를 설명하는 1-2 문장).
- 형식:
**추천:** 옵션 [X] - <근거> - 그런 다음 모든 옵션을 Markdown 테이블로 렌더링합니다:
옵션 설명 A <옵션 A 설명> B <옵션 B 설명> C <옵션 C 설명> (필요에 따라 최대 5개까지 D/E 추가) 단답 다른 짧은 답변 제공(<=5단어) (자유 형식 대안이 적절한 경우에만 포함) - 테이블 뒤에 다음을 추가합니다:
옵션 문자(예: "A")로 답변하거나, "yes" 또는 "recommended"라고 말하여 추천을 수락하거나, 자신의 짧은 답변을 제공할 수 있습니다.
- 모든 옵션을 분석하고 다음을 기반으로 가장 적합한 옵션을 결정합니다:
-
단답형 스타일(의미 있는 개별 옵션이 없는 경우):
- 모범 사례와 컨텍스트를 기반으로 제안된 답변을 제공합니다.
- 형식:
**제안:** <제안된 답변> - <간단한 근거> - 그런 다음 다음을 출력합니다:
형식: 짧은 답변 (<=5단어). "yes" 또는 "suggested"라고 말하여 제안을 수락하거나, 자신의 답변을 제공할 수 있습니다.
-
사용자가 답변한 후:
- 사용자가 "yes", "recommended" 또는 "suggested"라고 답변하면, 이전에 명시한 추천/제안을 답변으로 사용합니다.
- 그렇지 않으면, 답변이 하나의 옵션에 매핑되거나 5단어 이하 제약 조건에 맞는지 확인합니다.
- 모호한 경우, 빠른 명확화를 요청합니다(카운트는 동일한 질문에 속함; 진행하지 않음).
- 만족스러우면, 작업 메모리에 기록하고(아직 디스크에 쓰지 않음) 다음 대기 질문으로 이동합니다.
-
다음과 같은 경우 추가 질문을 중단합니다:
- 모든 중요한 모호함이 조기에 해결된 경우(나머지 대기 항목이 불필요해짐), 또는
- 사용자가 완료 신호를 보낸 경우("done", "good", "no more"), 또는
- 5개의 질문을 한 경우.
-
향후 대기 중인 질문을 미리 절대 공개하지 않습니다.
-
시작 시 유효한 질문이 없으면, 즉시 중요한 모호함이 없다고 보고합니다.
-
-
각 수락된 답변 후 통합(증분 업데이트 방식):
- 명세의 메모리 내 표현(처음에 한 번 로드됨)과 원시 파일 내용을 유지합니다.
- 이 세션에서 첫 번째 통합된 답변의 경우:
## 명확화섹션이 있는지 확인합니다(없는 경우 명세 템플릿당 가장 높은 수준의 컨텍스트/개요 섹션 바로 뒤에 생성).- 그 아래에 오늘 날짜의
### 세션 YYYY-MM-DD하위 제목을 생성합니다(없는 경우).
- 수락 직후에 글머리 기호 줄을 추가합니다:
- Q: <질문> → A: <최종 답변>. - 그런 다음 즉시 가장 적절한 섹션에 명확화를 적용합니다:
- 기능적 모호함 → 기능 요구 사항의 글머리 기호를 업데이트하거나 추가합니다.
- 사용자 상호 작용/행위자 구분 → 사용자 스토리 또는 행위자 하위 섹션(있는 경우)을 명확화된 역할, 제약 조건 또는 시나리오로 업데이트합니다.
- 데이터 형태/엔티티 → 데이터 모델 업데이트(필드, 유형, 관계 추가)하고 순서를 유지합니다. 추가된 제약 조건을 간결하게 기록합니다.
- 비기능적 제약 조건 → 성공 기준 > 측정 가능한 결과에서 측정 가능한 기준을 추가/수정합니다(모호한 형용사를 메트릭 또는 명시적 목표로 변환).
- 에지 케이스/부정적 흐름 → 에지 케이스 / 오류 처리 아래에 새 글머리 기호를 추가합니다(또는 템플릿이 이에 대한 자리 표시자를 제공하는 경우 해당 하위 섹션을 생성).
- 용어 충돌 → 명세 전반에 걸쳐 용어를 정규화합니다. 필요한 경우에만
(이전에는 "X"라고 함)을 추가하여 원본을 유지합니다.
- 명확화가 이전의 모호한 진술을 무효화하는 경우, 중복하지 말고 해당 진술을 대체합니다. 구식의 모순된 텍스트를 남기지 않습니다.
- 각 통합 후에 명세 파일을 저장하여 컨텍스트 손실 위험을 최소화합니다(원자적 덮어쓰기).
- 서식을 유지합니다. 관련 없는 섹션의 순서를 변경하지 말고, 제목 계층을 그대로 유지합니다.
- 삽입된 각 명확화를 최소한으로 유지하고 테스트 가능하게 만듭니다(서사적 표류 방지).
-
검증(각 쓰기 후 및 최종 패스 후 수행):
- 명확화 세션에는 수락된 답변당 정확히 하나의 글머리 기호가 포함됩니다(중복 없음).
- 총 질문(수락된) 수 ≤ 5.
- 업데이트된 섹션에는 새 답변이 해결해야 하는 남아있는 모호한 자리 표시자가 없어야 합니다.
- 모순된 이전 진술이 남아 있지 않아야 합니다(이제 유효하지 않은 대안 선택이 제거되었는지 스캔).
- Markdown 구조가 유효해야 합니다. 허용되는 새 제목만:
## 명확화,### 세션 YYYY-MM-DD. - 용어 일관성: 업데이트된 모든 섹션에서 동일한 표준 용어를 사용해야 합니다.
-
업데이트된 명세를
FEATURE_SPEC에 다시 씁니다. -
명세 품질 체크리스트 재검증(존재하는 경우):
FEATURE_DIR/checklists/requirements.md파일이 있는지 확인합니다.- 파일이 없으면, 이 단계를 조용히 건너뜁니다.
- 파일이 있는 경우:
- 체크리스트 파일을 읽습니다.
- GitHub 작업 목록 체크박스 줄을 모두 식별합니다 — 코드 펜스 외부에서
- [ ],- [x]또는- [X]와 일치하는 줄(대소문자 구분 안 함, 중첩 항목의 경우 선행 공백 허용). 다른 모든 내용(제목, 메모, 체크박스가 아닌 글머리 기호, 메타데이터)은 무시합니다. - 각 체크박스 줄에 대해 현재 마커 상태(선택됨 또는 선택 안 됨)와 항목 텍스트를 이전 스냅샷 목록에 기록합니다.
- 업데이트된 명세(7단계에서 방금 저장된 버전)에 대해 각 체크박스 항목을 재평가합니다.
- 선택/선택 해제 상태가 실제로 변경되는 경우에만 각 체크박스 항목을 업데이트합니다:
- 항목이 이제 통과하고 이전에 선택되지 않은 경우:
[ ]를[x]로 변경합니다. - 항목이 이제 실패하고 이전에 선택된 경우:
[x]/[X]를[ ]로 변경합니다. - 상태가 변경되지 않은 경우: 변경하지 않고 그대로 둡니다.
- 항목이 이제 통과하고 이전에 선택되지 않은 경우:
- 상태가 변경된 각 체크박스 항목에 대해 설명하는 요약 메시지를 출력합니다:
- 새로 선택됨:
- [x] ~task 텍스트~ (업데이트된 명세에 따라 해결됨) - 새로 선택 해제됨:
- [ ] ~task 텍스트~ (업데이트된 명세에 따라 더 이상 충족되지 않음)
- 새로 선택됨:
- 두 경우 모두 변경된 체크박스 줄로 인해 뒤따르는 중첩 체크박스의 계층 구조가 변경될 수 있습니다. 계층 구조가 깨지지 않도록 수동으로 수정하지 말고, 대신 방금 저장한 명세 파일에 대한 각 후속 호출이 자체적인 읽기-재평가-쓰기 주기를 수행한다는 점에 의존하십시오. 원래 체크박스 줄만 업데이트하고, 체크박스 외부의 모든 내용(제목, 메모, 표, 코드 펜스)은 그대로 둡니다.
- 업데이트된 체크리스트를
FEATURE_DIR/checklists/requirements.md에 다시 씁니다. - 최종 업데이트된 체크리스트를 사용자에게 표시하지 마십시오. 대신 체크리스트 재검증이 완료되었으며 위에서 언급된 변경 사항(있는 경우)이 적용되었다는 상태를 요약합니다.
-
최종적으로,
## 명확화섹션의 현재 세션(세션 YYYY-MM-DD) 아래에 걸린 질문이 하나도 없는지 확인합니다. 세션이 동기화되었음을 나타냅니다. -
아래 요약 출력 후 종료합니다:
--- - **질문한 질문 수**: {number} - **다룬 범주**: {comma-separated list} - **다음 단계**: 기능 명세가 명확합니다. `/speckit-plan`을 실행하여 구현 계획을 생성하십시오.