Claude Code には、特定の仕事を切り出して別のエージェントに任せるサブエージェントという仕組みがあります。コードレビュー担当、調査担当のように役割を分けておくと、親の会話を汚さずに済みます。
作り方自体は簡単で、Markdownファイルを1つ置くだけです。ただし公式ドキュメントのフロントマターには17個以上のフィールドが並んでおり、最初はどれを書けばいいのか分かりません。
この記事では、実際に何を書けばいいのかを、公式プラグインに同梱されている34個の定義ファイルを調べて絞り込みます。あわせて、初めて作るときに必ず踏む落とし穴を実測で示します。検証は Claude Code 2.1.229（Windows 11）で行いました。
1. 結論：必須は2つ、実用上は6つ
先に答えです。定義ファイルはこの形です。
---
name: style-checker
description: 記事の原稿をスタイルガイドと突き合わせ、逸脱だけを報告する。執筆後・投入前の点検に使う。
model: inherit
effort: medium
color: green
tools: Read, Glob, Grep
---
あなたは原稿を点検する校閲担当です。読み取り専用で、原稿は書き換えません。
## 手順
1. スタイルガイドを読む
2. 指定された原稿を読む
3. 逸脱している箇所だけを挙げる
## 報告
逸脱が無ければ「逸脱なし」とだけ答える。フロントマターが設定、本文がそのサブエージェントへの指示です。本文はそのままシステムプロンプトになります。
必須は name と description の2つだけで、残りは省略できます。
2. 実際に使われているフィールドは6つだけ
公式プラグインに同梱されている34個の定義ファイルを調べて、フィールドの出現数を数えました。
| フィールド | 34本中の使用 | 役割 |
|---|---|---|
name | 31 | 呼び出し名 |
description | 31 | どんなときに任せるか（自動選択に使われる） |
model | 23 | 使うモデル |
tools | 22 | 使わせるツール |
color | 19 | 表示色（機能に影響なし） |
effort | 7 | 思考の深さ |
一方、公式ドキュメントに載っている permissionMode memory maxTurns skills isolation omitClaudeMd mcpServers hooks は、34本すべてで1回も使われていませんでした。
最初は上の6つ、実質は上から4つだけ覚えれば足ります。 残りは必要になってから調べれば間に合います。
2.1 model は inherit が最多だった
model を指定していた23本の内訳です。
| 値 | 本数 |
|---|---|
inherit | 11 |
sonnet | 8 |
opus | 4 |
inherit は親の会話と同じモデルを使うという指定です。公式プラグインで最も選ばれているのがこれでした。
迷ったら inherit にしておくと、親のモデルを変えたときにサブエージェントも追随します。逆に「調査は軽いモデルで十分」のように役割で固定したい場合だけ、明示的に書きます。
3. 保存場所と優先順位
定義ファイルは置く場所で適用範囲が変わります。同じ名前があれば上が勝ちます。
| 場所 | 範囲 |
|---|---|
| 組織の管理設定 | 組織全体 |
--agents オプション | そのセッションのみ |
.claude/agents/ | そのプロジェクト |
~/.claude/agents/ | 自分の全プロジェクト |
プラグインの agents/ | プラグインを有効にした場所 |
実務では下の2つだけ使います。チームで共有したいものはプロジェクト側に置いてバージョン管理に入れ、個人用は ~/.claude/agents/ に置く、という使い分けです。
4. tools は省略すると全部使える
tools を書かなければ、サブエージェントは利用可能なツールをすべて継承します。読み取りだけさせたいのに書き込みも実行もできてしまうので、役割が限定されているなら明示的に絞るほうが安全です。
# 読み取り専用にする
tools: Read, Glob, Grep逆に「ほぼ全部でいいが、これだけは外したい」場合は disallowedTools で差し引けます。
4.1 呼べるサブエージェントを限定できる
あまり知られていない書き方として、Agent(...) で「どのサブエージェントを呼べるか」まで指定できます。
# Agentツールは使えるが、呼べる相手は explore だけ
tools: Read, Glob, Grep, Bash, Edit, Agent(claude-security:explore)括弧を付けずに Agent とだけ書けば任意のサブエージェントを呼べます。サブエージェントは別のサブエージェントを呼べるので、連鎖させたくない場合はここで止めます。
5. 落とし穴：作ったセッションでは使えない
ここが最初に必ず詰まるところです。定義ファイルを作って、そのまま呼び出してみます。
Agent type 'style-checker' not found.
Available agents: claude, claude-code-guide, Explore, general-purpose, Plan, statusline-setup認識されません。 利用できるサブエージェントの一覧はセッション開始時に読み込まれるため、途中でファイルを追加しても反映されません。
作ったら Claude Code を開き直してください。 ファイルの書式が間違っていると思って何度も直してしまいがちですが、書式は正しいのに読み込まれていないだけ、というのがこの症状です。
6. 呼び出しは description で決まる
サブエージェントを名指しせずに頼んだ場合、Claude は description を見て任せるかどうかを判断します。つまり description は説明文ではなく、選択のための条件文です。
# 曖昧で、選ばれにくい
description: コードをレビューします
# 具体的で、選ばれやすい
description: 変更したコードをプロジェクトの規約と突き合わせてレビューする。
コミット前やPR作成前に使う。対象は未ステージの差分（git diff で取得）。公式プラグインの定義を見ると、description に使うべき場面と対象の取り方まで書いてあるものが多くありました。長くなっても構いません。
ただし全サブエージェントの description の合計には約15,000トークンの上限があるため、数を増やすなら1本ずつは簡潔にする必要があります。
確実に使わせたいときは、@ を打って候補から選べば指名できます。
7. 親からは何が見えるのか
サブエージェントは独立したコンテキストで動きます。
渡らないもの
- 親のこれまでの会話
- 親が既に読んだファイルの内容
- 親が使ったスキル
渡るもの
- こちらが書いた依頼文
CLAUDE.md（omitClaudeMd: trueで止められる）- 定義ファイルの本文（システムプロンプトとして）
そして親に返るのは最終報告だけで、途中のやり取りは戻りません。だから定義ファイルの本文に「報告」の節を書いておくことが効きます。何をどの形で返すかを指定しておかないと、要約の粒度が毎回変わります。
会話が渡らないという性質は、依頼文に必要な前提を全部書く必要があるということでもあります。「さっきの件で」は通じません。
8. 作成用のウィザードは無くなった
以前は /agents コマンドで対話的に作成・編集・削除ができました。バージョン 2.1.198 でこのウィザードは廃止され、現在は実行すると「Claudeに頼むかファイルを直接編集してください」という案内が出るだけです。
現在の作り方は2つです。
- Claudeに頼む … 「
~/.claude/agents/に、原稿を点検するサブエージェントを作って」と依頼する - ファイルを直接置く … 本記事の形式で
.mdを作る
保存場所とフロントマターの仕様は変わっていません。変わったのは作成用のUIだけです。
9. まとめ
Claude Code のサブエージェントについて整理します。
- Markdownファイル1つ。 必須は
nameとdescriptionの2つだけ - 覚えるのは6フィールドで足りる。 公式プラグイン34本が使っていたのは
namedescriptionmodeltoolscoloreffortだけだった model: inheritが最多。 迷ったら親に追随させるtoolsは省略すると全部継承する。 役割が限定されているなら明示的に絞るAgent(...)で呼べる相手まで限定できる- 作ったセッションでは認識されない。 開き直す必要がある
descriptionが自動選択を決める。 説明ではなく条件文として書く- 親の会話は渡らず、返るのは最終報告だけ。 本文に「報告」の節を用意する
最初の1本は、読み取り専用で、失敗しても害のない役割から始めるのが安全です。tools: Read, Glob, Grep にしておけば、意図しない書き換えは起きません。
本記事の内容は Claude Code 2.1.229 と公式ドキュメント、および公式プラグイン34定義の実測に基づいています。この機能は更新が速いため、フィールドの増減は公式ドキュメントで確認してください。
コメント