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

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

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

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のチャットに手動で投入する代替手段です。

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

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

Fetch this design file, read its readme, and implement the relevant
aspects of the design.
https://api.anthropic.com/v1/design/h/<project-id>?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に貼り付ける

流れはシンプルです。

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

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

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は「デザインファイル取得と既存コードの探索を並行実施」と宣言し、実際に両方を同時に走らせました。

• 「デザインファイルを取得する」→「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を削除・更新

• 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で個人サービスを作った正直な話にまとめてあります。

よくある質問

まとめ

3点に集約します。

• 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”}が参考になります。