Claude Code公式から学ぶ、コンテキスト分離のSubAgent設計
はじめに
SubAgentって3種類あんねん。
SubAgentには「ユーザー定義」と「ビルドイン」があるというのは周知の事実だと思います。でも実はもう1つ、プロンプトで起動するSubAgent(即席SubAgent)があります。
これは公式ドキュメントには明記されていませんでしたが、挙動としては以前から確認されていました。そして昨日、公式ベストプラクティスの記事で軽く言及されていたので、今回はこの即席SubAgentについて解説します。
そこから踏み込んで、公式pluginのソースコードを覗いてみると、即席SubAgentがどのように使われているか、そしてもっと広い視点でどのようなアーキテクチャを用いているかが勉強になるので、紹介できればと思います。
SubAgentの3つの種別
1. ユーザー定義SubAgent
.claude/agents/ディレクトリにMarkdownファイルを置いて定義するタイプです。最も一般的なタイプです。
.claude/agents/
├── code-review.md
├── test-writer.md
└── doc-generator.md
2. 組み込みSubAgent
Claude Codeに最初から入っているSubAgentです。ビルドインなのでSubAgentだと認識していない人もいたかも知れません。
文脈を判断して勝手に使ってくれます。
- Explore: コードベースの探索に特化
- Plan: 実装計画の設計に特化
- General-purpose: 汎用的な調査・コード修正
3. 即席SubAgent
プロンプトで即席SubAgentを起動する方法です。公式記事でも軽く紹介されていました。
use a SubAgent to review this code for edge cases
ブログでは紹介されていませんでしたが、即席で利用するモデルも指定できます：
Launch a haiku agent to check the API response format
こんな感じで、その場で目的を指定してSubAgentを起動できます。プロンプトで即席に起動できるって、知ってました？
即席SubAgentの使いどころ
即席SubAgentの使いどころはいろいろありますが、特に強力なのが観点ごとにコンテキストを隔離して調査・判断させるパターンです。
例えばコードレビューで5つの観点があるとします。全部まとめて1つのプロンプトで評価させることもできますが、即席SubAgentなら観点ごとにSubAgentを起動し、メインコンテキストはオーケストレーターに徹することができます。
観点1: セキュリティ → SubAgent A
観点2: パフォーマンス → SubAgent B
観点3: 可読性 → SubAgent C
各SubAgentが独立したコンテキストで深く分析し、メインには結果だけが返る。一括処理より各観点に集中した分析ができます。
この考え方を実際にどう設計するか、Anthropic公式pluginのソースコードが具体例として参考になります。
公式pluginに学ぶ高度な使い方
ここからが本番。Anthropicが公開している公式pluginのソースコードを見ると、SubAgentの高度な使い方が学べます。
code-review pluginでは、PRレビューを複数のSubAgentで分担しています。
| ステップ | 責務 | 起動数 | モデル | 直列/並列 | 該当コード |
|---|---|---|---|---|---|
| Step 1 | PR状態チェック | 1 | Haiku | 直列 | L14-L20 |
| Step 2 | CLAUDE.mdパス検出 | 1 | Haiku | 直列 | L24-L26 |
| Step 3 | PRサマリー取得 | 1 | Sonnet | 直列 | L28 |
| Step 4 | バグ・規約レビュー | 4 | Sonnet×2 + Opus×2 | 並列 | L31-L56 |
| Step 5 | 妥当性検証 | N（問題数） | Opus / Sonnet | 並列 | L57 |
他にもfeature-dev pluginなど、同様のマルチエージェント設計を採用したpluginが公開されています。フェーズごとに異なる観点のagentを並列起動する構造で、こちらも勉強になります。
Anthropicアーキテクチャパターンとの対応
code-review pluginで見たように、SubAgentの設計はアーキテクチャ（分離単位・直列並列・モデル選択）と、各SubAgentへのプロンプト設計（何を渡し、何を制約し、何を返させるか）の両面から成り立っています。
AnthropicのBuilding Effective Agentsでは、こうした設計判断のパターンが紹介されています。
例えばcode-review pluginは以下のパターンを組み合わせています：
- Prompt Chaining: Step 1-3の順次実行（各ステップの出力が次の入力に）
- Parallelization: 複数agentでバグスキャンを並列実行
- Evaluator-Optimizer: 検証agentによる品質チェック
- Routing: Pre-flightチェックによる早期終了・条件分岐
紹介されているパターンがどのように使われているか、なぜ有効なのかを考えながら読むと、自分で構築する際に役立つので是非一読してみてください。
まとめ
この記事では、SubAgentの中でもあまり話題になっていない即席SubAgentについて紹介しました！
- プロンプトだけでコンテキスト隔離されたSubAgentを起動できる
- 複数の観点を並列処理し、メインコンテキストはオーケストレーターに徹する等の活用が可能
- 公式pluginのエージェント設計は勉強になる
Discussion