Claude Code Agent Teamsの使い方｜有効化・並列実行・コスト管理の完全ガイド

Claude Code Agent Teamsは、Claude Code内で複数のインスタンスを「チーム」として並列稼働させ、メンバー同士が直接メッセージをやり取りしながら共有タスクリストで自己調整できる実験的機能です。使い方の要点は「環境変数 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 で有効化」→「自然言語でチーム作成」→「Shift+Down でメンバーに切り替えて指示」→「作業後にクリーンアップ」の4ステップで、サブエージェントと違いメンバーが独立コンテキストを持ち直接通信できるのが最大の特徴です。

この記事でわかること:

• Claude Code Agent Teamsの有効化手順（settings.json / シェル環境変数）
• 表示モード（in-process / split panes）の違いと選び方
• チーム作成から片付けまでの実際のプロンプト例・キー操作
• サブエージェントや Git worktree との使い分け
• 「plan mode で約7倍」と公式が警告するトークンコストの抑え方
• 公式が明記している制限事項・セキュリティ注意点

対象読者: Claude Code を既に使っていて並列実行・複数視点レビューを自動化したいエンジニア／テックリード、サブエージェントとの違いを整理してから導入したい方。

Claude Code Agent Teamsとは

Claude Code Agent Teamsは、1つの Claude Code セッションを「チームリーダー」とし、複数の Claude Code インスタンスを「チームメンバー（teammates）」として並列稼働させる機能です。Anthropic 公式ドキュメント（code.claude.com/docs/ja/agent-teams）で2026年2〜3月頃に公開され、現時点では実験的機能（experimental）扱いのため、デフォルトでは無効になっています。

従来のサブエージェント（sub-agents）との決定的な違いは以下の2点です。

• メンバー同士が直接メッセージをやり取りできる（リーダーを経由しない）
• 共有タスクリストをメンバーが claim（要求）して進める自己調整型

公式ドキュメントでは、調査・設計議論・複数モジュールの並列リファクタ・PRレビューなど「複数視点や協調が価値を生むタスク」向けに設計されていると説明されています。

動作要件

サブエージェントとの違い

出典: Anthropic Claude Code 公式ドキュメント

Agent Teams とサブエージェント（sub-agents）は混同されやすいですが、通信モデル・タスク管理・コスト感がまったく異なります。公式ドキュメントとコミュニティ検証情報に基づいて整理すると以下のようになります。

出典: Anthropic公式 Agent Teams ドキュメント / Manage costs effectively

結論として、単一タスクの深掘り調査や結果のみ必要な調査はサブエージェントで十分、複数視点のレビューや並列リファクタのように途中経過の可視化・メンバー間の議論が欲しい場合は Agent Teams が向いています。

有効化方法（セットアップ）

Claude Code Agent Teams は実験的機能のため、環境変数 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS を 1 にセットして初めて利用できます。設定方法は2通りあり、どちらでも同じ結果になります。

方法1: settings.json に追記（推奨）

ユーザー設定ファイル ~/.claude/settings.json の env セクションに追記します。Claude Code を起動するたびに自動適用されるため、日常的に使う場合はこちらが便利です。

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

他の環境変数やキー設定がすでにある場合は、env オブジェクトの中に追加するだけで問題ありません。

方法2: シェル環境変数として設定

一時的に試したい場合は、シェルで環境変数を export するだけで有効化できます。

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude

恒久的に有効化したい場合は、.zshrc や .bashrc に追記します。

バージョン確認

有効化前に、Claude Code のバージョンが v2.1.32 以降であることを確認してください。

claude --version

古いバージョンでは機能自体が存在しないため、先に claude upgrade（または npm 等のインストール経路に応じた更新コマンド）でアップデートします。

表示モードの選び方（in-process / split panes）

Agent Teams の表示モードは現時点で2種類あります。どちらを使うかで操作感が大きく変わるため、環境に合わせて選ぶのが重要です。

