Claude Codeのエージェントチームとは──複数セッションが直接会話する実験的機能

Claude CodeのAgent Teams（エージェントチーム）は、1つのセッションが「リーダー」となり、複数の独立したClaude Codeインスタンス（チームメンバー）を生成して並列に作業させ、チームメンバー同士がリーダーを経由せず直接メッセージをやり取りできるようにする機能です。公式ドキュメントは冒頭で次のように警告しています。

エージェントチームは実験的機能であり、デフォルトでは無効になっています。settings.json または環境に CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS を追加して有効にしてください。その変数がない場合、セッション開始時にチームが設定されず、チームディレクトリが書き込まれず、Claude はチームメンバーをスポーンまたは提案しません。

この記事は2026年8月27日に取得した同ページ（v2.1.178時点の記述として明記）と、コスト・設定・フックの各公式ページだけを土台にしています。手元で claude --version を打つと2.1.247が返り、ドキュメントが挙げているバージョン注記（v2.1.178〜v2.1.207）はすべて追い越しているため、これから書く仕様は「アップデート待ち」ではなく現行の動作として読んで構いません。

• Agent Teamsは実験的機能でデフォルト無効。CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 環境変数（settings.jsonのenvかシェル）を1にして初めてチームメンバーがスポーンされる
• subagentとの違いは通信構造。subagentは呼び出し元にのみ結果を返すが、Agent Teamsのチームメンバーは共有タスクリストとメールボックスで互いに直接メッセージを送り合う
• 公式コストページは「チームメイトがプランモードで実行される場合、標準セッションよりも約7倍多くのトークンを使用する」と明記。セッション再開不可・ネストチーム禁止・ファイル競合などの制限も列挙されている

何をする機能か——subagentとの構造的な違い

公式ドキュメントはsubagentとの違いをこう説明しています。

subagents（単一セッション内で実行され、メインエージェントにのみ報告できる）とは異なり、リーダーを経由せずに個別のチームメンバーと直接対話することもできます。

比較表の該当行を抜粋すると次の通りです。

subagentの仕組み自体（Explore/Plan/general-purposeの3種類、CLAUDE.mdスキップの挙動など）は別記事サブエージェントとはで扱っているので、本記事はAgent Teams固有の部分に絞ります。

有効化はワンステップだが、忘れると何も起きない

有効化はsettings.jsonへの追記だけです。

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

前述の通り、この変数がないと「チームディレクトリが書き込まれず」「Claude はチームメンバーをスポーンまたは提案しません」。つまり、チームを使わせるつもりのプロンプトを書いても、リーダーは黙って単独で作業を進めます。エラーは出ません。

有効化後は、自然言語でチーム編成を依頼するだけで生成が始まります。ドキュメントが挙げている例文はこうです。

I'm designing a CLI tool that helps developers track TODO comments across their codebase. Spawn three teammates to explore this from different angles: one on UX, one on technical architecture, one playing devil's advocate.

Claudeがタスクの性質から「チーム化すべきか」を自律判断して提案してくることもありますが、ドキュメントは「Claude はあなたの承認なしにチームメンバーを生成しません」と明記しており、生成前には必ず確認が挟まります。

表示モードはin-processが既定。分割ペインには外部ツールが要る

表示モードは2種類で、既定値は in-process です。

エージェントチームは 2 つの表示モードをサポートしています。In-process：すべてのチームメンバーがメインターミナル内で実行されます。（中略）分割ペイン：各チームメンバーが独自のペインを取得します。（中略）tmux または iTerm2 が必要です。

teammateMode 設定の既定値はv2.1.179で auto から in-process に変わった、とドキュメントは注記しています。分割ペインを明示的に使いたい場合は tmux か iterm2（iTerm2ネイティブ、it2 CLI必須）を指定しますが、VS Codeの統合ターミナル・Windows Terminal・Ghosttyでは分割ペインモードがサポートされていないと制限事項に明記されています。ターミナル環境を選ばずに動かしたいなら、既定のin-processのままにしておくのが無難です。

タスクは共有リストで自己調整、ファイルはロックされない

