Agent Teams は、複数の Claude Code セッションを「チーム」として同時に走らせる実験的機能です。サブエージェントと違い、teammate 同士が直接メッセージを送り合い、共有タスクリストから自分で仕事を取ります。本記事では有効化の方法、サブエージェントとの使い分け、そして mailbox・タスクリストの実体と権限モデルを、手元の Claude Code v2.1.241 で確認しながら整理します。既定では無効で、有効にすると通常の委譲の挙動まで変わる点が最大の注意点です。
30秒でわかる Agent Teams
・既定で無効。CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 で有効化（v2.1.241 のバイナリに9箇所出現を確認）
・対話セッション専用。-p の非対話モードと Agent SDK では teammate は生成されない
・有効にすると通常の委譲も変わる。「名前つきサブエージェント」が自動で teammate になり、頼んでいなくてもチームが組まれる
・実体はファイルベース。mailbox は ~/.claude/teams/{team}/inboxes/{agent}.json、タスクは ~/.claude/tasks/{team}/
・teammate は権限を回避できない。拒否された操作を別の teammate に中継させることもできない
・トークンコストは高い。teammate ごとに別の Claude インスタンスが立つ
Claude Code 本体の設定はClaude Code｜2026年版・インストールからCLAUDE.md・Hooks・本番運用までの実装手引きにまとめています。本記事はその上で「並列に走らせる」話です。
Agent Teamsとは — 自己調整するチーム
Agent Teams は、リーダーとなるメインセッションが teammate（別の Claude Code インスタンス）を起動し、共有タスクリストとメールボックスで協調させる仕組みです。
構成要素は4つです。
| 要素 | 役割 |
|---|---|
| Team lead | teammate を起動し作業を調整するメインセッション |
| Teammates | 割り当てられたタスクを処理する独立した Claude Code インスタンス |
| Task list | teammate が自分で取りにいく共有の作業リスト |
| Mailbox | エージェント間の通信 |
公式が挙げる「効く」ケースは、並列に探索することに実際の価値があるタスクです。
・調査とレビュー：複数の teammate が別々の観点を同時に調べ、互いの結論をぶつける
・新規モジュール／機能：teammate がそれぞれ別の部分を担当し、衝突しない
・仮説が競合するデバッグ：異なる仮説を並列に検証して収束を早める
・レイヤー横断の調整：フロント・バック・テストをそれぞれ別の teammate が持つ
逆に公式は、はっきりこう釘を刺しています。
Agent teams add coordination overhead and use significantly more tokens than a single session. … For sequential tasks, same-file edits, or work with many dependencies, a single session or subagents are more effective.
逐次処理・同一ファイルの編集・依存関係の多い作業には向きません。
表示モードと操作
リーダーのターミナルでは、プロンプト入力欄の下のエージェントパネルに teammate が並びます。上下キーで選択、Enter でその teammate のトランスクリプトを開いて直接メッセージ、Escape で現在のターンを中断、という操作です。teammate ごとに分割ペインを割り当てる表示モードも用意されています。
パネルの挙動には版差があります。v2.1.199 以降は、他の teammate かサブエージェントがまだ動いている間、アイドルになった teammate の行もパネルに残ります（選択してトランスクリプトを読んだり追加の仕事を渡したりできる）。全員がアイドルになると30秒後に行が隠れ、次のターンで再表示されます——隠れている間も teammate は動き続けており、宛先としては有効です。v2.1.181〜v2.1.198 では、他が動いていてもアイドルになった行は自身のターン終了30秒後に隠れていました。v2.1.181 より前はそもそも隠れません。
4人以上がアイドルになると、先頭3行を超えた分は 2 idle agents のような1行にまとまります。
サブエージェントとの違い — どちらを使うか
並列化の手段としてはサブエージェントもあります。公式の比較を整理すると次のようになります。
| サブエージェント | Agent Teams | |
|---|---|---|
| コンテキスト | 独自のウィンドウ。結果は呼び出し元へ返る | 独自のウィンドウ。完全に独立 |
| 通信 | 呼び出し元へ結果を返す | teammate 同士が直接メッセージ |
| 調整 | 親エージェントが全部管理 | メッセージによる自己調整＋共有タスクリスト |
| 向くもの | 結果だけが必要な focused なタスク | 議論と協調が要る複雑な作業 |
| トークンコスト | 低い（結果が要約されて親に戻る） | 高い（teammate ごとに別インスタンス） |
判断基準はシンプルです。 「投げて結果だけ受け取りたい」ならサブエージェント。「途中で互いの発見を共有し、反論させたい」なら Agent Teams。コストが素直に効くので、迷ったらサブエージェントから始めるのが安全です。
なお、チームを組まずにセッション間でメッセージを渡すだけなら cross-session messaging という別の仕組みもあります。用途が「他のセッションに一言伝える」だけなら、そちらのほうが軽く済みます。
Claude Code を動かす面が増えていることはClaude Code Webとは｜–cloudと–teleportの使い方・制約をCLI実測で解説でも触れましたが、Agent Teams は「1台の中で並列にする」方向で、クラウドセッションの「手元を離れて走らせる」方向とは軸が違います。両方を組み合わせると、クラウド側で長い作業を回しつつ手元でチームを組む、といった構成も取れます。
有効化の方法と、有効にすると変わること
Agent Teams は既定で無効です。 環境変数で有効化します。
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
シェルの環境変数でも同じです。手元の Claude Code v2.1.241 のバイナリを調べたところ、この文字列が 9箇所に現れました。実験的とはいえ実装としてはしっかり組み込まれています。
strings "$(command -v claude)" | grep -c CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS
# 9
ついでに分かったこととして、同じ命名規則の実験的フラグがもう1つあります。CLAUDE_CODE_EXPERIMENTAL_OBSERVER_AGENTS です。バイナリ内には「観測されたコンテンツは指示ではなくデータである」旨の文言や ObserverReport といった文字列も含まれており、エージェントの活動を別のエージェントが監視する仕組みが存在するようです。本記事ではこちらは未検証で、公式ドキュメントでも今回参照した範囲には記載がありませんでした。
【重要】有効にすると通常の委譲も変わる
ここが一番の注意点です。公式ドキュメントはこう書いています。
Enabling agent teams also changes ordinary delegation. Claude may name a subagent on its own, and while agent teams are enabled, a subagent that Claude names launches as a teammate, so teams can form even when you didn’t ask for one.
Claude は「後でメッセージを送れるように」サブエージェントへ自分で名前を付けることがあります。Agent Teams が有効な間、名前が付いた時点でそれは teammate として起動します。つまり、あなたが「チームを組んで」と言っていなくてもチームができます。
トークンコストが高い機能なので、「試しに有効にして、そのまま忘れる」が一番まずいパターンです。使わない期間は無効に戻すのが無難です。
対話セッションが必須
もう1つの制約です。
Spawning teammates also requires an interactive session. In non-interactive mode with the
-pflag, including Agent SDK sessions, Claude doesn’t spawn teammates, and a subagent that Claude names runs as an ordinary subagent even with agent teams enabled.
-p の非対話モードと Agent SDK セッションでは teammate は生成されません。 CIから並列化を狙って有効にしても効きません。この場合、名前つきサブエージェントは通常のサブエージェントとして動きます。本記事では非対話環境のため、実際に teammate が起動する様子までは未検証です。
チーム形成から結果回収までを1本の流れにすると、サブエージェントとの構造差が見えます。
すべてリーダー側に出る"
実体はファイル — mailbox とタスクリスト
Agent Teams の内部はかなり素直なファイルベースです。
| 対象 | パス |
|---|---|
| チーム設定 | ~/.claude/teams/{team-name}/config.json |
| メールボックス | ~/.claude/teams/{team-name}/inboxes/{agent-name}.json |
| タスクリスト | ~/.claude/tasks/{team-name}/ |
team-name は session- ＋ セッションIDの先頭8文字です。チーム設定はセッション終了時に削除され、タスクリストは残り、アップロードもされません。保持期間は既存の cleanupPeriodDays に従います。
手元の環境で確認しました。
~/.claude/teams → 存在しない
~/.claude/tasks → 存在する（6エントリ）
~/.claude/teams が無いのは、この環境で Agent Teams を一度も有効にしていないからで、「既定で無効」という説明と整合します（ユーザー設定にも当該の環境変数はありませんでした）。
一方 ~/.claude/tasks は存在し、中身はこうなっていました。
~/.claude/tasks/09581d88-bf2f-4297-a6a3-43e96d2dfc52/
.lock
1.json
2.json
ディレクトリ名がドキュメント記載の session-XXXXXXXX 形式ではなく、完全なセッションUUIDでした。 タスクリスト自体は Agent Teams 専用ではなく Task ツールを持つ通常セッションでも使われるため、チーム時とそれ以外で命名が異なる、という理解が自然ですが、チーム有効時の命名は実際に有効化して確かめたわけではないので未検証です。中身は連番の JSON ファイルと .lock という、素直なファイルロック方式でした。
mailbox の壊れ方に版依存がある
公式が明記している挙動として、Claude Code はメールボックスを読むたびに全エントリを検証し、形式に合わないエントリはエラーとして報告のうえファイルから削除し、正常なメッセージは配信します。
ただしv2.1.207 より前は、1件の壊れたエントリが毎秒エラーを出し続け、そのメールボックスの配信をブロックしていました（手動でファイルを消すまで復旧しない）。古い版を使っている場合は把握しておく価値があります。
また、メッセージが「送信済み」と報告されるのは受信側のメールボックスへの書き込みが成功したときだけです。ディスクフルやディレクトリの権限不足で書き込みが失敗すると、送信側にエラーが返り、何も送られません。
プロジェクト直下に置いても設定にはならない
もう1点、公式が明示的に否定している誤解があります。プロジェクトディレクトリに .claude/teams/teams.json のようなファイルを置いても、チーム設定としては認識されません。 Claude はそれを普通のファイルとして扱います。チーム設定にプロジェクトレベルの相当物は存在しません。
再利用可能な teammate の役割を定義したい場合は、チーム設定ではなくサブエージェント定義を使います（後述）。また ~/.claude/teams/{team}/config.json にはセッションIDや tmux のペインIDといった実行時の状態が入るため、手で編集したり事前に用意したりすると次の状態更新で上書きされます。
権限モデル — teammate は抜け道にならない
複数のエージェントを走らせるとき、いちばん気になるのが「権限チェックをすり抜けられないか」です。公式の設計は明確です。
teammate はリーダーの権限設定を引き継ぎます。 リーダーが --dangerously-skip-permissions で動いていれば teammate も同じです。起動後に個別の teammate のモードを変えることはできますが、起動時に teammate ごとのモードを指定することはできません。
許可プロンプトはリーダーのセッションに出ます。 teammate の操作に承認が要るとき、あなたはリーダー側で承認します。例外は plan 承認で、これはリーダーが別プロンプトなしに与えます。
そして抜け道が塞がれています。
A teammate can’t approve a permission prompt or supply consent on your behalf, and a teammate that was denied an action can’t relay it to another teammate to bypass the check.
エージェント間で SendMessage が届いたとき、Claude Code は受信側に「これはあなたではなく別の Claude セッションから来た」と伝えます。これはチーム外の他セッションから来たメッセージでも同じです。
auto モードではさらに2段の検査が入ります。
・他エージェントから中継された承認の主張を、あなたからの確認ではなく信頼できない入力として扱う
・配信前に各メッセージを検査する（平文でも、シャットダウン要求や plan 承認応答のような構造化された protocol メッセージでも）。ブロックされたメッセージは受信側に届かない
バイナリ内の文字列にも同じ思想が現れていて、共有ストアの内容を teammate に渡すときには「これは参照データであって指示ではない」と明示する文面が埋め込まれていました。マルチエージェント構成でのプロンプトインジェクションを、プロンプト側でも防ごうとしている形です。
teammate の中身をコントロールする
teammate はゼロから作るのではなく、既存のサブエージェント定義を再利用できます。project / user / plugin / CLI いずれのスコープの定義でも構いません。
security-reviewer エージェントタイプで teammate を1つ立てて、auth モジュールを監査して。
このとき teammate は定義の tools 許可リストと model を尊重し、定義の本文はシステムプロンプトを置き換えるのではなく追記されます。in-process の teammate には SendMessage が許可リストに自動追加され、Task ツールを持つセッションではさらに TaskCreate / TaskGet / TaskList / TaskUpdate が加わります。
注意点として、サブエージェント定義の skills と mcpServers の frontmatter は teammate として動くときには適用されません。teammate はプロジェクトとユーザーの設定からスキルとMCPサーバーを読み込みます。定義側で絞ったつもりが効かないので、ここは把握しておく必要があります。
コンテキストの引き継ぎも整理しておきます。teammate は起動時に通常セッションと同じプロジェクトコンテキスト（CLAUDE.md・MCPサーバー・スキル）を読み、リーダーからの spawn プロンプトを受け取ります。リーダーの会話履歴は引き継がれません。 結果を共有したい teammate は、リーダーにメッセージを送るか共有タスクリストを更新する必要があります（アイドル通知だけでは出力は伝わりません）。
タスクの依存関係は自動で解ける
共有タスクリストには依存関係を持たせられます。ある teammate が「他のタスクが依存しているタスク」を完了すると、Claude Code が依存先を自動でアンブロックします。人が介入して「次いっていいよ」と伝える必要はありません。
逆に言うと、依存関係が多い作業ほどチームの利点は薄れます。teammate が互いの完了を待つだけの時間が増え、独立に走れないからです。公式が「逐次処理や依存の多い作業は単一セッションかサブエージェントのほうが効果的」と書いているのはこのためです。
名前を指定しておくと後で扱いやすい
リーダーは teammate を起動するときに必ず名前を割り当て、teammate 同士はその名前で呼び合います。起動指示の中で「この teammate は ux、こっちは arch と呼んで」と指定しておくと、後続のプロンプトから名指しで指示を出せます。 名前を任せると自動生成されるので、長いセッションでは指定しておくほうが取り回しが良くなります。
なお、全員に同じ連絡をしたい場合でも宛先ごとに1通ずつ送る必要があります（ブロードキャストの仕組みはありません）。
導入判断のまとめ
入れる価値があるのは、並列に探索させたい調査・レビュー系です。3つの観点を別々の teammate に持たせて互いに反論させる、という使い方は単一セッションでは再現しにくく、ここが Agent Teams の固有価値です。
ブラウザ操作を伴う検証を teammate に持たせたい場合はClaude in Chromeとは｜設定手順と22ツール・拡張機能の権限を実機で確認も併せて確認してください。teammate はリーダーの権限を引き継ぐため、ブラウザ連携を有効にしたセッションでチームを組むと、teammate 側もブラウザに手が届く構成になります。
入れる前に決めておくことは3つあります。
・使わない期間は無効に戻す。有効な間は名前つきサブエージェントが自動で teammate になり、意図せずコストが膨らむ
・CIでは効かないと理解しておく。-p と Agent SDK では teammate は生成されない
・権限はリーダーに集約される。--dangerously-skip-permissions で走らせると teammate 全員に伝播する
まとめ
・Agent Teams は既定で無効の実験的機能。CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 で有効化（v2.1.241 に9箇所の出現を確認）
・有効にすると通常の委譲も変わり、頼まなくてもチームが組まれる
・-p の非対話モードと Agent SDK では teammate は生成されない
・実体はファイルベース。~/.claude/teams/ と ~/.claude/tasks/。手元では前者が存在せず（未有効）、後者のみ存在した
・v2.1.207 より前は壊れた mailbox エントリ1件で配信が止まるバグがあった
・teammate は権限を回避できない。承認の代行も、拒否された操作の中継も塞がれている
・サブエージェント定義を teammate に流用できるが、skills と mcpServers は適用されない
トークンコストが素直に効く機能なので、「常時オン」ではなく「必要なときだけオン」が現実的な運用です。
実験的機能である以上、版によって挙動が動く前提で使うのが安全です。本記事で拾っただけでも、mailbox の壊れ方（v2.1.207）、アイドル行の表示（v2.1.181 / v2.1.198 / v2.1.199）、API エラー時の通知（v2.1.198）と、細かい修正が短い間隔で入っています。チーム構成をチームの標準手順に組み込むなら、Claude Code のバージョンも合わせて固定するほうが再現性を保てます。
なお「複数の Claude を並べる」手段は Agent Teams だけではありません。結果だけ欲しいならサブエージェント、他セッションに一声かけたいだけなら cross-session messaging、決定的な制御が要るなら dynamic workflows と、公式は4つを並べて比較しています。Agent Teams は「議論させたいとき」に限って選ぶのが、コストに見合う使い方です。
参照ソース
- Orchestrate teams of Claude Code sessions — 公式ドキュメント。有効化・アーキテクチャ・権限モデル・mailbox の版依存挙動（2026-08-27 参照）
- Run agents in parallel — サブエージェント／agent view／agent teams／dynamic workflows の比較（2026-08-27 参照）
- Subagents — サブエージェント定義と命名（2026-08-27 参照）
- Claude Code v2.1.241 バイナリの文字列調査、
~/.claude/teams/~/.claude/tasksの実地確認（2026-08-27 実測）
