screen-spec

name	screen-spec
description	PRD/요구사항을 화면 설계서(스크린 스펙)로 구체화한다. "화면 설계서 써줘 / 스크린 스펙 만들어줘 / 이 화면 어떻게 그려야 해 / 상태 정의 좀 / 빈 상태·에러 처리 정리해줘 / 화면 정책 정리 / 개발한테 넘길 화면 문서"라고 할 때 실행.

작업 흐름(항상): 왜(목적·의도) → 무엇을 → 어떻게 → 기존 컨텍스트·리서치 → 기획 → 시각화 → 호출·실행 → 🔁회고·보완. 자세히 [[method]].

화면 설계서 (스크린 스펙)

PRD의 요구사항을 "개발·디자인이 바로 그릴 수 있는 화면 단위"로 쪼개는 문서다. 목적은 딱 하나: 회의 없이 이 문서만 보고도 화면이 나오게 만드는 것.

공통 원칙 (항상 지켜라)

1. 왜(이유)를 사람 말로: "이 버튼은 권한 없으면 숨긴다" 옆에 "왜냐면 결제 안 한 사용자한텐 혼란만 주니까" 식으로.
2. 근거/출처: 수치·정책은 PRD·리서치·정책 문서에서 인용. 없으면 지어내지 말고 **"확인 필요"**로 남겨라. 추측한 값을 확정처럼 쓰면 개발이 그대로 박는다.
3. 반자동: 여기서 만드는 건 초안이다. AI가 표를 채우고 → 사람(기획자·개발·디자인)이 검토·결정한다. 확정 표시 전엔 draft.
4. 코칭(신입이면): 상태 정의(빈/로딩/에러/권한없음)를 빠뜨리는 게 신입의 90%다. 왜 4가지 상태를 다 봐야 하는지 짚어주며 진행.

진행 순서

1. [[write-spec]](PRD) 또는 요구사항 문서를 입력받는다. 없으면 먼저 write-spec부터.
2. 화면 목록(화면 인벤토리)을 뽑는다 → 사용자 확인.
3. 화면별로 아래 템플릿을 채운다.
4. 데이터는 ~/.pm-copilot/data의 기존 스펙·용어집 참조. 화면 목록/상태 누락(빈 상태·에러·로딩·권한없음 등)은 [[qa]] 정적 검수로 교차 확인.
5. 완성되면 [[mockup]]으로 넘겨 시각화, 이후 [[prototype]].

화면별 템플릿

1. 목적 · 사용자

• 이 화면이 푸는 문제 / 주 사용자(역할) / 진입 경로

2. 구성 요소 (영역 → 컴포넌트)

영역	컴포넌트	내용/라벨	비고
헤더	뒤로가기, 타이틀	"주문 상세"
본문	상품 리스트(카드)	썸네일·상품명·가격	최대 표시 수 확인 필요

3. 데이터 / 소스

필드	소스(API/테이블)	타입	예시	비고
주문번호	GET /orders/{id}	string	ORD-1024

4. 상태 (5종 필수)

상태	조건	화면 처리
기본	데이터 있음	정상 렌더
빈 상태	결과 0건	"주문 내역이 없어요" + CTA
로딩	요청 중	스켈레톤
에러	요청 실패	재시도 버튼 + 문구
권한없음	미로그인/미결제	로그인 유도 / 진입 차단

5. 사용자 플로우

• 진입 → 액션 → 결과 (분기 포함). 예: 상세 진입 → [취소] 클릭 → 확인 모달 → 취소 완료/실패

6. 엣지케이스

• 네트워크 끊김, 값 초과(긴 이름 말줄임), 동시성(이미 취소된 주문), 0/음수/최대값

7. 정책 (유효성 · 권한 · 개인정보)

• 유효성: 입력 규칙(필수/형식/길이) — 근거 인용
• 권한: 역할별 노출/차단
• 개인정보: 마스킹 대상(전화·카드 뒷자리) — 정책 문서 인용, 없으면 확인 필요

마무리 체크리스트

• 모든 화면에 상태 5종 있는가
• "확인 필요" 항목을 목록으로 뽑아 담당자 지정했는가
• 데이터 소스가 실제 API와 매칭되는가(개발 검토)

애매하면 관련: [[write-spec]] [[mockup]] [[prototype]] [[simple-design]] [[decision-log]]

🎨 Figma 연동 (커넥터 figma 연결 시)

• 열람: Figma URL/파일을 주면 기존 화면 디자인을 읽어(get_design_context·get_screenshot) 화면 목록·상태를 역산하고 스펙 근거로 삼는다.
• 생성/편집: 확정한 스펙을 Figma 프레임으로 반영(use_figma) — 편집 권한이 있을 때만.
• 불일치 시 현행화 기준: 최신 수정본이 기준(디자인·기획서 각각 last-modified 비교). 단 기획자는 대개 Figma 편집 권한이 없으므로 — 디자인이 더 최신 → 기획서를 현행화(디자인에 맞춰 스펙 갱신), 기획서가 더 최신 → Figma를 임의 편집하지 말고 불일치 목록(무엇을·어떻게 바꿀지)을 만들어 디자이너에게 전달.