Agent Teams（エージェントチームズ）

Claude Codeのsubagent（/agents）は使ったことがあって、複数のClaudeを同時に走らせて分担や議論をさせたい人向け

Agent Teams は、複数の Claude Code を「ひとつのチーム」として同時に走らせ、互いに会話させながら作業を進める仕組みです。1つのセッションがチームのリーダー役になって仕事を割り振り、残りの Claude が「チームメイト」として別々に動きます。公式ドキュメントはこれを「complex work requiring discussion and collaboration」、つまり相談しながら進める込み入った仕事向けと位置づけています。

普通に Claude Code を1つ動かすと、頭脳は1人ぶんです。込み入った不具合調査だと「あっちを直すとこっちが疑わしい」と1人で行ったり来たりして時間を食います。Agent Teams はそこに複数の頭を並べて、互いの説をぶつけ合わせる発想です。

そもそも Agent Teams って何のこと？

会議室にホワイトボードを1枚置いて、調査担当が3人座っている場面を想像してください。リーダーが「この不具合、原因の候補を分担して調べて」と付箋（タスク）を貼り出す。担当者はそれぞれ自分の席で別々に調べて、分かったことをホワイトボードに書き合い、お互いに「その説はおかしい」と突っ込み合う。これが Agent Teams のイメージです。

リーダーにあたるのが team lead、座っている3人が teammate、付箋の束が task list、突っ込み合うための連絡網が mailbox です。lead が全体をまとめ、teammate は自分の担当を独立して進めます。

ここがポイント。teammate はそれぞれ別の Claude Code として動きます。頭の中（記憶）も別々です。

使う前に：実験的な機能なので、まず自分でオンにする必要がある

Agent Teams は標準ではオフです。公式ドキュメントは「experimental and disabled by default」とはっきり書いています。何もしないまま「チームを作って」と頼んでも、無言で何も起きないので注意してください。

オンにするには、設定ファイル settings.json の env という欄に "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" の1行を足します。パソコンの起動時の設定値として同じ名前を1にしておく方法でも有効になります。

もう1つ前提があります。Claude Code v2.1.32 以降が必要です。今のバージョンは claude --version で確認できます。古いと、設定をオンにしても動きません。

subagent と何が違う？（ここを混同すると一番つまずく）

「複数の Claude を動かす」と聞くと、すでにある subagent（/agents で設定する下請け役）を思い浮かべる人が多いはずです。見た目は似ていますが、中身はかなり違います。

subagent は、1つのセッションの中で下請けが動いて、終わったら結果を親（main）に返すだけ。下請け同士はお互いに会話しません。公式の言い方だと「report results back to the main agent only」です。

Agent Teams の teammate は、お互いに mailbox で直接メッセージし合い、共有の task list を見て自分で次の担当を取りに行きます。さらに人間が個別の teammate に直接話しかけられます。公式は「Teammates message each other directly」「Shared task list with self-coordination」と書いています。

つまり、ただ並列で速くしたいだけなら subagent で足ります。teammate 同士が findings を共有して、互いの説を潰し合って、自分たちで段取りを調整する必要があるとき、はじめて Agent Teams の出番です。

そのぶん代償もあります。teammate は1人ずつ別の Claude インスタンスなので、token のコストは subagent より高い。公式も「Token cost: Higher」と明記しています。

「料理ブログの不具合調査」を例に、実際の手順を見る

料理ブログの Web アプリで「メッセージを送ると毎回落ちる」という不具合が出ているとします。原因の候補がフロント・バックエンド・データベースのどこにあるか分からない。これを3人の teammate に別々の仮説で同時に調べさせ、互いの説を潰し合わせて原因を絞る、という流れを追います。

前提として、Claude Code は v2.1.32 以降で、settings.json の env に CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS を1にして有効化済みとします。

ステップ1: lead に自然言語でチーム作成を頼む

専用コマンドを覚える必要はありません。今のセッション（これが lead になります）に、ふつうの言葉で頼みます。

「送信すると毎回落ちる」原因を、3人のチームメイトに
別々の仮説で同時調査させて。
1人はフロント、1人はバックエンド、1人はデータベース担当。
互いの説を潰し合うように議論させて、原因が固まったらまとめて。

