Claude Design→Code｜handoffで既存プロジェクトに統合

ムラサキ — Sat, 02 May 2026 10:05:22 +0000

昨日公開したClaude DesignでLPを生成した実測レポートの続編です。Designで生成したモバイルアプリのマッチング画面モックを、筆者の個人サービスの既存Reactプロジェクトに統合するところまで実行しました。

SE歴20年・Claude Max 5x契約の筆者が、Handoff to Claude Codeを使って既存リポジトリに統合した一次体験です。結論から言うと、Design→Codeの受け渡しはURL経由のfetch方式で、Design枠は消費せずCode枠+3%のみ、実装完了まで約1時間、437テスト全パス・Viteビルド成功までたどり着きました。

ムラサキ

Design単体の検証は昨日済ませたので、今回は「本番寄りの既存プロジェクトに統合する」実運用フェーズの記録です。

TL;DR / 三行要約 8 MIN READ · UPDATED 2026.04

Handoffの受け渡しはURL経由の静的fetchで、Design側の生成処理は走らない。Code枠のみ課金対象。
既存React+Vite+Tailwindプロジェクトへの統合が約1時間弱で完了。437テスト全パス・Viteビルド成功。
Claude CodeがTailwindクラス変更に伴うテスト更新・他ページへの影響封じ込めを計画段階で自発的に設計。

RESULT — Code枠+3%・437テスト全パス TOOL — Claude Design → Claude Code（Max 5x） COST — Design枠0消費・Code枠+3%のみ

Handoff to Claude Codeの正体
ターミナルで受け取る（CLI経由の実行）
1. Copy commandで取得してClaude Codeに貼り付ける
2. Design枠は消費しない（Code枠のみ課金）
Claude Codeが自発的にやったこと
実装結果の実測
Design→Codeフローで見えた注意点
よくある質問
最後に：受け渡しの安全設計とClaude Codeの現場対応力

Handoff to Claude Codeの正体

Claude DesignのExportメニューにある「Handoff to Claude Code」は、Design側で生成したUIモックをClaude Codeに引き渡すための公式機能です。どういう仕組みで動いているのかを実測しました。

「Send to local coding agent」ダイアログの中身

Designプロジェクト画面の右上「Export」→「Handoff to Claude Code…」を選ぶと、「Send to local coding agent」というダイアログが開きます。ダイアログの中身は次の3要素です。

Claude Code用の指示コマンド（コード風の枠に表示される）
Copy commandボタン（指示文をクリップボードにコピー）
Give the agent more detailの自由記述欄（追加指示を書ける）

オプションとして「Download zip instead」のチェックボックスもありました。URLが何らかの理由で使えない場合に、ローカルzipダウンロードに切り替えてClaude Codeのチャットに手動で投入する代替手段です。

Handoffダイアログの初期表示

APIエンドポイント経由のURLフェッチ方式

表示される指示コマンドは次のような形です。

Fetch this design file, read its readme, and implement the relevant
aspects of the design.
https://api.anthropic.com/v1/design/h/?open_file=Matches+Screen.html
Implement: Matches Screen.html

Anthropic側のAPIエンドポイントにDesignの成果物がホストされ、Claude Code側がそのURLをfetchして読み込む設計です。Claude Codeのログを見ると、実際にはfetch後にgzip圧縮ファイルが保存され、それを解凍して読み込む流れになっていました。

この方式の利点は、Design側がCode側のファイルシステムを直接操作しないこと。受け渡しは読み取り専用の配信で、ローカルに何を書くかはすべてClaude Code側の判断に委ねられます。

追加指示欄で統合方針を伝えられる

デフォルトの指示コマンドだけでは「このデザインを実装して」という漠然とした依頼にしかなりません。今回は自由記述欄に以下の統合方針を入力しました。

対象プロジェクト（既存のReact + Vite + Tailwind）と置換対象ファイルの明示
作業ブランチ名
既存自前コンポーネントを優先使用する方針
モックデータは破棄して既存のAPI関数に接続する方針
作業フロー（CLAUDE.md/BUGS.mdを読む→既存機能を把握→計画提示→承認後に実装）

追加指示を入れた状態のダイアログ

この欄に既存資産の情報を詰め込むと、後述の通りClaude Codeが計画段階で既存コードと整合性を取るための下調べをしてくれます。

ターミナルで受け取る（CLI経由の実行）

