executing-tickets-with-subagents

サブエージェントを使ったチケットの実行

概要

メインの会話ではオーケストレーションのみを行います。すべての編集、レビュー、QA パスは、ディスパッチされたサブエージェントで実行します。永続的な状態はディスクと GitHub に保存されます。コンパクションはどちらにも届かないため、実行はその後も継続できます。

実行ブランチの選択

• 無人実行。 ユーザーが明示的に離席すると伝え、作業の継続を依頼した場合は、最初のディスパッチの前に ${CLAUDE_SKILL_DIR}/references/unattended-scheduler.md を最後まで読んでください。スケジューリング、移行、更新、引き継ぎに関するその契約は、タスクが1件だけの場合にも適用されます。作業が複数タスクをまとめた GitHub チケットでもある場合に限り、以下のフェーズを使用してください。
• 複数タスクをまとめたチケット。 チケットの受け入れ、ウェーブ、終了処理には以下のフェーズを使用してください。

作業をディスパッチする前に、選択したブランチを台帳に記録してください。これがゲートです。

フェーズ 0：受け入れ

1. 再開チェック。 このチケットの台帳が存在する場合は、まずそれを読み、NEXT ACTION を実行してください。実行状態の唯一の情報源は台帳です。会話の記憶ではありません。次のウェーブの前に、todo リスト、チェックリストコメント、ハーネスタスク、台帳の4つすべてのトラッカーを照合してください。
2. イシューのスレッド全体を取得。 ${CLAUDE_SKILL_DIR}/../audit-ticket/references/ticket-evidence.md を最後まで読み、認証を使った、失敗時に即座に停止する画像ダウンロードの手順を ${CLAUDE_SKILL_DIR}/../audit-ticket/SKILL.md から確認してから、gh issue view <n> --json number,title,body,author,createdAt,updatedAt,state,assignees,url,comments で構造化されたイシュー JSON を取得してください。イシュー本文と、各コメントの body、author、createdAt、url からソースマップを作成してください。添付画像はすべて認証付きでダウンロードし、HTTP エラー時に終了するようにしてください。ファイルを開く前に終了コードを確認し、正常にダウンロードできた画像はすべて実際に読み取ってください。ダウンロードに失敗した場合は image <i> unavailable と記録してください。エラー内容を含む本文を画像の証拠として開いたり、ハッシュ化したりしないでください。コメントによって元の本文が頻繁に上書きされたり、情報が追加されたりします。未読のコメントがあれば、仕様を把握できていないことになります。
3. コードベースを調査。 ユーザーに質問する前に、コードに照らして主張を検証してください。

フェーズ 1：固定、計画、計測

1. コードを調査するため、読み取り専用のエージェントを並列で実行してください。サブイシューごとに、対応済み、一部対応済み、未着手のいずれかの判定と、ファイル名と行番号の根拠を示してください。
2. ユーザーに確認する。 タスクの順序、PR 戦略、タスクごとの完了基準、追跡方法、移行やコミット方針などユーザーが決める事項について grill-me を実行してください。上記すべての項目について、回答が確定して台帳に記録されるまで確認を続けます。確定した回答は、以降のすべてのディスパッチで必ず守るべきルールです。
3. 仕様を作成してから計画する。 サブイシューごとにブリーフを1つ作成し、すべてのサブイシューを網羅してください。それぞれに対象となる正確なコードと、レビュー担当者が確認すべき名前付きのリスクを2～3件記載します。タスクが反映されると行番号が変わるため、ブリーフでは行番号ではなくシンボルで位置を示してください。タスク1を始める前に、ブリーフ一式を対象に grill-me の検証パスを実行してください。
4. タスク1の前に追跡手段を整備してください。
   • 台帳（例：docs/<ticket>-progress.md）を維持してください。これは復旧マップであり、以下の契約に従います。
   • tasks/todo.md チェックリストを維持してください。
   • イシューには編集可能な GitHub チェックリストコメントを1件維持してください。コメントには各項目のステータスと根本原因を記載します。コメント ID を台帳に保存し、gh api ... -X PATCH -F body=@file で更新してください。初期コメント全体をファイルに出力し、その SHA-256 を固定します。コメントを作成する直前に、イシューの URL、updatedAt、本文、状態、担当者、コメントを再取得してください。意図したチェックリストがまだ存在しないことを確認してから、これらのガード、正確に固定したファイルとダイジェスト、確定した追跡方法、作成後に期待されるコメント本文、権威あるコメントの読み戻し結果を指定して preflight-mutations を実行してください。続行する前に、その結果の契約を適用してください。作成したコメントは ID で読み戻し、全文が固定した内容と一致することを確認してください。権威ある読み戻しで変更が反映されていないと証明された場合に限り、再試行してください。標準出力が空でも失敗ではありません。
   • TodoWrite を使ってハーネスの todo リストを維持してください。

