피그마 → 코드베이스 퍼블리싱 스킬 개발기

Claude Code 글로벌 스킬로 "피그마 링크 하나로 퍼블리싱"을 자동화하면서 겪은 설계 고민과 결정들을 정리한 기록.

목표

사용자 명령 한 줄
  ↓
Claude Code가 피그마 시안을 읽고
  ↓
코드베이스에 컴포넌트로 퍼블리싱

최종적으로 이 세 가지 명령을 지원하는 스킬을 만드는 것:

[url] 퍼블리싱 해줘              → 단순 퍼블리싱
[url,url,url] 반응형 퍼블리싱 해줘  → 반응형 퍼블리싱
[url] 다시 퍼블리싱 해줘           → 수정 퍼블리싱

고민 1 — 피그마를 어떻게 읽을 것인가

선택지

결정: 커스텀 CLI

이유: "완전히 똑같은 시안"이 목표라면 토큰 최적화가 핵심인데, 커스텀 CLI만이 "필요한 것만 추출해서 Claude한테 넘기는" 흐름을 직접 제어할 수 있다.

추가 인사이트 — 이미지도 같이 넘겨야 한다

처음엔 JSON만 추출하면 된다고 생각했는데, "완전히 똑같이"를 달성하려면 시각적 검증이 필요하다.

extractor.py 출력:
  node.json  ← 구조 파악용 (레이아웃, 색상, 크기)
  node.png   ← 시각적 검증용 (Claude가 직접 보고 판단)

Claude가 JSON으로 구조를 파악하고, PNG로 시각적으로 검증하는 구조가 가장 정확하다.

extractor.py 핵심 로직

피그마 원본 JSON은 수천 줄인데, 퍼블리싱에 필요한 필드만 추출해서 70~90% 토큰 절감이 목표다.

유지하는 필드:

KEEP_KEYS = {
    "id", "name", "type",
    "absoluteBoundingBox",      # 크기/위치
    "fills", "strokes",         # 색상
    "style", "characters",      # 텍스트
    "layoutMode",               # flex 방향
    "primaryAxisAlignItems",    # justify
    "counterAxisAlignItems",    # align
    "paddingLeft/Right/Top/Bottom", "itemSpacing",  # 간격
    "cornerRadius", "opacity", "visible",
}

제거하는 필드:

• exportSettings, transitionNodeID, reactions — 인터랙션 메타
• pluginData, sharedPluginData — 플러그인 데이터
• 소수점 5자리 이상 → 3자리 반올림

고민 2 — 프레임워크 대응 전략

문제

프로젝트마다 Tailwind, Chakra UI, Vanilla CSS 등 다른 스택을 쓴다. 스킬이 이걸 어떻게 알고 대응할 것인가.

선택지

A. 전체 대응 — 어댑터 모두 로드
→ 손님이 올 때마다 모든 메뉴를 차려놓는 것. 토큰 낭비.

B. 감지 후 로드 — 해당 프로젝트 어댑터만 로드
→ 예약 확인하고 그 메뉴만 준비하는 것. 효율적.

결정: 감지 후 로드 (어댑터 패턴)

claude.md → framework 읽기 → 해당 어댑터 1개만 로드

"둘 다 설치돼 있으면 어떡하나?" 문제

Tailwind + Chakra가 같이 설치된 경우가 있을 수 있다. 해결책을 여러 가지 고민했는데:

• 파일 위치 기반 감지 → 복잡함
• 명령어에 명시 (--tailwind) → 안전하지만 UX가 나쁨
• claude.md에 명시 → 가장 단순하고 명확

# claude.md (프로젝트 루트)
framework: tailwind

프로젝트 단에서 한 번만 설정해두면, extractor.py도 package.json 파싱할 필요 없이 이 값만 읽으면 된다. 오히려 감지 로직이 단순해졌다.

어댑터 파일 구조

adapters/
  tailwind.md   ← layoutMode → flex/grid 클래스 매핑
  chakra.md     ← layoutMode → VStack/HStack/Box 매핑
  vanilla.md    ← layoutMode → CSS 속성 매핑

