---
name: write-spec
description: 새 feature의 외부 관찰 가능한 동작(WHAT)을 사용자와 대화하며 spec.md로 확정한다. 요구사항이 모호하거나 여러 화면·경로에 걸쳐 있을 때 사용한다 — 사용자가 "spec"이라는 단어를 쓰지 않아도 다단계 feature를 정의하려는 신호가 보이면 트리거한다. 버그 수정, 한 줄 변경, 이미 구체적인 요구에는 쓰지 않는다. "/write-spec", "스펙 작성", "기능 정의"로도 호출한다.
argument-hint: "feature description"
---

# Write Spec

새 feature의 외부 관찰 가능한 동작(WHAT)을 사용자와 대화하며 확정한다.

## Inputs / Outputs

| 입력 | 출력 |
|---|---|
| `$ARGUMENTS` (feature 설명), 참조 이미지는 `artifacts/<feature>/references/`에 | `artifacts/<feature>/spec.md` — WHAT 전용 스펙 |

구현 선택(파일 배치, 스키마, 라이브러리, 테스트 유형)은 spec.md에 들어가지 않는다 — plan.md의 몫이다. 경계를 지키지 않으면 구현을 바꿀 때마다 spec을 고치게 된다.

## Workflow

### Step 1. Pre-exploration

이미 내린 결정을 뒤집지 않기 위해 질문 시작 전에 존재하는 맥락을 읽는다.

순서:
1. `artifacts/<feature>/idea.md` — 이미 결정된 방향과 원칙
2. `artifacts/<feature>/spec.md` — 이전 논의 기록 (있다면)
3. `artifacts/<feature>/references/` — 참조 자료가 있다면 구조·정보 계층 파악
4. **코드베이스의 관련 기능** — 기존 구현·패턴·데이터 모델. 이번 feature가 어디에 얹힐지 감을 잡는다

완전히 새로운 feature라 1-3이 없으면 4부터 시작한다.

### Step 2. Surface & Reframe

질문하기 전에 두 가지를 사용자에게 보여주고 확인받는다 — 코드를 쓰기 전에 오해를 드러내기 위함이다.

1. **내가 지금 가정하고 있는 것** — 사용자가 말하지 않았지만 내가 채우고 있는 빈칸
2. **모호한 목표의 측정 가능한 재진술** — 해당하는 경우에만

#### 출력 형식

```
내가 지금 가정하고 있는 것:
1. 로그인한 사용자만 대상 (게스트 지원 안 함)
2. 모바일·데스크톱 동시 지원

재진술 (모호 → 측정 가능):
- "대시보드를 빠르게" → 4G에서 LCP < 2.5s, 초기 데이터 < 500ms

→ 이대로 진행할까요, 아니면 바로잡을까요?
```

요구사항이 이미 구체적이면 재진술 블록은 생략한다. 가정은 항상 보여준다 — "가정 없음"이라도 그렇게 적는다.

### Step 3. Iterative Questioning

`$ARGUMENTS`에 대한 사용자 흐름을 시뮬레이션하며 빈칸을 찾는다.

**시뮬레이션 순서**:
1. happy path 하나를 먼저 끝까지 그린다
2. 그 위에 error paths, boundary conditions, 기존 feature와의 교차를 얹는다
3. 각 지점에서 빠진 결정을 기록한다

#### 질문 범위

사용자가 **관찰할 수 있는 것(WHAT)** 만 묻는다 — 파일 경로, 레이어 배치, 테이블 설계, 테스트 전략은 plan.md에서 결정된다.

#### 변경 비용 기반 우선순위

- **High cost of change** — 권한 경계, 데이터 모델, 사용자 노출 범위, 과금·결제 흐름. 나중에 바꾸면 마이그레이션·공지·재협의가 필요하므로 반드시 묻는다.
- **Low cost of change** — 카피 문구, 기본 정렬 순서, 에러 메시지 톤. 기본값을 제안하고 사용자가 수정할 여지를 남긴다.

#### 질문 규칙

- **한 번에 한 질문** — 2-4개 선택지를 제시하고, 답을 받기 전에는 다음으로 넘어가지 않는다 (사용자가 한 번에 답할 수 있는 분량)
- **이미 답이 있는지 먼저 확인한다** — 코드베이스·`idea.md`·이전 `spec.md`에 있을 수 있다
- **기존 시나리오와 교차하면 명시적으로 언급한다** — 사용자가 연결을 놓치지 않게
- **불확실성이 줄지 않으면 다음 단계로 넘어간다** — 단 미탐색 고비용 갈래는 넘어가기 전에 다룬다 (발견이 늦을수록 되돌리기 비용이 커진다)

### Step 4. Generate spec.md

`references/spec-template.md`의 섹션 구조를 따른다. 형식과 G/W/T 작성 가이드는 template에 있다.

#### 작성 규칙

- **WHAT만 쓴다** — 파일 경로, 테이블/컬럼명, 라이브러리·프레임워크, 테스트 유형은 spec.md에 나타나지 않는다. 그 결정은 plan.md로 미뤄야 구현이 바뀔 때 spec이 흔들리지 않는다.
- **성공 기준은 외부에서 관찰 가능해야 한다** — 사용자가 볼 수 있고 테스트 코드로 검증할 수 있는 것만. 내부 state, 함수 호출, DB 행 모양은 허용하지 않는다. 이 경계를 지키면 테스트가 리팩터링에 깨지지 않는다 — 내부 mock에 묶이면 구현 바꿀 때마다 깨진다.
- **제외 항목에는 이유를 단다** — 미래의 독자가 왜 미뤘는지 알아야 한다.
- **미결정은 사용자가 실제로 결정하지 못한 것만** — 질문을 안 해서 비어 있는 건 미결정이 아니라 누락이다.
- **여러 시나리오에 동일하게 적용되는 규칙은 불변 규칙으로 묶는다** — 단일 G/W/T로 담을 수 없는 cross-cutting 규칙(보안·성능·데이터 일관성). 해당 없으면 섹션 생략.

#### WHAT vs HOW 판정 예시

| 문장 | 판정 | 이유 |
|---|---|---|
| 사용자가 이메일로 로그인하면 대시보드로 이동한다 | OK | 관찰 가능한 입력 → 관찰 가능한 결과 |
| `/api/login` 엔드포인트가 JWT를 반환한다 | NG | 구현 수단. plan.md 소관 |
| 완료된 할 일에는 취소선이 표시된다 | OK | 외부에서 보이는 상태 |
| Zustand store의 `todos`가 업데이트된다 | NG | 내부 상태 |

파일명: `artifacts/<feature>/spec.md`

spec이 확정되면 **다음 단계**:

- **공간·시각 설계 결정**이 필요한 UI feature (예: 새 화면, 새 레이아웃, 화면 간 흐름) → `/sketch-wireframe <feature>`
- 그 외 → `/draft-plan <feature>`