Article

Claude Codeのサブエージェントとは？組み込み3種と自作の使いどころ・注意点

Claude Codeのサブエージェントはコンテキストを分離して使う仕組みです。組み込みのExplore・Plan・general-purposeとカスタムサブエージェントの違い、向くタスクと向かないタスク、設定ファイルとコスト面の注意点を実務目線で整理します。

This article is not published in this language yet, so the Japanese version is shown instead.

結論：サブエージェントは「本線の会話にゴミを混ぜたくないときに使う」

Claude Codeのサブエージェントは、本線の会話では読まなくていい情報（検索結果、ログ、大量のファイル内容）を別のコンテキストウィンドウで処理し、要約だけ本線に返す仕組みです。並列AIチームではなく、コンテキスト節約のための分業と理解するのが実態に近いです。

公式ドキュメントでも、サブエージェントは次の5点に効くと整理されています（Sub-agents）。

Preserve context: 探索や調査の副産物をメイン会話に残さない
Enforce constraints: ツール権限を絞って安全に働かせる
Reuse configurations: プロジェクト横断で同じ専門家を再利用
Specialize behavior: ドメイン専用のシステムプロンプトで振る舞いを固定
Control costs: Haikuのような速くて安いモデルに仕事を流せる

逆に言えば、本線の会話がシンプルに収まるタスクでは、サブエージェントを使う必要はありません。使いどころを見誤るとむしろオーバーヘッドになります。

本記事は、タスク分解の手順やPlan Modeプロンプトを把握している読者が、次のレイヤとしてサブエージェントを判断できるようにすることを狙います。

組み込みサブエージェント3種

Claude Codeには、明示的に作らなくても最初から使える組み込みサブエージェントがあります。Claude本体が必要と判断したときに自動で委譲されるので、まずこの3種を把握しておきます。

名前	モデル	ツール	役割
Explore	Haiku	読み取り系のみ（Write/Edit不可）	ファイル検索・コード探索
Plan	メイン会話と同じ	読み取り系のみ	Plan Mode中のコードベース調査
general-purpose	メイン会話と同じ	すべて	調査＋変更の両方が必要な複雑タスク

Explore

軽量なHaikuで動く、読み取り専用の高速検索エージェントです。rgやfind相当の作業、ファイル群からの情報抽出に向きます。Write/Editは禁止されているので、「探してくるだけ」で済む仕事に最適です。Claudeが呼び出すときにはquick / medium / very thoroughのいずれかで探索深度を指定します。

Plan

Plan Mode中にコードベースを調べるための読み取り専用エージェントです。モデルはメイン会話のものを引き継ぎます。Plan Mode中にPlanサブエージェントが走ることで、計画の根拠となる情報だけを本線に持ち帰れる設計になっています。

general-purpose

すべてのツールを持つ汎用エージェントです。調査と変更の両方が要る多段タスクで呼び出されます。フル機能の代償としてコンテキスト消費は大きいので、本当に必要なときだけ使う前提です。

そのほかの内部エージェント

/statuslineを動かすstatusline-setup、Claude Code自身に関する質問を拾うClaude Code Guideなど、ユーザーが直接呼ぶ想定ではない組み込みエージェントもあります。普段の運用では意識しなくて構いません。

カスタムサブエージェントの作り方

同じ仕事を何度も頼みそうなときだけ、カスタムサブエージェントを作ります。公式推奨は**/agentsコマンドから作成する方法**ですが、Markdownファイルを直接置いても動きます。

置き場所とスコープ

場所	スコープ	優先度
マネージド設定	組織全体	1（最高）
`--agents` CLIフラグ	そのセッション限り	2
`.claude/agents/`	プロジェクト	3
`~/.claude/agents/`	自分の全プロジェクト	4
プラグインの`agents/`	プラグイン有効時	5

プロジェクト固有のエージェントは.claude/agents/に置いてGitにコミットし、チームで共有する想定です。個人用ユーティリティは~/.claude/agents/に置きます。

最小のサブエージェント定義

サブエージェントはYAMLフロントマター＋Markdown本文の形です。最小構成はこれだけで動きます。

---
name: security-reviewer
description: Reviews code for security vulnerabilities
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior security engineer. Review code for:
- Injection vulnerabilities (SQL, XSS, command injection)
- Authentication and authorization flaws
- Secrets or credentials in code
- Insecure data handling

Provide specific line references and suggested fixes.

必須はnameとdescriptionだけです。ほかは省略するとメイン会話から継承します。descriptionはClaudeが委譲判断に使うので、どんな依頼のときに呼ぶかを明確に書きます。

起動の仕方

作成したサブエージェントは、自然言語で呼び出します。

Use the security-reviewer subagent to check src/auth/ for vulnerabilities.

組み込みの/agentsコマンドで一覧や編集ができます。claude agentsをシェルから打つと、インタラクティブ起動なしで登録済みサブエージェントの一覧を確認できます。

claude agents

代表的な設定フィールド

