Claude Code サブエージェント 使い方｜Task tool・Agent Teams・並列処理完全ガイド【2026年5月最新】

Claude Code のサブエージェントは、独立したコンテキストウィンドウで動く専用のAIアシスタントで、.claude/agents/ にMarkdownファイルを置くだけで作れます。現時点（2026年5月）では、旧称「Task tool」が Agent tool に改名され（v2.1.63）、複数セッションを1画面管理する Agent View（v2.1.139）、セッション横断で協調する Agent Teams（v2.1.32〜）、親の会話履歴を継承する フォークモード（v2.1.117〜）と、並列処理の仕組みが3層に体系化されています。

この記事でわかること:

• サブエージェント・Agent View・Agent Teams の3層アーキテクチャと使い分け
• カスタムサブエージェントの作成方法と呼び出し方（各3通り）
• frontmatterで設定できる全フィールドの意味と実践例
• 実測コスト事例とトークン最適化のベストプラクティス
• Agent Teams・フォークモードの有効化手順と現行の制限事項
• 権限・セキュリティ設計と実運用でのトラブル対処

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

出典: Claude Code 公式サイト

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

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

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

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

サブエージェントを使う5つの理由

重要な制限：ネスト委譲は不可

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

並列処理の3層アーキテクチャ（全体像）

Claude Code の並列処理機能は、2026年5月時点で3つの層に体系化されています。

Layer 1: サブエージェント
  └── 同一セッション内での専門化・並列化
      親が子を呼び出し、結果の要約を受け取る

Layer 2: Agent View（v2.1.139〜）
  └── 複数のバックグラウンドセッションを1画面で管理
      ターミナルを閉じてもセッションは継続

Layer 3: Agent Teams（v2.1.32〜、実験的）
  └── 複数の独立セッション間の協調・通信
      チームメイト同士が直接メッセージを送り合う

3層の使い分け早見表

名称の整理：サブエージェント・Agent tool・Agent Teams の違い

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

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

組み込みサブエージェント一覧

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

Explore と Plan の特別な挙動: この2つは CLAUDE.md ファイルと親セッションの git ステータスをスキップします（高速・低コスト化のため）。その他のサブエージェントは両方を読み込みます。

Explore はHaikuベースなので、大規模リポジトリを安価に検索したいときの定番です。Explore + Explore + Exploreを3並列で走らせた実験では、約2分で53回のツール呼び出しを並列実行できたという報告があります（DevelopersIO調べ）。

出典: Claude Code 公式サイト

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

方法1: /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. ツール・モデル・色・メモリスコープを選んで保存

保存後は即座に利用可能（セッション再起動不要）。画面上でフィールドごとに説明が出るため、初回はこの方法がいちばん事故が少ないです。

方法2: 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でバージョン管理するのが公式推奨です。

方法3: --agents CLIフラグでセッション限定に定義

ワンショットで試したいとき、またはCI/CDで一時的に注入するときは、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"
  }
}'

このセッションが終われば定義も消えるため、本番定義を汚染しません。

frontmatterフィールド 完全ガイド

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

実装例：DBマイグレーション専用エージェント（フル機能）

hooks や memory、isolation は比較的新しい仕様で、競合記事でもあまり解説されていません。

---
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-7
permissionMode: acceptEdits
memory: project
isolation: worktree
effort: high
color: blue
---

You are a database migration specialist. Before applying any migration,
analyze the schema diff, identify potential data loss risks, and present
a migration plan for approval. Apply only after explicit confirmation.

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

モデル解決の優先順位

複数の箇所でモデルを指定できるため、どれが優先されるか把握しておくことが重要です。

環境変数が最優先のため、全サブエージェントのモデルを一括変更したい場合は環境変数が最も確実です。

スコープと優先度（どこに置くか）

同名のサブエージェントが複数ある場合、上位のスコープが優先されます。

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

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

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

{
  "agent": "code-reviewer"
}

フォアグラウンド vs バックグラウンド実行

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

バックグラウンド化は「run this in the background」とClaudeに依頼するか、実行中に Ctrl+B で切り替えます。

バックグラウンドの注意点:

• 未許可ツールの呼び出しは自動拒否（権限プロンプトなし）
• 事前に必要なツールを permissionMode: acceptEdits や tools allowlist で明示してから起動する
• CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 で全バックグラウンドタスクを無効化可能

並列処理の実測値

DevelopersIO の実験では、3つの Explore エージェントを同時起動した場合、約2分で53回のツール呼び出しを並列実行できました。内訳はアーキテクチャ調査10回・テストカバレッジ27回・依存関係16回。MCPアクセスエラーが発生しても Bash コマンドで自動代替継続するなど、エラー耐性も確認されています。

