Claude Code Agent Teamsとは？使い方・設定・料金とサブエージェントとの違い【v2.1.289対応】

Claude Code Agent Teams（エージェントチーム）は、1つのClaude Codeセッションを「チームリード」にして、別のClaude Codeインスタンスを「チームメイト」として複数起動し、共有タスクリストとメッセージで協調させる機能です。サブエージェントも名前付きなら互いにメッセージを送れますが、チームメイトはそれぞれが独立したClaude Codeセッションで、リードを介さずに人間から直接指示を受けられ、作業の調整もチームメイト自身が行います。

2026年2月5日公開のv2.1.32でリサーチプレビューとして追加され、10月時点でも実験的機能のまま既定で無効です。ただし中身は2月から大きく変わっています。チームを作る専用ツール（TeamCreate）は6月のv2.1.178で廃止され、チームメイトの切り替えキーも変わりました。この記事は2026年10月6日時点の公式ドキュメント（Orchestrate teams of Claude Code sessions）とnpmのlatest版（2.1.289、10月3日公開）に合わせて書いています。

まとめ：Agent Teamsの要点

• 有効化は環境変数 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1。settings.jsonの env にも書けます。
• チームは「この観点で3人起動して」と自然言語で頼むと作られます。1セッションに1チームで、チーム名はセッションIDから自動で付きます。
• 表示は既定のin-process（どのターミナルでも動く）と、tmuxかiTerm2が必要なsplit paneの2種類です。
• 料金はAgent Teams専用の課金ではなく、チームメイトごとのトークン消費がそのまま加わります。消費はほぼ人数に比例します。
• 向くのは調査・レビュー・競合仮説によるバグ調査のように、互いに待たずに進められる作業です。同じファイルを触る作業や順番に進める作業は、単一セッションかサブエージェントのほうが安く速く済みます。

Agent Teamsの構成要素とサブエージェントとの違い

チームリード・チームメイト・タスクリスト・メールボックス

チームは4つの要素で動きます。チームリードはチームメイトを起動して作業を割り振るメインのセッションで、セッションの間ずっと固定です。途中でチームメイトをリードに昇格させることはできません。

共有タスクリストはTaskツールが利用できるセッションで使われ、タスクは pending・in progress・completed の3状態を持ちます。依存先が未完了のタスクは取得できません。ここに注意点があります。v2.1.233（8月14日）以降、Taskツールが既定で付くのはClaude 3.x、Opus 4〜4.7、Sonnet 4〜4.6、Haiku 4.5だけになりました。Opus 4.8やSonnet 5以降の新しいモデルでは、起動前に CLAUDE_CODE_ENABLE_TODO_TOOLS=1 を設定しない限り共有タスクリストは使われず、チームメイトはメッセージだけで作業を調整します。同時に同じタスクを取りに行く競合はファイルロックで防ぎます。チーム名は session- にセッションIDの先頭8文字を付けた自動の名前で、チーム設定（config.json）はセッション終了時に消えます。タスクリストは残るため、再開したセッションでもタスクは引き継がれます。

チーム設定ファイルにはtmuxのペインIDなどの実行時状態が入るので、手で編集しても上書きされます。プロジェクトに .claude/teams/teams.json のようなファイルを置いても設定としては読まれません。役割を使い回したいときは、後述のサブエージェント定義を使います。

サブエージェント・セッション間メッセージ・worktreeとの比較

公式docsは、チームを組む前に軽い手段で足りないかを確かめるよう勧めています。並列化の手段は4つあり、違いは「誰が調整するか」と「トークン量」です。

判断の分かれ目は、作業者同士が途中で発見を共有したり、互いの結論に反論したりする必要があるかどうかです。結果だけ受け取れれば済む調べものや単発の修正はClaude Codeのサブエージェントで足ります。人が手で複数セッションを並べる方法はClaude Codeのgit worktreeでの並列開発、自分のセッション同士で発見を渡す仕組み（v2.1.224以降）はclaude-peers-mcpと公式セッション間メッセージの違いで扱っています。