タスクには保留中・進行中・完了の3状態があり、依存関係を張れます。

タスク要求はファイルロックを使用して、複数のチームメンバーが同時に同じタスクを要求しようとするときの競合状態を防ぎます。

ここで注意が要るのは、ロックされるのは「タスクの要求」であって「ファイルの中身」ではないという点です。ベストプラクティス節にはっきりこう書かれています。

2 人のチームメンバーが同じファイルを編集すると、上書きが発生します。作業を分割して、各チームメンバーが異なるファイルセットを所有するようにしてください。

つまり、同じファイルを触る可能性があるタスクを2人に割り振ると、タスク管理上は競合なく進んでいるように見えて、実際には片方の変更が消える。防ぐ仕組みは用意されておらず、プロンプトの設計（担当ファイルを明示的に分ける）に委ねられています。

権限はリーダーの設定を継承。生成時にしか決められない

チームメンバーはリーダーの権限設定で開始します。リーダーが --dangerously-skip-permissions で実行する場合、すべてのチームメンバーも同様に実行します。生成後、個別のチームメンバーモードを変更できますが、生成時にチームメンバーごとのモードを設定することはできません。

権限プロンプトは各チームメンバーではなくリーダーのセッションに集約されます。トラブルシューティング節は「チームメンバーの権限リクエストはリーダーにバブルアップし、摩擦を生じさせる可能性があります」として、生成前に一般操作を事前承認しておくよう勧めています。

もう一点、auto modeとの組み合わせで実務上重要な記述があります。

auto mode では、別のエージェントからリレーされた承認クレームは、あなたからの確認ではなく、信頼できない入力として分類器によって扱われます。

チームメンバーAが「これは本人が承認済みです」とチームメンバーBに伝えても、Bの権限チェックはその発言をユーザーの同意として扱わない、ということです。権限のバイパスをチームメンバー間の会話で成立させることはできない設計です。

プラン承認の仕組みはリーダーへの通知だけで完結する

高リスクな変更を任せる場合、チームメンバーにプラン承認を要求できます。

チームメンバーはリーダーがアプローチを承認するまで、読み取り専用プランモードで動作します。（中略）承認されると、チームメンバーはプランモードを終了し、実装を開始します。（中略）リーダーセッションはあなたへの別のプロンプトなしにチームメンバープラン承認を付与します。

つまりプラン承認はリーダー（Claude自身）の自律判断であり、ユーザーへの追加確認は入りません。承認基準をコントロールしたいなら、生成プロンプトの時点で「テストカバレッジを含むプランのみ承認する」のように条件を明示する必要があります。

実体はどこに保存されるか

チーム設定とタスクリストはローカルファイルとして永続化されます。

• チーム設定: ~/.claude/teams/{team-name}/config.json
• タスクリスト: ~/.claude/tasks/{team-name}/
• 各エージェントのメールボックス: ~/.claude/teams/{team-name}/inboxes/{agent-name}.json

チーム名は「session- + セッションIDの先頭8文字」というセッション派生名で、手動で名付けることはできません。ドキュメントは「チーム設定はセッション ID と tmux ペイン ID などのランタイム状態を保持しているため、手動で編集したり、事前に作成したりしないでください」と釘を刺しています。セッション終了時にチーム設定ディレクトリは自動削除されますが、タスクリストはローカルに残り、通常のセッショントランスクリプトと同じ cleanupPeriodDays 設定で保持期間が管理されます。

プロジェクト側で事前定義する手段は存在しません。

プロジェクトレベルのチーム設定に相当するものはありません。プロジェクトディレクトリ内の .claude/teams/teams.json のようなファイルは設定として認識されません。Claude はそれを通常のファイルとして扱います。

再利用可能なロール（セキュリティレビュアーなど）を定義したい場合は、チーム専用の仕組みではなく既存のsubagent定義を名前で参照する形になります。

実務で引っかかる点

トークンコストは「プランモード実行時で約7倍」という具体的な数字が公式に出ている。 コストページはこう書いています。

エージェントチームは、チームメイトがプランモードで実行される場合、標準セッションよりも約 7 倍多くのトークンを使用します。

