wigtn Screen Spec Skill
/screen-spec 의 실행 엔진. PRD 하나를 읽어 화면정의서 5종을 각각 별도 파일로 만든다.
출력 계약 (타협 불가)
docs/prd/screens/<feature>/ 아래에 아래 5개 파일을 만든다. 하나의 문서로 합치지 않는다.
각 산출물은 해당 보일러플레이트를 Read해서 PRD 데이터로 채운다.
| # | 파일 | 보일러플레이트 (${CLAUDE_PLUGIN_ROOT}/skills/screen-spec/) |
|---|---|---|
| 1 | 01-IA.md |
templates/01-IA.md — 정보구조도, 페이지 ↔ FR 매핑 |
| 2 | 02-USER-FLOW.md |
templates/02-USER-FLOW.md — 분기 조건까지 명시한 플로우 |
| 3 | 03-SCREEN-SPEC.md |
templates/03-SCREEN-SPEC.md — 화면당 7개 슬롯 |
| 4 | 04-WIREFRAME.html |
templates/04-WIREFRAME.html (web) / templates/04-WIREFRAME-mobile.html (mobile) |
| 5 | 05-DEV-HANDOFF.md |
templates/05-DEV-HANDOFF.md — FR ↔ 화면 ↔ 컴포넌트 |
01 → 02 → 03 → 04 → 05 순서로 만든다. 앞 산출물이 뒤 산출물의 입력이다.
입력 — PRD가 단일 진실원
docs/prd/PRD_<feature>.md 를 읽는다. Role Key · FR ID · Route · 상태는 PRD에서 그대로 인용하고 새로 지어내지 않는다.
| PRD 섹션 | 쓰이는 곳 |
|---|---|
| §2.3 User Roles | 각 화면의 Audience (Role Key를 그대로) |
| §3 Functional Requirements | 페이지 ↔ FR 매핑 (01, 05) |
| §5.4 Pages | 대상 페이지 목록 (route / auth / responsive) |
| §5.4.1 Page State Matrix | 화면별 상태 명세 (03) |
| §5.5 User Flow | 플로우 확장의 출발점 (02) |
§5.4에서는 Has FE Components: Yes 인 행만 대상으로 한다. PRD 골격 정본은 ${CLAUDE_PLUGIN_ROOT}/contracts/PRD-CONTRACT.md.
상태 어휘는 5개로 고정: loading / empty / error / success / no-permission.
§5.4.1에서 체크된 상태는 03-SCREEN-SPEC.md에 1줄 이상 명세한다 (누락은 리뷰의 critical).
중단 조건 — 추측으로 메우지 말고 stop한다:
- FE 페이지 0개 → "백엔드 전용 PRD입니다.
/implement로 진행하세요" - §5.4.1 누락 → "Page State Matrix가 필요합니다"
- §5.5 누락 → "User Flow가 필요합니다"
플랫폼 판정
--platform 명시값이 있으면 그것이 우선. 없으면 PRD §1 Overview의 모바일 시그널(React Native, RN, iOS, Android, 네이티브, 앱스토어, 모바일 앱, mobile)을 보고 mobile 로 자동 전환하며, 전환했음과 --platform=web 으로 덮어쓸 수 있음을 사용자에게 알린다. 시그널이 없으면 web.
⚠️ 단독 앱은 시그널이 아니다 — 웹앱 / web app 에 부분 매칭되어 오탐한다.
모바일 템플릿은 네비 패턴 3종을 모두 담고 있으므로, 실제 산출물에서는 쓰지 않는 패턴 섹션을 제거한다.
INTERVIEW (--interview 일 때만)
PRD가 다루지 않는 화면 레이어 결정을 한 메시지에 번호 매긴 5~7개 객관식으로 묻고 1회 응답으로 끝낸다. 질문을 한 개씩 쪼개 보내지 않는다(라운드트립 폭증).
네비게이션(top / side / bottom / drawer) · 정보 밀도(compact / spacious) · 에러 톤(공식 / 친근) · 빈 상태 철학(일러스트+CTA / 최소 텍스트+CTA) · 전환 방식(page / modal / drawer) · 모바일 우선순위(desktop-first / mobile-first / parity) · 첫 화면 후크(value / action / story-first).
받은 답변은 03-SCREEN-SPEC.md에 명시적으로 반영한다. 플래그가 없으면 이 단계를 건너뛴다(PRD 추론 모드).
PRD에 TBD / ??? / 빈 셀이 5건 이상이면 종료 안내에서 --interview 재실행을 권한다.
생성 시 고정 규칙
실행 분기 (컨텍스트 절약)
- 01~03은 메인 스레드에서 만든다 — 짧고, 뒤 단계에서 계속 참조된다.
- 04·05는
general-purposesubagent에 분리 발주한다 — 출력이 가장 크고 재참조가 적다. subagent에 PRD 경로 · 01~03 경로 · 사용할 템플릿 경로 · INTERVIEW 결정사항 · 출력 경로를 넘기고, 파일 경로와 검증 요약만 돌려받는다(본문을 메인 컨텍스트에 싣지 않는다).
와이어프레임은 lo-fi다
- 흑백(
neutral-*) + 의미색만: error=red, success=green, warning·no-permission=amber. - 브랜드/액센트 컬러, 폰트·그림자·그라데이션 등 실제 디자인 금지. 스타일은 다음 단계의 결정이다.
- 회색 점선 박스 + 라벨로 영역을 표현하고, 페이지 간 이동은
<a href="#screen-<slug>">anchor로 클릭 가능하게 만든다. - 페이지 ≥6개 또는 04가 600줄 초과 →
04-wireframes/<slug>.html로 쪼개고04-WIREFRAME.html은 인덱스로 둔다.
연결 무결성
- 03의 Wireframe Anchor와 04의
<section id="screen-<slug>">가 일치해야 한다. - 모든 페이지는 1개 이상의 FR에, 모든 FR은 1개 이상의 화면에 연결된다(양방향).
- 모든 폼 필드는 validation과 microcopy를 둘 다 갖는다.
리뷰 (필수)
frontend-developer 에이전트에 산출물 디렉토리와 ${CLAUDE_PLUGIN_ROOT}/skills/screen-spec/references/handoff-checklist.md 를 넘겨 검증한다. INTERVIEW 결정사항이 있으면 그것이 일관되게 반영됐는지도 확인한다.
판정은 findings 롤업이다 — critical ≥1이면 FAIL(해당 산출물만 재생성 후 재검증), critical 0이고 major ≥1 또는 minor ≥5면 WARN(표시하고 진행), 그 외 PASS. 점수는 매기지 않는다.
부분 재실행
--pages=<list> 나 "와이어프레임만 다시 만들어" 같은 요청은 지정된 파일만 통째로 덮어쓰고 나머지 산출물은 보존한다. diff 머지는 하지 않는다.
참고
${CLAUDE_PLUGIN_ROOT}/skills/screen-spec/references/state-checklist.md— 상태별 UI 패턴${CLAUDE_PLUGIN_ROOT}/skills/screen-spec/references/microcopy-patterns.md— 마이크로카피 패턴${CLAUDE_PLUGIN_ROOT}/skills/screen-spec/references/handoff-checklist.md— 리뷰 체크리스트 + 반환 스키마- 스타일/브랜드 선택은 이 스킬 밖이다.
design-discovery가/implement직전에 담당한다. - 산출물은
/implement의 입력이다: 03 → 컴포넌트 props/state, 04 → 레이아웃 마크업, 05 → task 분해.