synapse-sdk 2026.1.1b3__tar.gz

synapse_sdk-2026.1.1b3/.claude/commands/compare-branch.md

@@ -0,0 +1,14 @@
+---
+name: compare-branches
+description: Compare changes between branches
+---
+
+Please compare the changes between the current branch and main using GitHub MCP.
+
+Analyze:
+1. File changes and their impact
+2. Code quality improvements or regressions
+3. Potential conflicts or issues
+4. Testing implications
+
+Branch to compare: $ARGUMENTS (default: main if not specified)

synapse_sdk-2026.1.1b3/.claude/commands/review-pr.md

@@ -0,0 +1,137 @@
+---
+name: review-pr
+description: Comprehensive PR review using GitHub MCP with P1-P4 Code Review Rules
+---
+
+Please perform a comprehensive review of PR using the GitHub MCP server.
+
+**Arguments:**
+- First argument: PR number (required)
+- Second argument: Language for review comments - "en" for English, "ko" for Korean (optional, defaults to "en")
+
+**Usage Examples:**
+- `/review-pr 123` - Review PR #123 with English comments
+- `/review-pr 123 en` - Review PR #123 with English comments  
+- `/review-pr 123 ko` - Review PR #123 with Korean comments
+
+**Parse Arguments:**
+Extract PR number from first argument and language preference from second argument (if provided). If second argument is not "ko", default to English ("en").
+
+**IMPORTANT Review Decision Logic:**
+1. **Track all P1, P2, P3 violations found during review**
+2. **If ANY P1, P2, or P3 violations are found** → Use `--request-changes`
+3. **If ONLY P4 violations or no violations found** → Use `--approve`
+4. **Never use `--comment` as the main review action** - always choose between approve or request-changes
+
+**Review Process:**
+1. Read and load P1-P4 Code Review Rules from the following files:
+   - P1_rules.md (Critical - Security and Stability)
+   - P2_rules.md (High Priority - Core functionality and architecture)
+   - P3_rules.md (Medium Priority - Best practices and maintainability)
+   - P4_rules.md (Low Priority - Code style and formatting)
+2. Fetch PR details and file changes
+3. Apply P1-P4 Code Review Rules systematically against the changes
+4. Analyze code quality, security, and performance
+5. Check for test coverage and documentation
+6. Look for potential bugs or issues
+7. Provide specific, actionable feedback with priority levels
+8. Create review comments directly on the PR for each issue found
+
+**P1-P4 Code Review Rules Application:**
+
+IMPORTANT: Before starting the review, read the complete rule sets from these files:
+- `P1_rules.md`
+- `P2_rules.md`
+- `P3_rules.md`
+- `P4_rules.md`
+
+Apply ALL rules from these files during the review process. The rules cover:
+
+**P1 Rules (Critical - MUST FIX):**
+- Security and database integrity issues
+- Critical Django/DRF patterns
+- System stability concerns
+
+**P2 Rules (High Priority):**
+- Core Django/DRF best practices
+- Architecture and design patterns
+- Performance considerations
+
+**P3 Rules (Medium Priority):**
+- Code maintainability
+- Best practices and conventions
+- Safety and error handling
+
+**P4 Rules (Low Priority - Style):**
+- Code formatting and style
+- Naming conventions
+- Consistency standards
+
+**Review Output Format:**
+For each violation found:
+1. **Report to user** with this format:
+   - **Rule Category:** P1/P2/P3/P4
+   - **Specific Rule:** Quote the exact rule from the files
+   - **Location:** File and line number
+   - **Issue:** What violates the rule
+   - **Recommendation:** How to fix it based on the rule guidance
+   - **Impact:** Why this matters (reference rule explanation)
+
+2. **Create PR review comment** using GitHub CLI:
+   - Use `gh pr review {PR_NUMBER} --comment-body "comment text"` for general review comments
+   - Use `gh pr comment {PR_NUMBER} --body "comment text"` for specific line comments when applicable
+   - Format comments with clear priority indicators: [P1], [P2], [P3], [P4]
+   - Include rule reference and actionable guidance in each comment
+   - **IMPORTANT:** Write all comments in the selected language (English or Korean)
+
+**Review Actions:**
+1. **Submit overall review** with summary using: `gh pr review {PR_NUMBER} --approve/--request-changes --body "overall review summary"`
+2. **Add individual comments** for each rule violation found
+3. **Use appropriate review status:**
+   - `--request-changes` if any P1, P2, or P3 violations are found
+   - `--approve` if only P4 violations or no issues found
+   - `--comment` for informational feedback only (no rule violations)
+4. **Language Requirements:**
+   - Write ALL review comments and summary in the selected language
+   - Use appropriate technical terminology for the chosen language
+   - Maintain professional tone in both languages
+
+**Focus Areas:**
+- **Priority 1 (P1):** Critical security and stability issues (MUST FIX) → REQUEST CHANGES
+- **Priority 2 (P2):** Core functionality and architecture (SHOULD FIX) → REQUEST CHANGES  
+- **Priority 3 (P3):** Best practices and maintainability (SHOULD FIX) → REQUEST CHANGES
+- **Priority 4 (P4):** Code style and formatting (OPTIONAL) → APPROVE WITH COMMENTS
+- Test coverage and documentation completeness
+- Breaking changes and backward compatibility
+
+**GitHub CLI Commands to Use:**
+- `gh pr view {PR_NUMBER} --json title,body,state,author,files,commits`
+- `gh pr diff {PR_NUMBER}`
+- `gh pr review {PR_NUMBER} --comment-body "review summary"`
+- `gh pr comment {PR_NUMBER} --body "specific comment"`
+
+**Language-Specific Comment Templates:**
+
+**English Template:**
+```
+[P{LEVEL}] **{TITLE}**
+
+{DESCRIPTION}
+
+**Location:** {FILE}:{LINE}
+**Issue:** {ISSUE_DESCRIPTION}
+**Recommendation:** {RECOMMENDATION}
+**Rule Reference:** {RULE_QUOTE}
+```
+
+**Korean Template:**
+```
+[P{LEVEL}] **{TITLE}**
+
+{DESCRIPTION}
+
+**위치:** {FILE}:{LINE}  
+**문제점:** {ISSUE_DESCRIPTION}
+**권장사항:** {RECOMMENDATION}
+**규칙 참조:** {RULE_QUOTE}
+```

