Claude Code Agent Teamsとは — サブエージェントとの違い

Claude Code Agent Teamsとは何か

Claude Code Agent Teamsは、複数のClaude Codeセッションを1つのチームとして協調させる実験的機能です。1つのセッションが「リード」となり、作業の割り当てと結果の統合を担当します。残りは「teammate(チームメイト)」として、それぞれ独立したコンテキストウィンドウで並行して作業し、リードを介さずteammate同士でも直接メッセージをやり取りします。

既定では無効です。settings.jsonか環境変数でCLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1を設定しないかぎり、セッション開始時にチームは作られず、teammateも生成されません。有効化したうえで「3人のteammateを立てて、UX・技術アーキテクチャ・反対意見の3方向からこのCLIツールの設計を検討して」のように自然文で頼むと、Claude自身が人数と役割を決めて起動します。

Claude CodeにはAgent Teamsより先に、単一セッション内で完結するSub-agents(サブエージェント)という並列化の仕組みがあります。どちらも「作業を分担して並列に進める」点は同じですが、コンテキストの持ち方と会話の続き方が違います。違いを押さえずに「並列化したいからAgent Teams」と選ぶと、単発の調査でもチーム全体のトークンコストを払うことになります。

サブエージェントで足りるか、チームが要るか

分かれ目は、共有タスクリストがあるかどうかと、あなたが直接話しかけられる独立セッションかどうかです。

サブエージェントは、作業が終わると要約がメイン会話に戻る一往復の分業が基本です。ただし名前を付けて起動したサブエージェントは、後から名前で話しかけて再開できます。そのため「サブエージェントは返って終わり、teammateは続く」は程度の差です。

決定的な差は、共有タスクリストがあることです。teammateは独立したセッションなので、あなたが直接話しかけられます。名前付きサブエージェント同士もSendMessageでメッセージを送れます。v2.1.206以降は、セッション内の名前付きエージェント一覧がサブエージェントに渡されます。teammate同士の対話は既定の設計です。

teammateは1つの独立したClaude Codeセッションです。Taskツールを使えるセッションでは、チーム全体のタスクリストを介した自己組織的な調整も加わります(pending / in progress / completedの3状態とclaimの仕組みはAgent Teamsのタスク割当とclaimの仕組みで扱っています)。

判断の切り分け

teammateが独立して動ける作業ならAgent Teams、そうでなければサブエージェントか単一セッションのほうが効果的です。チームが効くのは、並列に探索すること自体に価値がある作業です。

• 調査・レビュー: 複数のteammateが問題の異なる側面を同時に調べ、互いの発見を共有・検証し合う
• 新規モジュールや機能の追加: teammateごとに別々のコードを担当し、干渉せずに進める
• 競合仮説での原因調査: 異なる仮説を同時に検証し、収束を早める
• フロントエンド・バックエンド・テストにまたがる横断作業: 層ごとに別のteammateが担当する

典型例は、レビュー観点を分担する並列コードレビューと、原因仮説を競わせるバグ調査です。起動プロンプトと進め方はAgent Teams並列コードレビューの実践にあります。

逆に、順序依存の作業、同じファイルを編集し続ける作業、依存関係が多いタスクでは、teammate間の調整がそのまま無駄になります。サブエージェントが向くのは、テストスイートの結果だけを要約させる、ドキュメントから該当箇所だけ返させるといった、呼び出し元の会話を汚したくない用途です。

チームを組む前に、もう1つ軽い選択肢があります。自分で走らせている別々のセッション同士なら、チームを作らずにセッション間メッセージ(cross-session messaging)で発見を渡し合えます。

有効化してから最初の1チームまで

設定ファイルに書く最小の形は次のとおりです。

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

表示モードとモデルの選ばれ方

表示は既定でin-process、つまり全teammateが手元のターミナルの中で動きます。分割ペインで全員の出力を同時に見たいときは、teammateModeを"auto"にします。tmux内で動いているか、iTerm2にit2 CLIが入っていれば分割ペインになり、そうでなければin-processに戻ります。settings-referenceでは、iTerm2内ならit2かtmuxのどちらかがあれば分割ペインになると書かれています。分割ペインはVS Codeの統合ターミナル、Windows Terminal、Ghosttyでは使えません。

