Claude Agent Teams 完全ガイド

はじめに

Claude Code の Subagent を使ったことがあれば、並行開発は十分にパワフルだと感じているかもしれません。しかし Subagent には制限があります：メイン Agent に結果を報告することしかできず、互いにコミュニケーションを取ることができません。

Agent Teams はこの状況を根本的に変えます。想像してみてください：1つの Agent がセキュリティレビューを担当し、もう1つがパフォーマンス最適化を担当し、3番目がテストカバレッジを担当する——並行して作業できるだけでなく、直接対話し、互いに挑戦し、コンセンサスに達することができます。これが Agent Teams の核心的な価値です。

Agent Teams を理解する

Agent Teams のアーキテクチャは、実際の開発チームによく似ています：

┌─────────────────────────────────────────────────────────┐
│                    あなた（ユーザー）                       │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│                    Team Lead                             │
│            （メイン Claude インスタンス、調整を担当）        │
└─────────────────────────────────────────────────────────┘
         │              │              │
         ▼              ▼              ▼
┌─────────────┐  ┌─────────────┐  ┌─────────────┐
│ Teammate 1  │  │ Teammate 2  │  │ Teammate 3  │
│ セキュリティ │◄─►│ パフォーマンス│◄─►│ テスト      │
│  レビュー    │  │  最適化      │  │  カバレッジ  │
└─────────────┘  └─────────────┘  └─────────────┘
         │              │              │
         └──────────────┼──────────────┘
                        ▼
              ┌─────────────────┐
              │   共有タスクリスト │
              └─────────────────┘

Subagent との違い

簡単に言えば：Subagent はタスクを実行するために派遣する下請け業者、Agent Teams は同じ部屋で協力するプロジェクトチームです。

なぜ Agent Teams が効果的なのか

核心的な洞察：専門化が集中をもたらす。

単一の Agent が複雑なマルチステップタスクを処理する際、コンテキストは膨張し続け、頻繁に /clear でリセットが必要になります。Agent Teams は各 Teammate に狭い専門領域を持たせ、コンテキストをクリーンに保ち、パフォーマンスをより安定させます。

Agent Teams の有効化

Agent Teams は現在実験的機能であり、デフォルトでオフになっています。手動で有効にする必要があります：

方法1：環境変数

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

方法2：settings.json（推奨、永続的に有効）

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

コアの使い方

最初の Agent Team を作成する

有効化後、自然言語で Claude にチームの作成を指示するだけです：

agent team を作成して PR #142 をレビューして。
3人のレビュアーを生成して：
- 1人はセキュリティ問題に焦点
- 1人はパフォーマンスへの影響をチェック
- 1人はテストカバレッジを検証
それぞれがレビューして発見を報告するようにして。

キーワードのヒント："create an agent team" または "spawn an agent team" を使用してください。"spawn agents" だけだと、Subagent と Agent Teams が混同される可能性があります。

表示モード

Agent Teams は2つの表示モードをサポートしています：

デフォルトは auto：tmux 内で実行している場合は split panes を使用し、それ以外は in-process を使用。

表示モードの設定：

{
  "teammateMode": "in-process"
}

単一セッションでの指定：

claude --teammate-mode in-process

よく使うショートカットキー

Delegate Mode（重要）

Delegate Mode は Agent Teams の最も重要な機能の1つです：

なぜ Delegate Mode が必要なのか：

この制限がないと、Lead は頻繁に「仕事を奪う」ことがあります——3人の Teammates が待っているにもかかわらず、Lead が自分でコードを書き始めてしまう。Delegate Mode を有効にすると、Lead は純粋なプロジェクトマネージャーに強制され、タスク管理、Teammates とのコミュニケーション、出力のレビューしかできなくなります。

# チームを起動したら直ちに Shift+Tab を押して有効化

実践事例

事例1：並行コードレビュー

