Claude Code Agent Teams実践ガイド — マルチエージェント協調で大規模タスクを並列処理する方法

「このリファクタリング、1セッションでやると半日かかるな…」——Claude Codeを使い込んでいる開発者なら、一度はこの壁にぶつかったことがあるはずだ。2026年2月に追加されたAgent Teams機能は、複数のClaude Codeエージェントがピアツーピアで協調しながら並列開発を行う実験的機能だ。本記事では、サブエージェントとの違い・判断基準から、3〜5エージェント構成での実践ワークフロー、トークンコスト管理まで、実際に動かしながら解説する。

Agent Teamsとは何か — サブエージェントとの決定的な違い

サブエージェント：親子関係の単一セッションモデル

Claude Codeには従来から「Agent tool」によるサブエージェント機能がある。これは親エージェントが子プロセスを生成し、結果だけを受け取る垂直構造だ。子は独自のコンテキストウィンドウを持つが、親への結果報告のみで、子同士が直接やり取りすることはできない。

# サブエージェント（Agent tool）は単一セッション内で自動的に利用される
# 親が「調査して」と指示 → 子が実行 → 結果を親に返す
# コード上ではClaude Codeが内部的にAgent toolを呼び出す形

Agent Teams：対等なピアツーピア協調モデル

Agent Teamsはこれとは根本的に異なる。各エージェント（チームメイト）は独立したClaude Codeプロセスとして動作し、共有タスクリストとメッセージングで対等に協調する水平構造だ。

# Agent Teamsの起動（リードエージェントのセッション内で）
# 「チームを作って、フロントエンド・バックエンド・テストの3人で
#   このユーザープロフィール機能を開発して」と指示するだけでよい

# チームメイトの表示モードを指定する場合（tmux分割ペイン表示）：
claude --teammate-mode tmux

判断基準はシンプルだ。独立した小タスクの委譲にはサブエージェント、相互依存する複数領域の並列開発にはAgent Teamsを使う。

注意: Agent Teamsは2026年3月現在もexperimental機能であり、今後APIが変更される可能性がある。

セットアップと基本構成 — チームを立ち上げる

Agent Teamsの有効化方法

Agent Teamsはデフォルトで無効だ。有効化には2つの方法がある。

# 方法1: 環境変数
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

# 方法2: settings.json（~/.claude/settings.json）

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

表示モードは ~/.claude.json で制御する。tmuxを使っている場合は分割ペインで各エージェントの動きをリアルタイムに確認できる。

{
  "teammateMode": "tmux"
}

チーム構成の設計パターン（3〜5エージェント）

実践的な構成として、Next.jsフルスタックアプリでの3エージェント構成を紹介する。CLAUDE.mdにチーム共通ルールを書いておくと、全エージェントが参照してくれる。

<!-- CLAUDE.md に追加するチームルール例 -->
# チーム開発ルール
- 型定義は src/types/ に集約。変更時はチーム全体にメッセージを送ること
- npm install は backend担当のみが実行する（lockファイル競合防止）
- テストは各モジュール実装完了後にtest担当がまとめて作成

協調の仕組みを使いこなす

Agent Teamsの真価は、タスクリストとメッセージングの使い分けにある。正直、最初はどれをいつ使うか戸惑ったが、整理してみるとシンプルだ。

共有タスクリスト — 依存関係と進捗の可視化

チームリードがタスクを作成し、各チームメイトが自律的にタスクを取得（claim）して作業を進める。タスクには依存関係を設定でき、上流タスクが完了するまで下流はブロックされる。

タスク構成例（リードが作成）:

[Task 1] スキーマ・型定義の作成        → 担当: backend  / 依存: なし
[Task 2] APIエンドポイント実装          → 担当: backend  / 依存: Task 1
[Task 3] プロフィール編集UIコンポーネント → 担当: frontend / 依存: Task 1
[Task 4] APIクライアント層の実装        → 担当: frontend / 依存: Task 2
[Task 5] 結合テスト・E2Eテスト作成      → 担当: test     / 依存: Task 2, Task 3

Task 1が完了すると、Task 2とTask 3が自動的にアンブロックされ、backendとfrontendが並列で動き出す。この仕組みは~/.claude/tasks/{team-name}/にファイルベースで保存される。

ピアツーピアメッセージング — エージェント間の直接通信

APIのレスポンス型が変わった、共通コンポーネントの引数が増えた——こうしたリアルタイムの情報共有にはメッセージングを使う。リードを介さず、チームメイト同士が直接やり取りできる点がサブエージェントとの大きな違いだ。

