複数の観点でコードレビューを並列に回したいとき、サブエージェントだと各エージェントの結果が要約されてメインに戻るだけ。レビュアー同士が互いの指摘を突き合わせて議論する、という動きはできません。そこを埋めるのが Claude Code の実験的機能 Agent Teams。チームメイト同士が直接メッセージを交わし、共有タスクリストで仕事を奪い合いながら進みます。
サブエージェントとAgent Teamsはどこで分かれるか
どちらも並列化の道具ですが、設計思想が逆です。公式ドキュメントの “Compare with subagents” は、選ぶ基準を「ワーカー同士が会話する必要があるか」の一点に置いています。
報告だけのサブエージェント、会話するチームメイト
サブエージェントは単一セッション内で動き、メインエージェントに結果を返すだけ。中間のやり取りはサブエージェントのコンテキストに閉じ込められ、呼び出し元には最終出力しか見えません。Agent Teams のチームメイトは、それぞれが独立した Claude Code セッション。リードを介さずに、あなたが個々のチームメイトへ直接話しかけられます。
| サブエージェント | Agent Teams | |
|---|---|---|
| コンテキスト | 独立。結果は呼び出し元へ返る | 独立。完全に分離 |
| 通信 | メインエージェントへの報告のみ | チームメイト同士が直接メッセージ |
| 調整 | メインが全タスクを管理 | 共有タスクリストで自己調整 |
| トークン | 低い。結果を要約して戻す | 高い。各メイトが別インスタンス |
結果さえ戻ればいい集中タスクならサブエージェント。指摘をぶつけ合って結論を詰める作業ならチーム、という住み分けです。
トークンコストの差を最初に飲み込む
チームメイトはそれぞれが固有のコンテキストウィンドウを持ち、トークン消費はメイト数に比例して増えます。公式の “Token usage” でも、ルーティンワークには単一セッションのほうが安い、と明記されています。効くのはリサーチ・レビュー・新機能開発のように並列探索が価値を生む場面。ルーティンには向きません。
有効化と最初のチーム作成
環境変数とバージョン要件
Agent Teams はデフォルト無効の実験的機能です。settings.json か環境変数で CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS を 1 にして有効化します。
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}動作には Claude Code v2.1.32 以降が要ります。先にバージョンを確認しておきます。
claude --version2.1.32 (Claude Code)この数値を下回っていると、有効化しても TeamCreate などのツールが出てきません。
自然言語でチームを起こす
有効化したら、やりたいことと欲しいチーム構成を普通の言葉でリードに伝えます。リードがチームを作り、チームメイトを spawn し、調整まで回します。
コードベース全体のTODOコメントを追跡するCLIツールを設計したい。
別々の角度から検討するエージェントチームを作って。
1人はUX、1人は技術アーキテクチャ、1人は批判役(devil's advocate)で。3つの役割が互いに待たずに探索できるので、並列化が素直に効きます。リードのターミナルには各チームメイトと担当作業が並びます。
Team: todo-cli-design (3 teammates)
ux-explorer working: UX観点の整理
architect working: 技術構成の検討
devils-advocate working: 想定リスクの洗い出しこのリストが出れば、チームは起動済みです。
in-processとsplit panesの表示モード
表示モードは2つ。in-process は全チームメイトをメインのターミナル内で動かし、Shift+Down でメイトを切り替えて直接メッセージを打てます。追加セットアップは不要で、どの端末でも動きます。split panes は各メイトが独立したペインを持ち、全員の出力を同時に見られる代わりに tmux か iTerm2 が要ります。
既定は auto。すでに tmux セッション内にいれば split panes、そうでなければ in-process を選びます。固定したいときは ~/.claude/settings.json の teammateMode で指定します。
{
"teammateMode": "in-process"
}単発で in-process に倒すならフラグでも切り替わります。
claude --teammate-mode in-processTeammate display mode: in-processVS Code の統合ターミナル・Windows Terminal・Ghostty は split panes 非対応。これらで使うなら in-process 一択です。
並列レビューをチームで回す
Agent Teams が一番はまる用途が、観点を分けたレビュー。単独のレビュアーは一度に1種類の問題へ寄りがちで、セキュリティを見ているとテストカバレッジが手薄になります。観点ごとに担当を割れば、その偏りを構造で潰せます。
レビュー観点ごとに担当を割る
PRレビューなら、観点が重ならないように各メイトへ別のレンズを与えます。
PR #142 をレビューするエージェントチームを作って。レビュアーを3人:
- 1人はセキュリティ影響に集中
- 1人はパフォーマンス影響をチェック
- 1人はテストカバレッジを検証
それぞれレビューして指摘を報告して。3人とも同じ PR を見つつ、別のフィルタを当てます。終わったらリードが3観点の指摘を統合します。
security-reviewer done: 2 findings (1 high, 1 medium)
perf-reviewer done: 1 finding (N+1 query)
test-reviewer done: 3 findings (未カバー分岐)
lead: 統合中... 重複なし、計6件を重大度順に整理試した範囲で効いたのは、観点を文章で混ぜずに3行へ分けて書いた点。1人に「セキュリティとパフォーマンスとテストを見て」と頼むと結局1観点へ寄るので、担当を物理的に切り離すほうが網羅できました。
競合仮説で原因を絞り込む
原因が不明なバグは、単独エージェントだと最初に見つけたもっともらしい説明で探索を止めてしまいます。チームなら仮説を割り当て、互いの説を反証させられます。
ユーザーから「1メッセージ送ると接続が切れてアプリが落ちる」報告。
5人のチームメイトを spawn して別々の仮説を調査して。
互いに会話して相手の説を反証し合う、科学的な討論のように進めて。
合意が出たら findings ドキュメントを更新して。鍵は討論構造そのもの。逐次調査はアンカリングに弱く、一度ある説を掘ると後続がそれに引きずられます。互いに反証し合う独立調査者がいると、生き残った説が真の原因である確率が上がります。
チームメイトに直接指示する
各チームメイトは完全な独立セッション。途中で方針を変えたいメイトへ直接話しかけられます。in-process モードなら Shift+Down でメイトを巡回し、そのまま入力して送信。Enter でセッションを開き、Escape で現在のターンを中断、Ctrl+T でタスクリストの表示を切り替えます。公式の “Talk to teammates directly” に挙がる操作です。
タスクリストとメールボックスの仕組み
チームの調整は、共有タスクリストとメッセージングで回ります。公式の “Architecture” は構成要素を4つに分けています。
| 構成要素 | 役割 |
|---|---|
| Team lead | チームを作り、メイトを spawn し、作業を調整するメインセッション |
| Teammates | 割り当てタスクを処理する独立した Claude Code インスタンス |
| Task list | メイトが claim して完了させる共有作業リスト |
| Mailbox | エージェント間通信のメッセージング機構 |
チーム設定は ~/.claude/teams/{team-name}/config.json、タスクは ~/.claude/tasks/{team-name}/ にローカル保存されます。config はセッションIDや tmux ペインIDなどの実行時状態を持つので、手で編集したり事前に書いたりすると次の状態更新で上書きされます。
共有タスクリストとclaim
タスクは pending / in progress / completed の3状態。依存も持てて、未解決の依存があるタスクは依存先が completed になるまで claim できません。リードが明示的に割り当てる方式と、メイトが自分で次の未割り当てタスクを掴む self-claim の両方を取れます。claim はファイルロックで競合を防ぐので、複数メイトが同時に同じタスクを掴むことはありません。
チームサイズとタスク粒度の目安
メイト数に上限はないものの、トークンは線形に増え、調整コストも膨らみます。公式のベストプラクティスは 3〜5人から始め、1人あたり 5〜6タスクを持たせる構成。15個の独立タスクがあるなら3人が出発点です。公式も “Three focused teammates often outperform five scattered ones” と、集中した3人を推しています。
hooksで品質ゲートを差し込む
チームメイトが作業を終える瞬間や、タスクの作成・完了に合わせてルールを強制したいなら hooks を挟みます。
TeammateIdle: メイトがアイドルに入る直前。exit 2 でフィードバックして作業継続TaskCreated: タスク作成時。exit 2 で作成を止めてフィードバックTaskCompleted: タスク完了マーク時。exit 2 で完了を止めてフィードバック
テスト未通過のままメイトが手を止めるのを防ぐなら、TeammateIdle でテストを走らせ、失敗時に exit 2 を返してそのまま続行させる組み方になります。
実験的機能のハマりどころ
Agent Teams は experimental。公式の “Limitations” にある制約は、本番投入前に潰しておきます。
セッション再開でin-processチームメイトは戻らない
一番ハマるのがここ。/resume と /rewind は in-process のチームメイトを復元しません。再開後、リードがもう存在しないメイトへメッセージを送ろうとします。
# セッション再開後
lead: researcher にメッセージ送信...
→ teammate "researcher" not foundこの状態になったら、リードに新しいメイトを spawn し直すよう伝えれば復帰します。
researcher を spawn し直して、調査を続けて1度に1チーム、入れ子は不可
リードが管理できるチームは1つだけ。新しいチームを作る前に、現在のチームを cleanup する必要があります。チームメイトが自分のチームやメイトを spawn することもできません。リードを務めるのはチームを作ったセッションで固定、途中でメイトをリードに昇格させたり権限を移したりもできません。終わったらリードに後片付けを頼みます。
チームを片付けて(clean up the team)cleanup はアクティブなメイトが残っていると失敗するので、先に各メイトを shut down させてから実行します。tmux セッションが残ったときは手で消します。
tmux ls
tmux kill-session -t <session-name>まとめ
- サブエージェントは結果を報告するだけ、Agent Teams はチームメイト同士が直接メッセージを交わし共有タスクリストで自己調整する
- 有効化は
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1、動作には Claude Code v2.1.32 以降が要る - 表示モードは in-process と split panes。後者は tmux か iTerm2 が必要で、VS Code・Windows Terminal・Ghostty では使えない
- 観点を分けた並列レビューと、互いに反証し合う競合仮説の調査が、チームの効く代表的な用途
- 3〜5人・1人あたり5〜6タスクが目安。トークンは人数に比例して増える
- experimental ゆえ /resume で in-process メイトが戻らない、1度に1チーム、入れ子不可などの制約がある
まずは PR レビューやバグ調査のように境界がはっきりした読み取り中心のタスクから入ると、並列実装の調整コストを避けつつチームの価値を確かめられます。