Claude Code Agent Teams 完全ガイド2026：Subagentsとの違い・実践ユースケース・コスト計算

エンジニアのゆとです。

Agent Teamsを使い始めて、一番最初に感じたのは「これSubagentsと何が違うんだ」という疑問だった。

並列処理という文脈でまとめて語られるが、設計思想がまるで違う。Subagentsは「外注業者に仕事を振って結果だけもらう」モデル。Agent Teamsは「チームミーティングで全員がホワイトボードを囲んで議論する」モデルだ。

もう1つ、フリーランス一人で使う場合に必ず気になるのがコスト。「大幅にトークンが増える」という公式の注記があるが、Claude Max加入者には実質追加費用ゼロという事実がある。これを知らずに避けているエンジニアが多いと思って、この記事を書くことにした。

有効化の方法から、一人エンジニアが実際に使う場面、Subagentsとの使い分け判断まで、実用ベースでまとめる。

Agent Teamsとは：「Claude Code同士がグループチャットで議論する仕組み」

Agent Teamsは、複数のClaude Codeインスタンスがチームとして連携して動作する仕組みだ。1つのセッションがチームリーダーになり、複数のTeammateを生成して、共有タスクリストで作業を分担させる。

Teammateは独立したコンテキストウィンドウを持ち、互いに直接メッセージを送り合える。これが後述するSubagentsとの最大の違いになる。

必要なバージョンはClaude Code v2.1.32以降。まだ「Experimental（実験的機能）」という位置づけで、デフォルトは無効になっている。

Subagentsとの根本的な違い（表で整理）

同じ「並列処理」文脈で語られるが、アーキテクチャが根本的に異なる。

比較軸	Subagents	Agent Teams
コンテキスト	独立。結果のみメインに返す	独立。完全に自律したセッション
エージェント間通信	不可（メインとしか話せない）	可能（Teammate同士が直接通信）
調整方法	メインエージェントが全管理	共有タスクリストで自己調整
向いているタスク	結果だけ必要な集中タスク	議論・協調が必要な複雑作業
トークンコスト	低め（要約した結果をメインに返す）	高め（各Teammateが独立インスタンス）
/resumeサポート	可能	不可（制限あり）

Subagentsは「メインエージェントが全体を管理し、ワーカーは結果だけ報告する」ハブアンドスポーク型。Agent Teamsは「チームメンバーが共有タスクリストを見ながら、必要に応じて直接会話する」メッシュ型だ。

どちらを選ぶかの判断フローは記事の後半で整理する。

どんな問題を解決するのか

Agent Teamsが本領を発揮するのは「並列探索に価値があるタスク」だ。公式ドキュメントが挙げる代表例は以下の4つ：

• 調査とレビュー: 問題の異なる側面を複数のTeammateが同時に調査し、互いに検証
• 新機能開発: Teammateが干渉せずに別々のモジュールを担当
• 競合仮説のデバッグ: 異なる根本原因理論を並列でテストして収束を速める
• クロスレイヤー調整: フロントエンド・バックエンド・テストを別々のTeammateが担当

逆に、以下のようなケースではSubagentsや単一セッションのほうが効率的だ：

• 順序が決まっている逐次タスク
• 同じファイルを複数が編集する必要がある作業
• 依存関係が多くて独立実行が難しいタスク

「チームメンバーが独立して動ける」かどうかが、Agent Teamsを選ぶ判断基準になる。

有効化は30秒：settings.jsonに1行追加するだけ

Agent Teamsはデフォルト無効。有効化は環境変数 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS を 1 にセットするだけだ。

settings.jsonで有効化する方法

プロジェクトまたはユーザーのsettings.jsonに以下を追加する：

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

settings.jsonの場所：

• ユーザーレベル（全プロジェクトで有効）: ~/.claude/settings.json
• プロジェクトレベル（そのプロジェクトのみ）: .claude/settings.json

フリーランスで複数プロジェクトを抱えているなら、ユーザーレベルで一括設定するのが楽だ。

環境変数での設定（シェル別）

settings.jsonを使わず、シェルの環境変数として設定する方法もある：

# bash / zsh（.bashrc / .zshrc に追記）
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

# fish
set -x CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 1

# 一時的に有効化（現在のシェルセッションのみ）
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude

特定のプロジェクトだけで試したい場合は .env ファイルに書いて direnv と組み合わせるのが便利だ。

正常起動の確認方法

有効化後、Claudeにチーム作成を依頼してみる：

Create an agent team to review my codebase from 3 angles:
security, performance, and maintainability.

これでTeammateが生成されれば有効化成功だ。バージョンが足りない場合はエラーが出る：

# バージョン確認
claude --version
# v2.1.32 以上が必要

In-processモード（デフォルト）では、Shift+Downでテームメンバーを切り替えられる。分割ペインモードが必要な場合はtmuxのインストールが別途必要だが、通常の用途ではIn-processで十分だ。

フリーランスエンジニアが実際に使う場面3選

「並列処理が使える」と聞いても、具体的な場面がイメージできないと使わない機能になりがちだ。フリーランス一人エンジニアが本当に価値を感じた3つのユースケースを紹介する。

1. 並列コードレビュー（安全性・パフォーマンス・可読性を同時に）

PRレビューを1つのセッションで頼むと、どうしても1つの観点に偏る。セキュリティに集中すると可読性を見落とす、パフォーマンスを見ているとテストカバレッジが甘い、という状況になりやすい。

Agent Teamsで3つの観点を同時に走らせると、それぞれが専門家として独立したレンズで見てくれる：

Create an agent team to review PR #142.
Spawn three reviewers:
- security: security vulnerabilities, token handling, input validation
- performance: DB query efficiency, N+1, memory leaks
- readability: naming conventions, documentation, test coverage

3つのTeammateが同時にレビューを開始して、各自の調査結果を共有する。最終的にLeaderが統合報告書をまとめてくれる。

単一セッションだと3回に分けて頼むところを、1回のプロンプトで完結する。実際の体感では、PR1件のレビュー時間が30-40分から10分前後に縮まった。

2. フルスタック機能開発（フロントとバックを並行）

新しいAPIエンドポイントを追加する際に、バックエンド実装とフロントエンドのコンポーネント更新を同時に進めたいことがある。

通常は「バックエンド完成→フロントエンド実装」の逐次になるが、インターフェース定義を先に決めれば並行開発できる：

Create an agent team for the new notification feature:
- backend-dev: implement POST /api/notifications endpoint
  with the spec in docs/notification-api.md
- frontend-dev: build NotificationPanel component that
  consumes the new API (see the spec for interface details)
- test-writer: write integration tests for both sides

docs/notification-api.md にインターフェース仕様を事前に書いておくのがポイント。これがない状態でスポーンすると、バックエンドとフロントエンドで型定義がずれる。

3つのTeammateが独立したファイルセットを担当するため、ファイル競合も起きない。

3. 競合仮説デバッグ（「原因AとBを同時に調査させる」）

「本番でたまに落ちる」系のバグは根本原因の特定が難しい。1つのエージェントに頼むと、最初に「これが原因かも」という仮説に引きずられてしまう。アンカリング効果だ。

複数のTeammateに別々の仮説を担当させて、互いに反証させると収束が速い：

Users report the app exits after one message instead of
staying connected. Spawn 4 teammates to investigate:
- hypothesis-a: investigate WebSocket connection timeout issues
- hypothesis-b: investigate memory leak in message handler
- hypothesis-c: investigate race condition in connection pool
- hypothesis-d: focus on server-side session expiry

Have them try to disprove each other's theories,
like a scientific debate.

「反証しようとする」という指示が重要だ。単純に調査させるだけだと各TeammateがそれぞれのYesを返すだけになる。「他の仮説を崩しに行く」構造にすると、生き残った仮説が真因に近い。

実際に使ってみると「3つの仮説が潰れて1つが残った」というケースで、その残った仮説が正解だった確率が高い。

Agent Teamsを制御する

display mode：Teammate ModeとStandard Modeの使い分け

Agent Teamsには2つの表示モードがある：

• In-process（デフォルト）: 全Teammateがメインターミナル内で動く。Shift+Downでサイクル切り替え。追加セットアップ不要
• 分割ペイン（Split Pane）: 各Teammateが独自のペインを持つ。全員の出力を同時に確認できる。tmuxまたはiTerm2が必要

settings.jsonで設定する：

{
  "teammateMode": "in-process"
}

または単一セッションのみフラグ指定：

