Claude Code サブエージェント 使い方｜Task tool・Agent Teams・並列処理完全ガイド

Claude Code のサブエージェントは、独立したコンテキストウィンドウで動く専用のAIアシスタントで、.claude/agents/ にMarkdownで定義するだけで作成できます。現時点（2026年4月）では、以前 Task tool と呼ばれていた機能が Agent tool にリネームされ（v2.1.63）、さらに複数エージェントを並列に動かす Agent Teams も実験的機能として利用可能です。

この記事でわかること:

• サブエージェントの作成方法と呼び出し方（3通りずつ）
• frontmatterで設定できる全フィールドの意味と使いどころ
• 並列処理のやり方と「サブエージェント／Agent Teams／Skills」の使い分け
• Agent Teams（実験的機能）の有効化と現行の制限
• CLAUDE_CODE_SUBAGENT_MODEL を使ったコスト最適化
• 権限・セキュリティ設計と実運用でのトラブル対処

想定読者は、Claude Code を日常的に使っていて 「メイン会話の文脈を汚さずに特定のタスクを任せたい」「並列でリサーチや実装を走らせたい」 と考えているエンジニア・テックリードです。

Claude Code のサブエージェントとは

サブエージェント（Subagents）は、Claude Code 内で呼び出せる特化型のAIアシスタントです。メイン会話とは別のコンテキストウィンドウで動作し、結果の要約だけを親会話に返すのが最大の特徴です。

公式ドキュメントでは次のように定義されています。

サブエージェントは、特定の種類のタスクを処理する特化した AI アシスタント。独立したコンテキストウィンドウで動作し、結果の要約のみをメイン会話に返す。

具体的なメリットは次の5つです。

• コンテキスト保持 — 探索や長大な出力でメイン会話のトークンを消費しない
• 制約強制 — tools フィールドで使えるツールをホワイトリスト化できる（読み取り専用レビュアなど）
• 設定再利用 — ユーザーレベル（~/.claude/agents/）に置けば全プロジェクトで共通利用
• 動作特化 — 用途別に最適化したシステムプロンプトを書ける
• コスト制御 — メインはOpus、サブはHaiku/Sonnetといったモデル使い分けが可能

一方で重要な制限があります。サブエージェントは別のサブエージェントを生成できません（無限ネスト防止）。多段委譲が必要な場合は Skills か、メイン側からのチェーン呼び出しで設計します。

サブエージェント・Agent tool・Agent Teams の違い

Claude Code 周辺は名称が紛らわしいため、最初に整理しておきます。

Agent tool は旧 Task tool のリネームです。v2.1.63 で名称変更されましたが、Task(...) 記述はエイリアスとして引き続き動作します。新規作成では Agent(...) を使うのが公式推奨です。

サブエージェントと Agent Teams は別物です。サブエージェントは「親が子を呼び出して結果を受け取る」モデル、Agent Teams は「チームメイト同士が直接メッセージで会話しながら共同作業する」モデルという違いがあります。

サブエージェントの作成方法（3通り）

公式に用意された作成方法は3つあります。慣れないうちは（A）、チームに配布したくなったら（B）、一時的に試すなら（C）が目安です。

(A) /agents コマンドで対話的に作る（推奨）

Claude Code セッション中に /agents を実行すると、対話形式でサブエージェントを作成できます。

1. Claude Code 内で /agents と入力
2. Library タブ → Create new agent を選択
3. 保存スコープを指定
   • Personal: ~/.claude/agents/ （全プロジェクト共通）
   • Project: .claude/agents/ （現プロジェクトのみ）
4. Generate with Claude で自然言語から自動生成、または手動設定
5. ツール・モデル・色・メモリスコープを選んで保存

画面上でフィールドごとに説明が出るので、初回はこの方法がいちばん事故が少ないです。

(B) Markdownファイルを手動で作成

