Claude Codeのエージェントチームの使い方

Claude Codeのエージェントチームは、1つのセッションがリードになり、独立して動く複数のClaude Codeセッション（メンバー）に作業を割り振る実験的な機能です。既定では無効で、環境変数 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS を 1 にすると使えます。有効化後は、タスクの目的と欲しいメンバーを普段の言葉で頼めば、Claudeがメンバーを起動し、共有のタスクリストで進めます。向いているのは調査やレビュー、担当ファイルが分かれる新機能、仮説を並べるデバッグのように、メンバーが互いを待たずに進められる作業です。以下、公式ドキュメントの記述をもとに順に説明します。

エージェントチームは何をする仕組みなのか？

チームは4つの要素でできています。

要素	役割
リード	メンバーを起動し、作業を調整するメインのセッション
メンバー	割り当てられたタスクを進める、独立したClaude Codeのインスタンス
タスクリスト	メンバーが引き受けて完了させる共有の作業一覧
メールボックス	エージェント同士のメッセージの仕組み

エージェントチームのメンバーはそれぞれ自分のコンテキストウィンドウを持ち、メンバー同士で直接メッセージを送り合えます。人がリードを通さず特定のメンバーに話しかけることもできます。

メンバーは起動時にCLAUDE.md、MCPサーバー、スキルを通常のセッションと同じく読み込みますが、リードとの会話履歴を引き継がない独立した文脈で、リードからは起動時の指示（spawn prompt）を受け取ります。そのため、指示には作業に必要な情報を入れておきましょう。

サブエージェントとどちらを使えばいいのか？

判断の軸は「メンバー同士が話し合う必要があるか」です。

観点	サブエージェント	エージェントチーム
結果の扱い	呼び出し元に結果を返す	メンバー同士が直接メッセージを送る
調整	メインのエージェントが管理	メッセージと共有タスクリストで自己調整
トークンコスト	低い（要約を返す）	高い（メンバーごとに別インスタンス）

公式は、報告を返す手早い作業役ならサブエージェント、発見を共有し、互いに異を唱え、自分たちで調整してほしいならエージェントチーム、という基準を示しています。順番に進める作業、同じファイルの編集、依存の多い作業は、単一のセッションかサブエージェントのほうが効果的とされています。

サブエージェントの作り方はサブエージェントの解説、人間の開発チームでの共有はチーム開発の進め方、自動の調整なしで複数セッションを並べる方法はworktreeでの並列作業を参照してください。

エージェントチームはどうやって有効にするのか？

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS を 1 にします。シェルの環境変数か、settings.json の env で指定します（置き場所はsettings.jsonの書き方）。

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

有効化で変わる挙動が2つあります。1つは、普段の委任にも影響することです。Claudeは後でメッセージを送れるよう自分でサブエージェントに名前を付けることがあり、有効化中は名前付きのサブエージェントがメンバーとして起動します。頼んでいなくてもチームができる場合があり、起動時の確認もありません。もう1つは、-p の非対話モード（Agent SDKを含む）ではメンバーが起動せず、通常のサブエージェントとして動くことです。

最初のチームはどう頼めばいいのか？

タスクと欲しいメンバーを自然言語で伝えます。次の公式の例文では、UX、技術構成、反対意見の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.

観点ごとに担当を分け、互いの結果を待たない形にしておくと、メンバーが並行して進めやすくなります。

メンバーは入力欄の下のエージェントパネルに並びます。上下矢印で選び、Enterでそのメンバーのトランスクリプトを開いて直接メッセージを送れます。Escapeで選択解除（表示中ならそのメンバーのターンを中断）、x で停止、Ctrl+T でタスクリストの表示を切り替えます。

Claudeがチームの代わりにサブエージェントを使うこともあります。サブエージェントも同じパネルに出るため、パネルだけではチーム結成を確認できません。その場合はエージェントチームを明示して頼み直します。

人数やモデルも指示文で指定できます。

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

メンバーのモデルは、指示文での指定、サブエージェント定義の model、CLAUDE_CODE_SUBAGENT_MODEL（inherit 以外のとき）、リードの現在のモデル、の順で最初に当てはまるものが使われます。旧設定キー teammateDefaultModel は削除済みで、残っていても無視されます。モデルとfast modeは起動時に固定されます。

