---
description: 사용자 요구사항을 기반으로 현재 기능에 대한 사용자 정의 체크리스트를 생성합니다.
---

## 체크리스트 목적: "영어로 된 요구사항의 단위 테스트"

**핵심 개념**: 체크리스트는 **요구사항 작성에 대한 단위 테스트**입니다 - 주어진 도메인에서 요구사항의 품질, 명확성, 완성도를 검증합니다.

**검증/테스트용이 아님**:

- ❌ "버튼이 올바르게 클릭되는지 확인" 아님
- ❌ "오류 처리가 작동하는지 테스트" 아님
- ❌ "API가 200을 반환하는지 확인" 아님
- ❌ 코드/구현이 명세서와 일치하는지 확인하는 것 아님

**요구사항 품질 검증용**:

- ✅ "모든 카드 유형에 대해 시각적 계층 요구사항이 정의되어 있나요?" (완성도)
- ✅ "'눈에 띄는 표시'가 구체적인 크기/위치로 정량화되어 있나요?" (명확성)
- ✅ "모든 인터랙티브 요소에 대해 호버 상태 요구사항이 일관되게 정의되어 있나요?" (일관성)
- ✅ "키보드 탐색에 대한 접근성 요구사항이 정의되어 있나요?" (범위)
- ✅ "로고 이미지 로드 실패 시 어떻게 되는지 명세서에 정의되어 있나요?" (엣지 케이스)

**비유**: 명세서가 영어로 작성된 코드라면, 체크리스트는 그 단위 테스트 스위트입니다. 구현이 작동하는지가 아니라 요구사항이 잘 작성되었는지, 완전한지, 명확한지, 구현 준비가 되었는지를 테스트하는 것입니다.

## 언어 설정

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

## 사용자 입력

```text
$ARGUMENTS
```

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

## 실행 단계

1. **설정**: 저장소 루트에서 `.specify/scripts/bash/check-prerequisites.sh --json`을 실행하고 JSON에서 FEATURE_DIR과 AVAILABLE_DOCS 목록을 파싱합니다.
   - 모든 파일 경로는 절대 경로여야 합니다.
   - "I'm Groot"와 같이 인수에 작은따옴표가 있는 경우 이스케이프 구문 사용: 예: 'I'\''m Groot' (또는 가능하면 큰따옴표: "I'm Groot").

2. **의도 명확화 (동적)**: 최대 3개의 초기 컨텍스트 명확화 질문을 도출합니다 (미리 정해진 카탈로그 없음). 반드시:
   - 사용자의 표현 + spec/plan/tasks에서 추출된 신호로부터 생성
   - 체크리스트 내용을 실질적으로 변경하는 정보에 대해서만 질문
   - `$ARGUMENTS`에서 이미 명확한 경우 개별적으로 건너뛰기
   - 넓이보다 정확성 선호

   생성 알고리즘:
   1. 신호 추출: 기능 도메인 키워드 (예: auth, latency, UX, API), 리스크 지표 ("critical", "must", "compliance"), 이해관계자 힌트 ("QA", "review", "security team"), 명시적 산출물 ("a11y", "rollback", "contracts").
   2. 신호를 관련성 순으로 순위 매긴 후보 포커스 영역으로 클러스터링 (최대 4개).
   3. 명시적이지 않은 경우 가능한 대상 및 시점 식별 (작성자, 리뷰어, QA, 릴리스).
   4. 누락된 차원 감지: 범위 폭, 깊이/엄격성, 리스크 강조, 제외 경계, 측정 가능한 인수 기준.
   5. 다음 아키타입에서 선택한 질문 작성:
      - 범위 정제 (예: "이것이 X, Y와의 통합 터치포인트를 포함해야 하나요, 아니면 로컬 모듈 정확성에 한정해야 하나요?")
      - 리스크 우선순위 (예: "이 잠재적 리스크 영역 중 어느 것이 필수 게이팅 체크를 받아야 하나요?")
      - 깊이 조정 (예: "이것이 가벼운 사전 커밋 정상성 목록인가요, 아니면 공식 릴리스 게이트인가요?")
      - 대상 프레이밍 (예: "이것이 작성자만 사용하나요, 아니면 PR 리뷰 중 동료도 사용하나요?")
      - 경계 제외 (예: "이번 라운드에서 성능 튜닝 항목을 명시적으로 제외해야 하나요?")
      - 시나리오 클래스 갭 (예: "복구 흐름이 감지되지 않음—롤백/부분 실패 경로가 범위에 포함되나요?")

   질문 포맷팅 규칙:
   - 옵션을 제시하는 경우 열이 있는 간결한 테이블 생성: 옵션 | 후보 | 중요한 이유
   - 최대 A–E 옵션으로 제한; 자유 형식 답변이 더 명확하면 테이블 생략
   - 사용자가 이미 말한 것을 다시 말하게 하지 않음
   - 추측성 카테고리 피하기 (환각 없음). 불확실하면 명시적으로 질문: "X가 범위에 포함되는지 확인해 주세요."

   상호작용이 불가능할 때 기본값:
   - 깊이: 표준
   - 대상: 코드 관련이면 리뷰어 (PR); 그렇지 않으면 작성자
   - 포커스: 상위 2개 관련성 클러스터

   질문 출력 (Q1/Q2/Q3 레이블). 답변 후: 2개 이상의 시나리오 클래스 (대안 / 예외 / 복구 / 비기능 도메인)가 불명확하면 각각 한 줄 정당화와 함께 최대 2개의 추가 후속 질문 (Q4/Q5)을 할 수 있음 (예: "해결되지 않은 복구 경로 리스크"). 총 5개 질문을 초과하지 않음. 사용자가 더 이상 원하지 않는다고 명시적으로 거절하면 에스컬레이션 건너뛰기.

