Claude Code + Claude Design 連携ワークフロー：handoff bundle から Astro 実装を自動化

📖 背景

Anthropic が 2026-04-17 にリリースした Claude Design は、プロンプトから UI プロトタイプ・スライド・モックアップを生成する Web 製品（Research Preview 段階）。完成物を handoff bundle として書き出し、Claude Code に渡すことで Astro コンポーネント実装まで自動化できる。

CTS-KB プロジェクトでは 写真・イラスト素材は Adobe Firefly を継続利用し、UI プロトタイプ・バナー・OGP は Claude Design を併用する方針を採用した。本記事では .claude/ 配下に配置した agent / skill / slash command を組み合わせ、Claude Design → Claude Code の連携をどう運用に落とし込んでいるかを紹介する。

⚡ Claude Code ワークフロー概要

.claude/ 配下に agent / skill / slash command を配備している。

/image-optimize — 画像の webp 変換・リサイズ
/import-handoff / @design-handoff — Claude Design handoff bundle の Astro 化
apply-design-system — Design System 準拠チェック（Astro/HTML/CSS 編集時）

以下、各アセットの配置と使い方を順に解説する。

🗂️ ディレクトリ構成

.claude/ ハーネス配下に連携用のアセットを追加している。

.claude/
├─ settings.json                          # 画像処理ツール等の権限許可
├─ agents/
│  └─ design-handoff.md                   # @design-handoff エージェント
├─ commands/
│  ├─ image-optimize.md                   # /image-optimize
│  └─ import-handoff.md                   # /import-handoff
└─ skills/
   └─ apply-design-system/SKILL.md        # Design System 検証スキル

第 2 層（Skills）・第 3 層（Agents）・第 4 層（Settings）に責務を分離することで、UI 変換作業のときだけ関連ルールがロードされる構成にしている。詳細はClaude Code 7層ハーネスエンジニアリングを参照。

🖼️ `/image-optimize` — 画像最適化コマンド

public/images/ 配下の画像をリサイズ・トリミング・webp 変換する slash command。

使い方:

/image-optimize public/images/hero/new-hero.png

最適化基準:

用途	推奨サイズ	webp quality
ヒーロー画像	1920x1080 以下	85
サムネイル・カード	800x600 以下	80
OGP 画像	1200x630	85
ロゴ・アイコン	SVG/PNG 維持	—

前提ツール: sharp-cli（devDependency として導入済み）。npx sharp で呼び出し可能。

# 導入コマンド（初回のみ、このプロジェクトでは導入済み）
npm install -D sharp-cli

# バージョン確認
npx sharp --version

セキュリティ注記: sharp-cli@5.2.0 は依存する glob@11.x に high severity の脆弱性（command injection via -c/--cmd）が報告されている。ただし本プロジェクトでは glob CLI の -c フラグを使わないため実害なし、devDependency のため本番ビルドにも影響しない。npm audit fix --force は sharp-cli@4.2.0 への降格（破壊的変更）を伴うため実行しない。

📦 `/import-handoff` — Claude Design 取り込みコマンド

Claude Design が出力した handoff bundle を Astro コンポーネントに変換する slash command。

使い方:

/import-handoff ~/Downloads/claude-design-handoff-20260420

処理内容:

bundle 内の HTML / CSS / 画像を解析
Design System（src/styles/global.css の @theme）と照合
インライン CSS を Tailwind v4 のユーティリティクラスへ置換
単一ページは src/pages/、再利用パーツは src/components/ に配置
画像を public/images/ へ配置し、webp 化を案内
sm: / md: / lg: breakpoint を活用したモバイルファースト CSS に調整

単一画面の取り込みであればこのコマンドで十分。HTML/CSS を個別に変換しながら Tailwind v4 化までを一括で行う。

🤖 `@design-handoff` — 専用エージェント

複雑な handoff bundle を専門的に処理するサブエージェント。/import-handoff より高度な変換（複数画面の一括処理、既存コンポーネント再利用判定）を任せられる。

呼び出し例:

@design-handoff ~/Downloads/new-article-template-bundle を取り込んでください。
既存の記事ページ（src/layouts/ArticleLayout.astro）と同じ構成に寄せてほしい。

slash command との使い分けは「単一画面なら /import-handoff、複数画面や既存コンポーネント再利用判定が必要なら @design-handoff」が目安。

🎨 `apply-design-system` — Design System 検証スキル

新規・編集したコンポーネントが Design System に準拠しているかを検証するスキル。Astro / HTML / CSS の変更時に自動的に起動候補となる。

検証項目:

ハードコードされた hex カラー → Tailwind クラスへの置換提案
インラインスタイル → Tailwind 化の提案
既存コンポーネントの再利用可否
モバイルファーストのレスポンシブ設計

handoff bundle の取り込み直後に起動することで、Claude Design 側でハードコード化されたスタイルが本プロジェクトの @theme と整合しているかを最終確認できる。

