PingYang0717/frontend-design-skill

프론트엔드 프로젝트 부트스트랩

UI/UX에서 전달한 프로토타입을 '팀 표준의 프론트엔드 프로젝트 + 작성된 문서 + 작업 가능한 티켓'으로 변환하여, 이후 다른 사람이나 다른 코딩 에이전트가 작성한 코드가 마치 한 사람이 작성한 것처럼 보이게 합니다.

버전: CHANGELOG.md의 최상위 항목 참조.

핵심 원칙

1. 프로토타입은 요구사항素材일 뿐, 프로젝트로 옮길 코드가 아닙니다. 프로토타입에서 화면, 데이터, 색상표, 인터랙션을 추출하되, 그 구현을 복사하지 않습니다. 원본 파일과 스크린샷은 리포지토리에 넣어验收 기준으로 삼습니다.
2. 팀 규칙은 그대로 복사하고, 프로젝트 내용은 프로토타입에 따라 작성합니다. 두 가지 유형의 파일은 처리 방식이 다릅니다(아래 '파일 인덱스' 참조).
3. 확실하지 않으면 질문하고, 추측하지 마세요. 질문은 정지점에서 여러 라운드에 걸쳐 나누어 하며, 각 질문에 추천 답변을 함께 제시합니다. '예'라고 답하면 추천을 수락한 것으로 간주합니다.
4. 비즈니스 기능을 구현하지 않습니다. 이 스킬은 스켈레톤, 빈 페이지, 문서만 만듭니다. 비즈니스 기능은 이후 작업 티켓에 따라 /implement가 개발합니다.
5. 검증이 있어야 완료입니다. lint, typecheck, test, build가 모두 통과되어야 하고, 남아 있는 플레이스홀더가 없어야 하며, 모든 화면에 스크린샷이 있어야 합니다.

필요한 입력

• 프로토타입(단일 HTML, 다중 페이지 HTML, 디자인 파일 링크 또는 스크린샷)과 그 버전 / 전달 날짜
• 프로젝트 이름과 한 줄 설명
• 새 프로젝트의 폴더 위치(빈 폴더 또는 새 리포지토리여야 함; 내용이 이미 있으면 중단하고 확인)

나머지 정보(배포 환경, 백엔드 현황, 언어, 다크 모드)는 1단계에서 질문하며, 세부 사항은 references/workflow-detail.md를 참조하세요.

사전 준비(각 머신당 한 번)

cd <skill> && npm ci && npx playwright install chromium   # scripts/에서 사용하는 Playwright와 Prettier; 프로젝트 스켈레톤에는 포함되지 않음
# 머신에 이미 Chromium이 있으면 다운로드하지 말고, 스크린샷 스크립트 실행 시 CHROMIUM_EXECUTABLE=<경로> 사용

프로세스

작업 목록을 만들어 다음 5단계를 추적하고, 각 단계가 완료되면 체크합니다.

1단계: 접수

먼저 프로젝트 폴더가 없거나 비어 있는지 확인합니다(내용이 있으면 중단하고 질문). 그런 다음 프로토타입 파일, 버전, 팀 공유 저장 위치를 확인하고, references/workflow-detail.md 1단계 표에서 메시지에 아직 제공되지 않은 항목을 질문합니다.

2단계: 프로토타입 분석 및 스크린샷

references/prototype-analysis.md를 읽고, 그 방법에 따라 분석하여 docs/_bootstrap/prototype-analysis.md를 생성합니다(형식: templates/prototype-analysis.md). 프로토타입이 HTML인 경우, 원본 파일을 docs/prototype/에 넣고, docs/prototype/screens.json을 채운 후(형식: templates/prototype-screens.json), 스크린샷 스크립트를 실행하여 각 화면의 png를 생성합니다.

⏸ 정지점: references/prototype-analysis.md의 '정지점'에 따라 여러 라운드에 걸쳐 질문합니다: 확인이 필요한 문제, 누락된 상태의 기본 처리 방식, 라우팅 모드(history / hash), 백엔드 현황. 답변을 받으면 분석 파일의 11, 12절에 기록한 후 계속 진행합니다.

3단계: 스켈레톤 생성

assets/skeleton/을 복사하고(node_modules 제외), npm ci를 실행한 다음, references/workflow-detail.md 3단계에 따라 이름, 색상표, 라우팅 모드, 라우트 및 메뉴, 빈 페이지, 권한 코드를 수정합니다. 첫 번째 실제 기능이 완료될 때까지 Item 예제 기능을 유지합니다.

4단계: 문서 생성

references/workflow-detail.md 4단계의 대조표에 따라 복사하고 작성합니다. 모든 <!-- FILL: -->은 지시에 따라 채우고 주석을 삭제하며, 모든 {{PLACEHOLDER}}를 대체합니다. 모르는 것은 '확인 필요'라고 쓰고, 지어내지 않습니다.

5단계: 검증, 커밋 및 보고

npm run lint && npm run typecheck && npm test && npm run build
node <skill>/scripts/check-placeholders.mjs <project>

