Claude Code Agent Teamsの細かい運用上の注意点をまとめてみた

こんにちは、せーのです。先日 Anthropic から Claude Opus 4.6 が発表され、その中で Claude Code Agent Teams という実験的機能がリリースされました。複数の Claude Code がチームとして協調して並列でタスクをこなす仕組みです。早速使ってみたいと思います。

tmux でターミナルを分割して試した事例は既に こちらのブログ で紹介されているので、本稿では tmux がなくても使える in-process モード に絞り、有効化からタスク割り当て・並列実行・Mailbox まで検証した結果と、Subagent との使い分け・制限・運用の注意をまとめます。実験の途中では「空リポジトリ」を渡したらメンバーが自律的に報告して方針を切り替えたり、CLAUDE.md のルールを Teammates まで読んで動いたりと、予想外の挙動もいくつか見つかったので、そこもあわせて共有します。

Agent Teams とは（おさらい）

Agent Teams は、2026年2月5日に Opus 4.6 と同時に提供が始まった**実験的機能（Research Preview）**です。

• Team Lead（リーダー）1 体が全体をコーディネート
• Teammates（メンバー）がそれぞれ独立したコンテキストで作業
• 共有タスクリストで進捗管理（Ctrl+T で表示）
• Mailbox でメンバー同士が直接メッセージ交換可能

Claude Code には以前から Subagent（サブエージェント）があり、メインエージェントがサブに仕事を任せて結果を受け取る形でした。Agent Teams はそれとは役割が違います。

違いを整理すると、Subagent は「結果を報告してくれる部下」、Agent Teams は「互いに議論できるチーム」というイメージです。

使い分けの目安としては、

• 結果だけ欲しい・1つの観点で完結するなら Subagent で十分。
• 複数観点で並列に進めたい・メンバー同士に相談させたいなら Agent Teams

が向いています（並列コードレビュー、仮説検証デバッグ、マルチモジュール開発など）。

セットアップ — in-process と split panes の違い

Agent Teams を有効にするには、環境変数（または ~/.claude/settings.json）で次を設定します。

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

表示モードは in-process と split panes の2種類あります。

本稿では in-process モードに限定しています。

前提

• Claude Code の対応バージョンであること
• Claude MAX または Pro プランが実質必要
• 5 人チームだとトークンコストはおおよそ 5〜7 倍 → 日常の小さいタスクは従来どおり Subagent で十分、という説明が公式にあります

設定のコツ: 環境変数を毎回付けなくてよいように、~/.claude/settings.json に次を書いておくと意図が明確です。起動画面に特別な表示は出ませんが、有効化されていればチーム作成の依頼に反応します。

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "model": "sonnet",
  "language": "Japanese",
  "teammateMode": "in-process"
}

やってみた

ということで、実際に in-process モードで、次の 4 段階で検証しました。

実験1で使ったプロンプト例:

3人チームを作成して。役割は architect（設計）、implementer（実装）、reviewer（レビュー）に分けてください。

実験2で使ったプロンプト例:

このリポジトリで 3 つのタスクを作成し、各メンバーに割り当ててください。
- architect: リポジトリの構造を把握して概要をまとめる
- implementer: 主要ファイルを列挙して依存関係を整理する
- reviewer: コードの改善提案を 3 件挙げる

実験3で使ったプロンプト例:

セキュリティ・パフォーマンス・テストの観点で並列にコードレビューしてください。

確認用のパス

• チーム設定: ~/.claude/teams/{team-name}/config.json
• タスク一覧: ~/.claude/tasks/{team-name}/
• タスクステータスは 1〜2 秒遅れて反映されることがあるので、少し待ってから Ctrl+T を再度押すとよいです。

結果

実験1: 有効化とチーム作成・メンバー追加

上記のプロンプトで依頼すると、Team Lead がチームを作成し、Teammates が順に spawn していく流れが確認できました。

ターミナル上の表示の意味:

操作: Shift+Up / Shift+Down でアクティブなメンバーを切り替えられます。プロンプト表示も切り替わるので、in-process モードでも「今どのメンバーにいるか」は把握しやすいです。

config.json（~/.claude/teams/{team-name}/config.json）

