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-purpose subagent에 분리 발주한다 — 출력이 가장 크고 재참조가 적다. 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 분해.