Home / Blog / Claude Codeのサブエージェントと Agent Teams——どっちをいつ使うのか設計ロジックを整理した

Claude Codeのサブエージェントと Agent Teams——どっちをいつ使うのか設計ロジックを整理した

Claude Codeのサブエージェントと Agent Teams——どっちをいつ使うのか設計ロジックを整理した

Claude Codeのサブエージェント（Task tool）とAgent Teams（マルチセッション）の違いを設計レイヤで解説。タスクの粒度・コンテキスト分離・コスト効率で使い分ける判断基準。

Claude CodeサブエージェントAgent Teamsアーキテクチャ

エンジニアのゆとです。

Claude Codeで複数のタスクを並列実行しようとすると、最初に壁にぶつかる。

「サブエージェントってどう使えばいいんだ」「Agent Teamsって公式ドキュメントで見かけたけど、サブエージェントと何が違うのか」——同じ「並列処理」という言葉で語られるが、設計思想がぜんぜん違う。

これを混同したまま使うと、コンテキストが無駄に太ったり、逆にオーバーエンジニアリングで管理コストが爆増したりする。

この記事では、サブエージェント（Task tool）とAgent Teamsの違いを設計レイヤで整理して、「このタスクはどっちで処理すべきか」の判断基準をまとめる。

サブエージェントとは何か（Task tool）

まずサブエージェントの定義から整理する。

Claude Codeのサブエージェントとは、メインセッションのコンテキスト内から起動される、独立したClaude Codeインスタンスのことだ。

内部的にはTask toolという仕組みで動いている。メインのClaudeが「このサブタスクは分けて処理しよう」と判断すると、別のClaude Codeプロセスを起動してタスクを委譲し、結果だけをメインに返す。

# プロンプトでサブエージェントを明示的に起動する例
claude "src/components/ 以下のコンポーネントを全部レビューして
問題があれば review_report.md にまとめて。
これはサブタスクとして並列実行してほしい"

あるいはCLAUDE.mdや会話の中で明示的に指示することもできる：

以下の3つのタスクを並列でサブエージェントに実行させてほしい:
1. tests/ 以下の全テストを実行してエラーを収集する
2. src/ 以下の未使用インポートを検出する
3. docs/ の内容が実装と一致しているか確認する

サブエージェントの特徴

サブエージェントはメインセッションと同じ プロセス空間 に属している。

  • メインセッションが持つファイルアクセス権限・MCPサーバー接続をそのまま引き継ぐ
  • メインのコンテキストウィンドウとは別のコンテキストを持つ（コンテキスト分離）
  • タスク完了後にサブエージェントのコンテキストは解放される（メインは汚染されない）
  • サブエージェント同士で通信はできない（それぞれメインに結果を返す）

コンテキスト分離が最大のメリットだ。たとえば「src/ 以下の全ファイルを読んでドキュメントを生成する」というタスクをメインセッション内でやると、大量のファイル内容がコンテキストに積み重なって、その後の応答精度が落ちる。サブエージェントに任せれば、完了後にそのコンテキストはリリースされる。メインのセッションに残るのは「生成されたドキュメント」という結果だけだ。

Agent Teamsとは何か

Agent Teamsは、複数の独立したClaude Codeセッションを協調させるアーキテクチャだ。

サブエージェントとの最大の違いは「独立性」にある。Agent Teamsでは各エージェントが完全に独立したプロセスとして動き、ファイルシステムや共有ストレージを通じて情報を交換する。

Anthropicの公式ドキュメントでは、Agent Teamsは「orchestrator + workers」パターンで説明されている。

Orchestrator（司令塔）
     │
     ├──▶ Worker A（データ収集）
     ├──▶ Worker B（分析）
     └──▶ Worker C（レポート生成）

Orchestratorが全体のタスクを把握して各Workerに指示を出し、Workerはそれぞれ独立して作業する。Workerの完了状態はファイルやデータベースに書き込まれて、Orchestratorがポーリングで把握する。

Agent Teamsを構成する具体的な方法

現実的なAgent Teamsの実装パターンをいくつか挙げる。

パターン1: Bashスクリプトで複数セッションを起動

#!/bin/bash
# orchestrator.sh — 3つのClaude Codeセッションを並列起動する

# 共有ディレクトリの準備
mkdir -p /tmp/agent-workspace/{input,output,status}

