Claude Code のサブエージェント活用法#
Claude Code のサブエージェント機能は、専門分野に特化した別エージェントを呼び出す仕組み。うまく使えばメインのコンテキストを節約しつつ、専門的な判断を得られる。
基本構造#
flowchart TD
U[ユーザー] --> M[メイン Claude Code<br/>汎用]
M -->|特定タスク| S1[code-reviewer<br/>サブエージェント]
M -->|特定タスク| S2[security-reviewer<br/>サブエージェント]
M -->|特定タスク| S3[db-expert<br/>サブエージェント]
S1 --> M
S2 --> M
S3 --> M
メインはオーケストレーター役に徹し、専門タスクは別エージェントに委譲する。
得られる効果#
1. コンテキストの節約
メインのコンテキストにはサブエージェントの出力結果のみが入る。サブエージェント内部の長い推論はメインに残らない。
2. 専門性の向上
サブエージェントごとに専用のシステムプロンプトを持てる。セキュリティレビューなら OWASP Top 10、DB 設計なら正規化原則など、専門プロンプトで精度が上がる。
3. 並列実行
複数のサブエージェントを同時に走らせられる。レビュー・セキュリティ監査・テスト生成を並列化できる。
flowchart LR
M[メイン] --> S1[reviewer]
M --> S2[security]
M --> S3[test-gen]
S1 --> R[結果集約]
S2 --> R
S3 --> R設計のコツ#
1. 1 つの責務に絞る
サブエージェントは 1 つの仕事 に絞る。「コードレビュー + テスト生成 + デプロイ」のような複合責務は避ける。
2. 明確な入出力契約
- 入力: 何を渡すか（ファイルパス、コード片、要件 等）
- 出力: 何を返すか（JSON か、Markdown か、スコア付きか）
呼び出し側と認識を揃える。
3. モデルを使い分ける
シンプルな分類・要約は小さいモデル（Haiku 系）で十分。複雑な推論だけ上位モデルを使う。
4. 失敗時の挙動を決める
- タイムアウト時: デフォルト値を返すか、エラーを上げるか
- 部分成功時: どう報告するか
- リトライ: するかしないか
アンチパターン#
1. サブエージェントを増やしすぎる
10 個のサブエージェントを持つと、どれを使うべきか判断コストが増える。使用頻度の高いもの 3〜5 個に絞る。
2. メインで済むタスクを委譲する
軽いタスクまでサブエージェントに投げると、起動コストの方が重い。判断基準を決める。
- 委譲する: 専門プロンプトが活きる、コンテキストを汚染したくない、並列化したい
- 委譲しない: 単純な検索、短いテキスト処理、即座に結果が必要
3. サブエージェントの出力をそのまま採用
サブエージェントも LLM。検証なしに信じない。重要な出力は人間またはメイン側でチェックする。
4. ログを残さない
サブエージェント呼び出しの入出力をログしないと、何が起きたか追跡できない。
運用のチェック#
- [ ] サブエージェントの責務は 1 つに絞られているか
- [ ] 入出力契約が明文化されているか
- [ ] サブエージェントごとにモデルを使い分けているか
- [ ] 使用頻度が低いサブエージェントは削除対象か
- [ ] 呼び出しログが残っているか
まとめ#
サブエージェントはオーケストレーションの手段。メインを身軽に保ち、専門的な仕事を別エージェントに任せる。設計がうまく回ると、1 つのモデル・1 つのセッションで済ませるより、速くて安くて質が高い結果になる。