# Create Spec

> 제품 기획부터 기술 설계, 디자인까지 3종 문서를 한번에 생성하는 스킬. PRD(기획서), TECHNICAL(기술문서), DESIGN(디자인문서)을 이것만 보고 개발을 완료할 수 있는 수준으로 작성한다. stitch MCP로 실제 스크린을 생성하고 디자인 문서에 포함한다. 사용자가 "PRD 써줘", "기획서 만들어줘", "스펙 문서", "create-spec", "제품 문서", "기술 문서 작성" 등을 말하면 반드시 이 스킬을 사용할 것. 새 프로젝트 시작, 기능 기획, MVP 설계 시에도 트리거.

- Skill: `kangraemin/create-spec` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add kangraemin/create-spec`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kangraemin/create-spec/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: kangraemin (https://skillmd.com/u/kangraemin)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kangraemin/create-spec

---


# create-spec

제품의 기획 → 기술 설계 → 디자인을 한 사이클로 돌려서 3개 문서를 생성한다.
이 문서들만 있으면 개발자가 추가 질문 없이 개발을 완료할 수 있어야 한다.

## 산출물

프로젝트 루트 `spec-docs/` 디렉토리에 3개 파일 생성:

```
spec-docs/
├── PRD.md          # 제품 기획서
├── TECHNICAL.md    # 기술 설계서
└── DESIGN.md       # 디자인 문서 (stitch 스크린 포함)
```

## 전체 흐름

```
Phase 1: 컨텍스트 수집
    ↓
Phase 2: PRD 작성
    ↓
Phase 3: 기술 문서 작성
    ↓
Phase 4: 디자인 문서 작성 (stitch 스크린 생성)
    ↓
Phase 5: 크로스 검증 — 3개 문서 간 불일치/누락 검사
    ↓
Phase 6: 질문 루프 — 미결 이슈를 사용자에게 묻고, 답변을 3개 문서 모두에 반영
    ↓  ← AskUserQuestion("계속 검증할까요?") 항상 호출 — 사용자가 "완료"를 누를 때만 Phase 7로
    ↓  (사용자가 "완료"를 선택할 때까지 Phase 5-6 반복, 최대 10회)
Phase 7: 최종 산출물 확인
```

---

## Phase 1: 컨텍스트 수집 & 기획 탐색

### Step 1A: 기본 정보 수집

AskUserQuestion으로 묻는다:
1. **무엇을 만드는가?** — 서비스 한줄 설명

대화 컨텍스트에서 이미 파악된 정보는 재질문하지 않는다.

### Step 1B: ralph-x로 기획 질문 탐색 위임

`Skill("ralph-x")`를 아래 args로 호출한다:

```
{user_brief}에 대한 기획 질문 탐색.
각 iteration마다: 지금까지 수집된 질문을 log.md에서 읽고,
새 각도의 기획 질문(타겟유저/핵심기능/수익모델/플랫폼/기술제약/예외케이스/리스크 등)을
탐색해서 log.md에 append한다.
이미 수집된 질문과 중복이면 스킵.
새 질문이 없으면 log.md에 EXPLORE_DONE을 기록한다.
```

⚠️ **ralph-x가 완전히 자기 흐름을 처리한다. create-spec은 절대 개입하지 않는다.**
- ralph-x가 Step 2(Pipeline), Step 2-B(Model), Step 3(Iterations), Step 4(Checklist) 질문을 **직접, 하나씩** 사용자에게 묻는다.
- create-spec은 이 단계에서 AskUserQuestion을 호출하거나 ralph-x 대신 질문을 묻는 행위를 **절대 금지**.
- ralph-x가 run.sh 생성 + 백그라운드 실행까지 완료한 후, ralph-x가 출력한 RUN_DIR을 확인하고 Step 1C로 이어간다.

Ralph-x가 완료되면 출력된 RUN_DIR/log.md에 수집된 질문들이 누적되어 있다.

### Step 1C: 수집된 질문을 사용자에게 일괄 질문

ralph-x가 출력한 RUN_DIR에서 `log.md`를 Read 툴로 읽는다.
수집된 질문 목록을 파싱한다.
AskUserQuestion으로 **한번에** 모든 질문을 묻는다. (질문이 5개 초과 시 2번에 나눠 호출)

답변을 컨텍스트로 정리한 뒤 Phase 2로 진행.

---

## Phase 2: PRD 작성 (`spec-docs/PRD.md`)

이 문서만 보고 "뭘 만들어야 하는지" 100% 이해할 수 있어야 한다.
기획자가 개발자에게 전달하는 문서라고 생각하고 작성한다.

### PRD 구조

```markdown
# [서비스명] PRD

