spec-reviewer

name	spec-reviewer
description	Use when a spec or planning document needs development-readiness validation. Detects missing edge cases, state transitions, data constraints, and gives PASS/FAIL judgment. For developers reviewing specs or planning teams wanting pre-development quality checks. Triggers: "기획서 리뷰", "spec review", "기획서 검증", "개발 Ready 확인", "spec reviewer", "기획서 봐줘"
allowed-tools	AskUserQuestion, Write, Read, Glob, Grep

Spec Reviewer

기획서의 완성도를 개발 관점에서 검증한다. 14개 체크리스트 기반으로 누락 항목을 검출하고, Critical/Important/Nice-to-have로 분류하여 "개발 Ready" 판정을 내린다.

When to Use

• 기획서가 개발을 시작하기에 충분한지 확인하고 싶을 때
• spec-generator 산출물을 검증할 때
• 기존 기획서(어떤 형태든)의 빈틈을 찾고 싶을 때

Do NOT use when:

• 요구사항이 아직 정리되지 않은 상태 → spec-interview 먼저
• 기획서가 아닌 코드 리뷰 → pr-reviewer 사용
• 개발 스펙을 작성하고 싶을 때 → interview Skill 사용

Quick Reference

Phase	Action	Key Rule
1. Input 파싱	기획서 읽기 + 템플릿 매핑	어떤 형태의 기획서든 수용
2. 커버리지 체크	8개 섹션 대비 빈/약한 섹션 식별	정량적 매트릭스
2.5. 필수 질문	M1-M8 강제 질문 블록	스킵 불가, 모두 답변 필수
3. 갭 분석	14개 체크리스트 기반 누락 검출	도메인 기반 추론
4. 질문 생성 + 판정	분류 + PASS/FAIL	Critical 0개 = PASS

CRITICAL: AskUserQuestion 턴 분리 규칙

AskUserQuestion은 이 스킬이 로드된 턴(같은 assistant turn)에서 절대 호출하지 마세요.

Skill tool로 이 스킬이 로드되면, 같은 턴에서 AskUserQuestion을 호출할 경우 사용자에게 질문 UI가 표시되지 않고 빈 응답으로 자동 처리됩니다 (Claude Code 플랫폼 제약).

필수 절차:

• Input이 없으면: "어떤 기획서를 리뷰할까요?"를 텍스트로 출력하고 STOP한다
• Input이 있으면: Phase 1-4를 수행하고 결과 파일을 출력한다 (AskUserQuestion 불필요)

이 규칙을 어기면 사용자가 질문을 볼 수 없습니다.

핵심 원칙

1. 개발자 관점에서 검증하되, 기획팀이 답할 수 있는 질문을 만든다. "이 기능은 soft delete인가요?"가 아니라 "삭제하면 복구할 수 있나요, 완전히 사라지나요?"로 질문한다.

2. 검증은 엄격하게, 질문은 친절하게. 빈틈은 정확히 짚되, 질문은 기획팀이 이해할 수 있는 비즈니스 언어로 작성한다.

3. 판정 기준은 명확하다.

• Critical 0개 → PASS (개발 시작 가능)
• Critical 1개 이상 → FAIL (보완 필요)
• Important 5개 이상 → PASS이지만 경고

Protocol

Phase 1: Input 파싱

1. 기획서 파일 확인:

   • specs/{feature}-spec.md 존재 여부 확인 (Glob)
   • 같은 세션에서 spec-generator가 실행되었다면 해당 컨텍스트 활용
   • 사용자가 직접 제공한 파일/텍스트도 가능

