plan-feature

機能を計画する

よくある失敗は2つあります。ユーザーが決めるべきことを推測することと、レイヤーごとに分割して最後のフェーズまで何も見えないことです。まず決定事項を確定してから、垂直スライスに分割します。ステージ1を終えてからステージ2に進んでください。未決定事項を残したまま作成したタスクリストは、結局使い捨てになります。

計画は、リポジトリで設計ドキュメントを別の場所に保存している場合や、ユーザーがディレクトリを指定した場合を除き、plans/<feature-slug>.md に保存します。この機能の計画がすでに存在する場合は、そこから再開してください。

ステージ1 — すべての決定事項を確定する

まず意図を尋ねます。 依頼の背景にある最終目標やきっかけを尋ねてください。最善の推測を選択肢として提示します。依頼から「なぜ」を推測してはいけません。もっともらしい推測も、あくまで推測です。目標がより小規模な修正や別の修正を示している場合は、その旨を一度伝えてから、指示に従ってください。

次に、どこまで詳しく質問するかを尋ねます。 これを最初の Decision として記録してください。この選択は、意図、前提の不足、デプロイに関する質問を除き、両方のステージにおけるすべての質問を左右します。これらは常に質問してください。

• 重要な決定事項のみ（推奨）：変更を元に戻すコストが高い点を尋ね、残りは agent として確定します。
• すべて質問する：コストが低いものも含め、すべての決定事項を尋ねます。agent による選択は行いません。
• エージェントが決定する：残りのすべてを agent として確定し、ステージ2の前に一覧を提示します。

まずコードを読みます。 変更対象のファイル、使用されているパターン、ライブラリを把握してください。コードベースで実現可能な選択肢だけを提示します。

機能の枠組みを定めます。 下記の形式にある4つの枠組みの行を記入し、「なぜ」には意図についての回答を使います。行を書けない場合は、まずその点について尋ねてください。

コードから分かることは調べて答えます。 ライブラリのサポート状況、既存のスキーマ、類似機能の仕組みは、調査事項であり決定事項ではありません。research とタグ付けしてください。コードを読めば分かることを尋ねてはいけません。

重要な点について尋ねます。 「重要な決定事項のみ」の場合は、通常、スコープ、データモデル、パブリック API、ユーザーに見える部分など、変更を元に戻すコストが高い点を尋ね、元に戻しやすい決定は自分で確定します。質問の優先順位は「なぜ」に基づいて決めます。それに関係する点を尋ね、関係しない点は自分で確定してください。自分で行った選択にはすべて agent とタグ付けします。具体的な選択肢と、それぞれの実際のトレードオフを含め、推奨案を最初に提示して AskUserQuestion を使用してください。独立した質問は1回につき最大4件までまとめられます。回答に依存する質問は、その回答を得てから尋ねてください。作業内容（「リトライハンドラーを追加する」）ではなく、決定事項（「リトライはどこに置くか」）を尋ねてください。

技術的な詳細は、拘束力があるものだけ計画します。 レビュー担当者が守るべき不変条件、セキュリティルール、コード外の契約（Webhook URL、ロールアウト時に切り替えるフラグ）、変更を元に戻すコストが高い選択を、プロパティとして記述します（「通貨ごとの価格は最小通貨単位で表す」など）。スキーマのカラム、エンドポイントのパス、列挙型の値、環境変数名、テストケースは実装者とレビュー担当者に任せてください。コードができる前に仮定を固定すると、その仮定に縛られてしまいます。

デモを決めます。 機能全体を対象にしたデモを1つ用意し、すべてのフェーズがマージされた後に実行します。ユーザーがデモを希望するか、またその形式（ユーザー自身が実行する手順、こちらが行うウォークスルー、エンドツーエンドのチェック）を尋ねてください。あるフェーズで Verify を後回しにしない限り、none も有効です。

作業を進めながらファイルに書き込みます。 回答が得られたら記録し、未回答の項目には _open_ と記します。そうすれば、セッションが中断しても再開できます。それぞれの回答から新たな質問が生じることがあります。未回答の項目がなくなるまで続けてください。

異論は一度だけ述べ、その後は従います。 このスキルの選択に異論がある場合は、理由を2行で説明してから、ユーザーの決定を記録してください。

**未回答の項目がなく、回答に曖昧さがなく、すべての agent による選択をユーザーが確認した場合に限り、**ステージ2に進みます。

ステージ 2 — 作業をフェーズに分割する

垂直に分割します。 Backend、Frontend、Database、Tests、Setup といったレイヤーごとのフェーズでは、最後までユーザーに成果が見えず、統合の問題が後回しになります。

Bad — layer slices, nothing usable until the end
  Phase 1  Backend    [db][api]............  user sees nothing
  Phase 2  Frontend   ...........[ui][wire]  everything lands at once

