1 人の Claude では追いつかない ─ Claude Code Agent Teams 入門【処方箋#13】

「PR が積み上がっていく」「同僚にレビューを頼んでも 2 日返ってこない」「Claude に並列で見てほしいけど、Subagent では観点同士で議論できない」。シリーズ #12 同僚にレビューを頼むのを諦めた日 で扱った PR レビュー 3 ルートのうち、Managed Code Review は内部で複数エージェントを走らせて多視点のレビューを作っていました。

本記事ではその「複数の Claude を並列で動かす」運用を、自分の手元の Claude Code でも実現する公式の試験運用機能（experimental） Agent Teams を扱います。Subagent（#05）の延長線で「同じ作業をもう一段スケールさせたい」と感じたタイミングで読む記事です。

TL;DR

• Agent Teams は複数の Claude Code セッションを「同僚」として並列で動かす公式機能。試験運用扱いで、v2.1.32+ と CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 の有効化が必要（公式ドキュメント）
• Subagent（#05）との違いは 2 つだけ。1 つは メンバー同士が直接メッセージを送れること、もう 1 つは 共有タスクリストでメンバーが自分で次の作業を取りに行けること
• 向くのは PR の並列レビュー・競合仮説の検証・観点分担のリサーチ。向かないのは結果だけ欲しい焦点タスク（Subagent のままにする）
• 罠 4 つ: トークン消費が線形に増える / 同じファイルを複数メンバーに編集させて衝突 / リードがメンバーを待たずに自分で着手 / サブエージェント定義（#05）の skills と mcpServers はメンバー起動時には継承されない
• 今週やる 1 つ: Create an agent team to review PR #<番号>... の 1 プロンプトで PR の 3 観点並列レビューを回す

Subagent を 3 つ並べても、観点同士は議論できなかった

シリーズ #05 専門タスクは専門家へ で Subagent を扱いました。security-reviewer performance-checker test-coverage-auditor のような専門 Subagent を 3 つ作って、メイン会話から逐次や並列で呼べば、観点ごとに独立したコンテキストウィンドウで並列にレビューを走らせられます。

ところが、Subagent の制約に当たります。

• Subagent は呼び出し元（メインエージェント）にしか結果を返せない
• 同時に走る 2 つの Subagent が、互いの中間結果を見て「自分の仮説に反論する材料」を取り合うことはできない
• 観点 A が「ここは安全のためロックを増やすべき」と言い、観点 B が「ここはパフォーマンスのためロックを減らすべき」と言うとき、メインエージェントが両者の要約を読んでから初めて衝突が見える。Subagent 同士で「あなたの提案だとうちの観点が壊れる」と直接やり取りはできない

実務では、この「観点同士の議論」が抜けているせいで、AI レビューが「セキュリティ重視」「パフォーマンス重視」のような単観点に偏る現象が起きます。Anthropic 公式ベストプラクティスもこの現象を アンカリング（最初に見つけた仮説に引きずられる） と呼び、独立した調査者を複数走らせて互いの仮説を反論させ合うほうが、生き残った仮説が真の根本原因である可能性が高いと書いています（公式ドキュメント）。

Agent Teams は「同僚」を立ち上げる

公式ドキュメントから定義を引きます。

Agent teams let you coordinate multiple Claude Code instances working together. One session acts as the team lead, coordinating work, assigning tasks, and synthesizing results. Teammates work independently, each in its own context window, and communicate directly with each other. Unlike subagents, which run within a single session and can only report back to the main agent, you can also interact with individual teammates directly without going through the lead.

エージェント チームを使用すると、連携する複数のクロード コード インスタンスを調整できます。 1 つのセッションはチームのリーダーとして機能し、作業を調整し、タスクを割り当て、結果を統合します。チームメイトはそれぞれ独自のコンテキスト ウィンドウで独立して作業し、互いに直接通信します。単一セッション内で実行され、メイン エージェントにのみ報告できるサブエージェントとは異なり、リードを介さずに個々のチームメイトと直接対話することもできます。

ポイントを 2 つに要約するとこうなります。

1. メンバー同士が直接話せる: 共有のメールボックス（メッセージを溜める受信箱の仕組み）経由で SendMessage ツールが使える。観点 A のメンバーが観点 B のメンバーに直接「あなたの提案だとロックが解放されない問題が出る」と投げられる
2. 共有タスクリストで自分から作業を取りに行ける: リードが全部の作業を抱えなくても、メンバーが手の空いたタイミングで未割り当ての作業を自分で取りに行く（ファイルロックで競合は防がれる）

