罠ごと引き継ぐ 〜Claude Design → Claude Code のハンドオフ設計〜

T E C H TA L K 罠ごと引き継ぐ 〜Claude Design → Claude Code のハンドオフ設計〜 2026/07/28 @unsoluble_sugar

今日話すこと 1 3 趣味のMikuMikuDance動画ポータル サイトを作った話 データ140件の整備まで実質2日 2 4 罠ごと引き継ぐハンドオフで 「デザイン確定〜公開」を1時間で そこで得た設計・運用の学びを紹介

作ったもの：MMD動画ポータル

ポータルの規模と技術構成 5 ファイル 6本 140 件 サイト本体 データパイプライン用 登録動画 HTML+CSS+JS Pythonスクリプト 正データYAMLと1対1 趣味のMikuMikuDance（MMD）動画作品をまとめるポータルサイト ビルド不要の静的サイト（npm依存ゼロ）、正データはYAML 140本のみ手動編集 GitHub Pages + GitHub Actionsでホスティング

開発フローの全体像 見た目の意思決定は Claude Design、git・CI・データ処理は Claude Code ハンドオフ一式（README＝実装仕様＋既知の罠／HTML実体／実データ50件）を出力 して引き継ぎ 「見た目はDesign、実装はCode」と役割を明確に分離

CHAPTER 01 Claude Designフェーズ 見せ方の意思決定

① 「載せないもの」を先に決める 統計情報（再生数など）は載せない ―「作品を見せる場に数字は不要」 載せるのはタイトル・投稿日・キャラ名・シリーズ・クレジット・解説記事リンク 先に「載せないもの」を決めたことで、統計の取得・更新ロジックが最初から不要に。情 報設計もデータモデルも軽くなる

② 既存情報源からデータを抽出 ニコニコ・YouTube：タイトル・投稿 日・キャラ名などを取得 noteマガジン記事：サムネイル・クレジ ット・使用エフェクト情報を抽出 未取得項目はnullとし、段階的なデータ 拡充に対応 抽出結果は詳細モーダルのクレジット欄に反映

③ デザイン2案比較で決定 案A 採用 クリーン版 ポップ版 整理された余白・控えめな配色でまとめる クリーム色背景＋太い黒枠＋ハードシャド ウで視認性と個性を両立

④ 実装の罠を先に踏んで書き残す Claude Designでプレビュー操作 → 実装の詰まりを事前に発見 YouTubeの埋め込みエラー → referrerpolicy="origin" で解決 ニコニコは横型プレイヤー固定 → 縦型ショートも16:9に統一 ハンドオフREADMEに「罠」として明記 → Code側は一度も踏み直さず ニコニコは縦型ショートも16:9レターボックスで表示

CHAPTER 02 Claude Codeフェーズ 公開までの1時間

Phase単位でIssueに分解

Phase1〜3：データ基盤とサイト実装 Phase1 データ基盤 YAML正データ＋ Phase2 → サイト本体実装 （一覧ページ） Phase3 → 動画詳細モーダル 埋め込みプレイヤー build_data.py 生成物への直接編集は禁止、pre-commit hookで同期検査を自動化 ハンドオフHTMLはそのまま流用せず、app / render / modal に責務分離

公開前の最終調整：実機確認とPhase4 ! モーダルを閉じても動画再生が続く ! 開閉時のちらつき ! 無限スクロール時の再描画バグ → Phase4でデプロイ範囲を制御 Phase4：GitHub Actionsで _site/ に載せるファイルだけを列挙してデプロイ。正デー タYAML・Pythonツールはリポジトリに残したまま配信しない

CHAPTER 03 データ140件との格闘 公開後の作り込み

① 未登録データの自動発掘 127 件 128 件 108 本 ニコニコマイリスト YouTubeプレイリスト note記事 scaffold （雛形生成・未登録90件） → match （投稿日・シリーズ補完） → note match/fetch （解説記事照合・クレジット 抽出）

② 誤紐付けへの対応 同一楽曲・異なるキャラの投稿が存在。 候補1件でもキャラ名照合を必須化 共通処理 pick_by_chara を実装し、ド キュメントに明文化 エフェクトはコンテンツツリーの登録名 と既知語彙を照合、なければnullのまま UIごと非表示 照合できたエフェクトのみを一覧表示

モバイル実装でのハマりどころ iOSで絵文字グリフが置換される ヘッダーボタンが2段に折り返す → SVGアイコン化で解決 → モバイルは「@」ボタン1つに集約 モバイルでモーダル開閉時に動画が止まる 縦型ショートレールが場所を取る → 背後の再描画を最適化 → モバイルはデフォルト折りたたみに

継続運用のサイクルを確立 新規投稿 → note記事作成 → scripts/enrich match/fetch → build_data.py → デプロイ 「データの正」と「表示の優先」を分解 （出典はニコニコ, タブはYouTube優先） 後から片方だけ安全に変更できる設計 2サービスをタブで切り替える詳細モーダル

CHAPTER 04 得られた学び

4つの学び 1 3 ハンドオフに「罠」を書き残すと、実 装側は同じ穴を踏まない 実機確認の往復ループが品質を決める 2 4 自動で紐付けた結果は必ず検証する。 一意に見えても誤りは混ざる 「データの正」と「表示の優先」を分 けると、後から片方だけ変えられる

元記事 Claude DesignのハンドオフをClaude Codeで再実装する 〜動画ポータル開発の技術記録〜 zenn.dev/unsoluble_sugar/articles/a4cfe1e4cc9a0d

• https://zenn.dev/unsoluble_sugar/articles/a4cfe1e4cc9a0d