Claude Codeのサブエージェントとは？作り方と権限・モデル設定

Claude Codeのサブエージェントは、メインの会話とは別のコンテキストウィンドウで特定の作業を引き受け、結果の要約だけを返す専門アシスタントです。作り方は、YAMLのfrontmatter付きMarkdownファイルを .claude/agents/（そのプロジェクト用）か ~/.claude/agents/（全プロジェクト用）に置くだけで、必須の項目は name と description の2つです。使えるツールは tools、モデルは model、権限モードは permissionMode で決めます。以下、公式ドキュメント「Create custom subagents」の記述に沿って、作り方、設定項目の決め方、呼ばれないときの切り分けを順に説明します。

Claude Codeのサブエージェントは何をするのか

公式の定義では、サブエージェントは「検索結果やログ、二度と見ないファイルの中身で本題の会話があふれそうな脇道の作業」を引き受け、自分のコンテキストで処理して要約だけを返します。それぞれが独自のコンテキストウィンドウ、システムプロンプト、ツールの許可、権限を持って動きます。

押さえておきたい性質は次の4つです。

会話履歴を見ない: サブエージェントは新しいコンテキストで始まり、メインの会話履歴、すでに使ったスキル、Claudeが読んだファイルを見ません。Claudeがタスクを要約した委任メッセージを書き、サブエージェントはそこから作業します。
使用量は同じ枠に数えられる: サブエージェントも自分でリクエストを送り、それはメインの会話と同じ使用量の上限に数えられます。
1つのセッションの中で動く: 複数のセッションを協調させる仕組みは別機能のエージェントチームです。違いはエージェントチームの記事で扱っています。
Claudeが description を見て委任先を選ぶ: 依頼内容に合う description を持つサブエージェントがあれば、Claudeがそこへ作業を渡します。

カスタムのサブエージェント定義ファイルを作るべき目安として、公式は「同じ指示を持つ同じ種類の作業者を何度も立ち上げているとき」を挙げています。

最初から入っている組み込みサブエージェントは何か

自分で何も作らなくても、Claude Codeには組み込みのサブエージェントがあり、Claudeが適切な場面で自動的に使います。どれも親の会話の権限設定ルールを継承し、多くは制限されたツールで動きます。

名前	ツール	主な用途
Explore	読み取り専用（Write と Edit は拒否）	ファイル探索、コード検索、コードベースの調査
Plan	読み取り専用（Write と Edit は拒否）	プランモード中の、計画を出す前の調査
General-purpose	サブエージェントで使える全ツール	探索と変更の両方が要る、複数段階の作業

Explore と Plan では、次の2点にも注意します。1つは、調査を速く安く済ませるため、CLAUDE.md と git status のスナップショットを読まずに始まることです。もう1つは、1回きりで agent ID を返さないため、後から再開できないことです。続きを頼みたい作業には General-purpose かカスタムのサブエージェントを使います。

ユーザーかプロジェクトの範囲に Explore という名前のサブエージェントを置くと組み込みを上書きでき、model: haiku を指定すれば調査を低コストのモデルで回せます。

カスタムサブエージェントはどう作るのか

作成方法は2通りです。Claudeに書かせるか、ファイルを自分で書くかです。

Claudeに書かせる

公式のクイックスタートでは、作りたいサブエージェントと保存先を自然な文章で伝えます。公式の例文は次のとおりです。

Create a personal code-improver subagent in ~/.claude/agents/ that scans
files and suggests improvements for readability, performance, and best
practices. It should explain each issue, show the current code, and
provide an improved version. Make it read-only and have it use Sonnet.

公式によれば、Claudeは name、description、tools、model とシステムプロンプトを含むファイルを書きます。書き上がったら、frontmatterが依頼どおりかを自分で開いて確認します。公式に載っている構成ファイルの例は次のとおりです。

---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---

You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.

なお /agents コマンドは、現行版では「Claudeに頼むか .claude/agents/ と ~/.claude/agents/ を直接編集する」よう案内を表示するだけです。対話式の作成ウィザードが開くのは v2.1.197 以前です。古い解説記事の手順と画面が違うのはこのためです。

自分でファイルを書く

frontmatterの下に書いた本文が、そのままサブエージェントのシステムプロンプトになります。サブエージェントが受け取るのはこのシステムプロンプトと作業ディレクトリなどの基本的な環境情報だけで、Claude Code本体のシステムプロンプトは受け取りません。役割や手順、出力の形は本文に書き切る必要があります。

