「いい感じに作って」はなぜ5回目で崩壊するのか -- コードの前に書く6つの定義書と3つの記憶ファイル
「いい感じにログイン画面を作って」とClaude Codeに指示して、いい感じのログイン画面が出てきたとき、私は天才になった気がしました。その全能感は5日後、自分のプロジェクトのコードを自分で説明できなくなった時点で終了しました。
1回目の生成は動く。2回目の修正で方向が少しズレる。3回目でスパゲッティ化が始まり、5回目には「最初から作り直した方が早い」状態になる。この崩壊カーブに心当たりがある方は多いはずです。
原因はAIの能力不足ではありません。指示に構造がない ことです。処方箋はシンプルで、コードを書く前に6つの定義書を書く。いわゆる「ドキュメント・ファースト開発」です。2026年6月時点のClaude Code公式メモリ機能とどう役割分担するかも含めて、私の運用をまとめます。
スペック駆動開発と何が違うのか
スペック駆動開発(SDD)は「実装前に仕様を合意するプロセス」の話で、ドキュメント・ファースト開発はそれを ファイル体系として何をどう置くか に落とした実装論です。SDDが「仕様を書け」と言い、ドキュメント・ファーストは「この6ファイルをこの分担で書け」と言う。本記事は後者です。
人間のチームメンバーに「いい感じに作って」と丸投げしたら、経験豊富な人なら「何を作るんですか」と聞き返してくれます。AIは聞き返さずに作り始めます。あなたの「いい感じ」とAIの「いい感じ」が一致する保証はどこにもない。だから先に文書で一致させます。
6つの定義書
コードを1行も書く前に、以下の6ファイルを用意します。
1. PRD.md: 何を作り、何を作らないか
# PRD.md -- タスク管理アプリ
## 作るもの
- ユーザー登録・ログイン(メール+パスワード)
- タスクのCRUD、ラベル付け、期限設定
## 作らないもの(スコープ外)
- チーム共有機能(v2で検討)
- モバイルアプリ(v1はWebのみ)
- 外部サービス連携効くのは「作らないもの」の方です。AIは指示されていない機能を良かれと思って追加することがあります。スコープ外を明記しておくと、頼んでいないリアルタイム同期機能が突然生えてくる事故を防げます。
2. APP_FLOW.md: 画面遷移とユーザーフロー
画面一覧と主要フローをテキストで書きます。「ログイン画面 → 新規登録クリック → フォーム入力 → ダッシュボード」程度の粒度で十分です。
3. TECH_STACK.md: 技術スタック定義
# TECH_STACK.md
## フロントエンド
- Next.js 14.2.x (App Router)
- TypeScript 5.4.x (strict mode)
## バックエンド
- Prisma 5.x / PostgreSQL 16
## 注意: 上記以外のライブラリを追加しないこと最後の1行が本体です。AIは問題解決のために新しいライブラリを提案しがちで、放置すると依存関係が無秩序に増えます。
4. FRONTEND_GUIDELINES.md: デザインシステムとコンポーネント規約
カラーパレット、フォント、コンポーネントの配置ルール。これがないと画面ごとに微妙に違うボタンが量産されます。
5. BACKEND_STRUCTURE.md: DBスキーマとAPI設計
テーブル定義とエンドポイント一覧。AIにスキーマを推測させて後から直すより、正解を先に渡す方が速い。
6. IMPLEMENTATION_PLAN.md: フェーズ分割と検証ポイント
## Phase 1: 基盤構築
1. プロジェクト初期化
2. 認証機能
3. 検証: 登録→ログイン→ログアウトが動作
## Phase 2: コア機能
4. タスクCRUD API
5. 検証: タスクのライフサイクル一周が動作各フェーズ末尾の検証ポイントが品質を担保します。「Phase 1を実装して」と指示し、検証してから「Phase 2へ」。この段階実行が、5回目の崩壊を防ぐ心臓部です。
3つの記憶ファイル
6つの定義書が「何を作るか」なら、3つの記憶ファイルは「AIの記憶を維持する」ためのものです。
CLAUDE.md: 参照ハブ兼プロジェクトルール
6つの定義書への参照をここに集約します。
# CLAUDE.md
## 定義書
- 要件: docs/PRD.md
- 技術スタック: docs/TECH_STACK.md(記載外のライブラリ追加禁止)
- 実装計画: docs/IMPLEMENTATION_PLAN.md
## 罠
- If: 新しいAPIルート追加 → Then: BACKEND_STRUCTURE.mdも更新CLAUDE.mdの設計論そのものはCLAUDE.mdは結局Context Engineeringだった話に書いたので、ここでは「ハブにする」ことだけ覚えてください。
progress.md: セッション間の進捗記録
「何が終わり、いま何をしていて、次は何か」を記録する外部メモリです。/clear の後や翌朝のセッション開始時に、このファイル1枚で文脈が復元できます。私は「タスクが完了したらprogress.mdを更新してから終了して」とCLAUDE.mdに書いて、更新自体をClaude Codeに任せています。
lessons.md: 教訓の蓄積
「Prismaの findUnique でリレーション取得には include が必要」のような、エラーから学んだ教訓を日付つきで貯めます。何度も繰り返される教訓はCLAUDE.mdの「罠」セクションに昇格させます。
2026年6月の論点: auto-memoryで手動運用は不要になったのか
ここが、元になった書籍の章を書いた時点から一番進化した部分です。Claude Codeには現在、公式のauto-memory機能があります。MEMORY.mdをインデックスとして起動時に先頭200行(または25KB)を読み込み、トピック別ファイルは必要時にオンデマンドで参照します。さらにバックグラウンドで動くAuto Dreamが、セッションの記録を読み返して矛盾した記憶を削除し、重複をマージします。AIが寝ている間に記憶を整理するわけです。私より健全な睡眠習慣だと思います。
では手動の記憶ファイルは廃止していいのか。私の整理はこうです。
| ファイル | 役割 | auto-memoryで代替できるか |
|---|---|---|
| CLAUDE.md | 明示的ルール(禁止事項・規約) | できない。ルールは宣言するもの |
| progress.md | タスクの進捗状態 | 部分的。ただし「次にやること」の正確さは手動が上 |
| lessons.md | 学習された教訓 | かなり代替可能。auto-memoryの得意領域 |
auto-memoryが学習するのは「パターン」です。ビルドコマンド、コードスタイル、ハマったバグの回避策。lessons.mdの役割はここに吸収されつつあります。一方、「Phase 2のタスク編集モーダルが未実装」という 状態 の管理は、観測ではまだ手動progress.mdの方が確実です。auto-memoryは要約の過程で「どこまで終わったか」の精度が落ちることがあるからです。
つまり2026年6月時点の最適解は「lessons.mdはauto-memoryに任せ始めてよい、CLAUDE.mdとprogress.mdは手で書く」。3ファイル運用が2.5ファイル運用になった、くらいの進化です。
認知負債: ドキュメントは誰のためか
技術的負債の拡張概念として 認知負債(Cognitive Debt) という言葉があります。AIに任せすぎて、コードの状況を誰も把握できなくなる状態です。技術的負債は「コードの品質が低くて修正コストが上がる」、認知負債は「コードの理解者がいなくて修正方法がわからない」。Vibe Coding最大のリスクはこちらです。
防御策が2つあります。1つはここまで書いた定義書群。コードの詳細はAIに任せても、「何を・なぜ・どこまで」は常に人間が把握している状態を保つ。
もう1つは タスク分解の粒度 です。
# NG: 粒度が大きすぎる
「ECサイトのバックエンドを全部作って」
# NG: 技術レイヤー分割(結合時に壊れる)
「まずDBだけ」→「次にAPIだけ」→「最後にUIだけ」
# OK: 機能単位で分割
「ユーザー登録機能を作って(DB + API + UI + テスト)」目安は「結合テストができる最小単位」。1タスク完了ごとに実際に動作確認できる粒度なら、理解されていないコードの山は積み上がりません。
まとめ
- Vibe Codingが崩壊するのはAIの能力不足ではなく、指示に構造がないから
- 6つの定義書(PRD/APP_FLOW/TECH_STACK/FRONTEND_GUIDELINES/BACKEND_STRUCTURE/IMPLEMENTATION_PLAN)で「何を・どう作るか」を先に固定する
- 3つの記憶ファイルのうち、lessons.mdはauto-memory(MEMORY.md + Auto Dream)に任せ始めてよい。CLAUDE.mdとprogress.mdは手動が確実
- タスクは「結合テストができる最小単位」で分解する
正直に言うと、ドキュメントを先に書くのは面倒です。私も最初の頃は「定義書を書く30分でコードが書けるのに」と思っていました。いまは逆です。定義書の30分は、5回目の作り直しの5時間を買い取るための保険料でした。保険としては破格に安い。
この記事はZenn Book『Claude Code実践入門』の第5章をベースに、2026年6月時点の情報で再構成したものです。CLAUDE.md設計、チーム運用、セキュリティまで含めた全19章は Claude Code実践入門 にまとめています。
この記事は役に立ちましたか？