onejaejae/spec-generator

Spec Generator

구조화된 요구사항을 7개 섹션의 기획서로 변환한다. 빈 섹션은 도메인 기반 초안을 채우되, [추정] 마크를 붙여 reviewer가 잡을 수 있게 한다.

When to Use

• 요구사항이 정리되어 있고, 기획서 문서를 만들어야 할 때
• spec-interview 산출물(specs/{feature}-requirements.md)을 기획서로 변환할 때
• 기존 회의록/메모에서 기획서를 생성하고 싶을 때

Do NOT use when:

• 요구사항이 모호하고 정리가 안 된 상태 → spec-interview 먼저
• 이미 완성된 기획서를 검증하고 싶을 때 → spec-reviewer 사용
• 개발 스펙을 작성하고 싶을 때 → interview Skill 사용

Quick Reference

| Phase | Action | Key Rule | |-------|--------|----------| | 1. Input 분석 | 요구사항 파싱 + 기존 문서 스캔 | 있는 정보와 없는 정보를 구분 | | 2. 초안 생성 | 7개 섹션 채우기 | 빈 섹션은 [추정]으로 채움 | | 3. 사용자 확인 | 섹션별 리뷰 요청 | 추정 항목 집중 확인 | | 4. 기획서 출력 | specs/{feature}-spec.md | 항상 이 경로 |

CRITICAL: AskUserQuestion 턴 분리 규칙

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

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

필수 절차:

1. Phase 1 (Input 분석 + 정보 맵핑)을 수행한다
2. 정보 맵핑 결과를 텍스트로 출력한다
3. 반드시 STOP하고 사용자 응답을 기다린다
4. 사용자가 응답한 다음 턴에서 AskUserQuestion으로 Phase 1.5/3을 시작한다

이 규칙을 어기면 사용자가 질문을 볼 수 없고, 확인 절차가 진행되지 않습니다.

핵심 원칙

1. 비기술 언어 유지. 기획팀이 읽고 확인할 수 있는 언어로 작성한다. 개발 용어 사용 금지.

2. [추정]은 반드시 표시한다. AI가 도메인 지식으로 채운 내용에는 [추정] 마크를 붙인다. 사용자가 확인하지 않은 추정은 spec-reviewer가 검출할 수 있게 유지한다.

3. 없는 정보를 만들어내지 않는다. 추정 가능한 범위(도메인 상식)는 [추정]으로 채우되, 비즈니스 결정이 필요한 항목은 빈칸으로 두고 사용자에게 질문한다.

비즈니스 결정 vs 도메인 상식 구분 기준:

| 도메인 상식 ([추정] 가능) | 비즈니스 결정 (질문 필수) | |---|---| | 업계 표준 UX 패턴 (좋아요 토글, 목록 페이지네이션) | 수익/과금 관련 결정 | | 일반적 데이터 구조 (생성일시, 수정일시 필드) | 정책/규칙 (본인 글 좋아요 허용 여부) | | 보편적 예외 (네트워크 오류, 중복 요청) | 브랜딩/톤 관련 결정 | | 기본 권한 구조 (로그인 필요 여부) | 범위 결정 (v1에 뭘 넣을지) | | 표준 상태 흐름 (읽음/안읽음) | 알림/연동 대상 결정 | | 기본 장애 응답 (재시도 안내 메시지, 오류 표시) | 장애 복구 정책 (재시도 횟수, 폴백 동작, 보상 처리) |

Protocol

Input 유형 판단은 Phase 1 시작 전에 수행한다. 사용자가 input을 제공했는지 먼저 확인하고, 없으면 "어떤 기능의 기획서를 작성할까요?"를 텍스트로 출력한 뒤 STOP한다. 사용자의 다음 턴 응답을 받은 후 Phase 1로 진입한다.

Phase 1: Input 분석

1. 요구사항 파일 확인:

   • specs/{feature}-requirements.md 존재 여부 확인 (Glob)
   • 같은 세션에서 spec-interview가 실행되었다면 해당 컨텍스트 활용
   • 사용자가 직접 제공한 텍스트/파일도 가능
   • 요구사항 파일이 없고 텍스트만 제공된 경우, slug는 사용자에게 "이 기능의 영문 이름을 정해주세요 (예: user-like, notification)" 로 확인

2. 기존 관련 문서 스캔:

   • specs/ 폴더에서 관련 기능의 기존 기획서/요구사항 스캔 (Glob/Read)
   • 중복이나 의존 관계 파악

