「いい感じに作って」と言って、3 回目で破綻する

Claude Code に「いい感じにログイン画面を作って」と頼む。それなりのコードが出てくる。動く。ここまでは気持ちいい瞬間です。

問題は 2 回目の修正からです。「ボタン位置を変えて」と頼むと、 意図とズレた変更 が混ざる。3 回目には別ファイルまで触り始めて、スパゲッティ化する。5 回目は「最初から作り直したほうが早い」状態。

心当たりがある方は多いと思います。私は 5 プロジェクト並行している中で、何度かこの罠にハマりました。

Vibe Coding が破綻する理由は、AI の能力不足ではありません。 指示に構造がない ことです。本記事では、Claude Code で複数プロジェクトを安定運用するための 6 つの定義書 + 3 つの記憶ファイル の実装パターンを整理します。

ドキュメント・ファースト開発の全体像。CLAUDE.md をハブに、6 つの定義書と 3 つの記憶ファイルが連携する

なぜ「いい感じ」は通じないのか

人間のチームメンバーに「いい感じに作って」と丸投げしたら、経験豊富なエンジニアなら質問してきます。「何を作るんですか」「どの技術スタックですか」「既存コードとの整合性は」。

ところが AI は、特に指示されないかぎり質問せずに、 自分の解釈で「いい感じ」 に作り始めます。あなたの「いい感じ」と AI の「いい感じ」が一致する保証はゼロです。

ここでドキュメント・ファースト開発の発想が出てきます。コードを書く前にドキュメントを書く。AI に「いい感じ」を任せるのではなく、 「こういう感じ」を定義してから任せる 。

6 つの定義書

ドキュメント・ファースト開発の核心は、コードを 1 行も書く前に 6 つの定義書を準備することです。

1. PRD.md(要件定義書)

何を作り、何を作らないかを明確にする ドキュメントです。

# PRD.md - タスク管理アプリ
## 作るもの
- ユーザー登録・ログイン (メール + パスワード)
...

「作らないもの」の定義が肝です。AI は指示されていない機能も「良かれと思って」追加することがあります。スコープ外を明記すれば、 不要な実装の暴走 を防げます。

2. APP_FLOW.md(画面遷移)

## 画面一覧
1. ログイン (/login)
2. ダッシュボード (/dashboard)
...

画面遷移を絵的に書くより、 テキストでパスとイベントを明示 するほうが AI には伝わります。

3. TECH_STACK.md(技術スタック)

## フロントエンド
- Next.js 14.2.x (App Router)
- TypeScript 5.4.x (strict mode)
...

最後の「注意」が重要です。AI は問題解決のために新しいライブラリを提案しがちです。技術スタックを明記し、 逸脱を防ぐ ことで、依存関係の無秩序な増加を防ぎます。

4. FRONTEND_GUIDELINES.md(フロントエンド設計指針)

デザインシステム、コンポーネント規約、CSS 方針などをまとめます。「色はこの 3 つ、フォントはこれ、ボタンは shadcn/ui」と書くだけでも、AI の出力ブレが大きく減ります。

5. BACKEND_STRUCTURE.md(バックエンド構造)

DB スキーマと API 設計をテーブル形式で書きます。

### tasks
| カラム | 型 | 説明 |
|--------|-----|-----|
...

スキーマがズレるとデータ層全体が崩れます。最初に固めて、変更時は必ずこのファイルから更新するルールにします。

6. IMPLEMENTATION_PLAN.md(実装計画)

## Phase 1: 基盤構築
1. Next.js 初期化 + TypeScript 設定
2. Prisma セットアップ + DB スキーマ作成
...

各フェーズの末尾に 検証ポイント を設けます。「Phase 1 を実装して」と指示し、完了後に検証する。問題なければ「Phase 2 へ」。 段階的な実装と検証 のサイクルが、品質を担保します。

3 つの記憶ファイル

6 つの定義書が「何を作るか」を定義するのに対し、3 つの記憶ファイルは AI の記憶を維持する ためのものです。

1. CLAUDE.md(プロジェクトルール)

AI が最初に読む、プロジェクトの憲法です。6 つの定義書への参照を集約すると効果的です。

# CLAUDE.md
## プロジェクト概要
タスク管理 Web アプリ (Next.js 14 + TypeScript + Prisma)
...

「罠」セクションは効きます。私が何度もハマった「やらかし」を予防的に書き出すと、AI が先回りして対処してくれるようになります。

2. progress.md(進捗記録)

セッション間の 記憶喪失を防ぐ外部メモリ です。

# progress.md
## 完了
- [x] Phase 1: 基盤構築
...

/clear

