mcpField
P
planning-with-files

planning-with-files

github.com/davila7エージェントワークフロー33.0k557 回インストール1 日前に更新
リポジトリ

planning-with-files について

複雑な複数段階の作業を行うエージェント向けの計画スキルです。プロジェクトディレクトリ内の永続的な Markdown ファイルで、計画、調査結果、進捗、エラー、決定事項を段階ごとに記録します。

主な機能

  1. 01計画・調査・進捗ファイルの管理
  2. 02テンプレートによる計画の開始
  3. 03発見事項とエラーの記録
  4. 04判断前に計画を再確認
  5. 05初期化と完了確認のスクリプト

活用シーン

  1. 01複数段階にわたる調査の整理
  2. 02プロジェクト構築の進捗管理
  3. 03中断後の作業再開

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/davila7/claude-code-templates --skill planning-with-files

インストール後、Claude Code で/planning-with-filesを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

examples.md
reference.md
scripts/
check-complete.sh
init-session.sh
templates/
findings.md
progress.md
task_plan.md

詳細

ファイルを使った計画立案

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. 各フェーズの後に更新する — 完了をマークし、エラーを記録します

Note: 3 つの計画ファイルはすべて、スキルのインストールフォルダではなく、現在の作業ディレクトリ (プロジェクトルート) に作成する必要があります。

核心となるパターン

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

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

状況アクション理由
ファイルを書いた直後読まない内容はまだコンテキスト内にある
画像/PDF を表示した今すぐ発見事項を書くマルチモーダル → 失う前にテキスト化
ブラウザがデータを返したファイルに書くスクリーンショットは永続しない
新しいフェーズを開始する計画/発見事項を読むコンテキストが古い場合は再方向づけ
エラーが発生した関連ファイルを読む修正には現在の状態が必要
間隔を空けて再開するすべての計画ファイルを読む状態を復元する

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

これらに答えられるなら、コンテキスト管理は堅牢です:

質問回答の出典
今どこにいるか?task_plan.md の現在のフェーズ
どこへ向かっているか?残りのフェーズ
ゴールは何か?計画内のゴール記述
何を学んだか?findings.md
何をしてきたか?progress.md

このパターンを使うべきとき

使う場合:

  • 複数ステップのタスク (3 ステップ以上)
  • 調査タスク
  • プロジェクトの構築/作成
  • 多くのツール呼び出しにまたがるタスク
  • 整理が必要なものすべて

省略する場合:

  • 単純な質問
  • 単一ファイルの編集
  • 簡単な調べもの

テンプレート

開始するにはこれらのテンプレートをコピーしてください:

スクリプト

自動化のためのヘルパースクリプト:

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

応用トピック

アンチパターン

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

コメント

Markdown 対応