「レビューもテストも調査も、全部直列にやってたら時間がかかりすぎる」——そんなエンジニアの悩みに応えるのが、Claude Code のサブエージェント（Sub-agents）機能です。
サブエージェントを使うと、独立したタスクを複数の AI に同時に任せ、全体の処理時間を大幅に短縮できます。この記事では、公式ドキュメントに基づいた仕組みの解説から、実践的な設定方法・注意点まで、実践的な視点から徹底解説します。
サブエージェントとは何か
Claude Code サブエージェントとは、メインセッションから呼び出される独立した AI インスタンスです。各サブエージェントは以下の特性を持ちます。
- 独立したコンテキストウィンドウ：メイン会話の履歴は引き継がず、オーケストレーター（メインエージェント）が委譲メッセージを作成して渡す
- 専用のツール権限：各サブエージェントに許可するツールを個別に制限できる
- 並列実行：複数のサブエージェントが同時に動作し、結果だけをオーケストレーターに返す
- ネスト制限：ネスト深さが 5 に達したサブエージェントには Agent ツールが渡されず、それ以上の再帰呼び出しを防止する
メインエージェントとの違い
| 項目 | メインエージェント | サブエージェント |
|---|---|---|
| 役割 | タスク分解・委譲・結果統合 | 割り当てられた単一タスクの実行 |
| コンテキスト | 会話履歴全体を保持 | 委譲メッセージのみ（クリーンな状態） |
| ツール | 全ツールにアクセス可能 | frontmatter で制限・カスタマイズ可能 |
| モデル | セッション設定に依存 | 個別に指定可能（opus / sonnet / haiku / fable） |
| 生存期間 | セッション全体 | タスク完了まで |
キーポイントは「メインが考え、サブが動く」という分業です。
具体的なユースケース
1. 複数ファイルの並列レビュー
PR に含まれる 10 ファイルを直列にレビューすると、1 ファイルあたり 30 秒かかる場合、合計 5 分かかります。サブエージェントで 5 並列にすれば、壁時計時間は約 1 分に短縮できます。
2. 並列テスト実行
フロントエンド・バックエンド・E2E テストを独立したサブエージェントに割り当て、同時実行させます。各エージェントがログを独立して保持するため、テスト結果のノイズが混在しません。
3. 並列調査・リサーチ
「競合 A の技術スタックを調べるエージェント」「競合 B のドキュメントを調べるエージェント」「既存コードベースの依存関係を調べるエージェント」を同時に走らせ、結果をメインエージェントが統合するパターンです。
4. コード生成と検証の分離
「生成エージェント」と「レビューエージェント」を分離し、生成されたコードを独立した目で検証させます。同一コンテキストで自己レビューさせるより、見落としが減ります。
Claude Code サブエージェントの設定方法（.claude/agents/）
サブエージェントは .claude/agents/ ディレクトリに Markdown ファイルとして定義します。ファイルの先頭に YAML frontmatter を書き、その後にシステムプロンプトを続けます。
---
name: code-reviewer
description: コードレビューを専門に行うエージェント。PRのdiffを受け取りセキュリティ・可読性・パフォーマンスの観点でフィードバックを返す
model: sonnet
tools: Read, Grep, WebSearch
disallowedTools: Write, Edit, Bash
---
# コードレビュー専門エージェント
あなたはシニアエンジニアとしてコードレビューを行います。
以下の観点で必ずチェックしてください：
1. セキュリティ上の脆弱性
2. パフォーマンスのボトルネック
3. 可読性と保守性
4. テストカバレッジの欠如主なフロントマターフィールドは以下のとおりです。
- name（必須）：エージェントの識別名
- description（必須）：オーケストレーターがこの説明を読んで委譲タイミングを判断する。詳しく書くほど適切に呼ばれる
- model：使用モデル（opus / sonnet / haiku / fable）
- tools：許可するツールのリスト（カンマ区切り）
- disallowedTools：明示的に禁止するツール（カンマ区切り）
- maxTurns：最大ターン数
- isolation: worktree：独立した Git worktree を割り当てる
CLAUDE.md にルーティング規則を書いておくと、メインエージェントの判断が安定します。
# サブエージェント委譲ルール
- コードレビューは必ず code-reviewer に委譲する
- 3ファイル以上を同時に調査する場合は並列サブエージェントを使用する
- フロントエンドとバックエンドのテストは独立したサブエージェントで並列実行する
- 依存関係が発生するタスクは直列に処理する注意点・制限
コンテキスト汚染防止
サブエージェントはメインのコンテキストを持ちません。オーケストレーターが委譲メッセージに必要な情報を明示的に含めることが重要です。
並列数とトークン消費
5 つのサブエージェントを並列実行すると、トークン消費はおおよそ単一エージェントの 5 倍になります。1 ターンで起動するサブエージェントは 5 個以内に収めることを推奨します。
深さの上限（固定値）
サブエージェントのネスト深さは最大 5 です（設定変更不可）。
Write/Edit 権限の最小化
調査系のサブエージェントには disallowedTools: Write, Edit を設定し、意図しないファイル変更を防ぎます。
FAQ
Q. Claude Code サブエージェントは何個まで並列起動できますか？
公式に明示された上限値はありませんが、実用上は 1 ターンで 5 個以内が推奨です。それ以上は「タスク分割が不十分なサイン」として、まずタスク設計を見直してください。
Q. サブエージェントはメイン会話の履歴を参照できますか？
参照できません。サブエージェントは常にクリーンなコンテキストで起動します。メインエージェントが委譲メッセージを作成し、必要な情報をすべてその中に含めて渡します。
Q. サブエージェントごとに異なるモデルを指定できますか？
できます。frontmatter の model フィールドで haiku（軽量・高速）/ sonnet（標準）/ opus（高品質）/ fable を個別に指定可能です。
Q. プロジェクトのサブエージェントとグローバルなサブエージェントの違いは？
.claude/agents/（プロジェクト直下）に置いたエージェントはプロジェクト固有でチームと共有できます。~/.claude/agents/（ユーザーホーム）は全プロジェクトで使えるグローバルなエージェントです。同名の場合はプロジェクト側が優先されます。
Q. CLAUDE.md になくてもサブエージェントは動きますか？
動きます。ただし CLAUDE.md にルーティング規則がないと、メインエージェントが「いつサブエージェントを使うか」を自己判断します。明示的な委譲ルールを書いておくと、並列化すべきタスクの区別が安定します。
まとめ
- Claude Code サブエージェントは独立したコンテキスト・ツール権限・モデルを持つ AI インスタンスで、並列実行によって処理時間を大幅に短縮できる
- 定義ファイルは
.claude/agents/に YAML frontmatter 付き Markdown で作成する。description の品質がルーティング精度を決める - CLAUDE.md に委譲ルールを書くことで、並列化と直列処理の使い分けが安定する
- トークンコストは並列数に比例するため、1 ターン 5 個以内・haiku/sonnet/opus の使い分けでコスト最適化する
まずは自分のプロジェクトに .claude/agents/code-reviewer.md を 1 つ作成して試してみてください。
コメント