2. 제품 Context 로딩 (대화 컨텍스트에 이미 domain.md/codebase-summary.md가 존재하면 이 단계를 건너뛴다 — spec-pipeline에서 호출된 경우):

   • ~/.claude/skills/spec-pipeline/products/_registry.md를 읽고 기획서 내용에서 제품을 식별한다
   • 매칭된 제품의 ~/.claude/skills/spec-pipeline/products/{product-id}/codebase-summary.md를 읽어 기술적 제약을 파악한다
   • Context 활용 — 검증 강화: 코드베이스에 이미 존재하는 API/DB 구조와 기획서의 시나리오를 대조하여, 기존 시스템과의 정합성을 추가 검증한다
   • [Context 기반] 마크 처리: spec-generator가 붙인 [Context 기반] 마크는 코드/문서에 근거가 있으므로 [추정]보다 낮은 검증 강도를 적용한다:
     • 기본: Nice-to-have (근거가 있으므로)
     • 단, Critical 조건(핵심 흐름 영향, 핵심 데이터 제약 등)에 해당하면 Important 또는 Critical로 올린다 — 코드 근거가 있어도 핵심 기능에 영향이면 반드시 검증
   • 미등록 제품이면 context 없이 범용 모드로 진행한다

3. 템플릿 매핑: 입력이 8개 섹션 구조가 아닌 경우, 내용을 8개 섹션에 매핑:

   입력의 각 부분 → 8개 섹션 중 어디에 해당하는가?
   

   매핑 불가능한 내용은 "추가 정보"로 별도 기록한다.

4. [추정] / [Context 기반] 마크 수집: 기획서에 [추정] 또는 [Context 기반] 마크가 있으면 별도로 수집한다.

   • [추정]은 자동으로 Important 이상으로 분류된다
   • [Context 기반]은 코드/문서 근거가 있으므로 기본 Nice-to-have로 분류한다
   • 단, [Context 기반]이라도 Critical 조건(핵심 흐름 영향, 핵심 데이터 제약 누락 등)에 해당하면 Important 또는 Critical로 올린다
   • 주의: spec-generator에서 PM이 확인하여 마크가 제거된 항목은 확정 내용으로 취급한다. reviewer는 남아있는 마크만 플래그한다.

5. 미결 사항 수집: 기획서 또는 요구사항에 "미결 사항" 섹션이 있으면 수집한다.

   • 미결 사항이 이번 범위(scope) 내 기능에 영향을 미치는 경우:
     • Generator가 합리적 기본값을 [추정]으로 제안한 미결 사항 → Important (기본값이 있으므로 개발 시작은 가능)
     • Generator가 기본값을 제안하지 못한(빈칸) 미결 사항 → Critical (개발 시작 불가)
   • 미결 사항이 이번 범위 밖이거나 v2 이후 기능에 해당 → Nice-to-have로 분류
   • 미결 사항은 "알려진 미결"로서, 누락 항목과 구분하여 별도 섹션에 기록한다

Phase 2: 커버리지 체크

8개 섹션 각각에 대해 상태를 판정한다:

상태	기준	예시
충분	구체적 내용이 있고, 개발자가 바로 구현 가능	예외 상황 3개 이상 + 각각 사용자 반응 명시
약함	내용이 있지만 모호하거나 핵심 요소 절반 이상 누락	"관리자만 가능"만 있고 세부 권한 없음
없음	해당 섹션 내용이 전혀 없거나, 한 문장 이하	데이터 필드 목록 없이 "사용자 정보 저장" 수준
해당없음	이 기능에 적용되지 않음 (명시적으로 "없음" 언급 시)	"외부 연동 없음" 명시

마크가 포함된 섹션의 판정 규칙:

• [추정] 비율 임계치는 기능 복잡도에 따라 차등 적용한다:

  기능 복잡도	[추정] 임계치	판단 기준
  Low (단일 CRUD, 독립 기능)	30% 이상 → 최대 "약함"	요구사항이 명확해야 하는 범위
  Medium (다중 시나리오, 연동 1-2개)	40% 이상 → 최대 "약함"	일부 추정이 자연스러운 범위
  High (복합 흐름, 연동 3개+, 신규 도메인)	50% 이상 → 최대 "약함"	미지 영역이 넓어 추정이 불가피

• 복잡도 판단: 기획서의 시나리오 수, 연동 시스템 수, 상태 전이 수를 종합하여 판단

• 임계치 미만이면 → "충분" 가능하되, 비고에 [추정] 항목을 명시

• [Context 기반] 항목은 이 임계치에 포함하지 않는다 — 코드/문서 근거가 있으므로 확정 내용에 준한다

커버리지 매트릭스:

