エージェント チーム 高度なパターン

Claude Code Agent Teams は、共有タスク コンテキスト内での並列マルチエージェント調整を実現します。本スキルは、エージェント チーム トポロジーの設計、スケーリング、デバッグに関する本番グレードのパターンについて説明します。

エージェント チーム メカニクス

有効化:

• 環境変数を設定: CLAUDE_ENABLE_TEAMS=true
• または Claude Code CLI に --enable-teams フラグを渡す
• 各チームメイトは独立したコンテキスト ウィンドウと git ワークツリーを取得します

チームとサブエージェントの違い:

• サブエージェント はシーケンシャルなファイア・アンド・フォーゲット ワーカーです。メイン エージェントは結果を待機してから続行します。
• チームメイト はピア・ツー・ピア メッセージング付きで並列実行されます。すべてのチームメイトはタスク リストを共有し、リアルタイムで互いの進捗を確認できます。
• 独立したセッション: 各チームメイトは独自の会話状態を保持し、失敗しても他のチームメイトをブロックせずに復旧できます。
• 共有責任: チームメイトは親によって割り当てられた個別のサブタスクではなく、目標を集合的に所有します。

チーム トポロジー パターン

ハブ・アンド・スポーク (リード駆動)

1 人のリードがチームメイトに作業を割り当て、結果を収集します。

• 適している場合: 階層的ワークフロー、明確なタスク分解、報告要件
• リードの責任: 作業をタスクに分割し、チームメイトに割り当て、結果をマージ
• チームメイト: 割り当てられたタスクを実行し、ステータスと課題を報告
• コスト: 1 リード (Opus) + N チームメイト (Sonnet/Haiku)

      ┌─────────┐
      │  Lead   │
      └────┬────┘
      ┌────┴────┬─────────┬─────────┐
      │    │    │    │    │    │    │
      ▼    ▼    ▼    ▼    ▼    ▼    ▼
   Team1 Team2 Team3 Team4 Team5 Team6

メッシュ ネットワーク (ピア・ツー・ピア)

すべてのチームメイトは互いに直接メッセージを送信できます。真に並列で相互依存的な作業に有効です。

• 適している場合: フィーチャー ブランチ、クロスドメイン調整、研究チーム
• コミュニケーション: 直接ピア メッセージング、リードでボトルネックなし
• 自己組織化: チームメイトは共有キューからタスクを要求
• コスト: N エージェント (すべて同等のため Sonnet)

   ┌──────────────────────────┐
   │                          │
   ▼                          ▼
Team1 ◄──────────────────► Team2
   │                          │
   │ ◄──────────────────►     │
   │                          │
   └──────────►Team3◄─────────┘
      ◄────────┐ │ ┌───────────►
               │ │ │
            Self-Claim Queue

パイプライン (シーケンシャル ハンドオフ)

作業はステージを通じて移行します。各ステージは次に渡す前に完了します。

• 適している場合: トランスフォーメーション、マイグレーション、マルチフェーズ分析
• ステージ: 分析器 → 実装者 → バリデーター → デプロイヤー
• ブロック: 各ステージは前のステージの完了を待機
• コスト: 4 以上のエージェント (通常 Opus-Sonnet-Sonnet-Sonnet)

階層 (マルチレベル チーム)

チーム リードがサブチームを管理します。大規模な組織に有効です。

• 適している場合: エンタープライズ プロジェクト、スケーリングされた並列作業
• 構造: メイン チーム + 3-4 個のサブチーム (各リード付き)
• 複雑性: 各レベルで調整オーバーヘッドが増加
• コスト: 二次的にスケーリング (メイン リード + リード × メンバー)

クロスチーム コミュニケーション

共有タスク リスト

すべてのチームメイトは共有キューからタスクを表示、要求、完了できます。

• 自己要求: チームメイトが「誰がこれを要求していますか?」と尋ね、次の未要求のタスクを選択
• ステータス可視性: すべてのチームメイトが他のユーザーが何に取り組んでいるかを確認
• 重複作業の防止: タスク ロックは 2 人のチームメイトが同じ作業を要求するのを防止

ピア・ツー・ピア メッセージング

同期調整のためのチームメイト間の直接メッセージ。

Teammate1 → "Finished schema, Team2 can now generate tests"
Teammate2 → "Tests running, Team3 estimate for performance review?"
Teammate3 → "Ready when schema is final—what's your ETA?"

ステータス ブロードキャスト

全チームに表示される定期的な更新 (5 〜 10 分ごと)。

• 進捗: 「ユニット テスト 3/8 完了」
• 課題: 「Team4 の API 変更を待機中」
• ハンドオフ シグナル: 「フィーチャー ブランチはレビュー準備完了」

