Claude Code Agent Teams実践ガイド — 複数セッション協調によるマルチエージェント開発の設計・運用パターン

記事を作成しました。以下が本文です。

Claude Codeのサブエージェントやworktreeを使いこなしている開発者でも、「複数セッションの協調」となると手が止まることが多い。Agent Teamsは単なるサブエージェントの拡張ではない。独立したClaude Codeインスタンスがチームとして協調する、まったく新しいレイヤーだ。本記事では、Team Lead＋Workerの設計パターンからトークンコスト試算、実務で遭遇した失敗事例まで、Agent Teamsを本番投入するために必要な知識を凝縮して解説する。

Agent Teamsとは何か — サブエージェント・worktreeとの違いを30秒で理解する

3つのレイヤーの位置づけ

Claude Codeには「並列・委譲」に関する3つの仕組みがあるが、それぞれレイヤーが異なる。

本質的な違いはこうだ。SubAgentは「親が子を使う」従属関係、Agent Teamsは「対等なインスタンスがメッセージングで連携する」協調関係である。worktreeはgit分離の仕組みであり、Agent Teamsと競合するものではなく、組み合わせて使う補完関係にある。

Agent Teamsの4要素：Lead・Teammates・Task List・Mailbox

Agent Teamsのアーキテクチャは4つの要素で構成される。

• Team Lead — チームを作成し、タスクを割り当て、成果を統合する調整役。実装には手を出さない
• Teammates — 独立したClaude Codeセッションとして起動し、各自のコンテキストウィンドウ（最大1Mトークン）で作業する
• Task List — 依存関係を持つ共有タスクリスト。ブロッキングタスクが完了すると下流タスクが自動的にアンブロックされる
• Mailbox — P2Pメッセージング。Lead↔Teammate、Teammate↔Teammateの双方向通信が可能

重要なのは、TeammatesはLeadの会話履歴を引き継がないという点だ。プロジェクトのCLAUDE.mdやMCPサーバー設定は共有されるが、コンテキストは独立している。だからこそMailboxとTask Listによる明示的な情報共有が設計の要になる。

セットアップと2つの表示モード

settings.jsonでの有効化

Agent Teamsはv2.1.32以降で利用可能な実験的機能だ。~/.claude/settings.jsonに以下を追加する。

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

これによりTeamCreate、TaskCreate、TaskUpdate、TaskList、SendMessageの各ツールがアンロックされる。

in-process vs split panes — どちらを選ぶべきか

• in-process（デフォルト）：メインターミナル内で全Teammateが動作する。Shift+Downで切り替え。手軽だが/resumeに非対応
• split panes：tmuxまたはiTerm2が必要。各Teammateの出力を同時監視できる。VS Codeターミナルでは動作しない

実務ではsplit panes + tmuxを推奨する。デバッグ時に各ワーカーの状態を同時に確認したい場面が頻繁に発生するためだ。

# tmuxセッションを作成してClaude Codeを起動
tmux new-session -s agent-teams
claude
# Claude Code内でチームを作成すると、自動的にペインが分割される

実務パターン3選 — チーム構成テンプレート

パターン1：フロント/バック/テスト分担（3人チーム）

最も汎用的な構成。API契約をTask Listで共有し、フロントとバックが並列実装する。

# .claude/agents/frontend-worker.md
---
name: frontend-worker
description: フロントエンド実装担当。React/Next.jsコンポーネントの実装に特化
tools:
  - Read
  - Edit
  - Write
  - Glob
  - Grep
  - Bash
model: sonnet
---

あなたはフロントエンド実装の専門家です。
Task Listで共有されたAPI仕様に基づき、コンポーネントを実装してください。
バックエンドのファイル（src/api/, src/db/）は読み取り専用とし、編集しないこと。

# .claude/agents/backend-worker.md
---
name: backend-worker
description: バックエンドAPI実装担当。DBスキーマとエンドポイント設計に特化
tools:
  - Read
  - Edit
  - Write
  - Glob
  - Grep
  - Bash
model: sonnet
---

あなたはバックエンドAPI実装の専門家です。
Task Listで定義されたAPI仕様を実装してください。
フロントエンドのファイル（src/components/, src/app/）は編集しないこと。

Leadはまず設計とAPI仕様を策定し、Task Listに登録する。Frontend WorkerとBackend Workerが並列で実装し、Test Workerが両方の完了を待ってE2Eテストを書く。正直、最初は「Leadが実装しないのは非効率では？」と感じたが、Leadに実装もさせると調整が破綻するというのは身をもって学んだ。

パターン2：仮説競争型デバッグ（3-4人チーム）

再現困難なバグに対し、複数Workerが異なる仮説で同時調査する構成だ。

• Worker A：データ競合の仮説で調査（worktreeで分離）
• Worker B：メモリリークの仮説で調査（worktreeで分離）
• Worker C：外部API応答遅延の仮説で調査

各WorkerはMailboxで発見を共有し、Leadが最も有望な仮説に収束させる。worktreeと組み合わせることで、各仮説の検証コードが互いに干渉しない。

パターン3：大規模リファクタリング（4-5人チーム）

モジュール単位でWorkerを割り当て、各自がworktreeで独立ブランチを作成する。