Agent View（バックグラウンドセッション管理）

v2.1.139 以降で利用可能。複数の独立したバックグラウンドセッションを1画面で管理するインターフェースです。

有効化と起動

claude agents

バックグラウンドセッションの起動

# 名前なしで起動
claude --bg "investigate the flaky test"

# 名前付きで起動
claude --bg --name "flaky-test-fix" "investigate the intermittent failure in auth tests"

# 特定のエージェント定義を使って起動
claude --agent code-reviewer --bg "address review comments on PR 1234"

Agent View の特性

サブエージェントと Agent View の違い

Agent View は「ターミナルを閉じた後も走らせ続けたい長時間タスク」や「複数の独立したリポジトリを並列で処理したい」場合に特に有効です。

出典: Claude Code 公式サイト

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

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

詳細な設定方法と使い方は Claude Code Agent Teams 完全ガイド に詳しくまとめています。ここでは サブエージェントとの使い分けを中心に解説します。

有効化手順

# 環境変数で起動
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude

# またはsettings.jsonに追加（v2.1.32以上が必要）

settings.json に恒久設定する例:

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

サブエージェント vs Agent Teams の使い分け

Agent Teams に向いているユースケース

• 並列コードレビュー: セキュリティ / パフォーマンス / テストカバレッジを同時並行でチェック
• 新機能の並列実装: フロントエンド / バックエンド / テストを別々のメンバーが担当
• 競合する仮説でのデバッグ: 複数の仮説を同時に追いかけて議論させる
• クロスレイヤー調整: フロントエンド・バックエンド・DBの整合性を横断的に確認

Agent Teams に向いていないユースケース

• 順序付きタスク（依存関係が多い）
• 同じファイルの編集（競合発生）
• シンプルな修正（調整オーバーヘッドが大きくなりすぎる）

現行の制限事項（2026年5月時点）

フォークモード（実験的機能）

v2.1.117 以降で利用可能。CLAUDE_CODE_FORK_SUBAGENT=1 で有効化します。

通常のサブエージェントは独立した新規コンテキストで起動しますが、フォークモードでは親会話の全履歴を継承したサブエージェントを起動できます。

export CLAUDE_CODE_FORK_SUBAGENT=1

通常のサブエージェント vs フォークモードの違い

フォークモードの動作

• フォークモード有効時: general-purpose サブエージェントが自動的にフォークを使用
• /fork コマンドでユーザーが手動でフォークを開始可能
• フォークはさらにフォークを生成できない（ネスト不可）

注意: 実験的機能のため、動作・設定が変更される可能性があります。公式ドキュメントでも明示されています。

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

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

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

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

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

Agent(agent_type) 構文で生成できるサブエージェントの型を絞り込めます。

フックとの互換性注意点

PreToolUse / PostToolUse フックで tool_name をチェックしている場合は注意が必要です。"Task" → "Agent" に変わったため、フック条件の書き換えが必要になることがあります（Claude Code Hooks 活用ガイド参照）。

また v2.1.139 以降では SubagentStart / SubagentStop フックイベントが追加され、サブエージェントのライフサイクルを監視できるようになりました。

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

実際のコスト事例（参考値）

CloudZeroの調査によると、サブエージェントを制限なく使うと想定外のコストが発生しうることが報告されています。

これらはAPI課金のケースです。Max/Proサブスクライバーはサブスクリプションに含まれるためAPIトークン課金なし。ただしAgent Teams（複数独立インスタンス）は注意が必要です。

コスト削減の4つのアプローチ

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

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

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

メインはOpus、サブはSonnetという組み合わせは、品質を落とさずコスト圧縮する鉄板パターンです。

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

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

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

• エージェント数は3〜5人が目安（それ以上は収穫逓減）
• 曖昧な指示（「Fix authentication」だけ、参照ファイルなし）は高コスト
• 書き込み系タスクの並列化はコンフリクトでトークンが浪費される

4. allowlistで最小権限を与える

# 読み取り専用レビュアの例
tools: Read, Grep, Glob

# 特定コマンドのみ許可する例
tools: Read, Bash(pytest:*), Glob

不必要な Edit・Write 権限を渡さないことで、誤操作によるトークン浪費と事故の両方を防げます。

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

Claude Code セキュリティガイドでより詳細に解説していますが、サブエージェント特有の注意点を整理します。

bypassPermissions の危険性

権限プロンプトを完全スキップする bypassPermissions は便利ですが、以下への書き込みを含む強力な権限です。

• .git / .claude / .vscode / .idea / .husky ディレクトリへの書き込み
• サーキットブレーカーが作動するのは rm -rf / などルート・ホームディレクトリ削除のみ

