ホーム / チュートリアル / Claude Code のエージェントチームの使い方

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

Claude Code エンジニアリング 8分で読めます

Claude Code のエージェントチームは、複数の Claude Code セッションをひとつのチームとして協働させる実験的な機能です。リード（team lead）となるセッションがチームメイトを起動し、共有タスクリストとメッセージのやり取りで作業を分担します。この記事では公式ドキュメント Orchestrate teams of Claude Code sessions の内容をもとに、有効化の方法から制限事項までを日本語で整理します。

この機能は実験的で、既定では無効です。仕様はバージョンによって変わるため、実際に使う前に公式ドキュメントで最新の挙動を確認してください。

エージェントチームとは何か

エージェントチームは、複数の Claude Code インスタンスを同時に動かす仕組みです。ひとつのセッションがリードとして作業の割り振りと結果のとりまとめを担当し、チームメイトはそれぞれ独立したコンテキストウィンドウを持って作業します。チームメイト同士は直接メッセージをやり取りでき、利用者はリードを経由せずに任意のチームメイトへ直接指示を出すこともできます。

公式ドキュメントは、チームを組む前により軽い選択肢で足りないかを先に確認することを勧めています。ひとつのセッション内で完結する委譲であればサブエージェントで十分です。エージェントチームは調整のオーバーヘッドがあり、単一セッションと比べてトークン消費が大きく増えます。チームメイトが互いを待たずに独立して動ける仕事のときに効果が出ます。

公式が挙げている向いている用途は次の4つです。

逆に、順番に進めるしかない作業、同じファイルを編集する作業、依存関係が多い作業では、単一セッションかサブエージェントのほうが効率的だとされています。

サブエージェントとの違いは調整のしかたにあります。サブエージェントは呼び出し元へ結果を返す形で、作業の管理はメインのエージェントが一手に行います。エージェントチームでは、チームメイトが共有タスクリストから作業を自分で取り、互いに直接メッセージを送り合って自律的に調整します。

有効化と最初のチームの起動

エージェントチームは既定で無効です。環境変数 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS に 1 を設定すると有効になります。シェルの環境変数として設定してもよいですし、settings.json の env に書くこともできます。

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

有効化すると、通常の委譲の挙動も変わります。Claude は自分の判断でサブエージェントに名前を付けることがあり、エージェントチームが有効な間、名前の付いたサブエージェントはチームメイトとして起動します。つまり、チームを明示的に頼んでいなくてもチームが形成されることがあります。元の挙動に戻したい場合は、同じ変数を 0 に設定します。

もうひとつの前提として、チームメイトの起動には対話セッションが必要です。-p を付けた非対話モード（ヘッドレスモード）や Agent SDK のセッションでは、エージェントチームが有効でもチームメイトは起動せず、名前付きのサブエージェントは通常のサブエージェントとして動きます。

有効化したあとは、専用のコマンドを打つ必要はありません。やってほしい作業と欲しいチームメイトを自然言語で伝えるだけです。公式ドキュメントの例をそのまま引くと、次のような指示になります。

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.

この例が機能するのは、3つの役割が互いに独立していて、待ち合わせなしに調べられるからです。指示を受けた Claude は共有タスクリストを埋め、観点ごとにチームメイトを起動し、終わったら結果をまとめます。

なお、Claude がチームではなくサブエージェントを使うこともあります。サブエージェントもチームメイトと同じエージェントパネルに並ぶため、パネルに出ていることだけではチームができた証拠になりません。サブエージェントだった場合は、エージェントチームが欲しいと明示してもう一度頼みます。

表示モードとチームメイトへの指示

表示のしかたは2種類あります。

既定を変えるには ~/.claude/settings.json の teammateMode を設定します。

{
  "teammateMode": "auto"
}

1回のセッションだけ変えたいときはフラグで渡せます。このフラグは実験的で claude --help には出てきません。

claude --teammate-mode auto

in-process モードでは、プロンプト入力欄の下のエージェントパネルにチームメイトが並びます。上下の矢印キーで選択し、Enter でそのチームメイトの記録を開いて直接メッセージを送れます。Escape で選択を解除し、記録を見ている間の Escape はそのチームメイトのターンを中断します。選択したチームメイトに対して x を押すと停止、Ctrl+T でタスクリストの表示を切り替えられます。split panes モードでは、そのチームメイトのペインをクリックして直接やり取りします。