## 1. 개요
- 서비스 한줄 설명
- 해결하려는 문제
- 타겟 유저 페르소나 (구체적으로 — 나이, 상황, 니즈)

## 2. 핵심 가치 제안
- 왜 이걸 써야 하는지 (기존 대안 대비)

## 3. 기능 명세
각 기능마다:
### 3.N [기능명]
- **설명**: 무엇을 하는 기능인가
- **유저 시나리오**: 유저가 어떤 흐름으로 사용하는가 (step by step)
- **입력**: 유저가 무엇을 제공하는가
- **출력**: 무엇이 보여지는가
- **비즈니스 규칙**: 조건, 제한, 정렬 기준 등
- **예외 케이스**: 
  - 데이터 없을 때
  - 입력 오류 시
  - 네트워크 에러 시
  - 권한 없을 때
  - 로딩 중일 때
- **우선순위**: P0(필수) / P1(중요) / P2(있으면 좋음)

## 4. 유저 플로우
전체 사용자 여정을 텍스트로 기술.
진��� → 핵심 액션 → 이탈/반복 포인트.

## 5. 데이터 모델 (개념 수준)
어떤 데이터가 필요한지, 관계는 어떤지.
테이블명까지는 안 써도 되지만, "유튜버는 여러 영상을 갖고, 
영상은 여러 맛집을 포함" 같은 관계는 명시.

## 6. 외부 의존성
- 사용하는 외부 API 목록
- 각 API의 용도, 제한사항, 비용
- API 장애 시 대응 방안

## 7. 수익 모델
- 수익 구조
- 과금 시점/단위

## 8. 성공 지표 (KPI)
- 핵심 지표 2-3개
- 측정 방법

## 9. MVP 범위
- MVP에 포함되는 것
- MVP에서 빠지는 것 (v2에서 할 것)
- 이유

## 10. 제약 사항 & 리스크
- 기술적 리스크
- 비즈니스 리스크
- 법적 리스크 (저작권, 개인정보 등)
```

### PRD 작성 원칙
- **구체적으로**: "검색 기능" 대신 "유저가 검색창에 유튜버명/지역명을 입력하면 자동완성 드롭다운이 표시되고, 선택 시 해당 결과로 필터링"
- **예외를 반드시**: 모든 기능에 "잘 안 될 때" 시나리오를 포함
- **수치를 넣어**: "빠르게" 대신 "3초 이내", "많이" 대신 "최대 50개"
- **왜를 설명**: 기능마다 왜 필요한지 한 줄

---

## Phase 3: 기술 문서 작성 (`spec-docs/TECHNICAL.md`)

이 문서만 보고 개발자가 코드를 짤 수 있어야 한다.
PRD의 모든 기능이 기술적으로 어떻게 구현되는지 1:1 매핑.

### 기술 문서 구조

```markdown
# [서비스명] 기술 설계서

## 1. 아키텍처 개요
- 시스템 구성도 (텍스트 다이어그램)
- 컴포넌트 간 통신 방식
- 배포 환경

## 2. 기술 스택
| 계층 | 기술 | 선택 이유 |
|------|------|----------|
| 프론트엔드 | ... | ... |
| 백엔드 | ... | ... |
| DB | ... | ... |
| 인프라 | ... | ... |

## 3. 데이터베이스 스키마
실제 SQL 또는 스키마 정의.
각 테이블/컬렉션마다:
- 필드명, 타입, nullable, 기본값
- 인덱스
- 관계 (FK)
- 제약조건

## 4. API 명세
각 엔드포인트마다:
### [METHOD] /api/v1/endpoint
- **설명**: 
- **인증**: 필요 여부
- **Request**:
  - Headers
  - Query Parameters (이름, 타입, 필수여부, 설명)
  - Body (JSON 예시)
- **Response**:
  - 성공 (200): JSON 예시
  - 에러 (400/401/404/500): JSON 예시 + 발생 조건
- **비즈니스 로직**: 내부에서 어떤 처리를 하는지
- **외부 API 호출**: 있으면 어떤 API를 어떻게 호출하는지

## 5. 외부 API 연동 상세
각 외부 API마다:
- 엔드포인트, 인증 방식
- 요청/응답 실제 예시 (실제 API 규격 기반)
- Rate limit, 비용
- 타임아웃, 재시도 정책
- 에러 코드별 처리 방법
- 장애 시 fallback

## 6. 핵심 로직 상세
복잡한 비즈니스 로직은 의사코드 또는 플로우로 설명.
- 입력 → 처리 단계 → 출력
- 분기 조건
- 에러 처리

## 7. 보안
- 인증/인가 방식
- API 키 관리
- CORS 설정
- 입력 검증
- SQL Injection / XSS 방지

