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

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

1人のレビュアーは、放っておくと一度に1種類の観点しか深掘りしません。セキュリティを見ていればパフォーマンスが手薄になり、バグ調査では最初に浮かんだ仮説に引っ張られがちです。Agent Teamsは、観点や仮説をチームメイトごとに割り当てて同時に走らせることで、この偏りを構造的に減らします。

ここでは並列コードレビューと、対立仮説による原因調査を扱います。どちらも読み取り中心の作業で、Agent Teamsを最初に試す題材に向いています。始める手順は次のとおりです。

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

同じPRに対して、異なるフィルターを持つチームメイトを同時に走らせます。3人が別々のレンズで読むので、セキュリティ・パフォーマンス・テストカバレッジの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つの報告を統合します。

プロンプトの中で観点を明示的に分けるのが肝心です。「レビューして」とだけ指示すると、3人とも似たような一般的な指摘に収束し、並列化の効果が薄れます。

レビュアーのモデルを指定する

チームメイトのモデルは、スポーンのプロンプトで指定できます。読み取り中心のレビューなら、軽いモデルに寄せてコストを抑える選択肢があります。

Spawn three teammates to review PR #142, one each for security,
performance and test coverage. Use Sonnet for each teammate.

モデルは次の順で決まります。

1. スポーンのプロンプトでそのチームメイトに指定したモデル
2. サブエージェント定義から生成した場合は、定義のmodel
3. CLAUDE_CODE_SUBAGENT_MODEL(inherit以外のとき)
4. リードの現在のモデル

CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1(v2.1.257以降)を設定すると、1番と2番は適用されません。全チームメイトのモデルが環境変数で決まります。

チームメイトのモデルはスポーン時に固定され、/modelはチームメイトではなくリードのモデルを変えます。

毎回使うレビュアーはサブエージェント定義にする

セキュリティ担当のような役割は、サブエージェント定義にしておくと毎回書かずに済みます。定義はサブエージェントとしても、チームメイトとしても使えます。

---
name: security-reviewer
description: 認証・入力検証・秘密情報の扱いを重点的にレビューする
tools: Read, Grep, Glob
model: sonnet
---
認証、セッション管理、入力検証に絞ってレビューし、
指摘ごとに重要度を付けて報告してください。

これを.claude/agents/security-reviewer.mdに置き、「security-reviewerのエージェントタイプでチームメイトを1人スポーンして」と頼みます。toolsの制限とmodelは引き継がれ、本文は追加の指示になります。一方、定義のskillsはチームメイトには適用されません。インプロセスのチームメイトでは、mcpServersも無視されます。

ステップ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に反映してください」という指示です。

鍵は「互いの仮説を打ち崩そうとする」という一文です。順番に仮説を調べると、最初に検証した仮説に後の調査が引きずられるアンカリングが起きます。複数の調査者が独立して動き、互いに反証し合う構造なら、最後まで反証されずに残った仮説が本当の原因である可能性は高くなります。ただし、残った仮説の正しさが保証されるわけではありません。

チームメイトは名前で互いにメッセージを送り合います。後の指示で特定の担当者を呼び出せるように、スポーンの指示で「それぞれを何と呼ぶか」まで決めておくと、あとから話しかけやすくなります。

設計の要点: レンズの具体化と統合の担当

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

最終的な統合はリードの仕事として設計されています。3人のレビュー結果や5人の検証結果を1つにまとめるのはリードで、個々のチームメイトに「統合して」まで頼むと、作業が中途半端に分散して抜け漏れが起きやすくなります。

人数は、観点や仮説の数に合わせます。公式ドキュメントは、ほとんどのワークフローで3〜5人から始めるよう示しています。人数に厳しい上限はありませんが、人数が増えるとトークンコストと調整の手間が増え、ある時点から作業は比例して速くなりません。3人の焦点を絞ったチームメイトが、5人の散らばったチームメイトより良いこともあります。

実行中に使う操作

走り出したあとは、エージェントパネルでチームメイトを選んで介入します。

セキュリティ担当が認証以外の実装詳細に時間を使いすぎているなら、その担当者のトランスクリプトを開いて「認証まわりに絞って」と送れば、他の担当者の作業には影響しません。

表示モードは、既定がインプロセスです。全員を1つのターミナルの中で動かします。各チームメイトを別ペインに並べる分割ペインは、tmuxかiTerm2が必要で、teammateModeを"auto"か"tmux"にするか、--teammate-modeフラグで切り替えます。"auto"は、tmux内かit2入りのiTerm2のときだけ分割し、それ以外はインプロセスのままです。--teammate-modeフラグは実験的で、claude --helpには表示されません。分割ペインはVS Codeの統合ターミナル、Windows Terminal、Ghosttyでは使えません。