CI/CD 以外での使用は基本的に避けるのが無難です。

権限継承のルール

親セッションの bypassPermissions または acceptEdits はサブエージェント側でオーバーライドできません。親が自動モードの場合、サブエージェントも自動モードを継承します。

ツール制限のパターン例

# 読み取り専用レビュアー
tools: Read, Glob, Grep, Bash

# 書き込み禁止
disallowedTools: Write, Edit

# 特定エージェントのみ呼び出し可能に制限
tools: Agent(worker, researcher), Read, Bash

特定サブエージェントを組織ポリシーで禁止

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

claude --disallowedTools "Agent(Explore)"

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

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

実装例：よく使うカスタムエージェント

コードレビュアー（code-reviewer）

DevelopersIO の実験では、このパターンのエージェントが約1分で完了し、セキュリティ脆弱性3件・中程度問題・軽微問題を階層別に報告したと報告されています。

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

You are a senior code reviewer specializing in security and performance.
When invoked:
1. Identify all changed files using git status or the provided context
2. Review each file for: security vulnerabilities, performance anti-patterns, code quality issues
3. Return findings grouped by severity: Critical / Major / Minor
4. For each issue, provide: file path, line number, description, recommended fix

セキュリティスキャナー（security-scanner）

---
name: security-scanner
description: Scans codebase for security vulnerabilities. Use before PR merges.
tools: Read, Glob, Grep, Bash(grep:*)
model: sonnet
disallowedTools: Write, Edit
---

You are a security scanner. Scan for:
- SQL injection risks
- XSS vulnerabilities
- Hardcoded secrets or API keys
- Insecure dependencies
- Authentication bypass patterns

Report all findings with file paths and line numbers.

リサーチエージェント（researcher）

---
name: researcher
description: Conducts in-depth research on codebases, documentation, or technical topics. Use for investigation tasks that require reading many files.
tools: Read, Glob, Grep, Bash(find:*, cat:*, ls:*)
model: haiku
effort: high
---

You are a thorough researcher. When given a topic or question:
1. Systematically explore all relevant files and directories
2. Synthesize findings into a structured report
3. Return a concise summary with key findings and file references

出典: Claude Code 公式サイト

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

権限プロンプトが大量に出る

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

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

• CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 が効いていない
• バージョンが v2.1.32 未満（claude --version で確認）
• 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/Haiku構成）

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

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

用途別おすすめ選択ガイド

よくある質問（FAQ）

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

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

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

呼べません。無限ネスト防止のため、サブエージェントは別のサブエージェントを生成できない仕様です。多段委譲が必要なら Claude Code 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 のいずれかを指定し、スコープに応じて永続化された情報を次回以降の呼び出しで参照できます。特定プロジェクトの知識を蓄積させたいエージェントに有効です。

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

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

Q8. Agent Teams と Agent View の違いは何ですか？

Agent Teams は「複数のClaudeインスタンスが互いにメッセージを送り合って協調作業する」仕組みです（Layer 3）。Agent View は「複数のバックグラウンドセッションを1画面で管理する UI」で、各セッションは独立して動きます（Layer 2）。目的が「協調・討議」か「独立並列・長時間実行」かで使い分けます。

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

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

まとめ

• サブエージェントは独立コンテキストで動く特化AI。.claude/agents/ にMarkdownで定義するだけで作れる
• Agent tool（旧 Task tool、v2.1.63でリネーム）で呼び出される。Task(...) は後方互換で動作
• 並列処理は3層で考える：サブエージェント（同一セッション内）→ Agent View（バックグラウンドセッション管理）→ Agent Teams（セッション間協調、実験的）
• Agent View（v2.1.139〜）でバックグラウンドセッションを1画面管理。ターミナルを閉じても継続
• フォークモード（v2.1.117〜、実験的）で親の会話履歴を継承したサブエージェントを起動可能
• コストは並列数に応じて増える。下げたいときは CLAUDE_CODE_SUBAGENT_MODEL でサブを軽量モデルに
• 最小権限（tools allowlist）・プロジェクト用エージェントのGit管理が公式推奨の運用

まずはビルトインの Explore / Plan / general-purpose を使い、足りなくなった段階でプロジェクト用の .claude/agents/ を整備する、というステップが最もコスト効率の良い導入経路です。

Claude Code の基本から確認したい場合は Claude Code とは を、料金の詳細は Claude Code 料金 を参照してください。

参照元

• 公式: カスタムサブエージェントの作成
• 公式: Claude Code セッションのチームを調整する
• 公式: エージェントビュー
• 公式: コスト管理