| 섹션 | 상태 | 비고 |
|------|------|------|
| 1. 배경 | 충분 | — |
| 2. 사용자와 목표 | 약함 | 사용자 유형이 1개만 명시 |
| 3. 사용 시나리오 | 충분 | 정상 흐름 + 예외 3개 |
| 4. 데이터와 상태 | 없음 | 상태 전이 누락 |
| 5. 연결되는 시스템 | 해당없음 | — |
| 6. 권한 | 약함 | "관리자만 가능"만 명시 |
| 7. 범위와 성공 기준 | 충분 | — |
| 8. 개발 정책 | 약함 | [추정] 3개, 동시 수정 미정의 |

Phase 2.5: 강제 필수 질문 블록 (Mandatory Questions)

Phase 2 커버리지 체크 후, Phase 3 갭 분석 전에 8개 필수 질문에 반드시 답한다. 이 질문들은 체크리스트 14개와 별개로, 기획서의 "큰 그림" 빈틈을 잡는다. 어떤 질문도 건너뛸 수 없다 — "해당없음"이면 그 이유를 명시해야 한다.

#	필수 질문	왜 중요한가
M1	첫 사용 시 무엇이 보이는가? (빈 상태, 온보딩)	기획서의 80%는 "데이터가 있는 상태"만 기술. 빈 상태가 정의 안 되면 개발자가 임의로 만듦
M2	잘못된 입력이 들어오면? (악의적 입력 포함)	XSS, SQL injection, 형식 위반 등 방어 시나리오 누락 여부
M3	동시에 여러 명이 같은 것을 수정하면?	동시성 이슈는 기획에서 거의 100% 누락됨
M4	외부 연동이 실패하면? (API 타임아웃, 서버 다운)	외부 의존성 장애 시 사용자 경험이 정의 안 되면 500 에러 노출
M5	이 데이터의 생명주기는? (생성→수정→삭제→보관)	삭제 정책, 보관 기간, 개인정보 처리 누락
M6	누가 이 데이터를 볼 수 있고, 수정/삭제할 수 있는가?	권한 모델 누락 시 보안 취약점 발생
M7	이 기능이 프로덕션에서 문제가 생기면 어떻게 되돌리는가?	롤백 전략이 없으면 장애 시 수습 불가
M8	성공을 어떻게 측정하는가? (정량적 기준)	"잘 되면 됐다"는 테스트 불가능. 구체적 수치 필요

답변 형식:

## 필수 질문 블록

| # | 질문 | 기획서 답변 | 상태 |
|---|------|-----------|------|
| M1 | 첫 사용 시 무엇이 보이는가? | "빈 목록 + 생성 버튼" (섹션 3) | ✅ 충분 |
| M2 | 잘못된 입력이 들어오면? | 정의 없음 | ❌ 누락 → Important |
| M3 | 동시 수정 시? | 해당없음 (읽기 전용 기능) | ➖ N/A |
| ... | ... | ... | ... |

누락된 항목은 Phase 4의 질문 목록에 자동으로 추가된다. M1-M8 중 Critical 조건에 해당하는 누락은 Phase 4의 Critical로 직접 분류한다.

---

Phase 3: 갭 분석

14개 검증 체크리스트:

