サブエージェントとは何か

サブエージェントは、メイン会話とは別の独立したコンテキストで動く専門アシスタントです。特定の作業を、本体の会話を汚さずに任せられます。

Claude Code（Anthropic のコマンドライン向け AI コーディングツール）が提供する機能で、claude.ai のチャット UI にはありません。以下では Claude Code の公式ドキュメントを「公式」と呼びます。

各サブエージェントは次の特性を持ちます。

• 独立したコンテキストウィンドウ
• カスタムシステムプロンプト
• 個別のツール権限
• 完了時に最終結果の要約だけを親会話へ返す

公式が挙げるメリットは5つあります。

1. コンテキストの温存。探索や実装のログをメイン会話から隔離できます
2. 制約の強制。使えるツールを絞ってリスクを下げられます
3. 設定の再利用。ユーザースコープに置けば複数プロジェクトで共有できます
4. 振る舞いの専門化。ドメイン特化のシステムプロンプトを与えられます
5. コストの制御。Haiku など軽量モデルへルーティングできます

親会話に戻るのは最終要約だけです。サブエージェント内のツール呼び出し履歴は親へ流れません。ここがコンテキスト圧迫を抑える肝になります。

内蔵サブエージェントの種類と使い分け

自作しなくても使える内蔵サブエージェントが5種類あります。多くのケースはこれでまかなえます。

5種類の比較

使い分けの判断軸

判断軸はシンプルです。読み取りだけの軽い検索なら Explore、設計判断を含むなら Plan、編集やコマンド実行が必要なら general-purpose を選びます。Claude Code 自身の機能を調べたいときは claude-code-guide が向いています。

ひとつ注意点があります。Explore と Plan は CLAUDE.md と git status を読み込みません。軽量化のための設計です。プロジェクト固有のルールに沿った判断が要る場面では、これらではなく、ルールを継承するカスタムサブエージェントを使うほうが安全です。

サブエージェントを呼び出す3つの方法

呼び出し方は、手軽な順に3パターンあります。まず全体像をつかむと、状況に応じて選べます。

自動委任

メイン会話で自然文の依頼を書くと、Claude が各サブエージェントの description を見て委任先を判断します。

たとえば「テストランナーで失敗を直して」と書くだけで、該当する description を持つサブエージェントが起動します。委任の精度は description の書き方で変わるので、後の節で詳しく扱います。

@メンションで明示的に呼ぶ

@agent-code-reviewer のように打つと、そのサブエージェントが確実に起動します。入力中に @ を打つと候補がポップアップするので、選択もできます。

プラグイン経由のサブエージェントは @agent-my-plugin:code-reviewer のように名前空間付きで呼びます。自動委任に頼らず狙って呼びたい場面で使います。

セッション全体を起動する

3つのなかで最も影響範囲が広い方法です。claude --agent code-reviewer で、セッション開始時から指定のサブエージェントとして起動できます。.claude/settings.json の "agent": "code-reviewer" でも同じ効果が得られます。

この方法ではサブエージェントのシステムプロンプトがデフォルトを置き換えます。レビュー専門の窓口や、デバッグ専用ターミナルといった単機能のセッションを作るのに向いています。CLI フラグは設定ファイルより優先されます。

他機能との役割分担

自作に入る前に、似た機能との違いを整理します。ここを押さえると、何をサブエージェント化すべきかの判断が速くなります。

Claude Code には、サブエージェントと役割が似た機能が複数あります。

判断の目安は次の通りです。

• 独立コンテキストが欲しい → サブエージェント
• ガイドラインを参照させたいだけ → スキル
• ユーザー操作で呼びたい固定処理 → スラッシュコマンド
• ツール実行の前後で何かしたい → Hooks
• 外部システムへのアクセス → MCP

とくにサブエージェントとスキルは混同しやすい部分です。サブエージェントは別の担当に任せる仕組み、スキルは自分が読むマニュアル、と理解すると整理しやすくなります。

カスタムサブエージェントの作り方

内蔵で足りないときは自作します。定義は Markdown ファイル1枚で済みます。作成方法は2系統あります。

Claude に作ってもらう

いちばん手軽なのは、Claude に定義を書いてもらう方法です。「コードレビュー用のサブエージェントを作って」のように頼むと、frontmatter と本文の下書きを生成してくれます。生成された定義を .claude/agents/ に保存すれば、そのまま使えます。

ファイルを直接配置する

.claude/agents/foo.md ならプロジェクト用、~/.claude/agents/foo.md なら個人用（全プロジェクト共通）として認識されます。保存先で共有範囲が変わる点がポイントです。ファイルを直接書き換えた場合は、変更を反映するためにセッションの再起動が必要になります。

配置場所と優先順位