デフォルトの動作

設定を変更しなければ teammateMode は "auto" で動作し、tmux セッション内で起動していれば split panes、そうでなければ in-process に自動で切り替わります。

明示的に指定する方法

~/.claude.json の teammateMode キー、または CLI フラグでオーバーライドできます。

claude --teammate-mode in-process
# または
claude --teammate-mode split-panes

非対応ターミナルに注意

公式ドキュメントで明確に非対応と記載されているのは以下です。これらの環境では split panes モードを指定しても動作しません。

• VS Code 統合ターミナル
• Windows Terminal
• Ghostty

普段 VS Code で Claude Code を使っている方は、Agent Teams を試す場合だけ別途ターミナル（iTerm2 / tmux）を立ち上げるのが無難です。

チーム作成〜片付けまでの基本操作

ここからは実際のワークフローを、公式ドキュメント記載のプロンプトに沿って解説します。すべて自然言語で指示するスタイルで、コマンド暗記は不要です。

1. チームを作成する

Claude Code を起動したら、以下のように「どんな役割のチームを作りたいか」を自然言語で伝えます。

I'm designing a CLI tool that helps developers track TODO comments across
their codebase. Create an agent team to explore this from different angles: one
teammate on UX, one on technical architecture, one playing devil's advocate.

日本語でも同じように動作します。

PR #142 をレビューするために、SEO観点・UI観点・セキュリティ観点の3人チームを作って。

リーダーが役割ごとにチームメンバーを spawn し、共有タスクリストを作成して自己調整を開始します。

2. メンバーと直接対話する（キー操作）

In-process モードでは、以下のキー操作でメンバーを切り替えたり状態を確認したりできます。

Split panes モードの場合は、各メンバーのペインをクリックしてそのまま入力できます。

3. メンバー数・モデルを指定する

チームの規模やモデルは、チーム作成時に同時に指定できます。

Create a team with 4 teammates to refactor these modules in parallel.
Use Sonnet for each teammate.

公式推奨は Sonnet。Opus も使えますが、後述のトークンコストが大きく跳ね上がるため、特別な理由がなければ Sonnet を指定するのが無難です。

4. プラン承認モードで慎重に動かす

重要なリファクタや本番コードの書き換えを任せる場合は、プラン承認を挟むのが安全です。

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

この指示を入れると、メンバーはリーダーが承認するまで読み取り専用（plan mode）で待機します。リーダー側は「テストカバレッジを含むプランのみ承認」といった基準を後から追加することも可能です。

5. 既存のサブエージェント定義を流用する

すでにプロジェクトで .claude/agents/ にサブエージェント定義を置いている場合、そのまま teammate として spawn できます。

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

挙動の注意点は以下です。

• サブエージェントの tools allowlist と model は継承される
• サブエージェント本文は teammate の system prompt に追加される（置換ではなく追記）
• サブエージェント frontmatter の skills / mcpServers は引き継がれない — チームメンバーは通常の Claude Code セッションと同様、project / user 設定からロードします

最後の点は日本語記事でも正確に書かれていないことが多いハマりポイントです。スキルや MCP サーバーを前提としたサブエージェントをそのまま teammate として流用すると、期待した挙動にならないことがあります。

6. メンバーをシャットダウンする

個別のメンバーを終了させたい場合は、リーダーから指示します。

Ask the researcher teammate to shut down.

メンバーは承認または却下（理由付き）を返せます。作業途中の重要なタスクがある場合は、却下されることもあります。

7. チームをクリーンアップする

セッション終了時は、必ずリーダー側でクリーンアップを実行します。

Clean up the team.

クリーンアップ時の注意:

• アクティブなメンバーがいると失敗する — 先に全メンバーをシャットダウンしておく
• 必ずリーダー側から実行 — メンバー側から叩くとリソース整合性が崩れる可能性がある
• 放置はトークン浪費につながる — アイドル状態でもコンテキストを保持するためコストが発生し続ける