単一のレビュアーは特定の種類の問題に深入りしがちです。レビューの次元を独立した領域に分割することで、セキュリティ、パフォーマンス、テストカバレッジすべてに同等の注意が払われます：

agent team を作成してこの PR をレビューして。3人のレビュアーを生成して：
- セキュリティレビュアー：認証、認可、インジェクション脆弱性をチェック
- パフォーマンスレビュアー：アルゴリズムの複雑度、データベースクエリ、キャッシュ戦略を分析
- テストレビュアー：テストカバレッジ、境界条件、エラーハンドリングを検証

各自がレビューした後、発見した問題について互いに議論するようにして。

事例2：競合的仮説デバッグ

根本原因が不明な場合、単一の Agent は一見もっともらしい説明を見つけたら停止する傾向があります。Teammates に互いに挑戦させることでこの問題を回避できます：

ユーザーからフィードバック：アプリがメッセージを1つ送信した後に接続を維持せずに終了する。

5つの agent teammates を生成して異なる仮説を調査して。互いに議論し、
互いの理論を反証しようとするように、科学的な討論のように。合意に達した
発見を調査レポートに更新して。

キーメカニズム：討論構造。複数の独立した調査者が積極的に互いの理論を覆そうとし、最終的に生き残った仮説が真の根本原因である可能性が高くなります。

事例3：コンテンツの大量生産

これは非技術タスクの典型的な適用——1つの入力を複数の出力に変換：

agent team を作成してこのビデオスクリプトを4つのプラットフォーム向けコンテンツに変換して：
- LinkedIn 記事ライター
- Twitter スレッドライター
- Newsletter ライター
- ブログ記事ライター

スクリプトの場所：/content/scripts/video-20.md

各 Teammate が独立して制作しつつ、コンテンツの一貫性を維持します。

事例4：QA 品質チェッククラスター

ブログウェブサイトの品質チェックで、5つの Agent を並行してデプロイして異なる側面をテスト：

agent team を作成してブログの包括的な品質チェックを実施して：
- Agent 1：コアページテスト（ホーム、アバウト、お問い合わせ）
- Agent 2：記事ページテスト（レンダリング、ナビゲーション、SEO メタデータ）
- Agent 3：リンクチェック（内部リンク、外部リンク、デッドリンク）
- Agent 4：SEO 検証（タイトル、説明、構造化データ）
- Agent 5：アクセシビリティテスト（ARIA ラベル、コントラスト、キーボードナビゲーション）

優先度順に並べた問題レポートを生成して。

効果：本来なら人手で順次実行する必要がある包括的なチェックを数分で完了し、各 Agent が自分の領域に集中し、最後に優先度順の問題リストに統合します。

事例5：マルチラウンドディスカッションモード

有用なプロンプトパターン——Teammates にミーティングのように議論させる：

Agent Teams を使って4つの teammates を作成して [技術的決定] について議論して、
3ラウンドのディスカッションを行って。各ラウンドで teammates が互いに交流するようにして。
そのうち1つの teammate は Red Team の視点を専門に担当し、批判的な意見を述べるようにして。

このモードは、アーキテクチャの決定や技術選定など、多角的な検討が必要なシナリオに特に適しています。

事例6：C コンパイラプロジェクト

Anthropic は16の Agent を使って、Linux カーネルをコンパイルできる C コンパイラをゼロから構築しました：

最終成果：x86、ARM、RISC-V でブート可能な Linux 6.9 をビルドできる Rust コンパイラ。

チーム管理

Teammates とモデルの指定

Claude はタスクに基づいて生成する Teammates の数を自動的に決定しますが、明示的に指定することもできます：

4つの teammates を作成してこれらのモジュールを並行してリファクタリングして。
各 teammate は Sonnet モデルを使用して。

計画の承認を要求

複雑またはハイリスクなタスクでは、Teammates に実行前にまず計画を策定するよう要求できます：

認証モジュールをリファクタリングするアーキテクト teammate を生成して。
変更を行う前に、計画の承認を要求するようにして。

