planning-with-files：AI コーディングエージェントの計画を3つのMarkdownファイルでディスクに保持する
AI コーディング エージェントと長時間実行されるタスクのための永続的なファイルベースの計画。クラッシュプルーフのマークダウン プラン、/clear と圧縮後のセッションの回復、コンテキストの腐敗に対するターンごとの再注入、確定的な完了ゲート。マヌス風。 Claude Code、Codex、Cursor、Kiro、OpenCode、およびエージェント スキル標準による 60 以上のエージェント。
ひと目でわかる
- これは何？
- このプロジェクトは、エージェントの実行状態を task_plan.md、findings.md、progress.md に永続化し、毎ターン再注入することで、コンテキスト消失、/clear、圧縮に対応します。
- 誰に向いている？
- ターンをまたぐコーディング作業で計画と発見を Markdown として残したいエージェント利用者に合います。状態を外部ファイルに書けない環境や、厳格なワークフロー管理が必要なチームには追加設計が要ります。
- 商用利用できる？
- できます。MIT は寛容なライセンスで、著作権表示とライセンス表示を残せば、使用・改変・販売が可能です。
- 今もメンテナンスされている？
- されています。最後のコミットは 1 日前です。
- 何の言語で書かれている？
- 主に Python です（GitHub の言語統計による）。
回答はプロジェクトの GitHub データ（最終同期：2026年9月15日）と当サイトの分析に基づくもので、法的助言ではありません。
オープンソース詳細解説
三つの Markdown が持つ状態
planning-with-files は、AI コーディングエージェント向けのスキルで、計画状態をコンテキストウィンドウだけに置かず、ディスクに保存します。タスクに対して、スキルは3つのMarkdownファイルを作成します：task_plan.md はフェーズとチェックボックスを追跡し、findings.md は調査メモと決定を蓄積し、progress.md はセッションログとテスト結果を保持します。README は、コンテキストウィンドウをRAM、ファイルシステムをディスクと見なし、重要なものはすべてディスクに書き込むという原則を説明しています。ファイルは毎ターン開始時に再注入されるため、/clear、クラッシュ、コンテキスト圧縮によって計画が失われることはありません。
task_plan.md の作業分解
README の前後の例は、よくある失敗を示しています：計画ファイルがない新しいセッションはコンテキストがないと述べ、ユーザーにタスクの再説明を求めます。スキルがあれば、エージェントはディスクからファイルを読み取って再開します。注入形式は ===BEGIN PLAN DATA=== と ===END PLAN DATA=== で区切られたブロックで、UserPromptSubmit フックが task_plan.md からコンテキストに書き込みます。プロジェクト自身の内部リカバリベンチマークによると、ファイルがディスクにある新しいセッションは平均5.0ターンで再開できたのに対し、計画方法がない生のエージェントは13.3ターンでした。README はこのベンチマークを内部、著者実行と明記し、方法と限界は docs/evals.md を参照としています。
findings.md に残す発見
README は2つの主要なインストール経路を説明しています。Claude Code では、プラグイン経由でリポジトリをマーケットプレイスに追加し、プラグインをインストールすると、スキル、フック、スラッシュコマンドが含まれます。他のエージェントでは、npx skills add コマンドで Agent Skills 標準を通じてスキルをインストールし、60以上のエージェントをカバーします。README は、プロジェクトの信頼が受け入れられないか、フロントマターのフックがプロジェクトレベルのインストールで登録されない場合、スキル経路はフックなしで終わる可能性があると警告し、フックが必要なユーザーにはプラグイン経路を推奨し、/plan-doctor で検証するよう述べています。また、リポジトリは Claude Code、Codex、Cursor、Kiro、OpenCode などの IDE 別ミラーを提供しています。
progress.md とターン再開
スキルはエージェントの決定フローを定義しています：タスクが3ステップ以上または5回以上のツール呼び出しを必要とする場合は3つのファイルを作成し、学んだ情報は findings.md に追記し、アクションは progress.md に記録し、フェーズ完了は task_plan.md のチェックボックスをオンにし、コンテキストリセット後は全ファイルを再読み込みします。ライフサイクルフックがこれらのステップを機械的にします：README は Claude Code に5つ、Codex に7つ、Pi に8つのフックを挙げ、毎ターンの計画再注入、書き込み後のリマインダー、停止前の完了チェックをカバーしています。/clear 後のセッションリカバリは、アクティブな IDE のセッションストアを確認し、計画ファイルが最後に更新された時刻を見つけ、その後の会話を抽出し、キャッチアップレポートを表示します。
アーカイブとファイルの寿命
v3 ラインは、長時間実行されるエージェントタスク向けの機能を追加しています。自律モードはツール呼び出しごとの計画読み上げを省きますが、ターン開始時の注入は維持します。ゲートモードは、すべての完了条件が同時に満たされた場合にのみブロックする停止ゲートを追加します。セッションキャッチアップは /clear 後に IDE のセッションストアから計画ファイルを再読み込みします。SHA-256 計画認証は task_plan.md をロックし、改ざんされた計画本体を注入時に拒否します。実行台帳はフェーズ遷移を追記専用のJSONLファイルとして記録します。環境変数が動作を制御します：PLANNING_DISABLED=1 はその呼び出しの計画読み取りをすべてスキップし、PLAN_ID は .planning 下の特定の計画に固定し、PWF_INJECT=smart は固定の head -50 注入ウィンドウを、目標、次のステップ、現在のフェーズ、最近の決定に置き換えます。
評価資料が示す限界
README は Anthropic の skill-creator フレームワークを使った評価を報告しています：スキル v2.21.0、モデル claude-sonnet-4-6、日付 2026-03-06。スキルありは30の客観的に検証可能なアサーションのうち29を通過し、なしは2でした。3ファイルパターンは5回中5回守られ、なしは0回。盲検A/B比較は3勝0敗、平均ルーブリックスコアは10.0対6.8。README は、この数値がファイルパターンの忠実度を測定しており、長い自律実行での目標ドリフトではなく、新しいモデルと自律モードの作業はまだこの数値の対象外であると述べています。別の内部リカバリベンチマーク（v1、2026-07-06、著者実行、v3.4.0 対象）は、コンテキスト消去後の再開に必要なターンを測定しました：ファイルあり5.0、生のエージェント13.3。
エージェント運用への適合
README のリポジトリレイアウトは、skills/planning-with-files の下に正規のスキル（SKILL.md、スクリプト、テンプレート、例）と、5つの翻訳バリアント、Agent Skills 標準の .agents/skills パス、IDE 別のミラーディレクトリ、ドキュメント、テストスイート、ルートレベルのファイル（LICENSE を含む）を示しています。プロジェクトは MIT ライセンスで配布されており、著作権は 2026 Ahmad Adi。使用、複製、修正、結合、公開、配布、再許諾、販売の権利を許可し、ソフトウェアは商品性、特定目的への適合性、非侵害を含むいかなる種類の保証もなく「現状のまま」提供されると述べています。ライセンス文は、セキュリティ体制、サポート約束、またはその免責事項以外のことについては触れていません。
編集部の結論
ターンをまたぐコーディング作業で計画と発見を Markdown として残したいエージェント利用者に合います。状態を外部ファイルに書けない環境や、厳格なワークフロー管理が必要なチームには追加設計が要ります。最初に `task_plan.md`、`findings.md`、`progress.md` の更新と再注入を一つの作業で確認してください。
コミュニティノート