ファイルを追加・編集すると、Claude Codeは数秒以内に変更を検出し、次の委任から新しい定義を使います。再起動は要りません。

どこに置くか（優先順位）

同じ name のサブエージェントが複数あるときは、優先順位の高い場所のものが使われます。

場所	範囲	優先順位
管理設定（managed settings）	組織全体	1（最高）
`--agents` CLIフラグ	そのセッションだけ	2
`.claude/agents/`	現在のプロジェクト	3
`~/.claude/agents/`	自分の全プロジェクト	4
プラグインの `agents/`	プラグインが有効な場所	5（最低）

.claude/agents/ と ~/.claude/agents/ はサブフォルダまで再帰的に読まれるので、agents/review/ のように分けて整理できます。ただし識別に使われるのは name だけです。同じディレクトリ配下（サブフォルダ含む）で同名のファイルが2つあると、どちらが読まれるかは定まりません。/doctor がこの重複を報告します。

frontmatterでは何を設定できるのか

必須は name と description だけで、他は省略できます。よく使う項目を挙げます。

項目	内容
`name`	一意の識別子（256文字以内）。`:` は使えない。ファイル名と一致させる必要はない
`description`	Claudeがいつこのサブエージェントに委任すべきか
`tools`	使えるツール。省略するとサブエージェントで使える全ツールを継承
`disallowedTools`	拒否するツール。継承または指定したリストから取り除く
`model`	`sonnet`、`opus`、`haiku`、`fable`、`claude-opus-5-5` のようなモデルIDそのもの、または `inherit`
`permissionMode`	`default`、`acceptEdits`、`auto`、`dontAsk`、`bypassPermissions`、`plan`（`manual` は `default` の別名）
`maxTurns`	止まるまでのターン数の上限。上限に達すると出力は部分的なものとして返り、再開できる（部分的という印は v2.1.246 以降）
`skills`	起動時に読み込むスキル。説明だけでなく全文が注入される
`memory`	会話をまたいで残る記憶の範囲。`user`、`project`、`local`
`isolation`	`worktree` にすると一時的な git worktree で動く。変更がなければ自動で片付けられる
`omitClaudeMd`	`true` でユーザー・プロジェクト・ローカルの CLAUDE.md を読まずに起動（v2.1.271 以降）

項目名は綴りにも注意が必要です。複数語の項目は maxTurns や disallowedTools のようなcamelCaseで、表と正確に一致させる必要があります。Claude Codeは認識できない項目をエラーなしで無視するため、綴りを間違えても通常のエラー表示では気づきにくくなります。確認方法は後半の切り分けの節で説明します。

ツールと権限はどう絞るのか

ツールは tools（許可リスト）と disallowedTools（拒否リスト）で絞り、権限モードは permissionMode で決めます。

tools と disallowedTools

tools は許可リスト、disallowedTools は拒否リストです。両方を書くと、先に disallowedTools が適用され、残ったツールの中から tools が決まります。

公式の例では、tools を Read、Grep、Glob、Bash だけにすると、ファイルの編集や書き込み、MCPツールは使えなくなります。

---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---

逆に、Write と Edit のツールだけを外して残りのツールを引き継ぐなら disallowedTools を使います。公式の説明では、この場合も Bash や MCP ツールは残ります。

---
name: no-writes
description: Inherits the available tools except file writes
disallowedTools: Write, Edit
---

公式の例も、この使い分けに沿っています。レビュー役の code-reviewer は Edit と Write を外した読み取り中心の構成で、修正まで担う debugger は Edit を含めています。調べるだけの役には書き込みを渡さず、直す役にだけ渡す、という分け方です。

ここで間違えやすい点が1つあります。disallowedTools に Bash(git push *) のような条件付きの書き方をしても、消えるのは該当コマンドだけではなく Bash ツール全体 です。Bash は残して特定のコマンドだけ止めたい場合は、設定ファイルの permissions.deny に Bash の拒否ルールを書きます。このルールはメインの会話にもサブエージェントにも効きます。

permissionMode はいつ効くのか

permissionMode を書かなければ、サブエージェントはメインの会話の権限モードを引き継ぎます。書いた場合も、効くかどうかはメインの会話のモードで決まります。