Agent Teamsの有効化と最初のチームの起動手順

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMSの設定

シェルで export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 とするか、settings.jsonの env に書きます。プロジェクト単位で有効にするなら .claude/settings.json、自分の全プロジェクトなら ~/.claude/settings.json です。

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

チームメイトを起動できるのは対話セッションだけです。-p フラグの非対話モードやAgent SDKでは、変数を有効にしてもチームメイトは作られず、通常のサブエージェントとして動きます。CIのジョブにAgent Teamsを組み込む設計は、現行仕様では成り立ちません。

自然言語でチームを作る指示の書き方

有効化した後は、作業内容と欲しいチームメイトを文章で伝えます。公式docsの例は、3人が互いを待たずに別の角度から調べられる構成になっています。

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.

日本語で「PR #142 をセキュリティ・性能・テストカバレッジの3観点でレビューするチームメイトを3人起動して、それぞれの指摘をまとめて」のように書いても同じです。チームメイトはCLAUDE.md・MCPサーバー・スキルを読み込みますが、リードの会話履歴は引き継ぎません。対象ディレクトリ、使っている認証方式、報告の形式など、作業に必要な前提は起動の指示に書き込みます。

Claudeはチームを組まずにサブエージェントで済ませることがあります。サブエージェントもチームメイトと同じエージェントパネルに表示されるため、パネルに並んだだけではチームができた証拠になりません。チームが欲しい場合は「agent team として」と明示して頼み直します。

名前付きサブエージェントのチームメイト化と例外

見落としやすいのがこの挙動です。変数を有効にしている間、Claudeが名前（name）を付けて起動したサブエージェントは、forkによる起動やAgentツールの呼び出し自体にisolationを指定した場合を除き、チームメイトとして立ち上がります。Claudeは後でメッセージを送るために自分からサブエージェントに名前を付けることがあるので、チームを頼んでいない作業でもチームができ、トークンが増えます。起動時の確認もありません。

普段はサブエージェントだけを使いたいなら、変数を 0 にします。settings.jsonの env は保存した時点で実行中のセッションにも反映されるため、再起動は不要です。ただしプロジェクト設定・ローカル設定・管理設定のほうが優先度が高く、そこで 1 になっていればそちらが勝ちます。

表示モードの選び方（in-processとsplit pane・tmux・iTerm2）

表示モードは teammateMode で決めます。既定は "in-process" で、追加の準備なしにどのターミナルでも動きます。

in-processでは、プロンプト入力欄の下のエージェントパネルで操作します。上下の矢印キーでチームメイトを選び、Enterでその会話を開いて直接メッセージを送れます。選択中に x で停止、Ctrl+Tでタスクリストの表示を切り替えます。2月の解説にあるShift+Up/Downでの切り替えは、2月18日のv2.1.47でShift+Downだけに簡略化され、現行docsでは矢印キーとEnterの操作になっています。

チームメイトを開いている間も、/compact・/clear・/rewind はリードの会話に作用します（v2.1.286以降は実行前に確認が出ます）。/model と /fast もリードの設定を変えるため、この画面からは実行されません。チームメイトのモデルは起動した時点で固定です。

全員の出力を同時に見たいときはsplit paneにします。セッション単位なら claude --teammate-mode auto と起動します。このフラグは実験扱いで、v2.1.289の claude --help には表示されません。tmuxはOSのパッケージマネージャーで入れ、操作の基本はtmuxの使い方を参照してください。iTerm2では it2 CLI を入れたうえで、Settings → General → Magic の「Enable Python API」を有効にします。iTerm2自体の設定はiTerm2とは？Macのおすすめターミナルにまとめています。

split paneはVS Codeの統合ターミナル、Windows Terminal、Ghosttyでは使えません。Windowsで使う場合はin-processが前提です。

チームメイトのモデル・権限・計画承認の決まり方

モデルの解決順（v2.1.251以降）

チームメイトのモデルは、次のうち最初に当てはまるもので決まります。

