Claude Code のマルチエージェント協調: Subagents と Agent Teams はどう使い分けるか

Claude Code でマルチエージェント協調を考えるとき、最も混同しやすいのが Subagents と Agent Teams です。どちらも「複数の Agent を動かして一緒に作業する」ように見えますが、実際には想定している使い方が異なります。簡単に言えば、前者は独立したタスクを切り出して処理するのに向いており、後者は複数の Agent が同じテーマについて継続的に協力し、相互に検証しながら進めるのに向いています。

もし Skill を使ったことがあるなら、まずは次のように理解すると分かりやすいです。

Skill は手順やルールを定義する
Subagent や Agent teammate は実際の作業を行う

つまり重要なのは、どちらが「上位」かではなく、どの種類の協調課題を解きたいのかです。

Subagents: サイドタスクを切り出す

Subagents は、現在のセッションから一時的に送り出す分身に近い存在です。各分身は独自のコンテキストウィンドウを持ち、作業後は結果の要約だけを返します。そのため、メインの会話は大量の中間ログや出力で埋まりにくくなります。

この仕組みには、実務上かなり分かりやすい利点があります。

メインスレッドがきれいなままで、テストログや検索結果、長い出力で汚れにくい
相互依存のない調査や実行タスクを並列化できる
「結果だけ返してくれればよい」タイプの仕事に向いている

元記事では、Claude Code には次の 3 種類の組み込み Subagent があると説明されています。

Explore: 読み取り専用で、コードベースの高速検索に向く
Plan: 読み取り専用で、plan mode 中のバックグラウンド情報収集に向く
General-purpose: 読み書き可能で、探索と編集を組み合わせる仕事に向く

カスタム Subagent

組み込みのものだけでは足りない場合は、自分で Subagent を定義できます。やり方はシンプルで、Markdown ファイルを用意するだけです。

.claude/agents/: 現在のプロジェクトでのみ有効
~/.claude/agents/: すべてのプロジェクトで有効

ファイル形式は次のようになります。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---
You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:

1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:

- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed
Provide feedback organized by priority:

- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

ここで特に重要なのは description です。Claude はこの説明を見て、いつこの Subagent を呼ぶべきか判断します。説明が正確であるほど、呼び出しの精度も上がりやすくなります。

ほかにも知っておくと便利な設定項目があります。

tools: 使用できるツールを制限する
model: sonnet、opus、haiku、inherit から選ぶ
permissionMode: 編集権限や権限プロンプトの挙動を制御する
memory: Subagent に対話をまたぐ記憶ディレクトリを与える

一時的にだけ使いたい場合は、CLI 経由で定義することもできます。

1
2
3
4
5
6
7
8


claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

Subagents が向いている場面

Subagents が特に向いているのは、たとえば次のような仕事です。

テストを実行し、数千行のログではなく失敗要約だけをメイン会話に返す
相互依存しない複数モジュールの調査を並列に進める
「問題を見つける」と「修正する」を単純なパイプラインに分ける

たとえば次のような指示です。

1

Research the authentication, database, and API modules in parallel using separate subagents

1

Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them

一方で、タスクが何度も往復しながら調整を要する場合、複数段階で大量の文脈を共有する場合、あるいは変更が一つ二つのファイルに集中している場合は、Subagent を立てるよりメイン会話で直接処理したほうが楽なことが多いです。

Agent Teams: 複数の独立セッションで協調する

Agent Teams は別のレイヤーの機能です。1 つのセッション内で分身を出すのではなく、完全に独立した複数の Claude Code インスタンスを起動し、共有タスクリストを中心に協調させます。しかも、メンバー同士が直接メッセージを送り合うこともできます。

そのため、単なるサイドタスク処理というより、本当に小さなチームを作る感覚に近いです。

元記事では、これはまだ実験機能であり、先に有効化が必要だと説明されています。

1
2
3
4
5


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

これを settings.json に追加すると、Claude に対して目的に応じた team を組ませることができます。たとえば次のような形です。

1
2
3


