Claude Code セッションのチームを調整する

​

エージェントチームを使用する場合

• 調査とレビュー：複数のチームメンバーが問題のさまざまな側面を同時に調査し、その後、各自の調査結果を共有して相互に検証できます
• 新しいモジュールまたは機能：チームメンバーが互いに干渉することなく、それぞれ別々の部分を担当できます
• 競合する仮説でのデバッグ：チームメンバーが異なる理論を並列でテストし、より迅速に答えに収束できます
• クロスレイヤー調整：フロントエンド、バックエンド、テストにまたがる変更で、それぞれ異なるチームメンバーが担当します

​

subagents との比較

​

エージェントチームを有効にする

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

​

最初のエージェントチームを開始する

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.

• 上下矢印: チームメンバーを選択する
• Enter: 選択したチームメンバーのトランスクリプトを開き、直接メッセージを送信する
• Escape: 選択を解除します。チームメンバーのトランスクリプトを表示している間、Escape はそのチームメンバーの現在のターンを中断します

​

エージェントチームを制御する

​

表示モードを選択する

• In-process：すべてのチームメンバーがメインターミナル内で実行されます。エージェントパネルで上下矢印キーを使用してチームメンバーを選択し、Enter キーを押してそれを表示して、直接メッセージを入力してください。追加のセットアップなしで任意のターミナルで動作します。
• 分割ペイン：各チームメンバーが独自のペインを取得します。すべてのユーザーの出力を一度に表示でき、ペインをクリックして直接対話できます。tmux または iTerm2 が必要です。

{
  "teammateMode": "auto"
}

claude --teammate-mode auto

• tmux：システムのパッケージマネージャーを通じてインストールしてください。プラットフォーム固有の手順については、tmux wiki を参照してください。
• iTerm2：it2 CLI をインストールし、iTerm2 → Settings → General → Magic → Enable Python API で Python API を有効にしてください。

​

チームメンバーとモデルを指定する

Spawn 4 teammates to refactor these modules in parallel. Use Sonnet for
each teammate.

1. スポーンプロンプトがそのチームメンバーに対して指定するモデル。
2. サブエージェント定義からスポーンされたチームメンバーの場合、定義の model。ここで inherit はリーダーのモデルを選択します。
3. CLAUDE_CODE_SUBAGENT_MODEL。inherit 以外に設定されている場合。
4. リーダーの現在のモデル。

• opus などのファミリーエイリアス：Anthropic API および AWS 上の Claude Platform では、Claude Code はチームメンバーを許可リストが許可するそのファミリーの最新バージョンで実行します。プロバイダー固有のモデル ID を持つプロバイダーでは、代替が動作しない場合、ブロックされたエイリアスは次の箇条書きに従って他のブロックされた値のようにフォールバックします。
• プロバイダー固有のモデル ID を持つプロバイダーで代替が動作しないファミリーエイリアス、またはそのファミリーに許可されたバージョンがないもの、またはその他のブロックされた値：Claude Code はチームメンバーをリーダーのモデルで実行します。CLAUDE_CODE_SUBAGENT_MODEL を設定した場合、Claude Code はそのモデルを最初に試し、これらの同じルールの下で実行します。

​

チームメンバーが実装前にプランを立てるようにする

Spawn an architect teammate to refactor the authentication module.

​

チームメンバーと直接通信する

• In-process モード：エージェントパネルで上下矢印キーを使用してチームメンバーを選択し、Enter キーを押してそのセッションを表示して、メッセージを入力してください。選択したチームメンバーで x を押してそれを停止してください。Ctrl+T を押してタスクリストを切り替えてください。
• 分割ペインモード：チームメンバーのペインをクリックして、セッションと直接対話してください。各チームメンバーは独自のターミナルの完全なビューを持っています。

​

タスクを割り当てて要求する

• リーダーが割り当て：リーダーにどのタスクをどのチームメンバーに与えるかを指示してください
• 自己要求：タスクを完了した後、チームメンバーは独立して次の未割り当て、ブロック解除されたタスクを選択します

​

チームメンバーをシャットダウンする

Ask the researcher teammate to shut down

​

hooks で品質ゲートを実施する