チームメイトの人数やモデルは、指示の中で具体的に指定できます。指定しない場合は Claude が作業内容から判断します。モデルは、指示で名指ししたもの、サブエージェント定義の model、環境変数 CLAUDE_CODE_SUBAGENT_MODEL、リードの現在のモデル、という順で決まります。

役割を使い回したい場合は、サブエージェントの定義をチームメイトの型として指名できます。定義の tools と model と本文は適用されますが、skills は適用されず、チームメイトはプロジェクトとユーザーの設定からスキルを読み込みます。

チームメイトを終わらせたいときは、名前を挙げて終了を頼みます。リードが終了要求を送り、チームメイトは応じて終了するか、理由を付けて断ります。チームの共有ディレクトリはセッション終了時に自動で片付けられるため、別途の後始末は不要です。

共有タスクリストと権限の扱い

チーム内の作業は共有タスクリストで調整されます。タスクは pending（未着手）・in progress（進行中）・completed（完了）の3状態を持ち、他のタスクへの依存を持たせることもできます。依存が解決していない pending のタスクは、依存元が完了するまで取得できません。依存の解除は自動で行われ、あるチームメイトがタスクを完了すると、それに依存していたタスクが取得可能になります。

タスクの割り当てには2つの流れがあります。リードに「このタスクをこのチームメイトへ」と指示して明示的に割り当てる方法と、チームメイトがひとつ終えたあとに未割り当てで依存の解決済みのタスクを自分で取る方法です。複数のチームメイトが同時に同じタスクを取りにいく競合は、ファイルロックで防いでいます。

チームとタスクはセッション由来の名前でローカルに保存されます。名前は session- にセッション ID の先頭8文字を続けたものです。

~/.claude/teams/{team-name}/config.json      # チーム設定
~/.claude/tasks/{team-name}/                 # タスクリスト
~/.claude/teams/{team-name}/inboxes/{agent-name}.json   # 各エージェントのメールボックス

チーム設定にはセッション ID や tmux のペイン ID といった実行時の状態が入るため、手で編集したり事前に用意したりしてはいけません。次の状態更新で上書きされます。チーム設定のディレクトリはセッション終了時に削除されますが、タスクリストのディレクトリは残るので、再開したセッションはタスクを引き継げます。

権限については、チームメイトはリードの権限設定を引き継ぎます。リードが --dangerously-skip-permissions で動いていれば、チームメイトも同じ状態で動きます。起動時にチームメイトごとの権限モードを指定することはできず、起動後に個別に変更する形になります。チームメイトの権限確認はリードのセッションに出るため、承認はそこで行います。

エージェント間のメッセージは、受け取った側に対して「利用者からではなく別の Claude セッションから来たもの」として伝えられます。チームメイトが利用者の代わりに権限を承認することはできず、拒否された操作を別のチームメイト経由で通すこともできません。

品質のゲートを掛けたい場合はフックを使います。TeammateIdle はチームメイトが待機状態に入る直前に、TaskCreated はタスクの作成時に、TaskCompleted はタスクの完了時に実行され、いずれも終了コード 2 でその動作を止めてフィードバックを返せます。

制限事項と使いどころ

公式ドキュメントが挙げている制限は次のとおりです。実験的機能なので、把握したうえで使う必要があります。

使いどころの目安として、公式はまず3〜5人から始めることを勧めています。チームメイトを増やすとトークン消費は人数に比例して増え、調整の手間も増えるため、独立したタスクが15個あっても3人から始めるのがよい出発点だとされています。焦点の定まった3人は、散漫な5人よりよい結果を出すことが多い、という書き方です。

初めて使うときは、コードを書かない範囲から始めるのが安全です。プルリクエストのレビュー、ライブラリの調査、バグの調査といった、境界がはっきりしていて並行して調べる価値のある作業が向いています。実装を並行させるときは、チームメイトごとに担当ファイルを分けて、同じファイルを2人が編集する状況を避けてください。

関連する軽い選択肢として、ひとつのセッション内で委譲するサブエージェントと、自分で立てた複数セッションを並行させるGit worktreeがあります。まずこちらで足りるかを検討してから、チームを組むかどうかを決めるとよいでしょう。

関連チュートリアル / 次に読む

Claude Code のサブエージェントを使う worktree で並行セッションを走らせる Claude Code のフックで処理を自動化する Claude Code の設定と権限 Claude Code のセッション管理
← チュートリアル一覧へ戻る カテゴリで探す