3. **사용자 요청 이해**: `$ARGUMENTS` + 명확화 답변 결합:
   - 체크리스트 테마 도출 (예: security, review, deploy, ux)
   - 사용자가 언급한 명시적 필수 항목 통합
   - 포커스 선택을 카테고리 스캐폴딩에 매핑
   - spec/plan/tasks에서 누락된 컨텍스트 추론 (환각하지 않음)

4. **기능 컨텍스트 로드**: FEATURE_DIR에서 읽기:
   - spec.md: 기능 요구사항과 범위
   - plan.md (있는 경우): 기술 세부사항, 의존성
   - tasks.md (있는 경우): 구현 작업

   **컨텍스트 로딩 전략**:
   - 활성 포커스 영역과 관련된 필요한 부분만 로드 (전체 파일 덤프 피하기)
   - 긴 섹션을 간결한 시나리오/요구사항 불릿으로 요약 선호
   - 점진적 공개 사용: 갭이 감지된 경우에만 후속 검색 추가
   - 소스 문서가 크면 원시 텍스트 임베딩 대신 중간 요약 항목 생성

5. **체크리스트 생성** - "요구사항에 대한 단위 테스트" 생성:
   - `FEATURE_DIR/checklists/` 디렉토리가 없으면 생성
   - 고유한 체크리스트 파일명 생성:
     - 도메인에 기반한 짧고 설명적인 이름 사용 (예: `ux.md`, `api.md`, `security.md`)
     - 형식: `[domain].md`
     - 파일이 존재하면 기존 파일에 추가
   - CHK001부터 순차적으로 항목 번호 지정
   - 각 `/speckit.checklist` 실행은 새 파일 생성 (기존 체크리스트 덮어쓰지 않음)

   **핵심 원칙 - 구현이 아닌 요구사항 테스트**:
   모든 체크리스트 항목은 요구사항 자체를 다음에 대해 평가해야 함:
   - **완성도**: 필요한 모든 요구사항이 존재하는가?
   - **명확성**: 요구사항이 모호하지 않고 구체적인가?
   - **일관성**: 요구사항이 서로 일치하는가?
   - **측정 가능성**: 요구사항을 객관적으로 검증할 수 있는가?
   - **범위**: 모든 시나리오/엣지 케이스가 다뤄졌는가?

   **카테고리 구조** - 요구사항 품질 차원별 그룹화:
   - **요구사항 완성도** (필요한 모든 요구사항이 문서화되었는가?)
   - **요구사항 명확성** (요구사항이 구체적이고 모호하지 않은가?)
   - **요구사항 일관성** (요구사항이 충돌 없이 일치하는가?)
   - **인수 기준 품질** (성공 기준이 측정 가능한가?)
   - **시나리오 범위** (모든 흐름/케이스가 다뤄졌는가?)
   - **엣지 케이스 범위** (경계 조건이 정의되었는가?)
   - **비기능 요구사항** (성능, 보안, 접근성 등 - 명시되었는가?)
   - **의존성 및 가정** (문서화되고 검증되었는가?)
   - **모호성 및 충돌** (명확화가 필요한 것은?)

   **체크리스트 항목 작성 방법 - "영어로 된 단위 테스트"**:

   ❌ **잘못됨** (구현 테스트):
   - "랜딩 페이지가 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' 가정이 검증되었나요? [가정]"
   - 의존성: "외부 팟캐스트 API 요구사항이 문서화되어 있나요? [의존성, Gap]"
   - 누락된 정의: "'시각적 계층'이 측정 가능한 기준으로 정의되어 있나요? [Gap]"

   **내용 통합**:
   - 소프트 캡: 원시 후보 항목 > 40개이면 리스크/영향도로 우선순위 지정
   - 같은 요구사항 측면을 확인하는 거의 중복된 것 병합
   - 저영향 엣지 케이스 >5개이면 하나의 항목 생성: "요구사항에서 엣지 케이스 X, Y, Z가 다뤄졌나요? [범위]"

   **🚫 절대 금지** - 이것들은 요구사항 테스트가 아닌 구현 테스트가 됨:
   - ❌ "확인", "테스트", "검증", "체크" + 구현 동작으로 시작하는 모든 항목
   - ❌ 코드 실행, 사용자 동작, 시스템 동작에 대한 참조
   - ❌ "올바르게 표시됨", "제대로 작동함", "예상대로 기능함"
   - ❌ "클릭", "탐색", "렌더링", "로드", "실행"
   - ❌ 테스트 케이스, 테스트 계획, QA 절차
   - ❌ 구현 세부사항 (프레임워크, API, 알고리즘)

   **✅ 필수 패턴** - 요구사항 품질을 테스트:
   - ✅ "[시나리오]에 대해 [요구사항 유형]이 정의/명시/문서화되어 있나요?"
   - ✅ "[모호한 용어]가 구체적인 기준으로 정량화/명확화되어 있나요?"
   - ✅ "[섹션 A]와 [섹션 B] 사이에 요구사항이 일관되나요?"
   - ✅ "[요구사항]을 객관적으로 측정/검증할 수 있나요?"
   - ✅ "요구사항에서 [엣지 케이스/시나리오]가 다뤄졌나요?"
   - ✅ "명세서에 [누락된 측면]이 정의되어 있나요?"

