planning-with-files

planning-with-filesスキルの概要

planning-with-filesが実際にすること

planning-with-files は、その場限りのチャット記憶ではなく、markdownファイルを使ってシンプルかつ永続的に計画を進めるためのスキルです。中核になるのは3ファイル構成のワークフローで、task_plan.md に工程と進捗、notes.md に調査内容や発見事項、そして output.md のような最終成果物ファイルを置きます。複数ステップにまたがる作業で、進捗を再現可能な形で追跡したいなら、planning-with-files を入れる一番の理由はここにあります。

planning-with-filesを使うべき人

planning-with-files が向いているのは、複数の工程やセッションにまたがって進む作業をしている人です。たとえば、調査、移行、監査、分析、コンテンツ企画、日常的なプロジェクト整理などです。特に、エージェントがすでに学んだ内容を毎回コンテキストへ貼り直さずに覚えていてほしい場面で効果を発揮します。

planning-with-filesが最もハマる仕事

planning-with-files skill を使うべきなのは、「一回で答えを書いてほしい」のではなく、「計画を継続的に持ち、根拠を集め、流れを切らさずに成果物まで仕上げたい」というニーズがあるときです。その意味で、planning-with-files for Project Management は軽量な実行管理には向いていますが、重厚なPMフレームワークの代替にはなりません。

通常のプロンプトとの決定的な違い

普通のプロンプトでも計画は作れます。ただ、planning-with-files は作業のやり方自体を変えます。計画、メモ、成果物をファイルとして外に出す前提にすることで、コンテキストのリセットや長時間のツール利用があっても作業を継続しやすくなります。重要なのは一度きりのプロンプト文面ではなく、この運用モデルです。

planning-with-filesが向かないケース

小さな単発質問、会話ベースのアイデア出しだけをしたい場面、あるいはPRD専用のワークフローには planning-with-files はおすすめしません。リポジトリでも、PRD用途は明確に prd-planner へ案内されています。ワークスペース内に新しいファイルを作りたくない人にとっては、このスキルは汎用プロンプトより重く感じるはずです。

planning-with-filesスキルの使い方

planning-with-filesの導入前提

このリポジトリでは、SKILL.md 内に専用のインストールコマンドは用意されていません。そのため、通常はスキル集のリポジトリから次のように追加します。

npx skills add https://github.com/zhaono1/agent-playbook --skill planning-with-files

このスキルは、エージェントがmarkdownファイルを作成・更新できる環境を前提にしています。想定ツールとして宣言されているのは Read、Write、Edit、Bash、Grep、Glob です。

planning-with-filesが作成を想定しているファイル

実運用での基本形は次のとおりです。

• task_plan.md — 目的、工程、進捗、次のアクション
• notes.md — 調査内容、発見事項、判断、参照先
• [deliverable].md — output.md のような最終成果物

既存リポジトリで planning-with-files usage を取り入れるなら、特別な理由がない限りこの命名を維持するのがおすすめです。ファイル名が一貫しているほど、エージェントが迷いにくくなります。

採用前にまず読むべきファイル

読む順番は次のとおりです。

1. skills/planning-with-files/SKILL.md
2. skills/planning-with-files/README.md

SKILL.md には運用モデルがまとまっています。README.md はより短く、まず適合性をざっと確認したいときに便利です。追加のルール、補助リソース、ヘルパースクリプトは特にないため、隠れた自動化を探すより、このワークフローパターン自体を理解することに価値があります。

ユーザーはplanning-with-filesをどう呼び出しているか

実際には、次のような依頼で planning-with-files を起動することが多いです。

• 「複数ステップの移行計画を立てて、進捗をファイルで追跡して」
• 「調査計画を作って、メモと成果物を保存して」
• 「永続的なタスクファイルでこのプロジェクトを整理して」

これらが機能しやすいのは、単発の回答ではなく、複数フェーズのある作業を前提にしているからです。

曖昧な目標を強いプロンプトに変える

弱いプロンプト:

• 「このアプリの移行を手伝って」

