実践 8 で扱った Subagents は「メインから委譲して結果サマリーが返る」モデルだった。Agent Teams はその一段先 ── 複数の Claude が共有タスクリストとメッセージングを通じて協調する仕組みである。実験的機能で、明確な使い分けが要る。

Subagents との位置関係

混同しないようまず整理する。

Subagents (実践8)Agent Teams (本章)
アーキテクチャ中央 (オーケストレータ) → ワーカーリーダー + メンバー間直接通信
通信メインに結果のみ返すメンバー同士で直接メッセージ
調整メインがすべて管理共有タスクリストで自己調整
トークンコスト低 (結果だけメインに集約)高 (各メンバーが個別 Claude)
最適結果のみ重要な焦点タスク議論・相互検証が必要な複雑作業

つまり Subagents の上位互換ではない。「議論や相互検証が要らない」タスクなら、より安価な Subagents で済ませる方が合理的。Agent Teams は「議論することに価値がある」タスクのための道具である。

アーキテクチャ

Agent Teams は四つのコンポーネントで構成される:

コンポーネント役割
チームリーダーチームを作り、メンバーを生成し、作業を調整するメイン Claude セッション
チームメンバー個別の Claude Code インスタンス。独立したコンテキスト
タスクリストメンバーが要求して完了する共有作業項目
メールボックスエージェント間直接メッセージング

リーダーは「オーケストレータ的役割」も持つが、メンバー同士が直接話せる点が Subagents と本質的に違う。「順次に調査して報告」ではなく「お互いに反論しながら結論に収束する」のような動きができる。

有効化

実験的機能なのでデフォルト無効。環境変数で有効化:

# 環境変数で
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

# もしくは settings.json で
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Claude Code v2.1.32 以降が必要。

チームを開始する

Claude にチーム作成を指示するだけ。明示的にチーム構成を指定する例:

TODO コメントをコードベース横断で追跡する CLI ツールを設計したい。
チームを作って、異なる角度から探索して: 一人は UX、
一人は技術アーキテクチャ、一人は懐疑派 (devil's advocate)。

Claude が共有タスクリストを持つチームを作り、各観点のメンバーを生成し、問題を探索させ、結果を統合する。

CLI ターミナルでは、Shift+Down でメンバーを巡回して直接メッセージを送れる。各メンバーを独自の分割ペインに分けたい場合は、tmux か iTerm2 環境で --teammate-mode tmux を渡す。

効くユースケース

公式と経験から、価値が出やすいパターンは以下:

並列コードレビュー (異なるレンズ)

PR #142 をレビューする agent team を作って。3 人のレビュアーを生成:
- セキュリティ観点
- パフォーマンス影響
- テストカバレッジ
それぞれレビューして発見を報告して。

単一レビュアーは観点が偏るが、3 人を異なるレンズに割り当てれば、すべてのドメインに同時に注意が向く。リーダーが結果を統合する。

競合する仮説でのデバッグ

ユーザがアプリは 1 メッセージ後に終了すると報告している。
5 人のチームメイトを生成して、それぞれ異なる仮説を調査して。
お互いに会話して理論を反証し合う、科学的議論のように。
合意が出たら findings.md を更新して。

順次調査だと「先に出た説に引きずられる」アンカリング問題があるが、複数が互いに反証し合う設計だと、生き残った理論が真の根本原因である確率が高くなる。

モジュール並列実装

4 人のチームメンバーで、これらのモジュールを並列にリファクタして。
各メンバーには Sonnet を使って。

ファイル所有が分かれていれば、メンバー同士が干渉せずに並列で作業できる。同じファイルを編集すると上書き合戦になるので、作業を分けて各メンバーが別ファイルセットを持つように設計する必要がある。

チームメイトの権限

メンバーはリーダーの権限設定で開始する。リーダーが --dangerously-skip-permissions で動いていれば、すべてのメンバーも同様。生成後に個別メンバーのモードを変更できるが、生成時にメンバーごとのモードは設定できない。

チームのクリーンアップ

完了後はリーダーにクリーンアップを指示する:

チームをクリーンアップして

これでタスクリストとメンバーの共有リソースが削除される。リーダーから実行すること ── メンバーからクリーンアップするとリソースが不整合な状態で残ることがある。

既知の制限

実験的機能なので注意点が多い。代表的なものを列挙:

  • In-process メンバーでは /resume /rewind が機能しない ─ セッション再開後にリーダーが存在しないメンバーにメッセージしようとする
  • タスクステータスが遅延することがある ─ メンバーが完了をマークし忘れて、依存タスクが詰まる
  • シャットダウンが遅いことがある ─ 進行中のリクエスト完了を待ってから終了
  • セッションあたり 1 チーム ─ 並行で複数チームは持てない
  • ネスト不可 ─ メンバーは独自のチームを作れない
  • リーダーは固定 ─ チーム作成セッションが生涯リーダー
  • 権限は生成時設定 ─ 生成後に個別変更可、生成時のメンバーごと指定不可
  • 分割ペインは tmux/iTerm2 のみ ─ VSCode 統合ターミナル、Windows Terminal、Ghostty では不可

トークンコストへの覚悟

Agent Teams は単一セッションよりかなり多くトークンを使う。各メンバーが独自のコンテキストウィンドウを持つので、トークン使用量はメンバー数におおむね比例する。

公式ガイダンスは:

  • ほとんどのワークフローでは 3〜5 人で開始
  • メンバーあたり 5〜6 タスクが目安
  • ルーチンタスクは Agent Teams ではなく単一セッションが安い

「Subagents で済むかまず考える、議論が必要な時だけ Agent Teams を選ぶ」を原則にすると、コストを抑えやすい。

次章は、Claude Code をローカルマシンの外で動かす方向 ── Claude Code on the web と Remote Control に入る。

参考情報