これはプランモードで動かした場合の数字で、通常実行時の倍率は別途「チームサイズにおおよそ比例する」としか書かれていません。5人チームを気軽に組むと、単独セッションの数倍のトークンを消費する前提で予算を見ておく必要があります。

セッション再開でチームメンバーが消える。 in-processチームメンバーは /resume や /rewind で復元されません。再開後にリーダーが「もう存在しないチームメンバー」宛てにメッセージを送ろうとする挙動が制限事項として明記されており、対処は「新しいチームメンバーを生成するよう指示する」しかありません。長時間タスクを再開前提で組む用途には向きません。

ネスト不可・チーム数は1セッション1つ固定。 チームメンバーが自分のチームを持つことはできず、リーダーの委譲は1階層で止まります。また「セッションは正確に 1 つのチームを持ち、そのセッションにスコープされています」ので、複数の独立チームを同時運用する構成は組めません。

in-processチームメンバーからのバックグラウンドサブエージェントは使えない。 run_in_background や background: true を指定するサブエージェント定義を、チームメンバー内から呼ぶとエラーになります。理由は「チームメンバーのバックグラウンド作業がリーダーのプロセスより長く存在できないため」。並列度をさらに上げようとして入れ子で非同期化しようとすると、ここで止まります。

hooksで品質ゲートを敷けるが、対象は3種類だけ。 TeammateIdle・TaskCreated・TaskCompleted の3イベントで、終了コード2を返すとその挙動をブロックしてフィードバックを差し戻せます。フック公式ページには入力フィールドとして task_id・task_subject・teammate_name・team_name などが列挙されており、{"continue": false, "stopReason": "..."} を返すとチームメンバー全体を停止できます。ただし対象イベントはこの3つに限られ、例えば「メッセージ送信そのもの」をフックで検閲する仕組みはドキュメント上見当たりません。

公式に書かれていないこと・確認できなかったこと

• サブスクリプションプラン（Pro/Max/Team/Enterprise）による利用制限。 今回確認した agent-teams・hooks・costs・settings の4ページのいずれにも、プラン種別でAgent Teamsの可否が変わるという記載を見つけられなかった。環境変数で有効化するローカル機能という説明のみで、プラン依存の記述は無い。
• チームメンバー数の技術的な上限。 ベストプラクティス節は「厳しい制限はありません」「3〜5人で開始」と推奨値のみを示しており、システムが強制するハードリミットの数値は書かれていない。
• プランモード以外での正確なトークン倍率。 「約7倍」はプランモード実行時に限定した数字で、通常の実装作業でのチーム全体の倍率を示す具体的な係数は見つけられなかった（「チームサイズにおおよそ比例する」という定性的な記述のみ）。
• WindowsでのTmux経由の分割ペイン対応。 制限事項はWindows Terminal自体を名指しで「サポートされていない」としているが、WSL経由でtmuxを使った場合の扱いについては明記が無かった。
• APIキー課金とClaude.aiサブスクリプション課金でのAgent Teams利用時の請求区分の違い。 チームメンバーが個別のClaudeインスタンスとして課金対象になることは分かるが、請求明細上どう按分されるかの記述は確認できなかった。

---

出典

• Claude Code セッションのチームを調整する（Claude Code 公式ドキュメント）: https://code.claude.com/docs/ja/agent-teams
• コストを削減する（Claude Code 公式ドキュメント）: https://code.claude.com/docs/ja/costs
• 設定（Claude Code 公式ドキュメント）: https://code.claude.com/docs/ja/settings
• フック（Claude Code 公式ドキュメント）: https://code.claude.com/docs/ja/hooks

但し書き

本記事の仕様・数値・バージョン注記は、2026年8月27日時点で上記4ページを取得して確認した内容に基づきます。Agent Teamsは公式ドキュメントが繰り返し「実験的機能」と呼んでいる通り仕様変更の可能性があり、記載の挙動は後日変わりえます。実行前に手元のバージョン（claude --version）と公式ドキュメントの現行版で確認してください。トークンコストや作業速度の改善効果を保証するものではありません。