# Worker A: コードの静的解析
claude --print "src/以下のコードを静的解析してIssueを /tmp/agent-workspace/output/issues.json に書け" &
PID_A=$!

# Worker B: テスト実行と結果収集
claude --print "テストを全部実行して結果を /tmp/agent-workspace/output/test_results.json に書け" &
PID_B=$!

# Worker C: ドキュメント生成
claude --print "src/以下からJSDocを読んでAPIドキュメントを /tmp/agent-workspace/output/api_docs.md に書け" &
PID_C=$!

# 全Worker完了待ち
wait $PID_A $PID_B $PID_C

echo "全Worker完了。Orchestratorが結果をまとめる..."

# Orchestratorが結果を統合
claude --print "
/tmp/agent-workspace/output/ にあるissues.json・test_results.json・api_docs.md を読んで
プロジェクトの健全性レポートを /tmp/agent-workspace/output/final_report.md にまとめよ"

パターン2: Python SDKでプログラマティックに制御

import asyncio
import anthropic
import subprocess
from pathlib import Path

async def run_worker(task_description: str, output_path: str) -> str:
    """Claude Codeのヘッドレスセッションをサブプロセスで起動する"""
    result = subprocess.run(
        ["claude", "--print", "--no-color", task_description],
        capture_output=True,
        text=True
    )
    Path(output_path).write_text(result.stdout)
    return output_path

async def run_agent_team():
    """3つのWorkerを並列実行するOrchestrator"""
    tasks = [
        run_worker(
            "src/api/ 以下の全エンドポイントを一覧化してJSONで出力せよ",
            "/tmp/endpoints.json"
        ),
        run_worker(
            "src/以下で型エラーになっている箇所を全部見つけてJSONで出力せよ",
            "/tmp/type_errors.json"
        ),
        run_worker(
            "tests/以下のカバレッジが50%未満のモジュールを特定してJSONで出力せよ",
            "/tmp/low_coverage.json"
        ),
    ]
    
    # 3つを並列実行
    results = await asyncio.gather(*tasks)
    print(f"完了したWorkerの出力: {results}")

asyncio.run(run_agent_team())

パターン3: —output-format stream-json でリアルタイム監視

# Workerの進捗をリアルタイムで監視する
claude --output-format stream-json --print "大規模リファクタリングを実行" | \
  python3 -c "
import sys, json
for line in sys.stdin:
    event = json.loads(line)
    if event.get('type') == 'assistant':
        print(f'Worker進捗: {event[\"message\"][\"content\"][0][\"text\"][:100]}...')
"

判断フローチャート：どちらを使うか

「サブエージェント vs Agent Teams」の選択基準を整理すると、以下の3軸で判断できる。

タスクの独立性
      │
      ├── 完全に独立している（成果物がファイルに書ける）
      │         │
      │         ├── 長時間実行・大規模処理 → Agent Teams
      │         └── 短時間・小さいタスク → サブエージェントでも可
      │
      └── メインセッションとの連携が必要
                │
                └── サブエージェント

もう少し具体的な判断基準として、以下を目安にしている。

判断軸サブエージェントAgent Teams
セッション寿命メインセッションと同じ独立（何時間でも動ける）
コンテキストメインから分離、完了後解放完全に独立したウィンドウ
成果物の受け渡し直接メインに返すファイル/DBを経由
適切なタスク粒度数分〜十数分で終わるもの数十分〜数時間かかるもの
オーバーヘッド低い高い（セットアップ・監視が必要）
障害時の影響メインセッションに伝播しうる独立して失敗できる

サブエージェントが適するケース

調査・収集系タスク

「ファイルを大量に読んで情報を抽出する」系のタスクはサブエージェントの典型的なユースケースだ。

src/以下の全コンポーネントを読んで、
propsの型定義がないものを一覧化してリストにして返せ

このタスクをメインセッションでやると、数十ファイルの内容がコンテキストに積み上がる。サブエージェントに任せれば、結果だけが返ってくる。

並列で走らせる小さいタスク群

独立した小タスクを並列処理したい場合も、サブエージェントが向いている。

以下の3つを並列で処理してほしい（サブエージェントで同時実行）:
1. package.jsonの依存パッケージのうち、最新でないものを調べてリストアップ
2. README.mdの内容が src/と矛盾している箇所を見つけて指摘
3. ESLintエラーが多いファイルTOP5を特定

コンテキスト汚染を防ぎたいとき