3. 정보 맵핑: 요구사항에서 7개 섹션에 매핑 가능한 정보를 분류:

   | 섹션 | 정보 있음 | 정보 없음 (채워야 함) | |------|----------|---------------------|

   이 매핑 결과를 사용자에게 간략히 공유한다: "요구사항에서 [N개 섹션]은 충분히 커버됩니다. [M개 섹션]은 추정으로 채우거나 확인이 필요합니다."

Phase 1.5: 미결 사항 처리

요구사항에 "미결 사항"이 있는 경우, Phase 2 진입 전에 처리한다:

• 각 미결 사항에 대해 AskUserQuestion: "요구사항에서 미결이었던 [항목]은 결정되었나요?"
• 결정됨 → 해당 섹션에 반영
• 여전히 미결 → 기획서 하단 "미결 사항" 섹션에 명시적으로 기록하고, 해당 섹션은 빈칸으로 둔다 ([추정]으로 채우지 않는다)
• 처리 후에도 미결로 남은 항목이 3개 이상이면 "spec-interview 재실행을 권장합니다" 안내

Phase 2: 초안 생성

7개 섹션을 순서대로 채운다. 각 섹션의 작성 규칙:

섹션 1. 배경

• 요구사항의 "배경" 또는 문맥에서 추출
• 현재 문제와 해결 필요성을 1-2문단으로

섹션 2. 사용자와 목표

• 사용자 유형별 목표와 주요 행동을 표로 정리
• 요구사항에서 명시적으로 나오지 않은 사용자 유형이 있으면 [추정]으로 추가

섹션 3. 사용 시나리오

• 정상 흐름: 단계별로 "사용자가 ~ 한다 → 시스템이 ~ 한다" 형태
• 예외 상황: 표 형태 (상황 | 사용자에게 보이는 것 | 시스템 동작)
• 요구사항에서 예외가 없으면 도메인 기반으로 [추정] 예외 추가

섹션 4. 데이터와 상태

• 주요 데이터: 항목 | 설명 | 필수 여부 | 제약
• 상태 변화: 현재 상태 | 이벤트 | 다음 상태 | 부수 효과
• spec-interview가 발견한 상태와 전이를 표로 구조화하는 것이 이 섹션의 역할이다. 누락된 조합의 완전성 검증은 spec-reviewer가 수행한다.
• 해당하지 않으면 "상태 변화 없음" 명시

섹션 5. 연결되는 시스템

• 시스템 | 연동 내용 | 방향 (보내기/받기/양방향)
• 해당하지 않으면 "외부 연동 없음" 명시

섹션 6. 권한

• 역할 | 할 수 있는 것 | 할 수 없는 것
• 요구사항에서 역할이 언급되지 않았으면 [추정]으로 기본 역할 추가

섹션 7. 범위와 성공 기준

• 이번에 하는 것 / 안 하는 것 / 성공 기준
• 성공 기준은 가능한 한 테스트 가능한 형태로
• 비기능 요구사항: 동시 사용자 수, 기대 반응 속도, 보안/개인정보 등 interview에서 수집된 NFR을 이 섹션 하위에 기록
• 해당하지 않으면 "비기능 요구사항 없음" 명시

Phase 3: 사용자 확인

[추정] 항목이 있는 경우: AskUserQuestion으로 [추정] 항목들을 묶어서 확인한다.

• 2-3개씩 묶어서 질문 (한 번에 너무 많이 묻지 않는다)
• 각 [추정]에 대해: 맞다 / 수정 필요 / 삭제 옵션 제공

[추정] 마크 제거 규칙:

• PM이 "맞다"고 명시적으로 확인 → [추정] 마크를 제거하고 확정 내용으로 기록
• PM이 "글쎄요", "일단 그렇게 해요" 등 소극적 동의 → [추정] 마크 유지 (reviewer가 재확인)
• PM이 수정 → 수정 내용으로 교체, [추정] 마크 제거

[추정] 단계별 대응:

| [추정] 개수 | 대응 | |------------|------| | 0~2개 | 정상 진행. Phase 3에서 각 [추정] 개별 확인 | | 3~4개 | 경고: "[추정]이 N개입니다. 요구사항이 충분하지 않을 수 있습니다. spec-interview를 먼저 실행하시겠습니까?" 사용자가 "그냥 진행"하면 Phase 3에서 각 [추정] 확인 후 Phase 4로 | | 5개 이상 | 강력 권고: "요구사항이 부족합니다. spec-interview를 먼저 실행하는 것을 권장합니다." 사용자가 그래도 진행하면 Phase 3 진행하되, 출력 파일에 "요구사항 보완 필요" 경고 표시 |

