Claude Code セッションのチームを調整する
複数の Claude Code インスタンスがチームとして連携して動作するように調整し、共有タスク、エージェント間メッセージング、および一元管理を実現します。
エージェントチームを使用すると、複数の Claude Code インスタンスが連携して動作するように調整できます。1 つのセッションがチームリーダーとして機能し、作業を調整し、タスクを割り当て、結果を統合します。チームメンバーは独立して動作し、それぞれ独自のコンテキストウィンドウで動作し、互いに直接通信します。
subagents（単一セッション内で実行され、メインエージェントにのみ報告できる）とは異なり、リーダーを経由せずに個別のチームメンバーと直接対話することもできます。
このページでは、以下について説明します。
- エージェントチームを使用する場合（ユースケースと subagents との比較を含む）
- チームを開始する
- チームメンバーを制御する（表示モード、タスク割り当て、委任を含む）
- 並列作業のベストプラクティス
エージェントチームを使用する場合
エージェントチームは、並列探索が実際の価値を追加するタスクに最も効果的です。完全なシナリオについては、ユースケース例を参照してください。最も強力なユースケースは以下の通りです。
- 調査とレビュー：複数のチームメンバーが問題のさまざまな側面を同時に調査し、その後、各自の調査結果を共有して相互に検証できます
- 新しいモジュールまたは機能：チームメンバーが互いに干渉することなく、それぞれ別々の部分を担当できます
- 競合する仮説でのデバッグ：チームメンバーが異なる理論を並列でテストし、より迅速に答えに収束できます
- クロスレイヤー調整：フロントエンド、バックエンド、テストにまたがる変更で、それぞれ異なるチームメンバーが担当します
エージェントチームは調整オーバーヘッドを追加し、単一セッションよりも大幅に多くのトークンを使用します。チームメンバーが独立して動作できる場合に最も効果的です。順序付きタスク、同じファイルの編集、または多くの依存関係を持つ作業の場合は、単一セッションまたは subagents がより効果的です。
subagents との比較
エージェントチームと subagents の両方を使用すると、作業を並列化できますが、動作方法が異なります。ワーカーが互いに通信する必要があるかどうかに基づいて選択してください。
| Subagents | エージェントチーム | |
|---|---|---|
| コンテキスト | 独自のコンテキストウィンドウ。結果は呼び出し元に返される | 独自のコンテキストウィンドウ。完全に独立 |
| 通信 | メインエージェントにのみ結果を報告 | チームメンバーが互いに直接メッセージを送信 |
| 調整 | メインエージェントがすべての作業を管理 | 自己調整を伴う共有タスクリスト |
| 最適な用途 | 結果のみが重要な焦点を絞ったタスク | 議論と協力が必要な複雑な作業 |
| トークンコスト | 低い：結果がメインコンテキストに要約されて返される | 高い：各チームメンバーが個別の Claude インスタンス |
結果を報告する必要がある迅速で焦点を絞ったワーカーが必要な場合は subagents を使用してください。チームメンバーが調査結果を共有し、互いに検証し、独立して調整する必要がある場合は、エージェントチームを使用してください。
エージェントチームを有効にする
エージェントチームはデフォルトでは無効になっています。CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 環境変数を 1 に設定して有効にしてください。シェル環境または settings.json を通じて設定できます。
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
最初のエージェントチームを開始する
エージェントチームを有効にした後、実行したいタスクとチームメンバーを自然言語で説明してください。Claude がチームメンバーを生成し、プロンプトに基づいて作業を調整します。
この例は、3 つの役割が独立しており、互いに待つことなく問題を探索できるため、うまく機能します。
I'm designing a CLI tool that helps developers track TODO comments across
their codebase. Spawn three teammates to explore this from different angles:
one on UX, one on technical architecture, one playing devil's advocate.
その後、Claude は 共有タスクリスト を作成し、各視点のチームメンバーを生成し、問題を探索させ、完了時に調査結果を統合します。
リーダーのターミナルには、すべてのチームメンバーと彼らが取り組んでいる内容が表示されます。Shift+Down を使用してチームメンバーをサイクルして、直接メッセージを送信してください。最後のチームメンバーの後、Shift+Down はリーダーに戻ります。
各チームメンバーを独自の分割ペインに配置したい場合は、表示モードを選択を参照してください。
エージェントチームを制御する
リーダーに自然言語で実行したい内容を指示してください。チーム調整、タスク割り当て、および指示に基づいた委任を処理します。
表示モードを選択する
エージェントチームは 2 つの表示モードをサポートしています。
- In-process：すべてのチームメンバーがメインターミナル内で実行されます。Shift+Down を使用してチームメンバーをサイクルして、直接メッセージを入力してください。追加のセットアップなしで任意のターミナルで動作します。
- 分割ペイン：各チームメンバーが独自のペインを取得します。すべてのユーザーの出力を一度に表示でき、ペインをクリックして直接対話できます。tmux または iTerm2 が必要です。
デフォルトは "auto" で、既に tmux セッション内で実行している場合は分割ペインを使用し、そうでない場合は in-process を使用します。"tmux" 設定は分割ペインモードを有効にし、ターミナルに基づいて tmux または iTerm2 を使用するかどうかを自動検出します。オーバーライドするには、teammateMode を ~/.claude/settings.json で設定してください。
{
"teammateMode": "in-process"
}
単一セッションに対して in-process モードを強制するには、フラグとして渡してください。
claude --teammate-mode in-process
分割ペインモードには、tmux または it2 CLI を備えた iTerm2 が必要です。手動でインストールするには、以下を実行してください。
- tmux：システムのパッケージマネージャーを通じてインストールしてください。プラットフォーム固有の手順については、tmux wiki を参照してください。
- iTerm2：
it2CLI をインストールし、iTerm2 → Settings → General → Magic → Enable Python API で Python API を有効にしてください。
チームメンバーとモデルを指定する
Claude はタスクに基づいて生成するチームメンバーの数を決定するか、正確に実行したい内容を指定できます。
Spawn 4 teammates to refactor these modules in parallel. Use Sonnet for
each teammate.
チームメンバーはデフォルトではリーダーの /model 選択を継承しません。プロンプトで指定されていない場合に使用されるモデルを変更するには、/config で Default teammate model を設定してください。チームメンバーがリーダーの現在のモデルに従うようにするには、Default (leader's model) を選択してください。
チームメンバーのプラン承認を要求する
複雑またはリスクの高いタスクの場合、チームメンバーが実装前にプランを立てることを要求できます。チームメンバーはリーダーがアプローチを承認するまで、読み取り専用プランモードで動作します。
Spawn an architect teammate to refactor the authentication module.
Require plan approval before they make any changes.
チームメンバーがプランを完了すると、リーダーにプラン承認リクエストを送信します。リーダーはプランをレビューして、承認するか、フィードバック付きで却下するかのいずれかを選択します。却下された場合、チームメンバーはプランモードのままで、フィードバックに基づいて修正し、再提出します。承認されると、チームメンバーはプランモードを終了し、実装を開始します。
リーダーは自律的に承認決定を下します。リーダーの判断に影響を与えるには、プロンプトで「テストカバレッジを含むプランのみを承認する」や「データベーススキーマを変更するプランを却下する」などの基準を指定してください。
チームメンバーと直接通信する
各チームメンバーは、完全で独立した Claude Code セッションです。任意のチームメンバーに直接メッセージを送信して、追加の指示を与えたり、フォローアップの質問をしたり、アプローチをリダイレクトしたりできます。
- In-process モード：Shift+Down を使用してチームメンバーをサイクルして、メッセージを入力してください。Enter キーを押してチームメンバーのセッションを表示し、Escape キーを押して現在のターンを中断してください。Ctrl+T を押してタスクリストを切り替えてください。
- 分割ペインモード：チームメンバーのペインをクリックして、セッションと直接対話してください。各チームメンバーは独自のターミナルの完全なビューを持っています。
タスクを割り当てて要求する
共有タスクリストはチーム全体の作業を調整します。リーダーがタスクを作成し、チームメンバーがそれらを処理します。タスクには 3 つの状態があります。保留中、進行中、完了。タスクは他のタスクに依存することもできます。未解決の依存関係を持つ保留中のタスクは、それらの依存関係が完了するまで要求できません。
リーダーはタスクを明示的に割り当てるか、チームメンバーが自己要求できます。
- リーダーが割り当て：リーダーにどのタスクをどのチームメンバーに与えるかを指示してください
- 自己要求：タスクを完了した後、チームメンバーは独立して次の未割り当て、ブロック解除されたタスクを選択します
タスク要求はファイルロックを使用して、複数のチームメンバーが同時に同じタスクを要求しようとするときの競合状態を防ぎます。
チームメンバーをシャットダウンする
チームメンバーのセッションを適切に終了するには、名前で参照してください。例えば、researcher という名前のチームメンバーの場合：
Ask the researcher teammate to shut down
リーダーはシャットダウンリクエストを送信します。チームメンバーは承認して適切に終了するか、説明付きで却下できます。
チームの共有ディレクトリは、セッションが終了すると自動的にクリーンアップされるため、別のクリーンアップステップはありません。削除されるディレクトリと、再開されたセッションのために保持されるディレクトリについては、Architecture を参照してください。
hooks で品質ゲートを実施する
hooks を使用して、チームメンバーが作業を完了したときまたはタスクが作成または完了したときのルールを実施してください。
TeammateIdle：チームメンバーがアイドル状態になろうとしているときに実行されます。終了コード 2 でフィードバックを送信し、チームメンバーを動作させ続けてください。TaskCreated：タスクが作成されているときに実行されます。終了コード 2 で作成を防止し、フィードバックを送信してください。TaskCompleted：タスクが完了としてマークされているときに実行されます。終了コード 2 で完了を防止し、フィードバックを送信してください。
エージェントチームの動作方法
このセクションでは、エージェントチームの背後にあるアーキテクチャとメカニクスについて説明します。使用を開始したい場合は、上記の エージェントチームを制御する を参照してください。
Claude がエージェントチームを開始する方法
エージェントチームは最初のチームメンバーが生成されるときに形成され、メインセッションがリーダーとして機能します。チームメンバーが生成される方法は 2 つあります。
- チームメンバーをリクエストする：並列作業から利益を得るタスクを Claude に提供し、明示的にチームメンバーをリクエストしてください。Claude は指示に基づいてチームメンバーを生成します。
- Claude がチームメンバーを提案する：Claude がタスクが並列作業から利益を得ると判断した場合、チームメンバーの生成を提案する可能性があります。進行する前に確認してください。
どちらの場合でも、制御は維持されます。Claude はあなたの承認なしにチームメンバーを生成しません。
アーキテクチャ
エージェントチームは以下で構成されています。
| コンポーネント | 役割 |
|---|---|
| チームリーダー | チームメンバーを生成し、作業を調整するメイン Claude Code セッション |
| チームメンバー | 割り当てられたタスクで動作する個別の Claude Code インスタンス |
| タスクリスト | チームメンバーが要求して完了する共有作業項目リスト |
| メールボックス | エージェント間の通信用メッセージングシステム |
表示設定オプションについては、表示モードを選択 を参照してください。チームメンバーのメッセージはリーダーに自動的に到着します。
システムはタスク依存関係を自動的に管理します。チームメンバーが他のタスクが依存するタスクを完了すると、ブロックされたタスクは手動介入なしにブロック解除されます。
チームとタスクはセッション派生名でローカルに保存されます。名前は session- の後にセッション ID の最初の 8 文字が続きます。
- チーム設定：
~/.claude/teams/{team-name}/config.json - タスクリスト：
~/.claude/tasks/{team-name}/
Claude Code はセッション起動時にこれらの両方を自動的に生成し、チームメンバーが参加、アイドル状態になる、または離脱するときに更新します。チーム設定ディレクトリはセッション終了時に削除されます。タスクリストディレクトリはローカルに保持され、アップロードされることはないため、再開されたセッションはタスクを保持します。保持期間は、セッショントランスクリプト用に既に制御している同じ cleanupPeriodDays によって管理されます。
チーム設定はセッション ID と tmux ペイン ID などのランタイム状態を保持しているため、手動で編集したり、事前に作成したりしないでください。次の状態更新時に変更が上書きされます。
再利用可能なチームメンバーロールを定義するには、代わりに subagent 定義を使用 してください。
チーム設定には、各チームメンバーの名前、エージェント ID、およびエージェントタイプを含む members 配列が含まれています。チームメンバーはこのファイルを読み取って、他のチームメンバーを発見できます。
プロジェクトレベルのチーム設定に相当するものはありません。プロジェクトディレクトリ内の .claude/teams/teams.json のようなファイルは設定として認識されません。Claude はそれを通常のファイルとして扱います。
チームメンバーに subagent 定義を使用する
チームメンバーを生成するときに、任意の subagent スコープ（プロジェクト、ユーザー、プラグイン、または CLI 定義）から subagent タイプを参照できます。これにより、セキュリティレビュアーやテストランナーなどのロールを 1 回定義し、委任された subagent とエージェントチームチームメンバーの両方として再利用できます。
subagent 定義を使用するには、Claude にチームメンバーを生成するよう指示するときに名前で言及してください。
Spawn a teammate using the security-reviewer agent type to audit the auth module.
チームメンバーはその定義の tools 許可リストと model を尊重し、定義の本体はチームメンバーのシステムプロンプトに追加の指示として追加されます。チーム調整ツール（SendMessage やタスク管理ツール）は、tools が他のツールを制限している場合でも、チームメンバーが常に利用できます。
権限
チームメンバーはリーダーの権限設定で開始します。リーダーが --dangerously-skip-permissions で実行する場合、すべてのチームメンバーも同様に実行します。生成後、個別のチームメンバーモードを変更できますが、生成時にチームメンバーごとのモードを設定することはできません。
コンテキストと通信
各チームメンバーは独自のコンテキストウィンドウを持っています。生成されると、チームメンバーは通常のセッションと同じプロジェクトコンテキストをロードします。CLAUDE.md、MCP servers、および skills。また、リーダーからの生成プロンプトを受け取ります。リーダーの会話履歴は引き継がれません。
チームメンバーが情報を共有する方法：
- 自動メッセージ配信：チームメンバーがメッセージを送信すると、受信者に自動的に配信されます。リーダーは更新をポーリングする必要はありません。
- アイドル通知：チームメンバーが完了して停止すると、リーダーに自動的に通知します。
- 共有タスクリスト：すべてのエージェントはタスクステータスを表示でき、利用可能な作業を要求できます。
- チームメンバーメッセージング：その名前で特定のチームメンバーにメッセージを送信します。全員に到達するには、受信者ごとに 1 つのメッセージを送信してください。
リーダーは生成時に各チームメンバーに名前を割り当て、任意のチームメンバーはその名前で他のチームメンバーにメッセージを送信できます。後のプロンプトで参照できる予測可能な名前を取得するには、生成指示でリーダーに各チームメンバーを何と呼ぶかを指示してください。
トークン使用量
エージェントチームは単一セッションよりも大幅に多くのトークンを使用します。各チームメンバーは独自のコンテキストウィンドウを持ち、トークン使用量はアクティブなチームメンバーの数でスケールします。調査、レビュー、および新機能作業の場合、追加のトークンは通常価値があります。ルーチンタスクの場合、単一セッションがより費用効果的です。使用ガイダンスについては、エージェントチームトークンコスト を参照してください。
ユースケース例
これらの例は、エージェントチームが並列探索が価値を追加するタスクをどのように処理するかを示しています。
並列コードレビューを実行する
単一のレビュアーは一度に 1 つのタイプの問題に傾く傾向があります。レビュー基準を独立したドメインに分割することで、セキュリティ、パフォーマンス、およびテストカバレッジがすべて同時に徹底的に注意を受けます。プロンプトは各チームメンバーに異なるレンズを割り当てるため、重複しません。
Spawn three teammates to review PR #142:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.
各レビュアーは同じ PR から動作しますが、異なるフィルターを適用します。リーダーは完了後、3 つすべてにわたって調査結果を統合します。
競合する仮説で調査する
根本原因が不明な場合、単一のエージェントは 1 つのもっともらしい説明を見つけて停止する傾向があります。プロンプトはチームメンバーを明示的に敵対的にすることでこれと戦います。各チームメンバーの仕事は、独自の理論を調査するだけでなく、他の理論に異議を唱えることです。
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.
議論構造はここでの重要なメカニズムです。順序付き調査はアンカリングに悩まされます。1 つの理論が探索されると、その後の調査はそれに向かってバイアスされます。
複数の独立した調査官が互いに積極的に反証しようとしている場合、生き残る理論は実際の根本原因である可能性がはるかに高くなります。
ベストプラクティス
チームメンバーに十分なコンテキストを提供する
チームメンバーはプロジェクトコンテキスト（CLAUDE.md、MCP servers、および 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."
適切なチームサイズを選択する
チームメンバーの数に厳しい制限はありませんが、実際の制約が適用されます。
- トークンコストは線形にスケール：各チームメンバーは独自のコンテキストウィンドウを持ち、独立してトークンを消費します。詳細については、エージェントチームトークンコストを参照してください。
- 調整オーバーヘッドが増加：より多くのチームメンバーは、より多くの通信、タスク調整、および競合の可能性を意味します
- 収穫逓減：ある時点を超えると、追加のチームメンバーは作業を比例的に高速化しません
ほとんどのワークフローでは、3～5 人のチームメンバーで開始してください。これは並列作業と管理可能な調整のバランスを取ります。このガイドの例では、3～5 人のチームメンバーを使用しています。その範囲がさまざまなタスクタイプ全体でうまく機能するためです。
チームメンバーあたり 5～6 個の タスク を持つことで、過度なコンテキストスイッチングなしに誰もが生産的に保たれます。15 個の独立したタスクがある場合、3 人のチームメンバーが良い出発点です。
作業が本当にチームメンバーが同時に動作することから利益を得る場合にのみスケールアップしてください。3 人の焦点を絞ったチームメンバーは、5 人の散らばったチームメンバーよりもしばしば優れています。
タスクを適切にサイズ設定する
- 小さすぎる：調整オーバーヘッドが利益を超える
- 大きすぎる：チームメンバーはチェックインなしで長時間動作し、無駄な努力のリスクが増加します
- ちょうど良い：関数、テストファイル、またはレビューなど、明確な成果物を生成する自己完結型ユニット
チームメンバーが完了するまで待つ
時々、リーダーはチームメンバーを待つ代わりに、タスク自体を実装し始めます。これに気付いた場合は、以下を実行してください。
Wait for your teammates to complete their tasks before proceeding
調査とレビューから開始する
エージェントチームが初めての場合は、明確な境界があり、コードを書く必要がないタスクから開始してください。PR をレビューする、ライブラリを調査する、またはバグを調査します。これらのタスクは、並列実装に伴う調整の課題なしに、並列探索の価値を示しています。
ファイルの競合を回避する
2 人のチームメンバーが同じファイルを編集すると、上書きが発生します。作業を分割して、各チームメンバーが異なるファイルセットを所有するようにしてください。
監視と操舵
チームメンバーの進捗をチェックし、機能していないアプローチをリダイレクトし、調査結果が入ってくるにつれて統合してください。チームを長時間無人で実行させると、無駄な努力のリスクが増加します。
トラブルシューティング
チームメンバーが表示されない
Claude にチームメンバーを生成するよう指示した後、チームメンバーが表示されない場合は、以下を実行してください。
- In-process モードでは、チームメンバーは既に実行中ですが、表示されない可能性があります。Shift+Down を押してアクティブなチームメンバーをサイクルしてください。
- Claude に提供したタスクがチームメンバーを生成する必要があるほど十分複雑であることを確認してください。Claude はタスクに基づいてチームメンバーを生成するかどうかを決定します。
- 明示的に分割ペインをリクエストした場合は、tmux がインストールされ、PATH で利用可能であることを確認してください。
which tmux - iTerm2 の場合、
it2CLI がインストールされ、Python API が iTerm2 の設定で有効になっていることを確認してください。
権限プロンプトが多すぎる
チームメンバーの権限リクエストはリーダーにバブルアップし、摩擦を生じさせる可能性があります。チームメンバーを生成する前に、権限設定で一般的な操作を事前承認して、中断を減らしてください。
チームメンバーがエラーで停止する
チームメンバーはエラーが発生した後、回復する代わりに停止する可能性があります。In-process モードで Shift+Down を使用するか、分割モードでペインをクリックして出力を確認し、以下のいずれかを実行してください。
- 直接追加の指示を与える
- 作業を続行するために置き換えチームメンバーを生成する
リーダーが作業完了前にシャットダウンする
リーダーは、すべてのタスクが実際に完了する前に、チームが完了したと判断する可能性があります。これが発生した場合は、続行するよう指示してください。また、リーダーが委任する代わりに作業を開始する場合は、チームメンバーが完了するまで待つようリーダーに指示することもできます。
孤立した tmux セッション
チームが終了した後、tmux セッションが持続する場合、完全にクリーンアップされていない可能性があります。セッションをリストして、チームによって作成されたセッションを終了してください。
tmux ls
tmux kill-session -t <session-name>
制限事項
エージェントチームは実験的です。注意すべき現在の制限事項は以下の通りです。
- In-process チームメンバーでのセッション再開なし：
/resumeと/rewindは in-process チームメンバーを復元しません。セッションを再開した後、リーダーは存在しなくなったチームメンバーにメッセージを送信しようとする可能性があります。これが発生した場合は、リーダーに新しいチームメンバーを生成するよう指示してください。 - タスクステータスが遅延する可能性：チームメンバーはタスクを完了としてマークできず、依存タスクをブロックすることがあります。タスクが立ち往生しているように見える場合は、作業が実際に完了しているかどうかを確認し、タスクステータスを手動で更新するか、リーダーにチームメンバーをナッジするよう指示してください。
- シャットダウンが遅い可能性：チームメンバーは現在のリクエストまたはツール呼び出しを完了してからシャットダウンし、時間がかかる可能性があります。
- セッションあたり 1 つのチーム：セッションは正確に 1 つのチームを持ち、そのセッションにスコープされています。追加の名前付きチームを作成したり、セッション間でチームを共有したりすることはできません。
- ネストされたチームなし：チームメンバーは独自のチームメンバーを生成できません。リーダーのみがチームを管理できます。
- リーダーは固定：メインセッションはその生涯のリーダーです。チームメンバーをリーダーに昇格させたり、リーダーシップを譲渡したりすることはできません。
- 権限は生成時に設定：すべてのチームメンバーはリーダーの権限モードで開始します。生成後に個別のチームメンバーモードを変更できますが、生成時にチームメンバーごとのモードを設定することはできません。
- 分割ペインには tmux または iTerm2 が必要：デフォルトの in-process モードは任意のターミナルで動作します。分割ペインモードは VS Code の統合ターミナル、Windows Terminal、または Ghostty ではサポートされていません。
次のステップ
並列作業と委任の関連アプローチを探索してください。
- 軽量委任：subagents はセッション内で調査または検証用のヘルパーエージェントを生成し、エージェント間調整が必要ないタスクに適しています
- 手動並列セッション：Git worktrees を使用すると、自動チーム調整なしで複数の Claude Code セッションを自分で実行できます
- アプローチを比較：subagent とエージェントチームの比較を参照して、並べて比較してください