大きなファイルを読ませるタスクや、大量のツール呼び出しが発生するタスクは、サブエージェントで分離するとメインの応答精度が維持されやすい。

具体的には「1000行超のファイルを分析する」「テスト全件を実行して結果を解析する」などが該当する。

Agent Teamsが適するケース

大規模リファクタリング・複数リポジトリをまたぐ作業

単一リポジトリの全体的なリファクタリングや、マイクロサービス群の横断的な変更は、Agent Teamsが向いている。

理由は「完了まで時間がかかるから」だ。Claude Codeのセッションはコンテキストウィンドウに制限があるため、数時間にわたる大規模作業はセッションを跨ぐ設計が必要になる。Agent Teamsでワーカーを独立させれば、各ワーカーが自分のスコープだけに集中できる。

# マイクロサービスの全サービスに対して同時にセキュリティスキャンをかける
for service in auth payment notification analytics; do
    claude --print "
    /services/${service}/ のコードを全部読んで
    セキュリティ上の問題を /tmp/scan/${service}_report.md に書け。
    特に認証・入力検証・依存パッケージのCVEに注目すること。
    " &
done
wait
echo "全サービスのスキャン完了"

長時間実行が前提のバッチ処理

夜間に走らせる処理、大量データの変換・移行、継続的な監視ループなど、「終わるまで待てない」タスクはAgent Teamsが適している。

# 夜間バッチ: 1000記事のSEOメタデータを一括更新する（LaunchAgent経由）
for i in $(seq 0 9); do
    # 10並列で100記事ずつ処理
    START=$((i * 100))
    END=$((START + 99))
    
    claude --print "
    /content/articles/ から記事${START}番〜${END}番を読んで
    SEOメタデータ（title・description）を最適化し、
    元ファイルを上書き保存せよ。
    完了したら /tmp/batch/status_${i}.done を作成せよ。
    " &
done
wait

独立して失敗できる必要があるとき

「Worker AがFailしても、Worker BとCは続けてほしい」という要件があるなら、Agent Teamsが適切だ。サブエージェントの場合、失敗はメインセッションに伝播しうる。Agent Teamsなら各Workerが完全に独立しているため、失敗の影響が局所化される。

実践例: 両方を組み合わせた設計

実際の開発フローでは、サブエージェントとAgent Teamsを組み合わせる設計が最も実用的だ。

以下は「大規模なコードレビューパイプライン」の設計例。

[Orchestrator（Agent Teams層）]
  ├── Worker 1: 変更ファイルの収集とグルーピング
  │     └── 内部でサブエージェント × 3 を使って並列レビュー
  ├── Worker 2: テスト実行と結果分析
  │     └── 内部でサブエージェント × 2（ユニット・E2E）
  └── Worker 3: ドキュメント整合性チェック
        └── 単体で実行（サブエージェント不要）

[Orchestrator がまとめて最終レポートを生成]

Worker 1の中身を具体化すると：

# worker1.sh — 変更ファイルをグルーピングしてサブエージェントに渡す

CHANGED_FILES=$(git diff --name-only main...HEAD)

# ファイルをレイヤー別にグルーピング
API_FILES=$(echo "$CHANGED_FILES" | grep "^src/api/")
UI_FILES=$(echo "$CHANGED_FILES" | grep "^src/components/")
UTIL_FILES=$(echo "$CHANGED_FILES" | grep "^src/utils/")

# Worker 1 内部のサブエージェント（メインのClaude Codeセッション内で並列実行）
claude --print "
以下の3つのコードレビューをサブエージェントで並列実行せよ:

1. APIレイヤーのレビュー対象: ${API_FILES}
   観点: RESTful設計、エラーハンドリング、バリデーション

2. UIコンポーネントのレビュー対象: ${UI_FILES}
   観点: アクセシビリティ、props設計、パフォーマンス

3. ユーティリティのレビュー対象: ${UTIL_FILES}
   観点: 副作用、テスタビリティ、命名

各レビュー結果を統合して /tmp/worker1_output.md に書け
"

この設計のポイントは「粒度の使い分け」だ。

  • 上位（Orchestrator/Worker間）: プロセス分離が必要なため Agent Teams
  • 下位（Worker内の処理）: メインセッションで済む粒度のため サブエージェント