台帳の契約

台帳は、前提知識がまったくない読者に向けて記述します。次の執筆者は何も覚えていないものとします。すべてのウェーブの後に更新してください。タスクごとのステータスとコミット SHA、命令形で記述した現在の NEXT ACTION、トリアージ待ちの累積した Moderate および Minor の指摘、常設のプロセスルール、ブリーフと成果物の場所、およびチケットのソースマップを記載する必要があります。常設ルールには、許可された権限、環境の癖とフォールバック、QA の認証情報とデータに関する注意事項を含めます。

フェーズ 2：ウェーブ（タスクごとに 1 回）

1. ブリーフからスクラッチパッドへ。 計画後に HEAD が移動していた場合は、Explore によるドリフトチェックを実行し、追記を書きます。追記を優先します。

2. 新しい実装エージェント。 オーケストレーターがタスクを割り当て、エージェントが編集します。バグ修正は TDD で行います。まず失敗するテストを書き、失敗することを確認します。タスクの型チェックループをフォーマットして実行し、その後、独立したレビューのためにタスクの差分を未コミットのまま残します。ディスパッチ用プロンプトは自己完結している必要があります。パス、環境、確定済みの判断、検証コマンド、意図するコミット形式、報告形式、環境の癖に対するフォールバックを含めます。エージェントにはほかのコンテキストを与えません。

3. 別々のサブエージェントによる 2 段階レビュー。 1 人のレビュー担当者は最初に着手した観点に固執しますが、新たに起動した 2 人はそうなりません。レビューは 2 つの段階に分けて報告します。各段階につき 1 件です。

   • 第 1 段階、仕様準拠。 レビュー担当者にはタスクのブリーフと差分、および検証すべきリスクを提示します。入力はこの 2 つだけです。チケットの要件に対する判定を返します。判定は Missing、Extra、Misunderstood のいずれかで、それぞれにファイルと行番号の根拠を付けます。
   • 第 2 段階、コード品質。 独立したレビュー担当者が、正確性、エラー処理、実際の動作を検証するテスト、構造を確認します。指摘の重要度を Critical、Serious、Moderate、Minor に分類します。parallel-review は並行して実行し、スタイルと慣例を確認します。仕様違反を見つけるのは第 1 段階です。

4. すべての指摘をトリアージします。 FIX-NOW の場合は修正エージェントが対応し、仕様に準拠し、品質レビューで承認されるまで両段階で再レビューします。タスクを完了するのは、未解決の Critical および Serious の指摘がゼロになったときです。DISMISS には検証済みの根拠が必要です。レビュー担当者が確定済みの判断を蒸し返すため、まず確定済みの設計またはブリーフを確認してください。DEFER の対象は Moderate と Minor のみです。これらは台帳に記録します。レビューが完了したら、未コミットの差分に対して、そのタスクに該当する done レーンを実行します。done に git-commit を呼び出させ、検証済みのタスク単独のコミットを作成し、その SHA を記録します。確定済みのウェーブ戦略にプッシュが含まれる場合は、プッシュ前に preflight-mutations を呼び出します。その際、正確なリモートブランチ、ローカルとアップストリームの SHA およびコミット範囲、PR のベースとヘッドおよび依存関係、確定済みのプッシュ権限を指定します。

   すべての報告は未検証として扱います。SHA、件数、ファイルと行番号の参照、実行した内容と確認しただけの内容を検証し、根拠を確認できた場合にのみ指摘を解消します。

5. UI タスクでは browser-qa を使用します。 元のデータを記録し、復元して、復元されたことを証明します。成果物はスクラッチパッドのみに保存します。ウェーブの間に、実装エージェントが稼働していない状態で実行します。ホットリロードにより、テスト中にセッションが汚染されます。

6. 事務処理。 tasks/todo.md にチェックを入れます。各ウェーブのチェックリストに PATCH を適用する直前に、正確な issue と comment の ID、置き換え後の本文、現在のコメントのバージョンと本文、確定済みの追跡権限、読み戻し情報を指定して preflight-mutations を呼び出し、その結果の契約に従います。次のタスクに進む前に、ハーネスの TODO リストと台帳を更新します。