teammateModeの値はin-process(既定)・auto・tmux・iterm2の4つです。"iterm2"はv2.1.186で加わり、it2が無いとインストールコマンド付きのエラーが出ます。autoでit2が見つからないときも、v2.1.186以降は警告が出ます。

1セッションだけ変えるフラグ--teammate-modeもありますが、実験的な扱いで、v2.1.287のclaude --helpには載っていません。同じ--helpの出力に出てくるclaude agentsは「Manage background agents」と説明されており、Agent Teamsとは別の機能です。

teammateのモデルは、次の順で最初に当てはまったものが使われます。

1. 依頼文でそのteammateに指定したモデル
2. サブエージェント定義から立てた場合は、定義のmodel(inheritならリードのモデル)
3. CLAUDE_CODE_SUBAGENT_MODEL(inherit以外のとき)
4. リードの現在のモデル

v2.1.251より前はCLAUDE_CODE_SUBAGENT_MODELが先頭でした。CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1(v2.1.257以降)を設定すると1と2が無効になり、全teammateの選択がこの変数かリードのモデルに寄ります。かつてのteammateDefaultModelはv2.1.234で削除されました。残っていても無視されるので、モデルは依頼文で指定します。組織のavailableModelsで拒否されたモデルは、別のモデルに置き換えられます。

サブエージェント定義を役割に使う

セキュリティ審査役のような役割は、.claude/agents/のサブエージェント定義を一度書いておけば、サブエージェントとしても、teammateとしても呼べます。teammateに引き継がれるのはtools・model・本文で、skillsは引き継がれません。teammateはプロジェクトとユーザー設定のスキルを自分で読み込みます。mcpServersは分割ペインのteammateだけに効き、in-processのteammateは無視して、プロジェクトとユーザー設定のMCPサーバーを読み込みます。

頼んでいないのにチームが立ち上がるとき

有効にすると、通常の委譲の挙動も変わります。Claude CodeはAgent tool呼び出しにnameを付けてサブエージェントに名前を与え、後から名前で話しかけたり再開したりします。この命名判断をClaudeはユーザーに確認せず自分で行い、Agent Teamsが有効なあいだは、名前付きで起動されたサブエージェントはteammateとして立ち上がります(forkとして呼ばれた場合や、呼び出し自体にisolationが付く場合を除く)。サブエージェントを頼んだつもりで、実はチームが組まれていた、という状況が起こり得ます。

止めるにはCLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMSを0に戻します。設定ファイルのenv値はセッションを再起動しなくても反映され、Claudeが次にサブエージェントを起動するときから通常のサブエージェントになります。ただし、ユーザーのsettings.jsonで0にしても、プロジェクト設定・ローカル設定・--settingsで1が書かれていればそちらが勝ち、組織の管理設定で有効にされている場合は管理者に変更を頼むことになります。

もう1つ見落としやすいのが非対話モードです。-pフラグのヘッドレスモード(Agent SDKセッションを含む)では、有効でもteammateは生成されず、名前付きサブエージェントは通常のサブエージェントとして動きます。-pではteammateを使う自動化は組めません。同じ作業はサブエージェントで書きます。teammateが出てこない、早期に終了する、tmuxセッションが残るといった症状の切り分けはAgent Teamsが動かないときの対処法にあります。

人数とコストの見積もり

トークン消費はteammateの数にほぼ比例して増えます。公式は、人数に厳密な上限はないと断ったうえで、多くのワークフローは3〜5人から始めるよう勧めています。15個の独立したタスクがあっても、最初は3人です。タスクの粒度は「関数1つ」「テストファイル1つ」「レビュー1件」のように成果物がはっきりした単位が適切で、小さすぎれば調整のほうが重く、大きすぎれば確認なしに長く走って無駄になりやすくなります。1人あたり5〜6タスクが目安として挙げられています。

