Claude CodeのSubAgentとAgent Teamsの違い — 並列実行とコラボレーションで見分ける

複数の Issue を抱えてしまった日、ふと「これ、子エージェントに分担させたら一気に片付くのでは？」と思ったことはないでしょうか。Claude Code には子エージェントに仕事を任せる仕組みが大きく分けて 2 つあります。SubAgent（Agent ツールでワーカーを起動する方式）と、Agent Teams（チームメイトを立ててお互いに通信させる方式）です。

最初のうちは「並列で動かしたいなら Agent Teams 一択」「SubAgent はワンショットの使い捨て、Agent Teams はステートを持つチーム」と整理していました。ところが両方を実機で触って公式ドキュメントを読み込んでみると、思っていたのとはずいぶん違う対比軸が見えてきました。

たとえば SubAgent も SendMessage で resume でき、履歴を保持したまま再開できます。しかも長期継続の耐性については、むしろ SubAgent の方が強いという結果になりました。

この記事ではその「逆転現象」を軸に、両者の本当の違いがどこにあるのかを整理していきます。Claude Code 自体を触ったことがある前提で書いているので、まだの方はClaude Code入門に先に目を通しておくと読みやすいかもしれません。

注意: Agent Teams は本記事執筆時点（2026 年 5 月、Claude Code v2.1.126）で research preview 扱いの実験機能で、有効化には環境変数の設定が必要です。今後仕様や API 名は変わる可能性があるので、記事内のコマンド例・挙動は現時点のスナップショットとして読んでください。

そもそも何が違うのか（5秒サマリー）

ざっくりした全体像を先に出しちゃいます。詳細は後の節で展開していきます。

ポイントは 2 つ。まず「永続化の有無」では両者は区別できません。両者とも履歴は永続化されるし、両者とも resume できます。そのうえで本当の違いは「何人で・どう協働するか」というコラボレーション粒度に出てきます。

SubAgent: 思っていたより長生きだった

起動方法

SubAgent は Agent ツールを 1 回呼ぶだけで起動します。準備物はゼロ。description、prompt、subagent_type を渡せばすぐ走り出してくれます。

{
  "tool": "Agent",
  "params": {
    "description": "READMEのtypo修正",
    "prompt": "README.md のスペルミスを修正してコミットまでしてください",
    "subagent_type": "developer"
  }
}

~/.claude/agents/ に置いた Markdown 定義（あるいはビルトイン）をベースに、子エージェントが立ち上がる仕組みです。

並列性: 単一メッセージで複数を並べる

意外と知られていない（or 忘れられがちな）事実なんですが、単一メッセージ内で複数の Agent ツール呼び出しを並べると並列実行されます。親はすべての完了を待ってから次のターンに進む同期型です。

[親 Claude のターン]
  ├── Agent(description="Issue #101 を実装") ─┐
  ├── Agent(description="Issue #102 を実装") ─┼─ 並列実行
  └── Agent(description="Issue #103 を実装") ─┘
                            ↓
                  すべて完了 → 親が結果を統合

実機で試したときも、3 件直列なら 30 秒積み上がるはずの処理が、並列だとほぼ 1 件分の時間で終わりました。「複数 Issue を並列に捌く」だけなら、わざわざ Agent Teams を引っ張り出さなくても十分なことが多いです。

戻り値: テキスト + agentId + メタデータ

SubAgent は完了すると、最終応答テキスト、agentId、<usage> メタデータ（消費トークン量など）を親に返します。中途経過は親に届かず、完了した瞬間にドンと結果が来るモデルです。

ここで返ってくる agentId が、あとで resume するときの鍵になります。

resume できる ─ 公式が明文で保証

ここが今回いちばん意外だったところ。SubAgent は使い捨てじゃないんです。完了して停止した SubAgent に SendMessage(to: <agentId>) を投げると、過去の会話履歴を保持したまま自動で resume してくれます。

公式ドキュメント sub-agents には、resume 後の挙動と起動条件がしっかり書いてあります。

Resumed subagents retain their full conversation history, including all previous tool calls, results, and reasoning. The subagent picks up exactly where it stopped rather than starting fresh.

If a stopped subagent receives a SendMessage, it auto-resumes in the background without requiring a new Agent invocation.

実際に試してみると、SendMessage を投げた瞬間に次のシステムメッセージが返ってきました。

{
  "success": true,
  "message": "Agent \"a8f48875f87f5dc76\" had no active task;
              resumed from transcript in the background with your message.
              You'll be notified when it finishes."
}

resume された SubAgent は、最初のタスクで書き込んだファイルパス・タイムスタンプ・内容を、記憶だけで完全に再現してきました。LLM レベルでコンテキストを保持してなきゃ起こり得ない挙動です。これは正直、想定外でした。