Good — feature slices, each one usable
  Phase 1  Log in            [db][api][ui]   user has an account
  Phase 2  Generate an image [db][api][ui]   user makes an image
  Phase 3  Animate it        [db][api][ui]   user makes a clip

ユーザーが得られるものをフェーズ名にします。 「認証レイヤー」ではなく、「ログインして空のライブラリを確認する」とします。

すべてのフェーズに Verify 行を設けます。 そのフェーズのコードがなければ失敗するものにします。コマンド、URL、クリックの手順、テストなどが該当します。「チェックに合格する」では不十分です。手順と目に見える結果を記載し、結果が目に見えない場合に限り、クエリやフラグを指定します。Verify 行を書けないなら、それはフェーズではありません。

時間のかかる Verify 手順に注意します。 ビルダーはレビュー修正のたびに高速なチェックを再実行しますが、時間のかかるもの（E2E、Playwright、サービスを起動したりスリープしたりする統合テスト）は、PR の前とマージの前にのみ実行します。テストで証明できる場合は、Verify 行の検証を高速に保ちます。リポジトリをまたぐ実行は ## Demo に残します。

ローカルで検証します。 開発サーバー、テスト用データベース、または使い捨てアカウントを使用します。ビルダーは、途中で止めることなく、すべての Verify 行を実行できなければなりません。ローカルで検証できない場合は、本番環境を対象にするのではなく、フィクスチャを追加します。

• デプロイ済み URL、共有データベース、または本番環境の認証情報が必要な手順は、ロールアウト手順です。計画の最後に記載し、マージ後にユーザーが実行できるようにします。
• ユーザー自身のデバイスまたは個人アカウントが必要な手順は、## Demo に記載します。
• ユーザーが明示的に同意しない限り、Verify 行やデモのためにデプロイを計画してはいけません。

フェーズにローカルで検証できる対象がない場合に限り、Verify を保留します。 **Verify:** deferred — <理由> と記載し、デモで必ず確認します。十分に検討していない作業を保留してはいけません。保留が 2 回続く場合は、分割の仕方が適切ではありません。

各フェーズを 1 回のビルドセッションに収まる規模にします。 1 つのコンテキストで、実装、検証、レビュー修正を完了できるようにします。最初に最小限で目に見えるものを配置し、各フェーズはすでに動作しているものを基に構築します。3〜6 フェーズを推奨します。機能が 1 回のセッションで収まるなら、1 フェーズでも構いません。分割したら、フェーズ数を尋ねます。その際、まずこちらのフェーズ数を伝え、それぞれの選択肢で何を統合または分割するのかを説明します。数を合わせるためだけに分割してはいけません。

すべてのフェーズに Blocked by 行を設けます。 先にマージが必要なフェーズ、または none を記載します。そのフェーズのコードが必要な場合、ファイルを共有する場合、またはユーザーが順次実行を選んだ場合、そのフェーズはブロックされます。並列実行できるかどうかは、この依存関係グラフで判断し、計画上の順序では判断しません。互いにブロックせず、共有するファイルもない 2 つのフェーズがある場合は、2a／2b として実行するか尋ねます。

タスクは未チェックの命令形で、1 回の作業で完了できるようにし、ファイル名を記載します。 - [ ] Add source_generation_id to generations (internal/db/migrations)。方法ではなく内容を記載します。Loop with exponential backoff, max 3 ではなく、Retry failed uploads とします。ユーザーが特定の方法を求める場合は、Decision として記録します。ビルダーがチェックボックスに印を付けます。

確定した決定は維持します。 実装によって誤りが判明した場合は、Decisions を明示的に修正し、影響を受けるフェーズを明記します。ユーザーの選択を黙って別の計画に置き換えてはいけません。

ステージ 2 の agent の選択肢は最後に列挙します。 ユーザーが変更できるようにします。

計画ファイルの形式

# <Feature>
**The Job** — <what gets built>
**The Why** — <end goal behind the ask, from the user: who needs it, what breaks or stalls without it>
**The Guardrail** — <what must not change — omit if none>
**Done means** — <observable outcome that closes the feature>

## Decisions
- **Interview depth** — <key decisions only | ask everything | agent decides>
- **<question>** — <answer, one or two lines>
- **<question>** — <answer> `agent`
- **<question>** — <answer> `research`
- **<question>** — _open_   <-- only while stage 1 is running

## Progress
Active: 1 · 0/11 tasks

### Phase 1 — <what the user gains>
<one line: what they can do now that they could not before>
**Blocked by:** <phase numbers, or `none`>
- [ ] <task>
- [ ] <task>
**Verify:** <command, URL, click path, or test — or `deferred — <why>`>

## Demo
<how the finished feature gets shown once every phase has merged — or `none`>

制約、マージ後のロールアウト手順、採用しなかった案など、機能に必要なセクションを追加します。それ以外は追加しません。