Claude Codeのサブエージェントの作り方
サブエージェントの定義で必須のキーはnameとdescriptionの2つです。置き場所と書き方、modelとツールの指定が分かります。
- サブエージェントはメインの会話とは別のコンテキストで動き、大量の出力を処理して要約だけを返すので、メインの会話が汚れません。
- 組み込みは Explore、Plan（読み取り専用）、general-purpose です。Explore と Plan は CLAUDE.md を読まずに始まります。
- 定義は YAML の frontmatter 付きの Markdown で、.claude/agents/ か ~/.claude/agents/ に置きます。必須のキーは name と description だけです。
サブエージェントは、メインの会話とは別のコンテキストで動く専門の助手です。検索の結果やログのように、あとで読み返さない大量の出力を自分の中で処理し、要約だけを返します。そのため、メインの会話が汚れません。この記事では、組み込みのサブエージェント、作り方と置き場所、定義ファイルの書き方、呼ばれ方、model とツールの指定、コストの注意を順に説明します。並列で動かしたときの失敗はサブエージェント並列運用の失敗集にまとめています。編集部の検証環境（macOS、Claude Code 2.1.304、2026年10月20日）では、ダミーの todo アプリに定義ファイルを置き、書式の検査までを実行しました。サブエージェントを実際に呼ぶセッションは動かしていません。
組み込みのサブエージェント
| 名前 | 役割 | ツール |
|---|---|---|
| Explore | コードベースを速く検索して調べる | 読み取り専用。Write と Edit は使えない |
| Plan | plan mode で、計画の前に情報を集める | 読み取り専用。Write と Edit は使えない |
| general-purpose | 調べて変更もする、何段階もある作業 | サブエージェントが使えるすべてのツール |
Explore と Plan は、CLAUDE.md を読まずに始まります。
出典：https://code.claude.com/docs/en/sub-agents 、2026-10-20確認
作り方と置き場所
サブエージェントは、YAML の frontmatter が付いた Markdown のファイルです。Claude に「~/.claude/agents/ に読み取り専用のレビュアーを作って」と頼んで書かせるか、自分でファイルを書きます。今のバージョンの /agents は、設定画面を開かずに、Claude に頼むかディレクトリを直接編集するよう案内を出すだけです（v2.1.197 までは作成用の画面がありました）。
| 優先度 | 場所 | 範囲 |
|---|---|---|
| 1（最優先） | managed settings | 組織全体 |
| 2 | 起動時の --agents に渡す JSON | そのセッションだけ |
| 3 | .claude/agents/ | このプロジェクト |
| 4 | ~/.claude/agents/ | 自分のすべてのプロジェクト |
| 5 | plugin の agents/ | plugin が有効な場所 |
同じ名前のサブエージェントがあれば、優先度の高いほうが使われます。どのファイルかではなく、frontmatter の name で見分けられます。ファイルの追加や編集は数秒で反映されます。ただし、セッションを始めたときに無かった agents ディレクトリを新しく作った場合は、再起動が必要です。
出典：https://code.claude.com/docs/en/sub-agents 、2026-10-20確認
定義ファイルの形
ダミーの todo アプリの、読み取り専用のコードレビュアーです。.claude/agents/readonly-reviewer.md に置きます。
---
name: readonly-reviewer
description: Read-only code reviewer for the todo app. Use proactively after code changes, or when the user asks for a review of a diff. Do not use for writing fixes or running migrations.
tools: Read, Grep, Glob
model: sonnet
maxTurns: 20
---
You review changes in the todo app. You never edit files.
1. Read the list of changed files passed to you by the caller.
2. Read those files and their tests.
3. Report findings as a list: file:line, severity (high / medium / low), and one sentence on why.
4. If you find nothing, say "No findings" and list what you checked.本文がそのサブエージェントのシステムプロンプトになります。Claude Code 自体のシステムプロンプトは渡されません。
frontmatter の主なキーです。必須は name と description だけです。複数の単語からなるキーは maxTurns のようなキャメルケースで書きます。
| キー | 意味 |
|---|---|
name | 識別子。256字まで。: は使えない |
description | いつこのサブエージェントに任せるか |
tools | 使えるツールの一覧。省くと、使えるツールをすべて受け継ぐ |
disallowedTools | 使わせないツール |
model | sonnet、opus、haiku、完全なモデル ID、または inherit |
permissionMode | 権限モード。default、acceptEdits、auto、dontAsk、bypassPermissions、plan |
maxTurns | ターン数の上限 |
mcpServers | このサブエージェントだけが使う MCP サーバー |
isolation | worktree で、一時的な git worktree の中で動かす |
出典：https://code.claude.com/docs/en/sub-agents 、2026-10-20確認
書式を検査する
claude plugin validate .claude/agents で、セッションを始めずに検査できます。上の例は Validation passed でした。引用符を閉じ忘れたファイルを足すと、次のように出ました。
✘ Found 1 error:
❯ frontmatter: YAML frontmatter failed to parse: YAML Parse error: Unexpected character. At runtime this agent does not load at all — with no frontmatter name it is treated as a co-located reference document and skipped.YAML が壊れたサブエージェントは、まったく読み込まれません。 一方、tools を tool、model を modle と書き間違えたファイルや、name に : を含むファイルは、この検査を通りました。ただし公式によると、name が - で始まる、: を含む、256字を超えるファイルは、実行時に Claude Code が読み飛ばし、デバッグログにエラーを書きます。検査は通っても、読み込まれません。公式も、知らないキーはエラーを出さずに無視すると書いています。つづりの間違いは claude --debug のログで does not recognize or apply を探すと見つかる、とされています（未実行）。
description と呼び出し方
Claude は、依頼の内容、各サブエージェントの description、今の文脈から、任せる相手を決めます。自分から使ってほしいなら、description に「use proactively」のような言葉を入れるよう公式は勧めています。サブエージェントの description の合計が 15,000 トークンを超えると、起動時に警告が出ます。description は短くし、詳しいことは本文に書きます。
明示して呼ぶ方法は3つあります。
- 言葉で頼む：「Use the readonly-reviewer subagent to review my changes」。任せるかどうかは Claude が決める
@で指定する：@"readonly-reviewer (agent)" look at the auth changes。その作業では必ずそのサブエージェントが動く- セッション全体：
--agentフラグかagentの設定で、セッションそのものをそのサブエージェントとして動かす
出典：https://code.claude.com/docs/en/sub-agents 、2026-10-20確認
model の指定
モデルは次の順に決まります。
- Claude が呼び出しのたびに渡す
model - 定義ファイルの
model（inheritならメインの会話のモデル） - 環境変数
CLAUDE_CODE_SUBAGENT_MODEL - メインの会話のモデル
model を省くと、多くの場合メインの会話のモデルで動きます。上位のモデルで会話していれば、単純な検索も上位のモデルで走ります。どのモデルで動かすかは、定義ファイルに明示します。どのモデルで動いているかは /tasks で確かめられます（v2.1.242 以降）。
出典：https://code.claude.com/docs/en/sub-agents 、2026-10-20確認
権限とツールの受け継ぎ
- ツール：
toolsを省くと、メインの会話で使える組み込みのツールと MCP のツールを受け継ぐ。ただしAskUserQuestionなどの一部のツールは、どのサブエージェントにも渡らない - MCP：
toolsにmcp__github__*と書けば、そのサーバーのツールだけを渡せる。disallowedTools: mcp__*ですべての MCP ツールを外せる disallowedToolsにBash(git push *)と書いても、Bash ごと外れる。特定のコマンドだけを止めたいなら、設定のpermissions.denyに書く。このルールはサブエージェントにも効く- 権限モード：
permissionModeを省くと、メインの会話のモードを受け継ぐ。メインがbypassPermissions、acceptEdits、auto mode のときは、permissionModeの指定は無視される
v2.1.283 以降、対話のセッションは既定で auto mode で始まります。既定の auto mode では、サブエージェントの permissionMode は無視されます。そのため、読み取り専用は permissionMode ではなく tools で保証します。上の例で tools を Read, Grep, Glob に絞り、Bash を外しているのはこのためです。
出典：https://code.claude.com/docs/en/sub-agents 、https://code.claude.com/docs/en/permission-modes 、2026-10-20確認
コストの注意
サブエージェントは、それぞれ自分のコンテキストを持ち、自分でリクエストを送ります。そのリクエストも、メインの会話と同じ利用上限に数えられます。たくさん並べると、そのぶん使用量が増えます。並列で動かすときの手順はAIエージェントの並列実行にあります。
まとめ
- サブエージェントは、別のコンテキストで動いて要約だけを返す助手。必須のキーは
nameとdescription - 置き場所の優先順位は managed、
--agents、.claude/agents/、~/.claude/agents/、plugin の順 - 読み取り専用は
toolsで保証する。既定の auto mode ではpermissionModeは無視される modelは必ず書く。省くと多くの場合メインの会話のモデルで動く- YAML が壊れた定義は読み込まれず、キー名のつづり間違いは黙って無視される。
claude plugin validateは前者しか見つけない - サブエージェントのリクエストも、メインと同じ利用上限に数えられる