Agent Teams並列コードレビューの実践 — 対立仮説でバグ原因を絞る

この2つのユースケースで何が変わるか

1人のレビュアーは、放っておくと一度に1種類の観点しか深掘りしません。セキュリティを見ていればパフォーマンスが手薄になり、バグ調査では最初に浮かんだ仮説に引っ張られがちです。Agent Teamsは、観点や仮説をチームメイトごとに割り当てて同時に走らせることで、この偏りを構造的に解消します。ここでは並列コードレビューと対立仮説による原因調査という2つの代表的な使い方を、実際に投げるプロンプトとともに見ていきます。

始める前の前提は2つだけです。settings.jsonのenvにCLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: "1"を設定していること、そして対話セッションで使うことです。非対話モード(-pフラグ)やAgent SDK経由のセッションではチームメイトは生成されません。

ステップ1: 観点を分けて並列コードレビューを回す

1人のレビュアーがPR全体を通しで見ると、セキュリティ・パフォーマンス・テストカバレッジのどれかに注意が偏りがちです。Agent Teamsでは、同じPRに対して異なるフィルターを持つチームメイトを同時に走らせることで、3つの観点すべてに等しく厚い注意を向けさせます。

Spawn three teammates to review PR #142:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.

日本語で書くなら「PR #142を3人でレビューして。1人目はセキュリティへの影響、2人目はパフォーマンスへの影響、3人目はテストカバレッジを担当し、それぞれ調べた結果を報告して」という指定になります。3人のチームメイトは同じPRを見ますが、それぞれ異なるフィルターを通して読みます。全員の作業が終わると、リードが3つの報告を統合します。ここで重要なのは、プロンプトの中で観点を明示的に分けている点です。「レビューして」とだけ指示すると、3人とも似たような一般的な指摘に収束してしまい、並列化の効果が薄れます。

ステップ2: 対立仮説でバグの原因調査を進める

原因が絞り込めていないバグは、1人で調査すると最初に見つかった説明で止まってしまいがちです。この偏りへの対処として、チームメイト同士を意図的に対立させるプロンプトが有効です。

Users report the app exits after one message instead of staying connected.
Spawn 5 agent teammates to investigate different hypotheses. Have them talk to
each other to try to disprove each other's theories, like a scientific
debate. Update the findings doc with whatever consensus emerges.

日本語にすると「アプリが1メッセージで接続が切れるという報告があります。5人のチームメイトをスポーンして、それぞれ違う仮説から調査してください。互いの仮説を科学的な議論のように反証し合い、合意が形成された内容をfindings docに反映してください」という指示です。鍵になるのは「互いの仮説を打ち崩そうとする」という指示そのものです。1人で順番に仮説を調べていくと、最初に検証した仮説に引きずられるアンカリングが起きます。複数の調査者が独立して動き、互いの仮説を積極的に反証しようとする構造にすると、最後まで反証されずに残った仮説が実際の原因である確率は大きく上がります。生き残った仮説が正しいという保証はありませんが、一人称の調査より収束の質が高くなります。反証を試みる相手がいるだけで、調査の粗さが浮き彫りになる構造です。

2つのユースケースに共通する設計原則

どちらのプロンプト例にも共通しているのは、チームメイトに割り当てる「レンズ」を具体的な言葉で書いていることです。「レビューして」「調査して」ではなく、「セキュリティの影響」「パフォーマンスへの影響」「テストカバレッジの検証」、あるいは仮説そのものを名指しで割り当てています。レンズが曖昧だと、複数のチームメイトが同じ範囲を重複して調べるだけになり、チームを組むコストに見合いません。

もう1つの共通点は、最終的な統合をリードに任せていることです。3人のレビュー結果や5人の仮説検証結果を1つの結論にまとめる作業は、個々のチームメイトではなくリードの役割として設計されています。チームメイトへの指示に「統合して報告して」まで含めると、統合作業がどのチームメイトにも中途半端に割り当てられ、抜け漏れが起きやすくなります。

途中で観点がずれていると感じたら、リード経由で全員に指示を出し直すのではなく、該当のチームメイトだけを名指しして直接メッセージを送るほうが早く軌道修正できます。セキュリティ担当が認証以外の実装詳細に時間を使いすぎているなら、その担当者にだけ「認証まわりに絞って」と送れば、他の担当者の作業には影響しません。

レビュー結果の品質を一定に保ちたい場合は、HooksのTeammateIdleイベントを使って、チームメイトが作業を終えようとしたタイミングでチェックを挟む方法もあります。指摘の重要度ラベルが付いていない、特定のセクションに触れていない、といった基準を機械的にチェックし、満たしていなければ終了をブロックしてフィードバックを返せます。

完了はどう伝わるか

