Write Spec

---
name: write-spec
summary: 기능 요청을 받아 specs/<기능>.md 를 쓴다.
when: 새 기능을 시작할 때. 화면을 만들기 전에 항상 먼저.
---

# write-spec

## 1. 중복과 충돌을 먼저 본다

```bash
ls specs/
grep -ril "<핵심 키워드>" specs/
```

같은 흐름을 이미 정해 둔 명세가 있으면 새로 쓰지 말고 그쪽을 고친다. 화면 경로가 겹치면
`apps/miniapp/src/App.tsx` 의 `routes` 와 대조한다.

## 2. 템플릿을 복사한다

```bash
cp specs/_template.md specs/<기능-kebab>.md
```

파일명은 kebab-case. 한글도 허용된다 (`포인트-적립.md`). 밑줄로 시작하는 파일은 preflight 의
검사 대상이 아니므로 실제 명세에는 쓰지 않는다.

## 3. 화면 표를 먼저 채운다

경로 → 이름 → 역할. 경로는 해시 라우팅 기준(`/`, `/points`)이다.

각 화면마다 **진입 · 이탈 · 빈 상태 · 로딩 · 실패** 다섯 가지를 적는다. 이 중 하나라도
비어 있으면 `ui-builder` 가 임의로 정하게 된다.

## 4. 수용 기준을 쓴다

체크박스로. 각 문장은 앱을 켜고 확인할 수 있어야 한다.

최소한 이 네 개는 거의 모든 기능에 해당한다:

- [ ] 첫 화면에서 뒤로가기를 누르면 미니앱이 닫힌다
- [ ] 모든 화면에 빠져나갈 방법이 있다
- [ ] 앱을 재시작해도 <무엇>이 유지된다
- [ ] 모든 인터랙션이 2초 안에 반응한다

## 5. 심사 항목을 옮겨 적는다

`wiki/04-review-checklist.md` 에서 이 기능이 건드리는 항목만 골라 「심사 관련」에 넣는다.
전부 복사하지 않는다 — 해당 없는 항목이 섞이면 아무도 안 읽는다.

## 6. 범위 밖과 열린 질문

**범위 밖을 반드시 적는다.** 적지 않으면 구현 중에 늘어난다.

열린 질문이 하나라도 있으면 구현으로 넘기지 않는다. 사람에게 묻고 답을 받아 명세에 반영한 뒤
넘긴다.

## 완료 확인

```bash
pnpm preflight
```

`specs` 규칙에 error 가 없어야 한다.

## 출력

- 만든 파일 경로
- 정한 것 (화면 수, 핵심 수용 기준)
- 사람에게 묻는 것 (열린 질문)
- 다음 단계: `pnpm agent ui-builder "<화면 이름>"`