planning-workflow

計画ワークフロー — エージェント型開発の基盤

中核となる考え方：「計画に使うトークンは、実装に使うトークンよりずっと少なく、安価です。」

詳細な計画がコンテキストウィンドウ内に収まっていれば、モデルははるかに賢く推論できます。これが、時間の80％以上を計画に費やすことの要点です。

---

成果 — このスキルで達成できた状態

以下のすべてを満たしたとき、実用可能な計画ができています。

• 計画が自己完結している：プロジェクトを見たことのない新しいエージェントが読んで、人間に確認せずに実装を始められます。
• 依存関係が考慮されている：重要なタスクはすべて、何がそのタスクを妨げ、何の妨げを解消するかを明記しているため、作業を beads グラフに無理なく分解できます。
• 根拠が示されている：アーキテクチャ上の選択や自明でない機能にはすべて、単に「何をするか」だけでなく、「なぜそうするか」を少なくとも1文で記載しています。後続のエージェントが一貫した局所的判断を下すには、その根拠が必要です。
• 強力な推論モデル（実績のある選択肢は GPT Pro Extended Reasoning）による少なくとも4回のレビューを経て、定常状態に達しています。つまり、直近のレビューでは構造的な変更ではなく、わずかな修正だけが提案されています。
• 依存関係グラフを保ったままbeads に変換されているため、実装エージェントは計画を読み直さずに br ready --json から着手可能な作業を選べます。

次のいずれかに該当する場合は、成果を達成したとは言えません。重要なプロジェクトなのに計画が約1,500行未満（仕様不足）である。分割されないまま10,000行を超えている（実行不可能）。実装中に人間へ「これは何をすべきですか？」とまだ尋ねている（計画を完了せずに放棄した）。beads は作られているが依存関係の辺がない（変換時に計画の構造が失われた）。

このスキルを使わない場合

次の場合は、別の方法を選んでください。

• 変更が小規模で局所的（バグ修正1件、ファイル1つ、約200 LOC未満）→ チャットで計画するか、TaskCreate を1行で作成してください。計画のオーバーヘッドが実装コストを上回ります。
• 純粋な調査を行う（未知のコードベースを調べる、アイデアのプロトタイプを作る）→ まず codebase-archaeology または idea-wizard を使ってください。計画は実行のためのものであり、発見のためのものではありません。
• アーキテクチャが指定されている（既存システムの移植、仕様に従った実装、明確に定義された RFC の実装）→ porting-to-rust または testing-conformance-harnesses を使ってください。計画そのものが仕様です。
• 計画に80％の時間を割けない厳しい締め切りがある（進行中のインシデント、ホットフィックス、セキュリティパッチ）→ まず修正をリリースし、その領域でさらなる作業が必要なら後から計画を整えてください。

根拠付け — 計画上の判断における信頼できる情報源

計画モデルがアーキテクチャを提案するとき、その提案は仮説です。重要な主張はすべて、レビューを通過させる前に検証可能な情報源で裏付けてください。

• ライブラリ／フレームワークの選択： 最新の実際のドキュメントを確認してください（モデルの学習時点の情報ではなく、最新の安定版を参照します）。モデルが「Y には X を使う」と言うなら、導入するバージョンで X が今も存在し、保守され、Y をサポートしているかを検証してください。
• 既存のコードベースに関する主張： 既存プロジェクトに触れる計画では、モデルのプロジェクト構造に対する理解を疑ってください。構造に関する主張を計画に反映する前に、grep、git log、または codebase-archaeology を使って確認してください。
• パフォーマンス／スケーリングに関する主張： 引用元や計画されたベンチマークなしに、「毎秒1万リクエストを処理する」「100ミリ秒未満で読み込む」といった数値を受け入れてはいけません。計画に根拠なく書かれた数値は、事実に見せかけた推測です。
• コストに関する主張： 計画時点でプロバイダーの料金ページを確認してください。料金体系は変わります。計画には、料金を確認した具体的なプランを明記してください。
• 他のスキル／ツールへの相互参照： 計画に「X には <tool> を使う」とある場合、そのツールの現在の仕様が X をサポートしているか確認してください。計画内のリンク切れは、気づきにくい失敗の原因です。

根拠付けをせずにレビューを通過した計画は、実装時に予期せぬ事態を招きます。計画時に安価な検証を行うほうが、コードが半分書かれた後に高くつく手戻りをするより賢明です。

検証ループ（レビューラウンドの間）