[추정] 항목이 없는 경우: 전체 기획서를 간략히 요약하고 "이대로 작성하겠습니다. 수정할 부분이 있으시면 말씀해주세요" 확인.

사용자가 수정을 요청하면: 수정 내용을 Phase 2의 해당 섹션에 반영하고, 수정된 부분만 다시 Phase 3에서 확인한다. 수정-확인은 사용자가 "좋다"고 할 때까지 반복하되, 3회 이상 반복되면 "나머지는 spec-reviewer에서 잡겠습니다. 우선 출력할까요?" 제안.

Phase 4: 기획서 출력

Write to specs/{feature-slug}-spec.md. Always this path.

slug 규칙: 영문 소문자, 하이픈 구분. 요구사항 파일의 slug와 동일하게 맞춘다.

# {기능명} — 기획서

## 1. 배경
왜 이 기능이 필요한가. 현재 어떤 문제가 있는가.

## 2. 사용자와 목표
| 사용자 유형 | 목표 | 주요 행동 |
|------------|------|----------|

## 3. 사용 시나리오

### 정상 흐름
1. 사용자가 ~ 한다
2. 시스템이 ~ 한다
3. 결과로 ~ 가 보인다

### 예외 상황
| 상황 | 사용자에게 보이는 것 | 시스템 동작 |
|------|---------------------|------------|

## 4. 데이터와 상태

### 주요 데이터
| 항목 | 설명 | 필수 여부 | 제약 |
|------|------|----------|------|

### 상태 변화
| 현재 상태 | 이벤트 | 다음 상태 | 부수 효과 |
|----------|--------|----------|----------|

(해당하지 않으면 "상태 변화 없음" 명시)

## 5. 연결되는 시스템
| 시스템 | 연동 내용 | 방향 |
|--------|----------|------|

(해당하지 않으면 "외부 연동 없음" 명시)

## 6. 권한
| 역할 | 할 수 있는 것 | 할 수 없는 것 |
|------|-------------|--------------|

## 7. 범위와 성공 기준

### 이번에 하는 것
- ...

### 이번에 안 하는 것
- ...

### 성공 기준
- ...

### 비기능 요구사항
- 동시 사용자 수:
- 기대 반응 속도:
- 보안/개인정보:

(해당하지 않으면 "비기능 요구사항 없음" 명시)

Tell the user the file path after writing.

출력 후 안내: "기획서가 작성되었습니다: specs/{feature-slug}-spec.md 다음 단계로 /spec-reviewer를 실행하면 개발 관점에서 누락 항목을 검증할 수 있습니다."

Backflow 안내: Phase 3에서 PM이 새로운 요구사항을 추가하거나 기존 요구사항을 변경한 경우, 기획서 출력 후 다음을 안내한다: "Phase 3에서 추가/변경된 내용이 있습니다. 요구사항 파일(specs/{feature-slug}-requirements.md)도 업데이트하시겠습니까?" 사용자가 동의하면 해당 파일의 관련 섹션을 업데이트한다.

Input 유형별 처리

| Input 유형 | 처리 방식 | |-----------|----------| | specs/{feature}-requirements.md 존재 | 자동으로 읽고 매핑 | | 같은 세션에서 spec-interview 완료 | 컨텍스트에서 직접 활용 | | 사용자가 텍스트 붙여넣기 | 텍스트에서 정보 추출 후 매핑 | | 사용자가 파일 경로 제공 | Read로 파일 읽고 매핑 | | Input 없이 실행 | "어떤 기능의 기획서를 작성할까요?"를 텍스트로 출력하고 STOP, 다음 턴 응답을 input으로 사용 |

Common Mistakes

| Mistake | Fix | |---------|-----| | 기술 용어 사용 (API, DB 등) | 비기술 언어로 변환 | | [추정]을 마크 없이 삽입 | 반드시 [추정] 표시 | | 요구사항에 없는 비즈니스 결정을 추정으로 채움 | 비즈니스 결정은 질문, 도메인 상식만 추정 | | 모든 섹션을 한 번에 확인 요청 | [추정] 항목만 2-3개씩 묶어서 확인 | | specs/ 외 경로에 저장 | 항상 specs/{feature-slug}-spec.md | | 요구사항 파일의 slug와 다른 slug 사용 | 동일한 slug 유지 (-requirements.md → -spec.md) |

Red Flags — STOP and Reassess

• [추정]이 5개 이상인데 사용자에게 경고 없이 진행
• 요구사항 없이 기획서를 바로 작성 시작
• 기술 용어로 기획서 작성
• 사용자 확인 없이 기획서 출력
• Phase 1의 정보 맵핑을 건너뜀