.claude/agents/ 配下に YAML frontmatter 付きの Markdown ファイルを置くと、その場でサブエージェントとして認識されます。

---
name: code-reviewer
description: Reviews code for quality and best practices. Use proactively after code changes.
tools: Read, Glob, Grep
model: sonnet
---

You are a senior code reviewer. When invoked, analyze the diff and provide
specific, actionable feedback on quality, security, and best practices.
Return findings grouped by severity: Critical / Major / Minor.

ファイルの読み込み優先順位は以下の通りです。同名のサブエージェントが複数あると、上位が優先されます。

チームで共有する場合は プロジェクトの .claude/agents/ をGitでバージョン管理するのが公式推奨です。

(C) --agents CLIフラグでセッション限定に定義

ワンショットで試したいときは、CLIフラグでJSON形式のエージェント定義を渡せます。

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"
  }
}'

このセッションが終われば定義も消えるため、CI/CDで一時的に注入する用途にも向きます。

サブエージェントの呼び出し方（3通り）

作成したサブエージェントは、次の3通りで呼び出します。

プロジェクトで常に特定のエージェントをデフォルト化したい場合は、.claude/settings.json に以下を追加します。

{
  "agent": "code-reviewer"
}

「確実に走らせたい」ときは @-mention、「判断を任せたい」ときは自然言語で依頼、が基本です。

frontmatter フィールド完全ガイド

2026年4月現在、サブエージェントのfrontmatterでサポートされている主なフィールドは次の通りです。

フル機能を使った例が以下です。hooks や memory は2025年後半以降に追加された新しい仕様なので、競合記事でもあまり解説されていません。

---
name: db-migrator
description: Plans and applies database migrations safely. Use for Postgres/MySQL schema changes.
tools: Read, Grep, Bash(psql:*), Edit
model: claude-sonnet-4-6
permissionMode: acceptEdits
memory: project
isolation: worktree
effort: high
color: blue
---

You are a database migration specialist...

isolation: worktree を指定すると、サブエージェントは一時的なgit worktreeで作業し、無変更なら自動クリーンアップ、変更があればパスとブランチが結果に返ります。本番リポジトリへ直接変更を入れずに安全に検証したいときに便利です。

ビルトインサブエージェント一覧

Claude Code には標準で複数のサブエージェントが同梱されています。自分で作る前に、まずはビルトインで足りないかを確認してください。

Explore はHaikuベースなので、大規模リポジトリを安価に検索したいときの定番です。逆に変更も伴う探索では general-purpose を選びます。

並列処理の方法：サブエージェント vs Agent Teams

サブエージェントを複数同時に動かす方法は2パターンあります。結果だけ欲しい単発の並列ならサブエージェント、討議や相互チェックが必要な持続的な並列なら Agent Teams が公式の使い分けです。

パターン1: サブエージェントを並列に呼び出す

メイン会話から一度に複数のサブエージェントを呼ぶと、並列に実行されて結果が集約されます。

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

並列に向くケースと不向きなケースを整理します。

並列が効くケース:

• 3つ以上の独立したタスクがある
• タスク間に共有状態がない（同じファイルを書き換えない）
• 研究・調査系（書き込みなし）

逐次にすべきケース:

• タスク間に依存関係がある（後続が前の出力を必要とする）
• 同一ファイルを編集する
• 処理順序が結果に影響する

ドメイン分割パターン（フロントエンド／バックエンド／DBで別エージェントに割る）が最も成功率が高く、公式ベストプラクティスでも推奨されています。

パターン2: フォアグラウンド vs バックグラウンド

並列実行はフォアグラウンド（メインをブロック）／バックグラウンド（並行実行）の2通りから選べます。

バックグラウンド化は「run this in the background」とClaudeに依頼するか、実行中に Ctrl+B で切り替えます。無効化したい場合は環境変数 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 を設定します。

パターン3: 持続的な並列が必要なら Agent Teams

