Spec Generator

개요

PM 수준의 기획 문서 3종(requirements.md, design.md, tasks.md)을 생성합니다.
Kiro 스타일의 체계적인 문서로, 요구사항 추적과 안전한 개발이 가능합니다.

워크플로우

Phase 1: 요구사항 인터뷰

1. 기능 이름과 목적 확인
2. 주요 사용자(Actor) 파악
3. 핵심 유스케이스 정리
4. 엣지케이스/제약사항 확인
5. 다음 질문 (1~2개만):
   • "추가로 필요한 기능이 있나요?"
   • "특별히 고려할 제약사항이 있나요?"

Phase 2: 기존 자산 분석 (필수)

문서 생성 전 반드시 확인:

1. 기존 기능 확인: 비슷한 기능이 이미 있는가?
2. 재사용 가능 자산: 컴포넌트, 유틸, 훅 등
3. 현재 패턴 분석: tRPC 라우터, Prisma 스키마, 폴더 구조

Phase 3: 문서 생성

docs/specs/{feature-name}/ 폴더에 3개 파일 생성:

1. requirements.md - 요구사항 + 수락 기준
2. design.md - 설계 + 코드 예시
3. tasks.md - 작업 체크리스트

---

설계 원칙 (Non-Negotiable)

1. 기존 자산 우선

우선순위:
1. 기존 기능 그대로 사용
2. 기존 기능 확장 (extends)
3. 기존 패턴 따라 새로 생성
4. 새로운 패턴 도입 (마지막 수단, 근거 필요)

design.md에 반드시 포함:

• "재사용 가능한 기존 자산" 섹션
• 새로 만드는 경우 "왜 새로 만들어야 하는가?" 근거

2. 점진적 변경 (Breaking Change 금지)

❌ 위험: 기존 컬럼 삭제/변경
✅ 안전: 새 컬럼 추가 → 병행 운영 → 검증 → 레거시 제거

• 레거시 호환성 유지
• 마이그레이션은 항상 되돌릴 수 있어야 함
• 레거시 제거는 별도 Phase로 분리

3. 패턴 준수

• 프로젝트의 기존 패턴 따르기 (tRPC, Prisma, 폴더 구조)
• 새로운 패턴 도입 시 명시적 근거 필요

---

작업 순서 원칙 (안전 우선)

기본 순서: FE → BE

1. [FE] UI 개발 (Mock 데이터)
   → 화면 보면서 검증
   → 잘못되면 쉽게 삭제

2. 체크포인트 - UI 검증
   → "이 화면으로 가자" 확정

3. [BE] API 개발
   → UI 확정 후 진행

4. [BE] DB 마이그레이션
   → 가장 마지막 (되돌리기 어려움)

5. [FE] Mock → 실제 연결
   → 마무리

이유

• DB 변경은 되돌리기 어려움
• UI 먼저 확정 → 안전
• 체크포인트에서 검증 후 다음 단계

---

문서 형식

requirements.md

필수 섹션:

• 소개: 목적 한 줄 요약
• 용어집: 도메인 용어 정의
• 요구사항: 번호 + 사용자 스토리 + 수락 기준

수락 기준 형식:

1. THE System SHALL ...
2. WHEN ... THEN THE System SHALL ...

design.md

필수 섹션:

• 개요: 설계 요약
• 아키텍처: ASCII 다이어그램
• 기존 자산 분석: 재사용 목록 + 근거
• 컴포넌트 및 인터페이스: 실제 구현 가능한 코드 예시
• 데이터 모델: Prisma 스키마 (프로젝트 스택에 맞게)
• 마이그레이션 전략: 점진적, 되돌릴 수 있게

tasks.md

필수 섹션:

• 개요: 작업 요약
• 작업 목록:
  • 대분류에 [FE]/[BE] 태그
  • 소분류에 [필수]/[선택] 구분 (* 표시 = 선택)
  • 요구사항 역추적 (_요구사항: 1.1, 2.3_)
• 체크포인트: 검증 단계
• 참고사항: 선택 작업 설명

---

작업 형식 예시

## 작업

- [ ] 1. UI 개발 [FE]
  - [ ] 1.1 컴포넌트 생성 [필수]
    - 설명
    - _요구사항: 1.1, 1.2_
  - [ ]* 1.2 스토리북 작성 [선택]
    - _요구사항: 1.1_

- [ ] 2. 체크포인트 - UI 검증
  - 화면 확인 후 다음 단계 진행

- [ ] 3. API 개발 [BE]
  - [ ] 3.1 tRPC 라우터 생성 [필수]
    - _요구사항: 2.1, 2.2_
  - [ ]* 3.2 단위 테스트 작성 [선택]

- [ ] 4. DB 마이그레이션 [BE]
  - [ ] 4.1 새 스키마 추가 (기존 유지) [필수]
    - _요구사항: 3.1_
  - [ ] 4.2 데이터 마이그레이션 [필수]
    - _요구사항: 3.2_

- [ ] 5. 연결 및 마무리 [FE]
  - [ ] 5.1 Mock → 실제 API 연결 [필수]
  - [ ]* 5.2 E2E 테스트 [선택]

- [ ] 6. 최종 체크포인트
  - 모든 기능 동작 확인

## 참고사항

- `*` 표시된 작업은 선택 사항 (MVP에서 건너뛸 수 있음)
- 체크포인트에서 검증 후 다음 단계 진행
- 레거시 제거는 별도 Phase로 분리

---

사용 예시

좋은 요청

"팬들이 다른 팬의 덕질 일정을 볼 수 있는 '캘린더 공유' 기능 기획해줘.
- 공개/비공개 설정 가능
- 팔로우한 사람만 볼 수 있는 옵션"

결과

docs/specs/calendar-share/
├── requirements.md  (8개 요구사항)
├── design.md        (기존 SavedCalendar 확장 설계)
└── tasks.md         (12개 작업, FE→BE 순서)

피해야 할 요청

❌ "알림 기능 만들어줘"  ← 너무 모호
❌ "푸시 알림 코드 짜줘"  ← 기획 없이 바로 구현 (concise-planning 사용)

---

참조 예시

• docs/specs/permission-system-redesign/ - Kiro 스타일 기획 문서