競合解決

2 人のチームメイトが同じタスクを要求する場合:

1. タスク ロック: 最初に要求したユーザーが排他ロックを取得 (デフォルト 60 秒)
2. 競合検出: システムが 2 番目の要求者に警告
3. グレースフルな劣化: 2 番目のチームメイトが次のタスクを選択するか、並列作業で最初のユーザーをサポート

Git ワークツリー調整

各チームメイトは分離された git ワークツリーを取得し、作業中のマージ競合を防止します。

ワークツリー命名:

# チーム ID とチームメイト インデックスによる自動命名
.git/worktrees/team-{team_id}-{teammate_index}/

完了時のマージ戦略:

1. スカッシュ・アンド・マージ: デフォルト。コミット グラフのノイズを削減
2. リベース・アンド・マージ: リニア履歴を保持、パイプラインに適切
3. 3 方向マージ: 独立したブランチのデフォルト、競合がある場合あり

競合処理:

• 自動解決可能: 同じファイル、異なるセクション → マージ成功
• 競合マーカー: 両方のチームメイトが同じセクションを編集 → 手動解決が必要
• フォールバック: チーム リード (または指定された解決者) が競合をレビューして解決

ブランチ命名規則:

feature/{team-id}/{teammate-role}
  examples: feature/cce-001/frontend, feature/cce-001/backend

bugfix/{team-id}/{issue-number}
  examples: bugfix/cce-002/123, bugfix/cce-002/456

チーム サイズ ガイダンス

サイズ	特性	適している場合	コスト
2	最小調整オーバーヘッド。理想的な分割: フロントエンド + バックエンド、または分析器 + 実装者。	フィーチャー ブランチ、マイグレーション	2 倍単一エージェント コスト
3-4	ほとんどのプロジェクトに最適なスポット。独立した並列トラック。軽い調整。	フルスタック機能、マルチフェーズ分析	3-4 倍単一エージェント コスト
5 以上	調整オーバーヘッドが増加。チームメイト間のタスク切り替え。収益逓減。	エンタープライズ プロジェクト、研究チーム	5 倍以上だが直線的に価値が上がらない

コスト スケーリング:

• 各チームメイトは個別の Opus/Sonnet セッション
• 2 つの Sonnet エージェント = 約 2 倍のコスト、ただし作業は順序の約 50-60% で完了 (並列化の効率に依存)
• 5 エージェント = 5 倍のコスト、ただし作業は順序の約 30-40% で完了 (調整税が増加)

コスト・ベネフィット フォーミュラ:

TeamCost = (team_size × hourly_rate_per_agent)
Speedup = 100% / (1 + coordination_overhead)
ROI = (sequential_time - (team_time × speedup)) / TeamCost
→ ROI > 0 when team_time * speedup < sequential_time

障害処理

単一チームメイト障害

• 検出: 30 秒間ハートビートなし、またはタスクが失敗とマーク
• 影響: 他のチームメイトは続行。孤立した作業は次の利用可能なチームメイトに再割り当て
• 復旧: 失敗したチームメイトが新しいセッションで起動し、次の利用可能なタスクを選択
• 最大再試行: タスクあたり デフォルト 2 回。2 回の失敗後、チーム リードにエスカレート

カスケード障害

チームメイト A の障害がチームメイト B をブロック (依存関係)。

• タイムアウト: ブロックが 60 秒後に回避または並列パスを試みる
• エスカレーション: チーム リードを関与させて決定: 再試行、スキップ、または作業を再割り当て
• 部分的成功: 作業を「完了 (警告付き)」とマーク、課題をドキュメント化

チーム全体障害

すべてのチームメイトがダウンまたは応答なし。

• フォールバック: チーム リードが作業をシーケンシャルに引き継ぎ
• グレースフルな劣化: 最後に成功したチェックポイント (git コミット) から再開
• 監視: チーム アクティビティが 2 分無い場合、ユーザーに警告

チームメイト ヘルスの監視

# チームメイト ステータスを確認
claude-code teams status --team-id cce-001

# 出力:
# ┌─────────────┬────────────┬──────┬─────────────┐
# │ Teammate    │ Status     │ Task │ Last Update │
# ├─────────────┼────────────┼──────┼─────────────┤
# │ Frontend    │ RUNNING    │ 5/12 │ 2m ago      │
# │ Backend     │ COMPLETED  │ 8/8  │ 5m ago      │
# │ Tests       │ STALLED    │ 2/6  │ 10m ago     │
# └─────────────┴────────────┴──────┴─────────────┘

カスタム チーム テンプレート

