write-spec

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

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

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

2. 템플릿을 복사한다

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

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

3. 화면 표를 먼저 채운다

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

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

4. 수용 기준을 쓴다

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

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

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

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

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

6. 범위 밖과 열린 질문

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

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

완료 확인

pnpm preflight

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

출력

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