サブエージェントが解決するのは「コンテキスト汚染」という特定の問題だ。Claudeが読んだファイル、実行したコマンド、検討した中間結果 — これらすべてが単一のコンテキストウィンドウに蓄積されていく。小さなタスクなら問題ない。しかし大きなコードベース、長い調査作業、複数の独立したフェーズを含む作業では、コンテキストはすぐにいっぱいになり、品質が低下する。
サブエージェントはClaude Codeがこの問題に対して出した答えだ。独自の隔離されたコンテキストウィンドウの中で動作し、集中した作業をこなして、サマリーを返す。メインエージェントのウィンドウはクリーンなままを保てる。
このガイドでは、サブエージェントの実際の動作原理、効果的なAGENTS.mdの書き方、そして一般的なアプローチより確実に優れたパターンを解説する。
サブエージェントの仕組み
サブエージェントを起動すると、Claude Codeは新しいセッションを立ち上げる。そのセッションは以下を持つ:
- 独自のコンテキストウィンドウ（あなたのウィンドウとは分離されている）
- AGENTS.mdで定義されたカスタムシステムプロンプト
- 独自のツール権限（アクセスできるものを制限できる）
- 明示的に渡さない限り、現在の会話の記憶なし
サブエージェントはタスクを完了して結果を返す。その結果はメインセッションに注入される。サブエージェントが消費した何千ものトークン（ドキュメント閲覧、ファイル読み込み、コマンド実行）は、あなたのコンテキストに触れない。
これがコアバリューだ。200ページのドキュメントを読むサブエージェントは、自分のトークン予算を使う — あなたのではなく。
AGENTS.md: 設定ファイル
サブエージェントはAGENTS.mdファイルで定義される。配置ルールはCLAUDE.mdと同じで、プロジェクトルート、サブディレクトリ、またはグローバルの~/.claude/に置ける。
基本的なエントリーはこのようになる:
# agents
## code-reviewer
description: コードの正確性、セキュリティ問題、スタイル違反をレビューする。PRレビューやコミット前チェックに使う。
tools: read, bash
model: claude-sonnet-4-6
## doc-writer
description: コード変更に基づいてテクニカルドキュメントを書き・更新する。READMEファイル、APIドキュメント、インラインコメントの更新に使う。
tools: read, write
model: claude-sonnet-4-6
## test-generator
description: 既存コードのユニットテスト・インテグレーションテストを生成する。新機能実装後に使う。
tools: read, write, bash
model: claude-sonnet-4-6いくつかのポイントに注目:
descriptionフィールドが重要な役割を担う。 Claudeはこれを使って、サブエージェントを自動的に起動するタイミングを判断する。明確なトリガー条件として書くこと — 一般的な目的の要約ではなく。「コードをレビューする」は曖昧すぎる。「コードの正確性、セキュリティ問題、スタイル違反をレビューする。PRレビューやコミット前チェックに使う」なら、Claudeにいつこのエージェントが適用されるかを正確に伝えられる。
toolsのスコープが重要。 ドキュメントライターにbashは不要だ。コードレビュアーにwriteアクセスはおそらく不要だ — 問題を指摘させたいのであり、サイレントに修正させたいわけではない。ツールセットをサブエージェントが実際に必要とする最小限に絞る。
modelは任意だが指定する価値がある。 Sonnetは速くて安い。Opusは複雑な推論が得意。タスクに合わせてモデルを選ぶ。
明示的呼び出しと自動呼び出し
サブエージェントの起動方法は2つある。
自動呼び出し: Claudeはdescriptionに基づいてサブエージェントにタスクをルーティングする。descriptionが精確になれば機能するが、予想外の動作を引き起こすことも — Claudeが自分でやりたかったタスクを委任してしまうかもしれない。
明示的呼び出し: プロンプトでサブエージェント名を直接指定する。「このPRのdiffにcode-reviewerサブエージェントを実行して」は曖昧さがない。
本番ワークフローには明示的呼び出しの方が予測可能だ。自動呼び出しは、どのエージェントが何を処理するかをそれほど気にしない探索的な作業に便利。
明示的に起動するには:
src/auth/login.tsにtest-generatorサブエージェントを実行して。
無効な入力のエッジケースに集中して。Claudeはサブエージェントを立ち上げ、指示と指定したコンテキストを渡して、出力を返す。
並列・直列パターン
ここからサブエージェントが本当に強力になる — そして、多くの人がかなりのパフォーマンスを置き去りにしているところでもある。
直列（みんなが使っているデフォルト）
1. code-reviewer → 問題を見つける
2. test-generator → 見つかった問題のテストを書く
3. doc-writer → ドキュメントを更新する各ステップは前のステップに依存する。問題ないが遅い。各サブエージェントは前のものが完了するまで待つ。
並列（独立したタスクに使うべき方法）
タスクが互いに依存しない場合は同時実行する:
並列実行:
- code-reviewer: src/auth/ をレビュー
- code-reviewer: src/payments/ をレビュー
- code-reviewer: src/notifications/ をレビュー3つの別々のパッケージレビューが同時進行する。Claudeはすべてのツール呼び出しを同時に起動する。3回分ではなく1回分の時間で結果を得られる。
ルール: タスクBがタスクAの出力を必要としないなら、並列実行できる。開始前に依存関係グラフを整理する。
ファンアウト/ファンインパターン
大規模な調査や監査タスクで最も効果が高いパターン:
- ファンアウト: 複数のサブエージェントを起動し、それぞれがシステムの一部を分析
- ファンイン: それらのサマリーを集めて統合ステップへ
ファンアウトフェーズ（並列）:
- analyzer-agent: フロントエンドバンドルサイズの原因を分析
- analyzer-agent: APIレスポンスタイムのボトルネックを分析
- analyzer-agent: データベースクエリパターンを分析
ファンインフェーズ（直列）:
- architect-agent: 3つの分析レポートをもとに統合最適化プランを提案ファンインエージェントは生の分析ではなく、小さく密度の高いサマリーを受け取る。メインコンテキストには最終統合結果だけが渡される。
コンテキストの渡し方: 明示的に送るべきもの
サブエージェントは現在のセッションの知識を持たない状態で開始する。これは意外な落とし穴だ — Claudeとの対話でコンテキストを20のメッセージで構築してきても、サブエージェントにはそれが何も伝わらない。
サブエージェントが必要とするものを明示的に渡す必要がある。方法:
ファイルの内容ではなくファイルパスを渡す。 サブエージェント自身がファイルを読める。呼び出しメッセージにファイルの内容を貼り付けるだけでトークンが重複する。
src/payments/内のファイルにcode-reviewerサブエージェントを実行して。
使っている決済プロバイダーはStripe。関連設定はconfig/stripe.tsにある。コンテキストをファイルに書いて参照する。 複数のサブエージェントが必要とする複雑なコンテキストは、マークダウンファイルに書いて各サブエージェントに読ませる:
現在のアーキテクチャの決定事項はdocs/architecture-decisions.mdにある。
そのコンテキストでsrc/auth/にtest-generatorを実行して。サマリーは短くする。 サブエージェントが完了すると、その結果がメインコンテキストに戻る。3,000ワードの分析を書いてきたら、3,000トークン分を抱えることになる。サブエージェントには密度の高いサマリーを返させて、詳細はファイルに書かせる。
よくあるミス: 過剰委任
最もよく見られる悪用パターンは、「今すぐ対処したくないもの」の受け皿としてサブエージェントを使うことだ。
サブエージェントにはオーバーヘッドがある。サブエージェントを起動し、コンテキストを渡し、結果を待ち、サマリーを読む — これは実際のレイテンシーだ。10行の関数変更には、メインセッションで直接やる方が速い。
正しいメンタルモデル: サブエージェントは、実行作業（読み取り、検索、分析）が結果に対して有意に多くのコンテキストを消費するタスク向けだ。タスクが200トークンの答えのために5,000トークンの中間推論をコンテキストに追加するなら、サブエージェント候補として適切。300トークンで200トークンの答えが得られるなら、インラインでやる。
目安:
- 調査タスク（ドキュメント読み込み、コードベーススキャン）: サブエージェント候補として適切
- 単一ファイル編集: メインセッションでやる
- 横断的分析（10ファイル以上のレビュー）: サブエージェントの強力な候補
- 短い生成タスク（テスト1本を書く）: コンテキストが既に逼迫している場合を除きメインセッションでやる
サブエージェントとエージェントチーム
Agent Teams（2026年2月リリース）はサブエージェントとひとつの重要な点で異なる: チームメンバーは直接お互いと通信できる。サブエージェントはメインオーケストレーターにしか報告できない。
サブエージェントを使う場合:
- タスクが独立していて自己完結している
- 単一のオーケストレーターがコントロールを維持したい
- タスクのスコープが限定的で予測可能
Agent Teamsを使う場合:
- タスクがワーカー間の調整を必要とする
- チームメンバーがお互いの出力に異議を唱える必要がある
- 複数のメンバーが状態を同期する必要がある長期プロジェクトを実行している
日常的な開発作業のほとんどには、サブエージェントで十分だ。Agent Teamsは大規模リファクタリング、複雑なコード移行、複数の視点が必要な調査で威力を発揮する。
動くAGENTS.mdテンプレート
典型的なフルスタックプロジェクトへの出発点:
# agents
## researcher
description: 技術的な質問に答えるためにドキュメント、GitHubのissue、外部リソースを調査する。コードを書く前に、ライブラリ、API、不慣れなコードベースについて最新情報が必要な時に使う。
tools: read, bash, web_search
model: claude-sonnet-4-6
## code-reviewer
description: バグ、セキュリティ問題、パフォーマンス問題、スタイル違反について、ステージング済みの変更や特定のファイルをレビューする。コミット前やPRレビュー時に使う。重大度別に問題の構造化リストを返す。
tools: read, bash
model: claude-sonnet-4-6
## test-writer
description: 既存の関数やモジュールのユニットテスト・インテグレーションテストを生成する。機能実装後やバグ修正後に使う。適切なテストディレクトリにテストを書いてパスを確認する。
tools: read, write, bash
model: claude-sonnet-4-6
## doc-updater
description: コード変更を反映してドキュメントファイル（README、APIドキュメント、CHANGELOG）を更新する。機能のマージ後やリリース前に使う。diffを読んで影響を受けるドキュメントのみ更新する。
tools: read, write
model: claude-sonnet-4-6
## security-auditor
description: インジェクションリスク、認証の欠陥、コード内のシークレット、安全でない依存関係などのセキュリティ脆弱性についてコードを監査する。認証モジュール、APIハンドラー、本番デプロイ前に使う。
tools: read, bash
model: claude-opus-4-6実際の痛点を解決する2〜3エージェントから始める。エージェントが増えると設定のオーバーヘッドが増え、誤った委任が起きやすくなる。明確なパターンが見えてから追加する — 先回りして追加しない。
サブエージェント問題のデバッグ
よくある問題と解決策:
想定外のタイミングでサブエージェントが起動する: descriptionのトリガー条件を絞り込む。必要なら「使わない場合」の明示的な文言を追加する。
想定しているタイミングでサブエージェントが起動しない: descriptionがタスクの表現の仕方と一致していない可能性がある。descriptionを書き直すか、明示的呼び出しを使う。
サブエージェントが返す情報が多すぎる: 詳細な出力をファイルに書かせてサマリーを返すよう依頼する。AGENTS.mdのdescriptionや呼び出しプロンプトで返したいフォーマットを指定する。
並列エージェントが競合する編集を生成する: 同じファイルに書き込む並列エージェントを実行しない。各エージェントが別のファイルやディレクトリを担当するように並列作業を構成する。
サブエージェントシステムは強力だが魔法ではない。AGENTS.mdに注ぎ込む設定の作業は線形に報われる — より良いdescription、より精確なツールスコープ、より明確な出力フォーマット指示は、直接エージェントの動作品質に反映される。