onejaejae/spec-reviewer

Spec Reviewer

기획서의 완성도를 개발 관점에서 검증한다. 11개 체크리스트 기반으로 누락 항목을 검출하고, 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. 커버리지 체크 | 7개 섹션 대비 빈/약한 섹션 식별 | 정량적 매트릭스 | | 3. 갭 분석 | 11개 체크리스트 기반 누락 검출 | 도메인 기반 추론 | | 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. 템플릿 매핑: 입력이 7개 섹션 구조가 아닌 경우, 내용을 7개 섹션에 매핑:

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

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

3. [추정] 마크 수집: 기획서에 [추정] 마크가 있으면 별도로 수집한다. 이들은 자동으로 Important 이상으로 분류된다.

   • 주의: spec-generator에서 PM이 확인하여 [추정] 마크가 제거된 항목은 확정 내용으로 취급한다. reviewer는 남아있는 [추정]만 플래그한다.

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

   • 미결 사항이 이번 범위(scope) 내 기능에 영향을 미치는 경우 → Important로 분류
   • 미결 사항이 이번 범위 밖이거나 v2 이후 기능에 해당 → Nice-to-have로 분류
   • 미결 사항은 "알려진 미결"로서, 누락 항목과 구분하여 별도 섹션에 기록한다

Phase 2: 커버리지 체크

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

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

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

• [추정] 항목이 섹션 내용의 30% 이상이면 → 최대 "약함"
• [추정] 항목이 섹션 내용의 30% 미만이면 → "충분" 가능하되, 비고에 [추정] 항목을 명시

커버리지 매트릭스:

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

Phase 3: 갭 분석

11개 검증 체크리스트:

| # | 검증 항목 | 검증 질문 | Critical 조건 | |---|----------|----------|--------------| | 1 | 암묵적 가정 | 당연하다고 생각해서 안 쓴 비즈니스 규칙은 없는가? | 핵심 흐름에 영향 | | 2 | 에러/실패 시나리오 | 모든 정상 흐름에 대응하는 실패 시나리오가 있는가? | 정상 흐름 대비 예외 커버율 50% 미만 | | 3 | 상태 전이 완전성 | 모든 (현재상태, 이벤트) 조합이 정의되었는가? spec-generator가 구조화한 상태 표의 완전성을 검증한다. | 상태가 있는데 전이 미정의 | | 4 | 데이터 제약 | 모든 데이터 항목에 필수/선택, 최대길이, 형식이 있는가? | 핵심 데이터 제약 누락 | | 5 | 권한 모델 | 각 기능에 대해 누가 할 수 있고/없는지 명시되었는가? | 다중 역할인데 권한 미정의 | | 6 | 연동 계약 | 외부 시스템과의 인터페이스가 충분히 기술되었는가? | 연동 있는데 장애 시 동작 미정의 | | 7 | 목록 동작 | 목록이 있다면 빈 상태/대량/정렬/검색이 정의되었는가? | 목록 UI인데 빈 상태 미정의 | | 8 | 입력 유효성 | 사용자 입력 필드의 허용 범위/형식이 정의되었는가? | 핵심 입력 필드 유효성 누락 | | 9 | 범위 경계 | "안 하는 것"이 명시적으로 정의되었는가? | 범위가 전혀 정의되지 않음 | | 10 | 성공 기준 | 완성의 정의가 테스트 가능한 형태인가? | 성공 기준 없음 | | 11 | 비기능 요구사항 | 동시 사용자 수, 응답 속도, 보안/개인정보 요건이 정의되었는가? | 핵심 비기능 요건 누락 (예: 결제 기능인데 보안 요건 없음) |

갭 분석 방법:

• 각 항목을 순서대로 검증
• 도메인 지식을 활용하여 기획서에서 빠진 구체적 시나리오를 제시
  • 예: "결제 기능인데 '결제 중 네트워크 오류' 시나리오가 없습니다"
  • 예: "'주문' 상태에서 '취소 요청'이 들어오면 어떻게 되는지 정의되지 않았습니다"
• [추정] 마크가 붙은 항목의 분류 규칙:
  • [추정]이 체크리스트 Critical 조건 항목(핵심 흐름, 핵심 데이터, 범위 등)에 해당 → 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. ...

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

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

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

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

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

## 미결 사항 현황
- [미결 내용]: [이번 범위에 영향 여부] → [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

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