メインが bypassPermissions、acceptEdits、auto モードのときは、サブエージェントも同じモードで動き、書いた permissionMode は無視されます。
メインが default、dontAsk、plan のときは、書いた permissionMode で動きます。ただし bypassPermissions を書いた場合は、メインの会話のモードのままです。

各モードの意味は権限モードの記事にまとめています。

より細かい制御には PreToolUse フックを使います。公式の例では、読み取り専用のデータベース問い合わせだけを許すサブエージェントのfrontmatterの hooks に PreToolUse フックを書き、検証スクリプトが書き込み系のSQLを見つけると終了コード2を返してブロックします。フック自体の書き方はhooksの記事に譲ります。なお、プロジェクトのサブエージェントに書いたフックは、そのフォルダを信頼するまで実行されません。

モデルはどの順番で決まるのか

サブエージェントのモデルは、次の順で最初に見つかったものが使われます。

Claudeが呼び出すときに渡す model パラメータ
サブエージェント定義の model（inherit ならメインの会話のモデル）
環境変数 CLAUDE_CODE_SUBAGENT_MODEL
メインの会話のモデル

インストールしたmodが agent.spawn フックでモデルを指定している場合は、1の呼び出し時のパラメータの代わりにそのモデルが使われます。呼び出し時の model と定義の model がどちらもなければ、3か4で決まります。軽い調査役を低コストのモデルで回したいなら、定義に model: haiku などを書けます。ただし呼び出し時に model が渡されれば、そちらが優先します。公式はサブエージェントの利点の1つとして、Haikuのような速く低コストのモデルへ作業を振り分けてコストを抑えることを挙げています。

実行中のサブエージェントが実際にどのモデルで動いているかは、/tasks を実行すると各行に表示されます（v2.1.242 以降）。

どう呼び出すのか（自動・明示・セッション全体）

呼び出し方は、Claudeに任せる自動委任と、自分で指定する明示的な呼び出しの2つです。明示的な呼び出しには、セッション全体をそのサブエージェントで動かす方法も含まれます。

自動委任

Claudeは、依頼の内容、各サブエージェントの description、現在の文脈をもとに自動で委任します。積極的に使わせたいなら、description に「use proactively」のような表現を入れるよう公式は勧めています。

一方で、description はコンテキストを消費します。組み込み以外のサブエージェントの description の合計が15,000トークンを超えると、起動時に警告が出ます。description は「いつ使うか」に絞って短く書き、詳しい手順はサブエージェントが動くときにだけ読み込まれるシステムプロンプト側へ移します。

明示的に呼ぶ

自動委任に任せず自分で指定する方法は3通りあります。

自然な文章で名前を挙げる: 「Use the test-runner subagent to fix failing tests」のように頼む。委任するかの最終判断はClaude。
@メンション: @ を打って候補から選ぶ。Claudeに選ばせず、そのタスクを指定したサブエージェントに任せられる。手で打つなら @agent-<name> の形。
セッション全体をそのサブエージェントで動かす: --agent フラグか agent 設定を使う。

claude --agent code-reviewer

この場合、メインのスレッド自体がそのサブエージェントのツール制限とモデルを引き継ぎます。プロジェクトで毎回そうしたいなら .claude/settings.json に "agent": "code-reviewer" を書きます。CLIフラグと設定の両方があればフラグが優先です。

作ったのに呼ばれない・読み込まれないときは何を確認するか

まず、ファイルが読み飛ばされていないか、項目名の綴り、description の書き分けを確認します。公式に書かれている原因を、確認しやすい順に並べます。

1. ファイルがスキップされていないか

プロジェクト・ユーザー・管理設定の agents ディレクトリにあるファイルは、frontmatterが次のいずれかに当てはまると、セッション内では報告されないまま読み飛ばされます。

name がない（ドキュメントとして扱われる）
先頭の --- がファイルの1行目にない
name が - で始まる、: を含む、256文字を超える
name はあるが description がない
YAMLとして解析できない

理由はデバッグログに出るので、--debug 付きで起動して確認します。YAMLの解析エラーは、セッションを始める前にディレクトリ単位で検査できます（v2.1.233 以降）。ただし、name がないだけのファイルはこの検査では指摘されません。

claude plugin validate .claude/agents

2. 新しく作ったディレクトリではないか