• メンバー名・agentId・役割ごとの初期プロンプトが格納される
• 注意: Team Lead は settings.json の model（例: Sonnet）に従うが、Teammates には Opus 4.6 が自動で割り当てられる挙動を手元で確認しました。公式の「トークンコスト 5〜7 倍」の主因はここにありそうです。

上記の根拠として、チーム作成後に生成された ~/.claude/teams/{team-name}/config.json の members では、次のように model が振られていました（抜粋: name と model のみ）。

[
  { "name": "team-lead", "model": "claude-sonnet-4-6[1m]" },
  { "name": "architect", "model": "claude-opus-4-6" },
  { "name": "implementer", "model": "claude-opus-4-6" },
  { "name": "reviewer", "model": "claude-opus-4-6" }
]

メンバー選択パネル（Shift+Down）: 各メンバーの稼働時間・ツール使用回数・消費トークン数がリアルタイムで見えるので、コスト感の確認に役立ちます。

╒═ team-lead · 709 tokens · shift + ↑/↓ to select
├─ @architect:   Crunched for 40m 50s · 2 tool uses · 26.4k tokens
├─ @implementer: Cogitated for 40m 45s
├─ @reviewer:    Worked for 40m 38s · 3 tool uses · 27.4k tokens
❯╘═ hide · enter to collapse

チーム作成直後のターミナル出力の例は以下のとおりです。

⏺ チームが作成されました。3人のエージェントを並列でスポーンします。

⏺ Task(architect エージェントの起動)
⏺ Task(implementer エージェントの起動)
⏺ Task(reviewer エージェントの起動)

⏺ 3人チームの作成が完了しました。

  チーム「design-build-review」構成

  役割: architect
  エージェントID: architect@design-build-review
  担当: システム設計・技術仕様作成
  ────────────────────────────────────────
  役割: implementer
  エージェントID: implementer@design-build-review
  担当: コード実装・ファイル作成
  ────────────────────────────────────────
  役割: reviewer
  エージェントID: reviewer@design-build-review
  担当: コードレビュー・品質確認

  チーム設定: ~/.claude/teams/design-build-review/config.json

@architect❯ architect 起動完了、タスク待機中

@implementer❯ implementer 起動完了、タスク待機中

⏺ architect と implementer が起動完了しました。reviewer の報告待ちです。

  現在の起動状況:
  - ✅ architect — 待機中
  - ✅ implementer — 待機中
  - ⏳ reviewer — 起動中...

@reviewer❯ reviewer 起動完了、タスク待機中

⏺ 3人全員の起動が完了しました。

  チーム「design-build-review」— 全員待機中

  ┌────────────────┬────────┐
  │      役割      │  状態  │
  ├────────────────┼────────┤
  │ ✅ architect   │ 待機中 │
  ├────────────────┼────────┤
  │ ✅ implementer │ 待機中 │
  ├────────────────┼────────┤
  │ ✅ reviewer    │ 待機中 │
  └────────────────┴────────┘

実験2: 共有タスクリストとタスク割り当て

上記のプロンプトで依頼すると、リーダーがタスクを作成し、各メンバーに割り当てました。

タスク番号の仕組み:

タスクリスト（Ctrl+T）: pending → in_progress → completed のステータスが表示されます。ステータス反映に 1〜2 秒遅れることがあるので、少し待ってから Ctrl+T を再度押すと最新の状態が確認できます。

並列実行中の表示（スピナー ✻）

in-process モードでは、スピナーのサブ行に全メンバーの作業状況が同時に流れます。画面は分割されず、1 つのターミナルに並列の動きが詰まって見える形です。

タスク割り当て直後の出力例です。Ctrl+T で開くタスクリストでも同じように #4〜#6 が進行中で表示されます。

⏺ 3タスクの作成・割り当てが完了しました。

  ┌─────────────────────────────────────┬─────────────┬───────────┐
  │               タスク                │    担当     │   状態    │
  ├─────────────────────────────────────┼─────────────┼───────────┤
  │ #4 リポジトリ構造の把握・概要まとめ │ architect   │ 🔄 進行中 │
  ├─────────────────────────────────────┼─────────────┼───────────┤
  │ #5 主要ファイル列挙・依存関係整理   │ implementer │ 🔄 進行中 │
  ├─────────────────────────────────────┼─────────────┼───────────┤
  │ #6 コード改善提案3件                │ reviewer    │ 🔄 進行中 │
  └─────────────────────────────────────┴─────────────┴───────────┘

  3人が並列で作業中です。各メンバーから完了報告が届き次第お知らせします。