メッセージフロー例:

backend → frontend: 「ProfileUpdateResponseにavatarUrlフィールドを追加した。
                      src/types/profile.ts を確認してほしい」
frontend → test:    「UIコンポーネントのProps型が確定した。
                      テストのモック作成を開始して問題ない」

ファイル編集の競合に注意

タスクのclaim時にはファイルロックによって、同一タスクを複数エージェントが同時に取得することが防止される。ただし、ファイル編集自体の競合は防止されない。2つのチームメイトが同じファイルを編集すると上書きが発生する。そのため、各チームメイトが担当するファイルセットを明確に分けることが重要だ。

使い分けの指針:

• 疎結合タスク → タスクリストのみで十分
• 密結合タスク → メッセージングを追加
• 共有ファイルあり → 編集担当を明確に分け、同一ファイルを複数エージェントが触らないようにする

実践ワークフロー：フルスタック機能開発を並列で回す

ワークフロー全体像と各エージェントの動き

具体シナリオとして、「ユーザープロフィール編集機能」を3エージェントで開発する流れを見てみよう。

Phase 1: 基盤構築（直列）
  └─ backend: スキーマ定義 + 型定義を作成
     （frontend, test はブロック待ち）

Phase 2: 並列実装
  ├─ backend: APIエンドポイント実装（POST /api/profile, GET /api/profile/:id）
  └─ frontend: 編集フォームUI + バリデーション実装
     （型定義を共有しているので型安全に並列開発）

Phase 3: 結合（並列 → 直列）
  ├─ frontend: APIクライアント層を実装しフォームと結合
  └─ test: 結合テスト + E2Eテスト作成・実行

これは地味に便利で、Phase 2の並列化だけでも体感の作業時間は大幅に短縮される。

よくあるハマりポイントと対処法

1. エージェント間の型不整合

最も多いトラブル。対策はPhase 1で共有型定義ファイルを確定させること。型定義が固まる前に実装を始めると、後から手戻りが発生する。

// src/types/profile.ts — 全エージェントが参照する共有型定義
export interface ProfileUpdateRequest {
  displayName: string;
  bio?: string;
  avatarUrl?: string;
}

export interface ProfileUpdateResponse {
  id: string;
  updatedAt: string;
  profile: ProfileUpdateRequest;
}

2. npm install の競合

全エージェントが同時にnpm installを実行するとpackage-lock.jsonが壊れることがある。CLAUDE.mdで「依存追加はbackend担当のみ」と明記し、他のエージェントには既存の依存のみ使うよう指示する。

3. コンテキストの肥大化

各エージェントは独立したコンテキストウィンドウを持つ。スコープを絞らないと、関係ないファイルを読み込んでトークンを浪費する。ロール定義で「触っていいディレクトリ」を明示するのが効果的だ。

トークンコストと判断基準 — いつAgent Teamsを使うべきか

コスト構造の理解

Agent Teamsは各エージェントが独立したコンテキストを持つため、トークン消費は単一セッションの3〜5倍以上になりうる。さらに、メッセージングやタスク同期といった協調オーバーヘッドも加算される。

判断フロー

タスクを分析
  │
  ├─ 独立した小タスクが1〜2個 → サブエージェント（Agent tool）で十分
  │
  ├─ 相互依存するタスクが3個以上
  │   ├─ 各タスクの所要時間が30分未満 → サブエージェントを順次実行
  │   └─ 各タスクの所要時間が30分以上 → Agent Teamsを検討
  │
  └─ ファイルの重複編集が多い → Agent Teamsの恩恵は薄い（直列の方が安全）

推奨チームサイズは3〜5エージェント、1エージェントあたり5〜6タスクが目安だ。それ以上はオーバーヘッドが増えて効率が落ちる。

また、現時点での制限事項として以下を把握しておくとよい:

• チームのネスト（チームメイトが自分のチームを作ること）は不可
• in-processモードではセッション復元（/resume）が効かない
• リードは途中で変更できない

まとめ

Agent Teamsは「単一セッションの限界」を突破するための強力な選択肢だが、万能ではない。タスクの独立性と相互依存度を見極め、サブエージェントで十分なケースと使い分けることが、コスト効率と開発速度の両立につながる。まずは小規模な並列タスク（2〜3エージェント）から試して協調の仕組みの感覚を掴み、そこから本格的なフルスタック並列開発へスケールさせていくのがおすすめだ。