ファイルの変更は自動で検出されますが、監視対象はセッション開始時に存在したディレクトリだけです。その範囲で初めての agents ディレクトリを作った場合（~/.claude/agents/ を初めて作った場合など）は、Claude Codeを再起動します。

3. 項目名の綴りを間違えていないか

認識できない項目は黙って無視されます。claude --debug で起動し、~/.claude/debug/<session-id>.txt のデバッグログで does not recognize or apply を検索すると、認識されなかった項目名が最大5つ、近い正しい項目名があればそれと一緒に出ます（v2.1.296 以降）。

4. tools の指定が全部外れていないか

tools に書いた項目がすべて綴り違いなどでツールに解決できないと、Claude Codeは通常そのサブエージェントの起動を拒否し、解決できなかった項目名を含むエラーを返します。

5. description が他と区別できるか

Claudeは description を見て委任先を選ぶため、似た description が並んでいるなら、役割が区別できる書き方になっているかを見直します。公式のベストプラクティスにも、委任先を1つに絞り込める description を書くことが挙がっています。特定のサブエージェントに任せたいときは@メンションで指定します。

6. 同名のファイルがないか

同じディレクトリ配下の同名ファイルは片方しか読まれず、より優先順位の高い場所に同名があればそちらが使われます。/doctor で同じディレクトリ内の重複を確認できます。

サブエージェントを使わない方がいいのはどんな場面か

何度もやり取りして詰める作業や、すぐ終わる局所的な変更は、サブエージェントよりメインの会話のほうが向いています。公式は、サブエージェントとメインの会話の使い分けを明示しています。

メインの会話が向いているのは、何度もやり取りして詰める作業、計画から実装・テストまで多くの文脈を共有する作業、すぐ終わる局所的な変更、待ち時間を短くしたい場面です。公式によれば、フォークではないサブエージェントは新しい文脈から始まり、状況を集めるのに時間がかかることがあるためです。

サブエージェントが向いているのは、メインの文脈に要らない大量の出力が出る作業、ツールや権限の制限をかけたい作業、それだけで完結して要約を返せる作業です。

近い仕組みとの境目は次のとおりです。

仕組み	使う場面
サブエージェント	文脈を切り離して作業させ、要約だけ受け取りたい
スキル	再利用したい手順を、メインの会話の文脈のまま動かしたい（スキルの記事）
フォーク	会話全体を引き継いだまま脇の作業を任せたい。`/subtask` で起動（v2.1.212 以降）（フォークの記事）
`/btw`	すでに会話にある内容について質問したい。全文脈が見えるがツールは使えず、回答は履歴に残らない

CLAUDE.md との関係にも注意が要ります。Explore と Plan 以外のサブエージェントは CLAUDE.md の各階層を読み込みますが、メインの会話の自動メモリは読み込みません。「vendor/ は無視する」のように確実に届けたいルールは、委任するときのプロンプトに書き直すよう公式は勧めています。CLAUDE.md の書き方はCLAUDE.mdの記事で扱っています。

入れ子や同時実行に上限はあるのか

上限はあります。既定では、入れ子はメインの会話から3層下まで、同時実行は20個までです。

入れ子: サブエージェントは、メインの会話から3層下まで自分のサブエージェントを立ち上げられます。CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH で層の数を変えられ、1 にすると入れ子は無効です。
同時実行: 1つのセッションで20個のサブエージェントが動いていると、次の起動は Concurrent subagent limit reached で失敗します。CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS で変更できます（v2.1.217 以降）。セッション全体で起動できる総数には上限がありません。

この記事のバージョン番号や既定値は、2026年10月19日に照合した公式ドキュメント「Create custom subagents」（https://code.claude.com/docs/en/sub-agents）の記述です。Claude Codeは更新が速く、項目や既定値が変わることがあるため、使っているバージョンと合わないときはこのページを確認してください。

チームで使うときに決めておくこと

プロジェクトのサブエージェント（.claude/agents/）は、バージョン管理に入れてチームで使い、改善していくことを公式が勧めています。共有するなら、識別に使われる name の命名規則を揃え、書き込み系のツールを渡す役を限定しておきます。プラグイン経由で配る場合は、安全上の理由で hooks、mcpServers、permissionMode が無視される点に注意が要ります。これらに頼る定義は .claude/agents/ に置きます。

チーム全体の運用ルールの作り方は運用ルールの記事で扱っています。