spec-create

name	spec-create
description	새 기능/작업의 스펙 문서를 specs/not-started/ 아래에 작성한다. 사용자가 "스펙 만들어줘", "스펙 작성", "spec-create", 새 기능을 스펙 주도로 시작하려 할 때 트리거한다.

스펙 만들기 (spec-create)

스펙 주도 개발의 첫 단계. 구현 전에 "무엇을, 왜, 어떤 조건으로 완료되는가"를 합의 가능한 문서로 고정한다.

디렉터리 구조

스펙은 상태별 디렉터리로 분류되며, 상태 전환은 파일을 다른 디렉터리로 이동해서 표현한다.

specs/
  not-started/   # 작성됐지만 아직 구현 시작 전
  in-progress/   # 구현 중
  in-review/     # 구현·검증 완료, 검토 대기
  completed/     # 검토 통과

• 파일명: <NNNN>-<slug>.md (예: 0001-report-intake-api.md). 스펙 한 건 = 파일 한 개.
• <NNNN>: 4자리 일련번호. 세 디렉터리를 모두 확인해 가장 큰 번호 +1.
• <slug>: kebab-case 짧은 이름.
• 새 스펙은 항상 specs/not-started/에 만든다.

작업 순서

1. 컨텍스트 파악 — docs/(특히 PRD), 관련 기존 코드, 기존 specs/를 읽어 중복·전제를 확인한다.
2. 번호 결정 — specs/{not-started,in-progress,in-review,completed}를 모두 보고 다음 일련번호를 정한다.
3. 범위 합의 — 무엇을 만들지 정해지면 곧바로 작성하지 말고, 기능적·기술적으로 고려해야 할 사항(요구사항·엣지케이스·기술 선택지·제약)을 사용자에게 먼저 질문해 확정한다. 추측으로 굳히지 않는다. 사용자 머릿속 요구사항·제약을 끌어내기 전에 스펙을 굳히면 빠진 가정으로 잘못된 방향이 된다.
4. Best Practice 리서치 — 아래 "Best Practice 리서치" 절차를 따라 웹에서 모범 사례를 찾고, 무엇을 적용할지 사용자가 직접 고르게 한다.
5. 스펙 작성 — 합의된 범위 + 사용자가 선택한 Best Practice를 반영해 아래 템플릿으로 specs/not-started/<NNNN>-<slug>.md를 만든다.
6. 인덱스 등록 — specs/README.md의 인덱스 표에 이 스펙 행을 추가한다(아래 "인덱스 관리").
7. 확인 — 작성 후 사용자에게 경로와 핵심 결정사항(채택한 Best Practice 포함)을 요약 보고하고 "이대로 갈까요?"라고 확인을 받는다. 승인 전에는 임의로 완료 처리하거나 다음 단계(구현 등)로 넘어가지 않는다. 스펙은 이후 구현의 기준이 되므로 확정 전 승인으로 재작업을 막는다.

인덱스 관리

specs/README.md가 전체 스펙 인덱스다. 스펙을 추가·이동·삭제할 때마다 표를 즉시 맞춘다.

• 컬럼: ID | 제목 | 상태 | 생성일 | 갱신일 | 파일. 값은 각 스펙 frontmatter와 일치시킨다.
• 파일 컬럼은 상태 디렉터리를 포함한 경로(예: not-started/0001-report-intake-api.md)로 적어, 상태가 바뀌면 이 값도 갱신되게 한다.
• frontmatter와 인덱스가 어긋나면 frontmatter를 정답으로 보고 인덱스를 맞춘다.

Best Practice 리서치 (스펙 작성 전 필수)

스펙 주제에 대해 검증된 모범 사례를 조사해 선택지로 제시한다. 추측으로 채우지 않는다.

1. 검색 — WebSearch로 이 스펙 주제의 best practice / 표준 / 흔한 함정을 찾는다. 여러 각도로 검색한다(예: "<주제> best practices", "<주제> design patterns", "<주제> pitfalls", "<기술스택> recommended approach"). 한국어·영어 둘 다 시도한다.
2. 출처 확인 — 핵심 권고는 가능하면 1차 출처(공식 문서, 표준, 신뢰도 높은 글)를 WebFetch로 확인한다. 출처 없는 주장은 채택지로 올리지 않는다.
3. 선택지 정리 — 수집한 모범 사례를 서로 배타적이거나 트레이드오프가 있는 결정 항목으로 묶는다. 각 항목마다 후보안 2~4개 + 한 줄 트레이드오프.
4. 사용자 선택 — AskUserQuestion으로 각 결정 항목을 물어 사용자가 고르게 한다. 추천안이 있으면 첫 번째 옵션에 두고 "(추천)"을 붙이되, 강요하지 않는다.
5. 반영 — 사용자가 고른 항목을 스펙의 "설계 개요"·"요구사항"에 녹이고, 출처 링크는 frontmatter의 related 또는 본문 참고에 남긴다.

주제가 너무 일반적이거나 사내 고유 로직이라 외부 모범 사례가 없을 때만 이 단계를 건너뛰고, 건너뛴 이유를 사용자에게 한 줄로 알린다.

템플릿

---
id: "0001"
title: <스펙 제목>
status: not-started   # not-started | in-progress | in-review | completed
created: <YYYY-MM-DD>
updated: <YYYY-MM-DD>
related: []           # PRD 섹션, 이슈, 관련 스펙
---

# <스펙 제목>

## 1. 배경 / 문제
왜 필요한가. 해결하려는 문제.

## 2. 목표 (Goals)
이 스펙이 달성해야 하는 것.

## 3. 비목표 (Non-Goals)
이번 범위에서 명시적으로 제외하는 것.

## 4. 요구사항
기능/비기능 요구사항. 가능하면 번호로.

## 5. 설계 개요
데이터 모델, API, 흐름. 다이어그램은 필요 시.

## 6. 완료 조건 (Acceptance Criteria)
- [ ] 검증 가능한 체크리스트. spec-review와 spec-implement가 이 항목을 기준으로 판단한다.

## 7. 미해결 질문 / 리스크
열린 결정사항.

## Changelog
기능/기술이 크게 바뀐 변경만 한 줄씩. 단순 버그·오타·리팩터링은 제외.
- <YYYY-MM-DD>: 최초 작성

원칙

• 구현이 아니라 합의를 만드는 문서다. 완료 조건은 반드시 검증 가능하게 쓴다.
• 추측으로 빈칸을 채우지 않는다. 모르면 "미해결 질문"에 남긴다.
• frontmatter의 status와 실제 디렉터리는 항상 일치시킨다.