#	검증 항목	검증 질문	Critical 조건
1	암묵적 가정	당연하다고 생각해서 안 쓴 비즈니스 규칙은 없는가?	핵심 흐름에 영향
2	에러/실패 시나리오	모든 정상 흐름에 대응하는 실패 시나리오가 있는가?	정상 흐름 대비 예외 커버율 50% 미만
3	상태 전이 완전성	모든 (현재상태, 이벤트) 조합이 정의되었는가? spec-generator가 구조화한 상태 표의 완전성을 검증한다.	상태가 있는데 전이 미정의
4	데이터 제약	모든 데이터 항목에 필수/선택, 최대길이, 형식이 있는가?	핵심 데이터 제약 누락
5	권한 모델	각 기능에 대해 누가 할 수 있고/없는지 명시되었는가?	다중 역할인데 권한 미정의
6	연동 계약	외부 시스템과의 인터페이스가 충분히 기술되었는가?	연동 있는데 장애 시 동작 미정의
7	목록 동작	목록이 있다면 빈 상태/대량/정렬/검색이 정의되었는가?	목록 UI인데 빈 상태 미정의
8	입력 유효성	사용자 입력 필드의 허용 범위/형식이 정의되었는가?	핵심 입력 필드 유효성 누락
9	범위 경계	"안 하는 것"이 명시적으로 정의되었는가?	범위가 전혀 정의되지 않음
10	성공 기준	완성의 정의가 테스트 가능한 형태인가?	성공 기준 없음
11	비기능 요구사항	동시 사용자 수, 응답 속도, 보안/개인정보 요건이 정의되었는가? 고위험 도메인(결제/의료/개인정보)이면 규제 준수 요건이 있는가?	핵심 비기능 요건 누락 (예: 결제 기능인데 보안 요건 없음, 의료 데이터인데 비식별화 요건 없음)
12	개발 정책 완전성	섹션 8의 정책이 기능 유형에 맞게 정의되었는가? CRUD 기능이면 수정/삭제/동시성/중복/이력 정책이 있는가? 공유 기능이면 원본-사본 동기화/공유 취소/범위 정책이 있는가?	CRUD 기능인데 삭제 또는 동시성 정책 미정의. 공유 기능인데 동기화 정책 미정의
13	연관 데이터 영향	엔티티 간 연결이 있다면, 변경/삭제 시 연쇄 영향이 정의되었는가? 섹션 4의 "연관 데이터 영향" 표가 있어야 하는데 없거나, 있지만 불완전한가?	연관 데이터가 있는데 연쇄 영향 미정의
14	기존 시스템 정합성	기획서의 시나리오/데이터/상태가 기존 코드베이스(codebase-summary.md)와 모순되지 않는가? 기존 API/DB 구조와 충돌하는 설계가 있는가?	기존 시스템과 명시적으로 모순되는 설계 (context 있을 때만 검증)

갭 분석 방법:

• 각 항목을 순서대로 검증
• 도메인 지식을 활용하여 기획서에서 빠진 구체적 시나리오를 제시
  • 예: "결제 기능인데 '결제 중 네트워크 오류' 시나리오가 없습니다"
  • 예: "'주문' 상태에서 '취소 요청'이 들어오면 어떻게 되는지 정의되지 않았습니다"
• [추정] 마크가 붙은 항목의 분류 규칙:
  • [추정]이 체크리스트 Critical 조건 항목(핵심 흐름, 핵심 데이터, 범위 등)에 해당:
    • 미결 사항에서 Generator가 합리적 기본값을 제안한 [추정] → Important (기본값이 있으므로 개발 시작 가능, 다만 PM 확인 필요)
    • 그 외 [추정] (Generator가 독자적으로 채운 내용, 기본값 없는 미결) → Critical
  • [추정]이 그 외 항목에 해당 → Important
  • [추정]은 최소 Important. Nice-to-have로 내리지 않는다

Phase 4: 질문 생성 + 판정

질문 분류:

등급	기준	예시
Critical	이 정보 없이는 개발 시작 불가	"삭제 시 복구 가능한가요, 완전히 사라지나요?"
Important	개발 가능하지만 나중에 재작업 필요	"동시에 같은 데이터를 수정하면 어떻게 되나요?"
Nice-to-have	없어도 v1은 가능	"다국어 지원이 필요한가요?"

질문 작성 규칙:

• 비기술 언어로 작성 (기획팀이 답할 수 있어야 함)
• 각 질문에 왜 필요한지 한 줄 설명 추가
• 질문이 15개 이상이면 우선순위 상위 10개만 표시, 나머지는 "추가 질문" 섹션으로

판정 기준:

조건	판정
Critical 0개	PASS — 개발 Ready
Critical 0개 + Important 5개 이상	PASS (경고) — 개발 가능하지만 재작업 리스크
Critical 1개 이상	FAIL — Critical 해소 후 재검증 필요

Output 작성 — Write to specs/{feature-slug}-review.md:

# {기능명} — 기획서 리뷰

## 판정: PASS / FAIL

(FAIL인 경우) Critical N개 해소 필요
(PASS + 경고인 경우) 개발 가능하나 Important N개 주의