claude --teammate-mode in-process

フリーランスの日常用途では In-processで十分だ。分割ペインは5人以上のチームで全員の進捗を目視したい場合に有効だが、3-4人チームならIn-processのShift+Downで追いかけられる。

tmuxセッション内でClaude Codeを実行している場合はデフォルトで分割ペインモードに切り替わる。意図しない分割を防ぎたいなら "teammateMode": "in-process" を明示的に設定しておくこと。

チームメンバーのモデル指定でコストを下げる

Teammateが使うモデルはデフォルトではLeaderの選択を継承しない。設定しなければLeaderとは別のモデルが選ばれる。

明示的に指定するのが最も確実だ：

Create a team with 3 teammates to refactor these modules.
Use claude-sonnet-4-5 for each teammate.

プロンプトで指定しない場合のデフォルトモデルを変更するには /config で Default teammate model を設定する。Default (leader’s model) を選べば、LeaderのモデルにTeammateが追従する。

コスト観点ではSonnet系を指定するのが基本戦略だ。後述するコスト計算セクションで詳しく扱う。

Delegate ModeとPlan Approvalで暴走を防ぐ

リスクの高いタスク（本番データへのアクセス、スキーマ変更など）には、Teammateが実装前にプランを承認させる仕組みを使える：

Spawn an architect teammate to refactor the authentication module.
Require plan approval before they make any changes.

この指示でTeammateは「プランモード」で動き始める。コードを書く前に変更計画をLeaderに送って、承認を待つ。

LeaderがOKを出すまでTeammateは読み取り専用状態を保つ。「フィードバック付きで却下→再プラン→再承認」というサイクルも回せる。

公式ドキュメントによると、プランモードでのトークン消費は標準セッション比約7倍になる。「安全のためにプランApprovalを全部につける」というのはコスト面では得策ではない。実際のコード変更が走るタスクだけに限定するのが現実的だ。

CLAUDE.mdでチーム定義を書く（テンプレート付き）

Teammateの役割定義は毎回プロンプトに書くより、CLAUDE.mdまたはSubagent定義ファイルに書いておくと再利用できる：

# .claude/agents/security-reviewer.md
---
name: security-reviewer
description: セキュリティレビュー専門エージェント
tools: Read, Bash
model: claude-sonnet-4-5
---

# セキュリティレビューエージェント

認証・認可・入力バリデーション・XSS・SQLインジェクション・
機密情報の露出を中心にレビューする専門エージェント。

## レビュー観点
- JWTトークンの保管・有効期限設定
- セッション管理の適切性
- 入力値のサニタイズ・バリデーション
- 秘密鍵・APIキーのハードコード
- CORS設定の妥当性

## 出力形式
severity（critical/high/medium/low）付きで問題を箇条書き。
修正提案を各問題に添付。

定義済みのSubagentをTeammateとして使うには：

Spawn a teammate using the security-reviewer agent type to audit src/auth/.

この方法だと tools と model の設定がTeammateにも引き継がれる。毎回プロンプトで細かい役割を指定する手間が省けて、品質も安定する。

トークンコストの現実：結論「Maxプランなら追加ゼロ」

コストについてはっきり言うと、Claude Max加入者には実質的な追加費用はない。先にこれを書いておく。

チームメンバー数とコストの関係

公式ドキュメントには「トークン使用量はアクティブなTeammateの数と実行期間でスケールする」とある。シンプルに言うと：

Agent Teams総コスト ≈ Teammate数 × 各Teammateのコンテキスト使用量

3人チームなら単一セッション比でおおよそ3倍のトークンを消費する。プランモードを使う場合はさらに約7倍という公式の数字もある。

APIユーザーにとってはこれが直接コストに響く。Sonnet ($3/MTok input, $15/MTok output)で3人チームを1時間走らせると、数ドルから十数ドルになることがある。

SonnetでTeammateをOpusより大幅安くする戦略

Teammateのモデルを明示的にSonnetにするだけで、コストを大幅に削減できる。

参考として公式の料金体系（2026年6月時点）：

• claude-opus-4: Input $15/MTok / Output $75/MTok
• claude-sonnet-4-5: Input $3/MTok / Output $15/MTok
• claude-haiku-3-5: Input $0.8/MTok / Output $4/MTok

