Claude Code Agent Teams 完全ガイド 2026
Anthropic公式ドキュメント基盤で作成
Agent Teams出荷日: v2.1.32 (Research Preview) | 原文: https://code.claude.com/docs/en/agent-teams
1. 概要
Agent TeamsはClaude Code v2.1.32でResearch Previewとして導入されたマルチエージェント協業システムだ。複数のClaude Codeインスタンスが一つのチームとして協力して作業を実行する。
既存のSubagent（下位エージェント）との核心的な違いは、Subagentがメインエージェントにのみ結果を報告するのに対し、Agent Teamsのチームメンバーはお互いに直接メッセージをやり取りし、共有タスクリストを通じて自律的に調整するという点だ。ユーザーもチームリーダーを介さず個別のチームメンバーと直接やり取りできる。
Agent Teamsは実験的機能であり、セッション再開、タスク調整、終了動作に関する既知の制限事項がある。
2. 有効化方法
Agent Teamsはデフォルトで無効化状態だ。
環境変数設定
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
settings.json設定
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
3. チーム開始方法
有効化後、Claudeに自然言語でチーム構成をリクエストする。Claudeが作業とチーム構造に合わせてチームを生成する。
チームが始まる方式は2つ：
- ユーザーがチームをリクエスト: 並列作業が有利なタスクを説明しチームを明示的にリクエスト
- Claudeがチームを提案: Claudeが作業特性上チームが有利と判断したら提案。ユーザー確認後に進行
どちらの場合でもユーザー承認なしにチームは生成されない。
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.
4. ディスプレイモード
In-processモード
- すべてのチームメンバーが一つのターミナル内で実行
-
Shift+Up/Downでチームメンバー選択、タイピングして直接メッセージ送信 -
Enterでチームメンバーセッション表示、Escapeでインタラプト -
Ctrl+Tでタスクリストトグル - 別途設定なしですべてのターミナルで動作
Split panesモード
- 各チームメンバーが自体のtmux/iTerm2ペインで実行
- すべてのチームメンバーの出力を同時に見られ、ペインクリックで直接やり取り
- tmuxまたはiTerm2（
it2CLI必要）が必要 - VS Code統合ターミナル、Windows Terminal、Ghosttyでは非対応
設定方法
デフォルトは"auto"（tmuxセッション内で実行中ならsplit panes、そうでなければin-process）
{
"teammateMode": "in-process"
}
CLIフラグで単一セッションにのみ適用：
claude --teammate-mode in-process
"tmux"設定はsplit-paneモードを有効化し、ターミナルに応じてtmuxまたはiTerm2を自動検知する。
5. アーキテクチャ
核心コンポーネント
| コンポーネント | 役割 |
|---|---|
| Team Lead | チームを作成し、チームメンバーをスポーンし、タスクを調整するメインClaude Codeセッション |
| Teammates | 各自割り当てられたタスクを実行する別のClaude Codeインスタンス |
| Task List | チームメンバーがクレームして完了する共有タスク項目リスト |
| Mailbox | エージェント間通信のためのメッセージングシステム |
ファイルシステム構造
-
チーム構成:
~/.claude/teams/{team-name}/config.json -
タスクリスト:
~/.claude/tasks/{team-name}/
チーム構成ファイルには各チームメンバーの名前、エージェントID、エージェントタイプが含まれたmembers配列がある。チームメンバーはこのファイルを読んで他のチームメンバーを発見できる。
コンテキストと通信
各チームメンバーは自体のコンテキストウィンドウを持つ。スポーン時に通常のセッションと同じプロジェクトコンテキスト（CLAUDE.md、MCPサーバー、skills）をロードし、リーダーのスポーンプロンプトを受ける。リーダーの会話履歴は渡されない。
チームメンバー間の情報共有方式：
- 自動メッセージ転送: チームメンバーがメッセージを送ると受信者に自動転送。リーダーがポーリングする必要なし
- アイドル通知: チームメンバーがタスクを終えて止まるとリーダーに自動通知
- 共有タスクリスト: すべてのエージェントがタスク状態を見て利用可能なタスクをクレーム可能
コミュニケーションツール：
- message: 特定のチームメンバー1人にメッセージ送信
- broadcast: すべてのチームメンバーに同時送信。コストがチームサイズに比例するため可能ならmessage使用推奨
権限
チームメンバーはリーダーの権限設定で開始する。リーダーが--dangerously-skip-permissionsで実行中ならすべてのチームメンバーにも同様に適用される。スポーン後に個別チームメンバーモードを変更できるが、スポーン時点でチームメンバー別モードを設定することはできない。
6. タスクシステム
タスク状態
タスクは3つの状態を持つ：pending、in progress、completed
依存性がある待機タスクは依存タスクが完了するまでクレームできない。依存タスクが完了するとブロックされたタスクが自動的に解除される。
タスク割り当て方式
- リーダー割り当て: リーダーにどのタスクをどのチームメンバーに渡すか指示
- 自己クレーム: チームメンバーがタスク完了後、次の未割り当て/未ブロックタスクを自動的に取得
タスククレーム時にファイルロックを使用して複数のチームメンバーが同時に同じタスクをクレームする競合条件を防止する。
7. チーム制御
チームメンバーおよびモデル指定
Claudeがタスクに応じてチームメンバー数を自動決定するか、直接指定できる：
Create a team with 4 teammates to refactor these modules in parallel.
Use Sonnet for each teammate.
Plan Approval（プラン承認）
複雑または危険なタスクでチームメンバーが実装前に計画を提出するよう要求できる。チームメンバーは読み取り専用プランモードで作業し、リーダーが承認すると実装を開始する。
Spawn an architect teammate to refactor the authentication module.
Require plan approval before they make any changes.
- チームメンバーが計画を完了するとリーダーに承認リクエスト送信
- リーダー承認：チームメンバーがプランモード終了後に実装開始
- リーダー拒否：フィードバックを反映して計画修正後に再提出
リーダーは自律的に承認決定を下す。リーダーの判断に影響を与えるにはプロンプトに基準を提示する（例：「テストカバレッジを含む計画のみ承認しろ」「データベーススキーマを修正する計画は拒否しろ」）。
Delegate Mode（委任モード）
委任モードがないとリーダーがチームメンバーに委任せずに直接実装を始める場合がある。委任モードはリーダーを調整専用ツール（スポーン、メッセージング、終了、タスク管理）だけに制限する。
チームをまず開始した後、Shift+Tabを押して委任モードに切り替える。
チームメンバー終了
Ask the researcher teammate to shut down
リーダーが終了リクエストを送ると、チームメンバーが承認（正常終了）するか説明と共に拒否できる。
チーム整理
Clean up the team
アクティブなチームメンバーが残っていると整理が失敗するため、まずすべてのチームメンバーを終了させる必要がある。常にリーダーを通じて整理すべきだ。 チームメンバーが整理を実行するとチームコンテキストが正しく解決されずリソースが不整合状態で残る可能性がある。
8. Subagent vs Agent Teams比較
| 項目 | Subagent | Agent Teams |
|---|---|---|
| コンテキスト | 自体のコンテキストウィンドウ、結果が呼び出し元に返される | 自体のコンテキストウィンドウ、完全に独立 |
| 通信 | メインエージェントにのみ結果報告 | チームメンバー同士で直接メッセージ交換 |
| 調整 | メインエージェントがすべてのタスク管理 | 共有タスクリストで自己調整 |
| 適したタスク | 結果だけが重要な集中タスク | 議論と協業が必要な複雑なタスク |
| トークンコスト | 低い：結果がメインコンテキストに要約返却 | 高い：各チームメンバーが別のClaudeインスタンス |
選択基準: 素早く集中した作業者が結果だけ報告すればいい場合はSubagent。チームメンバーが発見事項を共有し、互いに挑戦し、自体で調整する必要がある場合はAgent Teams。
9. 使用事例
適した使用事例
- リサーチおよびレビュー: 複数のチームメンバーが問題の異なる側面を同時に調査し、発見事項を共有して互いに挑戦
- 新モジュールまたは機能開発: チームメンバーがそれぞれ別のピースを所有して衝突なく作業
- 競合仮説を通じたデバッグ: チームメンバーが並列で異なる理論をテストしてより速く収束
- クロスレイヤー調整: フロントエンド、バックエンド、テストにまたがる変更を各チームメンバーが担当
適さない場合
順次タスク、同じファイル編集、依存性が多いタスクには単一セッションやSubagentがより効果的だ。
例：並列コードレビュー
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.
各レビューアーは同じPRを異なるフィルタで検討する。リーダーがすべてのレビューアーの結果を統合する。
例：競合仮説デバッグ
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.
議論構造が核心だ。順次調査はアンカリングバイアスに陥りやすいが、独立した調査者が互いの理論を反証しようとすると生き残る理論が実際の根本原因である可能性が遥かに高い。
10. トークンコストとコスト管理
コスト規模
Agent Teamsは通常セッション比で約7倍多くのトークンを使用する（チームメンバーがプランモードで実行される時基準）。各チームメンバーが自体のコンテキストウィンドウを維持し、別のClaudeインスタンスとして実行されるためだ。トークン使用量はアクティブなチームメンバー数と各チームメンバーの実行時間に比例する。
コスト削減戦略（公式推奨）
- チームメンバーにSonnetモデル使用: 調整作業に能力とコストのバランスが良い
- チームサイズを小さく維持: 各チームメンバーが自体のコンテキストウィンドウを運営するためトークン使用量がチームサイズに大体比例
- スポーンプロンプトを集中的に作成: チームメンバーはCLAUDE.md、MCPサーバー、skillsを自動ロードするが、スポーンプロンプトのすべての内容が初期コンテキストに追加される
- タスク完了後にチーム整理: アイドル状態のチームメンバーもアクティブ状態で引き続きトークンを消費
リサーチ、レビュー、新機能開発などでは追加トークンコストが通常は価値があるが、日常的なタスクには単一セッションがよりコスト効率的だ。
11. 制限事項
-
In-processチームメンバーのセッション再開不可:
/resumeと/rewindはin-processチームメンバーを復元しない。再開後にリーダーが存在しないチームメンバーにメッセージを送ろうとする可能性がある。この場合新しいチームメンバーのスポーンを指示 - タスク状態遅延: チームメンバーが時々タスクを完了にマークできず依存タスクがブロックされることがある。タスクが止まっている場合は実際の完了可否を確認して手動更新するかリーダーにチームメンバーを催促するよう指示
- 終了速度低下: チームメンバーが現在のリクエストやツールコールを完了してからのみ終了するため時間がかかることがある
- セッションあたり1チームのみ: 新チームを始めるには現在のチームを整理する必要がある
- ネストチーム不可: チームメンバーは自体でチームやチームメンバーを作成できない。リーダーのみチーム管理可能
- リーダー固定: チームを作成したセッションが生涯リーダー。チームメンバーをリーダーに昇格させたりリーダーシップを移転できない
- スポーン時権限設定制限: すべてのチームメンバーはリーダーの権限モードで開始。スポーン後に個別モード変更可能だが、スポーン時点でチームメンバー別モード設定不可
- Split pane制限: デフォルトin-processモードはすべてのターミナルで動作。Split-paneモードはVS Code統合ターミナル、Windows Terminal、Ghosttyで非対応
参考：チームメンバーは作業ディレクトリのCLAUDE.mdファイルを正常に読む。これを通じてすべてのチームメンバーにプロジェクト別ガイドを提供できる。
12. ベストプラクティス
チームメンバーに十分なコンテキスト提供
チームメンバーはCLAUDE.md、MCPサーバー、skillsを自動ロードするが、リーダーの会話履歴は継承しない。スポーンプロンプトにタスク別の詳細を含める：
Spawn a security reviewer teammate with the prompt: "Review the authentication module
at src/auth/ for security vulnerabilities. Focus on token handling, session
management, and input validation. The app uses JWT tokens stored in
httpOnly cookies. Report any issues with severity ratings."
適切なタスクサイズ
- 小さすぎると：調整オーバーヘッドが利点を超過
- 大きすぎると：チェックインなしに長時間作業してムダリスク増加
- 適切なサイズ：関数、テストファイル、レビューなど明確な成果物を生産する自己完結的な単位
リーダーが十分なタスクを作らない場合、タスクをより小さなピースに分割するようリクエストする。チームメンバーあたり5-6個のタスクがすべてを生産的に維持し、誰かが詰まったらリーダーがタスクを再割り当てできるようにする。
チームメンバー完了待機
リーダーがチームメンバーの代わるに直接実装を始める場合：
Wait for your teammates to complete their tasks before proceeding
リサーチとレビューから始める
初めてなら、コード作成が不要で境界が明確なタスクから始める：PRレビュー、ライブラリリサーチ、バグ調査など。並列探索の価値を示しながらも並列実装の調整課題は回避できる。
ファイル衝突防止
2人のチームメンバーが同じファイルを編集すると上書きが発生する。各チームメンバーが異なるファイルセットを所有するようにタスクを分割する。
モニタリングおよび調整
チームメンバーの進行状況を確認し、うまくいかないアプローチをリダイレクトし、結果が出るたびに統合する。チームを放置しすぎるとムダリスクが増加する。
13. トラブルシューティング
チームメンバーが現れない
- In-processモードでチームメンバーがすでに実行中だが見えない可能性がある。
Shift+Downで循環確認 - Claudeがタスクにチームが必要なほど複雑と判断したか確認
- Split panesをリクエストした場合tmuxがインストールされてPATHにあるか確認：
which tmux - iTerm2の場合
it2CLIがインストールされていて、iTerm2設定でPython APIが有効化されているか確認
権限プロンプトが多すぎる
チームメンバーの権限リクエストがリーダーに転送されて摩擦が生じることがある。チームメンバースポーン前に権限設定で一般的なタスクを事前承認する。
チームメンバーがエラーで停止
In-processモードでShift+Up/Downで出力を確認するか、Splitモードで該当ペインをクリックした後：
- 追加指示を直接伝えるか
- 代替チームメンバーをスポーンしてタスク継続
リーダーがタスク完了前に終了
リーダーがすべてのタスクが実際に完了する前に終了を決定することがある。続行するよう指示するか、委任せず直接タスクを始めたらチームメンバー完了を待つよう指示する。
孤児tmuxセッション
チーム終了後もtmuxセッションが残ることがある：
tmux ls
tmux kill-session -t <session-name>
14. 実際の大規模事例：Cコンパイラ構築
- 16個の並列Claudeエージェント使用
- LinuxカーネルをコンパイルできるRust基盤のCコンパイラ構築
- 約100,000行のコンパイラコード生成
- ほぼ2,000個のClaude Codeセッション
- 約20億入力トークン、1.4億出力トークン消費
- 総額約**$20,000** APIコスト
- 約2週間で進行
- GCC torture test suiteなどほとんどのコンパイラテストスイートで99%通過率
- QEMU、FFmpeg、SQLite、PostgreSQL、Redisをコンパイル可能
参考資料
Anthropic公式
- Orchestrate teams of Claude Code sessions
- Manage costs effectively - Agent team token costs
- Introducing Claude Opus 4.6