権限プロンプトはリードに集まる

チームメイトはリードの権限モードで始まります(dontAskモードは継承しません)。チームメイトの権限プロンプトは、リードのセッションに表示されます。読み取り中心のレビューでも、git logやgrepなどの確認が止まるので、よく使う読み取り操作は先に権限設定で許可しておくと中断が減ります。

スポーン時にチームメイトごとの権限モードを決めることはできません。生成後に個別に変えることはできます。

品質ゲートをHooksで挟む

レビュー結果の品質を一定に保ちたいときは、Hooksが使えます。TeammateIdleはチームメイトが作業を終えようとしたときに動き、終了コード2でフィードバックを返すと、チームメイトは作業を続けます。指摘の重要度ラベルが付いていない、特定のセクションに触れていない、といった基準を機械的に検査できます。TaskCreatedとTaskCompletedも終了コード2で、タスクの作成や完了を止められます。

完了の伝わり方とタスクの切り方

完了をポーリングして待つ必要はありません。チームメイトが作業を終えて停止すると、最終的な回答を含む通知が自動でリードに届きます。APIエラーでターンが終わったときも、失敗とエラー内容が同じ仕組みで伝わります。リードは通知のたびに統合を進められます。

レビュー対象のファイルが多いときは、観点で割り振るだけでなく、共有タスクリストを使う方法もあります。タスクは保留・進行中・完了の3状態を持ち、依存関係のあるタスクは前提が完了するまで着手できません。リードが割り当てるほか、チームメイトが次の未割り当てのタスクを自分で取ることもできます。取り合いはファイルロックで防がれます。

タスクの大きさには目安があります。関数やテストファイル、レビュー1件のように、成果物がはっきりした自己完結の単位が適切です。公式ドキュメントはチームメイト1人あたり5〜6タスクを例に挙げ、15個の独立したタスクなら3人から始めるよう示しています。ファイル間に依存がないレビューは、タスクリストを使わずプロンプトで3人に割り振るだけでも足ります。

トークンコストはチームメイトの数だけ増える

よくあるつまずき

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

対立構造を作らずに調査を分散させても、同じ結果になります。「互いの仮説を反証し合う」という指示がなければ、5人がそれぞれ独立した調査を繰り返すだけで終わります。

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

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

動き出したあとに起きやすい挙動も、公式ドキュメントに挙がっています。

• リードが、チームメイトの完了を待たずに自分で作業を始めることがあります。「チームメイトのタスク完了を待ってから進めて」と指示します
• チームメイトがエラーのあとに回復せず止まることがあります。トランスクリプトを開いて追加の指示を送るか、置き換えのチームメイトをスポーンします
• リードが、全タスクの完了前にチームの作業を終えたと判断することがあります。続けるよう指示します
• チームメイトがタスク完了のマークに失敗し、依存するタスクが止まることがあります。作業が終わっているかを見て、状態を手動で更新するか、リードに促させます

構造上の制約もあります。/resumeと/rewindはインプロセスのチームメイトを復元しません。セッションは1つのチームしか持てず、チームメイトが自分のチームメイトをスポーンすることもできません。リードは固定で、途中で交代できません。長いレビューを再開しながら続ける運用には向きません。

レビューや調査は読み取り中心なので、ファイル競合が起きにくい作業です。修正の実装まで同時に進めさせると、2人が同じファイルを編集して上書きが起きるリスクが高まります。実装は、担当ファイルを分けてから別のタスクとして走らせます。

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

同じ並列レビューはSub-agentsでもできそうに見えます。分かれ目は、結果の返り方と、共有タスクリストの有無です。

対立仮説の調査では、仮説Aの担当者が仮説Bの担当者へ「その根拠は◯◯で説明がつかないのでは」と直接ぶつけられることが、ディベート構造の土台になります。観点を分けるだけで相互作用が要らない並列レビューなら、Sub-agentsの並列実行パターンでも近い効果が得られます。サブエージェントがコンテキストとプロンプトキャッシュを引き継いで並列実行される設計は、Claude Codeのサブエージェント並列設計にまとめています。

Agent Teamsを有効にしている間は、Claudeが名前を付けたサブエージェントがチームメイトとして起動します。サブエージェントのままにしたいときは、CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMSを0にします。新しいセッションを始める必要はありません。ただし、プロジェクト設定やマネージド設定が1を指定している場合は、そちらが優先されます。複数のセッションをまたいで結果を受け渡したいだけなら、セッション間の連携という選択肢もあります。

まとめ

並列コードレビューは観点を、対立仮説調査は仮説そのものを、チームメイトごとに具体的な言葉で割り当てると成立します。まずは読み取り中心の1本のPRで試し、人数は観点の数に合わせて3人程度から始めると、コストと調整の手間を見ながら広げられます。