Claude Code サブエージェントとは？作り方・frontmatter全項目・呼び出し方まとめ【2026年版】

Claude Code サブエージェントは、メインのセッションとは別の独立したコンテキストウィンドウで動く専用エージェントです。本記事では公式ドキュメントに基づき、サブエージェントとは何か、.claude/agents/への定義ファイルの作り方、frontmatterの全フィールド、呼び出し方3パターンを1ページにまとめます。

サブエージェントの位置づけを含むClaude Code全体の機能は Claude Code｜2026年版・インストールからCLAUDE.md・Hooks・本番運用までの実装手引き で体系的にまとめています。まずはサブエージェント単体の仕組みから見ていきます。

Claude Code サブエージェントとは何か——通常のセッションと何が違うのか

Claude Code サブエージェントは、メインの会話セッションとは別に、独立したコンテキストウィンドウ・独自のシステムプロンプト・独自のツールアクセス・独自の権限設定を持つ専用エージェントです。公式ドキュメントはこれを「メインの会話から呼び出せる、特化した目的を持つAIアシスタント」と定義しています。Claude Code自体のインストールや基本操作は Claude Codeとは？Anthropic公式AIコーディングツールの使い方・インストール・料金【2026年版】 を参照してください。

通常のClaude Codeセッションでは、会話が進むほどコンテキストウィンドウに情報が積み上がり、無関係な調査や大量のファイル読み込みが本題の作業を圧迫することがあります。サブエージェントに切り出すと、その調査・レビュー・検証といった作業は別のコンテキストで完結し、結果だけがメインセッションに戻ります。

・コンテキストの分離：サブエージェントの中でどれだけファイルを読んでも、メインセッションのコンテキストは消費しない
・役割の固定：システムプロンプトをサブエージェントごとに専用化できる（コードレビュー専任・セキュリティ監査専任など）
・権限の分離：tools/disallowedTools/permissionModeでサブエージェントごとにアクセス範囲を絞れる
・並列実行の単位：複数のサブエージェントを同時に立ち上げて別々の作業を進めることができる（ただし同時実行数の明示的な上限は公式ドキュメントに記載がなく未確認）

サブエージェントに切り出す判断基準

すべての作業をサブエージェントにする必要はありません。判断基準は「その作業がメインの会話の文脈から独立して完結するか」です。

・切り出しやすい作業：コードレビュー・大量ファイルの調査・特定観点でのチェック（セキュリティ・命名規則など）——結果だけをメインへ返せば十分な作業
・切り出しにくい作業：ユーザーとの対話を重ねながら方針を決めていく設計相談や、直前のやり取りの文脈を強く参照する編集作業
・迷ったら、そのタスクを「他の人に一言で依頼できるか」で判定するとよい。依頼文がそのままdescriptionになる

Claude Code サブエージェントの作り方：定義ファイルの置き場所とYAML frontmatter

サブエージェントの実体は、YAML frontmatter＋Markdown本文で書かれた1個の.mdファイルです。置き場所は2種類あり、どちらに置くかで有効範囲と優先度が変わります。

・プロジェクト用：.claude/agents/<name>.md に置く。そのプロジェクトを開いたときだけ有効で、優先度3
・ユーザー用：~/.claude/agents/<name>.md に置く。どのプロジェクトでも有効で、優先度4
・プラグイン提供：プラグインが提供するサブエージェントは最も優先度が低い（優先度5）
・同名のサブエージェントが複数の場所にある場合は、より優先度の高い場所（数字が小さい方）が使われる

実際に最小構成のサブエージェントを作ると、以下のようになります（公式ドキュメント記載の例）。

mkdir -p .claude/agents

---
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.

nameは小文字とハイフンのみで構成し、:は使用できません。frontmatterの下のMarkdown本文が、そのままサブエージェントのシステムプロンプトになります。

frontmatterフィールド完全リファレンス

上位の解説記事の多くはname/description/tools程度しか触れていませんが、サブエージェントのfrontmatterには実行制御・外部連携・表示に関わる項目が用意されています。

必須フィールドはnameとdescriptionの2つだけで、それ以外はすべて任意です。skills/mcpServers/hooksの3つは、それぞれSkill（コンテキストへの内容注入）・MCP（外部サーバー接続）・Hook（ライフサイクルイベント発火）という別メカニズムを、サブエージェント側から利用するための設定であり、サブエージェント自体の機能とは役割が異なります。

実行制御系フィールドの使い分け

tools/disallowedTools/permissionMode/maxTurns/model/effort/isolationは、そのサブエージェントが「どこまで動けるか」を決める項目です。

