Claude CodeのSub-agent設計 — 1セッションで専門家チームを使い分ける
Claude Codeで大きなリファクタリングをしていたとき、コードベース全体を調査させたらコンテキストウィンドウの70%が検索結果で埋まりました。肝心のリファクタリング指示を出す頃には、窓が狭すぎて的外れな提案しか返ってこない。
私は「調査が上手すぎて仕事ができなくなるAI」という、落語みたいな状況に立ち会っていました。
解決策はSub-agentです。調査を別の専門家に委譲して、結果の要約だけ受け取る。メインの会話は綺麗なままです。
Sub-agentとは何か
Sub-agentは、メインのClaude Codeセッションから呼び出される専門家です。独立したコンテキストウィンドウで動作し、タスクが終わったら結果だけを返します。
Eric Raymondの「目玉の数が十分あれば、バグは浅くなる」は、オープンソースのレビュアーの話でした。Sub-agentはこれをAIに持ち込みます。Exploreエージェントにコードを調査させ、セキュリティ用エージェントに脆弱性を探させる。「目」の数が増えるほど、見落としが減ります。
Sub-agentを使う理由は3つです。
コンテキストの保全。 コードベースの探索や大量ログの解析をメインでやると、検索結果がコンテキストを圧迫します。Sub-agentに委譲すれば、調査はSub-agent側で完結し、メインには要約だけ返ります。冷蔵庫の中身を全部テーブルに出して料理するか、必要な食材だけ取り出すかの違いです。
制約の強制。 Sub-agentにはツールアクセスを制限できます。調査専用エージェントにはRead/Grep/Globだけを許可し、ファイル編集を禁止する。「見ていいけど触るな」を技術的に強制できます。
コストの制御。 Sub-agentごとにモデルを指定できます。調査のような軽いタスクにはHaikuを使い、重要な設計判断にはOpusを使う。全員に役員報酬を払う必要はありません。
ビルトイン3種の使い分け
Claude Codeには、すぐに使えるSub-agentが3種あります。
| Sub-agent | 得意なこと | 使えるツール | 編集権限 |
|---|---|---|---|
| Explore | コード調査、リサーチ | Read, Grep, Glob, WebSearch | なし |
| Plan | 設計、実装計画 | Read, Grep, Glob, WebSearch | なし |
| general-purpose | 実装、テスト実行 | フルセット | あり |
Claudeはタスクの内容に応じてこれらを自動選択します。「このファイルの依存関係を調べて」と書けばExploreが、「リファクタリングの計画を立てて」と書けばPlanが起動します。
ここで大事なルールが1つ。Sub-agentはメインの会話履歴を引き継ぎません。 「さっき話した件」のような曖昧な参照は機能しません。タスクの指示はSub-agentに渡すプロンプトの中で完結させる必要があります。
隣の部屋にいる同僚に仕事を頼むときと同じです。「あれやっといて」ではなく「Aファイルの認証ロジックを調べて、OAuth2の実装箇所をリストアップして」と具体的に伝える。
カスタムSub-agentの作り方
ビルトイン3種でカバーできない専門家が必要なら、自分で作れます。
配置場所
| スコープ | パス |
|---|---|
| 個人(全プロジェクト共通) | ~/.claude/agents/<name>.md |
| プロジェクト(チーム共有) | .claude/agents/<name>.md |
プロジェクトの規約に依存する専門家(コーディング規約チェッカーなど)は .claude/agents/ に。個人のワークフローに関わるもの(ドキュメント検索など)は ~/.claude/agents/ に置きます。
実例: セキュリティレビュー用Sub-agent
---
name: security-reviewer
description: コードのセキュリティ問題を検出する
model: sonnet
allowed-tools: Read Grep Glob WebSearch
---
あなたはセキュリティレビューの専門家です。
コードを分析する際は、以下の観点で確認してください:
1. OWASP Top 10に該当する脆弱性
2. 認証・認可の不備
3. 入力値の検証漏れ
4. 機密情報のハードコーディング
5. 依存パッケージの既知の脆弱性
発見した問題はCVSSスコア(推定)付きで報告してください。
frontmatterの --- で囲まれた部分がメタデータ、それ以降がSub-agentのシステムプロンプトです。
frontmatterの主要フィールド
| フィールド | 説明 | 設計判断のポイント |
|---|---|---|
name | 表示名 | @name で呼び出すので短く |
description | いつ使うかの判断基準 | Claudeのルーティングに影響する |
model | 使用モデル | コスト制御の要 |
allowed-tools | 許可ツール(スペース区切り) | 最小権限の原則 |
memory | true でSub-agent専用の永続メモリ | 繰り返し使うSub-agentに有効 |
description フィールドは単なるラベルではありません。Claudeがこの説明文を読んで「このタスクにこのSub-agentを使うべきか」を判断します。「セキュリティレビュー」よりも「PRのコード変更からOWASP Top 10脆弱性を検出する」のほうが、適切なタイミングで呼び出されます。
モデル選択によるコスト制御
Sub-agentの設計でもっとも実用的な判断が、モデルの使い分けです。
| タスクの性質 | 推奨モデル | 理由 |
|---|---|---|
| コード検索、パターン照合 | Haiku | 読み取りだけなら高速・低コストで十分 |
| コードレビュー、バグ分析 | Sonnet | 判断力が必要だがOpusほどの推論は不要 |
| アーキテクチャ設計、複雑な判断 | Opus | 妥協すると後で手戻りするタスク |
全員Opusにすれば品質は最大になります。でもそれは、お使いも商談も全部社長が行くようなものです。調査はインターンに、レビューは中堅に、設計は社長に。組織設計と同じ原則です。
2026年2月にAnthropicが公開した社内活用PDFでも、このモデル使い分けパターンが中核として紹介されていました。Anthropic自身が「全部Opusにはしない」と言っている。説得力があります。
Git Worktreeによる並列編集
Sub-agentの隠れた強力機能が、Git Worktreeとの連携です。
Agent toolの isolation: "worktree" パラメータを使うと、Sub-agentは一時的なworktreeを作成してそこで作業します。メインブランチのファイルを編集しながら、別のSub-agentがworktree上でテストコードを書く。作業が完了したらworktreeのブランチをマージする。
変更がなかったworktreeは自動でクリーンアップされます。変更があった場合はパスとブランチ名が返されるので、手動でマージできます。
「同じファイルを2人が同時に編集して衝突」という、チーム開発あるあるのリスクを技術的に回避できます。
@メンションと永続メモリ
カスタムSub-agentは @agent-name で直接呼び出せます。チャットで @security-reviewer このPRをチェックして と書くだけ。
さらに、memory: true を設定するとSub-agent専用のAuto Memoryディレクトリが作成されます。セッションをまたいで学習した内容が保持されるので、同じSub-agentを繰り返し使うほど精度が上がります。
セキュリティレビュー用のSub-agentが「このプロジェクトではJWTの有効期限を15分に設定している」と学習すれば、次回以降は24時間に設定されたJWTを自動的に指摘してくれます。
私が実際に使っている3つのSub-agent
理論はここまでにして、実際の運用例を紹介します。
1. コードベース探索用(Explore強化版)
---
name: codebase-scout
description: コードベースの構造と依存関係を調査する
model: haiku
allowed-tools: Read Grep Glob
---
コードベースを調査し、以下の形式で報告してください:
- 関連ファイルの一覧(パスと1行説明)
- 依存関係のグラフ(テキスト形式)
- 変更時の影響範囲Haikuで十分です。ファイルを読んでパターンを見つけるだけなら、高級モデルは過剰投資です。
2. テスト設計用
---
name: test-designer
description: 実装コードからテストケースを設計する
model: sonnet
allowed-tools: Read Grep Glob
---
与えられたコードを分析し、テストケースを設計してください:
- 正常系: ゴールデンパスのテスト
- 異常系: エラーハンドリングのテスト
- 境界値: エッジケースのテスト
テストコードは書かないでください。テストケースの一覧と検証ポイントだけを報告してください。注意点は allowed-tools からEditを外していること。テスト設計と実装を分離することで、設計段階でのバイアスを防ぎます。テストを書く人が「実装しやすいテスト」を設計しがちな問題は、人間のエンジニアと同じです。
3. ドキュメント更新チェック用
---
name: doc-checker
description: コード変更に対してドキュメントの更新漏れを検出する
model: haiku
allowed-tools: Read Grep Glob
memory: true
---
コードの変更差分とドキュメントを比較し、更新漏れを報告してください:
- READMEとの乖離
- APIドキュメントの不整合
- 設定ファイルの説明漏れmemory: true にしているのは、プロジェクト固有の「どのドキュメントがどのコードに対応しているか」を学習させるためです。
Sub-agentを使うべき場面、使うべきでない場面
Anthropicの公式ドキュメントにある判断基準が的確です。
Sub-agentを使うべき場面: タスクが「ノイズが多く、範囲が限定的で、要約しやすい」とき。大量のファイルを検索する、特定パターンを見つける、独立したレビューを行う。
メインで続けるべき場面: タスクが「小さく、密結合で、共有メンタルモデルに依存する」とき。3行の修正、直前の議論を踏まえた判断、一連のリファクタリングの途中ステップ。
判断を間違えると、Sub-agentにコンテキストを渡すオーバーヘッドのほうが、メインでやるコストを上回ります。包丁を洗うより手でちぎったほうが早いレタスに、わざわざ包丁を出す必要はありません。
まとめ
- Sub-agentの価値は コンテキストの保全 が第一。重い調査をメインから隔離し、要約だけ受け取る
- ビルトイン3種(Explore/Plan/general-purpose)は自動選択される。カスタムが必要なら
.claude/agents/にMarkdown1枚 - モデル選択がコスト制御の要。 調査はHaiku、レビューはSonnet、設計はOpus
- Sub-agentへの指示は 自己完結 させる。「さっきの件」は通じない
- 「ノイズが多く、範囲が限定的で、要約しやすい」タスクに使う。それ以外はメインで続ける
まずは1つ、自分のプロジェクトでよく繰り返す調査タスクをSub-agentとして定義してみてください。.claude/agents/ にMarkdownファイルを1つ置くだけで始められます。私は最初にcodebase-scoutを作りましたが、正直なところ、効果に気づいたのは「あれ、今日のセッション、なんかコンテキスト圧迫されてないな」と思った3日後でした。地味な改善ほど、効いている証拠です。
参考リンク
- Claude Code Sub-agents公式ドキュメント — カスタムSub-agentの作成ガイド
- Anthropic社内Claude Code活用PDF — 2026年2月公開の社内活用パターン
- Claude Code Subagents: How to Create, Use, and Debug Them — 実践的なチュートリアル
さらに深掘りしたい方へ
本記事で触れたのは一部です。CLAUDE.md の書き方を「2行から100行まで」、Plan Mode 起点の開発フロー、チーム運用、非コーディング業務への応用まで、19章で体系化した 実践Claude Code — コンテキストエンジニアリングで開発が変わる を参考にしてください。
この記事は役に立ちましたか？