6. **구조 참조**: `.specify/templates/checklist-template.md`의 표준 템플릿을 따라 제목, 메타 섹션, 카테고리 제목, ID 포맷팅을 사용하여 체크리스트 생성. 템플릿을 사용할 수 없으면 다음 사용: H1 제목, purpose/created 메타 라인, `##` 카테고리 섹션에 CHK001부터 시작하는 전역 증가 ID로 `- [ ] CHK### <요구사항 항목>` 라인 포함.

7. **보고**: 생성된 체크리스트의 전체 경로, 항목 수 출력하고 각 실행이 새 파일을 생성한다는 것을 사용자에게 상기시키기. 요약:
   - 선택된 포커스 영역
   - 깊이 수준
   - 대상자/시점
   - 통합된 명시적 사용자 지정 필수 항목

**중요**: 각 `/speckit.checklist` 명령 호출은 파일이 이미 존재하지 않는 한 짧고 설명적인 이름으로 체크리스트 파일을 생성합니다. 이를 통해:

- 다른 유형의 여러 체크리스트 (예: `ux.md`, `test.md`, `security.md`)
- 체크리스트 목적을 나타내는 간단하고 기억하기 쉬운 파일명
- `checklists/` 폴더에서 쉬운 식별 및 탐색

혼란을 피하려면 설명적인 유형을 사용하고 완료되면 구식 체크리스트를 정리하세요.

## 체크리스트 유형 예시 및 샘플 항목

**UX 요구사항 품질:** `ux.md`

샘플 항목 (구현이 아닌 요구사항 테스트):

