| name | create-spec |
| description | 제품 기획부터 기술 설계, 디자인까지 3종 문서를 한번에 생성하는 스킬. PRD(기획서), TECHNICAL(기술문서), DESIGN(디자인문서)을 이것만 보고 개발을 완료할 수 있는 수준으로 작성한다. stitch MCP로 실제 스크린을 생성하고 디자인 문서에 포함한다. 사용자가 "PRD 써줘", "기획서 만들어줘", "스펙 문서", "create-spec", "제품 문서", "기술 문서 작성" 등을 말하면 반드시 이 스킬을 사용할 것. 새 프로젝트 시작, 기능 기획, MVP 설계 시에도 트리거. |
| allowed-tools | ["Read","Write","AskUserQuestion"] |
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으로 묻는다:
- 무엇을 만드는가? — 서비스 한줄 설명
대화 컨텍스트에서 이미 파악된 정보는 재질문하지 않는다.
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 구조
# [서비스명] 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 매핑.
기술 문서 구조
# [서비스명] 기술 설계서
## 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 호출은 서브에이전트에서 권한 거부될 수 있다.
반드시 다음 순서로 시도:
- 먼저 stitch 호출 시도 —
mcp__stitch__create_project 호출
- 성공하면 → 그대로 Phase 4 진행
- 권한 거부/에러 시 → DESIGN.md에 텍스트 명세만 작성하고, 사용자에게 안내:
"stitch 스크린 생성이 차단되었습니다. 메인 대화에서
/create-spec stitch로 스크린을 생성해주세요."
이 스킬이 서브에이전트로 실행될 때: Phase 1-3 문서를 먼저 완성하고, Phase 4에서 stitch 호출을 시도한다. 실패하면 DESIGN.md를 텍스트 명세로 완성한 뒤 메인 Claude에게 stitch 생성을 위임한다.
이 스킬이 메인 대화에서 실행될 때: stitch 호출이 정상 작동하므로 그대로 진행.
디자인 문서 생성 순서
- stitch 프로젝트 생성:
mcp__stitch__create_project로 프로젝트 생성
- 디자인 시스템 확인:
mcp__stitch__list_design_systems로 사용 가능한 디자인 시스템 확인
- 스크린 생성: PRD의 각 핵심 화면에 대해
mcp__stitch__generate_screen_from_text로 스크린 생성
- 플랫폼에 맞는 deviceType 설정 (DESKTOP/MOBILE/TABLET)
- PRD의 기능 명세를 반영한 상세 프롬프트 작성
- 정상 상태 + 예외 상태(빈 데이터, 에러, 로딩) 각각 생성
- 스크린 확인:
mcp__stitch__get_screen으로 결과 확인
- 필요시 수정:
mcp__stitch__edit_screens로 피드백 반영
디자인 문서 구조
# [서비스명] 디자인 문서
## 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. 사용자 판단이 필요한 이슈 질문
사용자 판단이 필요한 항목이 있으면:
- AskUserQuestion으로 질문 (한번에 모아서, 최대 4개)
- 답변 받으면 3개 문서 모두에 반영 — 하나의 답변이 여러 문서에 영향 줄 수 있음
6-3. ⚠️ 계속 여부 확인 (필수 — 절대 생략 불가)
질문 유무와 관계없이, 이 단계는 항상 실행한다.
AskUserQuestion으로 아래를 반드시 호출한다:
질문: "검증 라운드 N 완료. 계속 검증할까요?"
옵션:
- "예, 한 번 더 검토해" → Phase 5로 돌아가서 재검증
- "아니오, 문서 완성" → Phase 7로 진행
이 AskUserQuestion을 호출하지 않고 Phase 7로 넘어가는 것은 금지.
사용자가 직접 "완료"를 선택해야만 Phase 7로 진행할 수 있다.
질문 기준
- 질문해야 하는 것: 비즈니스 결정 (기능 범위, 우선순위, 수익 모델 세부), 유저 시나리오 모호한 부분, 기술 제약 미확인
- 질문하지 않는 것: 기술적으로 판단 가능한 것 (최적의 DB 인덱스, API 응답 형식 등)은 직접 결정
Phase 7: 최종 산출물 확인
모든 검증이 통과되면:
- 3개 파일이
spec-docs/에 저장되었는지 확인
- 각 문서의 목차를 사용자에게 보여줌
- stitch 프로젝트 링크 공유
- "문서 작성 완료. 이것만 보고 개발 시작 가능합니다." 안내
주의사항
- 실제 API 규격: 외부 API를 사용하면 반드시 공식 문서를 확인(context7 MCP 또는 웹 검색)해서 실제 요청/응답 형식을 반영한다. 추측으로 API 규격을 쓰면 안 된다.
- stitch 스크린은 실제 생성: 디자인 문서에 "이런 화면이 필요합니다" 텍스트만 쓰지 않는다. stitch MCP로 실제 스크린을 생성하고 ID를 기록한다.
- 예외 케이스 누락 금지: 정상 동작만 기술하는 것은 절반만 한 것이다. 에러, 빈 상태, 로딩, 권한 없음 등을 반드시 포함.
- 문서 간 동기화: 하나의 문서를 수정하면 나머지 2개에도 영향이 없는지 확인하고 반영.
