mvp-preview
요구사항 문서나 화면설계서를 받아서 순수 HTML/CSS/JS 파일로 화면 프리뷰를 만든다. 프레임워크 없이 브라우저에서 바로 열 수 있고, 링크 하나로 공유 가능하다. 완성도보다 빠른 확인이 목적이다.
지원 입력 형식
| 입력 | 처리 방식 |
|---|---|
.pdf | 내장 Node.js 스크립트로 텍스트 추출 후 분석 |
.txt / .md | 직접 읽어서 분석 |
screen-design/ 폴더 | 화면설계서 파일 자동 참조 |
| 없음 | 무엇을 만들지 간단히 물어보고 진행 |
실행 절차
Step 0 — 모드 감지
워크스페이스 루트에 preview/ 폴더가 이미 존재하는지 확인한다.
preview/없음 → 신규 생성 모드: Step 1부터 진행preview/있음 → 업데이트 모드: 아래 업데이트 모드 상세 절차로 건너뜀
- preview/ 하위에 사이트 폴더(예: preview/admin/, preview/user/)가 있으면 멀티 사이트 업데이트 모드
Step 1 — 입력 확인
다음 순서로 입력 소스를 결정한다:
- 사용자가 파일 경로를 제공했으면 → 해당 파일 사용 (
.pdf/.txt/.md만 허용) - 워크스페이스 루트에
screen-design/폴더가 있으면 → 자동으로 화면설계서 참조 - 아무것도 없으면 → 한 가지만 묻는다: "어떤 화면들을 만들어드릴까요? 간단히 설명해주세요." 답변을 받으면
brief.md에 기록하고 진행한다 (템플릿:templates/brief.md)
Step 2 — 텍스트 추출
PDF 입력일 때:
# 의존성 설치 (최초 1회)
cd ~/.claude/skills/mvp-preview/scripts && npm install --silent
# 텍스트 추출 — 반드시 이 경로로 저장
node ~/.claude/skills/html-prototype/scripts/extract_pdf_text.js \
<입력.pdf> -o <워크스페이스_루트>/preview/extracted/source.txtTXT/MD 파일, screen-design/ 폴더: Read 도구로 직접 읽는다.
Step 3 — 화면 목록 분석
입력에서 아래 항목을 파악한다:
- 필요한 화면 목록
- 화면 간 이동 흐름 (어디서 어디로 가는가)
- 각 화면의 주요 UI 요소
screen-design/ 참조 시 사이트 판단:
screen-design/하위에 사이트 폴더가 있으면 멀티 사이트- 각 사이트의
ia-sitemap.md상단 메타 테이블에서 플랫폼/레이아웃 정보를 읽는다 - 단일 사이트면
screen-design/ia-sitemap.md의 메타 테이블을 읽는다
문서 직접 입력 시 사이트 판단:
- 역할이 다르고 화면 구성이 전혀 다름 / 대상 디바이스가 다름 / 독립 배포 필요 → 멀티 사이트
- 사이트별 플랫폼과 레이아웃을 결정한다
분석 결과를 간략히 정리한 뒤 생성에 진입한다:
단일 사이트:
01. 로그인 화면 → 대시보드로 이동
02. 대시보드 → 목록, 설정으로 이동
03. 목록 화면 → 상세로 이동, 뒤로 가기
04. 상세 화면 → 뒤로 가기멀티 사이트:
[admin — 웹 데스크톱 / 사이드바]
01. 로그인 → 대시보드
02. 대시보드 → 회원 관리
03. 회원 관리 → 회원 상세
[user — 모바일 웹 / 하단탭]
01. 온보딩 → 홈
02. 홈 → 마이페이지
03. 마이페이지Step 3.5 — 공통 컴포넌트 생성 (해당 시)
화면 분석 결과, 네비게이션 바 · 사이드바 · 하단 탭 바 등이 3개 이상 화면에 반복되면 HTML 파일 생성 전에 공통 컴포넌트를 먼저 작성한다. 각 공통 요소를 Web Component로 정의하고, 해당 앱의 실제 메뉴 구조를 반영한다.
- 단일 사이트:
preview/components.js - 멀티 사이트: 사이트별
preview/[사이트]/components.js(플랫폼/레이아웃이 다르므로 분리)
Step 4 — HTML/CSS/JS 생성
references/build.md의 패턴을 참고해 화면별 HTML 파일을 만든다.
파일명 규칙: index.html (허브) + 01-[영문화면명].html, 02-[영문화면명].html,...
핵심 원칙:
- CSS/JS는 각 HTML 파일에 인라인으로 포함 (외부 파일 분리 안 함)
- Form 유효성 검사 없음 — 버튼 클릭 시 바로 다음 화면으로 이동
- 목업 데이터 하드코딩 — API 연결 없음
- 해피 패스만 — 에러 처리, 예외 케이스 없음
- 외부 CDN/라이브러리 없음 — 순수 HTML/CSS/JS만
- 공통 UI가 3개 이상 화면에 반복되면 Step 3.5에서 미리 만든
components.js의 Web Component 태그를 사용
멀티 사이트 시:
- 사이트별 폴더로 분리:
preview/admin/,preview/user/ - 각 사이트 폴더에
index.html(사이트 내 화면 허브) + 화면 파일 +components.js - 플랫폼에 따라 레이아웃 프리셋 적용 (
references/build.md참고):
- 웹 데스크톱 → max-width: 1200px, 사이드바 레이아웃 - 모바일 웹 → max-width: 480px, 하단탭 레이아웃 - 반응형 → 미디어쿼리 브레이크포인트
- 최상위
preview/index.html은 사이트 선택 허브 (각 사이트의 index.html로 링크)
Step 5 — 공유 안내
생성 완료 후 아래를 사용자에게 안내한다:
바로 보기:
preview/index.html 파일을 브라우저로 드래그하거나 더블클릭하세요.멀티 사이트: 사이트별로 개별 공유 가능 — 각 사이트 폴더(preview/admin/, preview/user/)를 독립적으로 배포할 수 있다.
링크로 공유: references/share.md의 상황별 방법 안내. 정적 HTML이므로 Surge.sh 또는 GitHub Pages가 가장 간편하다.
업데이트 모드 상세 절차
워크스페이스에 이미 preview/ 폴더가 있을 때 사용하는 플로우다. 참고 문서가 바뀌었거나 화면을 수정해야 할 때 해당한다.
U-Step 1 — 현황 파악
기존 파일을 읽어 현재 상태를 파악한다:
preview/index.html— 전체 화면 목록 허브 (또는 사이트 선택 허브)- 단일 사이트:
preview/0N-[화면명].html— 각 화면 파일 - 멀티 사이트:
preview/[사이트]/index.html+preview/[사이트]/0N-[화면명].html
현재 화면 수, 파일명 목록, 화면 간 링크 구조를 파악해둔다.
U-Step 2 — 변경 내용 파악
- 새 문서가 있는 경우: Step 1~3을 수행한 뒤 기존 현황과 비교
- 구두 지시만 있는 경우: 사용자 설명에서 직접 변경사항 도출
변경 유형 분류:
[추가] 새 화면
[수정] 기존 화면 UI/흐름 변경
[삭제] 화면 제거U-Step 3 — 선택적 수정
변경이 있는 파일만 수정한다.
- 특정 화면 변경 → 해당
.html+index.html(목록/링크 변경 시) - 새 화면 추가 → 새
.html생성 +index.html업데이트 - 화면 삭제 → 해당
.html삭제 +index.html링크 제거 + 관련 화면의 링크 정리
파일 넘버링은 기존 번호 유지, 새 파일은 마지막 번호 이어서 붙인다.
U-Step 4 — 변경 요약 보고
✅ 업데이트 완료
[수정된 파일]
- 02-list.html: 필터 UI 추가
- index.html: 링크 업데이트
[추가된 파일]
- 05-settings.html: 설정 화면 신규 추가
[변경 없는 파일]
- 01-login.html, 03-detail.html (변경 없음)참고 파일
references/build.md— HTML/CSS/JS 패턴, 화면 간 이동, form 처리references/share.md— 정적 파일 공유 방법 (Surge, GitHub Pages 등)templates/brief.md— 문서 없이 시작할 때 사용하는 맥락 기록 템플릿