Teammate が計画を完成すると、Lead に承認リクエストを送信します。Lead はレビュー後に承認するか、修正意見を返すことができます。

Teammates と直接対話

各 Teammate は完全な Claude Code セッションです。どの Teammate にも直接メッセージを送ることができます：

• In-process モード：Shift+Down で切り替え、メッセージを入力
• Split-pane モード：対応するペインを直接クリック

Teammates の終了

セキュリティレビューの teammate を終了して

Lead が終了リクエストを送信し、Teammate は承認するか拒否する（理由を説明して）ことができます。

チームのクリーンアップ

完了後、Lead にリソースをクリーンアップさせます：

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

重要：常に Lead を通じてクリーンアップしてください。Teammates にクリーンアップを実行させると、リソース状態の不整合が生じる可能性があります。

ベストプラクティス

チームサイズの制御

サイズの推奨：

経験則：各 Teammate に5-6個のタスクを割り当てるのが適切です。15個の独立したタスクがある場合、3人の Teammates が良い出発点です。

タスクの粒度

• 小さすぎる：調整のオーバーヘッドが効果を上回る
• 大きすぎる：Teammates がチェックポイントなしで長時間作業し、無駄のリスクが増加
• ちょうど良い：独立して完結し、成果物が明確な作業単位（1つの関数、1つのテストファイル、1つのレビューレポート）

ファイル衝突の回避

2人の Teammates が同じファイルを編集すると上書きが発生します。作業を分割する際は、各 Teammate が異なるファイルセットを担当するようにしてください：

Teammate 1：src/auth/ ディレクトリを担当
Teammate 2：src/api/ ディレクトリを担当
Teammate 3：src/utils/ ディレクトリを担当

監視とガイダンス

定期的に Teammates の進捗をチェックし、適切でない方向を早期に修正してください。チームを長時間監視なしで実行させると、無駄のリスクが増加します。

Lead がタスクを Teammates に待たせず自分で実装し始めた場合：

teammates がタスクを完了するのを待ってから続けて

十分なコンテキストを与える

Teammates はプロジェクトのコンテキスト（CLAUDE.md、MCP servers、skills）を自動的にロードしますが、Lead の会話履歴は継承しません。生成時に十分なタスクの詳細を提供してください：

セキュリティレビューの teammate を生成して、以下のプロンプトで：
"src/auth/ ディレクトリの認証モジュールのセキュリティ脆弱性をレビューして。
トークン処理、セッション管理、入力バリデーションに重点を置いて。
アプリケーションは httpOnly cookies に保存された JWT トークンを使用している。
発見を報告する際は深刻度の評価を添えて。"

セルフレポーティング検証モード

タスクの説明に明確な検証基準を含め、Teammates が完了後にセルフチェックを行うようにします：

タスク完了時に、Lead に以下を報告して：
1. チェックしたファイル
2. 発見した問題
3. 行った変更
4. 検証基準（テスト合格、lint 警告なしなど）が満たされたかどうか

このモードにより、Lead の検証作業量が減り、タスクが「完了したように見える」のではなく本当に完了していることが保証されます。

高度なテクニック

Hooks で品質ゲートを強制

Hooks を通じて Teammates が作業を完了した際にルールを強制実行します：

{
  "hooks": {
    "TeammateIdle": [
      {
        "command": "your-validation-script.sh"
      }
    ],
    "TaskCompleted": [
      {
        "command": "your-quality-check.sh"
      }
    ]
  }
}

• TeammateIdle：Teammate がアイドル状態になろうとする時に実行。exit code 2 を返すとフィードバックを送信して Teammate に作業を継続させる
• TaskCompleted：タスクが完了としてマークされた時に実行。exit code 2 を返すと完了をブロックしてフィードバックを送信

権限の事前承認

Teammate の権限リクエストは Lead にバブルアップし、頻繁な中断を引き起こす可能性があります。生成前に一般的な操作を事前に承認しておきます：