「複数のエージェントが互いに議論しながら結論を出す」ようなケースは、サブエージェントでは表現できません。Agent Teams はチームメイト同士が直接メッセージでやり取りでき、共有タスクリストで自己調整できる仕組みで、この用途に向いています。

サブエージェントと Agent Teams の違いは以下の通りです。

Agent Teams の使い方（実験的機能）

Agent Teams は v2.1.32 以降で使える実験的機能です。現時点では本番ワークフローに組み込むより、リサーチ・PRレビューなどの非致命的なタスクから試すのが安全です。

有効化手順

1. Claude Code のバージョンを確認: claude --version
2. CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 を設定

settings.json に直接書く例:

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

表示モードの選択

~/.claude.json に "teammateMode": "in-process" で固定、または claude --teammate-mode in-process でセッション単位で指定できます。

推奨チーム規模

公式ベストプラクティスでは、3〜5人チーム／1人あたり5〜6タスクが推奨されています。15個の独立タスクがあるなら3人チームから始め、明確な恩恵があるときだけスケールします。多すぎると調整オーバーヘッドで収穫逓減します。

公式ユースケース：PRレビューの並列化

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.

公式ユースケース：敵対的多重仮説デバッグ

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.

現行の制限事項

公式ドキュメントに明記されている既知の制限です。

• /resume や /rewind は in-process のチームメイトを復元しない
• タスクステータス更新が遅延し、依存タスクがブロックされることがある
• 1セッションで1チームのみ管理可能
• チームメイトは新しいチームを作れない（ネスト不可）
• team lead は固定（昇格・移譲不可）
• 権限はスポーン時のteam leadのモードを継承

設定ファイルは ~/.claude/teams/{team-name}/config.json、共有タスクリストは ~/.claude/tasks/{team-name}/ に保存されます。

Task tool から Agent tool へのリネーム（v2.1.63）

v2.1.63 で Task ツールが Agent ツールに名称変更されました。既存の Task(...) 記述はエイリアスとして引き続き動作するため、すぐに書き換えなくても動きます。新規に書く場合は Agent(...) を使います。

# 新しい書き方：サブエージェント生成をworker/researcherに限定
tools: Agent(worker, researcher), Read, Bash

# 括弧なし：すべてのサブエージェント生成を許可
tools: Agent, Read, Bash

# Agent を tools から外すと、サブエージェント生成不可

Agent(agent_type) 構文で生成できるサブエージェントの型を絞り込めます。ただしこれが効くのは claude --agent で起動されたメインスレッドのみで、サブエージェント自身は別のサブエージェントを生成できない制約があるため、サブエージェント側の tools に書いても意味がありません。

コスト最適化のベストプラクティス

並列化は便利ですが、何もしないとトークン消費は並列数に応じて線形に増えるため、コスト視点の設計が重要です。

1. CLAUDE_CODE_SUBAGENT_MODEL でサブのモデルを一括ダウングレード

環境変数一発で、全サブエージェントのモデルを上書きできます。

export CLAUDE_CODE_SUBAGENT_MODEL="claude-sonnet-4-6"

メインはOpus、サブはSonnetという組み合わせは、品質を落とさずコスト圧縮する鉄板パターンです。Explore のような検索特化エージェントはそもそもHaikuなので、さらに安価です。

2. ビルトインで足りるなら自作しない

Explore / Plan / general-purpose はモデル・ツール制約まで最適化済みです。自作前にビルトインのどれかで代替できないかを必ず確認します。

3. 過度な並列化を避ける

• 無駄にエージェント数を増やさない（3〜5人が目安）
• 曖昧な指示（"Fix authentication" だけ、参照ファイルなし）は避ける
• 書き込み系タスクを並列化しない（コンフリクトでトークンが浪費される）

4. サブエージェントにはallowlistで最小権限を与える

tools: Read, Grep, Glob のような読み取り専用allowlistで十分なタスクに、Editや全Bash権限を渡さない。誤操作によるトークン浪費と事故の両方を防げます。