Subagent との関係を 1 枚にまとめます。

flowchart LR subgraph Sub["Subagents（#05 で扱った）"] M["メインエージェント<br/>（あなたが話している<br/>セッション）"] M --> A["サブエージェント A"] M --> B["サブエージェント B"] M --> C["サブエージェント C"] A -- 結果 --> M B -- 結果 --> M C -- 結果 --> M end subgraph Team["Agent Teams（本記事）"] L["チームリード<br/>（あなたが話している<br/>セッション）"] T1["メンバー 1<br/>独立セッション"] T2["メンバー 2<br/>独立セッション"] T3["メンバー 3<br/>独立セッション"] Task[("共有タスクリスト<br/>~/.claude/tasks/")] L --- T1 L --- T2 L --- T3 T1 -. メッセージ .- T2 T2 -. メッセージ .- T3 T1 -. メッセージ .- T3 L --- Task T1 --- Task T2 --- Task T3 --- Task end

両者を表にまとめるとこうなります。

向き不向きを 1 行で言うなら、「結果が欲しい」なら Subagent、「議論が欲しい」なら Agent Teams です。

有効化と最小の動かし方

Agent Teams はデフォルト無効です。次の 2 つを満たしてから使います。

1. バージョン: claude --version で 2.1.32 以上を確認
2. 有効化: ~/.claude/settings.json（settings.json の階層は #09 settings 階層 参照）の env に CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS を追加

{ "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" }
}

シェルから一回切りで有効化したい場合は次のようにも書けます（公式ドキュメントの有効化手順章）。

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude

ここから先は自然言語のプロンプト 1 つでチームが立ち上がります。たとえば公式ドキュメントが提示している例はこうです。

私は開発者がコードベース全体で TODO コメントを追跡できるようにする CLI ツールを設計しています。これをさまざまな角度から調査するエージェント チームを作成します。1 人のチームメイトは UX、1 人は技術アーキテクチャ、もう 1 人は悪魔の代弁者です。

このプロンプト 1 つで、リードが 3 体のメンバーを立ち上げ、共有タスクリストを作り、メンバー同士が観点ごとの調査を進めます。リードのターミナルには全メンバーと各自の作業が並び、Shift+Down でメンバーを巡回してメッセージを送れます（同一プロセス内モード）。

tmux か iTerm2 が入っていれば分割ペイン モードに切り替えてメンバーごとに別ペインを持たせることもできます。teammateMode を ~/.claude/settings.json に書いて固定するか、起動時に claude --teammate-mode in-process で上書きします（公式ドキュメントの表示モード章）。

どこに何が保存されるか（構造）

公式ドキュメントのアーキテクチャ章に、チームの構成要素が 4 つだけ列挙されています。

チームの設定ファイルとタスクリストはローカルに保存されます。

• チーム設定: ~/.claude/teams/{team-name}/config.json
• タスクリスト: ~/.claude/tasks/{team-name}/

公式ドキュメントはこのファイルを 手で編集しない ように明記しています（チームの立ち上げ時に実行時状態で上書きされるため）。再利用したいメンバーの役割があるなら、サブエージェント定義（#05 で扱った .claude/agents/*.md）として書いて、立ち上げ時に Spawn a teammate using the security-reviewer agent type ... のように名前で参照します（公式ドキュメントのサブエージェント定義をメンバーに使う章）。

ただし、ここに 1 つ罠があるので後ろの「罠 4」で扱います。

罠 4 つ

罠 1: Subagent と同じ感覚で「結果が欲しい焦点タスク」に Agent Teams を使う

Agent Teams はメンバーごとに独立した Claude インスタンスを動かすので、トークン消費がメンバーの数だけ線形に増えます。公式ドキュメントは次のように書いています。

Agent teams use significantly more tokens than a single session. Each teammate has its own context window, and token usage scales with the number of active teammates. For research, review, and new feature work, the extra tokens are usually worthwhile. For routine tasks, a single session is more cost-effective.