## 8. 성능
- 캐싱 전략
- 페이지네이션
- 이미지/정적 파일 최적화
- DB 쿼리 최적화

## 9. 에러 처리 전략
- 글로벌 에러 핸들링
- 에러 코드 체계
- 유저에게 보여줄 메시지 vs 로그
- 모니터링/알림

## 10. 환경 변수
| 변수명 | 용도 | 예시 | 필수 |
|--------|------|------|------|

## 11. 디렉토리 구조
```
프로젝트/
├── ...
```

## 12. 배포
- 배포 플랫폼, 방법
- CI/CD (있으면)
- 환경 분리 (dev/staging/prod)
```

### 기술 문서 작성 원칙
- **실제 API 규격 반영**: 외부 API는 공식 문서의 실제 요청/응답 형식을 사용. 추측 금지.
- **코드 수준의 구체성**: "데이터를 저장한다" 대신 "Supabase의 restaurants 테이블에 INSERT하고, conflict 시 name+address 기준 UPSERT"
- **모든 에러 케이스**: 네트워크 타임아웃, API 장애, 잘못된 입력, 빈 결과 등
- **실행 가능한 예시**: curl 명령어, SQL 쿼리 등 바로 실행 가능한 형태

---

## Phase 4: 디자인 문서 작성 (`spec-docs/DESIGN.md`)

stitch MCP를 사용해서 실제 스크린을 생성하고, 디자인 문서에 포함한다.

### ⚠️ stitch MCP 실행 규칙

stitch MCP 호출은 **서브에이전트에서 권한 거부될 수 있다.**
반드시 다음 순서로 시도:

1. **먼저 stitch 호출 시도** — `mcp__stitch__create_project` 호출
2. **성공하면** → 그대로 Phase 4 진행
3. **권한 거부/에러 시** → DESIGN.md에 텍스트 명세만 작성하고, 사용자에게 안내:
   "stitch 스크린 생성이 차단되었습니다. 메인 대화에서 `/create-spec stitch`로 스크린을 생성해주세요."

**이 스킬이 서브에이전트로 실행될 때**: Phase 1-3 문서를 먼저 완성하고, Phase 4에서 stitch 호출을 시도한다. 실패하면 DESIGN.md를 텍스트 명세로 완성한 뒤 메인 Claude에게 stitch 생성을 위임한다.

**이 스킬이 메인 대화에서 실행될 때**: stitch 호출이 정상 작동하므로 그대로 진행.

### 디자인 문서 생성 순서

1. **stitch 프로젝트 생성**: `mcp__stitch__create_project`로 프로젝트 생성
2. **디자인 시스템 확인**: `mcp__stitch__list_design_systems`로 사용 가능한 디자인 시스템 확인
3. **스크린 생성**: PRD의 각 핵심 화면에 대해 `mcp__stitch__generate_screen_from_text`로 스크린 생성
   - 플랫폼에 맞는 deviceType 설정 (DESKTOP/MOBILE/TABLET)
   - PRD의 기능 명세를 반영한 상세 프롬프트 작성
   - 정상 상태 + 예외 상태(빈 데이터, 에러, 로딩) 각각 생성
4. **스크린 확인**: `mcp__stitch__get_screen`으로 결과 확인
5. **필요시 수정**: `mcp__stitch__edit_screens`로 피드백 반영

### 디자인 문서 구조

```markdown
# [서비스명] 디자인 문서

## 1. 디자인 원칙
- 시각적 방향성
- 톤앤매너
- 참고 서비스

## 2. 디자인 시스템
- 컬러 팔레트 (Primary, Secondary, Error, Success 등)
- 타이포그래피
- 간격/그리드 시스템
- 컴포넌트 목록

## 3. 화면 목록
| 화면 | 설명 | stitch 스크린 ID | 우선순위 |
|------|------|-----------------|---------|

## 4. 화면별 상세
각 화면마다:
### 4.N [화면명]
- **목적**: 이 화면이 왜 필요한가
- **진입 경로**: 어디서 이 화면으로 오는가
- **stitch 스크린**: 프로젝트 ID / 스크린 ID
- **레이아웃 설명**: 
  - 영역별 구성 요소
  - 인터랙션 (클릭, 호버, 스크롤 등)
- **상태별 디자인**:
  - 정상 (데이터 있음)
  - 빈 상태 (Empty State) — 데이터 없을 때
  - 로딩 상태 (Skeleton/Spinner)
  - 에러 상태 — 네트워크 에러, 서버 에러
- **반응형**: 데스크톱/모바일 차이점

## 5. 네비게이션 플로우
화면 간 이동 관계. 텍스트 다이어그램.