チーム構成ファイルを使用して、組み込みテンプレート以上のチーム構成を定義します。

例: カスタム 3 人マイグレーション チーム

version: 1
name: "Database Migration"
description: "Schema analyzer, data migrator, validator"
team:
  - name: "analyzer"
    role: "Database schema analysis"
    model: "claude-sonnet-4-6"
    skills:
      - sql-analysis
      - schema-design
    timeout_seconds: 1800

  - name: "migrator"
    role: "Data migration execution"
    model: "claude-sonnet-4-6"
    skills:
      - data-migration
      - transformation-engine
    timeout_seconds: 3600

  - name: "validator"
    role: "Post-migration verification"
    model: "claude-haiku-4-5"
    skills:
      - data-validation
      - integrity-checking
    timeout_seconds: 900

communication: "mesh"
task_strategy: "shared_queue"
parallelization: "full"

実例パターン

1. フィーチャー ブランチ チーム (3 エージェント)

• フロントエンド (Sonnet): UI コンポーネント、スタイリング、ステート管理
• バックエンド (Sonnet): API エンドポイント、データベース スキーマ変更
• テスト (Haiku): ユニット、統合、E2E テスト

→ 同期されたハンドオフによる並列開発

2. マイグレーション チーム (4 エージェント)

• 分析器 (Sonnet): 古いコードベースをオーディット、マイグレーション計画を作成
• マイグレーター (Sonnet): リファクタリングを実行
• バリデーター (Haiku): 回帰がないことを確認
• リード (Opus): 調整、競合を解決、PR をレビュー

→ 高い信頼性、迅速なマイグレーション

3. インシデント対応 チーム (3 エージェント)

• トリアージャー (Haiku): エラー シグナルを調査、重大度を分類
• フィクサー (Sonnet): ホットフィックスを実装
• ベリファイヤー (Haiku): フィックスが問題を解決することを確認、副作用なし

→ 高速なインシデント解決

4. リサーチ チーム (4 エージェント + シンセサイザー)

• リサーチャー 1-3 (Haiku): 3 つのトピックの並列調査
• シンセサイザー (Sonnet): 結果を組み合わせ、一貫した概要を作成

→ 並列研究でより多くの領域をカバー

5. レビュー ボード (3 エージェント)

• セキュリティ レビュアー (Sonnet): 脆弱性について監査
• パフォーマンス レビュアー (Haiku): ボトルネック、非効率なパターンをチェック
• 品質 レビュアー (Haiku): コード スタイル、保守性、テスト カバレッジ

→ 並列レビュー パースペクティブ

コスト管理

チーム コストの推定

Base cost = (num_teammates × model_cost_per_hour) × estimated_duration_hours
Example: 3 Sonnet agents × $15/hour × 2 hours = $90

vs.

Sequential cost = 1 Sonnet × $15/hour × 6 hours = $90
Speedup: 3 agents complete in 2 hours vs. 6 sequential → 3x faster, same cost

チームメイトごとのモデル割り当て

• Opus (チーム リード): 複雑なアーキテクチャ、競合解決、シンセシス
• Sonnet (実装): メイン作業 — 機能、リファクタリング、マイグレーション
• Haiku (リサーチ、検証): 軽量タスク — チェック、要約、エッジ ケース テスト

チームが価値があるとき

• はい、チームを使用する場合:

  • 作業は真に並列化可能 (フロントエンド + バックエンド、カスケード依存関係ではない)
  • タスク時間 > 1 時間 (調整オーバーヘッドは正当化される)
  • 期限は重要 (2-3 倍高速化はコストの価値あり)
  • リスクが高い (並列レビュー + 検証は余分なコストの価値あり)

• いいえ、シーケンシャルを使用する場合:

  • タスクはカスケード (B は A を待機、C は B を待機)
  • 作業は < 30 分 (調整オーバーヘッドは高すぎる)
  • 予算は固定で限定的 (シーケンシャルはより安価)
  • チームメイト パフォーマンスの高い分散 (不均等な完了)

コスト最適化のヒント

1. 検証に Haiku を使用 — Sonnet の代わり 75% より安価、同等の品質
2. チーム サイズを制限 — 3-4、真に独立したトラックが存在する場合を除き
3. 小さなタスクをバッチ処理 — 個別に割り当てるのではなく (調整オーバーヘッドを削減)
4. 積極的なタイムアウトを設定 (900 秒) — 停止したチームメイトに素早く失敗
5. 実際のスピードアップを監視 — 実際の時間 > シーケンシャルの 50% の場合、チーム サイズを削減

---

参照: teams-architect エージェント インタラクティブなチーム設計支援。