planning-with-files

Planning with Files

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

最初に：前回のセッションを確認する（v2.2.0）

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

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"

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

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

重要：ファイルの保存場所

• テンプレートは ${CLAUDE_PLUGIN_ROOT}/templates/ にあります
• 計画ファイルはプロジェクトディレクトリに保存します

場所	保存するもの
スキルディレクトリ（${CLAUDE_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. 各フェーズの後に更新する — 完了としてマークし、エラーを記録します

注： 計画ファイルはスキルのインストールフォルダーではなく、プロジェクトのルートに保存します。

基本パターン

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

→ Anything important gets written to disk.

ファイルの用途

ファイル	用途	更新するタイミング
task_plan.md	フェーズ、進捗、判断	各フェーズの後
findings.md	調査、発見事項	発見があったら必ず
progress.md	セッションログ、テスト結果	セッション全体を通して

重要なルール

1. まず計画を作成する

task_plan.md を作成せずに複雑なタスクを始めてはいけません。これは必須です。

2. 2アクションルール

「表示／ブラウザー／検索の操作を2回行うごとに、重要な発見をすぐにテキストファイルへ保存します。」

これにより、視覚情報やマルチモーダル情報が失われるのを防ぎます。

3. 判断する前に読む

重要な判断をする前に、計画ファイルを読みます。これにより、目標を注意の対象となるウィンドウに保てます。

4. 実行後に更新する

フェーズを完了したら、次の作業を行います。

• フェーズのステータスを更新します：in_progress → complete
• 発生したエラーを記録します
• 作成／変更したファイルを記録します

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

エラーはすべて計画ファイルに記録します。これにより知識が蓄積され、同じ問題の再発を防げます。

## 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 different method
  → Different tool? Different library?
  → NEVER repeat 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
  → Share the specific error
  → Ask for guidance

読み取りと書き込みの判断表

状況	アクション	理由
ファイルを書き込んだ直後	読み取らない	内容はまだコンテキスト内にあるため
画像／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 ファイルを作成する
目標を一度述べただけで忘れる	判断を下す前に計画を読み直す
エラーを隠して黙って再試行する	計画ファイルにエラーを記録する
コンテキストにすべてを詰め込む	大きなコンテンツはファイルに保存する
すぐに実行を始める	まず計画ファイルを作成する
失敗した操作を繰り返す	試行を記録し、アプローチを変更する
スキルディレクトリにファイルを作成する	プロジェクト内にファイルを作成する