Claude Code でサブエージェントを自作する手順をまとめます。組み込みの Explore や general-purpose で間に合うなら、わざわざ定義する必要はありません。同じ指示でワーカーを繰り返し起動しているなら、Markdown ファイルに固定する価値が出てきます。
自作の前に組み込みとの境界を引く
Claude Code v2.1系には Explore・Plan・general-purpose という組み込みサブエージェントがあります。コードベースの検索は Explore、計画づくりは Plan、探索と変更を両方やるなら general-purpose。ここで片づくタスクに自作は要りません。
自作が要るのは、特定ドメインのシステムプロンプトを固定したいとき、ツールを絞って事故を防ぎたいとき、複数プロジェクトで同じ設定を使い回したいときです。公式ドキュメントも自作の動機を Specialize behavior・Enforce constraints・Reuse configurations と並べています。
置き場所でスコープが決まる
サブエージェントは Markdown ファイル1枚です。どのディレクトリに置くかでスコープと優先順位が変わる。同名なら上位の置き場所が勝ちます。
| 置き場所 | スコープ | 優先順位 |
|---|---|---|
.claude/agents/ | そのプロジェクト | 高 |
~/.claude/agents/ | 全プロジェクト | 中 |
プラグインの agents/ | 有効化した場所 | 低 |
組織配布の managed settings と、起動時に渡す --agents CLI フラグはこれより上の優先順位を持ちます。チームで共有するならプロジェクト側に置いてバージョン管理に入れる、が基本形です。
組み込みと自作で読み込むものが違う
Explore と Plan は CLAUDE.md と git status を読み込みません。検索を速く安く保つためです。自作サブエージェントと general-purpose は両方とも読み込みます。プロジェクトのルールを効かせたいタスクは、組み込みではなく自作側に寄せる判断になります。
/agents コマンドで対話的に作る
推奨は /agents コマンド。タブ式の管理画面が開きます。
/agentsLibrary タブで Create new agent を選び、保存先を決めます。Personal なら ~/.claude/agents/ に入って全プロジェクトで使える。Project ならそのリポジトリ限定です。
Generate with Claude で雛形を作る
Generate with Claude を選ぶと、作りたいエージェントを文章で説明するだけで識別子・description・システムプロンプトを生成してくれます。説明はこのくらいの具体度で渡します。
A code improvement agent 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.実行結果として識別子 code-improver と description、システムプロンプトが埋まります。続けてツール選択(read-only に絞るか全継承か)とモデルを指定し、保存すればその場で使えます。
即時反映とディスク直編集の差
/agents 経由で作ったものは即座に反映されます。一方、エディタで .claude/agents/ のファイルを直接足したときはセッションの再起動が要る。サブエージェントはセッション開始時に読み込まれるためです。手で書いたのに認識されないときは、再起動を忘れていないか確認します。
Markdown を直接書く
中身を把握するには手書きが早い。frontmatter とシステムプロンプト本文の2部構成です。
---
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 on quality, security, and best practices.このファイルを .claude/agents/code-reviewer.md に置いて再起動すると、@agent-code-reviewer で呼び出せます。
> @agent-code-reviewer 直近の変更をレビューして
● code-reviewer(直近の変更をレビュー)
⎿ Critical: 認証トークンが平文でログ出力されています
Warning: handler の戻り値エラーが握りつぶされています必須は name と description だけ
公式の “Supported frontmatter fields” の表で Required が Yes なのは name と description の2つだけ。残りは全部オプションです。name は小文字とハイフン、description には「いつ委譲するか」を書く。Claude はこの description を見て委譲するかどうかを決めます。description が曖昧だと、自作しても呼ばれません。
body がそのままシステムプロンプト
frontmatter の下に書いた本文が、そのままサブエージェントのシステムプロンプトになります。Claude Code 本体の長いシステムプロンプトは渡りません。渡るのは本文と、作業ディレクトリなどの環境情報だけ。役割と手順は本文に具体的に書きます。ここが薄いとサブエージェントの精度が落ちる。
tools と disallowedTools で能力を絞る
tools の扱いを外すと事故が起きます。tools を書かないと、サブエージェントはメイン会話の全ツールを継承する。内部ツールだけでなく、接続済みの MCP サーバーのツールも全部です。
read-only のつもりで作ったレビュー用エージェントが、frontmatter に tools を書き忘れたせいで Slack 連携の MCP ツールまで握っていた、と後から /agents の画面で気づいたことがあります。description が「レビュー専用」でも、能力は description では絞られません。
tools は許可リスト
---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---これで Read・Grep・Glob・Bash の4つだけ。ファイル編集も書き込みも、MCP ツールも使えません。
> safe-researcher に README を書き換えさせる
● safe-researcher は Edit を持たないため、変更は実行されず調査結果だけが返るdisallowedTools は引き算
全部を許可リストに並べるのは面倒です。「Write と Edit だけ外したい」なら disallowedTools で引く方が短い。
---
name: no-writes
description: Inherits every tool except file writes
disallowedTools: Write, Edit
---Bash も MCP ツールもそのまま、Write と Edit だけ落ちます。両方を指定したときは disallowedTools が先に適用され、その残りに対して tools が解決される。両方に書いたツールは消えます。
MCP はサーバー単位で外せる
mcp__<server> や mcp__<server>__* でサーバーごと許可・拒否できます。disallowedTools なら mcp__* で全 MCP ツールを一括除去。github の MCP だけ外すならこう書きます。
disallowedTools: mcp__githubついでに、AskUserQuestion や ExitPlanMode はメイン会話の UI 前提のツールなので、tools に並べてもサブエージェントには渡りません。
model を省くと inherit になる
model を書かないと固定モデルではなく inherit、つまりメイン会話と同じモデルになります。安く回したいなら明示的に haiku を指定する。重い解析なら sonnet や opus を当てます。
エイリアスとフル ID
指定できるのは sonnet・opus・haiku・fable のエイリアス、claude-opus-4-8 のようなフル ID、それと inherit。--model フラグと同じ値を受け取ります。
解決順序
呼び出しごとにモデルが上書きされることもあります。優先順位は上が強い。
- 環境変数
CLAUDE_CODE_SUBAGENT_MODEL - 呼び出し時に渡す
modelパラメータ - frontmatter の
model - メイン会話のモデル
呼び出し方で確実さが変わる
作ったサブエージェントを、Claude に「使うかどうか」任せるのか、確実に指名するのかで書き方が分かれます。
自然文では委譲は保証されない
「code-reviewer サブエージェントで直近の変更を見て」と書くと、Claude が委譲するかどうかを判断します。名前を出しても必ず使われるとは限りません。
確実に特定のエージェントを走らせたいなら、自然文ではなく @ メンション。タイプアヘッドから選ぶか、@agent-code-reviewer と直接打ちます。
@agent-code-reviewer 認証まわりの変更を見てこれで code-reviewer が確実に起動します。送る指示文は Claude が組み立てますが、どのエージェントを使うかは @ メンションで固定されます。
セッション全体を1つのエージェントにする
セッションの最初から特定のエージェントで通すなら --agent フラグ。
claude --agent code-reviewerメインスレッド自体が、そのシステムプロンプト・ツール制限・モデルを引き継ぎます。.claude/settings.json に "agent": "code-reviewer" と書けば、プロジェクトの既定にもできます。
サブエージェントにしない方がいい場面
サブエージェントを増やすほど、毎回の文脈集め直しで遅くなります。公式の “Choose between subagents and main conversation” は、メイン会話を使うべき場面を先に挙げています。
往復の多い作業はメインで
計画 → 実装 → テストのように段階間で文脈を共有する作業、こまめな修正が要る作業はメイン会話向きです。サブエージェントは毎回まっさらな文脈から始まるので、背景を集め直すぶん時間がかかる。手早い一点修正もメインの方が速い。
Skill との使い分け
再利用したいのが「プロンプトや手順」で、隔離した文脈は要らないなら、サブエージェントより Skill が合います。Skill はメイン会話の文脈で動く。会話の中の小さな確認だけなら /btw で済みます。組み込みエージェントの役割分担は Explore/Plan/general-purpose の比較に、独立したセッションを並走させる話は Agent Teams にまとめてあります。
まとめ
- 作成は
/agentsコマンドか.claude/agents/の Markdown 直書き。前者は即時反映、後者はセッション再起動が要る - 必須 frontmatter は
nameとdescriptionだけ。本文がそのままシステムプロンプトになる toolsを省くと MCP 込みの全ツールを継承する。絞るならtools(許可)かdisallowedTools(拒否)modelを省くとinheritでメイン会話と同じ。安く回すならhaikuを明示する- 確実に指名するなら
@agent-名前、セッション全体なら--agent - 往復の多い作業や文脈共有が要る作業は、メイン会話か Skill を選ぶ
v2.1.172 以降はサブエージェントがさらにサブエージェントを起動できます。レビュー用エージェントが指摘ごとに検証用を分けて投げる、といった入れ子も組めるようになりました。