planning-with-files

Planning with Files

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

重要：ファイルの保存先

このスキルを使用する場合：

• テンプレートはスキルディレクトリの ${CLAUDE_PLUGIN_ROOT}/templates/ に保存します
• 計画ファイル（task_plan.md、findings.md、progress.md）はプロジェクトディレクトリ、つまり作業中のフォルダーに作成します

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

注： 3つの計画ファイルはすべて、スキルのインストール先ではなく、現在の作業ディレクトリ（プロジェクトのルート）に作成してください。

保存場所の境界

実際にインストールされているスキルディレクトリを使用します。CLAUDE_PLUGIN_ROOT はクライアント固有で、設定されていない場合があります。プライベートな計画ファイルは許可された場所に保管し、シンボリックリンクやパスによる範囲外へのアクセスを防ぎ、既存のファイルを上書きせず、自動的にコミットまたは公開しないでください。スクリプトはレビュー済みの任意の補助ツールであり、インストール済みのフックではありません。完了チェッカーがサポートするのは、同梱されたフェーズ見出し／ステータスのテンプレートであり、任意のチェックリストではありません。また、タスクの成功を判定するものでもありません。一時的なエラーに対しては、上限を設けた再試行が有効な場合があります。実際に未解決の判断がある場合にのみエスカレーションし、3回試したという理由だけで機械的にエスカレーションしないでください。

基本パターン

Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent within its retention/capacity limits)

→ Persist only necessary authorized findings; exclude secrets, personal data and private source dumps.

ファイルの用途

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

重要なルール

1. まず計画を作成する

既存のプロジェクトの計画規約と、ユーザーが提示した計画を使用します。ユーザーが別の指示をした場合、競合する状態ファイルを作成したり、添付された計画を編集したりしないでください。

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ステップ以上）
• 調査タスク
• プロジェクトの構築・作成
• 多数のツール呼び出しにまたがるタスク
• 整理が必要なあらゆる作業

次のような場合は省略します：

• 簡単な質問
• 1つのファイルだけの編集
• 簡単な調べもの

テンプレート

次のテンプレートをコピーして始めます：

• templates/task_plan.md — フェーズの追跡
• templates/findings.md — 調査結果の保存
• templates/progress.md — セッションの記録

スクリプト

自動化に役立つスクリプト：

• scripts/init-session.sh — すべての計画ファイルを初期化
• scripts/check-complete.sh — すべてのフェーズが完了しているか確認

詳細なトピック

• Manus Principles： reference.md を参照
• 実例： examples.md を参照

アンチパターン

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

制限事項

• 上記の説明にある適用範囲にタスクが明確に一致する場合に限り、このスキルを使用してください。
• 出力を、環境固有の検証、テスト、または専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、または成功基準が不足している場合は、作業を停止して確認を求めてください。