内部アーキテクチャ（知っておくと得する仕組み）

Agent Teams の動作をより深く理解するために、リーダー／メンバー／タスクリスト／メールボックスという4要素を押さえておくとトラブル時の切り分けが早くなります。

タスク状態と競合回避

• タスク状態は pending / in progress / completed の3段階で、依存関係は自動管理されます
• タスクの claim はファイルロックで競合を回避 — 同じタスクを2人が取ることはありません

設定・データの保存先

重要な運用ルール:

• チーム設定は手動編集禁止 — 次回の state update で上書きされます
• プロジェクトレベル設定（.claude/teams/teams.json など）はサポート対象外 — ユーザーレベルの ~/.claude/teams/ のみが有効

メンバー間のメッセージング

Agent Teams では2種類のメッセージ送信方法があります。使い分けがコストに直結するため、理解しておくと効果的です。

公式は broadcast の使用を「控えめに」と明記しています。人数が多いチームで毎回 broadcast を使うと、トークン消費がすぐに膨れ上がります。「全員に状況共有」のような運用指示が本当に必要か、message で足りないかを都度判断するのが良いでしょう。

メンバーがアイドル状態になった場合の通知は、自動でリーダーに配信されるため、ユーザー側で特別な設定は不要です。

品質ゲートに使える3つのHooks

Agent Teams には、チームの動作を制御・監視するための専用 hooks が用意されています。日本語記事ではほとんど解説されていない領域ですが、品質ゲートや自動化のトリガーとして強力です。

実用例:

• TeammateIdle: メンバーが「やるべきことが尽きた」と判断する前に、未実行のテストやカバレッジ確認を強制する
• TaskCreated: 粒度が粗すぎるタスクが切られたとき、より小さい単位に分割するようフィードバック
• TaskCompleted: lint / test が通っていないタスクを完了させない

いずれも ~/.claude/hooks/ 以下にスクリプトを配置し、exit code で制御する形です（通常の Claude Code hooks と同じ仕組み）。

トークンコスト：「約7倍」を現実的に管理する

Agent Teams 最大の注意点はトークン消費のスケールです。公式ドキュメント「Manage costs effectively」には以下の記述があります。

"Agent teams use approximately 7x more tokens than standard sessions when teammates run in plan mode."
（メンバーを plan mode で動かす場合、標準セッションと比較して約7倍のトークン消費）

各メンバーは独立したコンテキストウィンドウを持つ Claude インスタンスとして動くため、チームサイズに比例してトークンがスケールするのは当然の結果です。公式・コミュニティ情報から、現実的なコスト抑制のコツは以下の4点に集約されます。

コスト抑制のベストプラクティス

1. メンバーには Sonnet を指定する — Opus は必要最小限に
2. チームサイズは3〜5人に抑える — 4人を超えると broadcast コストが急増
3. spawn プロンプトを簡潔に — メンバーの system prompt に渡す初期情報を絞る
4. 作業完了後に必ずクリーンアップする — アイドル状態でもトークン消費が続く

課金形態別の影響

従量課金で利用している場合、常時7倍のコストが発生し得る点は事前に経理的な合意を取っておくことを強くおすすめします。

ユースケース：Agent Teamsが効くシーン

Agent Teams の威力が最大化されるのは、「複数視点」「並列探索」「協調議論」が価値を生むタスクです。コミュニティで報告されている実用例を整理すると次の通りです。

逆に以下のようなケースでは、Agent Teams を使う意味がほとんどありません。

• 1ファイル 1関数のバグ修正
• ドキュメントの軽微な書き換え
• 単純な依存関係アップデート

このような単発タスクは、単一セッションまたはサブエージェントで処理したほうが速く、コストも抑えられます。

公式が明記している制限事項