公式は起動方法を2通り挙げています。こちらから頼む形と、Claude のほうから「チームを組みましょうか」と提案してくる形です。どちらにせよ「Claude won't create a team without your approval」、つまり勝手にチームは作られず、必ず確認が入ります。

ステップ2: lead が task list を作り、3人を spawn する

lead は「フロント側を調べる」「バックエンド側を調べる」「データベース側を調べる」という共有タスクを切り出し、3人の teammate を呼び出します。teammate の保存場所は ~/.claude/teams/{チーム名}/ という場所に作られます。ここは Claude が状態を上書きするので、手で書き換えないのが鉄則です。

ステップ3: 各 teammate が自分の頭で調査する

3人はそれぞれ自分専用の記憶を持って、別々に調べ始めます。呼び出されたとき、teammate はふつうのセッションと同じプロジェクトの土台（CLAUDE.md・MCP・skills）を読み込みます。ただし lead がそれまで交わした会話の中身は引き継ぎません。

ここで初心者がやりがちな勘違いがあります。「lead が知っていることは teammate も全部知っている」と思い込むことです。実際は別の頭なので、調査に必要な情報は依頼文の中で渡す必要があります。

ステップ4: teammate 同士が mailbox で議論する

フロント担当が「送信ボタンの処理が怪しい」と言えば、バックエンド担当が「いや、サーバー側のエラーログにこの行が出ている」と返す。データベース担当が「保存先のテーブルが満杯で書き込みに失敗している」と割り込む。こうしてお互いの説を直接ぶつけ合います。subagent ではこれができません。

ステップ5: Shift+Down で個別の teammate を覗いて、直接指示も出せる

全員が同じ画面の中で動くモード（後述）なら、Shift+Down で teammate を順に切り替えて、そのまま打ち込めば特定の1人に直接話しかけられます。「データベース担当、テーブルの上限設定も確認して」のように、lead を通さず指示できるのが Agent Teams らしいところです。

ステップ6: 原因が絞れたら lead がまとめ、チームを片付ける

3人の議論で「データベースの書き込み失敗が真犯人」と固まったら、lead が結論を統合します。仕事が終わったら「Clean up the team」と頼んで後片付けします。片付けは必ず lead から。動いている teammate が残っているとこの片付けは失敗するので、先に止めてからにします。

同じことを subagent でやると、3人が互いに議論できず、main がそれぞれの報告を別々に読むだけになります。説を潰し合う動きが生まれないのが決定的な差です。

つまり Agent Teams は何をしてくれるのか

• やってくれる: 複数の Claude を同時に走らせ、teammate 同士を直接会話させて、共有タスクを自分たちで取り合いながら進める。互いの説を潰し合う議論や、観点ごとの分担調査に向く
• やってくれない: 自動で勝手にチームを組むことはしない（必ず確認が入る）。teammate が自分のチームを作ることもできない（入れ子は不可）。lead の交代もできない
• 意味が薄い場面: ただの繰り返し作業や、結果だけ返ってくれば十分な単純なお使い。これは subagent のほうが安く速い。token のコストが人数ぶん積み上がるので、議論がいらない作業に使うと割に合わない

使いどころ3シナリオ（具体題材で再現）

シナリオ1: 原因不明のバグを、観点を分けて同時調査する

家計簿アプリで「月をまたぐと合計額がずれる」という不具合が出たとします。1人で追うと、計算ロジック・日付の扱い・保存処理を行ったり来たりして時間がかかる。ここで3人の teammate にそれぞれ「計算」「日付」「保存」を担当させ、互いの説を潰し合わせると、的外れな候補が早めに消えて原因に近づきます。公式も「investigating a bug」を最初の使いどころに挙げています。

シナリオ2: 設計の方向性を、別々の立場から議論させる

料理ブログに新しく「献立の自動提案」を足すとして、設計の良し悪しを1人で判断するのは心もとない。1人を使い勝手の担当、1人を技術構成の担当、1人をあえて反対意見をぶつける担当にして議論させると、見落としが減ります。公式の例も、まさに「one on UX, one on technical architecture, one playing devil's advocate」という3人構成を挙げています。