Handoffの受け取り方はいくつか選べますが、今回はClaude Code CLI経由で実行しました。

Copy commandで取得してClaude Codeに貼り付ける

流れはシンプルです。

ダイアログのCopy commandボタンをクリック
ターミナルでプロジェクトディレクトリに移動
claude でClaude Code CLIを起動
クリップボードの指示コマンドを貼り付けてEnter

これだけで、Claude CodeがURLをfetchして実装準備に入ります。Mac版Claude Code、VSCode拡張、JetBrainsプラグインなど他のインターフェースでも同じコマンドを貼り付ければ動くはずです。

Handoff実行前にgit checkout -b feat/matches-screen-from-designのようなフィーチャーブランチを切っておくこと。既存のmainブランチに直接書き込まれると、気に入らない結果のときに戻すコストが高くなります。

Design枠は消費しない（Code枠のみ課金）

今回の作業前後でClaude Designの週次枠を実測した結果、Handoff後もDesign枠の消費はゼロでした。Claude Codeが fetch する先は静的配信のURLなので、Design側の生成処理は走っていないと理解できます。

代わりにClaude Code側の5時間セッション枠が25%から28%へ3ポイント増加。Max 5xプラン実測で、1本の本格的な統合作業がCode枠の+3%で済む計算になります。Claude CodeのOpus 4.7・Sonnet 4.6・Haiku 4.5のコスト感を踏まえると、個人開発レベルなら十分現実的な消費ペースです。

Claude Codeが自発的にやったこと

指示を投げたあとのClaude Codeの挙動が想像以上に賢く、Handoffの価値の大半はここにあると感じました。

Design成果物fetchと既存コード探索を並行実行

実行開始直後、Claude Codeは「デザインファイル取得と既存コードの探索を並行実施」と宣言し、実際に両方を同時に走らせました。

fetchと既存探索の並行実行ログ

「デザインファイルを取得する」→「gzip圧縮ファイルが保存された。解凍して読む」→「デザインファイル完全に取得できた」
その間に既存プロジェクトのCLAUDE.md・BUGS.md・既存ページ・関連コンポーネントを探索

統合型の実装では、新規資産（Design出力）と既存資産（プロジェクトのコード）の両方を把握しないと計画が立てられません。Claude Codeはこの並行実行を自動で判断していました。

テーマ衝突を検出して逆質問

取得完了後、Claude Codeは「設計に入る前に重要な決定を確認」として、AskUserQuestionツールで逆質問を投げてきました。

テーマ衝突の逆質問画面

デザインはウォームクリーム（#FAF7EF）の明るいテーマですが、既存プロジェクトはネイビー（#0a1628）のダークテーマです。対象ページをどちらに合わせますか？

選択肢として「デザイン通り（明るいクリーム）」「ダークテーマに合わせる」「他の内容を入力」の3択が提示されます。さらに各選択肢には、右カラムに「背景: #FAF7EF（ウォームクリーム）カード: #FFFFFF + 薄影テキスト: #2B2B2B アクセント: #E5A621（ゴールド）→ デザイン通りの見た目になる → 他ページはダークテーマのまま」という帰結説明が付いていました。

指示されていない判断ポイントを自発的に発見して、帰結まで提示して確認を取る挙動です。Design→Code統合の実運用では、この「既存環境との衝突検出」が一番重要なステップだと実感しました。

計画書に既存技術的癖の回避策まで含めてきた

テーマ判断（今回は「デザイン通り」を選択）のあと、Claude Codeは詳細な計画書を提示してきました。

プランレビュー画面

計画書の構成は次の通りです。

Context（作業の前提）
対象ファイル（4ファイルを明示）
カラーパレット（Design出力から抽出した7色）
重要テクニック
メインコンポーネントの新構造（ASCIIアートで描画）
ページ側の変更点
実装手順
再利用する既存資産
検証方法

特に「重要テクニック」の項目が秀逸で、次のように書かれていました。

Tailwindのbg-white等はindex.cssの!importantでダーク上書きされる

インラインスタイル（style={{ background: '#FAF7EF' }}）を使えば!importantの影響を受けない

既存ロジック（API関数・カスタムフック・フィルター関数）はすべて維持

プロジェクトの既存CSSが持つ「!importantでTailwindを上書きする」という技術的癖を読み取り、それを回避する具体的な戦略まで計画段階で組み込んでいます。追加指示に含めていなかった内容を、既存コードを読んで自律的に発見した挙動です。

