AI
エージェントはじめに
Claude Codeには、複数のClaude Codeインスタンスをチームとして連携させる「エージェントチーム」機能がある。1つのセッションがリーダーとして機能し、複数のチームメイトに作業を割り当て、チームメイト同士が直接コミュニケーションしながら並列で作業を進める仕組みである。
本記事では、エージェントチームの設定方法、subagentとの違い、ユースケース、ベストプラクティスについてまとめる。
なお、エージェントチームは実験的機能であり、デフォルトでは無効になっている。
エージェントチームのアーキテクチャ
エージェントチームは以下の4つのコンポーネントで構成される。
| コンポーネント | 役割 |
|---|---|
| チームリーダー | チームを作成し、チームメイトを生成・調整するメインセッション |
| チームメイト | 割り当てられたタスクを実行する個別のClaude Codeインスタンス |
| タスクリスト | チームメイトが要求・完了する共有作業項目リスト |
| メールボックス | エージェント間の通信用メッセージングシステム |
各チームメイトは独自のコンテキストウィンドウを持ち、完全に独立して動作する。リーダーの会話履歴は引き継がれないが、CLAUDE.md、MCPサーバー、スキルなどのプロジェクトコンテキストは自動的にロードされる。
subagentとの違い
Claude Codeには「subagent（Taskツール）」と「エージェントチーム」の2つの並列化手段がある。核心的な違いはチームメイト同士が直接会話できるかどうかである。
| 項目 | subagent | エージェントチーム |
|---|---|---|
| コンテキスト | 独自ウィンドウ。結果は呼び出し元に返却 | 独自ウィンドウ。完全に独立 |
| 通信 | メインエージェントにのみ報告 | チームメイト間で直接メッセージ送信可能 |
| 調整 | メインエージェントが全作業を管理 | 共有タスクリストによる自己調整 |
| 最適な用途 | 結果のみが重要な焦点を絞ったタスク | 議論と協力が必要な複雑な作業 |
| トークンコスト | 低い（結果がメインコンテキストに要約） | 高い（各チームメイトが個別インスタンス） |
選択の指針:
- 「答えだけ返してくれればいい」→ subagent
- 「議論・反論・協力が価値を生む」→ エージェントチーム
設定方法
環境変数の有効化
~/.claude/settings.json に以下を追加する。
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
設定後、Claude Codeのセッションを再起動すると有効になる。
表示モードの選択
エージェントチームは2つの表示モードをサポートしている。
| モード | 説明 | 要件 |
|---|---|---|
| in-process | 全チームメイトがメインターミナル内で実行 | なし（デフォルト） |
| 分割ペイン | 各チームメイトが独自のペインを取得 | tmuxまたはiTerm2 |
デフォルトは auto（tmuxセッション内なら分割ペイン、そうでなければin-process）。CLIフラグで明示指定も可能。
claude --teammate-mode in-process
使い方
チームの作成
自然言語でチーム作成を指示する。チームメイトの人数はClaude が自動判断するが、明示指定も可能。
このPRをレビューして。エージェントチームを作って：
- セキュリティ観点のレビュアー
- パフォーマンス観点のレビュアー
- テストカバレッジ観点のレビュアー
人数とモデルを明示する場合：
4人のチームメイトでこのモジュールを並列リファクタリングして。
各チームメイトにはSonnetを使って
チームメイトとの直接対話
- in-processモード:
Shift+Downでチームメイトを切替、メッセージを入力 - 分割ペインモード: チームメイトのペインをクリック
主な操作キー
| 操作 | キー |
|---|---|
| チームメイト切替 | Shift+Down |
| タスクリスト表示 | Ctrl+T |
| チームメイトの中断 | Escape |
| チームメイトのセッション表示 | Enter |
プラン承認の要求
複雑な作業では、チームメイトに実装前のプラン承認を要求できる。
認証モジュールのリファクタリング担当のチームメイトを作って。
変更前にプラン承認を必須にして
チームのクリーンアップ
作業完了後は必ずリーダーからクリーンアップを実行する。
チームメイトをシャットダウンして
チームをクリーンアップして
ユースケース
1. 並列コードレビュー
レビュー基準を独立したドメインに分割し、セキュリティ・パフォーマンス・テストカバレッジを同時に検証する。
PR #142をレビューするエージェントチームを作って。
- セキュリティの影響を重点的に見るレビュアー
- パフォーマンスの影響をチェックするレビュアー
- テストカバレッジを検証するレビュアー
それぞれレビュー後に発見を報告させて
2. 競合仮説でのデバッグ
原因不明のバグに対して異なる仮説を並列検証し、互いに反論させることで精度を高める。
アプリが1メッセージ後に切断される問題を調査して。
5人のチームメイトで異なる仮説を検証し、
科学的議論のように互いの理論に反論させて。
合意が得られた内容をドキュメントに記録して
3. 大規模リファクタリング
モジュールやレイヤーごとに担当を分割し、独立して並列作業する。ただし同じファイルを複数のチームメイトが編集しないよう注意が必要。
認証システムをリファクタリングして。エージェントチームを作って：
- フロントエンドのauth関連コンポーネント担当
- バックエンドのAPI/ミドルウェア担当
- テストの書き直し担当
4. クロスレイヤー調整
フロントエンド、バックエンド、テストにまたがる変更を、各チームメイトが異なるレイヤーを担当して進める。インターフェースの変更があれば直接やり取りして調整できるのがsubagentとの違い。
ベストプラクティス
チームサイズ
- 推奨は3〜5人
- チームメイトあたり5〜6個のタスクが目安
- 3人の焦点を絞ったチームメイトが、5人の散漫なチームメイトを上回ることが多い
タスクの粒度
| サイズ | 問題 |
|---|---|
| 小さすぎる | 調整オーバーヘッドが利益を超える |
| 大きすぎる | チェックインなしで長時間動作し、無駄な努力のリスク増加 |
| 適切 | 関数、テストファイル、レビューなど明確な成果物を生成する自己完結型ユニット |
ファイル競合の回避
2人のチームメイトが同じファイルを編集すると上書きが発生する。各チームメイトが異なるファイルセットを担当するよう作業を分割する。
監視とステアリング
チームを長時間無人で実行させない。進捗をチェックし、機能していないアプローチはリダイレクトする。
hooksによる品質ゲート
hooksを使ってチームメイトの作業完了時にルールを強制できる。
TeammateIdle: チームメイトがアイドル状態になる際に実行。終了コード2でフィードバックを送り作業を継続させるTaskCompleted: タスク完了時に実行。終了コード2で完了を防止しフィードバックを送る
制限事項
- in-processチームメイトはセッション再開（
/resume、/rewind）で復元されない - タスクステータスの更新が遅延する場合がある
- シャットダウンに時間がかかることがある（現在のツール呼び出し完了を待つため）
- セッションあたり1つのチームのみ
- チームのネストは不可（チームメイトは独自のチームを作れない）
- リーダーは固定（譲渡不可）
- 分割ペインモードはVS Code統合ターミナル、Windows Terminal、Ghosttyでは非サポート
まとめ
エージェントチームは、subagentでは対応しきれない「議論・協力・自己調整」が必要な複雑なタスクに有効な機能である。特に並列コードレビュー、競合仮説でのデバッグ、クロスレイヤーのリファクタリングなどで威力を発揮する。
一方で、トークンコストがチームメイト数に比例して増加するため、ルーチンタスクや順序依存の作業には向かない。subagentとの使い分けを意識し、並列探索が実際に価値を追加する場面で活用するのが良い。