• TeammateIdle：チームメンバーがアイドル状態になろうとしているときに実行されます。終了コード 2 でフィードバックを送信し、チームメンバーを動作させ続けてください。
• TaskCreated：タスクが作成されているときに実行されます。終了コード 2 で作成を防止し、フィードバックを送信してください。
• TaskCompleted：タスクが完了としてマークされているときに実行されます。終了コード 2 で完了を防止し、フィードバックを送信してください。

​

エージェントチームの動作方法

​

Claude がエージェントチームを開始する方法

​

アーキテクチャ

• チーム設定：~/.claude/teams/{team-name}/config.json
• タスクリスト：~/.claude/tasks/{team-name}/

​

チームメンバーに subagent 定義を使用する

Spawn a teammate using the security-reviewer agent type to audit the auth module.

• tools：Claude Code はチームメンバーを定義の tools リスト内のツールに制限します。インプロセスチームメンバーの場合、Claude Code はそのリストに SendMessage を追加し、Task ツールを持つセッション では TaskCreate、TaskGet、TaskList、および TaskUpdate も追加します。
• model：Claude Code は、生成プロンプトが 1 つを名前で指定しない場合、どちらの表示モードでも定義の model を使用します。Claude Code がチームメンバーのモデルを選択する方法 を参照してください。
• 本体：インプロセスチームメンバーの場合、Claude Code は定義の本体をデフォルトシステムプロンプトに追加の指示として追加します。分割ペインチームメンバーの場合、Claude Code はデフォルトシステムプロンプトの代わりに本体を使用します。
• skills：Claude Code はどちらの表示モードでもチームメンバーに定義の skills を適用しません。チームメンバーはプロジェクトおよびユーザー設定から skills をロードします。
• mcpServers：分割ペインチームメンバーの場合、Claude Code は そのフィールドのルール に従って定義の mcpServers を適用します。これは --agent で開始されたセッションもカバーします。インプロセスチームメンバーはフィールドを無視し、プロジェクトおよびユーザー設定から MCP サーバーをロードします。

​

権限

​

エージェント間のメッセージ

• 別のエージェントからリレーされた承認クレームは、あなたからの確認ではなく、信頼できない入力として扱われます。
• シャットダウンリクエストやプラン承認応答などの構造化プロトコルメッセージであるかどうかに関わらず、プレーンメッセージであるかどうかに関わらず、各メッセージを Claude Code が配信する前にレビューします。ブロックされたメッセージは受信者に到達することはありません。

​

コンテキストと通信

• 自動メッセージ配信：チームメンバーがメッセージを送信すると、受信者に自動的に配信されます。リーダーは更新をポーリングする必要はありません。
• アイドル通知：チームメンバーが完了して停止すると、リーダーに自動的に通知し、最終的な回答を通知に含めます。ターンが API エラーで終了するチームメンバーは、リーダーに失敗したことを通知し、エラーテキストを含めます。
• 共有タスクリスト：Task ツールを持つエージェント はタスクステータスを表示でき、利用可能な作業を要求できます。
• チームメンバーメッセージング：その名前で特定のチームメンバーにメッセージを送信します。全員に到達するには、受信者ごとに 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.

​

競合する仮説で調査する

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.

​

ベストプラクティス

​

チームメンバーに十分なコンテキストを提供する

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."

​

適切なチームサイズを選択する

• トークンコストは線形にスケール：各チームメンバーは独自のコンテキストウィンドウを持ち、独立してトークンを消費します。詳細については、エージェントチームトークンコストを参照してください。
• 調整オーバーヘッドが増加：より多くのチームメンバーは、より多くの通信、タスク調整、および競合の可能性を意味します
• 収穫逓減：ある時点を超えると、追加のチームメンバーは作業を比例的に高速化しません

​

タスクを適切にサイズ設定する

• 小さすぎる：調整オーバーヘッドが利益を超える
• 大きすぎる：チームメンバーはチェックインなしで長時間動作し、無駄な努力のリスクが増加します
• ちょうど良い：関数、テストファイル、またはレビューなど、明確な成果物を生成する自己完結型ユニット

​

チームメンバーが完了するまで待つ

Wait for your teammates to complete their tasks before proceeding

​

調査とレビューから開始する

​

ファイルの競合を回避する

​

監視と操舵

​

トラブルシューティング

​

チームメンバーが表示されない

