Claude CodeでIDDを実践したら一度破綻した — 機能単位分割とCLAUDE.mdで立て直すまで
はじめに
前の記事で「IDDのつもりでSDDをやっていた」という話を書いた。最後にこう書いた。
次に試すなら、Why/What を渡した後はタスクの確認すらせず一度流してみようと思っている。
実際にやってみた。結果から言うと、一度盛大に破綻した。その破綻の記録と、そこから何を変えたかをまとめておく。
やったこと
オープンソースのカードゲーム「DEBUG-ZERO」の開発で、Claude Code に一気に全実装を任せてみた。
指示の構造はシンプルで、「こういうゲームを作りたい、このルールで動けばいい」という Why + What だけを渡した。How は完全に Claude 任せ。前の記事でたどり着いた「IDDっぽい渡し方」の実験だ。
何が起きたか
結果は予想より派手に崩れた。
出来上がったものをブラウザで開いて確認すると、カードがプレイできない。プレイできてもターンが相手に回らない。ゲームとして成立していない状態だった。
「じゃあここを直して」と Claude に伝える。修正が入って再確認する。今度は別の箇所が壊れている——このループが延々と続いた。
問題
原因
カードがプレイできない・ターンが回らないなどゲームとして成立していなかった
実装範囲が広すぎて Claude 自身もコンテキストを見失っていた
バグ→修正→別のバグのループに陥った
修正の正しさを確かめる手段がなく、人間が目視でデバッグするしかなかった
トークンを猛烈な勢いで消費した
一度のセッションで抱えるコンテキストが膨大になった
JS が HTML に内包された
実装方針を渡していなかったため手っ取り早い選択をされた
このループが本当に消耗した。Claude がバグを直すたびに別の箇所が壊れる。デバッグの主役が完全に自分になってしまい、「AI に加速してもらっているはずが、自分がデバッガーになっている」状態に陥った。
なぜこうなったのか
原因を整理すると、二つに絞られる。
1. 「確認できる単位」を無視した
一気に全実装を渡すと、Claude は全体像を保持したまま実装を進める。実装範囲が広いほど、どこかでコンテキストを見失う。動作確認のタイミングがないまま積み上げた実装は、崩れたときの影響範囲も大きい。
2. テストが存在しなかった
テストがなければ、バグの発見は人間の目視になる。Claude が修正してもそれが正しいかどうかを確かめる手段がない。「動いてそう」という状態が積み重なっていく。
出てきた考え方：1タスク = 1確認できる単位
破綻から見えてきたのは、 「どこからが IDD でどこからが SDD か」という境界は、事前に何を決めるかではなく、「1タスク = 1確認できる単位かどうか」 だということだ。
IDD の柔軟さを保ちつつ崩れない構造にするには、機能単位の分割とテストの自動化がセットでないといけない。
立て直したフロー
理想のフローはこうなった。
機能単位でタスク分割
↓
1機能を実装
↓
Claude がテストを書く
↓
テストパス確認
↓
次の機能へ（テストが落ちた場合は人間に確認せず Claude が自律修正）「テストが落ちたら Claude が自律的に修正する」という構造を作ることで、人間のデバッグ工数をゼロに近づけるのが目標だ。
CLAUDE.md に反映したこと
今回の気付きをそのまま CLAUDE.md に書いた。LLM は明示されていない判断を自分で下す。その判断は「手っ取り早い方向」に向かいやすいので、やること・やらないことを明示する必要がある。
やることに追加したこと
- 1機能ずつ実装する。実装したら必ずテストを書いてパスさせてから次の機能へ進む
- ファイルは必ず分割する（JS・CSS を HTML に内包しない）
やらないことに追加したこと
- 複数機能を一度に実装しない
実装の進め方セクションを新設
- 機能単位でタスクを分割し、確認を取る
- 1タスク = 1確認できる単位（エンドポイント1本、UI1画面など）
- 実装 → テスト作成 → パス確認 → 次のタスクへ
- テストが落ちた場合は人間に確認せず自律的に修正する
実際のファイルはこうなる。
# DEBUG-ZERO CLAUDE.md
## このプロジェクトについて
数字カードと四則演算で目標値をゼロにするカードゲーム DEBUG-ZERO の
オンライン対戦 Web アプリ。
OSSとして公開し、アプリ自体をデバッグするという行為を
ゲームの世界観に取り込むことを目指している。
## 技術的な制約
- Cloudflare Workers / Durable Objects を使う
- フレームワークは Hono を使う
- 理由：Cloudflare のエコシステムを学ぶため、Hono コミュニティとの接点を持つため
## AIへの行動指針
### やること
- 実装前に必ず意図を確認する
- タスクリストを生成したら、実行前に確認を求める
- 不明点は実装を止めて質問する
- **1機能ずつ実装する。実装したら必ずテストを書いてパスさせてから次の機能へ進む**
- **ファイルは必ず分割する（JS・CSS をHTMLに内包しない）**
### やらないこと
- 要件定義書・設計書・詳細設計書を勝手に生成しない
- ディレクトリ構成を勝手に決めない
- node_modules を読まない
- How の判断を勝手に下さない
- **複数機能を一度に実装しない**
## 実装の進め方
1. 機能単位でタスクを分割し、確認を取る
2. 1タスク = 1確認できる単位（エンドポイント1本、UI1画面など）
3. 実装 → テスト作成 → パス確認 → 次のタスクへ
4. テストが落ちた場合は人間に確認せず自律的に修正する
## 渡すもの・渡さないもの
渡すもの：なぜ作るか、何ができればいいか
渡さないもの：どう実装するか（それはAIが提案する）
## 世界観・デザイン方針
ゲームの世界観はコンピュータの内側、デバッグの現場。
- 通常時：ダーク・サイバー・青いネオン
- レイド戦時：ダーク・サイバー・赤い警告色（緊張・危機感）
配色はUIの気分転換ではなく、ゲーム状態をプレイヤーに伝える手段。まとめと留保
- 「一気に全実装」は IDD ではなく、ただの丸投げだった。 IDD が機能するのは「1タスク = 1確認できる単位」という粒度管理があってこそ
- テストの自動化は IDD の必要条件に近い。 テストがなければデバッグの主役が人間になり、AI による加速が逆転する
- CLAUDE.md に実装フローを書くことで LLM の行動が変わった。 ただし 100% 守られるわけではないし、「CLAUDE.md が良かったのか、モデル精度が上がっているのか」はまだ切り分けできていない
今のところ機能単位分割 + テスト義務付けの構造でかなり安定してきた。「機能単位の粒度感はどう決めるか」はプロジェクトの規模や複雑さによって変わるので、引き続き調整しながら確認していく。