planning-with-files

ファイルを使った計画

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

まずは前回のセッションを確認（v2.2.0）

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

# Linux/macOS
$(command -v python3 || command -v python) ${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"

# Windows PowerShell
& (Get-Command python -ErrorAction SilentlyContinue).Source "$env:USERPROFILE\.claude\skills\planning-with-files\scripts\session-catchup.py" (Get-Location)

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

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