結論：Claude Code の Agent Teams は、複数の Claude Code インスタンス（teammate）を同時に立ち上げ、共有タスクリストとエージェント間メッセージングで役割分担・協調させる実験的機能です。2026年6月時点ではデフォルト無効で、有効化には CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 の設定が必要です。
- 要点1：サブエージェントとは別物。サブエージェントは1セッション内で結果だけを親に返すが、teammate は独立セッションとして互いに直接やり取りし、共有タスクリストで自律的に作業を分担する。
- 要点2：有効化は
settings.jsonのenvまたは環境変数でCLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1を設定するだけ。Claude Code v2.1.32 以降が必要。 - 要点3：各 teammate が独自のコンテキストウィンドウを持つため、teammate がプランモードで動くケースで標準セッションの約7倍のトークンを消費する（公式コストガイド）。Sonnet 利用・小さく保つ・終わったら片付けるのが定石。
対象読者：Claude Code でレビュー・調査・複数モジュール並行開発を効率化したい開発者・PM・テックリード。
今日やること：settings.json に CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 を追記し、PR レビューを「セキュリティ担当・性能担当・テスト担当」の3 teammate で並列レビューさせてみる。
「Claude Code を1セッションで動かしていると、調査・実装・レビューが直列になって待ち時間が長い」——複数モジュールを抱えるリポジトリで Claude Code を使っていると、誰もが一度はぶつかる悩みだと思います。Agent Teams は、まさにここに効く実験的機能です。本記事では、Agent Teams が何者で（サブエージェントとどう違うのか）、どう有効化し、teammate にどう役割を割り振り、コストをどう抑えるかを、2026年6月時点の公式ドキュメントに沿って整理します。実験的機能なので、挙動が変わる前提で読んでください。
Agent Teams とは何か（サブエージェントとの決定的な違い）
Agent Teams は、複数の Claude Code インスタンスを「チーム」として協調動作させる仕組みです。1つのセッションが team lead（チームリード） となり、チームの作成・teammate の起動・タスク割り当て・結果の統合を担当します。各 teammate は独立した Claude Code セッションとして、それぞれ自分のコンテキストウィンドウで作業し、必要に応じて teammate どうしが直接メッセージをやり取りします。
ここでよく混同されるのがサブエージェントです。サブエージェントは「1つのセッションの中」で動くヘルパーで、親エージェントに結果を返すだけ。サブエージェントどうしが会話することはありません。一方 Agent Teams の teammate は完全に独立したセッションで、共有タスクリストから自分で作業を取りに行き、互いに findings を共有し、ときに反論し合います。公式ドキュメントでは両者を次のように対比しています。
| 観点 | サブエージェント | Agent Teams（teammate） |
|---|---|---|
| コンテキスト | 独自。結果は呼び出し元へ返る | 独自。完全に独立 |
| 通信 | 親エージェントに結果を返すのみ | teammate どうしが直接メッセージ |
| 調整 | 親エージェントが全作業を管理 | 共有タスクリストで自己調整 |
| 向いている用途 | 結果だけが欲しい焦点的なタスク | 議論・協調が必要な複雑な作業 |
| トークンコスト | 低い（要約して親に返す） | 高い（各 teammate が独立インスタンス） |
判断の軸はシンプルです。「ワーカーどうしが互いに話す必要があるか」。結果さえ返ってくればいい焦点的なタスクならサブエージェント、findings を共有・批判し合いながら自分たちで調整してほしいなら Agent Teams、という使い分けになります。なお、サブエージェントの設計と使い分けは Claude Code サブエージェント並列開発入門 で詳しく扱っているので、合わせて読むと違いがクリアになります。
有効化の手順（実験的機能・デフォルト無効）
Agent Teams はデフォルトで無効です。公式ドキュメントには「Agent teams are experimental and disabled by default」と明記されており、有効化には CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS を 1 に設定する必要があります。設定方法は、シェルの環境変数か settings.json のどちらかです。また、Claude Code v2.1.32 以降が必要なので、まずバージョンを確認しましょう。
- バージョン確認 —
claude --versionを実行し、v2.1.32 以降であることを確認する。古い場合はアップデートする。 - settings.json で有効化 —
~/.claude/settings.json（またはプロジェクトの設定ファイル）のenvにCLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMSを追加する。 - または環境変数で有効化 — シェルで
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1を設定する。一時的に試すならこちらが手軽。 - 表示モードを選ぶ（任意） — 同一ターミナル内で切り替える in-process か、各 teammate を別ペインに分ける split panes（tmux または iTerm2 が必要）かを選ぶ。デフォルトは
"auto"。 - 動作確認 — Claude に「agent team を作って」と自然言語で依頼し、teammate が起動するか確認する。in-process モードでは Shift+Down で teammate を巡回できる。
settings.json での有効化は次のように書きます。
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}環境変数で一時的に有効化する場合は次の通りです。
# bash / zsh で一時的に有効化
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude表示モードを固定したいときは ~/.claude/settings.json の teammateMode を設定するか、起動時にフラグで渡します。
// ~/.claude/settings.json
{
"teammateMode": "in-process"
}# 単一セッションだけ in-process を強制する
claude --teammate-mode in-processなお split panes（分割ペイン）モードは tmux または iTerm2（it2 CLI）が前提で、VS Code 統合ターミナル・Windows Terminal・Ghostty では未対応です。どの環境でも動く in-process モードから始めるのが無難です。
teammate の立ち上げと役割分担
有効化したら、あとは 自然言語でリードに指示するだけです。Claude がチームを作り、teammate を起動し、共有タスクリストに沿って作業を割り振ります。teammate の数を Claude に任せることも、明示的に指定することもできます。たとえば PR レビューを並列化したいなら、こう書きます。
Create an agent team to review PR #142. Spawn three reviewers:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.3つの観点（セキュリティ・性能・テストカバレッジ）が独立しているため、teammate が互いに待たずに並行で動けるのがポイントです。リードは3者の findings を後で統合します。teammate 数とモデルを指定したい場合は、次のように書きます。
Create a team with 4 teammates to refactor these modules in parallel.
Use Sonnet for each teammate.役割分担のコツは、公式の best practices に沿うと外しにくくなります。
- ファイル衝突を避ける — 2つの teammate が同じファイルを編集すると上書きが起きる。teammate ごとに別のファイル群を担当させる。
- spawn プロンプトに十分なコンテキストを入れる — teammate はリードの会話履歴を引き継がない。CLAUDE.md・MCP・スキルは自動で読むが、タスク固有の情報は spawn プロンプトに明記する。
- チームサイズは3〜5人から — ほとんどのワークフローは3〜5 teammate でバランスが取れる。15個の独立タスクなら teammate 3人が出発点として妥当。
- タスクの粒度を合わせる — 小さすぎると調整コストが上回り、大きすぎるとチェックインが減る。関数・テストファイル・1レビューのような自己完結した単位が目安。
- リードに任せきりにしない — リードが teammate を待たずに自分で実装し始めることがある。その場合は「Wait for your teammates to complete their tasks before proceeding」と指示する。
リードと teammate の関係は、自然言語ですべて制御します。特定の teammate に追加指示を出したり、アプローチを修正したりも可能です（in-process なら Shift+Down で巡回、split panes ならペインをクリック）。リスクの高い変更では、teammate に「実装前にプランを承認させる」運用もできます。teammate は読み取り専用のプランモードで待機し、リードが承認するまで変更を加えません。プランモードそのものの使い方は Claude Code プランモード実践ガイド を参照してください。
コスト：標準セッションの約7倍をどう抑えるか
Agent Teams の最大の注意点はトークンコストです。各 teammate が独立したコンテキストウィンドウを持つため、消費トークンは teammate の数とそれぞれの稼働時間に比例して増えます。公式コストガイドは「Agent teams use approximately 7x more tokens than standard sessions when teammates run in plan mode（teammate がプランモードで動くとき、標準セッションの約7倍のトークンを使う）」と明記しています。プランモードに限った数字ではありますが、いずれにせよ単一セッションよりかなり多くのトークンを使う前提で運用する必要があります。
公式ガイドが挙げるコスト抑制策は次の通りです。
- teammate には Sonnet を使う — 調整タスクでは能力とコストのバランスが良い。teammate はリードの
/model選択をデフォルトでは継承しないため、/configの「Default teammate model」で指定できる。 - チームを小さく保つ — トークン消費はチームサイズにほぼ比例する。3〜5 teammate を上限の目安に。
- spawn プロンプトを絞る — teammate は CLAUDE.md・MCP・スキルを自動ロードする。spawn プロンプトに書いたものはすべて最初からコンテキストに乗るので、必要最小限にする。
- 終わったら片付ける — アイドル状態でも active な teammate はトークンを消費し続ける。作業が終わったらクリーンアップする。
クリーンアップは、必ずリード経由で行います（teammate にやらせるとチームコンテキストが正しく解決せず、リソースが不整合に残る恐れがある）。自然言語で次のように依頼します。
Clean up the teamクリーンアップは active な teammate が残っていると失敗するので、先に各 teammate をシャットダウンしておきます。シャットダウンもリード経由です。
Ask the researcher teammate to shut downコスト最適化の全体像（モデル選定・コンテキスト管理・プロンプト設計など）は Claude Code トークンコスト最適化ガイド にまとめています。Agent Teams を常用するなら、こちらの基本も押さえておくと無駄打ちが減ります。
使いどころ：並列探索が本当に効くタスク
Agent Teams は「並列探索が価値を生むタスク」で最も効果を発揮します。逆に、直列なタスク・同一ファイルの編集・依存関係の多い作業では、単一セッションやサブエージェントのほうが効率的です。公式が挙げる強い適用例は次の通りです。
- 調査とレビュー — 複数の teammate が問題の異なる側面を同時に調べ、findings を共有・批判し合う。PR レビューを「セキュリティ・性能・テスト」で分担する型が典型。
- 新規モジュール・機能 — teammate がそれぞれ別の部品を担当し、互いに踏まないように分業する。
- 競合仮説でのデバッグ — teammate が別々の仮説を並行検証し、互いの説を反証し合う「科学的議論」型で根本原因に速く収束する。
- レイヤー横断の調整 — フロントエンド・バックエンド・テストにまたがる変更を、それぞれ別の teammate が担当する。
特にデバッグでは、単一エージェントは「もっともらしい説明を1つ見つけて探索を止める」アンカリングに陥りがちです。複数の独立した調査者が互いの説を反証しに行くことで、生き残った仮説が真の根本原因である確率が高まります。次のような adversarial（敵対的）な指示が効きます。
Users report the app exits after one message instead of staying connected.
Spawn 5 agent teammates to investigate different hypotheses. Have them talk to
each other to try to disprove each other's theories, like a scientific
debate. Update the findings doc with whatever consensus emerges.はじめて Agent Teams を使うなら、コードを書かずに済む「PR レビュー・ライブラリ調査・バグ調査」から入るのがおすすめです。並列実装に伴う調整の難しさを避けつつ、並列探索の価値を体感できます。法人での Claude Code 導入を検討している場合は Claude Code 法人導入ガイド も参考にしてください。
【要注意】よくある失敗パターンと回避策
実験的機能だけに、つまずきポイントもはっきりしています。公式の Troubleshooting / Limitations から、特に踏みやすいものを挙げます。
失敗1：teammate が表示されない
❌ チームを作らせたのに teammate が見えず、起動失敗だと早合点する。
⭕ in-process モードでは teammate が動いていても見えていないだけのことがある。Shift+Down で active な teammate を巡回して確認する。split panes を明示した場合は which tmux で tmux の存在を確認する。なお Claude はタスクの複雑さを見て teammate を起動するか判断するため、タスクが単純だとチームを作らないこともある。
失敗2：ファイル衝突で上書きが起きる
❌ 複数の teammate に同じファイルを触らせて、変更が上書きされる。
⭕ teammate ごとに担当ファイルを分ける。作業を「別のファイル群を所有する」形に分解するのが鉄則。
失敗3：リードが勝手に終了する／自分で実装し始める
❌ 全タスクが終わる前にリードが「完了」と判断してしまう。あるいは委任せず自分で実装を始める。
⭕ 「keep going（続けて）」「Wait for your teammates to complete their tasks before proceeding（teammate の完了を待ってから進めて）」と明示的に指示する。タスクの完了マークが遅れて依存タスクがブロックされることもあるので、止まって見えたら実態を確認して手動でステータス更新する。
失敗4：セッション再開で teammate が消える
❌ /resume や /rewind で再開したら、in-process の teammate が復元されず、リードが存在しない teammate にメッセージを送ろうとする。
⭕ 現状の実験版では in-process teammate のセッション再開は未対応。再開後に teammate がいなければ、リードに「新しい teammate を起動して」と指示し直す。
そのほか、1つのリードが管理できるチームは1つだけ（新しいチームを作る前に現在のチームをクリーンアップ）、teammate は自分のチームや teammate を作れない（ネスト不可）、リードは生成元セッションに固定（リーダー交代不可）といった制約があります。実験的機能である以上、これらの挙動は将来変わり得る前提で扱ってください。
品質ゲートを hooks で強制する（任意）
チーム運用に慣れてきたら、teammate が作業を終えるタイミングやタスクの作成・完了時にルールを強制する hooks が便利です。公式は Agent Teams 向けに次の3つのフックを用意しています。いずれも exit code 2 でフィードバックを返し、処理を差し戻せます。
| フック | 発火タイミング | exit 2 の効果 |
|---|---|---|
TeammateIdle |
teammate がアイドルになる直前 | フィードバックを送って作業を継続させる |
TaskCreated |
タスク作成時 | 作成を止めてフィードバックを送る |
TaskCompleted |
タスクを完了マークする時 | 完了を止めてフィードバックを送る |
たとえば「テストが通っていない teammate をアイドルにさせない」「スキーマ変更を含むタスクの完了をブロックする」といったガードレールを、チームの自律性を保ちつつ仕込めます。実験的機能なので、まずは hooks なしで挙動に慣れ、運用が固まってから段階的に追加するのが現実的です。
まとめ：今日から始める3つのアクション
Claude Code の Agent Teams は、サブエージェントの「結果を返すだけ」を超えて、teammate どうしが議論・協調しながら並列で動く実験的機能です。レビュー・調査・新規モジュール開発のように並列探索が効く場面で威力を発揮しますが、トークンコスト（teammate のプランモードで約7倍）と実験段階ゆえの制約を理解したうえで、小さく始めるのが賢いやり方です。
- 有効化して1チーム動かす —
settings.jsonにCLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1を追記し（v2.1.32 以降を確認）、PR レビューを3 teammate で並列レビューさせてみる。 - Sonnet・小さく・片付ける — teammate は Sonnet、3〜5人から、spawn プロンプトは絞り、終わったら必ずリード経由で「Clean up the team」。
- サブエージェントと使い分ける — 結果だけ欲しいならサブエージェント、議論・協調が要るなら Agent Teams。迷ったら関連ガイドで違いを再確認する。
実験的機能のため、フラグ名・挙動・コストは更新される可能性があります。導入前に必ず公式ドキュメントで最新の仕様を確認してください。
Claude Code をチーム開発・法人で本格運用したい、Agent Teams やサブエージェントを含む設計・コスト管理を相談したい——そんなときは、Uravation の Claude Code 導入支援・個別指導もご活用ください。100社以上の支援で培った実装ノウハウを踏まえて、無理のない並列開発体制づくりをお手伝いします。
よくある質問（FAQ）
Q1. Agent Teams とサブエージェントの違いは？
サブエージェントは1セッション内で動き、結果を親エージェントに返すだけで互いに会話しません。Agent Teams の teammate は独立した Claude Code セッションで、共有タスクリストから自分で作業を取り、teammate どうしが直接メッセージをやり取りします。結果だけ欲しいならサブエージェント、議論・協調が必要なら Agent Teams です。
Q2. 有効化はどうやる？
デフォルト無効です。settings.json の env または環境変数で CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 を設定します。Claude Code v2.1.32 以降が必要なので、claude --version で確認してください（2026年6月時点）。
Q3. どれくらいトークンを使う？
各 teammate が独自のコンテキストウィンドウを持つため、単一セッションよりかなり多くなります。公式コストガイドは、teammate がプランモードで動くケースで標準セッションの約7倍と記載しています。Sonnet 利用・小さなチーム・spawn プロンプトの最小化・終了後のクリーンアップでコストを抑えます。
Q4. 何人くらいの teammate が適切？
ほとんどのワークフローは3〜5 teammate が目安です。多すぎると調整コストとトークンが増え、収穫逓減になります。15個の独立タスクなら teammate 3人から始めると管理しやすいと公式は推奨しています。
Q5. split panes（分割ペイン）はどの環境で使える？
tmux または iTerm2（it2 CLI）が必要です。VS Code 統合ターミナル・Windows Terminal・Ghostty では未対応で、その場合はどの環境でも動く in-process モードを使います。
Q6. 注意すべき制約は？
実験的機能のため、in-process teammate のセッション再開が未対応、タスクステータスの遅延、1リード1チームのみ、ネスト不可、リーダー交代不可といった制約があります。挙動が変わる前提で、公式の Limitations を確認しながら使ってください。
出典
- Claude Code 公式ドキュメント「Orchestrate teams of Claude Code sessions」（有効化フラグ・アーキテクチャ・制約・ベストプラクティス、2026年6月時点）
- Claude Code 公式ドキュメント「Create custom subagents」（サブエージェントの仕様・Agent Teams との違い）
- Claude Code 公式ドキュメント「Manage costs effectively」（Agent team token costs：プランモードで約7倍の記載）
- Claude Code 公式ドキュメント「Settings」（
env/teammateMode設定） - Claude Code 公式ドキュメント「Hooks」（
TeammateIdle/TaskCreated/TaskCompleted）
著者：佐藤傑（さとう・すぐる）
株式会社Uravation代表取締役。X（@SuguruKun_ai）フォロワー約10万人。100社以上の企業向けAI研修・導入支援。著書『AIエージェント仕事術』（SBクリエイティブ）、SoftBank IT連載7回執筆。
