Rubric Labs
디자인부터 코드까지···Ch 7 / 9

핸드오프 번들 까보기

Share → Handoff to Claude Code 메뉴가 만드는 ZIP 패키지의 정체를 뜯어봐요.

선민호 CTO
선민호 CTO
AI로 프로덕트 굽는 빌더

Claude Design이 Claude Code한테 넘기는 패키지 안에 무엇이 들어 있고 어떻게 전달되는지 짚어요.

다른 도구는 어디서 끊기나

다른 AI 디자인 도구도 코드 출력은 해요. v0가 그렇고, Lovable이 그래요. 그런데 그 코드는 자기 환경 안에서 돌아가는 코드예요. 회사 레포에 그대로 붙이려면 사람이 옮기고 맞춰야 해요.

Claude Design의 핸드오프는 다른 결이에요. Claude Code가 회사 레포의 실제 컨텍스트(파일 구조·기존 컴포넌트·코딩 컨벤션)를 읽고, 그 안에 맞는 형태로 디자인을 구현해요. 스크린샷이나 Figma 링크를 넘기는 게 아니라, 코딩 에이전트가 읽을 수 있는 구조화된 번들을 넘기는 거예요.

이 챕터에서는 실제로 받아본 번들을 기준으로 각 파일의 정체를 짚어봐요. 프로젝트 규모나 설정에 따라 세부 구조는 달라질 수 있어요.

Share → Handoff to Claude Code 메뉴

핸드오프 흐름은 간단해요.

  1. Claude Design 캔버스 우상단 Share 클릭
  2. Handoff to Claude Code 선택
  3. 모달이 열림 → 명령어 복사 또는 ZIP 다운로드 선택

'Handoff to Claude Code' 클릭 후 나타나는 명령어 모달 — 로컬 에이전트용 명령어와 Copy command 버튼이 보임

명령어 복사 방식은 로컬 Claude Code가 직접 번들을 fetch해서 실행해요. ZIP 다운로드 방식은 파일을 직접 받아서 Claude Code에 건네줘요. 결과는 동일해요.

ZIP 안에 뭐가 있나

다운로드한 ZIP을 풀면 이런 구조예요 (실제 받아본 번들 기준).

my-project/
├── README.md
└── project/
    ├── Page Name.html       ← 핸드오프 시 열어둔 페이지
    ├── styles.css
    └── assets/
        ├── colors_and_type.css   ← 디자인시스템 등록 시
        ├── fonts/
        └── logos/

README.md — 코딩 에이전트한테 주는 지시문

파일을 열면 첫 줄이 이래요.

# CODING AGENTS: READ THIS FIRST

내용은 세 가지예요.

  1. 핵심 파일을 먼저 읽어라 — 핸드오프를 실행할 때 열어둔 HTML 파일이 구현 대상이에요. 그 파일을 처음부터 끝까지 읽고, import한 파일(styles.css, assets/)까지 따라 열어서 전체 구조를 파악하라고 써 있어요.

  2. 픽셀 단위로 재현해라 — 이 파일들은 프로토타입이에요. 코드를 복사하는 게 아니라, 시각적 결과물을 레포 기술 스택(React·Vue 등)으로 다시 구현하라는 지시예요.

  3. 모호한 부분은 먼저 물어봐라 — 잘못 구현하고 나서 수정하는 것보다 미리 확인하는 게 낫다고 명시해요.

HTML 프로토타입 — 디자인 의도의 본체

각 페이지 HTML이 핸드오프의 핵심 파일이에요. 섹션마다 data-screen-label 속성이 붙어 있어요.

<header class="header"   data-screen-label="Header">
<section class="hero"    data-screen-label="01 Hero">
<section class="pricing" data-screen-label="02 Pricing">

이 레이블 덕분에 Claude Code가 섹션을 구분하고 구현 순서를 파악해요. 눈으로 보이는 화면이 아니라 코드로 읽히는 레이아웃 의도예요.

colors_and_type.css — 디자인시스템 스냅샷

디자인시스템을 등록한 프로젝트에만 생성돼요. 실제 레포의 CSS 변수를 추출해서 담아요.

/*
 * Design Tokens
 * Source: your-org/your-repo · app/globals.css
 */
:root {
  --primary:     #121827;
  --accent:      #9c3625;
  --radius-pill: 9999px;
  --fs-h1:       56px;
}

Claude Code는 이 파일을 보고 레포에서 이미 쓰는 변수명을 확인해요. HTML 프로토타입에 var(--accent)로 쓰인 색이 구현 코드에도 var(--accent)로 들어가는 이유예요. 임의의 헥스 코드가 코드에 새로 생기는 걸 막아주는 핵심이에요.

styles.css + assets/ — 스타일과 에셋

styles.css에는 히어로·섹션·버튼·카드 등 컴포넌트 스타일이 들어 있어요. assets/에는 폰트 파일과 로고 SVG가 포함돼 있어요. Claude Code가 에셋 경로를 파악하고, 레포에 이미 있으면 재사용하고 없으면 추가해요.

실제로 Claude Code가 하는 일

번들을 받은 Claude Code의 흐름이에요.

  1. README 읽기 — 구현 대상 파일 확인, 픽셀 재현 지시 확인
  2. HTML 프로토타입 읽기 — 섹션 구조, data-screen-label, 사용 클래스 파악
  3. 레포 스캔 — 기존 컴포넌트·CSS 변수·폴더 구조 파악
  4. colors_and_type.css 대조 (있을 경우) — 레포 변수명 확인, 프로토타입 토큰과 매핑
  5. 구현 — 레포 기술 스택으로 HTML 의도를 재현

프로토타입의 코드 구조가 아니라 시각적 의도를 레포 방식으로 다시 짜는 거예요.

다음 챕터에서 이 번들로 실제 핸드오프를 돌려봐요.