・toolsとdisallowedTools：許可リストと禁止リストの関係。コードレビュー専任ならtools: Read, Glob, Grepのように読み取り系だけを許可し、書き込み権限を持たせない設計ができる
・model：サブエージェントごとに使うモデルを固定できる。既定のinheritは呼び出し元セッションと同じモデルを使う
・maxTurns：意図せず長時間動き続けることを防ぐ上限
・isolation: worktree：実行環境を分離する指定。並行して複数のサブエージェントがファイルを変更する場合に競合を避ける用途で使う項目

連携系フィールドの使い分け

skills/mcpServers/hooks/memoryは、そのサブエージェントに何を持たせるかを決める項目です。いずれも指定しなければ、そのサブエージェントは連携なしの最小構成で動きます。

・skills：起動時にプリロードするSkillを指定する。特定の手順知識を常に持たせたい場合に使う
・mcpServers：利用できるMCPサーバーの範囲を絞る。外部システムへの接続が必要なサブエージェントにだけ設定する
・hooks：そのサブエージェントにスコープしたライフサイクルイベント処理を追加する
・memory：user/project/localのいずれかで、参照するメモリの範囲を指定する

呼び出し方3パターンとバックグラウンド実行の挙動

サブエージェントの呼び出し方は3パターンあります。

・自然言語で依頼：ユーザーの発言内容からClaude自身がどのサブエージェントに委任するか判断する
・@メンション：@<name>のように名指しして、確実にそのサブエージェントを実行させる
・--agentフラグ：CLI起動時の--agent <name>、または.claude/settings.jsonのagentキーで、セッション全体を最初からそのサブエージェントとして起動する
・実行方式はフォアグラウンド／バックグラウンドの2種類があり、フォアグラウンド実行はメイン会話をブロックする

2.1.198以降、サブエージェントはデフォルトでバックグラウンド実行されます。バックグラウンド実行時は利用できる組み込みツールが縮小され、Read/Grep/Glob/Bash/PowerShell/Edit/Write/NotebookEdit/WebFetch/WebSearch/TodoWrite/Skill/ToolSearch等に限定されます。「並列実行」については公式ドキュメントで”spawn multiple subagents to work simultaneously”と例示されていますが、同時実行数の明示的な数値上限はドキュメントに記載がなく未確認です。上限を前提にした運用設計をする場合は、この点が未公表であることを踏まえてください。

フォアグラウンドとバックグラウンドの使い分け

3つの呼び出し方とは別に、実行方式（フォアグラウンド／バックグラウンド）という軸もあります。

・フォアグラウンド実行：メイン会話をブロックする。サブエージェントの結果を見てから次を判断したい、対話的な調査に向く
・バックグラウンド実行：メイン会話をブロックしない。2.1.198以降はこちらが既定。複数のサブエージェントを並行して走らせつつメイン会話を続けたい場合に向くが、利用できる組み込みツールが上記の一覧に縮小される点に注意する
・ツールを絞り込んだ調査・レビュー系の作業はバックグラウンドの制限に収まりやすく、UI操作や対話的な確認を伴う作業はフォアグラウンドが向いている

Skill・Hook・MCPとの使い分け

Claude Codeには、サブエージェント以外にもコンテキストや外部連携を拡張する仕組みが複数あります。frontmatterのskills/hooks/mcpServersフィールドが指し示す先でもあるため、役割の線引きを整理します。

frontmatterのskills/hooks/mcpServersはいずれも、そのサブエージェントに何を持たせるかの設定であり、サブエージェント自体を代替する仕組みではありません。用途で迷ったら「別コンテキストで独立して動かしたいか」で判断できます。独立させたいならサブエージェント、現在のコンテキストのまま知識だけ足したいならSkill、イベント発火で自動化したいならHook、外部システムに繋ぎたいならMCPです。Skillの仕組みそのものを詳しく知りたい場合は Claude Skillsとは｜「スキル=フォルダ」の仕組みと作り方・使い方を徹底解説 にまとめています。サブエージェントを含むClaude Code内部の設計思想は Claude Codeの内部アーキテクチャ完全解剖：331モジュールから読み解く本番エージェント設計の全貌 で扱っています。

組み合わせて使う例

4つの仕組みは排他ではないため、1つのサブエージェントに複数を組み合わせられます。たとえば「コードレビュー専任のサブエージェント」を作るなら、次のように役割を積み重ねる設計になります。

・サブエージェント本体：code-reviewerとして独立コンテキストで起動する
・skills：社内のレビュー観点をまとめたSkillをプリロードし、毎回同じ基準でレビューさせる
・hooks：レビュー完了後に特定のコマンドを自動実行するHookをスコープする
・mcpServers：社内のIssue管理システムに接続するMCPサーバーをスコープし、レビュー結果をそのまま起票できるようにする

まとめ

参照ソース

・Create custom subagents（公式ドキュメント） — 定義ファイルの仕様・呼び出し方・frontmatter全フィールドを取得
・Claude Code Docs トップ — Skill/Hook/MCPとの関連ドキュメントへの導線を確認