セキュリティと権限の設計

サブエージェントはメイン会話と分離されるとはいえ、実行環境は共通です。以下の設計原則が公式から示されています。

最小権限の原則

tools フィールドで使えるツールをホワイトリスト化します。レビュアなら Read, Grep, Glob のみ、DBオペレータなら Read, Bash(psql:*) のみ、というように絞り込みます。

PreToolUse hook で条件付き検証

ツール単位より細かい制御が必要な場合は、PreToolUse hook で条件分岐を書きます。例えばSQLの SELECT だけ許可し INSERT/UPDATE/DELETE はブロックするバリデータを挟めます。

bypassPermissions は慎重に

権限プロンプトをスキップする bypassPermissions は便利ですが、.git .claude .vscode .idea .husky への書き込みだけは例外的に確認される仕組みになっています（.claude/commands .claude/agents .claude/skills は除外）。CI/CD 以外では基本的に避けるのが無難です。

また、親の bypassPermissions 設定はサブエージェント側で上書きできません。

特定のサブエージェントだけ禁止する

組織ポリシーで Explore を禁止したい、といったケースでは settings.json または CLI フラグで deny list を設定できます。

{
  "permissions": {
    "deny": ["Agent(Explore)"]
  }
}

claude --disallowedTools "Agent(Explore)"

プロジェクト用エージェントはバージョン管理に入れる

.claude/agents/ 配下をGitで管理することで、チーム全員が同じサブエージェント定義を共有できます。これは公式推奨の運用です。

実運用でのトラブルシューティング

現場で詰まりやすいポイントと対処を整理します。

権限プロンプトが嵐のように出る

バックグラウンドで動かす予定のタスクがフォアグラウンド扱いになっているケースが多いです。事前に必要なツールを permissionMode: acceptEdits や tools allowlist で明示してからバックグラウンドにするのが基本です。

Agent Teams のチームメイトが表示されない

• CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 が効いていない
• バージョンが v2.1.32 未満
• split panes 指定だが tmux / iTerm2 のどちらも起動していない
• VS Code統合ターミナル・Windows Terminal・Ghostty を使っている（split panes非対応）

まずは claude --version と echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS で原因を切り分けます。

タスクステータスが進まない

Agent Teams の既知の制限として、タスクステータス更新が遅延することがあります。依存タスクがブロックされている場合は、一度 team lead から該当タスクにメッセージを送って明示的に再評価を促すのが応急処置です。

/resume でチームメイトが戻らない

in-process のチームメイトは /resume や /rewind で復元されないため、長時間のチーム作業は前提として再現可能なタスクリストを残しておくことが重要です。

サブエージェントのログを確認したい

サブエージェントのトランスクリプトは ~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl に保存されています。cleanupPeriodDays（デフォルト30日）で自動削除される設定です。

--add-dir で追加したディレクトリが見えない

--add-dir で追加したディレクトリはサブエージェントのスキャン対象に入らない仕様です。サブエージェント側からアクセスさせたい場合は、メインスレッドから明示的にパスを渡します。

こんな方におすすめ／あまり向かないケース

現時点の仕様と実運用を踏まえた向き不向きをまとめます。

サブエージェント活用が合う方

• メイン会話の文脈を汚さずに長大な調査を回したい
• 読み取り専用の自動レビュアを運用したい（code-reviewer、security-reviewer 等）
• 3〜5個の独立ドメインに分けて並列実装を走らせたい
• チームで共通のエージェント定義を配布したい（.claude/agents/ をGit管理）
• コストを抑えたい（メインOpus・サブSonnet構成）

あまりおすすめしないケース

• 依存関係の強いタスクを無理に並列化したい（逐次で書いたほうが速く・安い）
• 単発の小さなタスクしかない（ビルトインで十分、自作は過剰設計）
• 本番で絶対に落とせないワークフロー（Agent Teamsは実験的機能）
• サブエージェントから更にサブエージェントを呼び出したい（仕様上不可）
• VS Code統合ターミナルしか使えない環境で split panes を使いたい（非対応）

