はじめに
Claude Code v2.1.32 で正式に実験的機能として搭載された Agent Teams は、複数の Claude Code インスタンスをチームとして協調動作させる仕組みです。コードレビュー・バグ調査・新機能開発など、並列探索によって価値が生まれるタスクを大幅に高速化できます。
この記事では、公式ドキュメントをもとに Agent Teams の設計思想・セットアップ・実践的な使い方をまとめます。
この記事で学べること
- Agent Teams と Subagents の違い・使い分け
-
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMSの有効化手順 - チームの作成・タスク管理・コミュニケーションの仕組み
- コードレビュー・デバッグへの応用
- ベストプラクティスと現在の制限事項
対象読者
- Claude Code を日常的に使っている開発者
- マルチエージェント設計に興味があるエンジニア
- 大規模コードベースでの AI 活用を検討している方
前提環境
- Claude Code v2.1.32 以降（
claude --versionで確認） - macOS / Linux（Windows は in-process モードのみ対応）
TL;DR
- Agent Teams は複数 Claude インスタンスをチームとして並列実行できる 実験的機能（デフォルト無効）
-
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1を設定して有効化 - チームメイトは 独立したコンテキストウィンドウ を持ち、共有タスクリストとメッセージで協調
- コードレビュー・並列デバッグ・新機能の並列実装に効果的
- チームサイズは 3〜5人 が推奨（トークンコストは人数分スケール）
Agent Teams vs Subagents — どちらを使うか
Agent Teams を理解するには、既存の Subagents との違いを把握することが重要です。
Subagents（既存の仕組み）
- メインエージェントが管理するワーカー
- 結果をメインエージェントへ一方的に報告
- チームメイト同士の直接通信は不可
- 向いている用途: 結果のみ必要な集中型タスク
Agent Teams（新しい仕組み）
- チームメイトが独立したセッションとして動作
- 共有タスクリストで自己調整（Self-coordination）
- チームメイト同士が直接メッセージ交換可能
- 向いている用途: 議論・検証・協調が必要な複雑なタスク
| 項目 | Subagents | Agent Teams |
|---|---|---|
| コンテキスト | 独立（結果はメインに返す） | 独立（完全に自律） |
| 通信 | メインのみへ報告 | チームメイト間で直接通信 |
| 調整 | メインが全管理 | 共有タスクリストで自律調整 |
| トークンコスト | 低（結果を要約して返す） | 高（各チームメイトが独立インスタンス） |
| 最適用途 | 結果のみ重要な集中タスク | 議論・検証が必要な複雑作業 |
セットアップ
1. バージョン確認
claude --version
# v2.1.32 以降が必要
2. Agent Teams を有効化
~/.claude/settings.json に以下を追加します：
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
または、環境変数で一時的に有効化：
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude
3. 表示モードの設定（任意）
Agent Teams は 2 つの表示モードをサポートします：
-
in-process（デフォルト）: チームメイトはメインターミナル内で動作。
Shift+Downで切り替え - split panes: tmux / iTerm2 で各チームメイトが独立ペインに表示
tmux を使う場合は settings.json に追加：
{
"teammateMode": "tmux"
}
または起動オプションで指定：
claude --teammate-mode in-process
チームの作成と基本操作
チームの作成
自然言語でチーム構成とタスクを指示するだけです。YAML ファイルや設定ファイルは不要です：
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.
Claude がチームを作成し、チームメイトを生成して作業を調整します。
チームメイトとの通信
-
in-process モード:
Shift+Downでチームメイトを順に切り替えてメッセージ入力 - split panes モード: ペインをクリックして直接操作
-
Ctrl+Tでタスクリストをトグル表示
タスクの管理
共有タスクリストは ~/.claude/tasks/{team-name}/ に保存されます。タスクには3つのステータスがあります：
| ステータス | 説明 |
|---|---|
| pending | 未着手（依存タスクが完了するまでクレーム不可） |
| in progress | 作業中（ファイルロックで競合防止） |
| completed | 完了 |
チームメイトはタスク完了後、次の未着手・未ブロックタスクを自動的に引き受けます。
チームの終了
Clean up the team
チームのリソースを削除します。アクティブなチームメイトがいる場合は先にシャットダウンが必要です。
実践的なユースケース
ユースケース 1: 並列コードレビュー
レビュアーが複数の観点（セキュリティ・パフォーマンス・テストカバレッジ）で同時にレビューします：
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.
1人のレビュアーだと特定の種類の問題に偏りがちですが、並列で異なる観点から調査することで、見落としを防げます。
ユースケース 2: 競合仮説によるデバッグ
原因不明のバグを複数の仮説で並列調査します：
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.
チームメイトが互いの仮説を検証し反論し合う構造により、逐次調査よりも正確な原因特定が期待できます。
ユースケース 3: 新機能の並列実装
フロントエンド・バックエンド・テストを各担当者が並列で実装します：
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.
承認基準をリードに指示できます：
Only approve plans that include test coverage.
Reject plans that modify the database schema.
Subagent 定義の再利用
.claude/agents/ のサブエージェント定義をチームメイトとして参照できます：
Spawn a teammate using the security-reviewer agent type to audit the auth module.
これにより、再利用可能な専門ロールを定義してチームに組み込めます。
フックによる品質ゲート
hooks を使ってチームの品質を自動管理できます。~/.claude/settings.json に設定：
{
"hooks": {
"TeammateIdle": [
{
"hooks": [
{
"type": "command",
"command": "echo '品質チェックを実行してください'"
}
]
}
],
"TaskCompleted": [
{
"hooks": [
{
"type": "command",
"command": "/path/to/quality-check.sh"
}
]
}
]
}
}
利用可能なフックイベント：
| フック | タイミング | exit 2 の効果 |
|---|---|---|
TeammateIdle |
チームメイトがアイドル状態になる前 | フィードバックを送りアイドルを防止 |
TaskCreated |
タスクが作成される前 | タスクの作成を却下 |
TaskCompleted |
タスクが完了とマークされる前 | 完了を阻止してフィードバックを送信 |
ベストプラクティス
チームサイズは 3〜5 人が最適
| 観点 | 推奨 |
|---|---|
| チームサイズ | 3〜5 人が標準。それ以上は調整オーバーヘッドが増大 |
| タスク数/人 | 5〜6 タスクが生産的 |
| タスクサイズ | 小さすぎず大きすぎず（関数・テストファイル・レビュー単位が目安） |
トークンコストは人数分線形にスケールするため、必要以上に大きなチームは避けてください。
ファイル競合を防ぐ
2 人のチームメイトが同一ファイルを編集すると上書きが発生します。各チームメイトが異なるファイルセットを担当する ように設計することが重要です。
スポーン時に十分なコンテキストを提供
チームメイトはリードの会話履歴を継承しません。スポーン指示に必要な情報を含めます：
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."
CLAUDE.md を活用
チームメイトは作業ディレクトリの CLAUDE.md を自動で読み込みます。プロジェクト固有のガイドラインを記載しておくことで、全チームメイトに共通のコンテキストを提供できます。
現在の制限事項
Agent Teams は実験的機能のため、以下の制限があります（2026年5月時点）：
| 制限 | 詳細 |
|---|---|
| セッション再開不可 |
/resume や /rewind は in-process チームメイトを復元しない |
| タスクステータスの遅延 | 完了マーク忘れで依存タスクがブロックされる場合がある |
| シャットダウンが遅い | 現在のリクエスト完了まで待機が必要 |
| 1セッション1チームのみ | リードは同時に1チームのみ管理可能 |
| ネストしたチーム不可 | チームメイトが自分のチームを作ることはできない |
| Split panes 制限 | VS Code 統合ターミナル・Windows Terminal・Ghostty では動作しない |
| 権限変更のタイミング | スポーン後に個別変更は可能だが、スポーン時には設定できない |
まとめ
Claude Code Agent Teams は、複数の Claude インスタンスを協調動作させることで、並列探索の価値が高いタスクを効率化する実験的機能です。
主なポイント:
-
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1で有効化（v2.1.32 以降） - コードレビュー・デバッグ・並列実装に最適
- チームサイズは 3〜5 人が推奨
- 各チームメイトは独立したコンテキストを持ち、共有タスクリストで自律調整
- フックで品質ゲートを自動化可能
現状は実験的機能でいくつかの制限がありますが、大規模コードベースでの並列作業の可能性を試す価値は十分にあります。