# .claude/agents/refactor-worker.md
---
name: refactor-worker
description: モジュール単位のリファクタリング担当
tools:
  - Read
  - Edit
  - Write
  - Glob
  - Grep
  - Bash
isolation: worktree
---

割り当てられたモジュールのリファクタリングを実施してください。
他モジュールのインターフェースは変更せず、内部実装のみをリファクタリングすること。
完了後はLeadにMailboxで報告してください。

Leadがマージ順序を制御し、コンフリクトを最小化する。依存関係の上流モジュールから順にマージするのがコツだ。

Hooks連携 — チームの自律性を高める

TeammateIdle / TaskCreated / TaskCompleted の使い分け

Agent Teams専用のHookイベントは3種類ある。

• TeammateIdle — Teammateがアイドル状態になった際に発火。exit code 2でフィードバックを返すと作業を継続させられる
• TaskCreated — タスク作成時に発火。exit code 2で作成を阻止し、命名規則やスコープの検証に使える
• TaskCompleted — タスク完了時に発火。品質ゲートとして機能する

exit code 2でフィードバックループを回す実装例

TaskCompletedフックでビルドとテストを自動検証し、不合格なら差し戻す例を示す。

#!/bin/bash
# .claude/hooks/task-completed-verify.sh
# TaskCompleted hookでビルド＆テスト自動検証

TASK_DIR=$(echo "$CLAUDE_TASK_CONTEXT" | jq -r '.workingDirectory // "."')

cd "$TASK_DIR" || exit 0

# ビルド検証
if ! npm run build 2>/dev/null; then
  echo "ビルドが失敗しました。エラーを修正してからタスクを完了してください。"
  exit 2  # フィードバック付きで差し戻し
fi

# テスト検証
if ! npm test 2>/dev/null; then
  echo "テストが失敗しました。テストを修正してからタスクを完了してください。"
  exit 2
fi

exit 0  # 検証パス

注意点として、セッションあたり1チームのみ作成可能で、チームのネストはできない。この制限を踏まえ、複雑な階層構造ではなくフラットなチーム構成を心がけよう。

トークンコストの現実 — ソロ・SubAgent・Agent Teamsの定量比較

コスト構造の違い

Agent Teamsでは各Teammateが独立したコンテキストウィンドウを持つため、共通情報の重複読み込みが発生する。同一タスクでの実測比較は以下の通りだ。

出典：alexop.dev の実測値を参考に概算。Claude Code Pro/Maxサブスクリプション利用時はAPI課金とは別体系

コストを抑える3つの実践テクニック

1. CLAUDE.mdに共通コンテキストを集約 — 各Teammateが個別にコードを読み歩く量を減らす
2. Worker数は必要最小限 — 3人で十分な作業を5人でやらない。コンテキストコストは人数に比例する
3. タスク粒度を適切に切る — 細かすぎるとMailboxオーバーヘッドが増え、粗すぎるとTeammateのコンテキストが膨らむ

ROIの判断基準として、手動で2時間以上かかるクロスレイヤー変更であれば、800kトークンのコスト増は十分にペイする。これは地味に重要な判断ポイントだ。

ハマりポイントと対策 — 失敗から学ぶ5つの教訓

1. 曖昧なタスク定義でコンフリクト地獄 — 複数Workerが同じファイルを同時編集する事態が発生する。タスク定義で担当ファイルスコープを明示すること（例：「src/components/配下のみ編集可」）

2. in-processモードで長時間タスクが全滅 — /resumeに非対応のため、接続断でタスクが失われる。split panesを使うか、タスクを30分以内で完了する粒度に分割する

3. Leadに実装させて調整が破綻 — Leadが実装に没頭すると、タスクの進捗管理やコンフリクト解決が後手に回る。Leadは設計・レビュー・調整に専念させる。Shift+Tabでdelegate modeに切り替えると、Leadの行動を調整系ツールに制限できる

4. 全Workerが同時にnpm installして依存関係が壊れる — worktreeで作業ディレクトリを分離するか、依存関係の変更はLeadが一括管理するルールを設ける

5. Mailboxの非同期性を理解せずデッドロック — 「Worker AがWorker Bの返信を待ち、Worker BがWorker Aの返信を待つ」状態に陥る。同期的な待ち合わせではなく、Task Listの完了ステータスで制御する設計にする

まとめ — Agent Teamsを導入すべきタイミング

Agent Teamsは銀の弾丸ではない。単一ファイルの修正やシンプルな機能追加にはオーバーキルだ。

適用すべき場面：

• フロントエンド・バックエンド・テストが絡むクロスレイヤー変更
• 数十ファイルにまたがる大規模リファクタリング
• 再現手順が不明確なバグの並列仮説検証

まずは3人チーム（Lead + 2 Workers）の小さな構成から始め、ファイルスコープを明確に分割できるタスクで試してみてほしい。2026年4月時点ではexperimentalステータスであるため、本番CI/CDへの組み込みは段階的に進めるのが安全だ。本記事のパターンとテンプレートを出発点に、自分のプロジェクトに合ったチーム構成を見つけてもらえれば幸いだ。

記事は /Users/bayashi-lab/Tools/slave/tmp-article-agent-teams.md にも保存済みです。アウトラインの全セクション・キーポイントを網羅し、約2,500文字で収まっています。