Planning with Files

Manus のように動作します：永続的な Markdown ファイルを「ディスク上の作業メモリ」として使用します。

FIRST: 前のセッションのコンテキストを確認 (v2.2.0)

作業を開始する前に、前のセッションから同期されていないコンテキストがないか確認してください：

# Linux/macOS (python3 または python を自動検出)
$(command -v python3 || command -v python) ${CODEBUDDY_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"

# Windows PowerShell
python "$env:USERPROFILE\.codebuddy\skills\planning-with-files\scripts\session-catchup.py" (Get-Location)

キャッチアップレポートに同期されていないコンテキストがある場合：

1. git diff --stat を実行して実際のコード変更を確認
2. 現在の計画ファイルを読む
3. キャッチアップと git diff に基づいて計画ファイルを更新
4. その後、タスクを進める

重要：ファイルの場所

• テンプレート は ${CODEBUDDY_PLUGIN_ROOT}/templates/ にあります
• あなたの計画ファイル は プロジェクトディレクトリ に置いてください

場所	内容
スキルディレクトリ (${CODEBUDDY_PLUGIN_ROOT}/)	テンプレート、スクリプト、リファレンスドキュメント
あなたのプロジェクトディレクトリ	task_plan.md, findings.md, progress.md

クイックスタート

複雑なタスクを始める前に：

1. task_plan.md を作成 — templates/task_plan.md をリファレンスとして使用
2. findings.md を作成 — templates/findings.md をリファレンスとして使用
3. progress.md を作成 — templates/progress.md をリファレンスとして使用
4. 判断する前に計画を再読 — 注意ウィンドウ内のゴールをリフレッシュ
5. 各フェーズ後に更新 — 完了をマーク、エラーをログ

注： 計画ファイルはスキルインストールフォルダではなく、プロジェクトルートに置いてください。

コアパターン

コンテキストウィンドウ = RAM（揮発的、容量限定）
ファイルシステム = ディスク（永続的、容量無制限）

→ 重要なことはすべてディスクに書き込みます。

ファイルの目的

ファイル	目的	更新タイミング
task_plan.md	フェーズ、進捗、決定	各フェーズ後
findings.md	調査、発見	何か発見した後
progress.md	セッションログ、テスト結果	セッション中継続

クリティカルルール

1. まず計画を作成

複雑なタスクを task_plan.md なしで始めてはいけません。必須です。

2. 2アクションルール

「ビューアー/ブラウザ/検索操作を 2 回行うたびに、直ちに 主要な発見をテキストファイルに保存します。」

これにより、ビジュアル/マルチモーダル情報が失われるのを防ぎます。

3. 決定の前に読む

重大な決定をする前に、計画ファイルを読んでください。これにより、ゴールが注意ウィンドウに留まります。

4. 行動後に更新

フェーズが完了した後：

• フェーズステータスを更新：in_progress → complete
• 発生したエラーをログ
• 作成/変更されたファイルを記録

5. すべてのエラーをログ

すべてのエラーを計画ファイルに記録します。これにより知識が蓄積され、繰り返しが防がれます。

## 発生したエラー
| エラー | 試行回数 | 解決策 |
|--------|---------|-------|
| FileNotFoundError | 1 | デフォルトコンフィグを作成 |
| API timeout | 2 | リトライロジックを追加 |

6. 失敗を繰り返さない

if action_failed:
    next_action != same_action

試したことを追跡します。アプローチを変化させます。

3 ストライク エラープロトコル

試行 1：診断と修正
  → エラーメッセージを注意深く読む
  → 根本原因を特定
  → 的を絞った修正を実施

試行 2：別の方法
  → 同じエラー？別の方法を試す
  → 別ツール？別ライブラリ？
  → 失敗した同じアクションを繰り返さない

試行 3：より広い観点での見直し
  → 前提条件に疑問を持つ
  → 解決策を検索
  → 計画の更新を検討

3 回の失敗後：ユーザーにエスカレート
  → 試したことを説明
  → 具体的なエラーを共有
  → ガイダンスを求める

Read vs Write 判断マトリックス

状況	アクション	理由
ファイルを書き込んだばかり	読まない	コンテンツはまだコンテキストにある
画像/PDF を見た	発見を直ちに書く	マルチモーダル → 失われる前にテキストに
ブラウザがデータを返した	ファイルに書く	スクリーンショットは永続化されない
新しいフェーズを開始	計画/発見を読む	コンテキストが古い場合は再認識
エラーが発生	関連ファイルを読む	修正するには現在の状態が必要
間隔後に再開	すべての計画ファイルを読む	状態を復元

5 つの質問リブートテスト

これらの質問に答えられれば、コンテキスト管理は堅実です：

質問	回答ソース
今どこにいるか？	task_plan.md の現在のフェーズ
どこに行くのか？	残りのフェーズ
ゴールは何か？	計画内のゴールステートメント
何を学んだか？	findings.md
何をしたか？	progress.md

このパターンを使う場合

使用対象：

• マルチステップタスク（3 ステップ以上）
• 調査タスク
• プロジェクト構築/作成
• 多くのツール呼び出しにまたがるタスク
• 組織化が必要なもの

スキップ対象：

• シンプルな質問
• 単一ファイル編集
• クイックルックアップ

テンプレート

開始するため、これらのテンプレートをコピーしてください：

• templates/task_plan.md — フェーズトラッキング
• templates/findings.md — 調査保管
• templates/progress.md — セッションログ

スクリプト

自動化用のヘルパースクリプト：

• scripts/init-session.sh — すべての計画ファイルを初期化
• scripts/check-complete.sh — すべてのフェーズ完了を確認
• scripts/session-catchup.py — 前のセッションからコンテキストを復元 (v2.2.0)

高度なトピック

• Manus の原則： reference.md を参照
• 実例： examples.md を参照

アンチパターン

しないこと	代わりにすること
TodoWrite を永続化に使う	task_plan.md ファイルを作成
ゴールを 1 度だけ述べて忘れる	決定の前に計画を再読
エラーを隠してサイレントに再試行	エラーを計画ファイルにログ
すべてをコンテキストに詰め込む	大きなコンテンツをファイルに保管
すぐに実行開始	まず 計画ファイルを作成
失敗したアクションを繰り返す	試行を追跡、アプローチを変化
ファイルをスキルディレクトリに作成	ファイルをプロジェクトに作成