---
title: "Claude Code Agent Teamsとは？使い方・設定・料金とサブエージェントとの違い【v2.1.289対応】"
url: "https://www.issoh.co.jp/tech/details/10960/"
published: 2026-02-13
updated: 2026-10-06
categories: ["Claude"]
publisher: "株式会社一創"
---

# 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）](https://code.claude.com/docs/en/agent-teams)と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つの要素で動きます。チームリードはチームメイトを起動して作業を割り振るメインのセッションで、セッションの間ずっと固定です。途中でチームメイトをリードに昇格させることはできません。

| 要素      | 役割           | 保存場所                                  |
| ------- | ------------ | ------------------------------------- |
| チームリード  | 起動・割り振り・統合   | メインのセッション                             |
| チームメイト  | 割り当てタスクを実行   | 独立したClaude Code                       |
| タスクリスト  | 作業の取り合いと依存管理 | \~/.claude/tasks/{team-name}/         |
| メールボックス | エージェント間メッセージ | \~/.claude/teams/{team-name}/inboxes/ |

共有タスクリストは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つあり、違いは「誰が調整するか」と「トークン量」です。

| 手段           | 調整役          | やり取り                | トークン     |
| ------------ | ------------ | ------------------- | -------- |
| サブエージェント     | メインのエージェント   | 結果を返す・名前付きなら相互通信も可能 | 少ない      |
| Agent Teams  | リード＋チームメイト自身 | チームメイト同士で直接         | 多い       |
| セッション間メッセージ  | 人間           | 自分のセッション同士          | セッション数次第 |
| git worktree | 人間           | なし（手動）              | セッション数次第 |

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

## 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"` で、追加の準備なしにどのターミナルでも動きます。

| teammateMode     | 動作                            |
| ---------------- | ----------------------------- |
| “in-process”（既定） | メインのターミナル内で全員が動く              |
| “auto”           | tmux内かit2入りiTerm2ならsplit pane |
| “tmux”           | tmuxかiTerm2を検出してsplit pane    |
| “iterm2”         | it2 CLIでiTerm2のネイティブ分割        |

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の使い方](/tech/details/9564/)を参照してください。iTerm2では [it2 CLI](https://github.com/mkusaka/it2) を入れたうえで、Settings → General → Magic の「Enable Python API」を有効にします。iTerm2自体の設定は[iTerm2とは？Macのおすすめターミナル](/tech/details/7913/)にまとめています。

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のパーミッションモードの違いと設定方法](/tech/details/11246/)で整理しています。

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

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

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

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

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

| イベント          | 発火タイミング           | exit 2の効果           | 追加版     |
| ------------- | ----------------- | ------------------- | ------- |
| TeammateIdle  | チームメイトがアイドルになる直前  | フィードバックを渡して作業を続けさせる | v2.1.33 |
| TaskCreated   | TaskCreateでタスク作成時 | 作成を取り消す             | v2.1.84 |
| TaskCompleted | タスクを完了にする時        | 完了にさせない             | v2.1.33 |

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の設定方法](/tech/details/9864/)で扱っています。

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

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

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

公式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](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md)とnpmレジストリの公開日時で確認しました。

| 版（公開日）        | 変更                                  |
| ------------- | ----------------------------------- |
| 2.1.32（2/5）   | リサーチプレビューとして追加                      |
| 2.1.33（2/6）   | TeammateIdle・TaskCompletedフック追加     |
| 2.1.47（2/18）  | 切り替えがShift+Downのみに                  |
| 2.1.84（3/25）  | TaskCreatedフック追加                    |
| 2.1.178（6/15） | TeamCreate・TeamDelete廃止、1セッション1チームに |
| 2.1.186（6/22） | teammateMode “iterm2” 追加            |
| 2.1.233（8/14） | Opus 4.8以降でTaskツールが既定で外れる           |
| 2.1.234（8/17） | 既定チームメイトモデルの設定を削除                   |
| 2.1.251（8/28） | モデル解決順を変更、最終回答がアイドル通知に載る            |
| 2.1.281（9/23） | –setting-sourcesをチームメイトにも適用         |

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

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

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

Agent Teamsの紹介では、AnthropicのNicholas Carlini氏が2026年2月5日に公開した[Building a C compiler with a team of parallel Claudes](https://www.anthropic.com/engineering/building-c-compiler)がよく引かれます。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はチームメイトごとに担当ファイルを分けるよう求めています。
- 前の結果を待たないと進めない順次作業：調整コストだけが増えます。
- 定型の小さな修正：単一セッションのほうが安く済みます。
- 放置して回したい長時間作業：チームメイトはエラーで止まることがあり、リードも全タスクの完了前に「終わった」と判断することがあります。

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

| 制限                                    | 回避策                       |
| ------------------------------------- | ------------------------- |
| /resume・/rewindでin-processチームメイトが戻らない | 新しく起動し直させる                |
| タスクの状態更新が遅れることがある                     | 手動で更新するかリードに催促させる         |
| 入れ子のチームは作れない                          | チームの管理はリードだけ              |
| in-processチームメイトのサブエージェントは前景実行のみ      | background: true の定義を使わない |
| 終了に時間がかかる                             | 実行中の処理が終わるまで待つ            |

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

## よくある質問

### 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対応】](/tech/details/7911/)
- [Claude Codeのgit worktreeで並列エージェント開発を行う方法｜仕組み・使い方・注意点【2026年版】](/tech/details/11708/)
- [Claude Code Hooksの設定方法｜全33イベント一覧とsettings.jsonの書き方【2026年9月版】](/tech/details/9864/)
- [Claude Codeの料金プラン比較｜Pro・Max・Team・APIの損益分岐と支出上限の設定【2026年9月】](/tech/details/17988/)
- [tmuxの使い方｜Windows(psmux・WSL)の導入とコマンド・画面分割【3.7対応】](/tech/details/9564/)

---

出典: [Claude Code Agent Teamsとは？使い方・設定・料金とサブエージェントとの違い【v2.1.289対応】](<https://www.issoh.co.jp/tech/details/10960/>)（株式会社一創）