1. 起動の指示でそのチームメイトに指定したモデル
2. サブエージェント定義から起動した場合は、その定義の model（inherit ならリードのモデル）
3. CLAUDE_CODE_SUBAGENT_MODEL（inherit 以外の値のとき）
4. リードの現在のモデル

v2.1.251より前は環境変数が最優先でした。全員を1つのモデルに固定したい場合は CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1（v2.1.257以降）を使います。2月時点にあった既定モデルの設定（teammateDefaultModel）はv2.1.234で削除され、残っていても無視されます。組織で availableModels の許可リストを設定している場合、許可されていないモデルの代替は、指定値と接続先によって異なります。ファミリー別名の置換に対応する接続先では同じファミリーの許可済み最新版を使い、それ以外では設定済みの CLAUDE_CODE_SUBAGENT_MODEL を同じ許可条件で試してから、リードのモデルへ戻ります。

権限モードの継承と承認プロンプト

チームメイトはリードの権限モードを引き継ぎます。例外は dontAsk で、これは継承されません。リードを --dangerously-skip-permissions で起動すると全員がそのモードで動くため、隔離していない環境では避けてください。起動後に個別のモードへ変えることはできますが、起動時にチームメイトごとのモードを指定する方法はありません。モードの違いはClaude Codeのパーミッションモードの違いと設定方法で整理しています。

チームメイトの承認プロンプトはすべてリードのセッションに上がってきます。人数が増えると承認待ちで止まりやすいので、よく使うコマンドは起動前に許可ルールへ入れておきます。チームメイト間のメッセージは「別のClaudeセッションからの発言」として扱われ、あるチームメイトが他のチームメイトの代わりに承認することはできません。

チームメイトの計画の自動承認と人による実行承認

リードをplanモードにしてからチームメイトを起動すると、そのチームメイトは計画ができるまで読み取り専用で動きます。2月時点の解説では「リードが計画を審査する」と書かれがちですが、現行docsでは、計画の承認要求が届いた時点でリードのセッションが審査なしに承認すると明記されています。計画段階を挟んでも、計画の中身を人が見るわけではありません。編集やコマンド実行には通常の承認プロンプトが残るので、人のチェックはそちらで行います。

Hooksによる品質ゲート（TeammateIdle・TaskCreated・TaskCompleted）

チーム向けのフックは3つあります。どれもマッチャーに対応せず、イベントのたびに必ず実行されます。TaskCreatedとTaskCompletedはTaskツールが動いているセッションでしか発火しないため、Opus 4.8以降のモデルでは前述の CLAUDE_CODE_ENABLE_TODO_TOOLS=1 が前提です。仕様の詳細は公式のHooksリファレンスにあります。

bash・jq・npmが利用でき、フックの作業ディレクトリにtestスクリプトを定義したpackage.jsonがある環境で、テストが通るまでタスクを完了にさせない例です。stderrに書いた文がそのままチームメイトへのフィードバックになります。入力JSONの teammate_name はリード自身が完了にした場合などに欠けることがあるため、既定値を置いています。

#!/bin/bash
# .claude/hooks/task-completed.sh
INPUT=$(cat)
SUBJECT=$(echo "$INPUT" | jq -r '.task_subject')
WHO=$(echo "$INPUT" | jq -r '.teammate_name // "lead"')
TEST_LOG=$(mktemp) || exit 2
trap 'rm -f "$TEST_LOG"' EXIT

if ! npm test --silent > "$TEST_LOG" 2>&1; then
  echo "[$WHO] テストが通っていません。直してから「$SUBJECT」を完了にしてください。" >&2
  tail -n 20 "$TEST_LOG" >&2
  exit 2
fi
exit 0

このスクリプトは、テストが失敗する package.json に入力JSONを流すと終了コード2とメッセージを返し、成功させると0を返すことをbashとjq 1.7.1で確認しています。登録はsettings.jsonに書きます。

