Claude Code Agent Teamsとは？サブエージェントとの違いと並列独立タスクの組み方

Claude Code Agent Teamsは、1つのリードセッションが複数のティームメイト（独立したClaude Codeインスタンス）を統括し、共有タスクリストと相互メッセージングで協調作業させる機能です。公式ドキュメントは冒頭で「実験機能、既定で無効」と明示しており、CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1を設定して有効化します。サブエージェントとの最大の違いは「ティームメイト同士が直接通信できる」点で、議論や役割分担が必要な調査・レビュー・新規モジュール開発で価値が出ます。

結論を先に書いておくと、Agent Teamsを使うべきなのは「並列で議論や相互牽制が必要なときだけ」です。逐次タスク、同一ファイル編集、依存だらけの実装は単一セッションかサブエージェントのほうが効率的で、コストも低く済みます。

サブエージェントとAgent Teamsはどう違うのか

サブエージェントとAgent Teamsはどちらも並列化の手段ですが、設計思想が異なります。サブエージェントは「メインエージェントが起動して結果だけ受け取る」モデルで、ティームメイト同士の対話はありません。Agent Teamsは「リードと複数のティームメイトが共有タスクリストを介して自己調整する」モデルで、メイトどうしが直接メッセージをやり取りできます。

公式は「ティームメイトが互いに発見を共有・反論・調整する必要があるならAgent Teams、そうでないならサブエージェント」とシンプルに線を引いています。後者は実装上のコストも明確で、サブエージェントの結果は要約して親に戻るため親コンテキストを汚しません。Agent Teamsは各自が独立コンテキストを保持するためトークン消費は線形に増えます。

いつ使うべきか：4つの典型ユースケース

公式が「価値が出る」とする4ケースを覚えておくと判断しやすくなります。第1はリサーチとレビューで、PRをセキュリティ・性能・テストカバレッジで分担してから結果を持ち寄る使い方です。単一レビュアーが偏りやすい問題を、独立した観点で並列に検証することで解消します。

第2は新規モジュールや機能の並列開発です。ティームメイトごとに別ファイル群を所有させると、編集の衝突を避けながら同時に進められます。第3は競合する仮説の同時検証によるデバッグで、5人のメイトに別々の仮説を持たせて科学的議論のように互いを反証させると、単独調査で陥りがちなアンカリングを破れます。第4はフロント・バック・テストにまたがる横断変更で、レイヤー別に担当を割り振る運用です。

逆に避けるべきは、1人で30分で終わる小さなタスク、同じファイルを複数人で触る作業、依存関係でほぼ直列にしかならない作業です。これらに使うと調整のオーバーヘッドだけが増えます。

有効化と最初のチーム作成

Agent TeamsはClaude Code v2.1.32以降が必要です。バージョンを確認しておきましょう。

有効化は環境変数かsettings.jsonで行います。~/.claude/settings.jsonに次のキーを足すと、ユーザースコープで常時有効になります。

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

その後Claude Codeを起動し、自然言語でチーム結成を依頼します。公式が示す代表例は次のようなものです。

TODOコメントを横断追跡するCLIツールを設計したい。
3人構成のagent teamを作って、UX担当・技術アーキ担当・デビルズアドボケイトの
3視点で並列に検討してほしい。

リードは共有タスクリストとともにチームを生成し、各ティームメイトを別コンテキストで走らせます。リードのターミナルにはメイト一覧と進行状況が表示され、Shift+Downでメイト間を巡回して直接メッセージできます。

表示モードとモデル選択

表示モードは2種類あります。in-processは全メイトをメインターミナル内に同居させる方式で、追加ツールなしで動きます。split panesはメイトごとに別ペインを開く方式で、tmuxまたはiTerm2（とit2 CLI）が必要です。VS Code統合ターミナル・Windows Terminal・Ghosttyではsplit panesに非対応である点が既知の制約として明記されています。