🔁 推奨フロー

新規ページ追加の場合

1. Claude Design で UI プロトタイプ生成（Web UI）
   ├─ Design System は本プロジェクトのコードベースから自動抽出
   └─ チーム内レビュー・調整
2. Handoff bundle をダウンロード
3. Claude Code で /import-handoff <bundle path>
   └─ 複雑な場合は @design-handoff エージェント
4. public/images/ に配置した画像を /image-optimize で webp 化
5. apply-design-system スキルで最終チェック
6. npm run dev で動作確認
7. git commit → デプロイ

写真素材のみ追加の場合（従来フロー維持）

1. Claude でプロンプト作成
2. Adobe Firefly で生成・ダウンロード
3. public/images/<カテゴリ>/ へコピー
4. /image-optimize で webp 変換
5. 参照箇所の拡張子を更新

Claude Design は UI プロトタイプに特化しており、写真・イラスト素材の生成品質では Firefly に軍配が上がる。両者を用途で使い分けることで、生成物の一貫性とブランド統一を両立している。

🖌️ Firefly で生成した実例: CTS-KB トップページヒーロー

本サイトのトップページ（src/pages/index.astro）で使用しているヒーロー画像は、Firefly で生成したダークブルー基調の等角イラスト。@theme で定義した bg-primary (#0a2540) との親和性が高く、AI・データ・ナレッジを象徴するモチーフ（地球・書籍・チャート・ネットワーク）を一枚に統合している。

配置: public/images/hero/hero-knowledge.webp（webp）/ hero-knowledge.avif（avif）
生成ツール: Adobe Firefly
最適化: /image-optimize で webp / avif に変換済み

Claude Design でこの種の装飾イラストを生成すると、UI プロトタイプ寄りのフラットな表現になりがちで、トーンが KB のブランドと揃わない。一方 Firefly はスタイル指定（等角・サイバー・ダークブルー）に忠実で、コーポレートサイトとのブランド統一に向く。

🌈 カラー規約リファレンス

Tailwind v4 の @theme 定義（src/styles/global.css）。KB は可読性重視のライト配色をベースとし、ヘッダー/フッターのみコーポレートサイト（www.cts-g.com）と共通のダークブルーで統一している。

ブランド共通（ヘッダー/フッター）

Tailwind クラス	値	用途
`bg-primary`	#0a2540	ヘッダー/フッター
`bg-secondary`	#0f4c75	アクセント背景
`bg-accent`	#2563eb	リンク・ボタン (blue-600)
`bg-accent-hover`	#1d4ed8	ホバー (blue-700)

コンテンツエリア（ライトモード）

Tailwind クラス	値	用途
`bg-bg-main`	#f8fafc	メイン背景 (slate-50)
`bg-bg-card`	#ffffff	カード・記事背景
`bg-bg-sidebar`	#f1f5f9	サイドバー背景 (slate-100)
`text-text-main`	#1e293b	メインテキスト (slate-800)
`text-text-sub`	#64748b	サブテキスト (slate-500)
`border-border`	#e2e8f0	ボーダー (slate-200)

ダークモード上書き

html.dark 配下で bg-main / bg-card / text-main などが slate 系の暗色に切り替わる。Claude Design が独自のダークモード CSS を出力した場合、本プロジェクトの @theme ダークモード定義と二重化する可能性があるため、/import-handoff はライトモード変換のみを行い、ダークモードは既存 @theme 定義に委譲する運用とした。

重要: tailwind.config.mjs は存在しない。Tailwind v4 の CSS-first 設定方式を採用しており、テーマ変更は @theme ブロックを直接編集する。Claude Design 側で生成された tailwind.config.js を無条件に取り込むと設定が二重化するため、/import-handoff は設定ファイルを無視し @theme のみを正とする。

🔐 権限設定（settings.json）

.claude/settings.json で以下のコマンドを事前承認済み。

npx sharp-cli / npx @squoosh/cli / cwebp / magick（画像処理）
astro / npm run（ビルド・開発サーバ）
public/** / src/** の読み書き

権限を追加する場合は allow 配列に追記する。UI 変換のたびに権限プロンプトが出ると作業が止まるため、画像処理系の CLI はあらかじめ allowlist に含めておくのが運用上の定石。

🔗 外部リソース

Claude Design（アプリ本体） — プロトタイプ生成・handoff bundle ダウンロード（claude.ai サイドバーの「Design」からもアクセス可）
Claude Design 公式発表
Anthropic Claude Code ドキュメント

📝 まとめ

Claude Design と Claude Code の連携は、UI 生成 → 実装 → 最適化までのパイプラインをハーネスの 3 種類のアセット（slash command / agent / skill）に分散配置することで、各ステップが単独でも再利用可能な形になっている。Firefly による写真素材生成との併用で、CTS-KB のブランド一貫性を保ちながら UI 作業を自動化できる。