- "시각적 계층 요구사항이 측정 가능한 기준으로 정의되어 있나요? [명확성, Spec §FR-1]"
- "UI 요소의 개수와 위치가 명시적으로 지정되어 있나요? [완성도, Spec §FR-1]"
- "상호작용 상태 요구사항 (호버, 포커스, 활성)이 일관되게 정의되어 있나요? [일관성]"
- "모든 인터랙티브 요소에 대해 접근성 요구사항이 명시되어 있나요? [범위, Gap]"
- "이미지 로드 실패 시 폴백 동작이 정의되어 있나요? [엣지 케이스, Gap]"
- "'눈에 띄는 표시'를 객관적으로 측정할 수 있나요? [측정 가능성, Spec §FR-4]"

**API 요구사항 품질:** `api.md`

샘플 항목:

- "모든 실패 시나리오에 대해 오류 응답 형식이 명시되어 있나요? [완성도]"
- "속도 제한 요구사항이 구체적인 임계값으로 정량화되어 있나요? [명확성]"
- "모든 엔드포인트에 대해 인증 요구사항이 일관되나요? [일관성]"
- "외부 의존성에 대한 재시도/타임아웃 요구사항이 정의되어 있나요? [범위, Gap]"
- "버전 관리 전략이 요구사항에 문서화되어 있나요? [Gap]"

**성능 요구사항 품질:** `performance.md`

샘플 항목:

- "성능 요구사항이 구체적인 지표로 정량화되어 있나요? [명확성]"
- "모든 중요한 사용자 여정에 대해 성능 목표가 정의되어 있나요? [범위]"
- "다른 부하 조건에서의 성능 요구사항이 명시되어 있나요? [완성도]"
- "성능 요구사항을 객관적으로 측정할 수 있나요? [측정 가능성]"
- "고부하 시나리오에 대한 저하 요구사항이 정의되어 있나요? [엣지 케이스, Gap]"

**보안 요구사항 품질:** `security.md`

샘플 항목:

- "모든 보호된 리소스에 대해 인증 요구사항이 명시되어 있나요? [범위]"
- "민감한 정보에 대한 데이터 보호 요구사항이 정의되어 있나요? [완성도]"
- "위협 모델이 문서화되고 요구사항이 그에 맞춰져 있나요? [추적성]"
- "보안 요구사항이 컴플라이언스 의무와 일치하나요? [일관성]"
- "보안 실패/침해 대응 요구사항이 정의되어 있나요? [Gap, 예외 흐름]"

## 반면교사: 하지 말아야 할 것

**❌ 잘못됨 - 구현을 테스트함, 요구사항이 아님:**

```markdown
- [ ] CHK001 - 랜딩 페이지가 3개의 에피소드 카드를 표시하는지 확인 [Spec §FR-001]
- [ ] CHK002 - 데스크톱에서 호버 상태가 올바르게 작동하는지 테스트 [Spec §FR-003]
- [ ] CHK003 - 로고 클릭이 홈 페이지로 이동하는지 확인 [Spec §FR-010]
- [ ] CHK004 - 관련 에피소드 섹션이 3-5개 항목을 표시하는지 확인 [Spec §FR-005]
```

**✅ 올바름 - 요구사항 품질을 테스트함:**

```markdown
- [ ] CHK001 - 추천 에피소드의 개수와 레이아웃이 명시적으로 지정되어 있나요? [완성도, Spec §FR-001]
- [ ] CHK002 - 모든 인터랙티브 요소에 대해 호버 상태 요구사항이 일관되게 정의되어 있나요? [일관성, Spec §FR-003]
- [ ] CHK003 - 모든 클릭 가능한 브랜드 요소에 대해 탐색 요구사항이 명확한가요? [명확성, Spec §FR-010]
- [ ] CHK004 - 관련 에피소드 선택 기준이 문서화되어 있나요? [Gap, Spec §FR-005]
- [ ] CHK005 - 비동기 에피소드 데이터에 대한 로딩 상태 요구사항이 정의되어 있나요? [Gap]
- [ ] CHK006 - "시각적 계층" 요구사항을 객관적으로 측정할 수 있나요? [측정 가능성, Spec §FR-001]
```

**주요 차이점:**

- 잘못됨: 시스템이 올바르게 작동하는지 테스트
- 올바름: 요구사항이 올바르게 작성되었는지 테스트
- 잘못됨: 동작 검증
- 올바름: 요구사항 품질 검증
- 잘못됨: "X를 하나요?"
- 올바름: "X가 명확히 명시되어 있나요?"