公式に列挙されているfrontmatterのうち、実務でよく使うものだけ抜粋します。

フィールド	意味
`tools`	使えるツールを許可リストで指定。未指定だと全継承
`disallowedTools`	使えないツールを拒否リストで指定
`model`	`sonnet` / `opus` / `haiku` / 具体ID / `inherit`
`permissionMode`	`default` / `acceptEdits` / `auto` / `plan` など
`mcpServers`	そのサブエージェントだけで使うMCPサーバー
`skills`	起動時にプリロードするスキル
`maxTurns`	停止までの最大ターン数
`isolation`	`worktree`にすると一時的なgit worktreeで動く

toolsとdisallowedToolsは併用でき、disallowedToolsが先に適用されてからtoolsで許可リストが絞られるルールです。安全側で設計するなら、toolsを明示的に列挙してWrite/Editを外す形が堅いです。

向くタスクと向かないタスク

向くタスク

コードベース探索: 「OAuthの既存実装を調べて」のように、ファイルをたくさん読むけど本線に持ち帰るのは要約でよい作業
レビュー: 実装を書いたのとは別の文脈で、バイアス少なく読み直す「Writer/Reviewer」パターン
同じ型の調査の繰り返し: 毎回似た手順で行う差分レビューやセキュリティチェックなど、テンプレ化できる仕事
ツール権限を絞って動かしたい仕事: 書き込み禁止の調査員、DBにしか触らない調査員、など

向かないタスク

本線の会話で流れを維持したい編集作業: 小〜中規模の実装は本線で進めたほうが速い
1回限りの単純作業: 変数名変更やlog行追加なら、ふつうに依頼する
前後の文脈が強く要る仕事: 直前の議論や試行錯誤を踏まえる必要があるタスクは、サブエージェントに切ると情報が欠ける
「とりあえず並列で回せば速い」的な発想の仕事: サブエージェントは並列AIチームではなくコンテキスト分離装置なので、分解できていないタスクでは効果が薄い

公式ドキュメントにも、「複数のサブエージェントが並列で通信しながら動く用途には、サブエージェントではなくagent teamsを使う」と明記されています。ここを混同すると、サブエージェントを増やしても体感が良くならないという沼にはまります。

コストとトークンの注意点

サブエージェントは別のコンテキストで動きますが、課金は別扱いになるわけではありません。入出力トークンは通常どおり積み上がります。コスト面で期待できるのは次の2点です。

モデル選択でコストを下げる: Explore的な検索仕事はHaiku相当の軽量モデルで済ませる
本線コンテキストを長持ちさせる: 結果として、メイン会話のコンパクションや再スタートを遅らせられる

逆に過剰に使うと無駄にトークンを食うので、次の判断軸でブレーキを踏みます。

本線の会話で1〜2ツール呼び出しで済むなら、本線で完結させる
サブエージェントを呼ぶと決めたら、拾って帰る情報量を依頼時に絞る（「ファイル一覧とその要約だけ返す」など）
同じ質問を繰り返しサブエージェントに投げない（結果を本線のメモに残す）

料金・モデル別レートは変わりやすいので、運用に入る前に料金ページで最新値を確認しておくのが安全です。

既存の組み込みだけで足りるかを最初に考える

実務で一番まずいのは、「サブエージェントが便利と聞いたから作ってみた」で、実態は組み込みで足りていたパターンです。次の順で判断すると無駄が減ります。

本線だけで済むか？ 済むなら使わない
Explore / Plan / general-purposeで済むか？ 済むなら組み込みで済ます
同じ専門家を何度も作っているか？ YESなら初めてカスタム化する
ツール権限を絞る必要があるか？ 絞りたいならカスタムで限定

カスタムサブエージェントはコピペで無限に増やせるのが危ういポイントです。プロジェクト.claude/agents/配下が10個、20個と膨らむと管理コストがかかり、選択肢が多すぎて委譲判断もブレます。増えすぎたら、ドキュメントと照らしながら役割が被るものを統合していくのがおすすめです。

実務で使える3つのテンプレ

1. 調査専用（読み取りのみ）

---
name: repo-scout
description: Read-only codebase scout. Call when you need file discovery or pattern search.
tools: Read, Grep, Glob, Bash
model: haiku
---

You are a read-only scout. Return concise findings with file paths and
line numbers. Never propose code changes.

2. テスト実行と失敗解析

---
name: test-runner
description: Runs the test suite and analyzes failures without modifying code.
tools: Read, Bash, Grep
model: sonnet
permissionMode: default
---

Run `npm test`. If failures occur, identify the failing test, relevant files,
and the likely root cause. Return a summary only. Do not edit files.

3. セキュリティレビュー

---
name: security-reviewer
description: Reviews diffs for injection, auth, and secret leakage issues.
tools: Read, Grep, Glob, Bash
model: sonnet
---

Review code for injection vulnerabilities (SQL, XSS, command injection),
authentication/authorization flaws, hard-coded secrets, and insecure data
handling. Provide specific line references and suggested fixes.