{
  "hooks": {
    "TaskCompleted": [
      {
        "hooks": [
          { "type": "command", "command": "bash \"${CLAUDE_PROJECT_DIR}/.claude/hooks/task-completed.sh\"" }
        ]
      }
    ]
  }
}

TaskCompletedとTeammateIdleは、終了コードの代わりに {"continue": false, "stopReason": "..."} を返すとチームメイト自体を止められます。ただしTaskCompletedでは、チームメイトのターン終了によって発火した場合に限ります。TaskUpdateによる発火では continue: false は無視され、完了を阻止するには終了コード2を返します。TaskCreatedは continue: false を無視します。TeammateIdleでexit 2を返し続けると、チームメイトがアイドルにならずトークンを使い続ける点に注意してください。判定条件は「成果物ファイルがあるか」のように、いずれ必ず満たせるものにします。フック全般の書き方はClaude Code Hooksの設定方法で扱っています。

Agent Teamsの料金とトークン消費の目安

Agent Teamsに専用の料金はありません。チームメイトはそれぞれ独立したClaude Codeインスタンスとして自分のコンテキストウィンドウを持つため、その分のトークンが、使っているプランの利用枠かAPIの従量課金からそのまま消費されます。公式のコスト解説は、消費は動いているチームメイトの数と各自の稼働時間に比例し、おおむねチームの人数に比例すると説明しています。

比較の基準として、公式のコスト解説が示すClaude Code全体の企業平均は、開発者1人あたり稼働日1日約13ドル、月150〜250ドルです。チームメイトを3人足せば、その時間帯の消費はリード1人の数倍になると見積もっておくのが安全です。プランごとの上限や損益分岐はClaude Codeの料金プラン比較を参照してください。

公式docsが挙げる抑え方は次のとおりです。

• チームメイトにはSonnetを指定する（起動の指示に「Use Sonnet for each teammate」と書く）
• 人数を絞る。docsの目安は多くの作業で3〜5人、独立タスクが15個あっても3人から始める
• 起動の指示を必要な前提だけに絞る（指示文はそのまま全員のコンテキストに載る）
• 作業が終わったチームメイトは「researcher に終了するよう伝えて」と名前で止める

見落としやすいのがキャッシュです。in-processのチームメイトのリクエストはメイン会話のキャッシュ期間の対象外で、サブスクリプションでも既定5分で切れます。休憩を挟む長い作業では、subagentPromptCacheTtl を "1h" にすると再読み込みが減ります。ただしAPI課金では1時間キャッシュの書き込み単価が高くなります。

2026年2月の解説から変わったAgent Teamsの仕様

国内の解説記事の多くは2月の公開直後に書かれています。次の変更を知らずに手順をなぞると、存在しないツールやキーを探すことになります。版と日付は公式CHANGELOGとnpmレジストリの公開日時で確認しました。

版の変更以外にも、現行docsの記述が2月時点と違う点が3つあります。全員に一斉送信する説明は消え、「全員に届けるには1人ずつ送る」と書かれています。Shift+Tabで切り替えるデリゲートモードは現行docsに記載がありません。チーム名は自分で付けるものではなく、session- で始まる自動の名前です。フックの入力にある team_name も非推奨になっています。

Claude Code本体の版の確認とアップデートはClaude Codeの最新バージョンは2.1系を参照してください。Agent Teamsは版ごとの修正が多い機能なので、挙動が記事と違うときはまず版を上げてから確かめます。

Cコンパイラ事例とAgent Teams機能の関係

Agent Teamsの紹介では、AnthropicのNicholas Carlini氏が2026年2月5日に公開したBuilding a C compiler with a team of parallel Claudesがよく引かれます。16エージェントがおよそ2,000セッション・2週間で、Linux 6.9をx86・ARM・RISC-Vでビルドできる10万行のRust製Cコンパイラを書いた事例で、入力トークンは20億、費用は2万ドル弱でした。GCC torture test suiteを含む主なテストスイートの通過率は99%です。

