Claude Codeを使い込んでいくと、ある時点でシングルセッションの限界を感じ始めます。「セキュリティレビューと機能実装を同時に進めたい」「複数の仮説を並行して検証したい」、そんな場面で選択肢に上がるのが Agent Teams です。
Agent Teamsは、複数のClaude Codeインスタンスが文字通りチームを組んで動く仕組みです。2025年現在はまだ実験的な機能ですが、使いこなせれば並列開発の武器になります。有効化からチーム起動、メンバーへの直接指示まで、コピペで試せる形で並べました。
前提条件
- Claude Code v2.1.32 以降が必要です。
claude --versionで確認してください - 機能は実験的（Experimental）であり、デフォルトでは無効です
- セッション再開（
/resume）との組み合わせに既知の制限があります
有効化する
Agent Teamsはデフォルトで無効です。環境変数 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS を 1 にセットすることで有効になります。
恒久的に有効にするには ~/.claude/settings.json に追記するのが楽です。
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
これだけです。以降はセッションを起動するたびに自動で有効化されます。
Subagentsとの違いを先に整理する
Agent Teamsを初めて聞いた方が混乱しやすいのが「Subagentsと何が違うの？」という点です。ここが理解できると、使いどころが明確になります。
| 観点 | Subagents | Agent Teams |
|---|---|---|
| コンテキスト | 独自のコンテキストウィンドウを持ち、結果を呼び出し元に返す | 独自のコンテキストウィンドウを持ち、完全に独立して動く |
| コミュニケーション | メインエージェントにのみ結果を返す | チームメンバー同士が直接メッセージを送り合う |
| 調整方法 | メインエージェントが全作業を管理する | 共有タスクリストでセルフコーディネーション |
| 向いている作業 | 結果だけ必要な集中型タスク | 議論・コラボレーションが必要な複雑な作業 |
| トークンコスト | 低め：結果だけが返ってくる | 高め：各チームメンバーが独立したClaudeインスタンス |
一言でまとめると、Subagentsは「指示して結果をもらう」、Agent Teamsは「チームメンバー同士が議論しながら動く」です。
チームメンバー同士が直接やり取りできるかどうかが最大の差分です。
最初のAgent Teamを起動する
有効化したら、自然言語でチームを作るよう指示するだけです。Claude側がチームを組成し、メンバーをスポーンし、タスクを割り振ります。
CLIツールのコードベースのTODOコメントを追跡するツールを設計しています。
Agent Teamを作って異なる角度から検討してください。
- UX担当のチームメンバー1人
- 技術アーキテクチャ担当のチームメンバー1人
- 悪魔の代弁者（批判的視点）担当のチームメンバー1人
それぞれが独立して探索した後、知見を統合してください。
このプロンプトが機能する理由は、3つの役割が互いに依存せず並列で動けるからです。UX担当が終わるのを待ってアーキテクチャ担当が動く必要がない。これがAgent Teamsが効く典型例です。
起動後、リード（メインターミナル）にはチームメンバーの一覧と現在の作業が表示されます。 Shift+Down でメンバーを切り替えながら直接メッセージを送ることができます。
表示モードを選ぶ
Agent Teamsには2つの表示モードがあります。
in-process モード（デフォルト）
全メンバーがメインターミナル内で動きます。Shift+Downでメンバーを切り替えて直接操作できます。どのターミナルでも動くので追加セットアップは不要です。
split panes モード
tmuxかiTerm2があれば各メンバーが独立したペインに表示されます。全員の出力を同時に見られるのがメリットです。
モードを固定したい場合は ~/.claude.json に記述します。
{
"teammateMode": "in-process"
}
1回だけ切り替えるならフラグで指定できます。
claude --teammate-mode in-process
split panesモードにはtmuxのインストールが必要です。
# macOS
brew install tmux
# tmuxセッション内でClaude Codeを起動する
tmux new-session -s claude
claude
split panesモードはVS Codeの統合ターミナル、Windows Terminal、Ghosttyでは動きません。これらの環境ではin-processモードを使ってください。
チームメンバーに直接指示を送る実践例
チームを起動したら、リード経由だけでなくメンバーに直接話しかけることができます。これがAgent Teamsの地味に便利な部分です。
たとえば並列コードレビューをさせる場合：
PR #142 をレビューするAgent Teamを作ってください。
レビュアーを3人スポーンしてください。
- セキュリティの影響を確認する担当
- パフォーマンスへの影響をチェックする担当
- テストカバレッジを検証する担当
それぞれがレビューして知見を報告するようにしてください。
途中でセキュリティ担当に追加の視点を与えたい場合は、in-processモードなら Shift+Down でそのメンバーに切り替えて直接入力します。
認証トークンの有効期限処理も合わせて確認してください
リードを介さず直接届くので、作業が細かくコントロールできます。
仮説検証チームの作り方
バグの原因が不明確なときに特に効果的なパターンです。複数の仮説を並行検証させて、メンバー同士が互いの理論を否定しようとする構造を作ります。
ユーザーが1つメッセージを送った後にアプリが切断されると報告しています。
5人のAgent Teamsを作って異なる仮説を調査させてください。
互いの理論を否定しようとするよう、科学的ディベートの形式で議論させてください。
emergence した合意をfindings.mdに記録してください。
単一のエージェントに調査させると、最初に見つけた「もっともらしい原因」に引きずられがちです。複数のメンバーが別々に調査して互いを批判する構造にすると、生き残った仮説が真の原因である可能性が上がります。
チームサイズの目安として、3〜5人のメンバーが調整コストとパラレル効果のバランスが取れています。メンバーあたり5〜6タスクが割り当てられる規模が目安です。15個の独立タスクがあれば3人チームが出発点としてちょうどいい計算です。
Plan approval で変更前に確認する
破壊的な変更や重要なリファクタリングでは、実装前にプランを確認したいことがあります。メンバーに plan approval を要求すると、承認があるまで読み取り専用のプランモードで動きます。
認証モジュールをリファクタリングするアーキテクトのメンバーをスポーンしてください。
変更を加える前にプランの承認を要求するようにしてください。
メンバーがプランを提出するとリードにレビューリクエストが届きます。リードが承認すれば実装フェーズへ、却下するとフィードバックを受けてプランを修正して再提出します。
リードの承認基準を細かく制御したい場合はプロンプトに条件を加えます。
テストカバレッジを含まないプランは承認しないでください
データベーススキーマを変更するプランは却下してください
Hooksでクオリティゲートを設ける
チームメンバーの動作にフックを設定することで、タスク完了の品質を強制できます。
| フック名 | 発火タイミング | exit code 2の効果 |
|---|---|---|
TeammateIdle |
メンバーがアイドル状態になる前 | フィードバックを送って作業を継続させる |
TaskCreated |
タスクが作成されるとき | タスクの作成を防いでフィードバックを送る |
TaskCompleted |
タスクが完了とマークされるとき | 完了を防いでフィードバックを送る |
たとえば「テストなしのタスクは完了にしない」を強制する場合は TaskCompleted フックでテストファイルの存在を確認してexit code 2を返す、という構成になります。
チームの後始末
作業が終わったらリードにクリーンアップを指示します。
チームをクリーンアップしてください
ただし、まだ動いているメンバーがいるとクリーンアップは失敗します。先にメンバーをシャットダウンしてから実行するのが正しい順序です。
リサーチャーのメンバーにシャットダウンするよう伝えてください
クリーンアップは必ずリードから実行してください。メンバー側からクリーンアップを実行すると、チームのコンテキストが正しく解決されずリソースが不整合な状態に残ることがあります。
tmuxのセッションが残ってしまった場合は手動で削除します。
tmux ls
tmux kill-session -t <session-name>
よくあるハマりポイント
メンバーがエラーで止まる
in-processモードならShift+Downで該当メンバーに切り替えて出力を確認します。追加指示を直接送るか、代替メンバーをスポーンして作業を引き継がせます。
リードが委任せず自分で作業を始める
自分で作業を進める前に、チームメンバーがタスクを完了するのを待ってください
と指示するとリードが待機モードに入ります。
パーミッションの確認が頻発する
メンバーのパーミッションリクエストはリードにバブルアップしてきます。よく使う操作は事前にパーミッション設定で承認しておくと割り込みが減ります。
タスクが stuck に見える
メンバーがタスクを完了とマークし忘れることがあります。実際の作業は終わっているのにステータスが更新されない場合は、リードに「このタスクのステータスを更新するようメンバーに伝えて」と指示するか、手動でステータスを更新します。
チームの内部構造
仕組みを知っておくと設定変更やトラブル対応に役立ちます。
チームのデータはローカルに保存されます。
~/.claude/teams/{team-name}/config.json # チーム設定
~/.claude/tasks/{team-name}/ # タスクリスト
config.json はClaude Codeが自動管理するファイルで、手動編集するとチームの状態更新時に上書きされます。再利用可能なメンバーロールを定義したい場合はSubagent定義を使います。
security-reviewer エージェントタイプを使って、authモジュールを監査するメンバーをスポーンしてください
Subagent定義の tools 許可リストと model 設定はメンバーに引き継がれます。ただし skills と mcpServers のフロントマターフィールドは適用されない点に注意が必要です。メンバーのスキルとMCPサーバーはプロジェクトおよびユーザー設定から読み込まれます。
Agent Teamsは「並列探索」のためのツール
Agent Teamsはすべての作業に向いているわけではありません。同じファイルを複数のメンバーが編集すると上書きが起きますし、順序依存のタスクでは単一セッションの方がシンプルです。
向いているのは、独立して動ける作業を複数同時に走らせたい場面です。コードレビューの視点を分割する、バグの原因仮説を並行検証する、フロントエンド・バックエンド・テストを別々のメンバーが担当する、といったユースケースで真価を発揮します。
Agent Teamsを試すなら、コードを書かないタスクから始めるのが安全です。PRのレビューや調査タスクなら、並列探索の効果が分かりやすく、ファイルの競合リスクもありません。感触を掴んでから並列実装に挑戦するのが安全なステップアップです。