LeaderがOpusで動いていても、TeammateはSonnet指定にするだけでコストが1/5になる。Teammateの多くは「単一ドメインのレビュー・実装・テスト」という集中タスクなので、Sonnetで十分な品質が出る。

Create a team with 4 teammates using claude-sonnet-4-5 to refactor
the API modules in parallel.

複雑なアーキテクチャ設計や多段推論が必要なTeammateだけOpusにして、残りはSonnet—という使い分けが最もコスト効率がいい。

Claude Max（$200/月）加入者は追加費用なし

これが最重要の事実だ。

公式ドキュメントの/usageコマンド説明に明記されている：

Claude Max および Pro サブスクライバーはサブスクリプションに使用量が含まれているため、セッションコスト数値は請求目的では関連がありません。

Claude Max（$200/月）プランはトークン使用量に応じた追加課金がない。Agent Teamsで3人のTeammateを同時に走らせても、$200の月額に含まれる。

フリーランスエンジニアでClaude Maxに加入している場合、Agent Teamsのコスト試算は実質ゼロだ。「トークンを3倍消費する」という事実は変わらないが、Maxプランの「使い放題」の枠内で動く。

ただし、使用量が多すぎると利用制限に引っかかる場合はある。その際はしばらく待つか、Teammate数を減らすかで対応する。

ちなみに /usage コマンドで現在の消費状況を確認できる。プランの利用量バーが確認できるので、上限が近い場合はTeammateを走らせるタイミングを調整できる。

やりがちな失敗3つとその対処

コンテキスト不足で的外れな結果が出る

TeammateはLeaderの会話履歴を引き継がない。プロジェクトのCLAUDE.md・MCPサーバー・Skillsは自動ロードされるが、「さっきの議論で決まった方針」「この変数名の意味」といった会話コンテキストは届かない。

対処は単純で、スポーンプロンプトに必要な情報を全部入れること：

# 悪い例
Spawn a security reviewer to check the auth module.

# 良い例
Spawn a security reviewer teammate to audit src/auth/.
Context:
- This app uses JWT tokens stored in httpOnly cookies
- Session expiry is 24h, refresh token is 7 days
- The authentication flow is OAuth2 with Google as IDP
Focus on: token handling, session management, input validation.
Report issues with severity ratings (critical/high/medium/low).

5-10行のコンテキストを追加するだけで、Teammateの結果品質が大きく変わる。「コンテキスト不足で的外れ」は最もよくある失敗だ。

ファイル競合（同じファイルを複数が同時編集）

2人のTeammateが同じファイルを編集すると、後から書いた方が上書きする。Agent Teamsにファイルロック機能はない（タスクClaimのロックはあるが、ファイルレベルのロックは別の話だ）。

対処は「担当ファイルを事前に分割する」こと：

Create a team to refactor the API layer:
- teammate-routes: handle src/routes/ only
- teammate-controllers: handle src/controllers/ only
- teammate-models: handle src/models/ only

IMPORTANT: Each teammate works only in their assigned directory.
Do not modify files outside your scope.

担当スコープをプロンプトに明示的に書く。特に共通ファイル（types.ts や constants.ts など）は競合しやすいので、「誰が担当するか」を明確にしておくか、Leaderが後でマージする構造にする。

/resumeが使えない問題（Delegate Modeで回避）

Agent Teamsのin-processモードでは /resume と /rewind が使えない。セッションが途中で切れた場合、TeammateのコンテキストはそのままLeaderが失ったTeammateに向かってメッセージを送ろうとする状態になる。

回避策は2つある：

方法1：新しいTeammateを生成して引き継ぐ

The previous researcher teammate disconnected.
Spawn a new researcher teammate and give it this context:
[調査済みの内容を要約して貼り付ける]

方法2：分割ペインモード（tmux）を使う

分割ペインモードではこの制限が緩和される場合がある。長時間セッションが必要なAgent Teamsはtmux環境で実行するのが安全だ。

セッションが途中で切れることを前提に、重要な調査結果はLeaderにその都度報告させる設計にしておくのが最善策だ：

Periodically report your findings to the team leader
every 30 minutes, even if the task isn't complete yet.

また、Hooksを使った品質ゲートで TeammateIdle イベントをトリガーに進捗をファイルに保存させる方法も有効だ。

