トップ > Claude Code > Claude Code Agent Teams入門

Claude Code Agent Teams入門

Claude Code
記事タイトルとURLをコピーする

Claude Code Agent Teams入門

こんにちは、サーバーワークスで生成AIの活用推進を担当している針生です。

Claude CodeにAgent Teamsという実験的機能が追加されました。複数のClaude Codeインスタンスを「チーム」として協調させ、並列に作業を進められる機能です。

この記事では、Agent Teamsのセットアップから実践的な活用例まで紹介します。

セットアップ

Agent Teamsは現時点では実験的機能のため、デフォルトでは無効になっています*1。有効にするには、環境変数を設定します。前提として、Claude Codeがインストール済みであることが必要です。

方法1: settings.jsonに追加

~/.claude/settings.json に以下を追加します。

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

プロジェクト単位で有効にしたい場合は、プロジェクトルートの .claude/settings.json に同じ内容を書きます。

方法2: シェルの環境変数

一時的に試したい場合は、シェルで環境変数を設定してからClaude Codeを起動します。

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude

設定後、Claude Codeを起動して「3人のチームを作って」のようにチーム作成を指示してみてください。Agent Teamsが有効になっていれば、チーム名の提案やチームメイトの起動が始まります。チーム作成に関する反応がなければ、設定の記述ミスやClaude Codeの再起動を確認してください。

具体例で理解するAgent Teams

3つの活用パターンを、難易度順に紹介します。

例1: 並列コードレビュー（入門向け）

最初に試すなら、読み取り専用のタスクがおすすめです。ファイルの同時編集による競合の心配がなく、Agent Teamsの動きを安全に体験できます。

シナリオ: PRのレビューを3つの観点で同時に行う

PR #42 をレビューするチームを作って。
- セキュリティ担当: 脆弱性や入力バリデーションを確認
- パフォーマンス担当: N+1クエリやメモリ使用量を確認
- テスト担当: テストカバレッジと境界値テストを確認

この指示を送ると、以下のように進みます。

  1. Leadが3人のチームメイトを起動
  2. 各チームメイトがそれぞれの観点でPRを並列レビュー
  3. 各チームメイトがLeadに結果を報告
  4. Leadが3つのレビュー結果を統合して報告

1人でレビューすると、最初に見つけた問題（例えばセキュリティ）に意識が引っ張られ、他の観点（パフォーマンスやテスト）が手薄になりがちです。専門の担当者に分けることで、多角的なレビューが実現します。

ポイント: 読み取り専用のタスクはファイル競合のリスクがなく、Agent Teamsの入門に最適です。

例2: フルスタック機能開発（実践的）

次のステップとして、ファイルの所有権を分けた並列実装を試してみましょう。

シナリオ: 決済機能をバックエンド・フロントエンド・テストに分けて並列開発

決済機能を開発するチームを作って。
- バックエンド担当: src/api/payments/ 配下のAPIエンドポイントを実装
- フロントエンド担当: src/components/payment/ 配下のUIコンポーネントを実装
- テスト担当: tests/payments/ 配下のテストスイートを作成
各担当者は自分のディレクトリ内のファイルのみを編集してください。
バックエンドがAPIの型定義を先に作り、それを基に他のチームメイトが作業を進めて。

ここでのポイントはタスクの依存関係です。「バックエンドの型定義完了」を待ってからフロントエンドとテストが開始する、という順序をLeadに指示すれば管理してくれます。

もう1つの重要なポイントはファイルの所有権です。上の指示例のように、各チームメイトが担当するディレクトリを明示的に指定します。同一ファイルを複数のチームメイトが編集すると上書き競合が発生するため、これは必須の工夫です。

ポイント: 並列実装ではファイルの所有権を明確に分けることが成功の鍵です。

例3: 競合仮説デバッグ（応用）

Agent Teamsの真価が発揮されるのが、チームメイト同士の対話を活用した競合仮説デバッグです。

シナリオ: 原因不明のバグに対して複数の仮説を同時検証

本番環境でWebSocket接続が1分後に切断される問題を調査するチームを作って。
- 仮説A担当: サーバー側のタイムアウト設定を調査
- 仮説B担当: ロードバランサーのkeep-alive設定を調査
- 仮説C担当: クライアント側のハートビート実装を調査
互いの発見を共有し、仮説を検証・反証し合ってください。

単独セッションでのデバッグでは、最初に思いついた仮説（例えば「タイムアウト設定が原因だろう」）に固執してしまいがちです。競合仮説アプローチでは、3つのチームメイトがそれぞれ異なる仮説を同時に検証し、互いの発見を直接メッセージで共有します。

例えば、以下のような対話が行われます。

  • 仮説A担当 → Lead:「サーバー側のタイムアウトは120秒に設定されていて問題なさそうです」
  • 仮説B担当 → 仮説A担当:「それならロードバランサーのアイドルタイムアウトが60秒なので、これが原因の可能性が高いですね」
  • 仮説C担当 → 仮説B担当:「クライアント側のハートビートが55秒間隔なので、タイミング次第では間に合わないかもしれません」

このように、チームメイト同士が直接情報交換し、仮説を絞り込んでいきます。

ポイント: チームメイト同士が直接やり取りし、仮説を反証し合えるのはAgent Teamsならではの強みです。

Agent Teamsの仕組み

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

Claude Codeには、単一セッション内でサブプロセスを起動する「サブエージェント」という機能もあります。サブエージェントは結果を親セッションに返すだけですが、Agent Teamsのチームメイトは独立したコンテキストウィンドウを持ち、チームメイト同士で直接やり取りしながら協調できます。サブエージェントが「ちょっとこれ調べてきて」と頼む部下なら、チームメイトは「それぞれの専門領域を持つプロジェクトメンバー」に近いイメージです。