シナリオ3: OSS を clone した直後に、全体像を手分けして読む

初めて触る公開プロジェクトを GitHub から自分のパソコンに持ってきた直後、フォルダの数が多すぎてどこから読めばいいか分からない場面があります。teammate を「画面まわり担当」「サーバー処理担当」「設定まわり担当」に分けて手分けして読ませ、後で突き合わせると全体像が早くつかめます。公式は「start with tasks that don't require writing code」、つまり最初はコードを書かない調べもの系から始めるのを勧めています。

初心者が踏みやすい落とし穴

• subagent と取り違える。「並列で速くしたい」だけなら subagent で足ります。teammate 同士が議論し、互いの説を潰し合い、自分たちで段取りする必要があるときが Agent Teams です。ここを混同すると、わざわざ高いほうを使ってしまいます。
• 有効化を忘れて無言で失敗する。標準ではオフです。settings.json の env に CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS を1にして、Claude Code を v2.1.32 以降にしておく。やらないと「チームを作って」と頼んでも何も起きません。
• token のコストが跳ねる。teammate は1人ずつ別の Claude です。記憶も別々に持つので、人数ぶん消費が積み上がります。公式も「significantly more tokens than a single session」と書いています。routine な作業に使うと割に合いません。
• 同じファイルを複数の teammate に触らせる。2人が同じファイルを書き換えると上書き事故になります。公式は「each teammate owns a different set of files」、担当ごとにファイルを分けて持たせろと言っています。
• 同時に何チームも作ろうとする。lead が管理できるのは1チームだけです。新しいチームを作る前に、今のチームを片付けます。teammate が自分のチームを作る入れ子もできず、lead の交代もできません。
• 復元後に消えた teammate へ話しかける。全員を1画面で動かすモードのとき、/resume や /rewind では teammate は戻りません。復元したらいないメンバーに指示しようとせず、新しく spawn し直します。
• teammate に後片付けをさせる。片付けは必ず lead からです。動いている teammate が残っているとこの片付けは失敗するので、先に止めてからにします。teammate に片付けさせると、中途半端に状態が残ります。
• 画面分割モードが使えない環境で詰まる。teammate ごとに窓を分けるモードには tmux か iTerm2 が要ります。VS Code 内蔵のターミナル・Windows Terminal・Ghostty では使えません。どの環境でも動くのは、全員を1画面で動かすモードのほうです。
• 終わったはずのタスクが止まって見える。仕事は終わったのに、teammate がそのタスクをまだ「作業中」と読んで、後続のタスクが動き出さないことがあります。そのときは lead に「このタスクは終わっている、状態を更新して」と伝えるか、手でタスクの状態を直します。公式も「Task status can lag」と認めているクセです。
• 「止まれ」と言ってもすぐには止まりません。teammate はシャットダウンを頼まれても、今やっている処理が片付くまで動き続けます。「なぜまだ動くんだ」と慌てず少し待つのが正解で、公式も「Shutdown can be slow」と書いています。

書き方

（今のセッションに自然言語で頼む）3人のチームメイトを作って、フロント・バックエンド・データベースで分担して原因を調べて

やってみるとこうなる

入力

「送信すると毎回落ちる」原因を、3人のチームメイトに別々の仮説で同時調査させて。1人はフロント、1人はバックエンド、1人はデータベース担当。互いの説を潰し合うように議論させて、原因が固まったらまとめて。

出力例

lead（リーダー役のセッション）が共有のやることリストを作り、3人のチームメイトを呼び出す → 3人がそれぞれ自分専用の記憶で別々に調査 → メンバー同士が連絡網で直接議論し、互いの説を潰し合う → 原因が絞れたらleadが結論を統合 → 「Clean up the team」で後片付け。subagentと違い、3人が互いに会話して段取りを自分で調整する。

関連項目

• Subagent Types（サブエージェントタイプス）
• Agentic Loop（エージェンティック・ループ）
• /agents（エージェンツ）
• Plan Mode（プランモード）
• /batch（バッチ）

公式ドキュメント

https://code.claude.com/docs/en/agent-teams