Agent Teams は実験的機能のため、いくつか重要な制約があります。導入前に必ず把握しておく項目です。

長時間タスクで注意したいこと

/resume で in-process メンバーが復元されないため、「長時間走らせっぱなしにして翌日再開」という運用には向きません。重要な作業は必ず途中経過をログやファイルに残す、または作業が終わるまでセッションを閉じない前提で使うのが安全です。

セキュリティ上の注意点

Claude Code Agent Teams を扱う際、権限モデルとファイル競合の2点に特に注意が必要です。

1. 権限モードはリーダーから全メンバーに継承される

リーダーが --dangerously-skip-permissions で動作していれば、全メンバーにも同じ権限モードが継承されます。意図せずメンバーが危険操作（例: ファイル削除、外部通信）を通してしまうリスクがあるため、このフラグは Agent Teams では原則使わないことを推奨します。

2. 権限プロンプトはリーダーにバブルアップする

メンバーが権限プロンプトを必要とする操作を行う場合、リーダーにプロンプトがバブルアップします。チームサイズが大きいと、リーダー側でプロンプト対応に追われて本来の作業が止まるため、起動前に permissions 設定で一般操作を事前承認しておくのが推奨されています。

3. CLAUDE.md はメンバー全員が読む

プロジェクトの CLAUDE.md はメンバーにも読み込まれるため、プロジェクト固有のガードレール（触ってはいけないディレクトリ、守るべき命名規則など）はここに明記しておくと、各メンバーの判断のばらつきを抑えられます。

4. 同一ファイルの同時編集は上書きリスクがある

2人のメンバーが同じファイルを編集すると、後から書き込んだ側の変更で前の変更が上書きされる可能性があります。チーム作成時に「メンバーAは src/auth/ 配下、メンバーBは src/billing/ 配下」のようにファイル境界を明確に分けるタスク設計が重要です。

失敗しないためのチェックリスト

導入時に踏みがちなトラップを避けるための運用チェックリストです。

• Claude Code のバージョンが v2.1.32 以降
• CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 を settings.json で設定済み
• split panes を使う場合、tmux または iTerm2 で起動
• メンバーのモデルは原則 Sonnet を指定
• チームサイズは 3〜5人 に抑える
• タスク設計で ファイル境界を明確に 分けている
• CLAUDE.md にプロジェクト固有のガードレールを記載済み
• --dangerously-skip-permissions は使っていない
• 作業完了後に 必ずクリーンアップ（Clean up the team）
• 長時間タスクでは途中経過をファイルに出力
• 従量課金 API 利用時は、コスト上限の合意を取っている

サブエージェント / Git worktree との使い分け

Claude Code には並列作業を支える手段が複数あり、それぞれ得意領域が異なります。Agent Teams だけに頼ると過剰になるケースもあるため、3つのアプローチの使い分けを整理しました。

単発の単純タスクは単一セッションやサブエージェント、協調が必要な複雑タスクは Agent Teams、完全に独立した機能ブランチを同時進行するなら Git worktree と役割分担するのが現実的です。

こんな人におすすめ／おすすめしない人

導入をおすすめしたい方

• Claude Code を日常的に使っているエンジニア／テックリード
• PR レビュー・調査・設計議論など「複数視点」が価値を生むタスクが多い
• Claude Max / Team / Enterprise など月額枠に余裕があるプランを使っている
• macOS + tmux / iTerm2 環境で split panes を活用しやすい
• 複数モジュールの並列リファクタや大規模コードベース調査を効率化したい

導入を急がなくてよい方

• シンプルな単発タスク（1ファイル編集、バグ修正1件）が中心
• 同一ファイルに対する逐次編集が多く、ファイル境界を切りにくい
• 従量課金 API 利用でコストを厳しく管理する必要がある
• VS Code / Windows Terminal / Ghostty を中心に使っている
• /resume で長期セッションを復元しながら運用したい

FAQ

