1. 검증 가능한 목적을 줍니다.
Figma 디자인 시스템을 코드로 변환하는 디자인 시스템 하네스를 만들 거야. 이번 청크에서는 "무엇을 달성하면 성공인가"를 측정 가능한 기준으로 못 박고 CLAUDE.md를 시작만 한다.
목적 3가지(반드시 측정 가능한 동사로):
일관성 보장 → 모든 시각 값이 토큰만 참조 (raw hex/px/rgb/arbitrary Tailwind 0건).
하드코딩 자동 차단 → 토큰 외 값 입력 시 사람 리뷰가 아니라 도구 레벨에서 자동 차단.
구현 프로세스 표준화 → 모든 컴포넌트 작업이 동일한 4단계 절차를 거침.
기술 스택 전제: Vite 6 + React 19 + TypeScript 5 + Tailwind CSS v4 + Storybook 8(addon-designs + autodocs).
할 일:
CLAUDE.md 생성, 최상단에 위 "목적 + 측정 가능한 완료 기준"만 작성.
4원칙/에이전트/hook/토큰은 아직 만들지 마 (뒤 청크에서 채운다).
코드 짜기 전 플랜 먼저 보여주고 승인받아.이미 만든 CLAUDE.md에 카파시 4원칙을 추가해. 각 원칙은 반드시 "막는 문제 + 강제 방식"을
쌍으로 적는다(슬로건 금지).
1. Think Before Coding — 문제: 잘못된 가정. 강제: 모호하면 멈추고 질문, 추측을 사실처럼 말하지 않음.
2. Simplicity First — 문제: 부풀리기. 강제: 새로 만들기 전 기존 토큰/컴포넌트 재사용, 요청 안 한 추상화·옵션 금지.
3. Surgical Changes — 문제: 범위 밖 변경. 강제: 변경된 모든 줄이 요청과 1:1 추적.
4. Goal-Driven Execution — 문제: 미완 종료. 강제: 측정 가능한 완료 조건, 자체 검증 통과 전 "완료" 금지.
추가: 표준 워크플로 = 모든 작업은 Clarify→Reuse→Implement→Evaluate 4단계이며
각 단계가 원칙 1~4와 1:1 대응함을 명시.
- CLAUDE.md만 편집. 1단계 목적 섹션은 수정 말고 아래에 덧붙이기.
- 플랜 먼저, 승인 후 작성.3. 규칙을 잘 지키도록 Hook등의 강제 레이어를 줍니다.
4원칙이 "문서 권고"로 끝나지 않고 실제로 강제된다는 걸 CLAUDE.md에 계약으로 명시해.
강제는 3중 레이어:
- 레이어1 선언: CLAUDE.md가 원칙/규칙을 선언.
- 레이어2 절차: 에이전트가 Clarify→Reuse→Implement→Evaluate 절차로 원칙을 실행.
- 레이어3 자동차단: hook이 토큰 외 값을 도구 레벨에서 차단.
추가로 CLAUDE.md에:
- 토큰 규칙: 모든 시각 값은 src/tokens 토큰만, raw hex/px/rgb/arbitrary Tailwind 금지.
- 에이전트 라우팅 표(작업→에이전트) + 스킬 가이드 표(에이전트=역할 / 스킬=절차).
※ 다음 청크에서 만들 에이전트/스킬 4개를 가리키는 자리만 잡아둬도 됨.
- CLAUDE.md만 편집. 앞 내용 보존하고 덧붙이기.
- 플랜 먼저, 승인 후 작성.
4. 실제 산출물(하네스 결과물)에 대한 구체적인 가이드를 줍니다.
=== 핵심요소 4: 범위 4축 결정 (실제 파일 생성) ===
CLAUDE.md의 선언을 실제 파일로 구현해. 범위는 4개 축으로 결정한다.
[축1 — 에이전트 분리] .claude/agents/*.md 4개, 각각 Clarify→Reuse→Implement→Evaluate 강제:
- figma-implementer: Figma 링크/노드 → MCP(get_metadata/get_screenshot/get_design_context/get_variable_defs)로 읽어 구현.
- token-guardian: 하드코딩 감지·토큰 매핑·Figma 변수→토큰 동기화. 토큰 파일만 편집.
- component-builder: Figma 없이 기존 토큰으로 컴포넌트 생성/변형. Surgical 엄격.
- design-reviewer: 완료 전 검증 게이트(하드코딩0/토큰사용/범위일치/빌드/a11y/스크린샷). 코드 수정 안 함, PASS/FAIL.
+ 스킬 4개 .claude/skills/<name>/SKILL.md (해당 에이전트를 결정적으로 호출):
/figma-to-code, /new-component, /sync-tokens, /review-design.
[축2 — 스캐폴드 범위] Vite 6 + React 19 + TS 5: package.json / vite.config.ts(@vitejs/plugin-react + @tailwindcss/vite) /
tsconfig(+app,node) / index.html / src/main.tsx / src/App.tsx(토큰 기반) / src/index.css(@import "tailwindcss"+토큰) /
src/vite-env.d.ts / .gitignore. Storybook 8: storybook init 후 addon-designs 설치, .storybook/main.ts 등록,
preview.ts에 `import '../src/index.css'` + `tags:['autodocs']`. boilerplate 예제 스토리·addon-onboarding 제거.
[축3 — hook 하드블록] .claude/hooks/check-hardcode.mjs (Node, 의존성0, stdin JSON) +
.claude/settings.json PreToolUse, matcher "Edit|Write|MultiEdit". .tsx/.jsx/.ts/.js/.css 스캔,
hex/rgb/hsl/raw px/arbitrary Tailwind 감지 → exit 2 차단 + "값→토큰" 안내.
예외: design-tokens.css, *.tokens.css, 줄 끝 `token-exempt: <사유>` 주석.
[축4 — Figma MCP 직접 사용] 위 에이전트들이 MCP 도구를 직접 호출(중간 변환 레이어 없음)함을 각 에이전트 파일에 명시.
[토대(축들이 참조할 SSOT)] src/tokens/design-tokens.css에 Tailwind v4 @theme로
color/spacing/radius/typography/shadow/breakpoint 중립 기본. *.tokens.css 분리 가능,
src/tokens/README.md에 의미기반 네이밍 + raw 금지 규칙.
- CLAUDE.md와 앞 청크의 선언은 수정 말고 라우팅 표의 빈 자리만 채워.
- 플랜 먼저, 승인 후 구현.
5. 검증해야 하는 항목과 방법들을 구체적으로 명시합니다.
지금까지 만든 하네스 전체를 자체 검증하고 보고해. 통과 전 "완료" 선언 금지.
검증 항목:
- hook 가짜 입력 직접 테스트: 하드코딩 입력→exit 2 / 토큰 입력→exit 0 / SSOT·.tokens.css 면제→exit 0 / `token-exempt` 주석→exit 0.
- .claude/settings.json JSON 유효성.
- `npm run build` 통과.
- `npm run build-storybook` 통과.
각 항목의 실제 실행 결과(명령·출력 요약)를 보여주고, 하나라도 실패하면 원인과 수정안을 제시해.