概要
Claude Codeのエージェントチーム (Agent Teams) は、複数のClaude Codeセッションを並列で調整・協働させるための実験的機能である。
現在はデフォルトで無効化されており、明示的に有効化する必要がある。
エージェントチームでは、1つのセッションが「リーダー」として機能し、複数の「チームメンバー」がそれぞれ独立したコンテキストウィンドウで並列に作業する。
チームメンバー同士が直接メッセージを交換でき、共有タスクリストから自動的に作業を割り当てることができる。
エージェントチームの主な特徴は以下の通りである。
- リーダー / メンバー構成
- 1つのリーダーセッションが複数のチームメンバーを統括する
- メンバー間直接通信
- チームメンバー同士がリーダーを経由せずに直接メッセージを交換できる
- 共有タスクリスト
- タスクリストをチームで共有し、メンバーが自動的にタスクをクレーミング (請求) して作業を進める
- 並列作業
- 複数のメンバーが異なるタスクを同時進行で実行できる
- プロジェクトコンテキストの継承
- チームメンバーはCLAUDE.md、MCPサーバ、スキルを自動で読み込む
サブエージェントとの主な違いとして、サブエージェントは結果のみをメインエージェントに返すのに対し、エージェントチームではメンバー同士が直接通信して協調作業を行う点が挙げられる。
複数エージェントが相互に検証・議論する必要がある複雑な作業に適している。
エージェントチームの有効化
エージェントチームは実験的機能のため、デフォルトでは無効化されている。
以下に示すいずれかの方法で有効化することができる。
方法 1 : 環境変数による有効化
ターミナルで以下の環境変数を設定する。
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
この設定は現在のシェルセッションにのみ有効である。
永続的に有効化する場合は、シェルの設定ファイル (~/.profileファイル等) に設定する。
方法 2 : settings.jsonによる有効化
Claude Codeの設定ファイル (settings.jsonファイル) に以下の内容を設定する。
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
設定ファイルの場所は以下の通りである。
- Linux
- ~/.config/claude/settings.json
- MacOS
- ~/Library/Application Support/claude/settings.json
- Windows
- %APPDATA%\claude\settings.json
表示モード
エージェントチームには、チームメンバーの表示方法として2つのモードが用意されている。
In-process モード (デフォルト)
全チームメンバーがメインターミナル内で実行されるモードである。
- 特別なセットアップが不要で、任意のターミナルで動作する。
- [Shift] + [Down]キーでチームメンバー間を切り替えられる。
- VS Code統合ターミナル、Windows Terminal、Ghosttyでも動作する。
Split-pane モード
各チームメンバーが独立したペインで表示されるモードである。
- 複数のメンバーの出力を同時に確認できる。
- 対象ペインをクリックして直接チームメンバーと対話できる。
- tmux または iTerm2 が必要
- VS Code統合ターミナル、Windows Terminal、Ghosttyでは非対応
モードの指定
モードはコマンドラインオプションで指定できる。
claude --teammate-mode in-process claude --teammate-mode tmux
設定ファイル (settings.json) では、teammateMode 項目で指定する。
- teammateMode
- チームメンバーの表示モードを指定する。
auto- 自動検出
- tmuxセッション内ならsplit-panes、それ以外はin-process
in-process- 全メンバーをメインターミナル内で実行
tmux
- split-paneモード (tmux または iTerm2を使用)
下表に、2つのモードの比較を示す。
| 項目 | In-processモード | Split-paneモード |
|---|---|---|
| セットアップ | 不要 | tmux または iTerm2が必要 |
| 表示方法 | メインターミナル内で切り替え | 独立したペインで同時表示 |
| メンバー切り替え | [Shift] + [Down]キー | ペインを選択 |
| 対応ターミナル | 任意のターミナル | tmux / iTerm2 のみ |
| デフォルト | あり | なし |
キーボードショートカット
下表に、エージェントチームで使用するキーボードショートカットを示す。
| ショートカット | 機能 | 備考 |
|---|---|---|
| [Shift] + [Down]キー | チームメンバーの切り替え | In-processモードで使用する。 次のチームメンバーに表示を切り替える。 |
| [Ctrl] + [T]キー | タスクリストの表示 / 非表示 | 共有タスクリストの一覧を表示する。 タスクの状態や依存関係を確認できる。 |
| [Esc]キー | リーダーセッションに戻る | チームメンバーの表示からリーダーに戻る。(In-processモード) |
フック (Hooks) 設定
エージェントチームでは、チームメンバーのライフサイクルイベントに対してフック (Hooks) を設定できる。
フックを使用することにより、特定のイベント発生時にカスタムコマンドを自動実行することが可能になる。
利用可能なフックイベント
下表に、エージェントチーム固有のフックイベントを示す。
| イベント名 | 発生タイミング | 用途の例 |
|---|---|---|
SubagentStart |
サブエージェント (チームメンバー) の開始時 | 環境セットアップスクリプトの実行、ログ記録の開始 |
SubagentStop |
サブエージェント (チームメンバー) の終了時 | クリーンアップ処理、結果の収集 |
TeammateIdle |
チームメンバーがアイドル状態になった時 | 次のタスクの割り当て通知、リソースの解放 |
TaskCompleted |
タスクが完了した時 | 完了通知の送信、依存タスクのトリガー |
フックの設定例
settings.json ファイルにフックを設定する例を以下に示す。
この例では、名前に"reviewer"を含むチームメンバーが開始された時に、セットアップスクリプトを実行する。
{
"hooks": {
"SubagentStart": [
{
"matcher": "reviewer",
"hooks": [
{
"type": "command",
"command": "./setup-reviewer.sh"
}
]
}
]
}
}
matcher フィールドを使用することにより、特定の名前パターンに一致するチームメンバーにのみフックを適用できる。
matcher を省略した場合は、全てのチームメンバーに対してフックが実行される。
使用方法
チームの作成
チームの作成は、リーダーセッションに対して自然言語で指示するだけでよい。
リーダーが自動的にチームを編成して、チームメンバーを生成する。
チームメンバーへの指示として、以下に示すような情報を含めることができる。
- チームメンバー数の指定
- "4人のチームメンバーでこれらのモジュールを並列にリファクタリングして。"
- 使用するモデルの指定
- "各チームメンバーにSonnetを使って。"
- プラン承認の要求
- "変更を行う前にプランの承認を必須にして。"
チーム作成のプロンプト例を以下に示す。
# 例 1 : 異なる視点からの検討 異なる角度からこの問題を検討するエージェントチームを作成して。 UX担当、技術アーキテクチャ担当、反対意見を述べる役割のチームメンバーをそれぞれ1人ずつ。 # 例 2 : 並列コードレビュー PR #142をレビューするエージェントチームを作成して。3人のレビュアーを生成: - 1人目はセキュリティへの影響に注力 - 2人目はパフォーマンスへの影響を確認 - 3人目はテストカバレッジを検証
チームメンバーとの対話
エージェントチームでは、リーダーとチームメンバー間、およびチームメンバー同士の通信にメールボックスシステムが使用される。
各チームメンバーは独立したメールボックスを持ち、他のメンバーやリーダーからのメッセージを受信できる。
表示モードに応じて、以下の方法でチームメンバーに直接メッセージを送ることができる。
- In-process モードの場合
- [Shift] + [Down]キーで対象チームメンバーに移動してメッセージを入力する。
- [Esc]キーでリーダーセッションに戻ることができる。
- Split-pane モードの場合
- 対象ペインをクリックして直接入力する。
- 複数のメンバーの出力を同時に確認しながら作業できる。
リーダーから特定のチームメンバーに対して指示を送る場合のプロンプト例を以下に示す。
# 特定のチームメンバーにメッセージを送信 セキュリティレビュアーにSQLインジェクションの脆弱性もチェックするよう伝えて。 # チームメンバーの作業方針を変更 フロントエンド担当のチームメンバーに、コンポーネントをReactからVue.jsに切り替えるよう伝えて。 # 全チームメンバーへの一斉指示 全チームメンバーに現在の作業を中断して、認証の重大バグに集中するよう指示して。
タスク管理
エージェントチームには共有タスクリストによるタスク管理機能が備わっている。
リーダーがタスクを作成して、チームメンバーが自律的にタスクを取得して作業を進める仕組みとなっている。
タスク管理の基本的な流れは以下の通りである。
- リーダーが新しいタスクを作成し、共有タスクリストに追加する。
- チームメンバーが未割り当てのタスクを自動的にクレーミング (請求) する。
- チームメンバーが担当タスクを実行し、完了時にタスクを完了済みとしてマークする。
- 完了済みタスクに依存する後続タスクが自動的にアンロックされ、他のメンバーが取得可能になる。
下表に、タスクの状態遷移を示す。
| 状態 | 説明 |
|---|---|
| 未割り当て (Unassigned) | リーダーが作成した直後の状態 チームメンバーがクレーミング可能 |
| 進行中 (In Progress) | チームメンバーがクレーミングして作業中の状態 |
| 完了 (Completed) | チームメンバーが作業を完了した状態 依存タスクのアンロックをトリガーする。 |
| ブロック (Blocked) | 依存する先行タスクが未完了のため、まだクレーミングできない状態 |
[Ctrl] + [T]キーでタスクリストの表示 / 非表示を切り替えられる。
タスクリストでは、各タスクの状態、担当メンバー、依存関係を一覧で確認できる。
チームメンバーのシャットダウン
特定のチームメンバーをシャットダウンする場合は、リーダーを通じて指示する。
チームメンバーは承認して正常終了するほか、シャットダウンを拒否することもできる。
リサーチ担当のチームメンバーをシャットダウンして
チームのクリーンアップ
チームの使用が終わったら、以下の指示でリソースをクリーンアップする。
チームをクリーンアップして
クリーンアップはリーダーのみが実行すること。
チームメンバーがクリーンアップを実行すると、リソースが不完全な状態で残る可能性がある。
ユースケース
並列コードレビュー
単一レビュアーでは一度に1種類の問題に焦点を当てがちだが、複数のレビュアーが異なる観点から同時に検証することにより、より包括的なレビューを実現できる。
チームメンバーの役割分担例を以下に示す。
- セキュリティレビュアー
- セキュリティ影響、トークン処理、認証メカニズムを検査する。
- パフォーマンスレビュアー
- パフォーマンス影響、リソース使用効率を検査する。
- テストカバレッジレビュアー
- テストの網羅性、テスト品質を検査する。
プロンプト例を以下に示す。
PR #142をレビューするエージェントチームを作成して。3人のレビュアーを生成: - 1人目はセキュリティへの影響に注力 (トークン処理、認証、入力バリデーション) - 2人目はパフォーマンスへの影響を確認 (クエリ効率、メモリ使用量、キャッシュ) - 3人目はテストカバレッジを検証 (エッジケース、エラーパス、統合テスト) 各レビュアーに重要度評価付きの構造化されたレポートを作成させて。
競合仮説による調査
根本原因が不明な問題に対して、複数のチームメンバーが異なる仮説を同時に検証する手法である。
各チームメンバーが独立した仮説を検証しながら、科学的な討論のように互いの理論に反論し合うことで、より確実な根本原因の特定が可能になる。
プロンプト例を以下に示す。
ユーザから、アプリが接続を維持せず1つのメッセージ送信後に終了するとの報告がある。 5人のエージェントチームメンバーを生成して、異なる仮説を調査して: - WebSocket接続のライフサイクル - セッションタイムアウトの設定 - メモリリークによるクラッシュ - 認証トークンの有効期限切れ - フロントエンドのイベントハンドラのバグ 互いの理論を反証するように、科学的な討論のようにチームメンバー間で議論させて。
並列モジュール開発
複数のチームメンバーが異なるモジュールを並列開発することで、開発速度を向上できる。
各チームメンバーが異なるファイルセットを担当するように分割することが重要である。
担当の分割例を以下に示す。
- チームメンバー A
- フロントエンドコンポーネントの開発 (src/components/ ディレクトリ配下)
- チームメンバー B
- バックエンドAPIの開発 (src/api/ ディレクトリ配下)
- チームメンバー C
- テストスイートの作成 (tests/ ディレクトリ配下)
- チームメンバー D
- データベースマイグレーションとモデルの作成 (src/models/ ディレクトリ配下)
プロンプト例を以下に示す。
ユーザダッシュボード機能を構築する4人のチームを作成して: - フロントエンド: src/components/dashboard/ にReactコンポーネントを構築 - バックエンド: src/api/dashboard/ にREST APIエンドポイントを作成 - データベース: src/models/ にマイグレーションとモデルを作成 - テスト: tests/dashboard/ にユニットテストと統合テストを作成 各チームメンバーが担当ディレクトリを所有する。APIの契約を相互に調整して。
クロスレイヤー調整
複数のレイヤーにまたがる変更を並列で実装する際に有効である。
フロントエンド、バックエンド、テストをそれぞれ異なるチームメンバーが担当して、定期的に相互確認しながら作業を進める。
例えば、認証システムの刷新のように、フロントエンドのログインフォーム、バックエンドの認証ロジック、データベースのスキーマ変更、テストの更新を同時に進める場合に有効である。
チームメンバー間で直接メッセージを交換してAPIの契約を確認し合うことで、各レイヤーの整合性を保つことができる。
データ分析の並列調査
複数のチームメンバーが異なる角度からデータやコードベースを分析する場合にも有効である。
プロンプト例を以下に示す。
認証、データベース、APIモジュールを別々のチームメンバーで並列調査して。 各チームメンバーは以下を実施すること: - 現在のアーキテクチャを文書化 - 技術的負債を特定 - 改善案を提案 その後、互いの調査結果をクロスレビューさせて。
サブエージェントとの比較
エージェントチームとサブエージェントは、いずれも並列作業を実現する機能だが、用途と特性が異なる。
| 項目 | サブエージェント | エージェントチーム |
|---|---|---|
| コンテキスト | 独立したコンテキストウィンドウを持ち、結果がメインエージェントに返される。 | 独立したコンテキストウィンドウを持ち、完全に独立して動作する。 |
| 通信方法 | メインエージェントにのみ結果をレポートする。 エージェント間通信なし |
チームメンバー同士が直接メッセージを交換する。 リーダーを経由しない。 |
| 作業調整 | メインエージェントが全作業を管理する。 | 共有タスクリストで自己調整する。 チームメンバーが自動的にタスクをクレーミングする。 |
| 最適な用途 | 結果のみが重要な焦点を絞ったタスク | 議論と協働が必要な複雑な作業 |
| トークンコスト | 低い。結果がメインコンテキストに要約されて返される。 | 高い。 各チームメンバーが独立したClaudeインスタンスを消費する。 |
使い分けの指針を以下に示す。
- サブエージェントを推奨する場合
- 実行時間が短い焦点を絞った作業
- 結果の要約が必要な場合
- トークンコストを最小化したい場合
- エージェントチームを推奨する場合
- 複数エージェントが相互に検証・議論する必要がある場合
- 長期にわたる並列研究・開発
- 複数のモジュール / レイヤーでの並列作業
- 個別のチームメンバーと対話しながら進める必要がある場合
推奨される事柄
エージェントチームを効果的に活用するための推奨される事柄を以下に示す。
研究・レビューから開始
エージェントチームの使用に慣れていない場合は、まず、ソースコードの記述を伴わないタスクから始めることを推奨する。
以下に示すような用途は、明確な境界があり並列化の効果を実感しやすい。
- PRレビュー (複数の観点からの検証)
- ライブラリの調査 (候補の比較検討)
- バグの原因調査 (複数仮説の並列検証)
- コードベースのドキュメント作成 (モジュール別の分担)
これらのタスクは並列探索の価値を実感しながら、並列実装で発生しやすいファイルコンフリクト等の調整課題を回避できるため、段階的な導入に適している。
コンテキストの提供
チームメンバーはプロジェクトコンテキスト (CLAUDE.md、MCPサーバ、スキル) を自動で読み込むが、リーダーの会話履歴は継承しない。
そのため、スポーン (生成) 時のプロンプトにタスク固有の詳細を含めることが重要である。
セキュリティレビュアーのチームメンバーを以下のプロンプトで生成して: 'src/auth/ の認証モジュールにセキュリティの脆弱性がないかレビューして。 トークン処理、セッション管理、入力バリデーションに注力すること。 アプリはhttpOnly cookieに保存されたJWTトークンを使用している。 重要度評価付きで問題を報告して。'
チームサイズの選択
適切なチームサイズの選択がコスト効率と生産性に大きく影響する。
- トークンコストはチームメンバー数に線形にスケールする。
- チームメンバー数が増えると通信・調整のオーバーヘッドも増加する。
- ある規模を超えるとチームメンバー追加による効率向上が鈍化する。(収穫逓減)
- 推奨サイズ: 大多数のワークフローには3から5チームメンバーが適切
- 比率の目安: チームメンバーあたり5から6タスク程度が生産性を維持できる。
タスクサイズの最適化
チームメンバーに割り当てるタスクのサイズは、作業効率に大きく影響する。
- 小さすぎるタスク
- 調整オーバーヘッドがタスクの実行時間を上回り、非効率になる。
- 大きすぎるタスク
- チェックイン間隔が長くなり、方向性の誤りに早期に気づけないリスクがある。
- 適切なサイズ
- 1つの関数、1つのテストファイル、1つのコンポーネント等、自己完結型の作業単位が望ましい。
例えば、15個の独立したタスクがある場合、5チームメンバーに3タスクずつ分配するよりも、3チームメンバーに5タスクずつ分配する方が効率的な場合が多い。
ファイルコンフリクトの回避
各チームメンバーが異なるファイルセットを担当するように作業を分割すること。
同一ファイルへの複数エージェントによる同時編集は、変更のオーバーライトを招く可能性がある。
ファイルコンフリクトを防ぐための具体的な方策を以下に示す。
- ディレクトリ単位でチームメンバーの担当範囲を明確に分ける。
- 共有ファイル (設定ファイル、型定義ファイル等) の編集は1人のチームメンバーに集約する。
- APIの契約 (インターフェース定義) は事前に合意しておき、実装を並行して進める。
チームの監視とステアリング
チームを長時間無人にするのは避けること。
以下の点を定期的に確認して、チームの作業方向を適切に調整することを推奨する。
- チームメンバーの進捗確認
- 機能しない手法を発見した場合のリダイレクト
- 各チームメンバーの知見の統合
制限事項
エージェントチームには現在いくつかの既知の制限がある。
| 制限事項 | 詳細 |
|---|---|
| セッション再開に非対応 | /resume および /rewind コマンドでin-processチームメンバーを復元できない。再開後、リーダーが存在しないチームメンバーへのメッセージを試みる可能性がある。 |
| タスク状態のラグ | チームメンバーがタスク完了マークを忘れることがあり、依存タスクがブロック状態のままになる可能性がある。 |
| シャットダウンの遅延 | チームメンバーは現在処理中のリクエストやツール呼び出しが完了するまでシャットダウンしない。 |
| 1セッションにつき1チーム | リーダーは同時に1つのチームのみ管理できる。 |
| ネストされたチームなし | チームメンバーは独自のチームやチームメンバーを生成できない。 リーダーのみがチーム管理可能 |
| リーダーは固定 | チームを作成したセッションはそのライフタイムを通じてリーダーとなる。 リーダーシップを移譲することはできない。 |
| 権限はスポーン時に設定 | 全チームメンバーはリーダーの権限モードで開始する。 スポーン後に個別チームメンバーの権限モードを変更することは可能だが、スポーン時には設定できない。 |
| Split-paneのターミナル制限 | Split-paneモードは、tmux または iTerm2が必須 VS Code統合ターミナル、Windows Terminal、Ghosttyでは非対応 |
トークンコストについて
エージェントチームはサブエージェントと比較してトークンコストが高くなる。
- 各チームメンバーが独立したコンテキストウィンドウを持つため、トークン使用量がアクティブなチームメンバー数に線形に比例する。
- 研究、レビュー、新機能開発など複雑な作業では、トークンコストの増加に対してそれ以上の価値が得られることが多い。
- ルーチン作業や単純なタスクでは、単一セッションの方が費用対効果が高い場合がある。
CLAUDE.mdとの関係
エージェントチームにおけるCLAUDE.mdファイルの扱いは以下の通りである。
- チームメンバーは自分の作業ディレクトリからCLAUDE.mdファイルを自動的に読み込む。
- プロジェクト固有のルールやガイドラインをCLAUDE.mdに記載しておくことにより、全チームメンバーに統一的な指示を提供できる。
- チームメンバーはリーダーの会話履歴を継承しないが、CLAUDE.mdの内容は共有される。
下表に、チームメンバーが継承するプロジェクトコンテキストと継承しない情報を示す。
| 情報 | 継承の有無 | 備考 |
|---|---|---|
| CLAUDE.md | 継承する | 作業ディレクトリのCLAUDE.mdを自動読み込み |
| MCPサーバ設定 | 継承する | プロジェクト設定のMCPサーバを利用可能 |
| スキル定義 | 継承する | プロジェクトのスキルを利用可能 |
| リーダーの会話履歴 | 継承しない | スポーン時のプロンプトでタスク固有の情報を明示的に提供する必要がある。 |
| リーダーの権限モード | 継承する | スポーン時にリーダーと同じ権限モードで開始する。 |
CLAUDE.mdにエージェントチーム向けの指示を記載する場合は、各チームメンバーの役割や担当範囲に関する一般的なガイドラインを含めると効果的である。
関連リンク
- Claude Code公式ドキュメント - Agent Teams
- Claude Codeの設定 - サブエージェント
- Claude Codeの設定 - 環境変数
- Claude Codeの設定 - CLAUDE.md