transcript の永続化先と保持期間

SubAgent の会話履歴は親セッションごとに JSONL ファイルとして保存されてます。

~/.claude/projects/{project-hash}/{sessionId}/subagents/
  ├── agent-{agentId}.jsonl       # 会話履歴
  └── agent-{agentId}.meta.json   # メタ情報

公式ドキュメントには保持期間と再開条件が次のように書いてあります。

Session persistence: Subagent transcripts persist within their session. You can resume a subagent after restarting Claude Code by resuming the same session.

Automatic cleanup: Transcripts are cleaned up based on the cleanupPeriodDays setting (default: 30 days).

親セッションを claude --resume <session-id> で蘇らせれば、別の Claude Code プロセスからも同じ SubAgent に追加指示を投げられるってことです。プロセス境界をまたいだ resume が公式サポートされてる、と。けっこう気前のいい仕様だなと思います。

resume の実例

resume 用の SendMessage 呼び出しはこんな感じです。

// 1. SubAgent を起動して agentId を受け取る
Agent({
  description: "ファイル編集タスク",
  subagent_type: "developer",
  prompt: "README.md に1行追記してください"
})
// 戻り値: agentId: "abc123..."

// 2. （あとから）同じ SubAgent に追加指示
SendMessage({
  to: "abc123...",  // SubAgent の agentId
  message: "さっき編集した README にもう1行追加してください"
})
// → SubAgent が履歴を保ったまま再開（resumed from transcript）

補足: SendMessage を使うには CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 の有効化が必要です。「Agent Teams 専用ツールでしょ？」って思いがちなんですけど、公式 Tools reference には「teammate へのメッセージ送信」と「agentId による subagent resume」の両方が用途として併記されてます。

Agent Teams: チームでコラボするための仕組み

有効化

Agent Teams は環境変数で明示的に有効化が必要です。~/.claude/settings.json か shell の export で指定します。

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

公式ドキュメントは Agent Teams をはっきり「token-intensive」って位置づけてます。

Agent teams use significantly more tokens than a single session. Each teammate has its own context window, and token usage scales with the number of active teammates. For research, review, and new feature work, the extra tokens are usually worthwhile. For routine tasks, a single session is more cost-effective.

軽い気持ちで常用するというより「ここぞ」のとき使う運用が現実的なんだと思います。

正規のフローは「自然言語で lead に頼む」

Agent Teams のチーム作成・メンバー起動って、ユーザーが構造化 API を直接叩くもんじゃなくて、自然言語で lead（メインセッション）に依頼するのが正規フローなんです。公式 agent-teams の “Start your first agent team” 節がこの点をズバッと言ってます。

After enabling agent teams, tell Claude to create an agent team and describe the task and the team structure you want in natural language. Claude creates the team, spawns teammates, and coordinates work based on your prompt.

公式サンプル:

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.

手元で試したときも、こんな感じで頼むだけで lead が TeamCreate を呼んで、teammate を spawn して、shared task list にタスクを並べてくれました。

（環境変数 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 を設定した上で）

「Issue #A-001 と #B-002 を並行で進めるエージェントチームを作って。
 dev-A と dev-B の2人体制で、それぞれ developer サブエージェント定義を使ってほしい。
 dev-A は #A-001、dev-B は #B-002 を担当して、両者の進捗は私に逐次報告して」

注意: 構造化された Agent({team_name: "...", name: "...", ...}) みたいな呼び出しは、ユーザーが直接叩く API ではないので注意です。これは lead が内部で発行してるツール呼び出しを観察しただけで、Tools reference の Agent 行には team_name パラメータの記載がありません。あくまで実装詳細で、experimental である以上シグネチャは将来変わると思っていてください。

in-process と split panes の2モード

Agent Teams は teammate の表示モードを 2 種類持ってます。公式ドキュメントの記述を整理するとこんな感じ。

既定値は "auto" で、tmux セッション内なら split panes、そうじゃなければ in-process が選ばれます。明示したいときは ~/.claude/settings.json に teammateMode を書きます（CLI フラグ --teammate-mode in-process でも切り替え可）。

{
  "teammateMode": "in-process"
}

手元で tmuxPaneId: "in-process" が観察されたのは、tmux 外で起動して auto が in-process を選んだ結果でした。「tmux 必須」「最新版で in-process が既定」と決めつけちゃうと正確じゃないので、起動環境によって auto が切り替わる、くらいに覚えておくのが安全です。

shared task list と Mailbox

Agent Teams のアーキテクチャは、公式ドキュメントだとこんなコンポーネントで説明されてます。

ファイル上の永続化先はこの 2 か所です。

~/.claude/teams/{team-name}/config.json   # チーム設定 + runtime state
~/.claude/tasks/{team-name}/              # 共有タスクリスト