メインコンポーネントの新構造設計

実装結果の実測

計画を承認してから実装完了までは、逆質問の往復を含めて約1時間弱でした。

変更ファイル4つ・437テスト全パス・ビルド成功

最終的な変更内容は次の通りです。

メインコンポーネント：デザイン通りに全面再設計（トレーナー情報帯・2カラム中央揃え本体・フッター帯・ゴールドグラデーションのリクエストボタン）
ページ側：ページ背景#FAF7EFをインラインスタイルで設定してダークテーマ上書きを回避、countバッジ付きタブフィルター、アイコンボックス付きセクションヘッダー
index.html：Zen Maru Gothic / M PLUS Rounded 1cフォントを追加
テストファイル：クラス名ベースassertionを削除・更新

実装完了メッセージ（437テスト pass）

npm run test:runの結果：437 passed / 0 failed
Viteプロダクションビルド：成功
コミットまで自動で完了

Tailwindクラス名に依存した既存テストをClaude Codeが自律的に書き換えた点が重要です。デザイン変更でTailwindクラスが変わるとテストが壊れやすい問題を先回りして対処しています。

クォータ消費はCode枠+3%のみ

枠	作業前	作業後	消費
Claude Code 5時間セッション（Max 5x）	25%	28%	+3%
Claude Code 週間枠（すべてのモデル）	24%	24%	変化なし
Claude Design週間枠	参考値	参考値	0%（別タスクでの消費は除く）

Design→Codeの受け渡しは静的ファイルのfetchなので、Design側の生成処理は走りません。Code側の実装作業だけが課金対象になる構造です。大規模なリファクタや新機能開発ではなく既存画面の置き換えだったため、Code枠の消費も軽く済みました。

見た目の再現度と既存機能の両立

実装後の対象画面と、他ページの画面を並べると、テーマの封じ込めが機能していることが確認できます。

実装後の対象画面（クリームテーマ）

対象ページ側はDesign出力通りのクリーム色背景とカード、ゴールド系アクセント、丸ゴシック系フォント。既存ロジック（方向フィルター、表示用バッジ、情報帯など）も維持されています。Design出力には無かった既存機能も、既存コードから読み取って再実装してくれた形です。

変更の影響を受けなかった他ページ（ダークテーマ維持）

一方の他ページ側は元のダークネイビーテーマをそのまま維持。インラインスタイルでダークテーマ上書きを封じ込めた戦略が、他ページに一切漏れていません。追加指示に「他ページには影響させるな」と書いていなかったにもかかわらず、Claude Codeが計画段階でこの分離を設計していたことになります。

Design→Codeフローで見えた注意点

3件のDesign検証に続けて今回の統合作業を実行して、実運用で押さえておきたいポイントが見えてきました。

テーマ衝突は必ず起きる想定で計画する

Design側は配色・フォント・余白を独立に設計するため、既存プロジェクトと100%一致するケースはほぼありません。AskUserQuestionで逆質問が来るパターンを想定し、判断材料（既存テーマの色コード・フォント・CSS設計思想）を事前に整理しておくとスムーズです。今回は「index.cssで!important上書き」という癖が事前に整理されていたからこそ、Claude Codeが回避策を提示できた側面もあります。

既存自前コンポーネントの扱いは追加指示で明示する

追加指示欄で「既存自前コンポーネントを再利用する」「Design出力に同等コンポーネントが含まれていても既存版を優先」と明示したことで、Claude Codeは計画段階で再利用リストを作り、Design出力の一部をそのまま活かしつつ既存コンポーネントを維持する判断をしました。明示がなければDesign出力をそっくりそのまま置き換える形になっていた可能性があります。

言語・型設定は追加指示で回避する

Design出力はJavaScriptで来ましたが、プロジェクトによってはTypeScript化を自動で試みる挙動もありうるため、追加指示欄に「JavaScript (.jsx)を維持。TypeScript化しない。」と明記しておくのが安全です。今回はこの一文があったため、Claude Codeは一切TS化を試みず既存のJS構成を尊重しました。

mainブランチには直接適用しない（必ずフィーチャーブランチ）

Handoffの挙動は予測不能な部分があり、最初の1手で既存のmainが壊れるリスクがあります。今回はフィーチャーブランチで作業し、mainへのマージは後日の追加検証フェーズに持ち越しました。Claude Codeを使った個人開発の運用ノウハウはClaude Codeで個人サービスを作った正直な話にまとめてあります。

