はじめに：毎朝記憶をなくした同僚と働く感覚
Claude CodeやCursorなどのAIエージェントと開発していると、こんな体験をしたことはないでしょうか。
昨日あれだけ議論して、設計方針を固めて、ようやく実装に入ったのに——
今日また新しいセッションを開いたら、AIは昨日のことを何も覚えていない。
自分「このバグを直してほしい」
AI「承知しました！まず現在のプロジェクト構成を教えていただけますか？」
自分「……（また一から説明か）」
これが毎日繰り返される。プロジェクトが大きくなるほど、説明にかかる時間も増えていく。
これは AIのコールドスタート問題 と呼べる現象で、LLMがセッションをまたいで記憶を持てない構造的な制約から生まれます。
世の中のコンテキスト管理にまつわる既存手法の考え方をベースに、どんなAIエージェント（Cursor、Claude Codeなど）でも今すぐ実践できるよう、3層の構造に落とし込んで体系化したのが、今回ご紹介するドキュメント設計パターン「Warm Boot Protocol」です。
コールドブートとウォームブート
コンピューターには2種類の再起動があります。
- コールドブート：電源を完全に切ってから起動。ゼロから立ち上げる。
- ウォームブート：シャットダウンせず再起動。前の状態を引き継いで素早く立ち上がる。
AIセッションは毎回コールドブートです。昨日の文脈も、決めた方針も、何も引き継がれない。
Warm Boot Protocol はこれをウォームブートに変えます。
新しいセッションを開いたAIが、プロジェクトのドキュメントを読むだけで即座に「今どういう状況か」を把握し、説明不要で作業を開始できる状態をつくる——そのためのドキュメント設計パターンです。
解決策：3層のドキュメント構造
Warm Boot Protocol は、以下の3層構造でドキュメントを整理します。
┌─────────────────────────────────┐
│ Layer 1: エントリポイント層 │ AI設定ファイル（CLAUDE.md 等）
│ セッション開始時に自動で読まれる │ → ai-context.md と progress.md を読むよう誘導
└────────────────┬────────────────┘
│
┌─────────┴──────────┐
↓ ↓
┌──────────────┐ ┌──────────────┐
│ Layer 2a │ │ Layer 2b │
│ ai-context │ │ progress.md │
│ .md │ │ │
│ 資料インデックス│ │ 現在の文脈 │
│（安定・変化小） │ │（タスク・方針）│
└──────┬───────┘ └──────────────┘
│
↓
┌─────────────────────────────────┐
│ Layer 3: 詳細資料層 │ 各機能の README・仕様書等
│ 必要なときだけ参照する │ → 実装方法・設計・パラメータ等
└─────────────────────────────────┘
Layer 1：AI設定ファイル（CLAUDE.md など）
Claude Codeなら CLAUDE.md、Cursorなら .cursorrules のように、多くのAIツールにはセッション開始時に自動で読み込まれる設定ファイルがあります。
ここに書くのは 最小限の誘導だけ です。
## 作業開始時の参照先
- 開発資料インデックス: `ai-context.md` を必ず読むこと
- 進捗・残課題: `progress.md` を読むこと
このファイルにすべてを詰め込みたくなりますが、それはやめましょう。AI設定ファイルはグローバルで一元管理したいケースが多く、プロジェクト固有の情報を書き込むほど管理が大変になります。「次に何を読むか」だけを書く のが正解です。
Layer 2a：ai-context.md（資料インデックス）
「このプロジェクトで何かあったときに、どの資料を見ればいいか」を一覧にしたファイルです。
# AI Context
## 機能Aに関する資料
| 資料 | 目的 |
|---|---|
| `docs/feature-a/README.md` | 概要・実装手順 |
| `docs/feature-a/spec.md` | 詳細仕様 |
## 機能Bに関する資料
| 資料 | 目的 |
|---|---|
| `docs/feature-b/README.md` | 概要・デザイン編集の手順 |
このファイルの特徴は 変化が少ない こと。資料の場所はめったに変わらないので、一度書いたらほとんど触らなくて済みます。タスクが変わるたびに更新が必要な progress.md とは役割が明確に分かれています。
Layer 2b：progress.md（現在の文脈バッファ）
AIに「今どういう状況か」を伝えるファイルです。タスク管理ツールというより、「AIへのブリーフィング資料」 と捉えると正確です。
# Progress
> 開発資料インデックスは `ai-context.md` を参照。
## 残課題
### 機能Aのバッチ連携（優先度：高）
実装手順は `docs/feature-a/README.md` を参照。
- [ ] image_params の変換層を実装する
- [ ] バッチからの呼び出しを実装する
## 方針・保留判断
- 集計方式は案Aで稼働中。3ヶ月後にデータが揃ったタイミングで案Bへの切り替えを検討。
書くべき内容は3種類です。
- 残課題・次のアクション
- 設計方針・判断保留中の事項
- 背景や経緯のメモ（「なぜこうなっているか」）
逆に、完了済みタスクの詳細手順は残しません。コードや git log に残るので、progress.md に書き続けると肥大化するだけです。
Layer 3：詳細資料（README・仕様書など）
各機能の README や仕様書です。必要なときだけ参照します。
ここで重要なのは 「AIフレンドリーに書く」 こと。人間向けの資料とAI向けの資料は、書き方が違います。
| 人間向けの書き方 | AIフレンドリーな書き方 |
|---|---|
| 「良い感じに進めてください」 | 「必ずこの順序で作業すること」 |
| 手順が暗黙知になっている | 「なぜこの順序か」の理由を書く |
| 「README参照」 | 「README の『デザイン編集の手順』セクション参照」 |
| アンチパターンが書いていない | 「〜はしないこと」を明示する |
AIは曖昧な指示を受けると「良い感じ」に解釈しようとしますが、その解釈が意図と外れることがあります。理由を明示する と、AIは手順を守りやすくなります。
3つの設計原則
原則1：変化速度でファイルを分離する
| ファイル | 変化速度 |
|---|---|
| AI設定ファイル（CLAUDE.md） | 低（規約が変わるとき） |
ai-context.md |
低（資料が増減するとき） |
progress.md |
高（タスクが変わるたび） |
| 詳細資料（README等） | 中（機能が変わるとき） |
変化速度の違うものを同じファイルに書くと、頻繁な変更のたびに安定した情報まで触ることになります。よく書き換える progress.md と、滅多に変わらない ai-context.md を分けているのはこのためです。
原則2：ホップ数は最大2回まで
AIが資料をたどる深さは浅いほどよいです。
良い例: CLAUDE.md → ai-context.md → 詳細資料（2ホップ）
悪い例: CLAUDE.md → A.md → B.md → C.md → 詳細資料（4ホップ）
間接参照が深くなるほど、どこかで読み飛ばされるリスクが増えます。
原則3：progress.md に完了済みの詳細記録を残さない
完了したタスクの設計メモや手順を progress.md に書き続けると肥大化し、「今何が残っているか」が見えにくくなります。完了した内容はコード・コミットメッセージ・詳細資料に残るので、progress.md からは削除して「現在地」を保ちましょう。
チケット管理ツールを使っている場合は？
LinearやGitHub IssuesなどのチケットをMCPでAIと連携しているケースも増えています。その場合、タスク管理は外部ツールに任せることができます。
| 情報の種類 | progress.md のみ | 外部ツール（MCP）併用 |
|---|---|---|
| タスク・残課題 | progress.md に記載 | 外部ツールのチケットで管理。AIがMCP経由で参照 |
| 設計方針・保留判断 | progress.md に記載 | チケットには書きにくいため progress.md に残す |
| 担当者・期日・ステータス | 向かない | 外部ツールが得意 |
外部ツールを使う場合でも、progress.md はなくなるわけではありません。「チケットに起票するほどではない文脈情報」の置き場として機能し続けます。
# Progress
> タスク管理は Linear を参照（MCP連携済み）。
## 方針・保留判断
- 集計方式は案Aで稼働中。3ヶ月後にデータが揃ったタイミングで案Bへの切り替えを検討。
- 外部APIのレート制限により、バッチ間隔を現在15秒に設定している。
チームが大きくなるほど、progress.md は「タスク管理ファイル」から「AIへの文脈ブリーフィング資料」という本来の役割に純化されていきます。
やりがちな失敗パターン
❌ AI設定ファイルに全部書く
# CLAUDE.md（やりがちな例）
- 機能Aの資料は docs/a.md
- 機能Bの資料は docs/b.md
- 機能Aの実装手順は...
- タスク1は完了、タスク2は残っていて...
AI設定ファイルをグローバルで一元管理している場合、プロジェクト固有の情報をここに書き込むたびに管理が大変になります。
❌ progress.md に完了済みの詳細を残す
達成感から書き残したくなりますが、完了した内容は削除が正解です。「今どういう状況か」だけを残しましょう。
❌ タスクに詳細資料へのリンクがない
## 残課題
- [ ] 機能Aを実装する ← どこを見ればいいかわからない
タスクだけ書いてあっても、AIはどの資料を読めばいいかわかりません。必ず「実装手順は docs/feature-a/README.md 参照」のように誘導を書きましょう。
導入チェックリスト
新しいプロジェクトに Warm Boot Protocol を導入するときの確認リストです。
-
AI設定ファイルに
ai-context.mdとprogress.mdへの誘導を書いた -
ai-context.mdをリポジトリルートに作成した -
progress.mdをリポジトリルートに作成した -
progress.mdの冒頭にai-context.mdへの誘導を書いた - 各タスクに詳細資料へのリンクを書いた
- 詳細資料に「どの順序でやるか」と「なぜか」を書いた
- AI設定ファイルとリポジトリ管理ファイルを分離した
まとめ
Warm Boot Protocol は、ファイルを3種類用意するだけです。
| ファイル | 役割 |
|---|---|
CLAUDE.md（AI設定ファイル） |
「次に何を読むか」だけを書く |
ai-context.md |
「どの資料がどこにあるか」の地図 |
progress.md |
「今どういう状況か」のブリーフィング |
これだけで、新しいセッションを開いたAIが「現状を教えて」と言わずに作業を始められるようになります。
毎朝記憶をなくした同僚と働く感覚から、引き継ぎが完璧な同僚と働く感覚へ。
ぜひ試してみてください。