각 어댑터는 피그마 속성 → 프레임워크 문법 변환 규칙을 담는다.

예시 (Tailwind):

고민 3 — 퍼블리싱 타입 분기

세 가지 타입

단순 퍼블리싱 (simple.md)

• 새 컴포넌트 생성
• 노드 name → PascalCase 컴포넌트명
• 기존 파일 있으면 덮어쓰기 전 확인

반응형 퍼블리싱 (responsive.md)

• URL 여러 개 → 각각 추출 (mobile.json, tablet.json, desktop.json)
• absoluteBoundingBox.width로 브레이크포인트 자동 판단
• 모바일 퍼스트로 base 작성 후 변경값만 브레이크포인트 추가

수정 퍼블리싱 (patch.md)

• 기존 파일 찾아서 diff 분석
• 최소 변경 원칙 — 전체 재작성 금지, 변경된 부분만 수정
• 커스텀 로직/이벤트 핸들러 절대 덮어쓰지 않음

분기 방법

Claude Code가 명령어 패턴으로 즉시 결정:

"[url] 퍼블리싱"        → simple.md
"[...] 반응형 퍼블리싱"  → responsive.md
"[url] 다시 퍼블리싱"    → patch.md

추론 비용 없이 패턴 매칭으로 해결.

최종 파일 구조

publishing-skill/
  SKILL.md              ← 진입점. 감지 + 분기만 담당
  figma/
    api.md              ← 피그마 API 가이드, 환경 설정
    extractor.py        ← 노드 JSON 추출 + PNG export
  types/
    simple.md           ← 단순 퍼블리싱 워크플로우
    responsive.md       ← 반응형 퍼블리싱 워크플로우
    patch.md            ← 수정 퍼블리싱 워크플로우
  adapters/
    tailwind.md
    chakra.md
    vanilla.md

SKILL.md의 역할

SKILL.md는 오케스트레이터다. 직접 작업하지 않고 위임만 한다.

1. 피그마 URL 파싱 → extractor.py 실행
2. claude.md에서 framework 읽기 → 어댑터 로드
3. 명령어 패턴 판단 → 타입 워크플로우 로드
4. 코드 생성

토큰 최적화 전략 요약

복습 포인트

Claude Code 스킬 설계 원칙

1. SKILL.md는 가볍게 — 오케스트레이터 역할만. 실제 지식은 하위 파일에.
2. 역할 분리 — Python은 데이터 수집/전처리, Claude는 판단과 생성.
3. 컨텍스트는 필요한 것만 — 전체 대응보다 감지 후 로드가 토큰 효율적.
4. 프로젝트 설정은 claude.md에 — 런타임 감지 로직보다 명시가 단순하고 안전.

피그마 API 사용 시 주의사항

• URL에 node-id가 없으면 전체 파일을 가져옴 → 반드시 노드 링크 사용
• 이미지 export는 rate limit 있음 (급할 때 --no-image 옵션 활용)
• file_key는 URL에서 /file/ 또는 /design/ 다음 세그먼트
• node-id의 -는 API 호출 시 :로 변환 필요

반응형 퍼블리싱 시 체크리스트

• 브레이크포인트별 preview.png와 시각적으로 일치하는가
• 레이아웃 방향 전환 (VERTICAL ↔ HORIZONTAL)이 올바른가
• visible: false인 요소가 올바르게 처리됐는가
• 모바일 퍼스트로 작성됐는가

수정 퍼블리싱 시 절대 원칙

• 기존 로직/이벤트 핸들러가 있으면 절대 덮어쓰지 않는다
• 구조가 크게 바뀌면 먼저 변경 범위를 설명하고 확인받는다
• 전체를 다시 쓰지 않는다 — 변경된 부분만 수정한다

다음 스텝

• FIGMA_TOKEN 환경변수 설정 후 extractor.py 실제 테스트
• Claude Code 글로벌 스킬 등록 (~/.claude/skills/)
• 실제 퍼블리싱 결과 보고 어댑터 규칙 튜닝
• extractor.py에 에러 핸들링 보강 (rate limit, 잘못된 URL 등)