build-feature

機能をフェーズごとに構築する

1 フェーズにつき 1 件の PR を作成し、マージ前にレビューと修正を複数回行います。機能を 1 つのブランチで構築すると試すことができず、レビューを 1 回だけ通してマージしたコードには、レビューを受けていない修正が含まれます。

main
 └─ integrate/<plan>                         cut once, before the first phase
     ├─ <plan>-phase-1 ──PR──▶ integrate     build, verify, review x2-3, fix, merge
     ├─ <plan>-phase-2 ──PR──▶ integrate
     ├─ <plan>-phase-N ──PR──▶ integrate
     └──────────────────PR──▶ main           demo, then the user merges

one phase: feat/<plan> ──PR──▶ main          no integrate branch

記憶ではなく、必ず計画ファイルから始めます。 引数で指定されたパスを使うか、plans/ を調べて、複数の候補がある場合はユーザーに確認します。フェーズごとにファイルを読み直します。いずれかの決定が _open_ の場合は、作業を止めてユーザーに計画へ戻ってもらいます。フェーズ 1 の前に、すべての Verify 行と ## Demo を確認します。証明も延期の記載もないフェーズは計画上の問題なので、今のうちに指摘するのが最も低コストです。

図のとおりにブランチを作成します。 最新の main から integrate/<plan-name> を切ってプッシュするか、すでにあればそれを再利用します。すべてのフェーズはこのブランチから分岐し、これをマージ先とするため、main に機能の一部だけが取り込まれることはありません。1 フェーズのみの計画では、このブランチを省略します。main から feat/<plan-name> を切り、デモ後はユーザーがマージできるよう、グリーンの PR の状態で停止します。

作業を開始するのは、Blocked by: に記載されたフェーズがマージ済みで、未チェックのボックスがあるフェーズのみです。実行するのはそのフェーズのタスクだけです。 Solo モードでは、計画に記載された順に 1 つずつ進めます。まだ開始していないフェーズの作業を、たとえ 3 行であっても前倒ししてはいけません。フェーズの境界を守ることで、PR のレビューがしやすくなります。無関係なバグや、ついでに行いたくなるリファクタリングは、計画に 1 行だけメモします。作業と同じコミットでボックスにチェックを入れ、## Progress を更新します。Active: には進行中のフェーズをすべて記載します。例：Active: 2a, 2b · 7/15 tasks。

再開するときは、やり直さずに続けます。 まず、インテグレーションブランチを対象とするオープン PR を探します。マージされていないフェーズの PR がオープンなら、サイクルの途中です。そのコミットとレビューコメントから、どのラウンドまで進んだかが分かります。Solo モード以外では、ランタイムにフェーズのワーカーが残っていれば、そのワーカーで続行します。残っていない場合はその旨を伝え、計画と PR の情報を新しいワーカーに引き継ぎます。

作業を始める前に、進め方を示します。 現在の状況を把握したら、計画のフェーズ、マージ済み PR、オープン PR をもとに、プレーンテキストの図で進行状況を表示します。各ステップに完了、進行中、または保留中の印を付け、残りの作業をユーザーが確認できるようにします。Blocked by: の行がある場合は、フェーズをウェーブごとにまとめます。各ウェーブには、ブロッカーがすべて前のウェーブにあるフェーズを含めます。各フェーズのブロッカーを記載します。フェーズはウェーブ全体が終わったときではなく、独自のブロッカーがマージされた時点で開始するためです。Blocked by: がない場合は、フェーズを順番に並べます。2a のように、計画に記載されたフェーズ ID を使います。1 フェーズのみの計画では、インテグレーションブランチの代わりに feat/<plan> を表示します。

plans/<plan>.md
main
 └─ integrate/<plan>
     ├─ wave 1
     │   └─ [x] phase 1  <title>   merged #12
     ├─ wave 2
     │   ├─ [~] phase 2a <title>   PR #14, review round 2
     │   └─ [~] phase 2b <title>   building
     ├─ wave 3
     │   └─ [ ] phase 3  <title>   blocked by 2a, 2b
     ├─ [ ] demo
     └─ [ ] final PR ──▶ main      user merges

フェーズ 1 の前に、AskUserQuestion を使って構築方法を確認します。 回答は Decisions の下に **Build mode** として記録し、再開時にも引き継がれるようにします。1 フェーズのみの計画では、この確認を省略して Solo モードで構築します。

• Orchestrator (Recommended) — フェーズごとに新しいワーカーサブエージェントを使うため、フェーズ 6 がフェーズ 1 のコンテキストで実行されることはありません。Blocked by: に記載されたフェーズがマージ済みのフェーズは、各ワーカーがそれぞれ独立した git worktree で同時に実行します。Blocked by: の行がない場合は、1 つずつ実行します。並行して動くワーカーは、それぞれ自分のボックスだけにチェックを入れます。マージのたびに、あなたが ## Progress を更新します。
• Solo — すべてのフェーズをあなたが構築し、各ラウンドで新しいレビュアーサブエージェントを使います。後続のフェーズは、コンテキストが混み合った状態で実行されます。