した後や新規セッションを開始するとき、このファイルがあれば どこまで進んだかが 3 秒で分かる 。私は Claude Code に自動更新させています。

3. lessons.md(教訓の蓄積)

エラーから学んだ教訓を記録し、 同じミスを繰り返さない自己改善ループ を作るファイルです。

lessons.md

2026-02-15

• Prisma の findUnique でリレーション先を取得するには include が必須
  ...

繰り返される教訓は、CLAUDE.md の「罠」セクションに昇格させます。プロジェクトレベルのルールとして定着させると、新規セッションでも自動的に守られます。

認知負債の防御

ここで一つ重要な概念を導入します。認知負債 (Cognitive Debt) です。

技術的負債 (Technical Debt) は広く知られています。急いで書いたコードが将来の開発を遅くする現象です。認知負債はその拡張概念で、AI に任せすぎてコードの状況を誰も把握できなくなる 状態を指します。

技術的負債：コードの品質が低い → 修正コストが上がる
認知負債：コードの理解者がいない → 修正方法がわからない

Vibe Coding の最大のリスクは、この認知負債です。AI が生成したコードを理解せずに積み上げると、あるとき 誰も (AI を含めて) 全体像を把握できない 状態に陥ります。コンテキストウィンドウに収まりきらない、理解されていないコードの山。

ドキュメント・ファースト開発は、認知負債への防御策です。6 つの定義書は 人間が理解している状態を維持する ためのツールです。コードの詳細は AI に任せても、何を作っているか・なぜそう作っているか・どこまで進んだかは常に人間が把握する。

タスク分解の粒度

認知負債を防ぐもう一つの実践は、適切なタスク分解 です。

# ❌ 粒度が大きすぎる
「EC サイトのバックエンドを全部作って」
# ❌ 技術スタック分割 (結合時に壊れやすい)
...

タスクの粒度は 「結合テストができる最小単位」 が目安です。一つのタスクが完了した時点で、実際に動作を確認できること。これにより、認知負債の蓄積を防ぎつつ、AI の生産性を最大化できます。

段階的開示の実践

6 つの定義書と 3 つの記憶ファイルを用意したら、次は Claude Code にどう渡すか を考えます。

すべてを一度にコンテキストに注入するのは非効率です。認証機能を実装しているとき、デプロイ手順の情報は不要です。必要な情報を、必要なタイミングで、必要な量だけ 渡す。これが段階的開示です。

# Phase 1 の実装時
$ claude
> PRD.md と TECH_STACK.md と BACKEND_STRUCTURE.md を読んで、
...

CLAUDE.md に参照を書いておけば、Claude Code が自分でファイルを読みに行くこともあります。ただ、明示的に「このファイルを読んで」と指示する方が、確実にコンテキストに含まれます。

私のドキュメント・ファースト実践

複数プロジェクトを並行していて感じるのは、ドキュメントは 「AI のため」ではなく「自分のため」 だということです。

5 つのプロジェクトを同時に進めていると、先週触ったプロジェクトの仕様を忘れることがあります。そのとき、PRD.md を読めば「何を作っていたか」を思い出せる。progress.md を見れば「どこまで進んだか」がわかる。

これは AI の記憶喪失への対策であると同時に、人間の記憶の有限性への対策 でもあります。

布石を打つように、ドキュメントを先に整備する。その布石が、1 ヶ月後の自分を助ける。3 ヶ月後のチームメンバーを助ける。Claude Code のセッション開始時に、最初の数秒で正しいコンテキストを提供する 。

まとめ

• Vibe Coding が破綻するのは AI の能力不足ではなく、指示に構造がないから
• 6 つの定義書 (PRD・APP_FLOW・TECH_STACK・FRONTEND_GUIDELINES・BACKEND_STRUCTURE・IMPLEMENTATION_PLAN) で「何を・どう作るか」を明確化
• 3 つの記憶ファイル (CLAUDE.md・progress.md・lessons.md) でセッション間の記憶喪失を防ぐ
• 認知負債を防ぐには「結合テストができる最小単位」でタスクを分解
• 段階的開示で、必要なドキュメントを必要なタイミングで読み込ませる
• ドキュメントは「AI のため」ではなく「自分のため」に書く

Claude Code は「いい感じ」を引き受けてくれる相棒ではなく、「こういう感じ」を実装してくれる相棒 です。前者を望むかぎり破綻し、後者を提供すれば伸びる。境界線は、ドキュメントを先に書くか後に書くかだけです。

参考文献

• 梶谷健人 (@kajikent), 6 定義書 +3 記憶ファイル紹介 - X (2026-02-16)
• Anthropic, Claude Code best practices
• 関連記事：CLAUDE.md の書き方完全ガイド