Q1. Agent Teams は正式リリースされていますか？

現時点（2026年4月時点）では実験的機能（experimental）扱いです。公式ドキュメントにも Warning が明記されています。今後 GA 化される可能性はありますが、仕様変更やフラグ名変更が入り得る点を前提に使うのが安全です。

Q2. 無料プランでも使えますか？

Claude Code 自体が動けば機能としては有効化できます。ただし Agent Teams は通常セッションの数倍〜約7倍（plan mode 使用時）のトークンを消費するため、無料枠ではすぐに上限に到達します。実用するなら Pro 以上のサブスクリプション、または API キー（従量課金）での利用が現実的です。

Q3. Windows（WSL）でも動きますか？

CLI 自体は動作しますが、split panes は Windows Terminal で非対応と公式が明記しています。WSL + tmux の組み合わせでの動作詳細は公式ドキュメントに記載がないため、まずは in-process モードで使うのが確実です。

Q4. チームメンバーに別のモデル（Opus など）を指定できますか？

可能です。チーム作成時に「Use Opus for the architect teammate, Sonnet for the others.」のように自然言語で指定できます。ただし Opus はトークン単価が高いため、本当に必要な1メンバーのみに絞るのが推奨されます。

Q5. サブエージェントの設定をそのまま流用できますか？

tools allowlist と model は継承されます。サブエージェント本文は teammate の system prompt に追加される形です。ただしskills と mcpServers は継承されないため、スキルや MCP サーバーに依存したサブエージェントをそのまま流用すると期待通りに動かないことがあります。

Q6. チームを作ったら毎回どれくらいのコストがかかりますか？

タスクの長さ・メンバー数・モデル選択・plan mode の使用有無で大きく変わります。公式指標は「plan mode で標準比約7倍」ですが、通常モード＋Sonnet＋3人チームの短時間作業なら2〜3倍程度に収まるケースも多いと報告されています。従量課金なら最初は小さいチームで試し、消費トークンを確認するのが安全です。

Q7. 作業中のチームを一時停止して後で再開できますか？

Claude Code の /resume では in-process のチームメンバーが復元されません。再開後にリーダーが存在しないメンバーに指示を送ろうとする場合があるため、長時間タスクは「その場で最後までやり切る」か、途中成果物を必ずファイルに出力してから終了することをおすすめします。

Q8. チームのクリーンアップを忘れるとどうなりますか？

アクティブなメンバーがアイドル状態で残り続けます。コンテキスト保持のためにトークンを消費し続けるため、セッション終了時は必ず「Clean up the team.」を実行するのが基本です。

まとめ

Claude Code Agent Teams は、複数の Claude Code インスタンスをチーム化し、メンバー同士が直接通信しながら共有タスクリストで自己調整する実験的機能です。従来のサブエージェントと違って並列可視性と協調性が高く、PR レビュー・複数視点の設計議論・並列リファクタのような複雑タスクで威力を発揮します。

導入の4ステップはシンプルです。

1. Claude Code を v2.1.32 以降に更新
2. CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 で有効化
3. 自然言語でチームを作成し、Shift+Down でメンバーに指示
4. 作業完了後に「Clean up the team.」で確実にクリーンアップ

一方で、plan mode で約7倍のトークン消費、/resume 非対応、split panes の動作環境制限など、実験的機能ならではの制約もあります。本記事のチェックリストと使い分け表を参考に、単発タスクはサブエージェント、協調タスクは Agent Teams の判断軸で運用すれば、コストを抑えながら並列開発の恩恵を受けられるはずです。

あわせて読みたい

• Claude Codeとは｜できること・料金・使い方を完全解説
• Claude Code 使い方ガイド｜セットアップから応用まで
• Claude Code 料金プラン徹底解説
• AIエージェント フレームワーク おすすめ比較
• マルチエージェントAIとは｜仕組み・ユースケース・主要ツール