各モードの図を、そのモードのオプションの preview に表示します。質問ツールにプレビュー機能がない場合は、質問する前に両方の図を表示します。

Orchestrator
you ─┬─ worker 1 ── phase 1 ── reviewers
     ├─ worker 2 ── phase 2 ── reviewers
     └─ worker 3 ── phase 3 ── reviewers
fresh context per phase; unblocked
phases run in parallel

Solo
you ─┬─ phase 1 ── reviewers
     ├─ phase 2 ── reviewers
     └─ phase 3 ── reviewers
one context, grows each phase

サブエージェントが使うモデルを尋ねてはいけません。 ユーザーの引数に別の指定がなければ、どちらもあなたと同じモデルを使います。effort パラメーターがある場合、レビュアーはあなたと同じ effort で実行し、ワーカーは 1 段階低い effort で実行します（high→medium）。Claude Code では $CLAUDE_EFFORT を読み取ります。推測してはいけません。見つからない場合は effort を未設定のままにします。構築モードとともに、各ロールのモデルと effort を記録します。

サブエージェント用のツールがない場合はどうしますか？ 作業を止め、インストールするようユーザーに伝えます。独自の起動ツールを作ってはいけません。Pi では、 構築方法を尋ねる前に、このファイルと同じ場所にある pi.md を読みます。 ワーカーが実装し、あなたが統括します。 フェーズのコードと検証は、そのワーカーが担当します。フェーズブランチを作成し、実装と検証を行い、PRを開き、レビュー修正を適用します。あなたは統合ブランチ、レビュー、マージ、報告、デモを担当します。計画のパス、そのワーカーが担当するフェーズ、このスキルに定められたスコープ、検証、PR、修正、固定済みの決定に関するルール、およびよくある間違いをワーカーに伝えてください。レビューの各ラウンドでは、メッセージ（例：SendMessage）を送って同じワーカーを使い続けてください。ワーカーはすでに差分を把握しています。指摘事項があるレビュー報告は、その都度ワーカーに伝えてください。指摘なしのラウンドでは、メッセージは不要です。報告後にレビュアーから届くアイドル通知にも返信は不要です。単独モードでは、あなたがワーカーを兼任します。

phase N
  worker W ── spawned once: builds, verifies, opens PR
     │  round 1  reviewer R1 (new) ──report──▶ you ──relay──▶ W fixes, commits
     │  round 2  reviewer R2 (new) ──report──▶ you ──relay──▶ W fixes, commits
     │  round 3  reviewer R3 (new) ──report──▶ you ──relay──▶ W fixes, commits
     ▼
  merge ── W retired; phase N+1 gets a new worker

PRを開く前にローカルで検証します。 リポジトリのチェックに加えて、そのフェーズで約束したことが実現されている証拠を確認してください。証拠には、計画の Verify 行を使います。それがない場合は、このフェーズのコードがなければ失敗するテスト、またはローカルのフィクスチャや開発サーバーを使った実行を用いてください。「コンパイルできる」だけでは証拠になりません。

• 使い捨ての環境を使ってください。検証にデプロイ済みのホスト、共有データベース、または管理者ログインが必要な場合は、何を変更することになるのかを明示して中断し、確認を求めてください。実行可能にするために、認証情報ファイルを開いてはいけません。
• Verify 行が deferred の場合（古い計画では **Demo:**）、チェックを実行し、証拠の確認はデモに延期すると伝えて、次に進んでください。独自に検証方法を作らないでください。
• ユーザー自身のデバイスまたは個人アカウントが必要で、テスト用アカウントを用意できない手順については、残りを実行し、その手順の確認は、質問せずにデモに延期して、フェーズ報告に明記してください。

時間のかかる検証に注意してください。 高速チェックは、ビルド後と修正コミットのたびに実行します。E2E、Playwright、サービスを起動したりスリープしたりする統合テストなどの低速チェックは、PRの前に一度実行し、修正が対象範囲に触れた場合に限り、マージ前にも再度実行します。レビュアーは低速チェックを実行しません。

PRは統合ブランチを対象に開き、main は対象にしません。 タイトルは Phase <n>: <imperative title> にしてください。本文には、ユーザーが得られるものを説明する ## Summary、変更規模に応じた箇条書き、および計画ファイルのパスを記載します。テスト計画、チェックリスト、共著者の行は含めません。gh または GitHub リモートがない場合は、プッシュ済みのブランチで作業を止め、その旨を伝えてください。レビューのサイクルを捏造してはいけません。

