要約
Claude Codeのサブエージェント機能は、メインセッションから独立した特化型AIエージェントを起動し、タスクを委譲する仕組みである。本記事では、サブエージェントの定義方法、全16のフロントマター設定項目、4つの呼び出しパターン、コンテキスト分離の仕組み、並列高速化の実績、そしてAgent Teamsとの比較まで、全体像を網羅的に解説する。
この記事を読むことで得られるメリット
この記事を読むことで以下のことが分かる:
- サブエージェントの定義方法と3つの作成手段が理解できる
- 全16フロントマターフィールドの役割と設定方法が把握できる
- コンテキスト分離の仕組みと、メインセッションへの影響範囲が明確になる
- 役割分離・並列高速化・コスト最適化など具体的なメリットが数値で理解できる
- Agent Teamsとの違いを理解し、適切な使い分けができるようになる
この記事を読むのにかかる時間
約20分
環境
- Claude Code v2.1+
- macOS / Linux / Windows
サブエージェントとは何か
サブエージェントは、メインのClaude Codeセッションから独立して動作する特化型AIエージェントである。独自のコンテキストウィンドウ、カスタムシステムプロンプト、特定のツールアクセス、独立した権限を持ち、メインセッションとは分離された環境でタスクを処理する。
イメージとしては、プロジェクトマネージャー（メインのClaude）が、専門家（サブエージェント）に調査や実装を依頼するようなものである。専門家がどれだけ大量の資料を読み漁っても、プロジェクトマネージャーの机（コンテキスト）は散らからない。最終的な報告だけが返ってくる。
サブエージェントの作り方
定義ファイルの形式
サブエージェントはYAMLフロントマター付きのMarkdownファイルで定義する。フロントマターがメタデータと設定を、Markdown本体がシステムプロンプト（AIへの指示）を構成する。
---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.3つの作成方法
方法 | 説明 | 推奨度 |
|---|---|---|
| ガイド付きの対話形式でセットアップ | 推奨 |
手動でMarkdown作成 |
| 中 |
| JSON形式でセッション限定のエージェントを定義 | 限定的 |
/agents コマンドを使えば、対話形式で名前・説明・ツール・モデルなどを順番に設定でき、初めてでも迷わず作成できる。
定義ファイルの解決順序
同名のサブエージェントが複数の場所に存在する場合、以下の優先度で解決される。
場所 | スコープ | 優先度 |
|---|---|---|
管理設定（組織管理者がデプロイ） | 組織全体 | 1（最高） |
| 現在のセッションのみ | 2 |
| 現在のプロジェクト | 3 |
| 全プロジェクト | 4 |
プラグインの | プラグイン有効範囲 | 5（最低） |
チーム共有には .claude/agents/ が最適である。Gitリポジトリにコミットすれば、チーム全員が同じサブエージェント定義を使える。個人用のカスタマイズは ~/.claude/agents/ に配置すると、全プロジェクトで利用可能になる。
全16フロントマターフィールド詳解
サブエージェントの設定項目は大きくコア設定、実行制御、拡張統合の3カテゴリに分類できる。
コア設定（名前・モデル・ツール）
フィールド | 必須 | 説明 |
|---|---|---|
| Yes | 小文字とハイフンを使用した一意の識別子（例: |
| Yes | Claudeが自動委譲する条件を判断する最重要フィールド |
| No |
|
| No | 許可リスト — 使用可能なツールを限定 |
| No | 拒否リスト — 特定ツールのみ除外 |
ここで最も重要なのは description である。Claudeはこのフィールドの内容に基づいて「このタスクはこのサブエージェントに委譲すべきか」を自動判断する。曖昧な説明では意図通りに委譲されないため、いつ・どんな状況で使うべきかを具体的に記述する必要がある。
model を未指定にすると inherit（メインセッションと同じモデル）が適用される。tools を省略するとMCPツールを含むメイン会話の全ツールを継承するため、実運用では必要なツールのみ明示指定することが推奨される。
tools と disallowedTools の両方が設定されている場合、disallowedTools が先に適用され、その後 tools が残りに対して解決される。
実行制御
フィールド | 説明 | デフォルト |
|---|---|---|
| 権限モード |
|
| 最大エージェントターン数（暴走防止） | なし |
|
|
|
|
| なし |
| 推論努力レベル: | なし |
permissionMode には default / acceptEdits / auto / dontAsk / bypassPermissions / plan の6つの選択肢がある。メインセッションが bypassPermissions を使用している場合、それが優先され、サブエージェント側でオーバーライドできない点に注意が必要である。
maxTurns はサブエージェントの暴走を防止する重要なフィールドで、推奨値は 10〜25 である。小タスクなら10前後、複雑な調査なら25程度に設定するとよい。
拡張統合
フィールド | 説明 |
|---|---|
| 指定したスキルの本文全体を起動時にコンテキストへ読み込む |
| 利用可能なMCPサーバー（文字列参照またはインライン定義） |
| ライフサイクルフック（ |
| 永続メモリスコープ: |
| UI表示色（ |
|
|
特に注意すべきは、サブエージェントはメイン会話のスキルを自動継承しないという点である。サブエージェントでスキルを使いたい場合は、skills フィールドに明示的にリストする必要がある。
4つの呼び出しパターン
サブエージェントの起動方法は4通りある。
方法 | 説明 | 使い方 |
|---|---|---|
自動委譲 |
| （設定するだけで適切なタイミングで自動起動） |
自然言語で指定 | プロンプト内でエージェント名を明示 |
|
@メンション |
|
|
セッション全体で使用 | CLIフラグでセッション全体に適用 |
|
自動委譲の精度を高めるテクニックとして、description に 「Use proactively」 というフレーズを含めると、Claudeがより積極的に自動委譲するようになる。例えば、公式のCode Reviewerサブエージェントでは "Use immediately after writing or modifying code" と記述されている。
組み込みエージェント
Claude Codeには、最初から利用可能な組み込みサブエージェントが搭載されている。
エージェント | モデル | ツール | 用途 |
|---|---|---|---|
Explore | Haiku | 読み取り専用 | ファイル探索・コード検索 |
Plan | メインから継承 | 読み取り専用 | プランモードでのコードベースリサーチ |
General-purpose | メインから継承 | 全ツール | 複雑なリサーチ・マルチステップ操作 |
statusline-setup | Sonnet | — |
|
Claude Code Guide | Haiku | — | Claude Code機能に関する質問対応 |
ExploreとPlanは読み取り専用エージェントであり、Write/Editツールを持たない。コードを変更せず調査のみを行う用途に最適化されている。
永続メモリ機能
memory フィールドを設定すると、サブエージェントに会話をまたいで洞察を蓄積する永続メモリディレクトリが提供される。
スコープ | 保存先 | 用途 |
|---|---|---|
|
| 全プロジェクトで共有（グローバル） |
|
| プロジェクト単位（Git管理・チーム共有可） |
|
| マシン固有（バージョン管理対象外） |
デフォルトでは無効であり、memory フィールドを明示的に指定して有効化する必要がある。公式の推奨デフォルトスコープは project（チーム共有が可能なため）である。有効化すると Read / Write / Edit ツールが自動的に付与される。
コンテキスト管理の仕組み
サブエージェント機能の最大の特徴は、完全なコンテキスト分離にある。
サブエージェントが受け取る情報
サブエージェントはメインエージェントの会話履歴を一切受け取らない。受け取るのは以下の情報のみである。
- エージェント定義（.mdファイルの本文 = システムプロンプト）
- タスク指示（Claudeがユーザーの依頼から生成したもの）
- 環境詳細（作業ディレクトリ、プラットフォーム等）
- 指定スキル（
skillsフィールドで指定した場合のみ） - 永続メモリ（
memory有効時のみ、MEMORY.mdの先頭200行/25KB）
コンテキスト消費の仕組み
何が起きるか | メインのコンテキスト消費 |
|---|---|
サブエージェントがファイルを読む | 消費しない（サブ側のみ） |
サブエージェントが試行錯誤する | 消費しない（サブ側のみ） |
サブエージェントの最終結果が返る | 消費する |
つまり、サブエージェントが大量のファイルを読んだり、何度も試行錯誤したりしても、メインに返るのは最終結果の要約だけである。中間処理のトークンはメインのコンテキストを一切消費しない。これが長時間セッションでのコンテキスト枯渇を防ぐ重要な仕組みとなっている。
実行モード: フォアグラウンドとバックグラウンド
サブエージェントの実行には2つのモードがある。
方式 | 待機 | 権限の承認タイミング |
|---|---|---|
フォアグラウンド（デフォルト） | 完了まで待つ | 操作のたびにユーザーに確認 |
バックグラウンド | 待たない（並行作業可） | 開始前にまとめて承認（実行中は確認なし） |
コンテキスト消費はどちらのモードでも同じ（戻り値のみ）である。バックグラウンドモードでは、開始前に承認しなかった操作は自動で拒否される点に注意が必要である。
バックグラウンドへの切り替え方法
- 実行中に切り替え: Ctrl+B でフォアグラウンド実行中のサブエージェントをバックグラウンドに送る
- 呼び出し時に指定: Claudeに 「run this in the background」 と自然言語で依頼
サブエージェントの再開
各サブエージェント呼び出しは、デフォルトで新しいコンテキストの新しいインスタンスを作成する。ただし、Claudeに「再開して」と依頼すれば、全ツール呼び出し・結果・推論を含む完全な会話履歴を保持したまま、停止した場所から正確に再開できる。Claude Codeを再起動した後でも、同じセッションを再開することでサブエージェントの再開が可能である。
サブエージェントの3つのメリット
メリット1: 役割分離による品質向上
Anthropic公式ブログでは、Planner（計画）/ Generator（生成）/ Evaluator（評価）を別エージェントに分担する3役構成が、単一エージェントより顕著に高品質な出力を生むと報告されている。
その理由は、自己評価バイアスにある。エージェントは自分の成果物を甘く採点する傾向がある。生成者を批判的にするより、独立した評価者を懐疑的にチューニングする方がはるかに扱いやすい。「作業する役」と「評価する役」を分離することで、この問題を回避できる。
メリット2: コンテキスト節約と並列高速化
コンテキスト管理のセクションで解説した通り、中間処理はメインに返らず最終結果のみが返るため、メインのコンテキスト寿命が大幅に延びる。長時間セッションや大規模タスクほどこの効果は大きくなる。
並列実行による高速化の実績として、以下のような報告がある。
タスク | Before | After |
|---|---|---|
テストリファクタリング | 8分 | 3分未満（4並列サブエージェント） |
テストスイートを4つのサブエージェントに分割並列実行することで、順次実行の8分が3分未満に短縮された事例である。
メリット3: 柔軟なカスタマイズと制御
- 最小権限の設定: リサーチ用は読み取り専用（Read, Grep, Glob のみ）、実装用はフル権限など、エージェントごとにツールアクセスを細かく制御できる
- モデルの使い分け:
modelフィールドでHaiku（高速・安価）/ Sonnet（バランス）/ Opus（高度な判断）を目的に応じて指定できる
制約事項
サブエージェントには以下の制約がある。
- ネスト不可: サブエージェントは他のサブエージェントを生成できない（無限再帰防止のための設計上の制約）
- コンテキスト非共有: メインエージェントの会話履歴や他のサブエージェントの出力はサブエージェントに渡されない。必要な情報はタスク指示に明示的に含める必要がある
- ファイル競合: 同一ファイルを複数のサブエージェントが並列編集すると競合が発生する
サブエージェントを使うべきタイミング
Anthropic公式ブログが示す判断基準は明確である。
使うべき場面
- 10以上のファイルを探索する必要がある — 大規模なコード調査
- 3つ以上の独立した作業がある — 並列実行で高速化
- 偏りのないセカンドオピニオンが必要 — 独立した評価
使うべきでない場面
- 順序依存の作業: ステップ2がステップ1の完全な出力を必要とする場合
- 同一ファイルへの並列編集: 競合が発生する
- オーバーヘッドが利点を上回る小さなタスク: 単純な作業にサブエージェントを使うとかえって遅くなる
他の機能との比較: Subagent vs Agent Teams
Claude Codeには「サブエージェント」の他に「Agent Teams」というマルチエージェント機能が存在する。両者の違いを理解することは、適切な選択のために重要である。
観点 | Subagent | Agent Teams |
|---|---|---|
セッション | メインと同一セッション | 別セッション間で調整 |
コンテキスト | メインとは独立だが、結果はメインに返る | 各メンバーが完全に独立（結果もメインに返らない） |
情報の流れ | サブ→メインの一方向のみ | メンバー間で双方向メッセージ |
タスク管理 | メインエージェントが全体を管理 | 共有タスクリストで自律的に調整 |
コスト | 中程度 | 高い（プランモード時は約7倍） |
適したタスク | 独立性が高く衝突しにくい作業（結果だけ返れば足りる） | 議論・協調が必要な複雑作業 |
アーキテクチャの核心的な違いは、サブエージェントが同一セッション内で動作するのに対し、Agent Teamsは別セッション間で協調する点にある。
選択の指針
- 結果だけ返してもらえれば十分（調査結果、レビュー結果など）→ サブエージェント
- メンバー間で議論・協調が必要（設計方針のすり合わせ、依存関係のある実装など）→ Agent Teams
- コストを抑えたい → サブエージェント
まとめ
本記事では、Claude Codeのサブエージェント機能の全体像を解説した。ポイントを振り返る。
- 簡単に作れる:
/agentsコマンドで対話形式に従うだけでカスタムエージェントを作成できる - 品質向上の仕組み: Planner / Generator / Evaluator など役割分担した構成で、単一エージェントより高品質なアウトプットを実現できる
- コンテキスト最適化: 中間処理がメインに返らず結果のみが返るため、コンテキスト消費を大幅に抑制できる
- Claude Code内での位置付け: サブエージェントはメインセッションと並ぶ「実行主体」の1つであり、Skill / MCP（能力拡張）やCLAUDE.md / Hook（ルール制御）とは役割のレイヤーが異なる
次回の「実践ガイド編」では、設計のベストプラクティス、公式プラグインから学ぶ実装パターン、Building Effective Agentsの4つのワークフローパターン、そしてXで注目の活用事例を紹介する。