よくある質問

Q Claude Code CLI以外でもHandoffは使える？: A

使える。ダイアログのタイトルが「Send to local coding agent」となっている通り、ローカルで動くコーディングエージェント全般を対象にしている。Mac版Claude Code・VSCode拡張・JetBrainsプラグインのいずれでも、Copy commandで取得した指示コマンドを貼り付ければ同じ挙動になるはず。今回はCLI経由で実測したが、他のインターフェースでも検証価値はある。

Q Design枠とCode枠、両方消費される？: A

筆者の実測ではDesign枠は消費しなかった。Claude Codeがfetchする先は静的ファイル配信のURLで、Design側の生成処理は走っていないため。Code側の実装作業だけが枠消費の対象になる。大規模な画面生成と統合を繰り返す場合でも、Code枠だけを気にすれば運用できる。

Q 既存の自前コンポーネントとDesign出力が重複したときはどうなる？: A

重複時は追加指示欄の明示に従う。今回は「既存自前コンポーネントを再利用する」「Design出力に同等コンポーネントが含まれていても既存版を優先」と伝えたところ、Claude Codeは計画段階で再利用する既存資産のリストを作り、Design出力の見た目を活かしつつ既存ロジック(API関数・カスタムフック・フィルター関数)はすべて維持する判断をした。明示しなければDesign出力でそっくり置き換えられていた可能性がある。

Q デザインと既存プロジェクトでテーマが食い違ったらどうなる？: A

Claude Codeが計画に入る前にAskUserQuestionツールで逆質問してくる。今回はウォームクリーム(#FAF7EF)のデザインと既存プロジェクトのダークテーマ(ネイビー#0a1628)が衝突し、「デザイン通り」「ダークテーマに合わせる」「他の内容を入力」の3択と、各選択肢を選んだ場合の配色・影響範囲まで提示された。「デザイン通り」を選んだ結果、計画書にはindex.cssの!importantによるダーク上書きをインラインスタイルで回避する対策まで盛り込まれていた。指示していない判断ポイントを自発的に見つけて確認を取ってくる挙動だ。

Q Handoffで受け取ったコードは既存スタックに合わせてくれる？: A

ある程度合わせてくれる。追加指示で「Tailwind CSS v3を維持」「CSS変数を尊重」と明示すれば、Design出力が異なるスタイリング方式だったとしても変換する挙動になる。ただし100%自動調整されるわけではないので、計画書レビュー時に「既存スタックとの整合が取れているか」を筆者が確認する工程は必須。

Q Handoffを実行する前にやっておくべき準備はありますか？: A

必ずフィーチャーブランチを切ってから実行してください。Handoffの挙動には予測できない部分があり、mainに直接書き込まれると戻すコストが高くなります。筆者はgit checkout -b feat/matches-screen-from-designで作業しました。あわせて追加指示欄に対象ファイル・既存資産の優先方針・言語設定を書くと計画の精度が上がります。

最後に：受け渡しの安全設計とClaude Codeの現場対応力

今回の統合作業ではっきりしたのは、受け渡し方式が読み取り専用で安全なことと、Claude Codeがテーマ衝突や既存コードの技術的癖まで拾って計画に反映する対応力の高さだ。

Handoff to Claude CodeはAPI経由のURLフェッチ方式で、DesignとCodeのファイルシステムを直接繋がない安全な設計
Design枠は消費せず、Code枠のみ+3%で本格的な既存プロジェクト統合が完了した実測値
テーマ衝突・既存コード癖・テスト更新などの「実運用で必要な判断」を、Claude Codeが計画段階で自発的に拾ってくれる

Design単体の検証は前回の記事で完結しましたが、本当の価値はDesign→Code handoffによる「初稿生成→実装まで一本化される体験」にあると実感しました。次はClaude Code v2.1.114時代の他の新機能も/powerup入門あたりと繋げて試していく予定です。

一次情報に当たりたい場合は、Anthropic公式のClaude Design発表記事{target=”_blank” rel=”noopener noreferrer”}、Opus 4.7の仕様をまとめたAnthropic APIドキュメント{target=”_blank” rel=”noopener noreferrer”}、Claude Code公式ドキュメント{target=”_blank” rel=”noopener noreferrer”}の3つを確認するのが早い。