解決すべき問題
ほとんどの開発者にとって、AIとの最初の出会いは「1つのプロンプト」「1つの応答」から始まります。それは強力に感じます——タスクが複雑になるまでは。AIに「競合3社を調査し、その結果を統合してレポート形式にまとめて」と依頼すると、単一のコンテキストウィンドウが急にとても小さく感じられるようになります。これがサブエージェントが解決する問題です。
デモ
上のデモでは、名前を明示してエージェントを呼び出しています。オーケストレーションされたワークフローでは、Claudeはタスク構造に基づいて、このような複数のエージェントを自動的に——並列または逐次で——呼び出せます。
Skills GitHub Repo - .claude/agents/code-quality-reviewer.md
サブエージェントとは何か？
サブエージェントとは、オーケストレーションするAIが、より大きなワークフロー内の特定のサブタスクを処理するために呼び出すAIインスタンスです。複数エージェントシステムでは広く——Claude、GPT、Gemini、あるいはオープンソースモデルに基づく場合でも——中核となるパターンは同じです。つまり、単一のモデルがすべてを順番にやり切るのではなく、オーケストレーターが作業を分解し、それぞれを委任するのです。あらゆる関数を自分で書くのではなく、技術リードが専門家に仕事を割り当てるのに似ています。
AnthropicのClaude Agent SDKのドキュメントによれば、サブエージェントは2つの主要な目的を担います。並列化（複数のタスクを同時に実行すること）とコンテキストの分離（各サブエージェントがそれぞれ独自のコンテキストウィンドウを使い、全コンテキストではなく関連する結果だけをオーケストレーターに返すこと）です。[^1]
割り当てられた範囲内では、サブエージェントは実行の主体となるユニットです。Webを閲覧したり、コードを実行したり、ファイルを読み書きしたり、外部APIを呼び出したりできます。彼らは単に推論するだけではありません。実行します。
サブエージェントのワークフローはどう動くのか
オーケストレーターは重い処理を自分でやるわけではありません。調整します。各サブエージェントには、明確な目的、出力形式、ツールへのアクセスがセットになった集中的なプロンプトが渡され、その後、簡潔な結果を返します。オーケストレーターはそれらの結果を集約し、最終成果物を作り上げます。
Anthropicの社内リサーチシステムはまさにこのパターンを採用しています。リードエージェントがサブエージェントを生成して、問い合わせの異なる側面を並列に調べさせ、その調査結果を統合して筋の通った回答にまとめます。評価の結果、このアプローチは社内のリサーチベンチマークで、単体のClaude Opus 4を90.2%上回りました。[^2]
オーケストレーションのパターン
すべてのサブエージェントのワークフローが同じ形をしているわけではありません。次の3つのパターンが、ほとんどの実運用ケースをカバーします。
- 並列ファンアウト — 独立したサブタスクが同時に起動されます。複数のドキュメントを同時に分析するようなタスクに最適です。
- 逐次パイプライン — あるサブエージェントの出力が次のサブエージェントに渡されます。依存関係の連鎖がある場合（リサーチ→ドラフト→編集→フォーマットなど）に最適です。
- 階層的な委任 — サブエージェント自体が、より深いサブタスクに対するオーケストレーターになります。強力ですが、調整の複雑さが増します。
間違ったパターンを選ぶことはよくあるミスです。逐次タスクを並列化してもオーバーヘッドが増えるだけで得はありません。独立したタスクを逐次化すると時間を浪費します。
Claude Code CLIでサブエージェントを作成する
Claude Codeはサブエージェントを作成する方法を2つ提供します。/agentsコマンドによるインタラクティブな方法、またはMarkdownファイルとして手動で作る方法です。どちらも同じ結果になります——.claude/agents/ディレクトリ内にある.mdファイルです。
インタラクティブな方法
/agents create
ガイド付きのセットアップが案内されます。名前、説明、ツール、モデル、スコープです。最後にファイルが保存され、エージェントは即座に利用可能になります。
手動の方法
Markdownファイルを直接作成します——フロントマターが振る舞いを定義し、本文はシステムプロンプトです：
---
name: security-reviewer
description: "Expert security reviewer. Use PROACTIVELY after any changes to auth, data handling, or API endpoints."
tools: Read, Grep, Glob
model: haiku
permissionMode: plan
---
あなたは、脆弱性についてコードをレビューするシニアセキュリティエンジニアです。
呼び出されたら：
1. 最近変更されたファイルを特定する
2. OWASP Top 10 の脆弱性について分析する
3. シークレット、SQLインジェクション、ハードコードされた認証情報を確認する
4. 深刻度レベルと修正手順とともに調査結果を報告する
ファイルの置き場所
サブエージェントのスコープは、そのファイルが配置されているディレクトリによって決まります：
| スコープ | パス | 使用するタイミング |
|---|---|---|
| Project |
.claude/agents/ （プロジェクトのルート） |
チーム共有のエージェント。バージョン管理にコミットする |
| User |
~/.claude/agents/ （ホームディレクトリ） |
個人用エージェント。すべてのプロジェクトで利用可能 |
Project スコープは推奨されるデフォルトです。これにより、サブエージェントの定義をバージョン管理で共有できるようになります。リポジトリがどこであっても、どこでも利用可能にしたい汎用的なエージェントには user スコープを使ってください。
ベストプラクティス
正しくトリガーされる説明を書く。 Claude は
descriptionフィールドを使って、サブエージェントを自動的に呼び出すべきかどうかを判断します。自動トリガーしたい場合は、具体的にしてPROACTIVELYを含めてください。たとえば： "Use PROACTIVELY after any changes to authentication or data handling."ツールを意図的に制限する。
toolsフィールドは、エージェントが実行できることを制限します。セキュリティ監査者はRead、Grep、Globだけが必要で、ファイルを書き込む必要はありません。この制限を明確にしておく価値があります。タスクの複雑さに合わせてモデルを選ぶ。 サブエージェントの探索は、Haiku のようなより安価で高速なモデルに振り分け、本当に必要なアーキテクチャ推論には Opus を予約します。読み取り専用のコードスキャナには、生産コードを書き込むエージェントと同じモデルは不要です。
システムプロンプトは集中させる。 限定され、明確に定義された役割を持つサブエージェントは、ゼネラリストよりも優れた性能を発揮します。プロンプトが多くの異なる懸念事項をカバーし始めたら、2つのエージェントに分割してください。
実務上の課題：コンテキスト管理
各サブエージェントは、共有メモリなしで毎回新しく開始します。つまり：
- オーケストレータは、成功に必要なすべてのコンテキストを、各サブエージェントのプロンプトに作り込まなければならない
- サブエージェントの出力は、他のすべてと一緒にオーケストレータのコンテキストへ戻せるほど簡潔である必要がある
- 出力が大きい場合、オーケストレータは集計する前に要約しなければならない
良いサブエージェント設計とは、主に情報設計です。各エージェントが何を知る必要があり、何を生み出さなければならず、その出力がどのように全体へ流れ込むのかを決めます。
安全性に関する考慮事項
サブエージェントが現実世界のアクションを取れる場合、安全の境界は単一エージェントのシステムよりも重要になります：
- 最小権限 — 各サブエージェントに、本当に必要なツールだけを渡す。調査エージェントは、生産データベースへの書き込み権限を必要としません。
- 出力の検証 — サブエージェントの出力を、下流へそのまま無条件に渡さない。軽量なサニティチェックでも被害範囲を縮小できます。
- プロンプトインジェクション — Web を閲覧したり外部ファイルを読み込んだりするサブエージェントは、その振る舞いを操作するための内容に遭遇する可能性があります。これはエージェント型システムにおける現実の攻撃面です。
サブエージェントを使うべきとき
| サブエージェントを使うべき場合… | サブエージェントを避けるべき場合… |
|---|---|
| タスクが明確に分割できる | タスクが 1 つのエージェントで単純に済む |
| 並列実行によって意味のある時間短縮ができる | 委任するにはサブタスク間で状態の共有が多すぎる |
| 合計作業量が 1 つのコンテキストウィンドウを超える | 調整（コーディネーション）のオーバーヘッドが得を上回る |
| 異なるサブタスクが異なるツールを必要とする | まだ試作段階で、まずはシンプルに保つべき |
まずは単一エージェントのアプローチから始め、オーケストレーションが本当に辛くなってきたら導入してください。複雑さにはコストがあります。
サブエージェントとスキル：簡単な補足
この2つの用語は、ときどき混同されますが、まったく別の層で動作します。 スキル は受動的な命令ドキュメントであり、Claude がタスクの前に読み込む markdown ファイルです。ベストプラクティス、利用可能なライブラリ、出力の慣習を理解するためのものです。 サブエージェント は能動的な実行単位で、実行され、ツールを使い、結果を返します。
正直な関係性：サブエージェントは、自分の作業の前にスキルを読むかもしれません。一方は知識を形作り、もう一方は実行します。
最後に
より大きな Claude のスタックは、5つの層として概念化できます。接続性のための MCP、タスク固有の知識のための Skills、主要な作業者である Agent、並列の独立した作業者としての Subagents、そして調整のための Agent Teams です。[^3] これらのビルディングブロックは、次々とリリースされており、そのパターンは急速に成熟しています。
この領域に入ったばかりの開発者向けに言うと：初日から完全なオーケストレーションシステムを構築する必要はありません。しかし、このパターン——委任がどのように機能するのか、サブエージェントにできること／できないこと、どこが危険なポイントか——を理解しておくと、最初から AI アーキテクチャについての考え方が形作られます。
サブエージェントは、単なる機能ではありません。私たちが、AI に何をやらせられるのかについて考える方法が変わってきているのです。
参考文献
- [^1]: Anthropic エンジニアリング。 Claude Agent SDK でエージェントを構築する。 -> https://www.anthropic.com/engineering/building-agents-with-the-claude-agent-sdk
- [^2]: Anthropic エンジニアリング。 マルチエージェントのリサーチシステムをどのように構築したか。 -> https://www.anthropic.com/engineering/multi-agent-research-system
- [^3]: Winbuzzer。 Anthropic が、サブエージェントと MCP を使って Claude Code をスケールする方法を紹介。 -> https://winbuzzer.com/2026/03/24/anthropic-claude-code-subagent-mcp-advanced-patterns-xcxwbn/
- [^4]: Anthropic。 カスタムサブエージェントを作成 — Claude Code Docs。 -> https://code.claude.com/docs/en/sub-agents
ここまで読み進めてくれたのであれば、私はあなたに読み続けてもらえるだけの十分満足のいく努力をしたはずです。どうかコメント、または訂正があれば共有してください。