I'm designing a CLI tool that helps developers track TODO comments across
their codebase. Create an agent team to explore this from different angles: one
teammate on UX, one on technical architecture, one playing devil's advocate.

Agent Teams の構成

Agent Team は主に次の 3 つで構成されます。

Team lead: あなたが使っているメインセッション。編成、割り振り、要約を担当する
Teammates: 複数の独立した Claude Code インスタンス
Task list と Mailbox: 共有タスクリストとメッセージ経路

Subagents との最大の違いは、teammates 同士が直接やり取りできることです。毎回 lead を経由する必要はありません。タスク状態は通常 pending、in progress、completed の間を移り、1 つ終えた teammate は次のタスクを引き取ることもできます。

Agent Teams が向いている場面

複数視点からの検討、結論への異議申し立て、仮説同士の競合、あるいはモジュール単位の並列開発が必要なときは、Agent Teams のほうが適しています。

記事では次のような典型例が挙げられています。

同じ PR を複数 reviewer が並列でレビューし、それぞれ異なる観点を見る
同じ bug に対して複数の Agent が異なる仮説を立て、互いに反証する
フロントエンド、バックエンド、テストが別々の領域を並列で進める

たとえば並列コードレビューでは、次のように指示できます。

1
2
3
4
5


Create an agent team to review PR #142. Spawn three reviewers:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.

また、討論型のデバッグでは次のような使い方ができます。

1
2
3
4


Users report the app exits after one message instead of staying connected.
Spawn 5 agent teammates to investigate different hypotheses. Have them talk to
each other to try to disprove each other's theories, like a scientific
debate. Update the findings doc with whatever consensus emerges.

この種の仕事に共通しているのは、単に 1 つの答えが欲しいのではなく、複数の Agent が判断を持ち寄り、前提を揺さぶり合いながら、より確かな結論に収束していくことです。

どう使い分けるか

手早く判断したいなら、次のように覚えると分かりやすいです。

結果だけ持ち帰ればよいなら Subagents
議論や相互検証が必要なら Agent Teams

もう少し整理すると、主な違いは次の通りです。

通信方法: Subagents は主にメイン会話へ結果を返すが、Agent Teams はメンバー同士で直接やり取りできる
調整方法: Subagents はメイン会話側のオーケストレーションに依存しやすいが、Agent Teams は共有タスクリストをもとに各メンバーが自律的に動ける
Token コスト: Subagents のほうが軽く、Agent Teams は各 teammate が独立インスタンスのため高くなりやすい
向いている仕事: Subagents は独立性が高く結果志向の仕事向き、Agent Teams は議論や相互検証が重要な仕事向き

実運用で気をつけたいこと

Agent Teams は強力ですが、だからといってすべてのタスクで team を組むべきというわけではありません。記事では特に次のような現実的な注意点が挙げられています。

token 消費が明らかに大きい
複数 teammate が同じファイルを同時に編集すると、上書き競合が起きやすい
teammate が多すぎると調整コストが増え、成果が伸びるとは限らない

そのため、比較的安全な進め方としては次のようになります。

まずは 3〜5 人程度の teammate から始める
モジュールやファイル単位で仕事を分け、編集衝突を避ける
lead が早まって teammate の仕事に手を出し始めたら、先に待つよう明示する

また、現時点の実験版には次のような制約もあります。

/resume と /rewind で in-process teammates を復元できない
タスク状態が遅れて反映され、手動での更新が必要になることがある
1 人の lead が同時に扱える team は 1 つだけ
teammate がさらに子 team を作ることはできない

まとめ

この 2 つの機能は、互いの代替ではありません。解いている協調課題そのものが違います。

目的が「サイドタスクを並列化し、メインの文脈をきれいに保つこと」なら、まずは Subagents を使うのが自然です。目的が「複数の Agent に小さなチームのように協力させ、議論し、相互検証させること」なら、Agent Teams が向いています。

実際のタスクで一度試してみると、違いはかなり早く体感できます。片方は文脈の分離と結果回収に強く、もう片方は多視点での協調と継続的なやり取りに強い、という違いです。