planning-with-files 向けに改善したプロンプト:

• 「Use planning-with-files to create task_plan.md, notes.md, and migration-output.md for a React to Next.js migration. Break the work into phases, track open risks, save findings in notes.md, and keep task_plan.md updated as you go.`

これが良い理由:

• ファイルベースのワークフローを明示している
• 成果物が具体的
• メモを継続保存すべきことが伝わる
• 最初のアウトライン作成だけでなく、計画の更新まで求めている

出力品質を大きく左右する入力情報

可能なら、最初に次の情報を渡してください。

• ゴール
• 制約条件
• 現在のリポジトリや元資料
• 締切または優先順位
• 希望する成果物ファイル名
• 「完了」の定義

例:

• Goal: onboardingフローを監査し、改善案を提案する
• Constraints: コード変更なし、分析のみ
• Inputs: /docs, /src/onboarding, analytics summary
• Deliverable: onboarding-audit.md
• Done means: 発見事項、優先順位付きの課題、推奨アクションがそろっていること

これらがなくてもエージェントはファイルを作れますが、計画全体が汎用的なままで終わりやすくなります。

推奨されるワークフローループ

質の高い planning-with-files guide は、たいてい次の流れに沿います。

1. 目的と工程を含む task_plan.md を作る。
2. ソース資料を調査・確認する。
3. 発見事項を notes.md に保存する。
4. task_plan.md に進捗、ブロッカー、次のアクションを反映する。
5. notes.md をもとに最終成果物を下書きする。
6. 仕上げ前に残っている抜け漏れを明示する。

重要なのは、最初にファイルを作ること自体ではなく、このループを回し続けることです。

Project Management用途でplanning-with-filesが向くケース

planning-with-files for Project Management は、エンタープライズ向けPMツールではなく、軽量な連携や進行管理として捉えるとハマります。相性がよい例は次のとおりです。

• 移行計画
• 調査の進捗管理
• 実装チェックリスト
• コンテンツ制作フロー
• 技術監査
• 依存関係の調査

特に、エージェントが情報を発見しながら、それを完成したアウトプットへ変換していくタイプの作業で強みが出ます。

導入時によくあるつまずき

よくある障壁は、考え方より運用面にあります。

• 小さな作業に即効性を期待してしまう
• エージェントに明確な成果物を指定していない
• task_plan.md を継続更新するよう依頼していない
• すでに厳密なプロジェクト構成があり、新しいトップレベルファイルを増やしたくない

これらに当てはまるなら、インストール前に、このパターンを本当に採用したいのか、それとも単発の計画プロンプトで十分なのかを先に判断したほうがよいです。

実務的なファイル配置のアドバイス

リポジトリ内の例では、ルート直下にシンプルなファイル名で置く形になっています。単独タスクならそれで十分です。一方、タスクが多いプロジェクトでは、/workstreams/migration/ のような作業用フォルダ配下に置いたほうが整理しやすいこともあります。その場合は、エージェントがファイルを別々の場所に作らないよう、プロンプト内でパスを明示してください。

planning-with-filesスキル FAQ

planning-with-filesはチャットで計画を頼むより優れている？

複数ステップの作業なら、たいていはYesです。利点は永続性と追跡しやすさにあります。planning-with-files は、変化していく計画や発見事項をファイルとして保存するので、エージェントが途中から再開してもブレが少なくなります。単に一度だけアウトラインがほしいなら、普通のプロンプトのほうが簡単です。

planning-with-filesスキルは初心者向き？

はい。パターン自体はシンプルで、計画ファイル1つ、メモファイル1つ、成果物ファイル1つという構成です。初心者がやりがちな失敗は、ファイル運用の手間に見合わないほど小さな作業に使ってしまうことです。

planning-with-filesは特定のプロジェクト種別を前提にしている？

いいえ。パターンは意図的に汎用化されています。エージェントがファイルを読み書きできるなら、エンジニアリング、調査、運用、執筆、分析など幅広いタスクを支援できます。

planning-with-filesを使わないほうがいいのはいつ？

planning-with-files を使わないほうがよいのは次のケースです。

• 1ターンで終わる回答
• 会話中心のアイデア出しだけをしたい場合
• ファイルを書き込めない環境
• prd-planner のほうが適しているPRD専用ワークフロー

タスクトラッカーやTodoWriteとは何が違う？

このスキルが解決するのは別の問題、つまり持続する作業記憶です。タスクトラッカーはtodo一覧を管理できますが、planning-with-files は計画、根拠、最終成果物を、エージェントが再度開いて継続利用できるプレーンなmarkdownファイルとしてつなげて保持します。

planning-with-filesには自動化やスクリプトが含まれている？

このリポジトリ配下には含まれていません。価値の中心は、ツール同梱ではなくワークフローパターンそのものにあります。そのぶん理解しやすい反面、出力品質はタスク定義の明確さに大きく左右されます。

planning-with-filesスキルを改善する方法

planning-with-filesは最初のタスク定義を鋭くする

planning-with-files の結果を最も早く改善する方法は、対象範囲、制約、成果物名を含んだタスク定義を最初に渡すことです。「これを調査して」では弱すぎます。「auth failure を調べ、発見事項を notes.md に保存し、原因と修正案をまとめた auth-failure-analysis.md を作成して」のほうがはるかに強い依頼になります。

ファイル作成だけでなく更新も求める

ありがちな失敗は、エージェントが3つのファイルを一度作ったあと、実際の作業はほとんどチャット上で進めてしまうことです。各主要ステップのあとに task_plan.md を更新し、実質的な発見事項は notes.md に残すよう明示してください。これでワークフローが生きた状態を保てます。

長いタスクではフェーズを明示する

作業が複雑なら、task_plan.md を discovery、analysis、execution、validation、handoff のようなフェーズに分けるよう依頼してください。区別のないチェックリストにするより、スキルが機能しやすくなります。

根拠の期待値を伝えてnotesの質を上げる

notes.md は、次の要素を求めるだけで一気に使いやすくなります。

• source path や参照先
• 仮定
• 未解決の疑問
• 下した判断
• 採用しなかった選択肢

これにより、単なる走り書きではなく、再利用できる作業記憶として機能します。

成果物仕様を示して汎用的すぎる出力を減らす

最終ファイルが意思決定メモなのか、移行チェックリストなのか、監査レポートなのか、実装計画なのかを具体的に伝えてください。planning-with-files skill の具体性は、最終的にどんなアウトプットを求めるかで決まります。

最初の出来が弱かったときの立て直し方

初回の実行が浅かった場合は、ゼロからやり直さないでください。代わりにエージェントへ次を依頼します。

1. task_plan.md を見直して不足しているフェーズを補う
2. notes.md に根拠と未解決の質問を追加する
3. 更新したメモを使って成果物を書き直す

多くの場合、最初から再プロンプトするより早く品質が上がります。

ワークスペースに合わせてファイル構成を意図的に調整する

デフォルトの3ファイル構成は、最小限で扱いやすいのが利点です。既存チームに合わせるべき構成がある場合を除き、まずはそのまま使うのが無難です。ファイル名を変える、サブフォルダへ移動する、といった調整をするなら、正確なパスを指定して、セッションをまたいでも planning-with-files usage がぶれないようにしてください。

planning-with-filesは実物のソース確認と組み合わせる

このスキルは、エージェントが実際に確認できる材料があるほど強くなります。たとえば、repo内のフォルダ、docs、logs、issue一覧、requirements などです。抽象的な目標だけでもワークフロー自体は回せますが、できあがるファイルは根拠のある作業記録というより、雛形のような内容になりがちです。

planning-with-filesが合っていないサインを見極める

planning-with-files が不向きだとわかる最も明確なサインは、計画ファイルが支援ではなく事務作業になっているときです。ひとつの集中した回答で十分に解けるタスクなら、オーバーヘッドは避けて、直接的なプロンプトを使うほうが適しています。