Claude Code Subagents: Setup, Config, and When to Use Them
ノイズの多い作業は委譲し、コンテキストをクリーンに保ちましょう。
ほとんどの Claude Code セッションが遅くなり、混乱に陥るのは同じ理由によります。探索的な grep、ログのダンプ、そして「もう1つのファイルを確認してみよう」といった動作が、メインの会話に永遠に残り続けるからです。
サブエージェント（Subagents）は、まさにこの問題を解決するために存在します。それらは、ノイズの多い並列処理可能なタスクを処理するために、Claude Code に組み込まれたエージェントプリミティブの一つです。混乱を隔離されたウィンドウに押し込み、重要なサマリーのみを返す方法を提供します。
サブエージェントはより賢い Claude ではなく、スキル（Skill）とも異なります。それは、独自のコンテキストウィンドウ、独自のツール使用許可リスト（allowlist）、そして明示的にフォークしない限り現在の会話の記憶を持たない、独立した推論エージェントです。この違いを理解することは、コンテキスト予算を静かに節約するサブエージェント設定と、何の利益もなくレイテンシを追加するだけの設定との違いを決定します。
サブエージェント vs スキル vs MCP
Claude Code は異なる問題を解決する3つの拡張ポイントを提供しますが、これらはすべて技術的に「タスクを支援できる」ため、常に混同されます。
| レイヤー | 概要 | 使用すべきタイミング |
|---|---|---|
| スキル | メインエージェントのコンテキストにオンデマンドで読み込まれる指示書 | 再利用可能な手順、チェックリスト、プレイブック — 開発者向けの Claude Skills を参照 |
| サブエージェント | 独自のコンテキストウィンドウを持つ独立したエージェント。委任されたタスクのためにディスパッチされる | ノイズの多い探索、並列可能なリサーチ、メインセッションから除外したいもの |
| MCP サーバー | プロトコル経由で公開された外部ツール/データコネクタ | ローカルセッション外のシステムへのアクセス — API、データベース、リモートサービス |
実用的な経験則として：フックは決定論的に厳格な制約を強制し、スキルはメインエージェントにインラインで機能を与え、サブエージェントは委任してメインコンテキストから完全に除外したいタスクのために使用されます。スキルの役割がまだ存在しないツールをオーケストレーションすることである場合、それは通常、サブエージェントではなく MCP サーバーが必要であるという兆候です。この構造において Claude Code だけが特殊なわけではありません。OpenCode のエコシステムには、計画・調査・レビューを専任の役割で分割する類似のアイデアである 専門化エージェント が存在します。
サブエージェントとは実際に何なのか
Claude Code のサブエージェントを定義する3つのプロパティがあり、それらはすべて使用方法において重要です：
- 隔離されたコンテキスト。 サブエージェントは新しいウィンドウから開始します。明示的にフォークしない限り、会話履歴を見ることができません。これにより、数ターン前に議論した内容によって出力が汚染されるのを防ぎます。
- 制限されたツール使用許可リスト。 サブエージェントは、親セッションが既に持っているサブセットのツールのみを使用できます。それらは新しい機能を自分自身に付与することはできず、設計の優れたサブエージェントは、そのタスクに必要なツールのみを受け取るべきです（例えば、リサーチエージェントには読み取り専用ツール）。
- サブエージェント間の可視性の欠如。 サブエージェントは互いの進行中の作業を見ることができません。タスク B が本当にタスク A の出力を必要とする場合、それは並列化できるものではなく、逐次的な依存関係です。
サブエージェントを使用するトリガーは「このタスクは難しい」ことではありません。「このタスクはノイズが多い」ことです。中間出力（数十回のファイル読み取り、長いログ、リポジトリ全体に対する探索的な grep など）を大量に生成し、その中間資料のどれもが次の会話ターンに生存する必要のない種類のタスクです。
サブエージェントを使うべき時（と使わないべき時）
適切な用途：大きな変更前のコードベースの探索、パス/フェールと失敗サマリーのみを気にする自動化テスト実行、セキュリティまたはスタイルレビュー、および生データがメインセッションを氾濫させてしまうような多段階のリサーチタスク。
不適切な用途：2秒間の検索（「この関数は何を返すのか」）、緊密な往復による微調整が必要な任何东西、および2番目が1番目の回答を必要とするにもかかわらず「並列化」したくなる依存タスク。自明な検索にサブエージェントを使用することは、実際の隔離利益なしに新しいコンテキストウィンドウを起動するオーバーヘッドを追加するだけです。
効果の測定：コンテキストとコストの計算
サブエージェントの提案は、実際のタスクに数値を当てはめるまで抽象的なものです。一般的な例として：約500ファイルのサービスで、非推奨の構成キーがまだ読み取られている箇所をすべて grep し、正確なファイル:行の一致を報告するというタスクを考えてみましょう。
| アプローチ | メインセッションで消費されるコンテキスト | 次のターンに引き継がれるもの |
|---|---|---|
| サブエージェントなしの直接探索 | ~35-45K トークン — 全ての grep 一致、確認のために開いた全てのファイル、全ての行き違い | 誤った方向を含め、すべて |
| Explore サブエージェントに委任 | ~1.5-3K トークン — 1つの要約レポート | 重要な発見のみ |
これは、そのステップにおいてメインセッションが抱え込む必要があるものの約15-20倍の削減であり、「サブエージェントがセッションを高速化する」ことの実際のメカニズムです。それは魔法ではなく、最初からロードされないコンテキストです。
コスト側も同様に累積します。Claude Code の価格分解 の価格を使用して、同じ探索パスを Opus（入力 $5/MTok、出力 $25/MTok）で実行すると、~40K の入力トークンのみで約 $0.20-0.25 かかります。それを Haiku（入力 $1/MTok、出力 $5/MTok）にルーティングすると、$0.04-0.05 に低下します。そして、メインセッションの Opus バジェットは探索トークンによる影響を一切受けません。なぜなら、それは ~2K トークンのサマリーのみを見るからです。
カスタムサブエージェントの定義
カスタムサブエージェントは、プロジェクトスコープの .claude/agents/（リポジトリにコミットされ、チーム全体で共有される）またはユーザースコープの ~/.claude/agents/（すべてのプロジェクトに持ち込む個人用ツール）にある、YAML フロントマターを持つ Markdown ファイルとして存在します。
---
name: code-reviewer
description: >
コミット前に、ステージされた変更に対するバグ、セキュリティの問題、
スタイル違反をレビューします。ユーザーがコミットまたはPR作成前に
レビュー、監査、または変更の確認を求めた时使用。
tools: Read, Grep, Glob
model: sonnet
skills:
- security-checklist
---
あなたは慎重なコードレビュアーです。ステージされた差分を読み取り、ファイル:行の参照付きで具体的な問題をフラグを立て、
短いパス/フェールサマリーで終了してください。ファイルの変更は行わないでください。
description フィールドはファイルの中で最も重要な行です。親セッションのルーティングロジックが、このサブエージェントが現在のタスクに適しているかどうかを決定するために読むものです。それを採用条件として明示的に名付ける「求人広告」のように書きましょう。曖昧な「コードを支援する」といった記述は避けます。曖昧な記述は、自動ディスパッチによってスキップされたり誤適用されたりします。
tools フィールドはあなたの隔離境界です。リサーチサブエージェントに Read、Grep、Glob を与え、それ以外は与えません。利用可能なすべてのツールを与えることは、制限されたサンドボックスで実行する意味を完全に損ないます。オプションの skills フィールドは、指定されたスキルの完全な内容をサブエージェントの起動コンテキストにプリロードします。サブエージェントがタスクの途中で発見および読み込むターンを費やさずにドメイン知識を必要とする場合に有用です。
モデルルーティング：安価なモデルで雑用を処理
サブエージェントはまた、コスト管理が本格的になる場所でもあります。ファイル発見、ログスキャン、および他の安価に検証できる作業を Haiku にルーティングし、Sonnet または Opus は推論が重いステップ — アーキテクチャの決定、曖昧なデバッグ、間違えると高価な任何东西 — に予約します。Haiku は Opus よりもトークンあたり約15倍安く、サブエージェントが構築された種類のノイズの多い探索において、その差は実際の作業セッション全体で急速に蓄積します。
探索、計画、実行パターン
複雑で多段階の作業において、実践的に通用するパターンは「探索、計画、実行」です。ノイズを生成する部分には安価なサブエージェントを使用し、人間によるレビューゲートは実際に重要な1つの場所に保持します。
人々が逆にしてしまうキーとなる詳細は、レビューゲートがどこにあるべきかという点です。探索は安価なので、許可を最初に求めることなくサブエージェントが自由に読むことを許します。計画は分析的なので、エージェントが独自にアプローチを設計することを許します。しかし、エージェントがファイルを修正する前に、計画を確認し承認する必要があります。それが Claude Code の計画モード（permissionMode: plan）の目的であり、それはすべての差分が適用される前にレビューするという、より広範な Vibe Coding のベストプラクティス で議論されているのと同じ原則です。
一般的なミス
チームがカスタムサブエージェントの作成を開始すると、いくつかのミスが繰り返し現れます：
- 曖昧な記述。 「コードを支援する」だけでは正しくルーティングされません。正確なトリガー条件を名付けます。
- 広すぎるツールアクセス。 読み取り専用のリサーチサブエージェントに書き込みと bash アクセスを与えることは、最初に作成する価値があった隔離保証を削除します。
- 依存するタスクの並列化。 タスク B がタスク A の完了した出力を必要とする場合、それらを逐次的に実行します — サブエージェントは共有オーケストレータのようにタスクの途中で協調できません。タスクの途中でエージェントが互いに通信する必要があるワークフローの場合、それは異なる形状の問題です。単一リポジトリのワークフローではなく本番システムを構築している場合は、マルチエージェントオーケストレーションパターン を参照してください。
- 自明な作業にサブエージェントを使用。 「このJSONをフォーマットする」または「この1つのコマンドを実行する」には新しいコンテキストウィンドウは必要ありません。直接行ってください。
作業例：コードレビューサブエージェントの端到端
すべての非自明なコミットが適用される前にレビューされるようにしたいとしましょう。前述の code-reviewer 定義を .claude/agents/code-reviewer.md にドロップし、チーム全体が同じレビュアーを共有するようにコミットし、「コミット前にステージされた変更をレビューして」といった自然なリクエストで呼び出します。Claude Code はリクエストをサブエージェントの description と一致させ、Read、Grep、Glob のアクセスのみで起動し、ファイル:行参照付きの発見とパス/フェールサマリーを返します — そこに到達するためのファイルごとのノイズは一切メインセッションに触れません。
メイントランスクリプトでの見た目の注釈付き：
You: コミット前にステージされた変更をレビューして
Main: [code-reviewer サブエージェントをディスパッチ — 6つのファイル読み取り、1回のgrepパス、
どれもここで表示されない]
Main: code-reviewer の発見：
- auth/session.go:142 — トークンリフレッシュパスは期限切れのリフレッシュトークンを処理せず、
nil参照外れにフォールスルー
- auth/session.go:203 — スタイル：エラーが %w なしでラップされている
PASS/FAIL: FAIL (1つのブロック問題)
6つのファイル読み取りと1回のgrepパスが行われ、あなたのメインセッションはそのうちの4行分のみを支払いました。そのギャップ — サブエージェントが行ったすべて versus 実際に3行のサマリー — が、1つのトランスクリプトにおける価値提案全体です。
あなたのチームが Spec-Driven Development のスケルトンも使用している場合、レビューサブエージェントは検証ステップに自然に適合します。ポータブルおよびIDE統合された SDD 設定間のレビューゲートの比較については、GitHub Spec Kit vs Kiro vs Claude Code SDD ワークフロー を参照してください。
カスタムサブエージェントの設定は価値があるか？
1日目にはそうではありません。組み込みの汎用サブエージェントは、すでに1つの YAML ファイルも書かずにほとんどの探索とリサーチ委任をカバーしており、1回の探索-計画-実行パスが日常の作業の大部分に十分です。カスタム .claude/agents/*.md ファイルは、同じタスクを手動で3回委任した後にのみ作成してください — コードレビュアー、テストランナーのトライアジャー、特定の内部ライブラリ用のドキュメント検索エージェント。最初の週に5つのサブエージェントを書くチームは、通常、実際のトリガー条件がドリフトしたときに誰も更新しない5つの陳腐化した description フィールドで終わります。これは静かに数ヶ月後に自動ルーティングを壊します。カスタムサブエージェントをゼロから始め、1つずつ追加し、反復 — 理論的な有用性ではなく — がそれを要求するときにのみ追加してください。
既知の制限
サブエージェントを中心に構築する前に知っておくべきいくつかの粗いエッジがあります：
- 再帰的委任の欠如。 サブエージェントは独自のサブエージェントを生成できません。タスクが本当に2番目の層の委任を必要とする場合、それは異なるオーケストレーション形状が必要であるという兆候です。単一の Claude Code セッション外でそれがどのようなものかについては、マルチエージェントオーケストレーションパターン を参照してください。
- 呼び出し間の記憶の欠如。 関連するタスクで5分前に同じサブエージェントを呼び出したとしても、すべてのディスパッチはゼロから開始します。サブエージェントが最後の実行を記憶するための組み込みメカニズムはありません。
- 隔離はツール使用許可リストであり、サンドボックスではありません。
Bashアクセスを持つサブエージェントは、他のツール呼び出しと同様にファイルシステムとネットワークに依然としてアクセスできます。toolsを制限することは爆発半径を縮小しますが、厳格なセキュリティ境界を作成するものではありません。
トラブルシューティング
サブエージェントがトリガーされない。 記述がほぼ常に問題です。一般的な機能記述ではなく、特定のトリガー条件を中心に書き直し、ファイルが .claude/agents/（プロジェクト）または ~/.claude/agents/（個人）に正しく配置され、正しい拡張子を持っていることを確認します。
サブエージェントが依然として多くのコンテキストを消費する。 tools 使用許可リストを確認します — 広すぎるツールセットは広すぎる探索を誘発します。また、タスクが1つで何でもやる代わりに2つのサブエージェントに分割されるべきであったかを確認します。
リストされたスキルがサブエージェント内でロードされない。 Claude Code は skills フィールドに名付けられた存在しないまたは無効なスキルをスキップし、実行を失敗させるのではなく、デバッグ出力（メインセッションから /debug、次にディスパッチを再現）にその旨の行をログします — skill "security-checklist" not found, skipping のようなもの。その後 /doctor を実行して、セットアップの残りが健全であることを確認します。
実行間で結果が一貫していないように感じる。 これはしばしばモデルルーティングの問題であり、サブエージェント設計の問題ではありません — 安価なモデルに割り当てられた推論が重い作業はよりばらつきがあります。それを Sonnet または Opus に移動し、Haiku は決定論的で低曖昧性のステップに保持します。
サブエージェントははるかに大きなツールボックスの一部です。このワークフローにコミットする前に Claude Code を AI 開発者ツールエコシステム の残りと比較している場合、その概要は次の良い停止点です。