詳しい比較は公式ドキュメントを参照してください。

アーキテクチャ

Agent Teamsは、Lead（指揮役のメインセッション）・チームメイト（独立したClaude Codeインスタンス）・タスクリスト（共有のタスク一覧）・メールボックス（メッセージング機構）の4つのコンポーネントで構成されます。

ワークフローの流れやパーミッション、メッセージングの仕組みなど、アーキテクチャの詳細は公式ドキュメントを参照してください。

使いこなすためのTips

まずは読み取り専用タスクから

初めてAgent Teamsを使う場合は、リサーチやコードレビューなど読み取り専用のタスクから始めましょう。ファイルの競合リスクがなく、チームの動きを安全に理解できます。慣れてきたら、ファイルの所有権を分けた並列実装に進むのがおすすめです。

チームメイトにはコンテキストを十分に渡す

チームメイトはLeadの会話履歴を引き継ぎません。プロジェクトの設定ファイル（CLAUDE.mdなど）は読み込みますが、それまでLeadと話していた内容は知りません。

チーム作成の指示に、作業に必要な背景情報を含めるのが重要です。

# コンテキストが不足した指示
セキュリティレビューするチームメイトを作って

# コンテキストを十分に含めた指示
src/auth/ の認証モジュールをセキュリティレビューするチームメイトを作って。
JWTトークンをhttpOnlyクッキーに保存する方式を使っている。
トークン処理、セッション管理、入力バリデーションに注目してレビューして。

Delegate ModeでLeadの暴走を防ぐ

チームを作成しても、Leadが自分で実装を始めてしまうことがあります。Shift+Tab を押してDelegate Modeに切り替えると、Leadの操作がチームの指揮（タスク管理、メッセージング、チームメイトの管理）に制限されます。

自然言語で「チームメイトの作業が完了するまで待って」と伝えるのも有効です。

plan modeでチームメイトの行動を制御する

チームメイトをplan modeで動作させると、実装前に計画を作成し、Leadの承認を得てから実装に移ります。チームメイトが勝手にコードを書き始めるのを防げるため、複雑なタスクやリスクの高い変更で有効です。

チーム作成時に「チームメイトはplan modeで動作させて」と指示してください。

チームメイトのモデルにSonnetを指定してコストを抑える

Agent Teamsのチームメイトは、デフォルトではLeadと同じモデル（通常はOpus）で動作します。しかし、チームメイトのモデルにSonnetを指定することで、コストを大幅に抑えられます。

指定方法は、チーム作成時の指示にモデルを含めるだけです。

決済機能を開発するチームを作って。チームメイトにはSonnetを使って。
- バックエンド担当: src/api/payments/ 配下のAPIエンドポイントを実装
- フロントエンド担当: src/components/payment/ 配下のUIコンポーネントを実装

公式ドキュメントにも以下のような例が示されています。

Create a team with 4 teammates to refactor these modules in parallel.
Use Sonnet for each teammate.

公式ドキュメントでは「チームメイトにはSonnetを使うことで、コーディネーションタスクに対して能力とコストのバランスが取れる」と推奨されています。Leadが全体を指揮する役割である一方、チームメイトは与えられたタスクを実行する役割です。チームメイトにSonnetを使うことで、Leadの高い判断力を維持しつつ、チーム全体のコストを抑える運用ができます。

チームメイトの操作方法

表示モード 条件 チームメイトの切り替え
In-process（デフォルト） 通常のターミナル Shift+Up/Down で選択
Split panes tmuxまたはiTerm2環境 各チームメイトのペインをクリック

In-processモードでは、Shift+Up/Downでチームメイトを選択し、直接メッセージを送れます。Split panesモードでは、各チームメイトが独立したペインを持ち、クリックで直接操作できます。なお、Split panesモードを使うにはtmuxまたはiTerm2が必要です。VS Codeの統合ターミナルなどでは利用できません。

知っておくべき注意点

実験的機能である

Agent Teamsは現時点で実験的機能です。今後、挙動が変更される可能性があります。

トークンコストが大きい

各チームメイトが独立したコンテキストウィンドウを持つため、トークン消費量は大きく増加します。公式ドキュメントによると、チームメイトがplan modeで動作する場合、単一セッションの約7倍のトークンを消費します。plan modeを使わない場合でも、チームサイズに応じてトークン消費量は増加します。前述のチームメイトのモデルにSonnetを指定する方法を活用する、チームを小さく保つなど、コストを意識した運用が必要です。

セッションの復元制限

/resume や /rewind でセッションを復元しても、In-processモードで起動したチームメイトは復元されません。復元後にLeadが存在しないチームメイトにメッセージを送ろうとすることがあるため、その場合は新しいチームメイトを起動し直してください。

向かないケース

以下のような場面では、Agent Teamsのオーバーヘッドが利点を上回ります。

  • 順次的なタスク: 前の作業結果に依存する連鎖的な作業
  • 同一ファイルの編集: 上書き競合が発生する
  • 単純なタスク: 1つのセッションで十分に完結する作業

まとめ

Agent Teamsは、複数のClaude Codeインスタンスを「チーム」として協調させる実験的機能です。トークンコストが大きい点には注意が必要ですが、並列性が活きる場面では強力なツールになりそうです。

コードレビューのような読み取り専用タスクからAgent Teamsを試してみてください。

この記事のまとめイラスト

参考文献

*1:Anthropic. "Orchestrate teams of Claude Code sessions." Claude Code Docs. https://code.claude.com/docs/en/agent-teams

針生 泰有(執筆記事の一覧)

サーバーワークスで生成AIの活用推進を担当