問題
本当のボトルネック：探索コスト
500テーブルのアプリケーションでは、あらゆるAIタスクがls、grep、ファイル読み取りの探索から始まる。 1行のコードを書く前に数千トークンを消費し、 探索結果がコンテキストウィンドウを埋め、 実装に使える余地を圧迫する。
コンテキストウィンドウはストレージではない。認知負荷だ。
200Kウィンドウに195Kトークンを詰め込めば、推論する余地がなくなる。
解決策
コンテキストエンジニアリングの3原則
コンテキストを無限のストレージとして扱うのをやめよう。コードと同じようにエンジニアリングしよう。
分離 (Isolation)
各タスクに必要最小限のコンテキストを提供する。ファイルサイズではなく責務でスコープを切る。
OAuth2モデル + 関連コントローラ
連鎖 (Chaining)
作業をステージに分割する。会話履歴全体ではなく、成果物を受け渡す。
会話履歴 (30Kトークン) ではなく
余裕 (Headroom)
100%容量で動作させない。モデルが実際に思考するためのスペースを確保する。
推論のための余裕を残す
インサイト
コードベースはパレート分布に従う
コミット履歴はべき乗則を示す：少数のファイルが変更の大半を占める。 毎回すべてを検索する必要はない。 頻繁に変更される領域の知識をplanに蒸留すれば、 探索コストは劇的に下がる。
500ファイル走査 → ~15,000トークン
1つのplanを読む → ~300トークン
紹介
Plan Stack
実装計画をファーストクラスの成果物に
/clearのたびに調査と決定が消えていく代わりに、 Plan
Stackは軽量で再利用可能なplanとしてそれらを保存する。
50ファイルの調査が300行のplanになる。6ヶ月後、1つのplanを読むだけで、50ファイルを読み直してアーキテクチャの意図を再発見するより遥かに早い。
- + AIコンテキスト用に圧縮された調査結果
- + 人間のための長期記憶
- + コンテキストリセット後の信頼できる起点
- + 追加インフラ不要 — Gitで管理され、AIにも人間にも読める
LLMが読むガイド
planはClaude Codeが読んで従う実装ガイドになる。セッションごとにアーキテクチャを説明し直す必要がない。
AI が500ファイルを盲目的にgrep ではなく
知識の継承
似た修正？AIが過去のplanから設計判断を見つける。人間の説明は不要。
毎回パターンを再発見 ではなく
なぜRAGではなくdocs/？
構造化されたマークダウンは検索性が高い。Gitで自然にバージョン管理。 ベクトルDB不要、パイプライン不要。AIも人間も同じ情報源を読む。
RAGパイプライン → 埋め込み → 検索 → オーバーヘッド ではなく
ワークフロー
調査、計画、実行、レビュー
各フェーズがコンテキストエンジニアリングの原則を適用する。ワークフローは知識が蓄積される自己強化ループを作る。
調査
AIがdocs/plans/で類似実装を検索。planがあれば数百トークンで対象ファイルを特定。
なければ探索を実行し、結果を新しいplanとしてコミット。
計画
AIが構造化されたplanを生成、コード前に人間がレビュー。 誤った実装にトークンを費やす前に意図のずれを検出。
Headroom実行
planがコンテキストリセットをまたいで意図を運ぶ。/clearして再開 — 再説明も再探索も不要。
レビュー
PRにplanがあることでAIと人間の両方がレビュー可能。 設計意図と実装の乖離を検出。
Isolation + Chainingパターン
リセットを受け入れる
コンテキストの劣化は避けられない。Plan Stackは/clearを損失から機能に変える。
作業を再開することなく、0%コンテキストから再スタート。
はじめる
1行で始める
CLAUDE.mdにこの指示を追加:
Search docs/plans/ for similar past implementations before planning.この1行が自己強化ループを作る:
-
1. AIがまず
docs/plans/をチェック（数百トークン） - 2. plan発見 → 対象ファイルを即座に特定
- 3. planなし → コードベースを探索
- 4. 探索結果をplanとしてコミット → 知識ベースが成長
誰に優しいか
チームのあらゆる役割のために
Plan StackはAI最適化だけではない。ソフトウェア開発に関わるすべての人のワークフローを改善する。
AIフレンドリー
探索トークン削減、コンテキスト汚染防止、意図の明示。 AIは探索ではなく実装にトークンを使う。
15,000トークンでコードベースをgrep ではなく
レビュアーフレンドリー
すべてのPRにplanがある。レビュアー — 人間もAIも — コードを読む前に設計意図を把握できる。
コード変更から意図を推測 ではなく
チームフレンドリー
知識が蓄積・継承される。新メンバーはplanを読んで過去の設計判断を理解。 オンボーディングが加速する。
10人に聞く → バラバラの回答 ではなく
学ぶ
コンテキストエンジニアリングをマスターする
初心者から上級者まで無料コース。各レッスンは1〜2分、時間を大切にするエンジニアのために設計。