並列実行中はスピナーに全員の状況がまとめて表示されます。

✻ コード改善提案をまとめ中… (43m 10s · 86.5k tokens · thought for 2s)
  ⎿  ◼ リポジトリの構造を把握して概要をまとめる (@architect)
           Searching for 2 patterns, reading 2 files……
       ◼ 主要ファイルを列挙して依存関係を整理する (@implementer)
           Searching for 2 patterns, reading 1 file……
       ◼ コードの改善提案を3件挙げる (@reviewer)
           Running 再帰的にディレクトリ内容を確認…

実験3: 並列実行と結果の取りまとめ

上記のプロンプトで依頼したところ、次の流れで進みました。

1. 各メンバーがそれぞれの観点（セキュリティ・パフォーマンス・テスト）でコードを読み、出力が順に（あるいはインターリーブして）流れる
2. in-process では 1 つのターミナルに出力が並ぶため、誰のコメントかは prefix や文脈で判別
3. 一通り出そろったあと、リーダーに「結果をまとめてください」と依頼 → 優先度付きの 1 本のまとめが得られる

観点ごとに分けてレビューさせることで指摘の重複が少なくなり、きちんと並列で動いてまとめまで一通り取れました。

並列実行後、リーダーに「結果をまとめてください」と依頼すると次のような 1 本のまとめが得られます（本例は空リポジトリで方針変更した後の出力です）。

⏺ 全タスクが完了しました。

  architect（タスク#4）— リポジトリ概要

  - 現状: 完全に空のディレクトリ（git未初期化）
  - 推測目的: Claude Code チームエージェント機能の動作検証用サンドボックス
  - 想定構造: src/, tests/, docs/, CLAUDE.md, README.md 等

  implementer（タスク#5）— 依存関係

  - 現状: ファイル0件・依存関係なし
  - 提案: TypeScript + @anthropic-ai/sdk を軸に、チームエージェント協調動作を実装する構成

  reviewer（タスク#6）— 改善提案3件
  （今回のセッションで実際に観察された問題に基づく提案）

  #1: config.json にバリデーションスキーマ（zod等）を導入
      問題の根拠: フィールドの型・必須/任意が未定義
  ────────────────────────────────────────
  #2: エージェント間メッセージングにタイムアウト＋リトライ機構
      問題の根拠: reviewer が長時間ブロックされた今回の事象
  ────────────────────────────────────────
  #3: タスク依存関係の明示定義と循環依存検出
      問題の根拠: 依存未設定で reviewer がレビュー開始した今回の事象

実験4: Mailbox — 予想外の「空リポジトリ」で自律的に発火

「メンバー同士で相談しながら」と明示しなくても、問題を検知したメンバーが自律的に Mailbox（SendMessage）を使う場面に遭遇しました。

起きた流れ（依頼なしで）:

各メンバーの切り替え後の動き:

• architect: 推測で「こういうプロジェクトだろう」という構造案を出力
• implementer: 「コードを書くならこのスタック」という提案を出力
• reviewer: このセッションで観察した問題（config のバリデーション不足、メッセージのタイムアウトなど）を改善提案として出力

つまり、タスクの前提が途中で変わっても、メンバーが自律的に報告し、リーダーが方針を出し直し、全員がそれに沿って動く流れが、指示なしで起きたわけです。architect は「推測でこういうプロジェクトだろう」という構造案を、implementer は「コードを書くならこのスタック」という提案を、reviewer は「このセッションで観察した問題（config のバリデーション不足、メッセージのタイムアウトなど）」を改善提案として出しており、役割に応じた self-organizing な動きになっていて、ちょっとおもしろいなと感じました。相談を明示的に促すプロンプトにすれば、メンバー同士の SendMessage もより多く見られると思います。