補足: 検証で見つけた ~/.claude/teams/<team>/inboxes/<member>.json のような inbox 構造は、公式 docs の Architecture 節には書かれてない実装詳細です。公式は Mailbox という抽象でしか言及してないので、ファイル名や JSON 構造に依存したスクリプトを書くなら将来変わる前提でいた方が無難です。

peer 通信 ─ teammate 同士が会話できる

SubAgent との決定的な差のひとつが、teammate 同士で直接 SendMessage を投げ合えるところ。公式ドキュメントには次のようにあります。

Teammate messaging: send a message to one specific teammate by name. To reach everyone, send one message per recipient.

SubAgent ではこれができません。SubAgent 同士は会話できず、すべての通信が親 ↔ 子の 1 対 1 に閉じる作りです。

[SubAgent: 親が司令塔。子同士は会話しない]

         親
       ↗ ↑ ↘
      / | \
   子A 子B 子C

[Agent Teams: peer 通信が可能]

         lead
       ↗ ↑ ↘
      / | \
   T1 ←→ T2 ←→ T3
   （teammate 同士で SendMessage）

「設計者と実装者で議論しながら進める」「複数の仮説を立てた調査担当が互いに反証し合う」みたいな、peer 通信そのものが必要なシナリオになると Agent Teams が活きてきます。

「決定的な違い」は別のところにあった

ここまで両者を別々に見てきましたが、次は重ねて眺めてみます。本当の対比軸がどこにあるのかを浮かび上がらせるパートです。

共通している仕組みを整理する

まず共通点をまとめておきます。