## 6. 인터랙션 정의
- 애니메이션/트랜지션
- 토스트/모달/바텀시트 동작
- 제스처 (모바일)
```

### 디자인 작성 원칙
- **모든 상태를 디자인**: 정상/빈/로딩/에러 — 4가지 상태 필수
- **stitch 스크린은 실제 생성**: 텍스트 설명만이 아니라 실제 stitch로 스크린을 만들어야 함
- **PRD 기능과 1:1 매핑**: PRD에 있는 기능이 디자인에 빠지면 안 됨

---

## Phase 5: 크로스 검증

3개 문서가 완성되면 아래를 점검한다:

### 5-1. PRD ↔ TECHNICAL 정합성
- PRD의 모든 기능이 TECHNICAL에 구현 방법이 있는가?
- TECHNICAL의 API가 PRD의 기능을 모두 커버하는가?
- PRD의 데이터 모델과 TECHNICAL의 DB 스키마가 일치하는가?
- PRD의 예외 케이스가 TECHNICAL의 에러 처리에 반영되었는가?

### 5-2. PRD ↔ DESIGN 정합성
- PRD의 모든 화면이 DESIGN에 있는가?
- PRD의 유저 플로우가 DESIGN의 네비게이션과 일치하는가?
- PRD의 예외 케이스가 DESIGN의 상태별 디자인에 있는가?

### 5-3. TECHNICAL ↔ DESIGN 정합성
- TECHNICAL의 API 응답이 DESIGN의 화면에 표시할 데이터와 일치하는가?
- TECHNICAL의 에러 코드가 DESIGN의 에러 상태와 매핑되는가?

### 5-4. 자체 완결성
- 이 문서들만 보고 개발자가 추가 질문 없이 개발 가능한가?
- 빠진 예외 케이스가 없는가?
- 모호한 표현("적절히", "빠르게", "등")이 없는가?

불일치/누락 발견 시 → 해당 문서 수정.

---

## Phase 6: 질문 루프

### 6-1. 미결 이슈 정리
Phase 5 검증 결과를 다음 형식으로 출력한다:
```
[검증 라운드 N]
- 발견된 이슈: M개
  1. (이슈 설명)
  2. (이슈 설명)
- 자체 해결: K개
- 사용자 판단 필요: J개
```

### 6-2. 사용자 판단이 필요한 이슈 질문
사용자 판단이 필요한 항목이 있으면:
1. AskUserQuestion으로 질문 (한번에 모아서, 최대 4개)
2. 답변 받으면 **3개 문서 모두에 반영** — 하나의 답변이 여러 문서에 영향 줄 수 있음

### 6-3. ⚠️ 계속 여부 확인 (필수 — 절대 생략 불가)
질문 유무와 관계없이, 이 단계는 **항상** 실행한다.
AskUserQuestion으로 아래를 반드시 호출한다:

```
질문: "검증 라운드 N 완료. 계속 검증할까요?"
옵션:
  - "예, 한 번 더 검토해" → Phase 5로 돌아가서 재검증
  - "아니오, 문서 완성" → Phase 7로 진행
```

**이 AskUserQuestion을 호출하지 않고 Phase 7로 넘어가는 것은 금지.**
사용자가 직접 "완료"를 선택해야만 Phase 7로 진행할 수 있다.

### 질문 기준
- **질문해야 하는 것**: 비즈니스 결정 (기능 범위, 우선순위, 수익 모델 세부), 유저 시나리오 모호한 부분, 기술 제약 미확인
- **질문하지 않는 것**: 기술적으로 판단 가능한 것 (최적의 DB 인덱스, API 응답 형식 등)은 직접 결정

---

## Phase 7: 최종 산출물 확인

모든 검증이 통과되면:

1. 3개 파일이 `spec-docs/`에 저장되었는지 확인
2. 각 문서의 목차를 사용자에게 보여줌
3. stitch 프로젝트 링크 공유
4. "문서 작성 완료. 이것만 보고 개발 시작 가능합니다." 안내

---

## 주의사항

- **실제 API 규격**: 외부 API를 사용하면 반드시 공식 문서를 확인(context7 MCP 또는 웹 검색)해서 실제 요청/응답 형식을 반영한다. 추측으로 API 규격을 쓰면 안 된다.
- **stitch 스크린은 실제 생성**: 디자인 문서에 "이런 화면이 필요합니다" 텍스트만 쓰지 않는다. stitch MCP로 실제 스크린을 생성하고 ID를 기록한다.
- **예외 케이스 누락 금지**: 정상 동작만 기술하는 것은 절반만 한 것이다. 에러, 빈 상태, 로딩, 권한 없음 등을 반드시 포함.
- **문서 간 동기화**: 하나의 문서를 수정하면 나머지 2개에도 영향이 없는지 확인하고 반영.