AIエージェントの「文脈崩壊」を防ぐ ― ファイルベース永続プランニング入門（planning-with-files 実践）

背景と概要

2026年9月、長時間の自律タスクをAIエージェントに任せる開発者の間で、コンテキスト崩壊が深刻な課題となっていました。Claude CodeやCodexなどのツールで数時間に及ぶタスクを実行すると、会話履歴がモデルのコンテキストウィンドウを超過し、自動圧縮や手動の/clearによってエージェントが当初の目標や中間判断を喪失してしまうのです。

この問題に対し、開発者コミュニティから「planning-with-files」と呼ばれる軽量な対策が提案されました。タスク計画、調査メモ、進捗ログをplan.md、research.md、progress.mdという3つのMarkdownファイルに永続化し、毎ターンの開始時にそれらを再注入することで、エージェントの記憶と目標を復元する手法です。当初はClaude Codeのプラグインとして公開され、npxコマンドで他のエージェント環境にも容易に導入できることから、急速に注目を集めました。

この手法は、Claude CodeやCodex CLIを長時間の自律タスクに活用する中級以上の開発者を主な対象としており、低コストで高い信頼性を提供します。

深掘り分析

この手法の有効性は、大規模言語モデルエージェントのアーキテクチャ上の制約を巧みに回避する点にあります。数十万トークンのコンテキストウィンドウでも、数時間のタスクでは不足しがちです。標準的な圧縮機構（スライディングウィンドウや要約）は細粒度の状態を不可逆的に破棄しますが、ファイルベースの永続化はファイルシステムを外部の監査可能な長期記憶として利用します。

3つのファイルは明確な役割を担います。plan.mdはタスクの分解、マイルストーン、現在のフェーズを保持し、research.mdは収集した参考資料やAPIドキュメントの断片、意思決定の根拠を保存します。progress.mdは完了したステップ、発生した問題とその解決策を時系列で記録します。各ターン開始時にこれらの内容をシステムプロンプトとして注入することで、論理的に全コンテキストを復元します。

ベクトルデータベースを用いた検索拡張記憶と比較すると、ファイル方式は追加の埋め込みモデルやインフラを必要とせず、ほぼゼロコストで導入できます。また完全に決定的であり、開発者はいつでもファイルを開いてエージェントの「思考過程」を確認できるため、デバッグや手動介入が容易です。単純な会話要約と異なり、構造化されたMarkdown形式は詳細な情報と論理関係を保持し、要約に伴う情報の歪みを回避します。

業界への影響

この手法の採用は、長時間タスクの失敗率を大幅に低減し、開発者がより複雑なエンドツーエンドの作業をエージェントに委任することを促しています。複数リポジトリにまたがるリファクタリング、数日間にわたる技術調査、自動化されたDevOpsパイプラインなどがその例です。これによりClaude CodeやCodex CLIの実用価値が直接的に高まり、プロフェッショナルなソフトウェア開発への浸透が加速しています。

また、この実践は主要なエージェントプラットフォームの状態管理における欠陥を露呈させ、AnthropicやOpenAIに組み込みの状態管理機能を求める圧力となっています。Claude Codeチームは既にこのプラグインのフィードバックに注目しており、将来的に公式のチェックポイント復旧や設定可能な永続化機能が統合される可能性があります。

より広範なエコシステムでは、LangChainやAutoGPTといったフレームワークが再検討されています。これらは以前、ベクトルストアや単純なバッファに依存していましたが、ファイルベースプランニングのミニマリズムと即効性が、「明示的で解釈可能なファイルベース」の記憶パラダイムへの移行を促しています。この変化は、CursorやWindsurfのような次世代エージェントIDEの設計にも影響を与える可能性があります。

今後の展望

短期的には、3ファイルパターンの特殊化が進むと予想されます。研究エージェント向けの文献ノートファイル、自動テスト向けのテストケース状態ファイル、複数エージェントの協調作業向けの共有計画ファイルなどが登場するでしょう。ツールチェーンもこれらのファイルを自動生成・管理する方向に進化し、将来のエージェントフレームワークの標準機能となる可能性があります。

注目すべきシグナルとして、Claude Codeがカスタマイズ可能なテンプレートを備えたネイティブのファイル永続化を統合するかどうか、OpenAIのCodex CLIやGitHub Copilot Workspaceが類似のチェックポイント機構を導入するかどうか、そして新興のエージェントIDEがファイルベースプランニングをインタラクションモデルにどのように組み込むかが挙げられます。

コンテキストウィンドウが数百万トークンに拡大しても、明示的なファイル永続化の価値は減じません。タスク状態ファイルはエージェントの目標集中を助け、中断後のシームレスな復旧を可能にし、人間に監査可能な意思決定の軌跡を提供します。より深いレベルでは、planning-with-filesはAIエージェント工学の中核的課題、すなわち信頼性の低い確率的生成と信頼性の高い決定論的状態管理を橋渡しするという課題に取り組んでいます。最も古く最も安定した情報媒体であるファイルは、この二つの世界を結ぶ理想的な架け橋となるかもしれません。