• transcript はディスクに永続化される（SubAgent: ~/.claude/projects/.../subagents/、Agent Teams: 同左 + チーム配下）
• SendMessage で resume できる（to に渡す値が agentId か teammate-name かの違い）
• subagent 定義（~/.claude/agents/*.md）を再利用できる
• 会話履歴を保持できる（resume すれば過去のコンテキストを引き継ぐ）

「ステートフルなのは Agent Teams だけ」という思い込みは、ここでガラガラと崩れます。

逆転現象: 長期継続耐性は SubAgent の方が高い

ここで強調しておきたいのが、Agent Teams の in-process teammate は /resume で復元されない、という事実です。公式 agent-teams#limitations にもしっかり書いてあります。

No session resumption with in-process teammates: /resume and /rewind do not restore in-process teammates. After resuming a session, the lead may attempt to message teammates that no longer exist. If this happens, tell the lead to spawn new teammates.

一方の SubAgent は、さっき見たとおり claude --resume <session-id> のあとに SendMessage(to: <agentId>) で蘇らせられます。両者の対比を図にするとこんな感じです。

[SubAgent]
  Claude Code 起動 → 親セッションで Agent 起動 → agentId 取得
  ⏏ Claude Code 終了
  ⏵ claude --resume <session-id> で別プロセス起動
  ⏵ SendMessage(to: <agentId>)
  ✅ "resumed from transcript in the background"

[Agent Teams]
  Claude Code 起動 → 自然言語で lead にチーム作成依頼 → teammate 起動
  ⏏ Claude Code 終了
  ⏵ /resume で復活
  ❌ in-process teammate は復元されない（公式 limitation）
  → lead に新しい teammate を spawn し直してもらう必要あり

つまり「長期間にわたって履歴を引き継ぎながら作業したい」というニーズには、むしろ SubAgent の方が向いてるんです。これ、最初の下書きを書いてた時点では完全に逆に思い込んでいて、今回の記事を書き直す動機そのものになりました。

じゃあ、Agent Teams の本当の差別点は何？

「永続化」でも「ステート保持」でもないとなると、Agent Teams ならではの価値ってどこ？という話になります。残るのはこの 4 点です。

1. peer 通信: teammate 同士が直接メッセージを送り合える
2. 状態可視化: shared task list と Mailbox で進捗・通信履歴を構造化管理
3. team 単位のライフサイクル: TeamCreate / TeamDelete で明示的にチームを生成・解散
4. メンバー切替 UI: in-process モードでの Shift+Down 切替、split panes での独立ペイン

公式が「Use agent teams when teammates need to share findings, challenge each other, and coordinate on their own」と書いてるのは、まさにここを指してるんだと思います。

リライトした比較表

ここまでの整理を踏まえて、対比表を作り直しました。SendMessage を共通項として両側に置いて、to に渡す値の違いで見せてます。

いつどっちを使うか

判断材料を、ここまでの整理に沿ってまとめ直します。

SubAgent が向いていそうなケース

• 互いに独立した Issue や調査を並列に一気に捌きたい
• 1 回投げて結果を回収すれば終わる、ワンショットの作業
• 親の会話を汚さず、コンテキストを分離して効率化したい
• できるだけ token を節約して動かしたい
• 長丁場でも履歴を引き継いで何度も呼び出したい（resume 耐性が高い）
• まだ実験機能には踏み込みたくない

Agent Teams が向いていそうなケース

• 複数メンバーがリアルタイムで議論・並列実装したい
• teammate 同士の peer 通信が本質的に必要な作業（仮説の反証、設計と実装のキャッチボール、レビュー往復など）
• shared task list で 進捗を可視化したい
• メンバーごとに役割（実装担当・レビュー担当など）を固定し、UI 上でも見分けたい
• token-intensive を許容できる場面

「長期継続したい」は判断基準にならない

ここが前回記事との最大の違いです。「長期継続したいから Agent Teams」という選び方は、結論から言うと誤りでした。両者とも resume できるし、/resume 耐性に関しては SubAgent の方が高いからです。長期継続そのものは判断基準にならなくて、選ぶときに見るべきは「peer 通信が必要か」「複数メンバーの状態を可視化したいか」のほうなんです。

自サイトでの実践メモ

このブログ自体も Claude Code をフル活用して運営してて、~/.claude/agents/ にはレビュー担当・記事ライター・チームリーダーなど 17 個くらいサブエージェント定義が置いてあります。普段の記事執筆や軽い修正は SubAgent で十分まわっていて、resume を活用すれば「数日越しのレビュー反映」みたいな作業もいけました。

サブエージェント定義そのものの書き方はClaude CodeのCLAUDE.md書き方ガイドにまとめてます（tools allowlist や model 指定の挙動を実機ベースで書いた記事）。Agent Teams の teammate も同じ subagent 定義を再利用できるので、定義側をちゃんと整えておくと両方で使い回せて便利です。

機能開発みたいな「設計 → 実装 → レビュー指摘 → 修正」を行き来する場面は、SubAgent の resume でも Agent Teams の peer 通信でも、どっちでも実現できます。今回の検証を踏まえて出した結論はシンプルで、peer 通信が要らないなら SubAgent + resume で十分。token も節約できるしお手軽です。

エージェント自体の作り方や考え方をもうちょっと深掘りしたい方は、opencodeのソースから読み解くAIコーディングエージェントの処理フローも合わせてどうぞ。サブエージェントがどうやってコンテキストを分離してるか、実装側から眺める視点が掴めます。

今後の展望

ここまで見てきた Agent Teams の便利さを眺めてると、peer 通信や shared task list を SubAgent 側だけで再現できないかという問いも気になってきます。agentId を使った継続呼び出しと、外部ファイルでの擬似タスクリスト管理を組み合わせれば、安定機能の範囲でどこまで Team 風の運用ができるか。別記事のネタとして温めておこうと思います。

注意（再掲）: Agent Teams は research preview です。本記事の挙動は v2.1.126 時点のスナップショットで、API 名やシグネチャは予告なく変わる可能性があります。プロダクションへの組み込みは慎重に判断してください。

まとめ

• SubAgent と Agent Teams は「ステート保持の有無」では区別できない: 両方とも transcript は永続化されるし、両方とも SendMessage で resume できる
• 真の対比軸はコラボレーション粒度: SubAgent は親 ↔ 子の 1 対 1、Agent Teams は teammate 同士の peer 通信
• 逆転現象: 長期継続耐性はむしろ SubAgent の方が高い（Agent Teams の in-process teammate は /resume で復元されない）
• Agent Teams の差別点: peer 通信、shared task list、Mailbox、team 単位のライフサイクル、メンバー切替 UI
• 判断基準: 「peer 通信が必要か」「状態を可視化したいか」で選ぶ。「長期継続したい」は判断基準にならない
• 公式ドキュメントを読むの大事: 思い込みで対比軸を立てると、平気で逆の結論が出ます（出ました）

ヒヨリ

あたしもね、最初は「SubAgent は使い捨てで、Agent Teams は状態を持つチーム」って思い込んでたんだけど、実は両方とも transcript は永続化されてて、SendMessage(to: <agentId>) で SubAgent もちゃんと resume できるんだよね！ 本当の違いはコラボレーション粒度で、親↔子の1対1で動かしたいのか、それとも teammate 同士の peer 通信 でワイワイ協調させたいのか、って軸で選ぶのが大事なんだって。しかも面白いのが、長期継続耐性は SubAgent の方が高いっていう逆転現象もあるの。Agent Teams の in-process teammate は /resume で復元されないから、そこは要注意なんだよね。やっぱり思い込みで使い分けちゃう前に、公式ドキュメントをちゃんと読むのって大事だなあって改めて思ったよ。さあ、試してみよう！