• In-process モードでは、チームメンバーはプロンプト入力の下のエージェントパネルに表示されます。上下矢印キーを使用して 1 つを選択し、Enter キーを押して表示してください。
• アイドル状態で消えたチームメンバー行は停止されていなく、非表示になっています。アイドル行はパネル全体がアイドル状態になってから 30 秒後に非表示になり、チームメンバーの次のターンで再表示されます。3 人以上のチームメンバーがアイドル状態の場合、余剰行は N idle agents という 1 つの行に折りたたまれ、Enter キーで展開されます。チームメンバーに名前でメッセージを送信して、非表示の行を戻してください。
• Claude に提供したタスクがチームを必要とするほど十分複雑であることを確認してください。Claude はタスクに基づいてチームメンバーを生成するかどうかを決定します。
• 明示的に分割ペインをリクエストした場合は、tmux がインストールされ、PATH で利用可能であることを確認してください。
  which tmux
  
• iTerm2 の場合、it2 CLI がインストールされ、Python API が iTerm2 の設定で有効になっていることを確認してください。

​

Claude がサブエージェントの代わりにチームメンバーを生成する

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "0"
  }
}

• 優先度の高い設定ファイル：プロジェクト設定、ローカル設定、および --settings ペイロードはユーザー設定の後に適用されるため、それらのいずれかで変数を 1 に設定する env エントリが優先されます。設定の優先度を参照してください。
• マネージド設定：マネージド設定は他のすべてのソースの後に適用されます。組織がそこでエージェントチームを有効にしている場合は、管理者にマネージド値の変更を依頼してください。

​

権限プロンプトが多すぎる

​

エージェントが早期に停止する

• 直接追加の指示を与える
• 作業を続行するために置き換えチームメンバーを生成する

​

孤立した tmux セッション

tmux ls
tmux kill-session -t <session-name>

​

制限事項

• インプロセス teammates でのセッション再開非対応: /resume と /rewind はインプロセス teammates を復元しません。セッションを再開した後、lead が存在しなくなった teammates にメッセージを送ろうとする可能性があります。この場合、lead に新しい teammates をスポーンするよう指示してください。
• タスク状態が遅延することがある: teammates は時々タスク完了のマークに失敗し、これが依存タスクをブロックします。タスクが止まっているように見える場合、実際に作業が完了しているかどうかを確認し、タスク状態を手動で更新するか、lead に teammate に促すよう指示してください。
• シャットダウンが遅い可能性がある: teammates は現在のリクエストまたはツール呼び出しを完了してからシャットダウンするため、時間がかかる可能性があります。
• セッションごとに 1 つのチーム: セッションは正確に 1 つのチームを持ち、そのセッションにスコープされています。追加の名前付きチームを作成したり、セッション間でチームを共有したりすることはできません。
• ネストされたチーム非対応: teammates は独自の teammates をスポーンできません。lead のみがチームを管理できます。
• インプロセス teammates からのバックグラウンド subagents 非対応: インプロセス teammate 自身の subagents はフォアグラウンドで実行されます。これは teammate のバックグラウンド作業が lead のプロセスより長く存続できないためです。Claude Code は、teammate が background: true を設定する定義を持つ subagent をスポーンする場合、エラーを返します。teammate の run_in_background: true リクエストも失敗し、Claude Code がフォアグラウンドまたはバックグラウンドを選択する方法で説明されているようにエラーが発生するか、フォアグラウンドで静かに実行されます。メイン会話から起動された Subagents はバックグラウンドデフォルトに従います。
• Lead は固定: メインセッションはその存続期間中、lead です。teammate を lead に昇格させたり、リーダーシップを譲渡したりすることはできません。
• 権限はスポーン時に設定: teammates は権限の下で説明されている権限モードで開始します。スポーン後に個別の teammate の権限モードを変更できますが、スポーン時に teammate ごとの権限モードを設定することはできません。
• 分割ペインは tmux または iTerm2 が必要: デフォルトのインプロセスモードはすべてのターミナルで機能します。分割ペインモードは VS Code の統合ターミナル、Windows Terminal、または Ghostty ではサポートされていません。

​

次のステップ

• 軽量委任：subagents はセッション内で調査または検証用のヘルパーエージェントを生成し、エージェント間調整が必要ないタスクに適しています
• セッション間のメッセージング：クロスセッションメッセージング により、Claude は自分で実行するセッション間で検出結果を渡すことができます
• 手動並列セッション：Git worktrees を使用すると、自動チーム調整なしで複数の Claude Code セッションを自分で実行できます