ただし、この実験はClaude CodeのAgent Teams機能そのものを使ったものではありません。記事に書かれた実装は、エージェントごとにDockerコンテナを立て、claude --dangerously-skip-permissions -p を無限ループで回し、共有のbareリポジトリへpushさせる自作のハーネスです。タスクの取り合いは current_tasks/ にテキストファイルを書いてロックし、衝突はgitの同期で検出していました。前述のとおり、Agent Teams機能は -p の非対話モードではチームメイトを起動しません。

この事例から持ち帰れるのは機能の使い方ではなく、並列化の条件です。Linuxカーネルのビルドという1つの巨大なタスクでは、16エージェントが同じバグに取り組んで互いの変更を上書きし、並列化が効きませんでした。GCCを正解として使い、カーネルの大半のファイルをGCCで、残りだけを自作コンパイラでビルドする方式に変えて、ようやく各エージェントが別々のバグを担当できるようになっています。Agent Teamsでも同じで、作業を互いに独立した単位に割れない限り、人数を増やしても速くなりません。16bit x86のコード生成を最後まで実装できなかった点など、記事には限界も具体的に書かれています。

Agent Teamsが向かない作業と現行の制限

採用を見送るべきなのは、次の条件に当てはまる作業です。

• 同じファイルを複数人が編集する：上書き事故が起きます。docsはチームメイトごとに担当ファイルを分けるよう求めています。
• 前の結果を待たないと進めない順次作業：調整コストだけが増えます。
• 定型の小さな修正：単一セッションのほうが安く済みます。
• 放置して回したい長時間作業：チームメイトはエラーで止まることがあり、リードも全タスクの完了前に「終わった」と判断することがあります。

現行の制限は次のとおりです。

split paneで使った後にtmuxのセッションが残った場合は、tmux ls で一覧を出し、チームが作ったセッションを tmux kill-session -t <セッション名> で終了します。初めて導入するなら、コードを書かせる前にPRレビューやライブラリ調査のような読み取り中心の作業から始めると、並列化の効果と調整の手間を切り分けて確かめられます。複数エージェントを協調させる設計パターンの全体像はAnthropic公式マルチエージェント協調5パターンの選び方で比較しています。

よくある質問

Agent TeamsはWindowsで使えますか？

既定のin-processモードはどのターミナルでも動きます。split paneはtmuxかiTerm2が必要で、Windows TerminalとVS Codeの統合ターミナルには対応していません。

チームメイトは何人まで起動できますか？

公式docsには、起動人数の上限値は明記されていません。ただし人数に比例してトークンが増え、調整の手間も増えるため、docsは多くの作業で3〜5人から始め、1人あたり5〜6個のタスクを持たせる構成を勧めています。

claude -p やAgent SDKからAgent Teamsを使えますか？

使えません。非対話モードとAgent SDKのセッションでは、変数を有効にしてもチームメイトは起動せず、名前付きのサブエージェントも通常のサブエージェントとして動きます。

サブエージェント定義をチームメイトに使い回せますか？

使えます。「security-reviewer エージェントタイプでチームメイトを起動して」のように定義名を指定すると、tools と model が適用されます。定義の skills はどちらの表示モードでも適用されず、mcpServers はsplit paneのチームメイトにだけ効きます。

リードがチームメイトを待たずに自分で実装を始めたらどうしますか？

公式docsの対処は「Wait for your teammates to complete their tasks before proceeding」とリードに伝えることです。逆にリードが早く切り上げた場合は、続けるよう指示します。

関連記事

• Claude Codeのサブエージェントとは？作り方・設定項目・使い方【v2.1.287対応】
• Claude Codeのgit worktreeで並列エージェント開発を行う方法｜仕組み・使い方・注意点【2026年版】
• Claude Code Hooksの設定方法｜全33イベント一覧とsettings.jsonの書き方【2026年9月版】
• Claude Codeの料金プラン比較｜Pro・Max・Team・APIの損益分岐と支出上限の設定【2026年9月】
• tmuxの使い方｜Windows(psmux・WSL)の導入とコマンド・画面分割【3.7対応】