3人や5人のチームメイトを走らせている間、リードの完了をポーリングして待つ必要はありません。チームメイトが作業を終えて停止すると、自動的にリードへ通知が届き、その通知には最終的な回答も含まれます。APIエラーでターンが終わった場合も、失敗したこととエラー内容が同じ仕組みでリードに伝わる設計です。並列コードレビューで3人の報告を待つときも、対立仮説の調査で5人の結論を待つときも、リードは各チームメイトからの通知を受け取るたびに統合作業を進められます。

タスクの数がプロンプト1行の指示より多い場合は、共有タスクリストを使う設計に切り替えると管理しやすくなります。レビュー対象のファイルが10本あるなら、3人のチームメイトに3観点を割り当てるだけでなく、ファイルごとにタスクを立てて自己申告制で拾わせる方法もあります。タスクは保留・進行中・完了の3状態を持ち、依存関係があるタスクは前提が完了するまで着手できません。ファイル間に依存がないレビューでは、この仕組みを使わずシンプルにプロンプトで3人に割り振るだけでも十分です。

よくあるつまずき

「4人でこのPRをレビューして」とだけ投げると、4人とも同じような一般的な指摘に落ち着きます。観点を割り当てずに複数人を投げるパターンです。観点や仮説を1人ずつ具体的に書き分けるところまでがプロンプトの仕事です。

対立構造を作らずに調査を分散させるパターンも同じ結果を招きます。5人にバグ調査を任せても、「互いの仮説を反証し合う」という指示がなければ、それぞれが独立した一人称調査を5回繰り返すだけで終わります。ディベート構造そのものが精度を上げる鍵なので、この一文を省略しないでください。

見落としやすいのは前提知識の引き継ぎです。

• チームメイトはリードの会話履歴を引き継ぎません
• PR番号やバグの再現手順は書いても、「なぜこのPRが出たか」「過去に似た不具合があったか」のような背景はスポーンプロンプトに含めない限り伝わりません
• 背景情報が要る調査ほど、スポーン時点で明示的に渡す必要があります

レビューや調査は読み取り中心の作業なので競合が起きにくく、Agent Teamsを試す最初のタスクとして向いています。ここでファイルを編集させながら並列レビューさせてしまうと、話は変わってきます。修正の実装まで同時に進めさせると、同じファイルへの書き込みが競合するリスクが一気に高まるからです。

Sub-agentsではなくAgent Teamsを使う理由

同じ並列レビューはSub-agentsでも一見できそうに見えます。違いは、チームメイト同士がリードを介さず直接メッセージをやり取りできるかどうかです。対立仮説の調査は、この直接対話が本質的な役割を果たします。仮説Aを担当するチームメイトが仮説Bの担当者に「その根拠は◯◯で説明がつかないのでは」と直接ぶつけられるからこそ、ディベート構造が成立します。Sub-agentsは結果をリードに返すだけの一方向の関係なので、この相互反証は起きません。

一方、観点を分けるだけで相互作用が不要な並列コードレビューは、実はSub-agentsの並列実行パターンでも近い効果が得られます。チームメイト間の直接対話が必要かどうかが、どちらを選ぶかの分かれ目です。複数のセッションをまたいで結果を受け渡したいだけなら、セッション間の連携という選択肢もあります。

よくある質問

レビュー担当のチームメイトは何人が適切ですか

観点の数に合わせるのが基本です。セキュリティ・パフォーマンス・テストカバレッジの3観点なら3人、それ以上に観点を増やすなら4〜5人まで広げても構いません。観点の数より多い人数を割り当てても、重複した指摘が増えるだけです。

対立仮説の調査で意見が割れたままになったらどうしますか

「合意が形成された内容をfindings docに反映する」という形が、公式のプロンプト例で示されています。完全な合意に至らない場合は、反証されずに残った仮説を優先順位の高い候補としてリードにまとめさせ、次の検証ステップを人間が判断する運用が現実的です。

レビューと実装を同じチームで同時に進めてよいですか

レビューや調査は読み取り中心でファイル競合が起きにくい一方、実装は書き込みが発生します。同じチームで同時に走らせると、2人のチームメイトが同じファイルを編集して片方の変更が上書きされるリスクが高まります。まずレビューや調査で結論を出し、実装は担当ファイルを設計し直してから別タスクにする進め方が安全です。

対立仮説の手法はバグ調査以外にも使えますか

設計の意思決定や、複数の実装方針のどちらが良いかを検討する場面にも応用できます。「案Aを支持するチームメイト」「案Bを支持するチームメイト」を立てて互いに反論させると、単独で検討するより見落としが減るのが利点です。ライブラリの選定やアーキテクチャの見直しのように、正解が1つに決まらない意思決定ほど、対立構造を作る効果は大きくなります。

まとめ

並列コードレビューは観点を、対立仮説調査は仮説そのものを、チームメイトごとに明示的に割り当てることが成否を分けます。どちらも読み取り中心のタスクなのでファイル競合のリスクが低く、Agent Teamsを初めて試す題材として最適です。チームメイト同士が直接対話できる点がSub-agentsとの決定的な違いで、特に対立仮説による反証はこの仕組みがあって初めて機能します。