체크리스트 목적: "요구사항에 대한 단위 테스트"
핵심 개념: 체크리스트는 요구사항 작성의 단위 테스트입니다. 특정 도메인에서 요구사항의 품질, 명확성, 완전성을 검증합니다.
검증/테스트용이 아님:
- ❌ "버튼이 올바르게 클릭되는지 확인"
- ❌ "에러 처리가 작동하는지 테스트"
- ❌ "API가 200을 반환하는지 확인"
- ❌ 코드/구현이 명세와 일치하는지 확인
요구사항 품질 검증용:
- ✅ "모든 카드 유형에 대한 시각적 계층 구조 요구사항이 정의되었습니까?" (완전성)
- ✅ "'눈에 띄게 표시'가 특정 크기/위치로 정량화되었습니까?" (명확성)
- ✅ "모든 대화형 요소에 대해 호버 상태 요구사항이 일관되게 정의되었습니까?" (일관성)
- ✅ "키보드 탐색에 대한 접근성 요구사항이 정의되었습니까?" (커버리지)
- ✅ "로고 이미지 로드 실패 시 어떻게 되는지 명세에 정의되어 있습니까?" (엣지 케이스)
비유: 명세가 영어로 작성된 코드라면, 체크리스트는 그 코드의 단위 테스트 스위트입니다. 구현이 작동하는지 테스트하는 것이 아니라, 요구사항이 잘 작성되었는지, 완전한지, 모호하지 않은지, 구현 준비가 되었는지를 테스트하는 것입니다.
소유권 및 체크박스 생명주기:
- 이 명령으로 생성된 맞춤형 체크리스트는 리뷰어 소유의 요구사항 품질 검토 산출물입니다.
[x]는 리뷰어가 요구사항 품질 기준이 충족되었다고 판단했음을 의미합니다.[x]는 구현 작업이 완료되었음을 의미하지 않습니다.- 이 명령은 체크리스트 항목을 생성하거나 추가합니다. 생성된 항목을
[x]로 표시해서는 안 됩니다. - 에이전트는 리뷰어가 명시적으로 요청한 경우에만 항목 평가를 도울 수 있습니다.
checklists/requirements.md는/speckit-specify및/speckit-clarify에서 관리하는 별도의 내장 명세 품질 체크리스트입니다. 이 예외를 여기서 생성된 맞춤형 체크리스트에 적용하지 마십시오.
사용자 입력
$ARGUMENTS
진행하기 전에 사용자 입력을 반드시 고려해야 합니다(비어 있지 않은 경우).
실행 전 검사
확장 훅 확인 (체크리스트 생성 전):
- 프로젝트 루트에
.specify/extensions.yml이 있는지 확인합니다. - 존재하는 경우, 읽고
hooks.before_checklist키 아래의 항목을 확인합니다. - 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와 다를 수 있습니다. 예: 스킬 모드 에이전트는/skill:speckit-...또는$speckit-...로 실행). 블록만 출력하는 것으로는 훅이 실행되지 않습니다.
- 선택적 훅 (
- 등록된 훅이 없거나
.specify/extensions.yml이 존재하지 않으면 조용히 건너<뜁니다.
실행 단계
-
설정: 리포지토리 루트에서
.specify/scripts/bash/check-prerequisites.sh --json --template checklist-template을 실행하고 JSON에서 FEATURE_DIR, AVAILABLE_DOCS 목록, TEMPLATE_CONTENT를 구문 분석합니다.- 모든 파일 경로는 절대 경로여야 합니다.
- "I'm Groot"와 같은 인수의 작은따옴표에는 이스케이프 구문을 사용합니다(예: 'I'''m Groot' 또는 가능하면 큰따옴표: "I'm Groot").
-
존재하는 경우: 프로젝트 원칙 및 거버넌스 제약 조건을 위해
.specify/memory/constitution.md를 로드합니다. -
의도 명확히 하기 (동적): 최대 세 개의 초기 컨텍스트 기반 명확화 질문(미리 준비된 카탈로그 없음)을 도출합니다. 다음을 반드시 준수해야 합니다:
- 사용자의 표현 + 명세서/계획/작업에서 추출된 신호를 기반으로 생성되어야 합니다.
- 체크리스트 내용을 실질적으로 변경하는 정보에 대해서만 질문해야 합니다.
$ARGUMENTS에 이미 명확한 경우 개별적으로 건너뛰어야 합니다.- 정확성을 폭보다 선호합니다.
생성 알고리즘:
- 신호 추출: 기능 도메인 키워드(예: 인증, 지연 시간, UX, API), 위험 지표("중요", "필수", "규정 준수"), 이해관계자 힌트("QA", "리뷰", "보안 팀"), 명시적 산출물("a11y", "롤백", "계약").
- 신호를 관련성 순으로 순위가 매겨진 후보 초점 영역(최대 4개)으로 클러스터링합니다.
- 명시적이지 않은 경우 예상 대상 및 시기(작성자, 리뷰어, QA, 릴리스)를 식별합니다.
- 누락된 차원 감지: 범위 범위, 깊이/엄격함, 위험 강조, 제외 경계, 측정 가능한 승인 기준.
- 다음 아키타입에서 선택한 질문 공식화:
- 범위 세분화(예: "여기에 X 및 Y와의 통합 접점을 포함해야 합니까, 아니면 로컬 모듈 정확성에만 국한해야 합니까?")
- 위험 우선순위 지정(예: "이러한 잠재적 위험 영역 중 어떤 것이 필수 게이트 검사를 받아야 합니까?")
- 깊이 보정(예: "이것은 가벼운 커밋 전 체크리스트입니까, 아니면 공식 릴리스 게이트입니까?")
- 대상 프레이밍(예: "작성자만 사용합니까, 아니면 PR 리뷰 중 동료도 사용합니까?")
- 경계 제외(예: "이번에는 성능 튜닝 항목을 명시적으로 제외해야 합니까?")
- 시나리오 클래스 격차(예: "복구 흐름이 감지되지 않았습니다. 롤백/부분 실패 경로가 범위에 포함됩니까?")
질문 형식 규칙:
- 옵션을 제시하는 경우 옵션, 후보, 중요성 열이 있는 간결한 테이블을 생성합니다.
- 옵션은 최대 A–E로 제한합니다. 자유 형식 답변이 더 명확한 경우 테이블을 생략합니다.
- 사용자가 이미 말한 내용을 반복하도록 요청하지 마십시오.
- 추측성 범주는 피합니다(환각 없음). 확실하지 않은 경우 명시적으로 질문합니다: "X가 범위에 속하는지 확인하십시오."
상호 작용이 불가능한 경우 기본값:
- 깊이: 표준
- 대상: 코드 관련인 경우 리뷰어(PR), 그 외 작성자
- 초점: 상위 2개 관련성 클러스터
질문 출력(Q1/Q2/Q3 레이블). 답변 후: 2개 이상의 시나리오 클래스(대체/예외/복구/비기능 도메인)가 여전히 불명확한 경우, 각각에 대한 한 줄 정당성과 함께 최대 두 개의 추가 대상 후속 질문(Q4/Q5)을 할 수 있습니다(예: "해결되지 않은 복구 경로 위험"). 총 질문 수는 5개를 초과하지 않아야 합니다. 사용자가 명시적으로 더 이상 질문을 거부하는 경우 확대하지 마십시오.
-
사용자 요청 이해:
$ARGUMENTS+ 명확화 답변 결합:- 체크리스트 테마 도출(예: 보안, 검토, 배포, UX)
- 사용자가 언급한 명시적 필수 항목 통합
- 초점 선택을 범주 구조에 매핑
- 명세서/계획/작업에서 누락된 컨텍스트 추론(환각 금지)
-
기능 컨텍스트 로드: FEATURE_DIR에서 읽기:
- spec.md: 기능 요구사항 및 범위
- plan.md(있는 경우): 기술 세부 사항, 종속성
- tasks.md(있는 경우): 구현 작업
컨텍스트 로드 전략:
- 활성 초점 영역과 관련된 필요한 부분만 로드합니다(전체 파일 덤프 방지).
- 긴 섹션을 간결한 시나리오/요구사항 글머리 기호로 요약하는 것을 선호합니다.
- 점진적 공개 사용: 격차가 감지된 경우에만 후속 검색을 추가합니다.
- 소스 문서가 큰 경우 원시 텍스트를 포함하는 대신 중간 요약 항목을 생성합니다.
-
체크리스트 생성 - TEMPLATE_CONTENT를 구조 템플릿으로 사용하고 "요구사항에 대한 단위 테스트"를 생성합니다:
- 디렉토리가 없으면
FEATURE_DIR/checklists/디렉토리를 생성합니다. - 고유한 체크리스트 파일 이름 생성:
- 도메인에 따라 짧고 설명적인 이름 사용(예:
ux.md,api.md,security.md). - 형식:
[domain].md
- 도메인에 따라 짧고 설명적인 이름 사용(예:
- 파일 처리 동작:
- 파일이 존재하지 않는 경우: 새 파일을 생성하고 CHK001부터 항목 번호를 매깁니다.
- 파일이 존재하는 경우: 마지막 CHK ID부터 이어서 새 항목을 기존 파일에 추가합니다(예: 마지막 항목이 CHK015이면 새 항목을 CHK016부터 시작).
- 기존 체크리스트 내용을 절대 삭제하거나 교체하지 마십시오. 항상 보존하고 추가하십시오.
- 새로 생성된 모든 항목은 선택되지 않은 상태(
[ ])로 둡니다. 체크박스 상태는 리뷰어의 것입니다.
핵심 원칙 - 요구사항을 테스트하고 구현을 테스트하지 마십시오: 모든 체크리스트 항목은 다음에 대해 요구사항 자체를 평가해야 합니다:
- 완전성: 필요한 모든 요구사항이 존재합니까?
- 명확성: 요구사항이 모호하지 않고 구체적입니까?
- 일관성: 요구사항이 서로 일치합니까?
- 측정 가능성: 요구사항을 객관적으로 검증할 수 있습니까?
- 커버리지: 모든 시나리오/엣지 케이스가 처리되었습니까?
범주 구조 - 요구사항 품질 차원별로 항목 그룹화:
- 요구사항 완전성 (필요한 모든 요구사항이 문서화되었습니까?)
- 요구사항 명확성 (요구사항이 구체적이고 모호하지 않습니까?)
- 요구사항 일관성 (요구사항이 충돌 없이 일치합니까?)
- 승인 기준 품질 (성공 기준을 측정할 수 있습니까?)
- 시나리오 커버리지 (모든 흐름/케이스가 처리되었습니까?)
- 엣지 케이스 커버리지 (경계 조건이 정의되었습니까?)
- 비기능 요구사항 (성능, 보안, 접근성 등 - 명시되었습니까?)
- 종속성 및 가정 (문서화되고 검증되었습니까?)
- 모호성 및 충돌 (무엇을 명확히 해야 합니까?)
체크리스트 항목 작성 방법 - "요구사항에 대한 단위 테스트":
❌ 잘못된 예 (구현 테스트):
- "랜딩 페이지에 3개의 에피소드 카드가 표시되는지 확인"
- "데스크톱에서 호버 상태가 작동하는지 테스트"
- "로고 클릭이 홈으로 이동하는지 확인"
✅ 올바른 예 (요구사항 품질 테스트):
- "주요 에피소드의 정확한 수와 레이아웃이 지정되었습니까?" [완전성]
- "'눈에 띄게 표시'가 특정 크기/위치로 정량화되었습니까?" [명확성]
- "모든 대화형 요소에 대해 호버 상태 요구사항이 일관되게 정의되었습니까?" [일관성]
- "모든 대화형 UI에 대해 키보드 탐색 요구사항이 정의되었습니까?" [커버리지]
- "로고 이미지 로드 실패 시 대체 동작이 지정되었습니까?" [엣지 케이스]
- "비동기 에피소드 데이터에 대한 로딩 상태가 정의되었습니까?" [완전성]
- "경쟁하는 UI 요소에 대한 시각적 계층 구조가 명세에 정의되어 있습니까?" [명확성]
항목 구조: 각 항목은 다음 패턴을 따라야 합니다:
- 요구사항 품질에 대해 묻는 질문 형식
- 명세/계획에 작성된 (또는 작성되지 않은) 내용에 초점
- 대괄호 안에 품질 차원 포함 [완전성/명확성/일관성 등]
- 기존 요구사항을 확인할 때 명세 섹션 참조
[Spec §X.Y] - 누락된 요구사항을 확인할 때
[Gap]마커 사용
품질 차원별 예시:
완전성:
- "모든 API 실패 모드에 대한 오류 처리 요구사항이 정의되었습니까? [Gap]"
- "모든 대화형 요소에 대한 접근성 요구사항이 지정되었습니까? [완전성]"
- "반응형 레이아웃에 대한 모바일 중단점 요구사항이 정의되었습니까? [Gap]"
명확성:
- "'빠른 로딩'이 특정 시간 임계값으로 정량화되었습니까? [명확성, Spec §NFR-2]"
- "'관련 에피소드' 선택 기준이 명시적으로 정의되었습니까? [명확성, Spec §FR-5]"
- "'눈에 띄는'이 측정 가능한 시각적 속성으로 정의되었습니까? [모호성, Spec §FR-4]"
일관성:
- "탐색 요구사항이 모든 페이지에서 일치합니까? [일관성, Spec §FR-10]"
- "카드 컴포넌트 요구사항이 랜딩 페이지와 상세 페이지 간에 일관됩니까? [일관성]"
커버리지:
- "제로 상태 시나리오(에피소드 없음)에 대한 요구사항이 정의되었습니까? [커버리지, 엣지 케이스]"
- "동시 사용자 상호 작용 시나리오가 처리되었습니까? [커버리지, Gap]"
- "부분 데이터 로딩 실패에 대한 요구사항이 지정되었습니까? [커버리지, 예외 흐름]"
측정 가능성:
- "시각적 계층 구조 요구사항이 측정 가능/테스트 가능합니까? [승인 기준, Spec §FR-1]"
- "'균형 잡힌 시각적 무게'를 객관적으로 검증할 수 있습니까? [측정 가능성, Spec §FR-2]"
시나리오 분류 및 커버리지 (요구사항 품질 초점):
- 다음에 대한 요구사항이 존재하는지 확인: 기본, 대체, 예외/오류, 복구, 비기능 시나리오
- 각 시나리오 클래스에 대해 질문: "[시나리오 유형] 요구사항이 완전하고 명확하며 일관됩니까?"
- 시나리오 클래스가 누락된 경우: "[시나리오 유형] 요구사항이 의도적으로 제외되었습니까, 아니면 누락되었습니까? [Gap]"
- 상태 변경이 발생하는 경우 복원력/롤백 포함: "마이그레이션 실패에 대한 롤백 요구사항이 정의되었습니까? [Gap]"
추적 가능성 요구사항:
- 최소: 항목의 ≥80%에 최소 하나의 추적 가능성 참조가 포함되어야 합니다.
- 각 항목은 명세 섹션
[Spec §X.Y]를 참조하거나[Gap],[모호성],[충돌],[가정]과 같은 마커를 사용해야 합니다. - ID 시스템이 없는 경우: "요구사항 및 승인 기준 ID 체계가 수립되었습니까? [추적 가능성]"
문제 표면화 및 해결 (요구사항 품질 문제): 요구사항 자체에 대한 질문:
- 모호성: "'빠른'이라는 용어가 특정 지표로 정량화되었습니까? [모호성, Spec §NFR-1]"
- 충돌: "탐색 요구사항이 §FR-10과 §FR-10a 사이에서 충돌합니까? [충돌]"
- 가정: "'항상 사용 가능한 팟캐스트 API'라는 가정이 검증되었습니까? [가정]"
- 종속성
- 디렉토리가 없으면