사용자 입력
$ARGUMENTS
진행하기 전에 사용자 입력을 반드시 고려해야 합니다(비어 있지 않은 경우).
사전 실행 검사
확장 훅 확인 (분석 전):
- 프로젝트 루트에
.specify/extensions.yml이 있는지 확인합니다. - 존재하는 경우,
hooks.before_analyze키 아래의 항목을 읽습니다. - 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}` EXECUTE_COMMAND: {command} 훅 명령의 결과를 기다린 후 목표를 진행하세요.{command}ID와 다를 수 있습니다. 예를 들어, skills 모드 에이전트는/skill:speckit-...또는$speckit-...로 실행합니다). 블록만 출력하는 것으로는 훅이 실행되지 않습니다.
- 선택적 훅 (
- 등록된 훅이 없거나
.specify/extensions.yml이 존재하지 않으면, 조용히 건너뜁니다.
목표
구현 전에 세 가지 핵심 아티팩트(spec.md, plan.md, tasks.md)에서 불일치, 중복, 모호성, 미지정 항목을 식별합니다. 이 명령은 /speckit-tasks가 완전한 tasks.md를 성공적으로 생성한 후에만 실행되어야 합니다.
운영 제약 조건
엄격히 읽기 전용: 파일을 수정하지 마십시오. 구조화된 분석 보고서를 출력합니다. 선택적 수정 계획을 제공합니다(사용자가 명시적으로 승인한 후에만 후속 편집 명령이 수동으로 호출될 수 있습니다).
헌법 권한: 프로젝트 헌법(.specify/memory/constitution.md)은 이 분석 범위 내에서 불가침입니다. 헌법 충돌은 자동으로 중요(CRITICAL)하며, spec, plan 또는 tasks의 조정이 필요합니다—원칙의 약화, 재해석 또는 묵시적 무시가 아닙니다. 원칙 자체를 변경해야 하는 경우, /speckit-analyze 외부에서 별도의 명시적 헌법 업데이트로 이루어져야 합니다.
실행 단계
1. 분석 컨텍스트 초기화
.specify/scripts/bash/check-prerequisites.sh --json --require-spec --require-tasks --include-tasks를 저장소 루트에서 한 번 실행하고 JSON을 파싱하여 FEATURE_DIR과 AVAILABLE_DOCS를 가져옵니다. 절대 경로를 도출합니다:
- SPEC = FEATURE_DIR/spec.md
- PLAN = FEATURE_DIR/plan.md
- TASKS = FEATURE_DIR/tasks.md
필요한 파일이 없으면 오류 메시지와 함께 중단합니다(사용자에게 누락된 사전 조건 명령을 실행하도록 안내). "I'm Groot"와 같이 인수에 작은따옴표가 있는 경우 이스케이프 구문을 사용하세요: 예: 'I'''m Groot' (또는 가능하면 큰따옴표 사용: "I'm Groot").
2. 아티팩트 로드 (점진적 공개)
각 아티팩트에서 필요한 최소한의 컨텍스트만 로드합니다:
spec.md에서:
- 개요/컨텍스트
- 기능 요구사항
- 성공 기준 (측정 가능한 결과 — 예: 성능, 보안, 가용성, 사용자 성공, 비즈니스 영향)
- 사용자 스토리
- 엣지 케이스 (있는 경우)
plan.md에서:
- 아키텍처/스택 선택
- 데이터 모델 참조
- 단계
- 기술적 제약 조건
tasks.md에서:
- 작업 ID
- 설명
- 단계 그룹화
- 병렬 마커 [P]
- 참조된 파일 경로
헌법에서:
.specify/memory/constitution.md에서 원칙 검증을 위해 로드
3. 의미 모델 구축
내부 표현을 생성합니다(출력에 원시 아티팩트를 포함하지 마십시오):
- 요구사항 인벤토리: 각 기능 요구사항(FR-###) 및 성공 기준(SC-###)에 대해 안정적인 키를 기록합니다. 있는 경우 명시적 FR-/SC- 식별자를 기본 키로 사용하고, 가독성을 위해 명령형 구문 슬러그도 선택적으로 도출합니다(예: "사용자가 파일을 업로드할 수 있음" →
user-can-upload-file). 빌드 가능한 작업이 필요한 성공 기준 항목(예: 부하 테스트 인프라, 보안 감사 도구)만 포함하고, 출시 후 결과 메트릭 및 비즈니스 KPI(예: "지원 티켓 50% 감소")는 제외합니다. - 사용자 스토리/행동 인벤토리: 승인 기준이 있는 개별 사용자 행동
- 작업 적용 범위 매핑: 각 작업을 하나 이상의 요구사항 또는 스토리에 매핑합니다(키워드 / ID와 같은 명시적 참조 패턴 또는 핵심 구문을 통한 추론).
- 헌법 규칙 집합: 원칙 이름과 MUST/SHOULD 규범적 진술문을 추출합니다.
4. 탐지 패스 (토큰 효율적 분석)
고신호 발견에 집중합니다. 총 50개로 제한하며, 나머지는 오버플로 요약에 통합합니다.
A. 중복 탐지
- 유사 중복 요구사항 식별
- 통합을 위해 품질이 낮은 표현에 표시
B. 모호성 탐지
- 측정 가능한 기준이 없는 모호한 형용사(빠른, 확장 가능한, 안전한, 직관적인, 견고한 등) 표시
- 해결되지 않은 플레이스홀더(TODO, TKTK, ???,
<placeholder>등) 표시
C. 미지정
- 동사는 있지만 목적어나 측정 가능한 결과가 없는 요구사항
- 승인 기준 정렬이 누락된 사용자 스토리
- spec/plan에 정의되지 않은 파일이나 컴포넌트를 참조하는 작업
D. 헌법 정렬
- MUST 원칙과 충돌하는 모든 요구사항 또는 계획 요소
- 헌법에서 요구하는 필수 섹션 또는 품질 게이트 누락
E. 적용 범위 격차
- 연결된 작업이 없는 요구사항
- 매핑된 요구사항/스토리가 없는 작업
- 작업에 반영되지 않은 빌드 가능한 작업이 필요한 성공 기준(성능, 보안, 가용성)
F. 불일치
- 용어 변화 (동일한 개념이 파일마다 다르게 명명됨)
- plan에서 참조되지만 spec에는 없는 데이터 엔터티(또는 그 반대)
- 작업 순서 모순 (예: 종속성 없이 기초 설정 작업 전에 통합 작업)
- 충돌하는 요구사항 (예: 하나는 Next.js를 요구하고 다른 하나는 Vue를 지정)
5. 심각도 할당
다음 휴리스틱을 사용하여 발견에 우선순위를 지정합니다:
- CRITICAL: 헌법 MUST 위반, 핵심 spec 아티팩트 누락, 또는 기본 기능을 차단하는 적용 범위가 0인 요구사항
- HIGH: 중복 또는 충돌하는 요구사항, 모호한 보안/성능 속성, 테스트 불가능한 승인 기준
- MEDIUM: 용어 변화, 누락된 비기능적 작업 적용 범위, 미지정된 엣지 케이스
- LOW: 스타일/문구 개선, 실행 순서에 영향을 주지 않는 사소한 중복
6. 간결한 분석 보고서 생성
다음 구조의 Markdown 보고서를 출력합니다(파일 쓰기 없음):
사양 분석 보고서
| ID | 카테고리 | 심각도 | 위치 | 요약 | 권장 사항 |
|---|---|---|---|---|---|
| A1 | 중복 | HIGH | spec.md:L120-134 | 두 개의 유사한 요구사항 ... | 병합; 더 명확한 버전 유지 |
(발견당 한 행씩 추가; 카테고리 이니셜을 접두사로 하는 안정적인 ID 생성)
적용 범위 요약 표:
| 요구사항 키 | 작업 있음? | 작업 ID | 비고 |
|---|
헌법 정렬 문제: (있는 경우)
매핑되지 않은 작업: (있는 경우)
메트릭:
- 총 요구사항 수
- 총 작업 수
- 적용 범위 % (>=1개 작업이 있는 요구사항)
- 모호성 개수
- 중복 개수
- 중요 이슈 개수
7. 다음 작업 제공
보고서 마지막에 간결한 다음 작업 블록을 출력합니다:
- CRITICAL 이슈가 있는 경우:
/speckit-implement전에 해결 권장 - LOW/MEDIUM만 있는 경우: 사용자는 계속 진행할 수 있지만 개선 제안 제공
- 명시적 명령 제안 제공: 예: "정제를 위해 /speckit-specify 실행", "아키텍처 조정을 위해 /speckit-plan 실행", "수동으로 tasks.md를 편집하여 'performance-metrics'에 대한 적용 범위 추가"
8. 수정 제안
사용자에게 질문: "상위 N개 이슈에 대한 구체적인 수정 편집을 제안해 드릴까요?" (자동으로 적용하지 마십시오.)
9. 확장 훅 확인
보고 후, 프로젝트 루트에 .specify/extensions.yml이 있는지 확인합니다.
- 존재하는 경우,
hooks.after_analyze키 아래의 항목을 읽습니다. - 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}` EXECUTE_COMMAND: {command}{command}ID와 다를 수 있습니다. 예를 들어, skills 모드 에이전트는/skill:speckit-...또는$speckit-...로 실행합니다). 블록만 출력하는 것으로는 훅이 실행되지 않습니다.
- 선택적 훅 (
- 등록된 훅이 없거나
.specify/extensions.yml이 존재하지 않으면, 조용히 건너뜁니다.
운영 원칙
컨텍스트 효율성
- 최소 고신호 토큰: 철저한 문서화가 아닌 실행 가능한 발견에 집중
- 점진적 공개: 아티팩트를 증분적으로 로드; 모든 내용을 분석에 덤프하지 않음
- 토큰 효율적 출력: 발견 테이블을 50행으로 제한; 오버플로 요약
- 결정론적 결과: 변경 없이 재실행 시 일관된 ID와 개수 생성
분석 지침
- 절대 파일을 수정하지 마십시오 (읽기 전용 분석)
- 절대 누락된 섹션을 환각하지 마십시오 (없는 경우 정확하게 보고)
- 헌법 위반에 우선순위를 두십시오 (항상 CRITICAL)
- 포괄적인 규칙보다 예제를 사용하십시오 (일반 패턴이 아닌 특정 인스턴스 인용)
- 이슈가 없으면 우아하게 보고하십시오 (적용 범위 통계와 함께 성공 보고서 출력)
컨텍스트
$ARGUMENTS