ai-docs

Orchestrate teams of Claude Code sessions

Properties1
tagsclaude-code, agents, orchestration, subagents, costs, permissions

15 min read

一行要約

subagent との決定的な違いは「teammate 同士が直接メッセージを送り合い、共有タスクリストから自分で仕事を取る」こと。だからこそ対立仮説のデバッグや並列レビューに効くが、トークンは teammate の数に比例して増える。

要点

Agent teams are experimental and disabled by default. Enable them by setting CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. agent teams は実験的機能であり、既定では無効である。CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 を設定して有効にする。

subagent との比較

SubagentsAgent teams
context独自 window。結果は呼び出し元に返る独自 window。完全に独立
通信メインエージェントにのみ報告teammate 同士が直接メッセージ
協調メインが全作業を管理共有タスクリストで自己協調
向く用途結果だけが要る絞られた作業議論と協働が要る複雑な作業
トークンコスト低い高い（teammate ごとに別インスタンス）

選ぶ基準は「ワーカー同士が通信する必要があるか」。

効く用途

  • 調査とレビュー — 複数の teammate が別々の側面を同時に調べ、互いの発見を共有して反論し合う
  • 新しいモジュールや機能 — teammate ごとに別の部分を持たせる
  • 対立仮説によるデバッグ — 複数の理論を並列に検証して速く収束する
  • 層をまたぐ調整 — フロント / バック / テストをそれぞれの teammate が持つ

向かない: 逐次的なタスク、同一ファイルの編集、依存関係が多い作業。

アーキテクチャ

構成要素役割
Team leadteammate を起こして作業を統率するメインセッション
Teammates割り当てられたタスクに取り組む別々の Claude Code インスタンス
Task listteammate が claim して完了させる共有の作業リスト
Mailboxエージェント間の通信機構

保存場所:

パス寿命
team config~/.claude/teams/{team-name}/config.jsonセッション終了時に削除
task list~/.claude/tasks/{team-name}/ローカルに残り、アップロードされない（resume したセッションがタスクを保持できる）
mailbox~/.claude/teams/{team-name}/inboxes/{agent-name}.json—

team 名は session- + セッション ID の先頭8文字。

mailbox の堅牢性: Claude Code は mailbox ファイルを読むたびに全エントリを検証する。形式に合わないエントリはエラーとして報告のうえファイルから除去され、正しいメッセージは配送される。v2.1.207 より前は、壊れたエントリが1つあるだけで毎秒エラーが繰り返され、手でファイルを消すまでその mailbox への配送が止まっていた。

送信の成否: Claude Code が「送信済み」と報告するのは、受信側の mailbox ファイルへの書き込みが成功したときだけ。ディスク不足や書き込み権限がないなどで失敗した場合、送信側にエラーが返り、何も送られない。

The team config holds runtime state such as session IDs and tmux pane IDs, so don’t edit it by hand or pre-author it: your changes are overwritten on the next state update. チームの設定ファイルは、セッション ID や tmux のペイン ID といった実行時の状態を保持する。したがって手で編集したり、あらかじめ書いておいたりするな。次の状態更新で変更は上書きされる。

タスクの claim

タスクは pending / in progress / completed の3状態。依存関係を持てる（未解決の依存があるタスクは claim できない）。

  • lead が割り当てる
  • teammate が自分で claim する — タスクを終えたら、割り当てのない未ブロックのタスクを自分で拾う

Task claiming uses file locking to prevent race conditions when multiple teammates try to claim the same task simultaneously. タスクの引き受けにはファイルロックを使い、複数の teammate が同じタスクを同時に引き受けようとしたときの競合を防いでいる。

権限（重要）

  • teammate は lead の権限設定で起動する。 lead が --dangerously-skip-permissions なら全員そうなる
  • spawn 時に teammate ごとの mode は設定できない（spawn 後には変更できる）
  • teammate の権限確認は lead セッションに出るので、そこで自分が承認する

エージェント間メッセージの扱い:

Claude Code tells the receiving agent the message came from another Claude session, not from you. A teammate can’t approve a permission prompt or supply consent on your behalf, and a teammate that was denied an action can’t relay it to another teammate to bypass the check. Claude Code は受け手のエージェントに、そのメッセージがあなたからではなく、別の Claude セッションから来たことを伝える。teammate はあなたの代わりに permission プロンプトを承認したり、同意を与えたりできない。また、ある動作を拒否された teammate がそれを別の teammate に回してチェックを迂回することもできない。

auto mode では分類器がさらに2つのチェックをかける。他のエージェントから中継された承認の主張を「あなたからの確認」ではなく信頼できない入力として扱う、そして配送前に各メッセージ（shutdown request や plan approval response のような構造化メッセージも含む）をレビューする。分類器がブロックしたメッセージは受け手に届かない。