## 커버리지
| 섹션 | 상태 | 비고 |
|------|------|------|
| 1. 배경 | 충분 | — |
| ... | ... | ... |

## 누락 항목

### Critical (N개)
1. **[항목명]**: [질문]
   - 왜 필요한가: [설명]

2. ...

### Important (N개)
1. **[항목명]**: [질문]
   - 왜 필요한가: [설명]

2. ...

### Nice-to-have (N개)
1. ...

## 발견된 엣지 케이스
- [시나리오 설명]: [왜 문제가 되는가]
- ...

## 상태 전이 빈틈
- [현재상태] + [이벤트] → 정의 안 됨
- ...

(상태 전이가 해당하지 않으면 이 섹션 생략)

## [추정] 항목 검토
- [추정 내용]: [확인 필요 여부]
- ...

(추정 항목이 없으면 이 섹션 생략)

## [Context 기반] 항목 검토
| 항목 | 코드/문서 근거 | 정합성 | 등급 |
|------|--------------|--------|------|
| [내용] | [출처: codebase-summary.md의 해당 부분] | 일치/불일치/확인 필요 | Nice-to-have/Important/Critical |

(Context 기반 항목이 없으면 이 섹션 생략)

## 미결 사항 현황
- [미결 내용]: [이번 범위에 영향 여부] → [Important / Nice-to-have]
- ...

(미결 사항이 없으면 이 섹션 생략)

## 권장 사항
1. ...
2. ...

slug 규칙: 요구사항/기획서 파일의 slug와 동일. 영문 소문자, 하이픈 구분.

Tell the user the file path after writing.

출력 후 안내:

PASS인 경우: "개발 Ready입니다. 기존 /interview로 개발 스펙을 작성하면 됩니다."

FAIL인 경우: "Critical N개를 해소한 후 다시 /spec-reviewer를 실행해주세요. 기획팀에 전달할 질문 목록이 specs/{feature-slug}-review.md에 있습니다."

재검증(Re-review) 프로토콜: FAIL 후 재실행 시, 이전 리뷰 파일(specs/{feature-slug}-review.md)이 존재하면:

• 이전 Critical/Important 항목 중 해소된 항목만 재검증한다
• 변경된 섹션이 있으면 해당 섹션에 대해서만 체크리스트를 다시 적용한다
• 변경 없는 섹션은 이전 판정을 유지한다
• 전체 재검증(full re-review)은 필요하지 않다

Input 유형별 처리

Input 유형	처리 방식
specs/{feature}-spec.md 존재	자동으로 읽고 검증
같은 세션에서 spec-generator 완료	컨텍스트에서 직접 활용
사용자가 기존 기획서 제공 (비구조화)	Phase 1에서 템플릿 매핑 후 검증
사용자가 파일 경로 제공	Read로 파일 읽고 검증
Input 없이 실행	"어떤 기획서를 리뷰할까요?" 질문

Common Mistakes

Mistake	Fix
기술 용어로 질문 작성	기획팀이 답할 수 있는 비즈니스 언어로
모든 항목을 Critical로 분류	분류 기준 엄격히 적용 — Critical은 "개발 불가"일 때만
도메인 분석 없이 체크리스트만 기계적 적용	도메인 맥락을 이해하고 구체적 시나리오로 질문
질문만 나열하고 "왜 필요한지" 미설명	각 질문에 필요 이유 한 줄 추가
specs/ 외 경로에 저장	항상 specs/{feature-slug}-review.md
"해당없음" 섹션에 질문 생성	해당없음으로 판정한 섹션은 검증 건너뜀
[추정] 항목을 무시	[추정]은 자동 Important 이상 분류

Red Flags — STOP and Reassess

• 기획서를 읽지 않고 리뷰 시작
• 체크리스트 14개를 모두 Critical로 판정
• 기획서에 없는 기능을 임의로 추가하여 "누락"으로 판정
• 개발 구현 방식에 대해 의견 제시 (리뷰어는 "무엇"의 빈틈을 찾는 것이지, "어떻게"를 말하지 않는다)
• 질문이 20개 이상인데 줄이지 않음
• PASS/FAIL 판정 없이 리뷰 종료