screen-design-doc

RFP, 기획문서, 요구사항 메모 등 어떤 형태의 원본 문서라도 받아서 IA(Information Architecture) 사이트맵과 화면별 설계서를 Mermaid + MD 형식으로 만든다. 화면을 직접 구현하기 전에 "어떤 화면이 있고 각 화면에 무엇이 들어가는가"를 빠르게 정리하는 것이 목적이다.

지원 입력 형식

형식 처리 방식

.pdf

내장 Node.js 스크립트로 텍스트 추출 후 분석

.txt

직접 읽어서 분석

.md

직접 읽어서 분석

그 외 파일 형식은 지원하지 않는다. 사용자에게 위 세 가지 중 하나로 변환해달라고 안내한다.

실행 절차

Step 0 — 모드 감지

워크스페이스 루트에 screen-design/ 폴더가 이미 존재하는지 확인한다.

• screen-design/ 없음 → 신규 생성 모드: Step 1부터 진행

• screen-design/ 있음 → 업데이트 모드: 아래 업데이트 모드 상세 절차로 건너뜀

Step 1 — 파일 확인

사용자가 제공한 파일 경로의 확장자를 확인한다.

• .pdf/.txt/.md 이외 → 명확한 오류 메시지와 함께 종료

• 파일이 존재하지 않으면 → 경로 재확인 요청

Step 2 — 텍스트 추출

PDF 입력일 때:

의존성 설치 (최초 1회)

cd ~/.claude/skills/screen-design-doc/scripts && npm install --silent

텍스트 추출 — 반드시 이 경로로 저장

node ~/.claude/skills/screen-design-doc/scripts/extract_pdf_text.js
<입력.pdf> -o <워크스페이스_루트>/screen-design/extracted/source.txt

추출된 파일은 반드시 screen-design/extracted/source.txt 경로에 저장한다.

TXT/MD 입력일 때: Read 도구로 직접 읽는다.

Step 3 — 요구사항 분석

텍스트에서 아래 항목을 식별한다:

요구사항 ID 감지: 원본 문서에 ID 패턴이 있는지 확인

• 감지 패턴 예: REQ-001 , FR-01 , F-001 , 요구사항번호 등

• 없으면 → ID 추적 생략, SC ID만 부여

• 있으면 → 각 화면 도출 시 해당 요구사항 ID를 함께 기록

사이트 판단: 멀티 사이트가 필요한지 판단한다

• 멀티 사이트 기준 (아래 중 하나 이상 해당):

• 사용자 역할이 다르고 화면 구성이 전혀 다름 (예: 관리자 vs 일반 사용자)

• 대상 디바이스/플랫폼이 다름 (예: 데스크톱 웹 vs 모바일 웹)

• 독립 배포가 필요함 (예: admin.example.com vs app.example.com)

• 멀티 사이트 → 사이트 슬러그 결정 (소문자 영문, 예: admin , user , partner )

• 단일 사이트 → 기존 플랫 구조 유지

화면 목록 도출: 기능 단위를 화면 단위로 묶는다

• 동일 목적/맥락의 기능 → 한 화면

• 화면 간 계층 관계 파악 (메인 → 서브 → 상세)

화면 그룹핑: IA 상위 카테고리 결정 (예: 인증, 대시보드, 설정)

• 그룹 번호가 SC ID의 첫 번째 자리가 된다

분석 결과를 아래 형식으로 정리한 뒤 다음 단계로 진입한다:

단일 사이트:

[그룹 01: 인증]

• SC-01-01: 로그인 화면 ← REQ-001, REQ-002
• SC-01-02: 회원가입 화면 ← REQ-003
• SC-01-03: 비밀번호 찾기 화면 ← REQ-004

[그룹 02: 대시보드]

• SC-02-01: 메인 대시보드 ← REQ-010, REQ-011
• SC-02-02: 알림 목록 ← REQ-012

멀티 사이트:

[사이트: admin — 관리자 / 웹 데스크톱 / 사이드바] [그룹 01: 인증] - SC-ADMIN-01-01: 로그인 화면 ← REQ-001 [그룹 02: 대시보드] - SC-ADMIN-02-01: 대시보드 ← REQ-010 - SC-ADMIN-02-02: 회원 관리 ← REQ-011

[사이트: user — 일반 사용자 / 모바일 웹 / 하단탭] [그룹 01: 온보딩] - SC-USER-01-01: 온보딩 ← REQ-020 [그룹 02: 홈] - SC-USER-02-01: 홈 화면 ← REQ-030

Step 4 — IA 사이트맵 생성

references/screen-design-guide.md 의 IA 패턴을 참고해 전체 화면 계층을 Mermaid로 표현한다.

모든 ia-sitemap.md 상단에 메타 테이블을 포함한다:

단일 사이트:

flowchart TD root[🖥️ 시스템명]

root --> g01[인증]
root --> g02[대시보드]

g01 --> sc0101["SC-01-01\n로그인"]
g01 --> sc0102["SC-01-02\n회원가입"]

g02 --> sc0201["SC-02-01\n메인 대시보드"]

screen-design/ia-sitemap.md 에 저장한다.

멀티 사이트:

각 사이트별로 별도의 ia-sitemap.md 를 생성한다. SC ID에 사이트 슬러그가 포함된다.

• screen-design/admin/ia-sitemap.md — 관리자 사이트 IA

• screen-design/user/ia-sitemap.md — 사용자 사이트 IA

Step 5 — 화면설계서 생성

