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自身がteammateの人数と役割を決めて起動します。

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

サブエージェントとの違いはどこにあるか

最大の違いは2つです。コンテキストの共有範囲と会話の継続性。

サブエージェントは独自のコンテキストウィンドウを持ちますが、それは「呼び出し元に結果を返して終わる」ための独立性です。作業が終わればテキストの要約が呼び出し元のメイン会話に返り、サブエージェント自身のコンテキストは基本的にそこで役目を終えます。呼び出し元がすべての作業を管理し、サブエージェント同士が直接会話することは、Claudeが名前を付けて呼び出したサブエージェント同士でメッセージを送り合うケースを除けば想定されていません。

Agent Teamsのteammateは違います。独自のコンテキストウィンドウを持つ点はサブエージェントと同じですが、そのコンテキストは完全に独立していて、リードの会話履歴を引き継ぎません。その代わりteammate同士は直接メッセージを送り合い、リードを介さず調整できます。さらにTaskツールを使えるセッションでは、チーム全体で共有されるタスクリストを介した自己組織的な調整も加わります(pending/in progress/completedの3状態とclaimの仕組みはAgent Teamsのタスク割当とclaimの仕組みで扱っています)。「会話の継続性」という観点では、teammateは1つの独立したClaude Codeセッションとして生き続け、作業が終わった後もリードから直接話しかけて追加指示を出せます。サブエージェントの結果は基本的に「返ってきて終わり」の一往復です。

トークンコストの差は明確です。サブエージェントは処理結果がメイン会話に要約されて戻るぶん、消費を抑えられます。Agent Teamsは各teammateが完全に別のClaudeインスタンスとして動き続けるため、teammateの数に比例してコストが積み上がります。

どちらを選ぶべきか

公式ドキュメントが提示する判断基準はシンプルです。teammateが独立して動ける作業ならAgent Teams、そうでなければサブエージェントか単一セッションのほうが効果的です。

Agent Teamsが効くのは、並列に探索すること自体に価値がある作業です。

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

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

逆に、作業が順序依存だったり、同じファイルを編集し続けたり、依存関係が多いタスクは単一セッションかサブエージェントのほうが向いています。teammate間の調整オーバーヘッドがそのまま無駄になるからです。

サブエージェントが向くのは「結果だけが欲しい集中タスク」です。テストスイートの実行結果だけを要約させる、ドキュメントを検索して該当箇所だけ返させる、といった「呼び出し元の会話を汚さずに済ませたい」用途では、コンテキストが呼び出し元に戻ってくる設計そのものが利点になります。

意図せずチームが立ち上がる仕組み

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

エージェントパネルにはteammateとサブエージェントが同じ場所に表示されるため、パネルを見ただけではチームが実際に組まれたかどうか判別できません。もし意図せずチームが形成されていたら、CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMSを0に戻すことでこの挙動を止められます。設定ファイルのenv値はセッション再起動なしで反映され、次にClaudeがサブエージェントに名前を付けるタイミングから通常のサブエージェントとして動くようになります。

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

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

teammateはリードの権限設定をそのまま引き継いで起動します。リードが--dangerously-skip-permissionsで動いていれば、teammateも同様です。起動後に個別のteammateだけモードを変更することはできますが、起動時点でteammateごとに異なる権限モードを指定することはできません。teammateの権限確認プロンプトはリードのセッションに表示されるため、承認作業自体はリードの画面で行うことになります。

例外はプランモードの承認です。リードがプランモードのteammateを立てた場合、teammateがプランを完成させるとリードにプラン承認リクエストが送られますが、Claude Codeはこれを人間の確認なしに即座に承認します。実際のファイル編集やコマンド実行は通常どおり権限プロンプトを経由するため、「計画の承認だけは自動、実行の承認は手動」という2段構えになっています。継承範囲の詳細とbypassPermissionsの伝播条件はAgent Teams権限モデルで扱っています。

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

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

自動承認モード(Auto mode)で動いている場合、エージェント間メッセージには2段のチェックが入ります。他のエージェントから中継された「承認済み」という主張は、ユーザー本人の確認ではなく未検証の入力として扱われます。加えて、シャットダウン要求やプラン承認応答のような構造化メッセージも含め、Claude Codeは配送前に各メッセージを審査し、ブロックされたメッセージは受信者に届きません。teammate同士が自由に会話できるからといって、権限モデルの外側で承認し合うことはできません。

リードとteammate、どちらが主導権を持つか

Agent Teamsではリードのセッションが構造上ずっとリードのままです。teammateを昇格させてリードにしたり、リード権限を別のセッションへ移したりすることはできません。1セッションにつきチームは1つに固定され、複数の名前付きチームを同時に持つこともできません。この制約は、サブエージェントの並列実行パターンのように呼び出し元が常に1つの視点で全体を統括する設計とも通じるところがあります。Agent Teamsが変えているのは「誰が統括するか」ではなく「統括される側がどこまで自律的に動けるか」です。

まとめ

Agent Teamsとサブエージェントは、どちらも「作業の並列化」という同じ目的のための機構ですが、コンテキストの独立性の意味が違います。サブエージェントは結果を返して終わる一往復の分業、Agent Teamsは独立したセッション同士が会話を続けながら協調する分業です。調査・レビュー・競合仮説の検証のように、teammate同士が発見を共有し議論すること自体に価値がある作業ではAgent Teamsが効きます。単発の集中タスクや同一ファイルへの逐次編集では、トークンコストの低いサブエージェントか単一セッションで十分です。Agent Teamsを有効にすると通常の委譲挙動も変わるため、「頼んだ覚えのないチームが立ち上がっていた」ときは、まずこの設定を疑うところから始めるとよいでしょう。