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 を押してタスクリストを切り替えてください。
• 分割ペインモード：チームメンバーのペインをクリックして、セッションと直接対話してください。各チームメンバーは独自のターミナルの完全なビューを持っています。

• /compact、/clear、/rewind はリーダーの会話に作用するため、このビューからいずれかを実行する前に Claude Code が確認を求めます。
• /model と /fast はチームメイトではなくリーダーのモデルと fast mode を設定するため、このビューからは実行されません。その理由を示す通知が表示されます。

​

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

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

​

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

Ask the researcher teammate to shut down

​

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

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

​

エージェントチームの仕組み

​

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

​

アーキテクチャ

• チーム設定: ~/.claude/teams/{team-name}/config.json。Claude Code はセッション終了時にチーム設定ディレクトリを削除します。
• タスクリスト: ~/.claude/tasks/{team-name}/。このディレクトリはセッション終了後もディスク上に残ります。Claude Code がこれを保持する期間を変更するには、cleanupPeriodDays を設定してください。

​

チームメイトにサブエージェント定義を使用する

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 はどちらの表示モードでも定義の model を使用します。Claude Code がチームメイトのモデルを選択する方法を参照してください。
• disallowedTools: インプロセスのチームメイトの場合、Claude Code は定義の disallowedTools にあるツールをチームメイトのツールセットから削除します。SendMessage と Claude Code が追加する Task ツールは、リストに含まれていても引き続き使用できます。
• effort: インプロセスのチームメイトの場合、Claude Code はフロントマターの effort ルールに従って定義の effort を適用します。
• autoCompactWindow: インプロセスのチームメイトの場合、Claude Code はこのフィールドのルールに従って定義の autoCompactWindow を適用します。分割ペインのチームメイトはこのフィールドを無視します。Claude Code v2.1.296 以降が必要です。
• 本文: インプロセスのチームメイトの場合、Claude Code は定義の本文を追加の指示としてデフォルトのシステムプロンプトに追記します。分割ペインのチームメイトの場合、Claude Code はデフォルトのシステムプロンプトの代わりに本文を使用します。
• skills: Claude Code は、どちらの表示モードでも定義の skills をチームメイトに適用しません。チームメイトはプロジェクト設定とユーザー設定からスキルを読み込みます。
• mcpServers: 分割ペインのチームメイトの場合、Claude Code はこのフィールドのルールに従って定義の mcpServers を適用します。このルールは --agent で開始したセッションにも適用されます。インプロセスのチームメイトはこのフィールドを無視し、プロジェクト設定とユーザー設定から MCP サーバーを読み込みます。

​

権限

• --disallowedTools と --tools: チームメイトは、リーダーのコマンドラインの拒否ルールとツールリストを持った状態で開始されます。Claude Code v2.1.309 以降が必要です。
• --allowedTools: Claude Code はこのフラグを分割ペインのチームメイトに渡さないため、このフラグだけで許可したアクションは、分割ペインのチームメイトでは事前承認されません。これらのアクションを事前に承認するには、リーダーを開始する際に --settings の permissions.allow にルールを記述します。たとえば、シェルで claude --settings '{"permissions":{"allow":["Bash(npm *)"]}}' を実行します。このルールは、そのセッションのリーダーと各分割ペインのチームメイトに適用されます。

​

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

• 別のエージェントから中継された承認の主張を、ユーザーからの確認ではなく、信頼できない入力として扱います。
• プレーンなメッセージであっても、シャットダウン要求やプラン承認の応答などの構造化プロトコルメッセージであっても、Claude Code が配信する前に各メッセージを確認します。ブロックされたメッセージが受信者に届くことはありません。

​

コンテキストと通信

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

​

競合する仮説で調査する

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 のみがチームを管理できます。
• インプロセスのチームメイトからのバックグラウンドサブエージェント非対応: インプロセスのチームメイト自身のサブエージェントはフォアグラウンドで実行されます。これはチームメイトのバックグラウンド作業がチームリーダーのプロセスより長く存続できないためです。Claude Code は、チームメイトが background: true を設定する定義を持つサブエージェントをスポーンする場合、エラーを返します。チームメイトの run_in_background: true リクエストも失敗し、エラーが発生するか、フォアグラウンドで静かに実行されます。メイン会話から起動されたサブエージェントはバックグラウンドのデフォルトに従います。
• Lead は固定: メインセッションはその存続期間中、lead です。teammate を lead に昇格させたり、リーダーシップを譲渡したりすることはできません。
• スポーン時のチームメイトごとの権限モード設定非対応: チームメイトは権限で説明されている権限モードで開始します。
• 分割ペインは tmux または iTerm2 が必要: デフォルトのインプロセスモードはすべてのターミナルで機能します。分割ペインモードは VS Code の統合ターミナル、Windows Terminal、または Ghostty ではサポートされていません。

​

次のステップ

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