同じ name のサブエージェントが複数階層に存在すると、優先度が高いほうが採用されます。

プロジェクト用と個人用が同名で重複した場合は、プロジェクト用が勝ちます。

ファイルの基本構造

frontmatter（Markdown 冒頭の YAML 形式メタ情報ブロック）にメタ情報を書き、本文をシステムプロンプトとして記述します。まずは基本形を見てみます。

---
name: code-reviewer          # エージェント名。小文字とハイフンのみ
description: コードレビュー専門。品質・セキュリティ・保守性を率先して確認する。コードの記述や修正の直後に使う。
tools: Read, Grep, Glob, Bash # 使えるツール
model: inherit               # 使うモデル。inherit は親会話と同じ
---

あなたは、コード品質とセキュリティの高い水準を担保するシニアなコードレビュアーです。

呼び出されたら、次の順で進めます。
1. git diff を実行して最近の変更を確認する
2. 変更のあったファイルに絞る
3. すぐにレビューを始める

この記事のコード例は、読みやすさのため説明部分を日本語で示しています。実際には description は英語で書くと自動委任が安定しやすく、name・tools・model などの値は英字で指定します。以降のサンプルも同じ方針です。

これを保存すると、Claude Code が自動的に検出し、委任候補として認識します。

主要な4つのフィールド

日常的に書くのは name / description / tools / model の4つです。まずはこれだけ押さえれば自作を始められます。

name は小文字とハイフンのみの識別子です。ファイル名と一致させる義務はありませんが、そろえると管理しやすくなります。Hooks のコンテキスト変数 agent_type にも、この name が渡ります。

description は Claude が委任判断を行う材料です。冒頭で役割を一言で示し、いつ起動すべきかを明示します。書き方は次の章で詳しく扱います。

tools は省略するとメイン会話で使える全ツールを継承します。許可リストとして列挙すれば、そのツールだけが使えます。継承できないツールもあります。AskUserQuestion や EnterPlanMode など、UI やセッション状態に依存するものは渡りません。MCP のツールはサーバー単位でも指定でき、mcp__myserver でそのサーバーの全ツールを許可、mcp__* で全 MCP ツールを拒否できます。

model はデフォルトが inherit で、メイン会話と同じモデルを使います。明示する場合は sonnet / opus / haiku / fable のエイリアス、または claude-opus-4-8 のような完全 ID を指定します。軽い検索系には haiku、複雑な設計判断には opus、コスト効率を重視するなら sonnet という使い分けが目安です。

その他のフィールド

frontmatter には、ほかにも12のフィールドがあります。特殊な要件で使うもので、必要になったとき参照すれば十分です。

disallowedTools を tools と併用すると、先に除外を適用してから tools が解決される順序になります。

自動委任が効く description の書き方

自動委任の精度は description で決まります。Claude はユーザーの依頼内容、各サブエージェントの description、現在のコンテキストの3つを見て委任先を選ぶためです。

言語は英語で書くのが無難です。Claude は英語の description を解釈しやすい傾向があり、既存のサンプルやドキュメントとも整合が取りやすくなります。

良い description の3要素

• 役割の一言定義
• 使うタイミングのトリガー
• 起動条件を示す文言（Use proactively や Use immediately after）

公式の code-reviewer が好例です。英語で書く効果を示すため、原文のまま引用します。

Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.

日本語では「コードレビュー専門。品質・セキュリティ・保守性を率先して確認する。コードの記述や修正の直後に使う」という意味です。役割、使うタイミング、proactively というキーワードがそろっています。

悪い description の例

A helpful agent.

日本語では「役に立つエージェント」程度の意味です。これでは Claude は委任判断ができません。いつ、何のために使うかが欠けているため、結果として呼ばれずに終わります。

設計のコツ

• 想定するユーザーの依頼文を逆算する。「テストが失敗した」「レビューしてほしい」といった典型プロンプトから自然に発火するように書きます
• スコープの境界を書く。do と don't の形で扱う範囲を明示すると、誤起動が減ります

公式サンプルで学ぶ実装例

公式は4つのサンプルを示しています。tools と model の使い分けの手本になります。description は日本語に訳して示します。順に読み解きます。

code-reviewer

---
name: code-reviewer
description: コードレビュー専門。品質・セキュリティ・保守性を率先して確認する。コードの記述や修正の直後に使う。
tools: Read, Grep, Glob, Bash # 読み取り系のみ。Edit と Write は外す
model: inherit
---

Edit と Write をあえて入れていないのがポイントです。レビュー専門という位置づけなので、コード変更は許さず、提案だけを返します。git diff を見て、指摘を重要度別に整理する設計です。

debugger