何でも Agent Teams にするとセットアップとモニタリングのコストが無視できなくなる。何でもサブエージェントにするとセッション寿命の制限に引っかかる。適切な粒度で使い分けるのが現実的な落とし所だ。

コスト・コンテキスト効率の比較

最後にコストとコンテキスト効率の観点でまとめる。

トークンコストの考え方

サブエージェントを起動するたびに、新しいClaude Codeインスタンスが立ち上がり、そのインスタンスもインプットトークンを消費する。つまり サブエージェントのコンテキスト量 × 起動数 だけ追加コストが発生する。

Claudeのモデル別インプットコスト（2026年4月時点）：

モデルインプットキャッシュヒット
Claude 3.5 Haiku$0.80/Mトークン$0.08/Mトークン
Claude Sonnet 4$3.00/Mトークン$0.30/Mトークン

コスト観点での指針として：

  • サブエージェントは「小さく・短く」使う。コンテキストが大きくなるほどコストが比例して増える
  • CLAUDE.mdはPrompt Caching対象なので、サブエージェントを多数起動してもキャッシュが効いてコストが抑えられる（繰り返し参照されるコンテキストはキャッシュヒット率が高い）
  • Agent TeamsでMax planを使う場合、月の使用量枠を複数セッションで共有する点に注意。長時間稼働するWorkerが枠を大量に使うと、他の作業に支障が出ることがある

レイテンシの実態

Agent TeamsでWorkerを並列に走らせると、処理時間の合計を並列数で割ったような改善が期待できる——ただし現実はもう少し複雑だ。

Claude Codeはレート制限があるため、大量のWorkerを同時起動すると個々の応答が遅くなる場合がある。Max planでも同時並列数の実質的な上限は体感で5〜8セッション程度で、それ以上は速度改善が鈍化する印象だ（公式なスペックではなく個人の観測値）。

実用上は「3〜5並列」が費用対効果の最適点に近い。それ以上は管理コストとレート制限のデメリットが増える。

コンテキスト消費の比較

シナリオ: 1000ファイルのコードレビュー

【メインセッションだけで実行した場合】
コンテキスト消費: ファイル全内容 + 会話履歴 ≒ 数十万トークン
問題: 中盤以降から応答精度が低下する

【サブエージェント × 10 で分割した場合】
メインコンテキスト消費: 最終結果のみ ≒ 数千〜数万トークン
各サブエージェント: 100ファイル分 ≒ 数万トークン（完了後に解放）
効果: メインの精度を維持できる

【Agent Teams（Worker × 10）で分割した場合】
同上。加えて各Workerが独立したセッションなのでメインは一切汚染されない
ただし: セットアップ・監視のオーバーヘッドが発生

まとめ

サブエージェントとAgent Teamsの使い分けを一言でまとめると：

  • サブエージェント: メインセッション内でコンテキストを分離したいとき。数分〜十数分で終わる小さなタスクの並列化。オーバーヘッドが低く、気軽に使える。
  • Agent Teams: 完全に独立したプロセスが必要なとき。長時間実行、複数リポジトリ横断、障害を局所化したい場合。設計コストが高いぶん、大規模タスクでスケールする。

実務でよくあるのは「まずサブエージェントで試して、セッション寿命が問題になったらAgent Teamsに移行する」という段階的なアプローチだ。最初からAgent Teamsを設計するのは、タスクの複雑さが確定してからでも遅くない。

「並列処理できるかも」と思ったら、まずサブエージェントで十分かどうかを確認する。それが一番コスパのいい出発点だと思っている。

記事が見つかりません:

記事が見つかりません:

記事が見つかりません:

// 関連記事

Claude Code × Vercel デプロイ自動化 — git push から本番反映まで AI に任せる

Claude Code × Vercel デプロイ自動化 — git push から本番反映まで AI に任せる
AI Agent 時代のシークレット管理設計 — Vault・SSO・MCP の3層アーキテクチャ

AI Agent 時代のシークレット管理設計 — Vault・SSO・MCP の3層アーキテクチャ
Claude Code エラー復旧パターン集——タスク失敗から立ち直る7つのテクニック

Claude Code エラー復旧パターン集——タスク失敗から立ち直る7つのテクニック
Claude Code × TDD の正しい分業——人間が失敗テストを書き、AIが実装する「2人羽織」パターン

Claude Code × TDD の正しい分業——人間が失敗テストを書き、AIが実装する「2人羽織」パターン
← 記事一覧に戻る