関連記事

• 総合入門: Claude Code とは
• 使い方ガイド: Claude Code 使い方ガイド
• チーム導入: Claude Code チーム導入 ガイド
• 関連機能: Claude Code Hooks 使い方 ／ Claude Code Skills 活用ガイド ／ Claude Code MCP連携 ガイド
• 料金: Claude Code 料金

よくある質問（FAQ）

Q1. Task tool は廃止されますか？

現時点では廃止されていません。v2.1.63 で Agent tool にリネームされましたが、Task(...) 記述はエイリアスとして動き続けます。新規に書くコードでは Agent(...) を使う、というのが公式推奨です。

Q2. サブエージェントから別のサブエージェントを呼べますか？

呼べません。無限ネスト防止のため、サブエージェントは別のサブエージェントを生成できない仕様です。多段委譲が必要なら Skills もしくはメインスレッドからのチェーン呼び出しで設計してください。

Q3. 並列実行するとコストは下がりますか？

下がりません。並列化は実時間は短縮しますが、トークン消費は並列数に応じて線形に増えるのが公式仕様です。コストを下げたいときは並列化ではなく、CLAUDE_CODE_SUBAGENT_MODEL でサブエージェントを軽量モデルにダウングレードするのが効きます。

Q4. Agent Teams は本番で使って大丈夫ですか？

公式が「実験的機能」と明記しており、/resume 非対応・タスクステータス遅延などの既知問題が残っています。PRレビューや調査など失敗しても致命的でないワークフローから試すのが安全です。

Q5. .claude/agents/ と ~/.claude/agents/ はどちらに置くべきですか？

チームで共有したいならプロジェクト直下の .claude/agents/、個人の全プロジェクト横断で使いたいなら ~/.claude/agents/ が基本です。同名エージェントがある場合はプロジェクト配下が優先されます。

Q6. フロントマターの memory フィールドは何のためにありますか？

サブエージェントに永続メモリスコープを与えるフィールドです。user / project / local のいずれかを指定し、スコープに応じて永続化された情報を次回以降の呼び出しで参照できるようにします。2025年後半以降に追加された新しい仕様です。

Q7. isolation: worktree はいつ使うべきですか？

本番リポジトリを汚さずに破壊的な変更を試したいときに有効です。サブエージェントが一時的なgit worktree内で動き、変更がなければ自動クリーンアップ、変更があればパスとブランチが結果として返ります。マイグレーション検証やリファクタリング試行に向きます。

Q8. Agent Teams は何人チームがベストですか？

公式ベストプラクティスは3〜5人／1人あたり5〜6タスクです。それ以上増やしても調整オーバーヘッドで効率が落ちます。15タスクあるなら3人チームが目安です。

まとめ

• サブエージェントは独立コンテキストで動く特化AI。.claude/agents/ にMarkdownで定義するだけで作れる
• Agent tool（旧 Task tool、v2.1.63でリネーム）で呼び出される。Task(...) は後方互換
• Agent Teams（v2.1.32〜、実験的）はチームメイト同士が直接会話する上位の仕組み
• 並列化は独立タスクに向き、依存タスクや書き込み競合がある場合は逐次が正解
• コストは並列数に応じて増える。下げたいときは CLAUDE_CODE_SUBAGENT_MODEL でサブを軽量モデルに
• 最小権限（tools allowlist）・プロジェクト用エージェントのGit管理が公式推奨の運用

まずはビルトインの Explore / Plan / general-purpose を使い、足りなくなった段階でプロジェクト用の .claude/agents/ を整備する、というステップが最もコスト効率が良い導入経路です。さらに複数エージェントの討議が必要になったら Agent Teams を段階的に評価していく流れをおすすめします。