既定の"auto"はtmuxセッション内ならsplit panes、それ以外はin-processを選びます。設定で固定するには~/.claude/settings.jsonに次を追加します。

{
  "teammateMode": "in-process"
}

セッション単位で上書きしたい場合はフラグで指定できます。

モデルはティームメイトがリードの/model選択を自動継承しません。/configの「Default teammate model」で既定を設定するか、依頼文に「Use Sonnet for each teammate」と明示します。公式は「ティームメイトはSonnetが推奨」としており、コストと能力のバランス上、リードがOpusでもメイトはSonnetにしておくのが現実解です。

タスク・通信・権限の設計

Agent Teamsの中核は共有タスクリストです。タスクはpending/in progress/completedの3状態を持ち、依存関係も持てます。リードが明示的に割り当てるか、メイトが自分で次のタスクを掴むかの2運用が可能で、同一タスクの取り合いはファイルロックで防がれます。

通信は2レイヤあります。第1はメイト宛メッセージで、リードがスポーンしたときの名前で各メイトを指定します。後で再参照したい場合は、依頼文の中でメイト名を指定しておくと予測可能になります。第2は自動配送と自動通知で、メイトのメッセージは自動でリードに届き、メイトがアイドル状態に入ると自動で通知されます。リードがポーリングする必要はありません。

権限はリードの設定を継承します。リードが--dangerously-skip-permissionsで起動していると全メイトに同じモードが伝播するため、危険操作を含むタスクでは原則として通常モードのまま使います。スポーン後に個別のメイトのモードを切り替えることはできますが、スポーン時点での個別指定はできません。プランモード強制を使いたい場合は「Spawn an architect teammate to refactor X. Require plan approval before they make any changes.」のように依頼すると、メイトはRead-onlyのプランモードで動き、計画承認をリードに要求してきます。

トークンコストの考え方

公式のコスト記事は、Agent Teamsについて「ティームメイトがプランモードで動くとき、標準セッション比でおおむね7倍のトークンを消費する」と注意喚起しています。コンテキストは各メイトが個別に保持し、リードからのスポーンプロンプトも全メイトの先頭に積まれるため、人数とランタイムに比例してトークンが伸びます。

コストを抑える具体的な手段は次のとおりです。

• ティームメイトにはSonnetを選ぶ（Opusはリードか、複雑推論が必要なメイトに限定）
• チームは小さく保つ（公式推奨は3〜5人、5〜6タスク/人の粒度）
• スポーンプロンプトを短く絞る（CLAUDE.md、MCPサーバー、Skillsは自動ロードされるので、追加情報だけ書く）
• 作業終了後は必ずクリーンアップする（アイドル状態でもメイトはトークンを消費し続ける）
• 1ラウンド回したら/usageでブレークダウンを確認し、想定より高ければ次回からチームサイズを下げる

「全部のタスクで使うべきか？」と悩むくらいなら、Agent Teamsは意識的に「並列議論が価値を生む案件だけ」に限定するのが結果的に一番安く付きます。

チームのライフサイクル：起動・運転・終了

起動には2経路があります。1つは利用者が明示的に「agent teamを作って」と依頼するケース、もう1つはClaudeが「並列化したほうがよさそうです」と提案して利用者が承認するケースです。どちらも利用者の承認なしには走り出しません。

運転中は人間が要所要所で監視・舵取りするのが推奨運用です。メイトがエラーで止まったときに自然回復せず固まる、進捗が滞る、リードが自分で実装を始めてしまう、といった挙動が報告されており、定期的な状況確認と「ティームメイトの完了を待って」「このタスクを別のメイトに振り直して」といった介入が必要になります。

終了時は「Clean up the team」とリードに依頼します。リードはアクティブなメイトが残っていないかを確認した上で共有リソースを片付けます。クリーンアップは必ずリードに依頼すること。ティームメイト自身にクリーンアップを実行させるとチームコンテキストの解決が不安定になり、リソースが中途半端な状態で残るおそれがあると公式は警告しています。

tmuxセッションが残ってしまった場合は、手動で片付けます。