synapse_sdk-2026.1.1b3/.claude/commands/speckit.analyze.md

@@ -0,0 +1,188 @@
+---
+description: 작업 생성 후 spec.md, plan.md, tasks.md 전반에 걸쳐 비파괴적 교차 산출물 일관성 및 품질 분석을 수행합니다.
+---
+
+## 언어 설정
+
+모든 출력과 사용자와의 대화는 **한국어**로 진행합니다.
+
+## 사용자 입력
+
+```text
+$ARGUMENTS
+```
+
+입력이 비어있지 않다면 진행하기 전에 **반드시** 사용자 입력을 고려해야 합니다.
+
+## 목표
+
+구현 전에 세 가지 핵심 산출물(`spec.md`, `plan.md`, `tasks.md`) 전반에 걸쳐 불일치, 중복, 모호성, 미명세 항목을 식별합니다. 이 명령은 `/speckit.tasks`가 완전한 `tasks.md`를 성공적으로 생성한 후에만 실행해야 합니다.
+
+## 운영 제약사항
+
+**엄격한 읽기 전용**: 파일을 수정하지 **마세요**. 구조화된 분석 보고서를 출력합니다. 선택적 수정 계획 제공(사용자가 후속 편집 명령을 수동으로 호출하기 전에 명시적으로 승인해야 함).
+
+**헌법 권한**: 프로젝트 헌법(`.specify/memory/constitution.md`)은 이 분석 범위 내에서 **협상 불가**입니다. 헌법 충돌은 자동으로 CRITICAL이며 명세서, 계획 또는 작업의 조정이 필요합니다—원칙의 희석, 재해석 또는 무시가 아닙니다. 원칙 자체를 변경해야 하는 경우 `/speckit.analyze` 외부의 별도 명시적 헌법 업데이트에서 발생해야 합니다.
+
+## 실행 단계
+
+### 1. 분석 컨텍스트 초기화
+
+저장소 루트에서 `.specify/scripts/bash/check-prerequisites.sh --json --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. 시맨틱 모델 구축
+
+내부 표현 생성(출력에 원시 산출물 포함하지 않음):
+
+- **요구사항 인벤토리**: 안정적인 키가 있는 각 기능 + 비기능 요구사항(명령형 구문에 기반한 슬러그 도출; 예: "사용자가 파일을 업로드할 수 있음" → `user-can-upload-file`)
+- **사용자 스토리/동작 인벤토리**: 인수 기준이 있는 개별 사용자 동작
+- **작업 범위 매핑**: 각 작업을 하나 이상의 요구사항 또는 스토리에 매핑(키워드/ID 또는 핵심 구문과 같은 명시적 참조 패턴에 의한 추론)
+- **헌법 규칙 세트**: 원칙 이름과 MUST/SHOULD 규범적 진술 추출
+
+### 4. 감지 패스(토큰 효율적 분석)
+
+고신호 발견에 집중. 총 50개 발견으로 제한; 나머지는 오버플로우 요약에서 집계.
+
+#### A. 중복 감지
+
+- 거의 중복된 요구사항 식별
+- 통합을 위해 낮은 품질의 표현 표시
+
+#### B. 모호성 감지
+
+- 측정 가능한 기준이 없는 모호한 형용사(빠른, 확장 가능한, 안전한, 직관적인, 견고한) 플래그
+- 해결되지 않은 플레이스홀더(TODO, TKTK, ???, `<placeholder>` 등) 플래그
+
+#### C. 미명세
+
+- 동사가 있지만 객체나 측정 가능한 결과가 없는 요구사항
+- 인수 기준 정렬이 누락된 사용자 스토리
+- 명세서/계획에 정의되지 않은 파일이나 컴포넌트를 참조하는 작업
+
+#### D. 헌법 정렬
+
+- MUST 원칙과 충돌하는 요구사항 또는 계획 요소
+- 헌법에서 요구하는 섹션이나 품질 게이트 누락
+
+#### E. 범위 갭
+
+- 연관된 작업이 0개인 요구사항
+- 매핑된 요구사항/스토리가 없는 작업
+- 작업에 반영되지 않은 비기능 요구사항(예: 성능, 보안)
+
+#### F. 불일치
+
+- 용어 드리프트(동일한 개념이 파일에 따라 다르게 명명됨)
+- 계획에서 참조되지만 명세서에 없는(또는 그 반대) 데이터 엔티티
+- 작업 순서 모순(예: 의존성 노트 없이 기반 설정 작업 전 통합 작업)
+- 충돌하는 요구사항(예: 하나는 Next.js를 요구하고 다른 하나는 Vue를 지정)
+
+### 5. 심각도 할당
+
+이 휴리스틱을 사용하여 발견 우선순위 지정:
+
+- **CRITICAL**: 헌법 MUST 위반, 핵심 명세서 산출물 누락, 또는 기본 기능을 차단하는 범위가 0인 요구사항
+- **HIGH**: 중복 또는 충돌하는 요구사항, 모호한 보안/성능 속성, 테스트 불가능한 인수 기준
+- **MEDIUM**: 용어 드리프트, 누락된 비기능 작업 범위, 미명세 엣지 케이스
+- **LOW**: 스타일/표현 개선, 실행 순서에 영향을 주지 않는 사소한 중복
+
+### 6. 간결한 분석 보고서 생성
+
+다음 구조로 마크다운 보고서 출력(파일 쓰기 없음):
+
+## 명세서 분석 보고서
+
+| ID | 카테고리 | 심각도 | 위치 | 요약 | 권장사항 |
+|----|----------|--------|------|------|----------|
+| A1 | 중복 | HIGH | spec.md:L120-134 | 두 개의 유사한 요구사항 ... | 표현 병합; 더 명확한 버전 유지 |
+
+(발견당 한 행 추가; 카테고리 이니셜이 접두사로 붙은 안정적인 ID 생성.)
+
+**범위 요약 테이블:**
+
+| 요구사항 키 | 작업 있음? | 작업 ID | 참고사항 |
+|-------------|-----------|---------|----------|
+
+**헌법 정렬 문제:** (있는 경우)
+
+**매핑되지 않은 작업:** (있는 경우)
+
+**지표:**
+
+- 총 요구사항
+- 총 작업
+- 범위 % (≥1 작업이 있는 요구사항)
+- 모호성 수
+- 중복 수
+- Critical 문제 수
+
+### 7. 다음 조치 제공
+
+보고서 끝에 간결한 다음 조치 블록 출력:
+
+- CRITICAL 문제가 있으면: `/speckit.implement` 전에 해결 권장
+- LOW/MEDIUM만 있으면: 사용자가 진행할 수 있지만 개선 제안 제공
+- 명시적 명령 제안 제공: 예: "정제와 함께 /speckit.specify 실행", "아키텍처 조정을 위해 /speckit.plan 실행", "'performance-metrics'에 대한 범위 추가를 위해 tasks.md 수동 편집"
+
+### 8. 수정 제공
+
+사용자에게 질문: "상위 N개 문제에 대한 구체적인 수정 편집을 제안해 드릴까요?" (자동으로 적용하지 마세요.)
+
+## 운영 원칙
+
+### 컨텍스트 효율성
+
+- **최소한의 고신호 토큰**: 철저한 문서화가 아닌 실행 가능한 발견에 집중
+- **점진적 공개**: 산출물을 점진적으로 로드; 모든 내용을 분석에 덤프하지 않음
+- **토큰 효율적 출력**: 발견 테이블을 50행으로 제한; 오버플로우 요약
+- **결정론적 결과**: 변경 없이 재실행하면 일관된 ID와 수를 생성해야 함
+
+### 분석 가이드라인
+
+- **파일 수정 안 함** (이것은 읽기 전용 분석)
+- **누락된 섹션을 환각하지 않음** (없으면 정확하게 보고)
+- **헌법 위반 우선순위 지정** (이것들은 항상 CRITICAL)
+- **철저한 규칙보다 예시 사용** (일반적인 패턴이 아닌 구체적인 인스턴스 인용)
+- **문제 없음을 우아하게 보고** (범위 통계와 함께 성공 보고서 출력)
+
+## 컨텍스트
+
+$ARGUMENTS

synapse_sdk-2026.1.1b3/.claude/commands/speckit.checklist.md

@@ -0,0 +1,298 @@
+---
+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가 명확히 명시되어 있나요?"