화면별로 넘버링된 MD 파일을 생성한다. references/screen-design-guide.md 의 화면설계서 템플릿을 기준으로 작성한다.

화면 ID 체계:

• 단일 사이트: SC-[그룹번호]-[순번] (예: SC-01-01 , SC-02-03 )

• 멀티 사이트: SC-[SITE]-[그룹번호]-[순번] (예: SC-ADMIN-01-01 , SC-USER-02-03 ) 파일명: 전체 순번 2자리 + 영문명 (예: 01-login.md , 04-dashboard.md )

각 화면설계서 파일 구성:

• 화면 기본 정보 (ID, 화면명, 목적, 진입 경로, 이전/다음 화면)

• 주요 영역/섹션

• 컴포넌트 목록 (영역별 UI 요소)

• 사용자 액션 → 화면 전환 테이블

• 요구사항 추적 테이블 (요구사항 ID가 있는 경우)

파일 넘버링은 그룹 순서대로 전체 화면을 이어서 붙인다:

01-login.md (SC-01-01) 02-signup.md (SC-01-02) 03-forgot-password.md (SC-01-03) 04-dashboard.md (SC-02-01)

Step 6 — 결과물 저장 및 보고

워크스페이스 루트 screen-design/ 폴더:

단일 사이트 (기존 플랫 구조 유지, ia-sitemap.md에 메타 테이블만 추가):

screen-design/ ├── README.md ← 화면 그룹 목록, SC ID 인덱스, 파일 링크 ├── ia-sitemap.md ← 메타 테이블 + 전체 화면 계층 Mermaid ├── 01-login.md ← 화면설계서 ├── 02-signup.md ├── ... └── extracted/ ← PDF 입력 시만 └── source.txt

멀티 사이트:

screen-design/ ├── README.md ← 전체 사이트 개요, 사이트별 링크 ├── admin/ │ ├── ia-sitemap.md ← 메타 테이블 + 관리자 IA Mermaid │ ├── 01-login.md │ ├── 02-dashboard.md │ └── ... ├── user/ │ ├── ia-sitemap.md ← 메타 테이블 + 사용자 IA Mermaid │ ├── 01-onboarding.md │ ├── 02-home.md │ └── ... └── extracted/ ← PDF 입력 시만 └── source.txt

저장 완료 후 생성된 화면 수, 그룹 구조, 파일 목록을 사용자에게 보고한다.

업데이트 모드 상세 절차

워크스페이스에 이미 screen-design/ 폴더가 있을 때 사용하는 플로우다.

U-Step 1 — 현황 파악

기존 파일을 모두 읽어 현재 상태를 파악한다:

• screen-design/README.md — 화면 목록, 그룹 구조

• 단일 사이트: screen-design/ia-sitemap.md — 현재 IA 구조

• 멀티 사이트: screen-design/[사이트]/ia-sitemap.md — 사이트별 IA 구조

• screen-design/[번호]-[화면명].md 또는 screen-design/[사이트]/[번호]-[화면명].md — 각 화면설계서

현재 SC ID 마지막 번호, 그룹 구조, 화면 수를 파악해둔다.

U-Step 2 — 변경 내용 파악

• 새 문서가 있는 경우: Step 1~3을 수행한 뒤 기존 현황과 비교

• 구두 지시만 있는 경우: 사용자 설명에서 직접 변경사항 도출

변경 유형 분류:

[추가] 새 화면, 새 그룹, 새 컴포넌트, 새 사이트 [수정] 화면명 변경, 컴포넌트 변경, 액션 변경 [삭제] 화면 제거, 그룹 통합, 사이트 제거

애매한 부분이 있으면 작업 전에 사용자에게 확인한다.

U-Step 3 — 선택적 수정

변경이 있는 파일만 수정한다.

변경 유형 수정 대상 파일

특정 화면 내용 변경 해당 화면 .md

• ia-sitemap.md (구조 변경 시) + README.md

새 화면 추가 새 화면 .md 생성 + ia-sitemap.md

• README.md

화면 삭제 해당 .md 삭제 + ia-sitemap.md

• README.md

새 그룹 추가 해당 그룹 화면 .md

• ia-sitemap.md
• README.md

새 사이트 추가 사이트 폴더 생성 + ia-sitemap.md

• 화면 .md
• README.md

사이트 제거 사이트 폴더 삭제 + README.md

SC ID 처리:

• 기존 SC ID는 절대 변경하지 않는다 (추적 이력 보존)

• 새 화면은 해당 그룹의 마지막 SC 순번 다음을 이어서 부여한다

• 새 그룹은 기존 마지막 그룹 번호 다음을 이어서 부여한다

• 삭제된 SC의 ID는 재사용하지 않는다

파일 넘버링:

• 새 파일은 마지막 전체 순번 다음을 이어서 붙인다

• 중간 삽입이 필요한 경우 이후 파일 번호 재조정 + README.md 링크 업데이트

U-Step 4 — 변경 요약 보고

✅ 업데이트 완료

[수정된 파일]

• 03-product-list.md: 필터 컴포넌트 추가
• ia-sitemap.md: 결제 그룹 화면 반영

[추가된 파일]

• 07-payment.md: 결제 화면 신규 추가 (SC-03-01)

[변경 없는 파일]

• 01-login.md, 02-signup.md (변경 없음)

참고 파일

• references/screen-design-guide.md — IA 사이트맵 Mermaid 패턴, 화면설계서 템플릿, SC ID 체계, 요구사항 추적 테이블 형식