Subagents vs Agent Teams：どっちを使うべきか判断フロー

結局「どっちを使えばいい？」という話だ。以下のフローで判断できる：

タスクの性質を確認
│
├── 順序が決まっている（A→B→C）？
│   └── YES → 単一セッション or Subagents
│
├── 独立して動けるか？
│   ├── NO（依存関係が多い）→ 単一セッション
│   └── YES → 次の判断へ
│
├── Teammate同士が会話・検証し合う必要があるか？
│   ├── NO（結果だけ集めればいい）→ Subagents
│   └── YES → Agent Teams
│
└── コスト条件を確認
    ├── Claude Max加入者 → Agent Teams（追加コストなし）
    └── API課金ユーザー → トークン見積もりをしてから判断

具体的なケース分類：

ケース	推奨	理由
PRのレビュー（複数観点）	Agent Teams	Teammateが互いに見落としを補完できる
テストの自動生成	Subagents	結果だけ必要。通信不要
フルスタック機能開発	Agent Teams	フロント/バックが干渉せず並行できる
ドキュメント生成	Subagents	独立タスク。Subagentsで十分
競合仮説のデバッグ	Agent Teams	仮説の反証に通信が必要
データ変換・バッチ処理	Subagents	通信不要の繰り返しタスク
アーキテクチャ設計の議論	Agent Teams	観点の対立・収束が価値

「Teammate同士が情報を共有・反証し合うことで質が上がるか？」がAgent Teamsを選ぶ基準だ。単に並列処理したいだけならSubagentsのほうがシンプルで低コストだ。

SubagentsとAgent SDKの詳細な使い方はこちらの記事で解説している。

まとめ：Agent Teamsは「一人エンジニアの分身システム」

Agent Teamsの実体は「複数のClaude Codeが同じプロジェクトの中でグループチャットしながら並行作業する仕組み」だ。

フリーランス一人エンジニアにとっての実用的なまとめ：

• 有効化はsettings.jsonに1行追加するだけ
• 「Teammate同士が会話・反証し合う必要があるか」がSubagentsとの選択基準
• Claude Max加入者はコスト追加なし。API課金ユーザーはSonnet指定でコスト最適化
• TeammateのコンテキストはLeaderの会話履歴を引き継がない。スポーンプロンプトに全情報を入れる
• 同じファイルを複数が編集すると上書き競合が起きる。担当ファイルを事前に分割する

一番効いたのは「競合仮説デバッグ」だ。根本原因が不明なバグに、4人のTeammateが別々の仮説で調査して互いに反証し合う構造は、単一セッションでは作れないやり方だ。

Hooksとの組み合わせで品質ゲートを自動化する方法はこちらの記事で詳しく書いている。

関連記事

• Claude Agent SDK・Subagents完全ガイド2026
• Claude Code Hooks 完全ガイド2026 — 品質ゲートと自動化の実装
• Claude Codeスキル完全ガイド2026

よくある質問

Q. Agent Teamsに使えるTeammateの数に上限はありますか？

A. 公式ドキュメントに明示的な上限はないが、3-5人が推奨サイズとされている。トークンコストはTeammate数にほぼ比例するし、調整オーバーヘッドも増える。「5人の散らばったチームより3人の集中チームのほうが良い結果が出る」というのが公式の見解。

Q. Agent Teamsを使うのにtmuxは必須ですか？

A. 必須ではない。デフォルトのIn-processモードは任意のターミナルで動く。tmuxが必要なのは「分割ペインモード」を使いたい場合だけだ。通常の用途はIn-processで十分使える。

Q. Teammate同士が同じファイルを編集したらどうなりますか？

A. 後から書いた方が上書きする。ファイルレベルの自動ロックはないので、担当ファイルをスポーンプロンプトで明示的に分割する必要がある。

Q. Agent TeamsのセッションはClaude.aiのWebと連携しますか？

A. しない。Agent TeamsはClaude Code CLI専用の機能。セッションデータはローカルの~/.claude/teams/に保存される。

Q. Claude Proプラン（$20/月）でもAgent Teamsは使えますか？

A. 使える。ただし使用量の制限がMaxより厳しいため、複数Teammateを走らせると制限に達しやすい。Agent Teamsを本格的に使いたいなら、$200/月のMaxプランの方が制限を気にせず使える。