네 가지 항목이 모두 통과(lint에 warning 없음)되고, 검사 스크립트에 ERROR가 0개여야 완료입니다. 그런 다음 첫 번째 커밋을 합니다. 보고 형식은 references/workflow-detail.md 5단계를 참조하세요.

사용자가 부재 중인 경우: 추천 답변이 있으면 추천을 채택하고 '추천 채택(임시)'라고 표시하며, 추천 답변이 없으면 '확인 필요'라고 쓰고 정상적으로 계속 진행합니다. 두 경우 모두 보고서에 나열합니다. 중단해야 하는 유일한 상황은 프로젝트 폴더에 이미 내용이 있는 경우입니다.

파일 인덱스

그대로 복사(이름만 바꾸고 내용은 수정 불가)

경로	복사 대상	내용
assets/skeleton/	프로젝트 루트	실행 가능한 스켈레톤: 설정 파일, api 계층, 데이터 hook, DataBoundary, 권한, i18n, theme, MSW, 테스트, CI(Azure DevOps), PR 템플릿, Item 예제 기능
references/standards/	docs/conventions/	18개의 팀 개발 규칙 + 인덱스
references/adr-baseline/	docs/adr/	ADR 0001–0016 + 인덱스
templates/agents/	docs/agents/	mattpocock skills의 tracker와 domain docs 설정(local markdown, single-context)

프로토타입에 따라 작성

템플릿	출력
templates/prototype-analysis.md	docs/_bootstrap/prototype-analysis.md
templates/prototype-screens.json	docs/prototype/screens.json(스크린샷 스크립트 입력)
templates/README.md, AGENTS.md, ARCHITECTURE.md, GLOSSARY.md	프로젝트 루트
templates/CLAUDE.md	프로젝트 루트(Claude Code용 어댑터 파일: 한 줄 설명 주석 + @AGENTS.md, 그대로 복사)
templates/prototype-README.md	docs/prototype/README.md
templates/adr-router-mode.md	docs/adr/0017-router-mode.md
templates/api-interface-auth.md, api-interface.md, api-checklist.md	docs/api/
templates/feature-spec.md	docs/specs/<feature>.md
templates/task.md, tasks-README.md, task-remove-example.md	docs/tasks/
templates/adr.md, bug-report.md 등	별도로 docs/templates/에 저장하여 이후 사용

설명 및 도구

경로	언제 읽는가
references/workflow-detail.md	각 단계의 구체적인 방법, 명령어 및 파일 대조
references/prototype-analysis.md	2단계
scripts/screenshot-prototype.mjs	2단계(프로토타입 개정 시 다시 실행)
scripts/check-placeholders.mjs	5단계

mattpocock skills 연동

이 스킬의 출력물은 mattpocock/skills의 입력입니다. 프로젝트에서 /setup-matt-pocock-skills를 다시 실행할 필요가 없습니다(실행해도 AGENTS.md의 ## Agent skills와 docs/agents/만 업데이트되며, CLAUDE.md에는 쓰지 못하게 합니다).

해당 스킬	여기서의 대응
/grill-with-docs, grilling	2단계의 정지점은 동일한 인터뷰 방식입니다. 이후 디자인 변경 시 직접 사용하며, 용어는 GLOSSARY.md에, 결정 사항은 docs/adr/0018+에 기록합니다.
domain-modeling	GLOSSARY.md(동일 형식)와 docs/adr/(팀 형식, docs/agents/domain.md 참조)를 읽고 씁니다.
/to-spec, /to-tickets	사용하지 않음. 명세는 이미 docs/specs/(Gherkin 번호)에, 작업은 이미 docs/tasks/(계층별 파일 경로 및 재사용 가능 컴포넌트 포함)에 있습니다.
/implement	첫 번째 버전의 구현 방식: 한 번에 한 장의 docs/tasks/<ID>-*.md, main에서 작업 티켓으로 작성된 브랜치로 시작하며, tdd와 code-review를 호출합니다.
tdd	seam은 이미 AGENTS.md의 '테스트 seam'에 작성되어 있으므로, 다시 논의할 필요가 없습니다.
/implement-spec	사용 가능하지만 아직 시도되지 않음: 각 worktree에서 npm ci(husky prepare)를 실행해야 하며, Azure DevOps에는 draft PR 통합이 없습니다.

Agent 도구 호환성

AGENTS.md는 유일한 규칙 소스입니다. opencode와 Kimi Code CLI는 프로젝트 루트의 AGENTS.md를 직접 읽습니다. Claude Code는 CLAUDE.md를 읽으므로, 스켈레톤에는 @AGENTS.md만 있는 어댑터 파일을 포함합니다. 어댑터 파일에 다른 규칙을 쓰지 마세요.

이 스킬 업데이트

팀 규칙을 변경하려면 이 스킬을 변경하고(standards, adr-baseline, skeleton을 함께 변경), CHANGELOG.md에 기록하고 버전을 올리세요. 개별 프로젝트에서만 변경하지 마세요. 개별 프로젝트의 이탈은 해당 프로젝트의 ADR(0017부터 시작)에 작성합니다. skeleton을 수정한 후에는 반드시 assets/skeleton/에서 lint, typecheck, test, build를 실행하세요. Markdown을 수정한 후에는 npm run format을 실행하세요.