画面の分割はどう切り替えるのか？

既定の in-process では全メンバーがメインのターミナル内で動き、どのターミナルでも追加設定なしで使えます。メンバーごとにペインを分ける split panes には tmux か iTerm2 が必要です。既定を変えるには ~/.claude/settings.json に teammateMode を書きます。

{
  "teammateMode": "auto"
}

"auto" はtmuxのセッション内か、it2 CLI を入れたiTerm2のときだけ分割し、それ以外はin-processに戻します。"tmux" は分割を有効にしてtmuxかiTerm2かを自動判定し、"iterm2" はiTerm2のネイティブ分割を使います（it2 CLI が必要）。1セッションだけなら次のフラグで指定できます。このフラグは実験的で claude --help には出ません。

claude --teammate-mode auto

VS Code の統合ターミナル、Windows Terminal、Ghostty では分割表示は使えません。

分担に向く作業と向かない作業はどう見分けるか？

公式が挙げるエージェントチームの強い用途は、調査とレビュー、別々の部分を受け持てる新しいモジュールや機能、仮説を競わせるデバッグ、フロントエンド・バックエンド・テストをまたぐ変更の4つです。2人が同じファイルを編集すると上書きが起きるため、メンバーごとに受け持つファイルを分けるよう公式は注意しています。着手前は次の3点で判断できます。

確認すること	向いている	向いていない
受け持つファイル	メンバーごとに分かれている	同じファイルを複数人が触る
待ち合わせ	他の結果を待たずに進められる	前の作業の出力が次の入力になる
話し合いの必要	発見の共有や反論に価値がある	結果だけ返れば足りる（サブエージェント向き）

初めてなら、PRのレビュー、ライブラリの調査、バグの調査のように、境界がはっきりしてコードを書かない作業から始めるよう公式は勧めています。並行実装の調整の難しさを抱えずに、並行して調べる価値を確かめられるからです。原因不明の不具合に複数のメンバーを当て、互いの仮説を反証し合わせる使い方も紹介されています。1人で順に調べると最初の説に引きずられやすく、反証を生き延びた説のほうが本当の原因である可能性が高い、という理由です。

人数とタスクの大きさはどれくらいが目安か？

人数にハードな上限はありませんが、トークンは人数に比例し、調整の手間も増え、一定以上は比例して速くなりません。公式の目安は次のとおりです。

ほとんどの作業は3〜5人から始める
独立したタスクが15個なら3人が出発点
1人あたり5〜6タスクあると手が止まらず、誰かが詰まってもリードが振り直せる

タスクは小さすぎると調整の負担が上回り、大きすぎると確認なしに長く走って無駄が出やすくなります。関数1つ、テストファイル1つ、レビュー1件のように成果物がはっきりしたタスク粒度が適切です。リードの分割が粗ければ、もっと小さく分けるよう頼みます。

メンバーは会話履歴を持たないので、指示文に作業固有の情報を入れます。公式の例は、対象パス、重点を置く観点、前提となる実装、報告の形式まで書いています。後で名前で呼びたいなら、呼び名も起動時に指定しておきます。

タスクの割り当てと終了はどう進むのか？

タスクは pending、in progress、completed の3状態で、依存先が終わっていないタスクは引き受けられません。依存先が完了するとブロックは自動で解除されます。割り当ては、リードに「どれを誰に」と伝えるか、メンバーが未割り当てで依存の解けた次のタスクを自分で取るかの2通りで、取り合いはファイルロックで防がれます。

終了させるときは名前で指示します。メンバーは承認して終了するか、理由を添えて断ります。セッションが終わると、チーム設定のディレクトリは自動で削除され、タスクリスト（~/.claude/tasks/{team-name}/）はディスクに残ります。

Ask the researcher teammate to shut down

リードがメンバーを待たずに自分で実装を始めたら、Wait for your teammates to complete their tasks before proceeding のように待つよう指示します。

権限と承認はどう扱われるのか？

メンバーはリードの権限モードで始まります（dontAsk は引き継がない）。リードが --dangerously-skip-permissions なら全員に及びます。起動後に個別のモードを変えることはできますが、起動時にメンバーごとには指定できません。モードの違いは権限モードの解説を参照してください。

