原典: Orchestrate teams of Claude Code sessions ／ 日本語版
一行要約
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 との比較
| Subagents | Agent teams | |
|---|---|---|
| context | 独自 window。結果は呼び出し元に返る | 独自 window。完全に独立 |
| 通信 | メインエージェントにのみ報告 | teammate 同士が直接メッセージ |
| 協調 | メインが全作業を管理 | 共有タスクリストで自己協調 |
| 向く用途 | 結果だけが要る絞られた作業 | 議論と協働が要る複雑な作業 |
| トークンコスト | 低い | 高い（teammate ごとに別インスタンス） |
選ぶ基準は「ワーカー同士が通信する必要があるか」。
効く用途
- 調査とレビュー — 複数の teammate が別々の側面を同時に調べ、互いの発見を共有して反論し合う
- 新しいモジュールや機能 — teammate ごとに別の部分を持たせる
- 対立仮説によるデバッグ — 複数の理論を並列に検証して速く収束する
- 層をまたぐ調整 — フロント / バック / テストをそれぞれの teammate が持つ
向かない: 逐次的なタスク、同一ファイルの編集、依存関係が多い作業。
アーキテクチャ
| 構成要素 | 役割 |
|---|---|
| Team lead | teammate を起こして作業を統率するメインセッション |
| Teammates | 割り当てられたタスクに取り組む別々の Claude Code インスタンス |
| Task list | teammate が 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 の permission mode で起動する。 lead が
--dangerously-skip-permissionsなら全員そうなる。例外はdontAskで、これだけは継承されない - spawn 時に teammate ごとの mode は設定できない（spawn 後には変更できる）
- teammate の権限確認は lead セッションに出るので、そこで自分が承認する。設計上の例外が plan 承認で、これだけは lead セッションが自分で承認してしまい、こちらにプロンプトは出ない（上の「teammate に先に計画させる」）
エージェント間メッセージの扱い:
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.
リードの会話履歴は引き継がれない。
情報の共有のしかた:
- メッセージは自動で配送される。 lead が polling する必要はない
- idle 通知には teammate の最終回答が含まれる。 ターンが API エラーで終わった teammate は、失敗したこととエラー本文を lead に知らせる
- 共有タスクリスト —— Task 系ツールを持つエージェントだけが状態を見て仕事を claim できる
- teammate へのメッセージは名前で1人ずつ。 全員に届けたいなら宛先の数だけ送る。名前は lead が spawn 時に付けるので、後のプロンプトで参照したいなら spawn 指示で呼び名を指定する
頼んでいないのにチームになる
agent teams が有効な間は、lead セッションで Claude が名前を付けて起こした subagent が teammate として立ち上がる。 Claude は後でメッセージを送れるように自分の判断で subagent に名前を付けるので、チーム作業のつもりがない委譲でもチームができる。確認は出ない。
例外は2つ —— fork の呼び出しと、呼び出し自体に isolation を渡した場合は teammate にならない。
subagent のまま使いたいなら CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS を 0 にする。
subagent 定義を teammate に使う
project / user / managed スコープの subagent 型を teammate として参照できる。役割を一度定義すれば、委譲する subagent としても teammate としても使い回せる。
定義のどこが効くかは表示モードで違う:
| 定義のフィールド | in-process | split pane |
|---|---|---|
tools | allowlist として効く。SendMessage は必ず足される（Task 系ツールを持つセッションなら TaskCreate / TaskGet / TaskList / TaskUpdate も） | allowlist として効く |
model | どちらのモードでも効く（spawn プロンプトがモデルを指定していないとき） | 同左 |
| 本体 | 既定の system prompt に追記される | 既定の system prompt を置き換える |
skills | 適用されない。 プロジェクトとユーザーの設定から読む | 同左 |
mcpServers | 無視される。 プロジェクトとユーザーの設定から読む | 適用される（--agent で起こしたセッションと同じ規則） |
止まった in-process teammate は、メッセージを送ると同じセッションに戻ってくる。 保存されていた会話が復元され、そのメッセージが次のプロンプトになる（セッションを resume した後は戻らない。下の「既知の制約」）。
ただし戻ってきた teammate に定義が再適用されるのは、そのエージェントファイルのあるフォルダを信頼しているときだけ。 プロジェクトの .claude/agents/ や --add-dir 由来の定義が対象で、親フォルダを信頼していても数えない。信頼するまでは、定義のツールも指示も無いまま（全 in-process teammate に必ず付くツールだけを持って）戻ってくる。
表示モード
| モード | 内容 |
|---|---|
in-process（既定） | 全 teammate がメインのターミナル内で走る。どのターミナルでも動く |
auto | tmux 内、または it2 CLI 入りの iTerm2 なら split pane、それ以外は in-process |
tmux | split pane を有効化し、tmux か iTerm2 かを自動判別 |
iterm2 | iTerm2 のネイティブ split pane を明示的に使う |
split pane は VS Code の統合ターミナル、Windows Terminal、Ghostty では非対応。
モデル
teammate のモデルは、上から順に最初に当てはまったもの（v2.1.251 以降。それより前は CLAUDE_CODE_SUBAGENT_MODEL が最優先だった）:
- spawn プロンプトがその teammate に指定したモデル
- subagent 定義から起こした teammate なら、定義の
model（inheritは lead のモデル） CLAUDE_CODE_SUBAGENT_MODEL（inherit以外が設定されているとき）- lead の現在のモデル
CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1を立てると、上の1と2が効かなくなる（v2.1.257 以降）。CLAUDE_CODE_SUBAGENT_MODELがinherit以外ならそれ、でなければ lead のモデルになるteammateDefaultModelは v2.1.234 で削除された。 設定に残っていても無視される- 組織の
availableModelsに弾かれたときの代替先 ——opusのような family alias は、Anthropic API と Claude Platform on AWS では許可されている中で最も新しい版に落ちる。provider 固有のモデル ID を使う環境では置換が働かないので、lead のモデルに落ちる（CLAUDE_CODE_SUBAGENT_MODELがあれば、同じ規則でそれを先に試す） - effort は既定で lead から継承する（split pane では v2.1.186 以降。それより前は lead のセッション effort が渡っていなかった）。subagent 型を指定して起こした in-process teammate は、定義の
effortを frontmatter の effort 規則に従って使い、定義のdisallowedToolsもツールから外す（SendMessageと、それが足す Task ツールは名指しされても残る）。参照できる subagent 型の範囲は project / user / managed に plugin も加わった - lead を
--setting-sourcesで起動すると、teammate も同じ絞った設定ソースから読む（v2.1.281 より前は、split pane の teammate がすべての設定ソースを読んでいた）
in-process の teammate を見ている間、平文と skill はその teammate へ、built-in command は lead のセッションへ行く。そのための安全策が2つある —— /compact / /clear / /rewind は lead の会話に効くので、実行前に確認を求める。/model と /fast は lead のモデルと fast mode を変えるものなので、この画面からは走らない（理由の通知が出る）。teammate の model と fast mode は spawn 時に固定される。
teammate に先に計画させる
lead が plan mode のあいだに起こされた teammate は、計画ができるまで読み取り専用の plan mode で働く。 つまり手順は「先に lead を plan mode にしてから teammate を頼む」。
ただし承認は自動で、人も lead も計画を読まない。
When a teammate finishes planning, it sends a plan approval request to the lead. Claude Code approves the plan in the lead’s session as soon as the request arrives, without the lead reviewing it.
teammate は計画を終えると lead に plan 承認要求を送る。Claude Code は要求が届いた時点で lead セッションの側で承認してしまい、lead が計画を読むことはない。
歯止めは permission 側にしか無い —— teammate の編集とコマンドは、通常どおり権限プロンプトを通る。
品質ゲート用の hook
| hook | タイミング | exit code 2 の効果 |
|---|---|---|
TeammateIdle | teammate が 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."先に計画させる（プロンプトで頼むのではなく、lead を plan mode にしてから頼む）:
Spawn an architect teammate to refactor the authentication module.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 の transcript を見ている間は、その teammate の現在のターンを中断する |
x | 選択した teammate を停止 |
Ctrl+T | タスクリストの表示切替 |
孤児 tmux セッションの掃除:
tmux ls
tmux kill-session -t <session-name>原典で言及されている関連文書
- sub-agents — subagent との使い分け、subagent 定義の再利用
- features-overview — 拡張どうしの使い分け（原典から agent teams の項目は落ちており、subagent との比較は上の表が正）
- workflows — スクリプトによる大規模統率（第三の選択肢）
- multi-agent-research-system — orchestrator-workers の実運用
- claude-code-auto-mode — エージェント間メッセージへの分類器の適用
- cross-session-messaging — チーム外のセッション間メッセージ。同じ信頼モデルが適用される
- costs — トークンコストの指針（原典の agent-team-token-costs）
- hooks — 品質ゲート用 hook（原典の teammateidle）
- worktrees — 手動での並列セッション