レビューのラウンドごとに、新しいサブエージェントを使ってください。 同じサブエージェントを再利用せず、また、想定していたことに最も気づきにくい執筆者も使わないでください。リポジトリにレビュー用スキルがインストールされている場合は、review-code をターゲット pr <number> で、--sub を付けずに使用してください。サブエージェントはすでに新しいコンテキストを持っているため、さらに別のサブエージェントを入れ子にしても意味はありません。それ以外の場合は、サブエージェントに差分をレビューさせ、正確性、セキュリティ、リソース、パフォーマンスに関する欠陥を確認し、重大度、可能性、修正する価値を評価させてください。平文で報告するよう依頼してください。出力スキーマを指定すると、レビューが始まる前にタスクが失敗します。ポーリングはせず、実行環境の待機機能で完了を待ってください。報告はそのまま伝えてください。

同じPRで2回または3回、レビューを実施してください。 各ラウンドは、前のラウンドの修正コミットが反映された後に行います。ラウンド1で指摘がなくても、ラウンド2は必ず実施してください。新しいレビュアーなら、最初のレビュアーが見落とした点に気づくことがあります。ラウンド2で修正が発生した場合に限り、ラウンド3を実施します。上限は3回です。ラウンド3でも修正する価値のある High または Critical の指摘が残った場合は、フェーズが大きすぎて収束できないため、マージ前に止めてください。対応案とともにユーザーに報告し、判断を仰いでください。それ以外の場合は、修正して再検証し、マージしたうえで、最後の修正はレビューを受けずにマージしたことをフェーズ報告に記載してください。

修正する価値のあるものだけを直します。 修正する価値のある指摘はすべて修正してください。判断が分かれる指摘は、小さく、このフェーズのスコープ内であれば修正し、それ以外は計画に記録してください。細かな指摘はそのままにします。1つの指摘で複数の欠陥が挙げられることもあります。修正依頼では各項目を列挙し、すべてを修正してください。次のラウンドで確認できるよう、修正は個別にコミットしてください。対応しなかった項目は1行で明記してください。黙って指摘を取り下げると、最初から存在しなかったように見えてしまいます。 次の4つすべてを満たす場合にのみマージしてください： 最後の修正コミット後に高速チェックが成功し、それらに影響する最後の修正後に低速チェックが成功していること、必須のレビューラウンドが実施されていること、修正する価値のある指摘が残っていないこと、CI がグリーンであること。CI はポーリングループではなく、ブロッキング呼び出しを1回実行して待ってください。PR が統合ブランチに遅れている場合は、先にその変更を取り込んで再検証してください。マージコミットを使用し、スカッシュはしないでください。フェーズごとの履歴が記録になります。GitHub で PR のマージが報告されたら、フェーズブランチを削除し、最新状態の統合ブランチに戻ってください。

各フェーズの報告は1つのブロックにまとめ、その後、次のフェーズを開始してください。 ユーザーから一時停止を求められている場合を除き、確認を求める必要はありません。PR のリンク、完了したタスク、修正した指摘と対応を見送った指摘、実行した内容を含めてください。

ロックされた決定が誤りだと判明したら、ビルドを停止してください。 その決定、コードから判明したこと、無効になる後続フェーズを明示してください。ユーザーに計画を修正してもらってください。選択を黙って別の方法に置き換えて計画し直してはいけません。

デモは計画どおり、最後に1回だけ実行してください。 すべてのフェーズがマージされた後、## Demo を実行し、確認した内容を報告してください。none の場合は最終 PR に進んでください。自分で実行できない場合は、手順をユーザーに提示して待ってください。デモを作り上げたり、フェーズごとに実施したりしてはいけません。ユーザーのみが実施できる、延期された Verify の手順はすべて引き継ぎに追加してください。計画に ## Demo がない場合（古い計画の場合）は、ユーザーに確認し、回答を計画に記録してから実行してください。デモが壊れている場合は、そのデモを担当するフェーズで、同じブランチ、レビュー、マージのサイクルを通じて修正してください。

**統合ブランチから main への最終 PR を作成し、**機能の概要、各フェーズの PR、デモとその結果、未実施のまま残っている Verify の手順、ユーザーが実行できるコマンド、計画に記載されたマージ後の手順を含めてください。main が更新されている場合は、その変更を取り込んでチェックを再実行してください。その後は停止してください。その PR はユーザーがマージします。

よくあるミスに注意

• ; でマージとブランチ削除を連結すること。 マージがハングすると、削除が実行されて PR がクローズされます。
• timeout なしでテストや git fetch を実行すること。 ハングすると、ツールが諦めるまで呼び出しがブロックされます。
• ワークツリー内で cd /abs/worktree && や git -C を使うこと。 分離ガードによって拒否されます。ワークツリーのルートから通常のコマンドを実行してください。
• 途中で切れたレビューを伝えること。 報告が指摘の途中で終わっている場合は、レビュー担当者に続きを求めてください。