各レビューラウンドの後、次のレビューに回す前に、以下の4つをすべて実施します。

1. 自己完結性チェック — 計画の中で最も分かりにくいタスクを選び、新しいチャットに単独で貼り付けて、「この記述だけで実装できますか？」と尋ねます。できない場合は、内容を補足します。
2. 依存関係グラフのチェック — タスクのDAGを描けますか？循環はありますか？消費側のない孤立タスクはありますか？いずれかに該当する場合、計画に問題があります。
3. 根拠のチェック — アーキテクチャ上の決定をランダムに5つ選びます。それぞれに「なぜ」を説明する段落が必要です。なければ、計画モデルに追加を依頼します。
4. 定常状態チェック — 今回の計画と前回の計画を比較します。構造が大きく変わっている場合は、もう1ラウンド必要です。誤字の修正程度であれば完了です。

いずれかのチェックに失敗した場合、計画は beads への変換準備ができていません。もう1ラウンドレビューしてください。

---

計画が重要な理由

• 二度測って一度切る — 「計画をN回確認して、一度で実装する」になります
• 非常に大規模で複雑なMarkdown計画でも、実質的なコードファイルをいくつか書くより短く済みます
• 計画段階で人間の意見を前もって取り入れることで、実装から自分自身を外せるようになります
• しっかりした計画を用意して十分な数のエージェントを開始すれば、コードは驚くほど速く書き上がります

---

正確なプロンプト — 計画レビュー（GPT Pro Extended Reasoning）

Carefully review this entire plan for me and come up with your best revisions in terms of better architecture, new features, changed features, etc. to make it better, more robust/reliable, more performant, more compelling/useful, etc. For each proposed change, give me your detailed analysis and rationale/justification for why it would make the project better along with the git-diff style change versus the original plan shown below:

<PASTE YOUR EXISTING COMPLETE PLAN HERE>

---

正確なプロンプト — 修正内容の統合（Claude Code）

GPT Pro の処理が完了したら（20～30分かかる場合があります）、出力を Claude Code に貼り付けます。

OK, now integrate these revisions to the markdown plan in-place; use ultrathink and be meticulous. At the end, you can tell me which changes you wholeheartedly agree with, which you somewhat agree with, and which you disagree with:

```[Pasted text from GPT Pro]```

---

プロセスの概要

1. INITIAL PLAN (GPT Pro / Opus 4.7 in web app)
   └─► Explain goals, intent, workflows, tech stack

2. ITERATIVE REFINEMENT (GPT Pro Extended Reasoning)
   └─► 4-5 rounds of revision until steady-state

3. MULTI-MODEL BLENDING (Optional but recommended)
   └─► Gemini 3.1 Pro Deep Think, Grok4 Heavy, Opus 4.7
   └─► GPT Pro as final arbiter

4. CONVERT TO BEADS (Claude Code + Opus 4.7)
   └─► Self-contained tasks with dependency structure

5. POLISH BEADS (6+ rounds until steady-state)
   └─► Cross-model review, never oversimplify

---

優れた計画の条件

良い計画	優れた計画
何を作るかを説明している	なぜ作るのかを説明している
機能を列挙している	ユーザーのワークフローと操作を詳述している
技術スタックに言及している	トレードオフを踏まえて技術選択の理由を説明している
タスクがある	依存関係と根拠を伴うタスクがある
約500行	改良後は約3,500行以上

必須要素

1. 自己完結している — 外部ドキュメントを参照する必要がない
2. 粒度が細かい — 複雑な機能を具体的なサブタスクに分解する
3. 依存関係を考慮している — 何が何を妨げるのかを明確にする
4. 根拠がある — 指示だけでなく理由も含める
5. ユーザーを重視している — それぞれの要素がエンドユーザーにどう役立つかを示す

---

よくある間違い

1. 実装を早く始めすぎる — 3時間の計画で、30時間の手戻りを防げます
2. 1ラウンドだけレビューする — 6ラウンド目以降でも改善を続けられます
3. GPT Proを使わない — この用途ではExtended Reasoningが特に優れています
4. 骨組みからコーディングする — 充実した計画を1つ作るほうが、段階的にコーディングするより優れています
5. コンテキストを失う — エージェントが元の計画を必要としないよう、計画をbeadsに変換します

---

参考資料

トピック	参考資料
すべての正確なプロンプト	PROMPTS.md
実例	EXAMPLES.md
FAQ	FAQ.md