メンバーの権限確認はリードのセッションに出るので、そこで本人が承認します。メンバー間のメッセージで人の承認を代行したり、拒否された操作を別のメンバーに回して迂回したりはできません。

例外は計画の承認です。リードをプランモードにしてから起動したメンバーは、計画ができるまで読み取り専用で動きます。ただし計画の承認リクエストはリードのセッションが内容を見ずに即時承認します。その後の編集やコマンドは通常の権限確認を通りますが、計画を人が審査する工程にはならない点に注意が必要です。

完了基準を機械的にかけるなら、hooksの TeammateIdle（アイドル直前）、TaskCreated（タスク作成時）、TaskCompleted（完了時）が使えます。いずれも終了コード2でフィードバックを返し、作業の継続や作成・完了の差し止めができます。

トークンはどれくらい増えるのか？

エージェントチームの各メンバーが自分のコンテキストウィンドウを持つため、消費はアクティブなメンバー数に比例します。公式のコスト解説には、メンバーがプランモードで動く場合に標準セッションの約7倍のトークンを使うという記述があります。調査、レビュー、新機能では見合うことが多く、定型作業は単一セッションのほうが費用対効果が高いとされています。

抑え方として公式が挙げるのは、メンバーにSonnetを使う、チームを小さく保つ、指示文を絞る（指示文の内容は最初からコンテキストに載る）、作業を終えたメンバーを終了させる（アクティブなメンバーは、自分が終了するかセッションが終わるまでトークンを消費する）の4つです。実際の消費はトークン使用量の確認方法で確かめられます。

うまく動かないときは何を確認すればいいのか？

メンバーが表示されない。 パネル全体がアイドルになって30秒たつと、アイドルの行は隠れるだけで停止はしていません。名前でメッセージを送れば戻ります。タスクがチームに値するほど複雑だったかも見直します。分割表示が出ないなら、tmuxがPATHにあるかを確認します。iTerm2なら it2 CLI と、設定でPython APIが有効かを見ます。

which tmux

サブエージェントのつもりがメンバーになる。 有効化中は名前付きのサブエージェントがメンバーとして起動します。戻すには値を 0 にします。保存すると実行中のセッションに再適用されます。

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

ユーザー設定で 0 にしても、プロジェクト設定、ローカル設定、--settings で 1 ならそちらが勝ちます。managed settings で有効化されている場合は管理者に依頼します。

権限の確認が多すぎる。 確認はすべてリードに上がるため、よく使う操作はメンバー起動前に権限設定で事前許可しておきます（セキュリティ設定の解説）。

途中で止まる。 メンバーはエラーで立て直さず止まることがあります。パネルで出力を確認し、直接指示を足すか、代わりのメンバーを起動します。リードが全タスク完了前に終わったと判断した場合は、続けるよう指示します。

tmuxのセッションが残る。 一覧を出し、チームが作ったものを終了します。

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

現時点の既知の制限として知っておくことは？

エージェントチームは実験的な機能のため、公式は次の制限を挙げています。仕様は今後変わりうるので、使う前に公式ドキュメントの Limitations の節で最新の状態を確認してください。

/resume と /rewind ではin-processのメンバーは戻らない。再開後は新しいメンバーを起動させる
メンバーが完了の記録を忘れ、依存タスクが止まることがある。実際に終わっていれば手で更新するか、リードに促させる
終了は時間がかかることがある（実行中のリクエストやツール呼び出しを終えてから止まる）
1セッションにチームは1つで、セッション間の共有はできない
入れ子は不可。メンバーは自分のメンバーを起動できない
リードは固定で、譲ったり昇格させたりできない

チーム設定（~/.claude/teams/{team-name}/config.json）は実行時の状態を持つため、手で編集しても上書きされます。プロジェクトに .claude/teams/teams.json を置いても設定としては読まれません。繰り返し使う役割は、サブエージェントの定義を作って起動時にその種類を指名します（定義の skills はメンバーには適用されません）。

着手前に、受け持つファイル、タスクの粒度、指示文に入れる情報を整理しておきましょう。分担の型を自分のリポジトリで試しながら身につけたい方は、月額1,980円から参加できる学習コミュニティ「AI駆動ラボ」も活用してください。