キャッシュにも違いがあります。in-process teammateのリクエストはメイン会話とは別のキャッシュTTLの枠に入り、既定では5分で切れます(サブスクリプション利用でも同じ)。1時間に延ばすにはsubagentPromptCacheTtlを1hにしますが、1時間のキャッシュ書き込みはAPIでは高い単価で課金されます。

権限の継承とプランモードの扱い

teammateはリードの権限モードで起動します。リードが--dangerously-skip-permissionsなら、teammateも同じです。例外はdontAskモードで、これは引き継がれません。起動後に個別のteammateだけモードを変えることはできますが、起動時にteammateごとに別のモードを指定することはできません。teammateの権限確認はリードのセッションに出るので、承認はリードの画面で行います。前もって許可設定に通常操作を入れておくと、確認の往復を減らせます。

例外がプランの承認です。リードがプランモードのときに立てたteammateは、プランが固まるとリードに承認リクエストを送ります。Claude Codeはこれをリードの内容確認なしに、届いた時点で承認します。ファイル編集やコマンド実行は通常どおり権限プロンプトを通るので、計画の承認だけが自動で、実行の承認は手動です。継承範囲の詳細とbypassPermissionsの伝播条件はAgent Teams権限モデルで扱っています。

teammate間のメッセージは無条件に信頼されない

teammate同士が直接メッセージを送り合う設計は、サブエージェントには無いリスクも持ち込みます。SendMessageでメッセージが届くとき、受信側には「ユーザーではなく別のClaudeセッションから来た」ことが明示されます。teammateは、ユーザーに代わって権限プロンプトを承認したり、同意を与えたりできません。権限を拒否されたteammateが、別のteammateに代行させて迂回することもできません。チームの外にいる別のClaude Codeセッションから届いたメッセージにも、同じ扱いが適用されます。

自動承認モード(auto mode)では、分類器がメッセージに2つのチェックをかけます。他のエージェントが中継した「承認済み」という主張は、ユーザー本人の確認ではなく未検証の入力として扱われます。さらに、シャットダウン要求やプラン承認応答のような構造化メッセージも含め、配送前に各メッセージが審査され、ブロックされたメッセージは受信者に届きません。

チームが手元に残すもの

チームの実体は、ホーム配下のファイルです。名前はsession-にセッションIDの先頭8文字を付けたものになります。

プロジェクト側に.claude/teams/teams.jsonのようなファイルを置いても、設定としては認識されません。再利用したい役割は、前述のサブエージェント定義に書きます。

チームの制約

制約のほとんどは「リードが固定で、チームは1つ」という設計から来ます。

• リードのセッションは終了までリードのままで、teammateの昇格や権限の移譲はできません
• 1セッションにチームは1つで、名前付きの複数チームや、セッションをまたぐ共有はできません。v2.1.178でTeamCreateとTeamDeleteは削除され、teammateはAgent toolのnameで直接立てます(削除された機能の一覧)
• teammateが自分のteammateを立てる入れ子のチームはできません
• in-process teammateは、/resumeと/rewindでは復元されません。再開後にリードが存在しないteammateへ送ろうとしたら、新しく立て直させます
• タスクの完了マークが付かず、依存タスクが止まることがあります。作業が実際に済んでいるかを確かめて、状態を直すか、teammateに促させます。TeammateIdleとTaskCompletedのhookは、終了コード2でフィードバックを返して作業を続けさせたり完了を止めたりできます(Agent Teamsのhooks)
• 終了は遅いことがあります。teammateは現在のリクエストかツール呼び出しを終えてから止まります

in-process teammateが立てるサブエージェントは常にフォアグラウンドで動きます。background: trueを定義に持つサブエージェントを呼ぶとエラーになります。

この「1人のリードが全体を統括する」形は、サブエージェントの並列実行パターンで呼び出し元が1つの視点で全体を統括する設計と通じます。Agent Teamsが変えているのは、誰が統括するかではなく、統括される側がどこまで自律的に動けるかです。

まとめ

有効化する前に、CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMSをユーザー設定・プロジェクト設定・管理設定のどこに書くかを決めておくと、後から止めるときに迷いません。設定の優先関係は、チームを止められるかどうかを左右します。