空リポジトリを検知したときの Mailbox のやりとりは次のとおりです。reviewer が報告し、team-lead が確認してから全員に方針変更を通知しています。

@reviewer❯ リポジトリが空、コード待ち状態を報告

⏺ reviewer からリポジトリが空との報告を受けました。実際の状態を確認します。

⏺ Read 1 file (ctrl+o to expand)

⏺ 確認しました。リポジトリは完全に空です（.git もなし）。

  architect・implementer にも状況を共有して、各タスクの方針を調整します。

⏺ 3人全員に方針変更を通知しました。

  メンバー: architect
  変更後の方針: 空リポジトリの事実報告 + ディレクトリ名から想定される目的・構造をまとめる
  ────────────────────────────────────────
  メンバー: implementer
  変更後の方針: 空リポジトリの事実報告 + 想定される主要ファイル構成と依存関係を提案
  ────────────────────────────────────────
  メンバー: reviewer
  変更後の方針: チームエージェント実装でよくある問題点・改善提案を3件まとめる

@architect❯ リポジトリは空、次のアクション指示待ち
@implementer❯ リポジトリは空、依存関係の整理対象なし
@reviewer❯ リポジトリ空のまま、レビュー対象不在の報告

実験で分かったこと・予想外の挙動

検証を通じて、ドキュメントにあまり書かれていない挙動がいくつか見つかりました。

16エージェントで C コンパイラを構築した事例

Agent Teams の「どこまでできるか」を示す事例として、Anthropic の Nicholas Carlini 氏らが 16 個の並列 Claude インスタンスでゼロから Rust ベースの C コンパイラを構築したプロジェクトがあります。

• 約 10 万行の Rust コードを生成
• 約 2 週間、2,000 以上の Claude Code セッション
• Linux 6.9 を x86 / ARM / RISC-V でコンパイル可能にし、QEMU や FFmpeg、SQLite、PostgreSQL、Redis、Doom もコンパイル成功
• GCC torture test suite で 99% 合格

彼らが挙げている学びの例は次のとおりです。本格的なマルチエージェント開発を考えるうえで参考になります。

• テスト設計が鍵: エージェント向けテストは人間向けと違う設計が必要
• README を広く書く: 新規コンテナ内での方向づけに不可欠
• 並列化の限界: 新機能・バグ修正が既存機能を壊しやすい

出典: Building a C compiler with a team of parallel Claudes

まとめ

Agent Teams を使ってみて感じたのは次の点です。

• Subagent で足りる場面: 結果だけ欲しい・1 つの観点で完結するタスク
• Agent Teams が向く場面: 複数観点で並列に進めたい、メンバー同士に相談させたい作業（並列コードレビュー、仮説検証デバッグ、マルチモジュール開発など）

空リポジトリを渡したときにメンバーが自律的に報告して方針を切り替えたように、前提が変わってもチームとして動きを合わせられるのがおもしろいな、と感じました。tmux がなくても、in-process モードで共有タスクリスト・Mailbox・並列実行は体験できるので、まずは in-process モードから試してみてはいかがでしょうか。

制限・運用の注意（公式ドキュメントおよび今回の検証より）:

実験的機能ではありますが、並列・協調が必要な開発タスクにはかなり刺さる機能だと思います。どうぞ参考にしてみてください。

参考資料

• Orchestrate teams of Claude Code sessions - 公式ドキュメント（英語）
• Claude Code 日本語ドキュメント - Agent Teams - 公式ドキュメント（日本語）
• Claude Code の Agent Teams 機能を使って、自分の指揮で動く専門家チームを作ってみた - クラスメソッド（tmux で split panes を使った体験談）
• Introducing Claude Opus 4.6 - Opus 4.6 リリース発表
• Building a C compiler with a team of parallel Claudes - 16エージェント C コンパイラ事例
• Qiita: Agent Teamsを試す - 実際に試した詳細レポート（PR レビュー 3 分など）
• Zenn: Subagentの課題からAgent Teamsを考える
• Zenn: 簡単に使えるか試してみた
• GitHub Issue #24108: teammates stuck at idle prompt in tmux split-pane mode
• GitHub Issue #23615: Agent teams should spawn in new tmux window