planning-with-files

ファイルを使った計画

ディスク上の Markdown ファイルを作業メモリとして使用します。

クイックスタート

1. 計画ファイルを作成する — /plan を使用するか、テンプレートから手動で作成します
2. 目標、フェーズ、重要な質問を含む task_plan.md を作成する
3. 調査結果と決定事項を記録する findings.md を作成する
4. セッションの記録用に progress.md を作成する
5. 決定を下す前に計画を読み直す — 注意の中に目標を呼び戻します
6. 各フェーズの後に更新する — ステータスを記録し、エラーをログに残します

使用する場面

• 複数の手順があるタスク（3 フェーズ以上）
• 多数の検索が必要な調査プロジェクト
• 複数のファイルを含むプロジェクトの構築や作成
• 多数のツール呼び出し（10 回超）にまたがるタスク
• 目標を見失うと大きな損失につながる作業
• 複数のセッションにまたがる可能性があるタスク

使用しない場面

• 簡単な質問や、すぐに答えが見つかる調べもの
• 範囲が明確な単一ファイルの編集
• 5 回未満のツール呼び出しで完了するタスク
• 実装を伴わない会話のやり取り

基本パターン

Context Window = RAM (volatile, limited)
Filesystem     = Disk (persistent, unlimited)

Anything important gets written to disk.

ツール呼び出しを何度も行うと、最初の目標は注意のウィンドウから徐々に薄れていきます。task_plan.md を読むと、目標を思い出せます。これが、ファイルベースの計画で最も重要なパターンです。

ファイルの役割

ファイル	目的	更新するタイミング
task_plan.md	フェーズ、進捗、決定事項	各フェーズの完了後
findings.md	調査、発見、決定事項	発見があったら必ず
progress.md	セッションログ、テスト結果	セッション中を通じて

3 つのファイルはすべて、プラグインディレクトリではなくプロジェクトのルートに配置します。

重要なルール

1. まず計画を作成する

task_plan.md を作成せずに、複雑なタスクを始めてはいけません。これは必須です。計画は永続的なメモリです。

2. 2 アクションルール

検索、閲覧、読み取りを 2 回行うごとに、重要な調査結果をすぐに findings.md に保存します。マルチモーダルコンテンツ（画像、ブラウザーの結果、PDF の内容）はコンテキスト内に保持されないため、失われる前にテキストとして記録します。

3. 決定する前に読む

重要な決定を下す前に、task_plan.md を読み直します。これにより目標とコンテキストが最近の注意のウィンドウに戻り、約 50 回のツール呼び出しの後に生じる「真ん中を忘れる」効果を軽減できます。

[Original goal -- far away in context, forgotten]
...many tool calls...
[Recently read task_plan.md -- gets ATTENTION]
→ Now make the decision with goals fresh in context

4. 実行後に更新する

各フェーズを完了したら、次のことを行います。

• フェーズのステータスを更新する：in_progress → complete
• 発生したエラーを「Errors」テーブルに記録する
• 作成または変更したファイルを progress.md に記録する

5. すべてのエラーを記録する

すべてのエラーを task_plan.md に記録します。試行回数と解決方法を含めます。これにより知識が蓄積され、同じ失敗を繰り返さずに済みます。

## Errors Encountered
| Error | Attempt | Resolution |
|-------|---------|------------|
| FileNotFoundError | 1 | Created default config |
| API timeout | 2 | Added retry logic |

6. 失敗を繰り返さない

ある操作に失敗した場合、次の操作は必ず異なるものにします。試したことを記録し、アプローチを変更します。

if action_failed:
    next_action != same_action

3 回失敗した場合のエラープロトコル

ATTEMPT 1: Diagnose & Fix
  -> Read error carefully
  -> Identify root cause
  -> Apply targeted fix

ATTEMPT 2: Alternative Approach
  -> Same error? Try a different method
  -> Different tool? Different library?
  -> NEVER repeat the exact same failing action

ATTEMPT 3: Broader Rethink
  -> Question assumptions
  -> Search for solutions
  -> Consider updating the plan

AFTER 3 FAILURES: Escalate to User
  -> Explain what you tried (with attempt log)
  -> Share the specific error
  -> Ask for guidance

読み取りと書き込みの判断マトリックス

状況	操作	理由
ファイルに書き込んだ直後	読み直さない	内容はまだコンテキスト内にある
画像や PDF を閲覧した	すぐに調査結果を書き込む	マルチモーダルコンテンツは保持されない
ブラウザーからデータが返された	ファイルに書き込む	スクリーンショットは保持されない
新しいフェーズを開始する	計画と調査結果を読む	コンテキストが古い場合に状況を把握し直す
エラーが発生した	関連ファイルを読む	修正には現在の状態を把握する必要がある
中断後に再開する	計画ファイルをすべて読む	状態を完全に復元する

5 つの質問による再起動テスト

計画ファイルを見て次の質問に答えられれば、コンテキストは十分に保たれています。

質問	回答の参照先
今どこにいるか？	task_plan.md の現在のフェーズ
これからどこへ向かうか？	残りのフェーズ
目標は何か？	計画に記載された目標
何を学んだか？	findings.md
何をしたか？	progress.md

アンチパターン

しないこと	代わりにすること
目標を一度述べたら忘れる	判断の前に計画を読み直す
エラーを隠して黙って再試行する	すべてのエラーを計画ファイルに記録する
コンテキストにすべてを詰め込む	大きなコンテンツはファイルに保存する
すぐに実行を始める	まず計画ファイルを作成する
失敗した操作を繰り返す	試行を追跡し、アプローチを変更する
プラグインディレクトリにファイルを作成する	プロジェクトのルートにファイルを作成する

参考資料

• テンプレート -- 3 つの計画ファイルすべての 初期テンプレート
• 原則 -- このアプローチの背景にあるコンテキストエンジニアリングの 原則
• 例 -- 具体例とエラーからの 復旧パターン