エージェント チームは、単一セッションよりもはるかに多くのトークンを使用します。各チームメイトには独自のコンテキスト ウィンドウがあり、トークンの使用量はアクティブなチームメイトの数に応じて変化します。研究、レビュー、新機能の作業には、通常、追加のトークンが価値があります。日常的なタスクの場合は、1 回のセッションの方がコスト効率が高くなります。

判断基準を 1 つ持っておくと迷いません。メンバー間の議論が成果に寄与しないなら、Subagent のままに。観点 A の出した中間結果を観点 B が読んで反論することで結論が変わる場合だけ Agent Teams にする、と決めておくとトークンの無駄遣いが減ります。

罠 2: 同じファイルを複数メンバーに編集させる

公式ベストプラクティスに「2 人のチームメイトが同じファイルを編集すると上書きが発生する」と書いてあります（公式ドキュメントのファイル衝突を避ける章）。共有タスクリストは作業間の依存関係は管理しますが、同じファイルに対する書き込み衝突は防ぎません。

対策は立ち上げ時のプロンプトでメンバーごとに担当ファイル領域を明示的に分けることです。

エージェント チームを作成して、認証モジュールをリファクタリングします。3 人のチームメイトを生成します:
- チームメイトの "tokens" は src/auth/tokens/** を所有します。
- チームメイトの "session" は src/auth/session/** を所有します。
- チームメイトの "tests" は testing/auth/** を所有します。
チームメイトは自分のスコープ外に書き込むべきではありません。

層をまたいで触らざるを得ない箇所は、メンバー間で作業を作って引き渡す（作業の依存関係を貼る）のが定石です。

罠 3: リードがメンバーを待たずに自分で実装し始める

これは公式ドキュメントのトラブルシューティング章に明記された既知の挙動です。

Sometimes the lead starts implementing tasks itself instead of waiting for teammates. If you notice this: Wait for your teammates to complete their tasks before proceeding

場合によっては、リードがチームメイトを待つのではなく、自らタスクの実装を開始することがあります。これに気付いた場合: 先に進む前に、チームメイトがタスクを完了するまで待ってください。

立ち上げプロンプトの最後に Wait for all teammates to finish before synthesizing. の 1 行を入れる癖をつけておくと、リードが勝手に着手する事故が減ります（公式ドキュメントのメンバーの完了を待つ章）。

罠 4: サブエージェント定義の skills と mcpServers はメンバー起動時には継承されない

#05 で作ったサブエージェント定義（~/.claude/agents/security-reviewer.md のようなファイル）を、Agent Teams のメンバーとしても再利用できます。「security-reviewer のエージェント型を使ってメンバーを立ち上げて」と頼むと、その定義の tools 許可リストと model 指定がメンバーに引き継がれます。

ところが、サブエージェント定義に書いた skills: と mcpServers: フィールドは メンバーとして起動するときには適用されません。公式ドキュメントはこう書いています。

The skills and mcpServers frontmatter fields in a subagent definition are not applied when that definition runs as a teammate. Teammates load skills and MCP servers from your project and user settings, the same as a regular session.

サブエージェント定義の「skills」および「mcpServers」フロントマター フィールドは、その定義がチームメイトとして実行される場合には適用されません。チームメイトは、通常のセッションと同じように、プロジェクトとユーザー設定からスキルと MCP サーバーを読み込みます。

メンバーごとに別のスキル一式を与えたい運用は、サブエージェント定義経由では実現できません。メンバー全員に同じスキル一式を行き渡らせたいなら、~/.claude/skills/ か .claude/skills/ に置いて全員が読める形にします（スキルの置き場所は #04 プロンプトを資産化する Claude Skills 入門 を参照）。

まとめ

Subagent（#05）は「結果だけ欲しい下請け」、Agent Teams は「議論できる同僚」。

観点が独立で並列に動かせる場面、競合仮説を互いに反論させたい場面で初めて、トークンをメンバー数だけ余分に払う価値が出ます。逆に焦点を絞った結果だけ欲しい作業は 1 セッションか Subagent のままにする。「議論が欲しいか、結果が欲しいか」 で選び分けるのが現時点での落としどころです。

Anthropic 公式が試験運用と明記しているうちは、セッション再開・シャットダウンの遅延・チームの入れ子不可といった制約をふまえて使う。それでも、PR の並列レビュー 1 つを Create an agent team to review PR #<番号>... の 1 プロンプトで回せるようになった現在地は、Subagent しか手段がなかった半年前と比べると静かに大きな前進です。