Hooksでの品質ゲートとサブエージェント定義の再利用

Agent Teamsには専用Hooksが3種類あります。TeammateIdleはメイトがアイドル直前に走り、終了コード2でフィードバックを返してメイトを継続させます。TaskCreatedはタスク生成直前に走り、不適切な分解をブロックできます。TaskCompletedはタスク完了直前に走り、テスト未実行などの「終わったことにする」挙動を防げます。チーム運用に品質ゲートを差し込みたい場合は、これらを併用するのが定石です。

サブエージェント定義の再利用も重要なポイントです。プロジェクトやユーザースコープに定義したsecurity-reviewerやtest-runnerなどのカスタムサブエージェント名をスポーン時に指定すると、そのtools許可リストとmodelが継承され、定義の本文がティームメイトのシステムプロンプトに追記されます（置き換えではなく追記）。チーム調整用ツール（SendMessageやタスク管理ツール）はtools制限とは別に常に利用可能になります。

ただし、サブエージェント定義のskillsとmcpServersフロントマターはティームメイトとして動くときは適用されません。メイトはプロジェクトとユーザー設定のSkills・MCPサーバーを通常セッション同様に読み込みます。この点は公式ノートで明記されており、設計時に意識しておく必要があります。

実験機能としての既知の制約

公式の制限事項を要約しておきます。設計時にこれらを知らないと事故ります。

• /resumeと/rewindがin-processメイトを復元しない：セッション再開後、リードは存在しないメイトにメッセージを送ろうとすることがある。新しいメイトをスポーンし直す
• タスクステータスが遅延することがある：完了したのにcompletedにならず、依存タスクが詰まる。手動で更新するか、リードに「該当メイトに完了を確認させて」と依頼する
• シャットダウンが遅い：現在のリクエストやツール呼び出しが終わるまでメイトは止まらない
• 同時に1チームのみ：別チームを作る前に必ずクリーンアップ
• ネステッドチーム禁止：メイトが自分のチームを持つことはできない
• リードは固定：チームを作ったセッションが寿命の終わりまでリード。昇格や移譲はできない
• 権限はスポーン時に決まる：個別モードはスポーン後に変更可能だが、スポーン時の個別指定は不可

これらは「実験機能だから残っている課題」であり、利用者側で運用ルールでカバーする前提です。本番ワークフローに組み込む前に、まずは社内の検証プロジェクトで3〜5人規模を試すのが安全です。

設計チェックリスト

最後に、Agent Teamsを実プロジェクトで回す前の8項目チェックリストを置いておきます。

• Claude Code v2.1.32以降を使っているか（claude --versionで確認）
• CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1をsettings.jsonに書いたか
• このタスクは並列議論が本当に必要か（逐次や単純並列ならサブエージェントで十分ではないか）
• チームサイズは3〜5人で、各メイトに5〜6タスクを割り当てられる粒度か
• 各メイトのファイル所有範囲は重ならないか（同一ファイル編集を避けたか）
• メイトモデルはSonnetで揃えたか（コスト最適化）
• HooksでTaskCompletedや品質ゲートを差し込んだか
• 作業後にリードに「Clean up the team」と明示する運用にしたか

Agent Teamsは強力ですが、「使うべきタイミングを選ぶ」ことそのものが運用スキルです。最初の数チームは小さく試して、自分のプロジェクトのどの作業に効くかを見極めていくのが王道です。

次に読むなら、サブエージェントの基本仕様で「コンテキスト分離」の側のモデルを押さえ、並列調査の3パターンでAgent Teams以外の並列化手段との使い分けを整理するのがおすすめです。コスト面が気になる場合はサブエージェントのトークン節約運用もあわせて確認すると、Agent Teamsを使うべきしきい値が見えてきます。

Source Claude Code Documentation

Orchestrate teams of Claude Code sessions

Coordinate multiple Claude Code instances working together as a team, with shared tasks, inter-agent messaging, and centralized management.