応答しなくなったエージェントには再度催促せず、終了させます。最終ステータスまたは正常な割り込みを記録し、その作業ツリーと差分の場所を保持してから、タスクを active から ready に移し、新しい担当者を割り当てます。非アクティブであることを証明できない場合は、2 人目の担当者を割り当てず、タスクを blocked にします。

フェーズ 3：終盤

1. 再計算したマージベースから、ブランチ全体を最終レビューします。 マージベースは移動するため再計算し、生成ファイルは除外します。見つかったタスク間の相互作用をすべて報告するか、なかったことを明示します。台帳にある軽微な項目をすべて FIX-NOW、FOLLOW-UP、DROP に分類します。
2. 修正パスを行い、その後 fix-pr-review を使って、外部レビューのすべてのスレッドにコミット SHA または根拠を示して返信し、解決します。
3. 最終 PR 本文全体をファイルに書き出し、その SHA-256 を固定します。本文を更新するか、PR をレビュー可能にする直前に、正確な PR URL、現在のタイトルと本文、ベースとヘッドの SHA、ドラフト状態、依存する PR とワークフローを最新の状態に更新します。対象ガード、固定した本文のパスとダイジェスト、正確な更新後の本文とレビュー可能な状態、更新とレビュー可能化のアクション、ユーザーによるレビュー可能化の承認を含めて、この外部メタデータの一括処理に対し preflight-mutations を実行します。その結果の契約に従い、書き込みごとにガードとダイジェストを再確認し、本文全体とドラフト状態について信頼できる読み戻しを必須とします。最終ヘッドで CI を監視します。ドラフトとマージコンフリクトがある場合、pull_request ワークフローは通知なしにスキップされるため、「失敗なし」は「一度も実行されていない」ことを意味する場合があります。最終ヘッドでワークフローが実行されたことを確認してから、成功したことを確認します。
4. 手動 QA 引き継ぎドキュメント。 これは、複数のバグ修正をまとめたチケットの標準的な完了成果物です。修正した項目ごとに、発端となったイシューコメントへのリンク、修正前に何が問題で、何が変わったかの平易な説明、ユーザーが各修正を検証するための手順を記載します。
5. 未処理の調査結果はそれぞれ、独立したチケットにします。 軽微なものは統合したフォローアップチケット 1 件にまとめます。重大な調査結果には、それぞれ専用のイシューを作成します。file-issue のセクション 6 に従い、後続チケットすべてに --label ai-created を付けます。書き換え、分割、フォローアップのイシューを作成する前に、${CLAUDE_SKILL_DIR}/../audit-ticket/references/ticket-evidence.md を再読します。その出所関係グラフとレンダリング済み完了条件は、元のイシューとすべての後続イシューに適用されます。ステージングする前に、提案する後続イシューすべてについて file-issue の 2 種類の語彙による重複検索を行い、一致したものをすべて解決します。最終本文をすべて先にレンダリングし、パスと SHA-256 ダイジェストを記録します。最初の書き込みの直前に、元のイシューの updatedAt を最新の状態に更新し、完全な一括処理に対して preflight-mutations を 1 回実行します。一括処理には、正確なリポジトリ、元のイシューの現在の状態とガード、凍結した元のイシューの調査更新またはコメントの完全なペイロード、凍結したすべての後続イシューのタイトル、本文のパスとダイジェスト、ai-created ラベルと作成オプション、重複検索クエリとその解決結果、元イシューから後続イシューへのリンク、後続イシューから先行イシューへのリンク、依存関係に関わる兄弟イシューへのリンク、情報源となる調査結果と証拠 ID、担当者、認可、レンダリング済みのイシューおよび画像の読み戻し計画を含めます。その結果の契約に従い、書き込みごとにガードとペイロードのダイジェストを再確認してから、その一括処理に含まれる書き込みのみを実行します。完了を報告する前に、レンダリング済みのイシュー一式と画像を再取得して読み直し、情報源マップと照合します。作成結果が曖昧な場合は再試行せず、preflight-mutations の reconcile-required 契約に従います。

厳守事項

ルール	理由
行き詰まったエージェント → 退任させ、引き継ぎ内容を保持してから交代する	再度促しても時間の無駄です。証拠なしに交代させると、担当者が 2 人になります
マイグレーション、マージ、ドラフト解除など、ユーザーが所有する領域 → 確認を求める	あるカテゴリへの承認が、次のカテゴリにまで及ぶことはありません