---
name: debugger
description: エラー・テスト失敗・想定外の挙動に対応するデバッグ専門。問題が起きたら率先して使う。
tools: Read, Edit, Bash, Grep, Glob # 修正もするので Edit を含める
---

修正もするので Edit が入っています。エラーの捕捉、再現手順の確認、失敗箇所の特定、最小修正、検証というワークフローを内蔵させる想定です。

data-scientist

---
name: data-scientist
description: SQL クエリ・BigQuery 操作・データ分析の専門。分析やクエリの作業で率先して使う。
tools: Bash, Read, Write
model: sonnet # スループット重視でモデルを固定
---

明示的に sonnet を指定しています。SQL や BigQuery の bq コマンドを扱う処理が中心で、深い推論よりスループットが効くため、コスト効率の良いモデルに固定する設計です。

db-reader

---
name: db-reader
description: 読み取り専用のデータベースクエリを実行する。データ分析やレポート生成で使う。
tools: Bash
hooks:
  PreToolUse:          # ツール実行前に発火するフック
    - matcher: "Bash"  # Bash の実行を対象にする
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh" # 書き込み系 SQL をここで弾く
---

Bash を持たせつつ、PreToolUse フックで書き込み系 SQL をブロックします。tools フィールドだけでは表現できない条件分岐を Hooks で補う例で、応用範囲が広いパターンです。

並列実行と入れ子のサブエージェント

サブエージェントは並列で実行できます。複数のタスクを同時に走らせると、調査や検証の時間を短縮できます。

1つのメッセージ内で複数の Agent ツール呼び出しを行うと、それぞれ独立したサブエージェントが同時に走ります。「認証、データベース、API の各モジュールを並列に調査して」と指示すれば、3つの Explore が並走するイメージです。

ただし、各サブエージェントの最終結果は親会話へ戻されます。大量に並走させると親コンテキストが圧迫されるので、公式も注意を促しています。目安は3〜5並列です。

実行モードには foreground と background があります。foreground は完了までメイン会話をブロックし、background は同時並行で動きます。background の権限要求はメインセッションに浮上し、個別に許可や拒否ができます。まとめて止めたいときは、環境変数 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 を設定します。

サブエージェントは自身からさらにサブエージェントを呼ぶ、入れ子の構成もできます。ただし実用上は3層もあれば十分で、それ以上を深追いする必要はまずありません。

運用上の注意点と落とし穴

• 最後に、実運用で詰まりやすいポイントをまとめます。事前に知っておくと、権限やセキュリティの設定でつまずきにくくなります。
• 内蔵の Explore と Plan は一度きりの実行で、agent ID を返しません。起動済みのサブエージェントに追い指示を出す（継続対話）には agent ID が要ります。継続して対話したい場合は、general-purpose か独自のカスタムサブエージェントを使います。
• Markdown ファイルを直接書き換えてサブエージェントを追加や編集した場合、変更の反映にセッションの再起動が要ることがあります。反映されないと感じたら、まず再起動を確認します。
• 権限まわりにも癖があります。permissionMode は、ツール実行時に権限プロンプトをどう出すかを決める設定です。bypassPermissions はプロンプトを丸ごとスキップし、acceptEdits は編集を自動承認します。bypassPermissions は便利な反面、.git や .claude などの設定ディレクトリへの書き込みも通ります。明示的な ask ルールや rm -rf / 系は依然プロンプトが出ますが、過信は禁物です。
• 権限モードは親から子へ引き継がれる点にも注意します。親セッションが bypassPermissions か acceptEdits、または auto モードのときは、子サブエージェントの permissionMode では上書きできません。意図したセキュリティ設定が効かないことがあるので、親の状態を把握しておくと安心です。
• プラグイン経由で配布されるサブエージェントでは、hooks と mcpServers と permissionMode は無視されます。第三者プラグインから強い権限が降りないようにするための制約です。

まとめ

サブエージェントは、Claude Code に専門の担当を用意する仕組みです。コンテキストを汚さずに調査やレビュー、デバッグを任せられ、ツール権限を絞ったりモデルを切り替えたりもできます。

• 内蔵5種類で多くのケースはまかなえる
• カスタムは Markdown 1ファイルで作れる
• description の書き方が自動委任の精度を決める

チーム開発では、定義をプロジェクトに含めて Git で共有すると、一貫したレビュー観点やデバッグ手順を運用できます。たとえばヘッドレスCMS の NILTO を運用するチームなら、入稿やレビューの手順をサブエージェント化しておくと、定型作業を任せやすくなります。

まず試すなら、直近で繰り返している作業をひとつ選び、Claude に頼んで専用のサブエージェントを1つ作ってみるのがおすすめです。コードレビューやデバッグのような定型タスクが向いています。