この規則はチームの外にも及ぶ。 cross-session messaging で自分の別の Claude Code セッションから届いたメッセージにも同じ扱いが適用される。

context の継承

teammate は spawn 時に通常のセッションと同じプロジェクト context（CLAUDE.md、MCP サーバ、skills）と、lead からの spawn プロンプトを読む。

The lead’s conversation history does not carry over. リードの会話履歴は引き継がれない。

subagent 定義を teammate に使う

任意の subagent スコープ（project / user / plugin / CLI）の型を teammate として参照できる。

  • 定義の tools allowlist と model を尊重する
  • 定義の本体は teammate の system prompt を置き換えるのではなく追記される
  • SendMessage とタスク管理ツールは、tools が他を制限していても常に利用可能

skills と mcpServers の frontmatter は teammate として走るときには適用されない。 teammate は通常のセッションと同じく、プロジェクトとユーザーの設定から skill と MCP サーバをロードする。

表示モード

モード内容
in-process（既定）全 teammate がメインのターミナル内で走る。どのターミナルでも動く
autotmux 内、または it2 CLI 入りの iTerm2 なら split pane、それ以外は in-process
tmuxsplit pane を有効化し、tmux か iTerm2 かを自動判別
iterm2iTerm2 のネイティブ split pane を明示的に使う

split pane は VS Code の統合ターミナル、Windows Terminal、Ghostty では非対応。

モデル

teammate は lead の /model 選択を既定では継承しない。 /config の Default teammate model で変えられる。effort は lead から継承する。

teammate の model と fast mode は spawn 時に固定されるので、teammate を見ている間に /model や /fast を打っても lead に効く。/effort だけは見ている teammate の以降のターンに効く。

品質ゲート用の hook

hookタイミングexit code 2 の効果
TeammateIdleteammate が idle になろうとするときフィードバックを送って作業を続けさせる
TaskCreatedタスクが作られようとするとき作成を阻止してフィードバックを送る
TaskCompletedタスクが完了とマークされようとするとき完了を阻止してフィードバックを送る

ベストプラクティス

  • チームサイズは 3〜5 から始める。 15 個の独立タスクがあっても 3 teammate が良い出発点

    Three focused teammates often outperform five scattered ones. 焦点の定まった3人の teammate は、散漫な5人を上回ることが多い。

  • タスクの粒度 — 小さすぎると協調のオーバーヘッドが上回り、大きすぎると check-in なしに長く走って無駄が増える。関数1つ、テストファイル1つ、レビュー1件のような自己完結した単位に
  • teammate 1人あたり 5〜6 タスクが目安
  • ファイル衝突を避ける — teammate ごとに別のファイル群を持たせる
  • 調査とレビューから始める — コードを書かないタスクのほうが協調の難しさが出にくい
  • lead が teammate を待たずに自分で実装し始めたら Wait for your teammates to complete their tasks before proceeding と言う

既知の制約

  • in-process teammate はセッション再開で復元されない — /resume と /rewind は teammate を戻さない
  • タスク状態が遅れることがある — teammate が完了マークを付け損ね、依存タスクがブロックされる
  • シャットダウンが遅い — teammate は現在のリクエストやツール呼び出しを終えてから落ちる
  • 1セッションに1チームだけ。名前付きの追加チームも、チームの共有もできない
  • チームの入れ子は不可。teammate は自分の teammate を作れない
  • in-process teammate はバックグラウンド subagent を作れない（lead のプロセスより長生きできないため）
  • lead は固定。teammate を lead に昇格させたり、リーダーシップを移譲したりできない

そのまま使える具体例

有効化:

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

最初のチーム（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.

並列コードレビュー:

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.

Sequential investigation suffers from anchoring: once one theory is explored, subsequent investigation is biased toward it. With multiple independent investigators actively trying to disprove each other, the theory that survives is much more likely to be the actual root cause. 逐次的な調査は anchoring（最初の仮説への固着）に陥る。ひとつの理屈を掘ると、以降の調査がそれに引きずられる。独立した複数の調査者が互いを積極的に反証しようとするなら、生き残った理屈が真の根本原因である見込みははるかに高い。

teammate に十分な context を渡す:

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

plan 承認を要求する:

Spawn an architect teammate to refactor the authentication module.
Require plan approval before they make any changes.

subagent 定義を役割として再利用する:

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

モデルを指定する:

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

シャットダウン:

Ask the researcher teammate to shut down

表示モードの設定:

{
  "teammateMode": "auto"
}
claude --teammate-mode auto

エージェントパネルの操作:

↑ / ↓     teammate を選択
Enter     選択した teammate の transcript を開いて直接メッセージする
Escape    選択した teammate の現在のターンを中断
x         選択した teammate を停止
Ctrl+T    タスクリストの表示切替

孤児 tmux セッションの掃除:

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

原典で言及されている関連文書

未取得の派生リンク

グラフビュー

バックリンク