{
  "permissions": {
    "allow": [
      "Read(*)",
      "Write(src/**)",
      "Bash(npm test)"
    ]
  }
}

Worktree との組み合わせ

Agent Teams は Worktree と組み合わせて使用でき、各 Teammate が自身の worktree で作業できます：

agent team を作成して、各 teammate が独立した worktree で作業するようにして、
ファイル衝突を回避して。

サードパーティオーケストレーションツール

ネイティブの Agent Teams 以外に、コミュニティもいくつかのオーケストレーションツールを開発しています：

これらのツールは Agent Teams の実験的機能の代替を提供しますが、より多くの手動設定が必要です。ネイティブ Agent Teams がニーズを満たす場合は、公式機能の使用を優先することをお勧めします。

現在の制限事項

Agent Teams はまだ実験的機能であり、制限を理解することが重要です：

コストの考慮

Agent Teams の Token 消費はシングルセッションより大幅に高くなります：

コスト分析：

• 各 Teammate は完全に独立した Claude インスタンスで、独自のコンテキストを持つ
• Teammates 間のコミュニケーションも Token を消費
• Lead がすべての Teammates を調整するため、追加のオーバーヘッドが発生

いつ価値があるか：

• ✅ 並行探索が必要なリサーチタスク
• ✅ マルチビューレビュー（セキュリティ、パフォーマンス、テスト）
• ✅ 議論によるコンセンサスが必要な意思決定
• ❌ 順次完了できるルーティンタスク
• ❌ 相互通信が不要な並行タスク（Subagent の方が経済的）

私の使用感

いつ Agent Teams を使うか

私の判断基準：

1. タスクに複数の視点が必要：異なる領域の専門知識（セキュリティ + パフォーマンス + テスト）
2. 議論とコンセンサスが必要：競合的仮説、アーキテクチャの決定
3. 並行探索に価値がある：複数の実装方案の比較

並行実行だけが必要で、相互通信が不要な場合は、Subagent や Worktree の方が適しています。

リサーチとレビューから始める

Agent Teams 初心者なら、コードを書く必要がないタスクから始めてください：PR のレビュー、技術方案のリサーチ、バグの調査。これらのタスクは明確な境界があり、並行探索の価値を示すことができ、同時に並行実装に伴う調整の課題を回避できます。

他の機能との組み合わせ

おわりに

Agent Teams は、AI支援開発の新しいパラダイムを代表しています：「1つのAIアシスタント」から「1つのAIチーム」へ。

Anthropic は16の Agent を使い、2週間、$20,000で10万行のコードの C コンパイラを書き上げました。このプロジェクトの重要な教訓は：テスト品質が何より重要。Agent は与えられた問題を自律的に解決するため、タスクバリデータはほぼ完璧でなければなりません。そうでなければ Agent は間違った問題を解決してしまいます。

3つの核心ポイントを覚えておいてください：

始め方はシンプルです：

agent team を作成して [あなたのタスク]

関連記事：

• Claude Worktree 完全ガイド — Worktree と Agent Teams の連携を理解する
• Claude Subagent 完全ガイド — Subagent と Agent Teams のユースケースを比較する
• Tmux 快速入門ガイド — Tmux で複数の Agent セッションを管理する

参考資料：

• Claude Code 公式ドキュメント - Agent Teams
• Building a C compiler with a team of parallel Claudes
• Claude Code Agent Teams: The Complete Guide
• Multi-Agent Orchestration: Running 10+ Claude Instances in Parallel

動画チュートリアル：

• 7 Unexpected Use Cases for Claude Code Agent Teams — 7つの非技術ユースケースのデモ
• Claude Code Multi-Agent Workflows — マルチエージェントワークフローの詳細解説
• Agent Teams Orchestration Deep Dive — チームオーケストレーションの深掘り
• Claude Code Agent Teams Setup Guide — 完全なセットアップチュートリアル