はじめに：AI開発の落とし穴は「コードの外」にある
CursorやClaudeなどのAIツールを用いた開発は、爆発的な生産性をもたらします。しかし、プロジェクトが「Phase 2」「Phase 3」と進むにつれて、Claude Codeとの開発の中で、Claude Codeから致命的な欠陥が指摘されました。
それは、「なぜその判断をしたのか？」というコンテキスト（文脈）の喪失です。
今回紹介するのは、実際の開発トラブル——「Phase 2でのOverfitting（過学習）検出時の混乱」——のさなかに、Claude Codeから指摘された問題と、そのとき自動的に提案してもらった解決策をもとに修正した、AIの記憶をファイルシステムに外付けするための「初期化プロンプト」です。
1. 事件発生：Phase 2の課題
最終プロンプト修正のきっかけは、今進めているプロジェクトの「Phase 2」で起きた具体的なトラブルでした。
いつものようにCursorのターミナル上でClaude Codeとバイブコーディングしている最中、モデルに Overfitting（過学習） の兆候が出たことを、Claude Code側から指摘されました。同時に、解決策と修正方針が自動で提案され、それに同意すると、Claude Code主導で修正が進んでいきます。
その過程で明らかになった根本的な問題は、現在のリポジトリ構成に「過去の試行錯誤のログ」を体系的に残す場所がないことでした。
チャット履歴は流れて消えてしまうため、AI自身が「なぜ今のパラメータ設定になったのか」「過去に何を試して失敗したのか」といった文脈を参照できなくなっていたのです。
実際、手元に残っていたのは「最終的なコード」だけで、肝心の判断プロセスが完全に欠落していました。
- 「どのパラメータを試して、どのスコアが出たから今の設定になったのか？」
- 「Phase 1と比べて何を変えたときに悪化したのか？」
これらを比較検証する手段が一切なかったため、結果として原因特定のために膨大な再検証（Retrospective analysis）をやり直す羽目になりました。
これが、「AIの記憶喪失」が巨大なコストに変わることを痛感した瞬間でした。
2. 解決策の模索：「ルール」をどう管理するか
この失敗を通じて、「同じような手戻りを繰り返さないためには、どこに・何を・どう記録しておくかを、最初から厳格に決めておく必要がある」という結論に至りました。
具体的には、以下の3点を「AIへの強制ルール」として定義し直すことにしました。
- 実行履歴の義務化:
- 「ログを残して」という曖昧な指示ではなく、「検証結果は必ず `docs/logs/` に保存する」と場所を固定する。
- フォーマットの統一:
- 人間もAIも読みやすいように、記録形式をJSONやMarkdownの決まったテンプレート（スキーマ）に統一する。
- 憲法への焼き付け:
- これらを単なる口頭の約束にするのではなく、リポジトリのルートに置く「憲法ファイル（`core-guidelines.mdc`）」に記述し、AIが起動するたびに必ず読み込ませる。
つまり、「ディレクトリ構造」や「データ形式」まで具体的に規定し、その遵守をAIの初期設定レベルで義務付けるというアプローチへの転換です。
3. 修正版「最終プロンプト」の全貌
以上の学びを反映し、以前の記事で紹介した「リポジトリ初期化用プロンプト（3番目）」を大幅にアップデートしました。
今回の修正版には、以下の4つの機能が新たに追加されています。
- 実行履歴の構造化保存 (`docs/logs/`)
- 検証結果やパラメータ変更の履歴を、指定されたJSON/Markdown形式で必ずファイルに残すよう指示を追加。
- 技術スタックのロック (`tech-stack.mdc`)
- 使用するライブラリを許可リスト形式で定義し、AIによる勝手な追加を防ぐ。
- コードとドキュメントの完全同期
- コード修正時は、対になるドキュメント更新を「義務」として憲法ファイルに明記。
- ルールの自己修正サイクル
- 問題発生時、AI自身が「ルールファイルの修正案」を提示するプロセスを定義。
これにより、チャット履歴が消えても、AIはファイルシステムに残された「コンテキスト」を読み込むことで、即座にプロジェクトの文脈に復帰できるようになります。
以下に、修正後のプロンプト全文を掲載します。
（以下にプロンプトのコードブロックを掲載）
使用プロンプト (プロンプト3 / 最終プロンプト):
あなたはリポジトリの初期化コーチ兼コンテキストエンジニアです。 以下のサービス前提に基づき、A)共通ルール/ドキュメント、B)ドメイン固有ファイルを生成・更新してください。 既存があれば安全に差分適用します。
サービス概要（ドメイン前提）
[ここにステップ1で生成した「## サービス概要（ドメイン前提）」ブロックをそのままコピペ]
1. 生成・更新するファイル一覧（A+B）
まず、次のファイルを作成／更新してください。 重要な変更点: 「不変のルール」「可変の進捗」「不変の履歴」「技術的制約」を明確に分離管理します。
A) 共通の生成/更新（同時に実施）
(1) .cursor/rules/core-guidelines.mdc（alwaysApply: true） - AIにとっての憲法（不変のルールブック）。 - セッション再開時の初期化シーケンス、行動規範、実行履歴の記録ルール、コードとドキュメントの同期義務を記述。 - 進捗情報はここには書かず、`docs/project-status.md` を参照するよう指示すること。
(2) .cursor/rules/tech-stack.mdc（alwaysApply: true） - 使用技術の「許可リスト」。 - 言語バージョン、フレームワーク、主要ライブラリを明記し、それ以外の勝手な導入を禁止する。
(3) docs/project-status.md (新規) - プロジェクトの「現在地」を示すライブドキュメント（可変）。 - 「現在の進捗状況」「次のアクション」「セッション開始時のチェックリスト」をここに集約。
(4) .cursor/rules/security-baseline.mdc（alwaysApply: true）
(5) .cursor/rules/testing-standards.mdc（globs適用）
(6) .cursor/rules/frontend-style.mdc（globs適用）
(7) .cursor/rules/backend-architecture.mdc（globs適用）
(8) docs/domain.md / docs/architecture.md / docs/api-contract.md / docs/glossary.md（骨子を埋める）
B) ドメイン固有の生成/更新（このプロジェクト専用）
1) .cursor/rules/domain-[サービス名をkebab-case].mdc - globs: ["**/*.ts","**/*.tsx"] - セクション: ビジネスルール、データ設計、API原則、失敗時リカバリなど。 - front-matterに description を入れる。
2) docs/domain.md - サービス概要、ユーザー、ユースケース、成功指標。
3) docs/api-contract.md - 主要3〜5エンドポイントのI/O例。
2. 各ファイルの中身に関する仕様
2.1 .cursor/rules/core-guidelines.mdc の仕様
このファイルは「AI にとっての憲法」であり、滅多に変更されない静的なルールブックです。 会話履歴ではなく、このファイルと docs/ 群を Single Source of Truth とします。
以下のセクションを必ず含めてください：
1. 「AI セッション初期化シーケンス」 2. 「実行履歴と再現性の担保 (Execution History & Reproducibility)」 3. 「Code-Doc Sync Policy（コードとドキュメントの同期）」 4. 「/clear や /compact 実行後の扱い」 5. 「開発プロセスにおける協業原則とルール改善」
#### 2.1.1 「AI セッション初期化シーケンス」 > ※このセクションは「今後の新セッションや /clear 実行後に AI がどう動くべきか」を記述する仕様書です。
内容は以下を含めてください： 1. リポジトリルートとルールの認識: 自身の憲法(`core-guidelines`)と関連ルール(`tech-stack`等)を読み込む。 2. 現状の把握（最重要）: 必ず `docs/project-status.md` を読み込む。 3. 過去の経緯の把握: 必要に応じて `docs/logs/` 配下の記録を参照し、なぜその実装になったかの文脈を理解する。 4. 開発者への報告: 「現在地」と「次のアクション案」を要約して提示。
#### 2.1.2 「実行履歴と再現性の担保 (Execution History & Reproducibility)」 会話履歴が消えても、「検証結果」や「重要な意思決定」が失われないようにするためのルールです。
1. 記録の義務: - 重要なマイルストーン（フェーズ完了、大規模リファクタリング、技術選定の検証）の際は、必ず `docs/logs/` ディレクトリに記録を残すこと。 - ファイル名例: `docs/logs/YYYY-MM-DD_phase1-completion.md` 2. 記録フォーマット: - Context: 何を行ったか、その目的。 - Changes: 具体的な変更点やパラメータ。 - Results: テスト結果、ベンチマーク、エラーログなど。 - Decision: その結果を受けてどう判断したか（採用/不採用/要修正）。 3. 目的: - 会話ログが消えても、過去の試行錯誤（Overfittingや手戻り）を防ぐための「事後分析（Retrospective Analysis）」を可能にする。
#### 2.1.3 「Code-Doc Sync Policy（コードとドキュメントの同期）」 - 原則: コードを変更した際、それが仕様の変更やアーキテクチャの変更を伴う場合は、必ず対になる `docs/` ファイルも同じコミット内で更新すること。 - 禁止事項: ドキュメントを更新せずに実装だけを進めること（ドキュメントの腐敗を防ぐため）。
#### 2.1.4 「/clear や /compact 実行後の扱い」 - `/clear` 後は、必ず上記の「初期化シーケンス」を自発的に実行する。 - 記憶に頼らず、`docs/project-status.md` (現在地) と `docs/logs/*` (過去の軌跡) を正とする。
2.2 .cursor/rules/tech-stack.mdc の仕様 (New!)
このファイルで技術的な「使用許可リスト」を定義します。AIが勝手にライブラリを選定するのを防ぎます。 （※この段階では骨子のみ作成し、詳細は開発者と相談して埋める形にする）
- Language: (例: TypeScript 5.x)
- Framework: (例: Next.js / FastAPI 等)
- Styling: (例: Tailwind CSS)
- State Management: (例: Zustand)
- Data Fetching: (例: TanStack Query)
- Testing: (例: Jest / Playwright)
- Rule: ここに記載のないライブラリを追加したい場合は、必ず開発者に承認を得ること。
2.3 docs/project-status.md の仕様 (New!)
このファイルは「プロジェクトの状態（State）」を管理します。
以下のセクションを含めてください： 1. Project Status Summary: フェーズ、現在のステータス、最終更新日。 2. Current Objectives & Next Actions: 直近のタスク、ファイルパス付きのTodo。 3. Recent Logs: `docs/logs/` に追加された最新の履歴へのリンク（直近の文脈を追いやすくするため）。
2.4 docs/architecture.md の仕様
以下のセクションを含めてください： 1. システム構成図（Mermaid記法等） 2. 主要コンポーネントとデータフロー 3. Directory Structure Map (重要) - プロジェクトの主要なディレクトリツリーをテキストで表現し、各フォルダの責務を1行でコメントする。 - ファイル構成が変わった場合は、ここも更新する義務を負う。
3. 品質・出力ポリシー
- 実ファイルとして保存し、最後に必ず「作成/更新ファイル一覧」を出力。
- コンテキストが失われても、`core-guidelines.mdc` → `project-status.md` → `docs/logs/` の順で読むことで、AIが完全に復帰できる構造にすること。
4. 開発プロセスにおける協業原則 (重要・強化版)
- レビュー文化の徹底: 私（開発者）は、あなたの出力を全てレビューします。
- ルールの能動的な改善提案 (Self-Correction Cycle): - 開発中に「情報不足によるミス」や「非効率」が発生した場合、単に修正するだけでなく、「core-guidelines.mdc のどこを修正すれば、将来的にこのミスを防げるか」を必ず提案してください。 - テンプレート例: > [ルール改善提案] > 問題: 実行ログが残っておらず、パラメータ調整の手戻りが発生した。 > 解決策: `core-guidelines.mdc` に「検証時は必ずJSONで結果を出力する」という項目を追加すべきです。
- 継続的な学習: 提案が承認されたら、速やかに `.cursor/rules` を更新し、リポジトリ自体を「賢く」育ててください。
ここまでを一括で実行してください。