原典: Create custom subagents / 日本語版

一行要約

subagent は「独自の context window・system prompt・ツール権限を持ち、要約だけを返すワーカー」であり、実務で効くのは frontmatter の細部(tools / permissionMode / skills / memory / isolation)と、フォアグラウンドとバックグラウンドでツールセットが変わるという挙動。

要点

何のために使うか

Use one when a side task would flood your main conversation with search results, logs, or file contents you won’t reference again: the subagent does that work in its own context and returns only the summary.

二度と参照しない検索結果・ログ・ファイルの中身で本流の会話が溢れそうなとき、subagent を使え。subagent はその作業を自分の context で行い、要約だけを返す。

  • context を守る — 探索と実装をメインの会話から外す
  • 制約を強制する — 使えるツールを限定する
  • 設定を再利用する — user レベルの subagent をプロジェクト横断で使う
  • 振る舞いを特化させる
  • コストを制御する — Haiku のような速く安いモデルに回す

context は守れても、使用量は別。 subagent は自分でもリクエストを送り、それはメインの会話と同じ使用上限に数えられる。詳細な結果を返す subagent を多く走らせると、context を食ううえに、それぞれが走っている間にトークンを使う。

組み込み subagent

すべて親の会話の権限を継承する。多くは制限されたツールセットで走る。

agentモデルツール用途
Exploreメイン会話のモデル。ただしメインが Fable のとき、Claude の購読・Console アカウント・ANTHROPIC_BASE_URL の LLM gateway では opus エイリアスが指す Opus、Bedrock / Agent Platform / Foundry / Claude Platform on AWS / Claude apps gateway ではメインのモデルのまま読み取り専用。Write / Edit は拒否ファイル発見、コード検索、コードベース探索
Planメイン会話から継承読み取り専用plan mode 中の調査
General-purposeメイン会話から継承subagent が使える全ツール探索と変更の両方が要る複雑な作業
claude継承全ツールより特化した agent に当てはまらないタスクの受け皿
statusline-setupSonnet—/statusline の設定時
claude-code-guideHaiku—Claude Code の機能について尋ねたとき

Explore と Plan だけが CLAUDE.md と親セッションの git status を読まない。 調査を速く・安く保つため。他のすべての組み込み・カスタム subagent は両方を読む。

Explore を呼ぶとき Claude は徹底度を指定する — quick(狙い撃ち)/ medium(バランス)/ very thorough(網羅的)。

Explore という名前の user / project subagent を定義すると組み込みを上書きできる。model: haiku を指定して探索を安く保つのが定石。

制限のかけ方:

  • 特定の組み込み型をブロック → permissions.deny
  • 一切委譲させない → Agent ツール自体を deny
  • Explore と Plan だけ外す → CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1
  • 非対話モード / Agent SDK で組み込みを全部外す → CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1

スコープと優先順位

場所スコープ優先度
Managed settings組織全体1(最高)
--agents CLI フラグ現セッション2
.claude/agents/現プロジェクト3
~/.claude/agents/自分の全プロジェクト4
plugin の agents/plugin が有効な場所5(最低)
  • project subagent は作業ディレクトリからリポジトリルートまで遡って走査される。同名なら作業ディレクトリに最も近いものが勝つ
  • .claude/agents/ と ~/.claude/agents/ は再帰的に走査される。サブフォルダで整理してよい。同一性は name frontmatter だけから決まるので、サブディレクトリのパスは識別に影響しない
  • したがってツリー全体で name は一意に保つ。同一ディレクトリ内で重複するとファイルシステムの読み取り順という文書化されていない順序で片方だけがロードされる。/doctor が重複を報告する
  • plugin だけは例外で、サブフォルダがスコープ識別子の一部になる(agents/review/security.md → my-plugin:review:security)
  • plugin subagent は hooks / mcpServers / permissionMode をサポートしない(セキュリティ上の理由で無視される)。plugin の作者なら、hook は plugin の hooks/hooks.json、MCP サーバは .mcp.json で配る(subagent の中だけでなく、plugin が有効な間ずっと効く)

frontmatter フィールド

必須は name と description のみ。

フィールド説明
name小文字とハイフン。hook はこれを agent_type として受け取る。ファイル名と一致していなくてよい。: は plugin スコープ用に予約されており使えない
descriptionいつこの subagent に委譲すべきか
tools使えるツール。省略すると subagent が使える全ツールを継承。Skill を preload したいなら Skill を並べるのではなく skills フィールドを使う
disallowedTools拒否するツール
modelsonnet / opus / haiku / fable / 完全なモデル ID / inherit。既定は inherit
permissionModedefault / acceptEdits / auto / dontAsk / bypassPermissions / plan / manual(default の別名)
maxTurns停止するまでの最大 agentic ターン数
skills起動時に context へ注入する skill。description ではなく全文が入る
mcpServersこの subagent が使える MCP server
hooksこの subagent に紐づく lifecycle hook
memoryuser / project / local。セッションを跨いだ学習を可能にする
backgroundtrue で常にバックグラウンド実行。未設定なら Claude が選ぶ(既定はバックグラウンド)
effortlow / medium / high / xhigh / max
isolationworktree で一時的な git worktree で走らせる。既定ブランチから分岐する(親セッションの HEAD ではない)。変更がなければ自動で片付けられる
colorタスク一覧・transcript での表示色
initialPrompt--agent か agent 設定でメインセッションのエージェントとして走るとき、最初の user ターンとして自動送信される。コマンドと skill は展開される。ユーザーのプロンプトの前に置かれる。plugin subagent では無視される
omitClaudeMdtrue で user / project / local の CLAUDE.md を読まずに起動する(managed policy のファイルは読む。managed subagent は除く)。委譲プロンプトだけで完結する subagent 向け。--agent か agent 設定でメインセッションのエージェントとして走るときは無視される(v2.1.271 以降)
experimental実験的オプションのマップ。cacheTtl を 5m か 1h にすると、この subagent のリクエストの prompt cache 寿命を選べる。experimental の中に書く(frontmatter の最上位ではない)。他の値は無視され、サブスクリプションが usage credits を使っている間は 1h も無視される。subagent ファイルからしか読まれない(v2.1.248 以降)

--agents フラグの JSON が受け付けるのは prompt(= markdown 本文にあたる system prompt)と、上の表の description / tools / disallowedTools / model / permissionMode / mcpServers / hooks / maxTurns / skills / initialPrompt / memory / effort / background / omitClaudeMd / isolation。color と experimental は受け付けず、拒否ではなく黙って無視される。 最上位のキーがエージェント名になる(- で始めない)。非対話モード(-p)では、同じオブジェクトを入れた JSON ファイルのパスも渡せる(claude -p --agents ./agents.json "..."。コマンドラインに収まらない大きな定義向け。対話セッションではパスは拒否される。v2.1.281 以降)。prompt は空でもよい —— memory も無いエージェントを --agent でセッションのエージェントに選ぶと、セッションの system prompt はそのまま残る(v2.1.281 以降)。

tools と disallowedTools の解決順: disallowedTools が先に適用され、残ったプールに対して tools が解決される。両方に載っているツールは除去される。

tools の全エントリがどのツールにも解決しないと、subagent は起動を拒否され、未解決のエントリ名を挙げたエラーが返る。

MCP はサーバ単位のパターンも受け付ける — mcp__<server> / mcp__<server>__*。disallowedTools では mcp__* で全 MCP ツールを外せる。

モデルの解決順(4段階)

  1. 呼び出しごとの model パラメータ
  2. subagent 定義の model frontmatter(inherit はメイン会話のモデル)
  3. CLAUDE_CODE_SUBAGENT_MODEL 環境変数
  4. メイン会話のモデル

v2.1.251 でこの順序が変わった。 それ以前は CLAUDE_CODE_SUBAGENT_MODEL が先頭で、呼び出しパラメータも frontmatter も(model: inherit さえ)上書きしていた。いまは既定値でしかない。

  • 全 subagent を1つのモデルに固定したいなら CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 を併せて設定する(teammate と workflow のエージェントにも効く。v2.1.257 以降)。CLAUDE_CODE_SUBAGENT_MODEL を設定せずに FORCE だけ設定すると、メイン会話のモデルに固定される
    • FORCE が効いている間は、上の1と2が無視される —— subagent 定義の model フィールドは無視され、Claude は起動時にモデルを渡せない
    • メイン会話のモデルで走り続けるものが2つある: fork と、model: inherit の「subagent で走る skill」
    • FORCE だけを設定した場合、組み込みの Explore は組み込み subagent の表にあるモデルで走る(上の表。メインが Fable なら Opus になりうる)
  • CLAUDE_CODE_SUBAGENT_MODEL を設定しただけでは、組み込みの Explore と Plan のモデルは変わらない
  • 変数に inherit を設定するのは、設定しないのと同じ(v2.1.196 より前は違った)
  • 呼び出しごとの model か frontmatter に書いたエイリアス(opus など)は、2つの場合だけメイン会話のモデルに解決される
    • メイン会話のモデルがその系統に属するとき —— [1m] 接尾辞ごとメイン会話とまったく同じモデルになる(拡張 context も同じになる)
    • Anthropic API 以外のプロバイダで、メイン会話のモデル系統を判別できないとき(Bedrock の application inference profile ARN を解決できていない場合など)。これは opus エイリアスだけの話で、ANTHROPIC_DEFAULT_OPUS_MODEL を設定している場合は当てはまらない(opus は設定したモデルに解決される)
    • CLAUDE_CODE_SUBAGENT_MODEL のエイリアスは、どちらの場合でも常にそのエイリアスが指すバージョンに解決される
  • 組織の availableModels に弾かれた値は差し替えられる。系統エイリアスなら許可された最新版、それ以外は継承したモデル。対話セッションでは、要求されたモデルと実際のモデルを挙げた警告が出る
  • どのモデルで走っているかは /tasks で見る(v2.1.242 以降。effort を設定していればそれも出る)
  • 呼び出しごとの model は再開やフォローアップにも効き続ける(v2.1.211 より前は再開で失われた)

v2.1.198 以降、subagent はメイン会話の extended thinking 設定も継承する。subagent ごとの thinking 設定は存在しない(それ以前は、メイン会話の設定によらず extended thinking は無効だった)。

ツールセットは2段のフィルタで決まる(重要)

フィルタ1 — 全 subagent から常に除去される(tools に書いても消える):

Agent(深さ上限のとき)、AskUserQuestion、EndConversation、EnterPlanMode、ExitPlanMode(permissionMode: plan を除く)、ScheduleWakeup、TaskOutput、WaitForMcpServers、Workflow

フィルタ2 — バックグラウンド実行の subagent(=既定)にのみ適用。MCP ツールは全部残るが、組み込みツールは次だけになる:

Read, Grep, Glob, Bash, PowerShell, Edit, Write, NotebookEdit, WebFetch, WebSearch, TodoWrite, Skill, ToolSearch, EnterWorktree, ExitWorktree, Monitor, TaskStop, SendMessage, Artifact

ListAgents もこのフィルタに従う。 cross-session messaging が有効なセッションでは foreground の subagent はこれを継承するが、background の subagent は保持しない。

the same definition can resolve to different tools in the foreground and the background

同じ定義であっても、フォアグラウンドとバックグラウンドとで別のツールに解決されることがある

同じ定義でもフォアグラウンドとバックグラウンドでツールが変わる。しかも除去はエラーを出さない(tools が空に解決した場合を除く)。

fork は両方のフィルタをスキップし、メイン会話とまったく同じツールプールを受け取る。

permission mode

モード挙動
default通常の確認
acceptEdits作業ディレクトリ / additionalDirectories 内のファイル編集と一般的なファイルシステム操作を自動承認
autoバックグラウンドの分類器がコマンドと保護ディレクトリへの書き込みを審査
dontAsk確認を自動拒否。明示的に許可されたツールは動く
bypassPermissions確認をスキップ
plan読み取り専用の探索

親が bypassPermissions か acceptEdits なら、それが優先され上書きできない。 親が auto mode なら subagent も auto mode を継承し、frontmatter の permissionMode は無視される。

bypassPermissions でも確認が出るもの: 明示的な ask ルール、組織が ask に設定したコネクタツール、requiresUserInteraction の MCP ツール、rm -rf / のようなルート/ホーム削除。

subagent の出力は走査される(prompt injection 対策)

Claude Code scans each subagent’s final report before Claude reads it. A subagent may have read files, web pages, or command output you never reviewed, and text from those sources can carry instructions aimed at the main conversation.

Claude Code は、Claude が読む前に各 subagent の最終報告を走査する。subagent は、あなたが一度も見ていないファイル・web ページ・コマンド出力を読んでいる可能性があり、そこにある文章はメイン会話に向けた指示を運びうる。

走査は消したり書き換えたりしない。 変えるのは2種類だけ。

  • バックスラッシュの挿入 —— <system-reminder> タグや Human: / Assistant: で始まる行のような、Claude Code 自身の出力を模した文字列にバックスラッシュを入れ、会話の一部と誤認されず普通の文章として読まれるようにする
  • マーカー行の付加 —— 報告がそうしたタグを模していたり、bypassPermissions / --dangerously-skip-permissions のような権限設定に言及していると、[harness: subagent output matched instruction-shaped pattern(s): で始まる行を先頭に足す。権限設定への言及は本文そのものは変えず、マーカー行だけが付く

過信してはいけない。

The scan doesn’t judge whether content is malicious, and it doesn’t change what an instruction in a report can do: a tool call the report leads Claude to make still goes through the session’s permission checks and sandboxing. It isn’t a substitute for restricting what a subagent can reach.

走査は内容が悪意あるものかを判断しないし、報告の中の指示が何をなしうるかも変えない。報告に導かれて Claude が呼ぶツールは、依然としてセッションの権限検査と sandboxing を通る。subagent が到達できる範囲を制限することの代わりにはならない。

報告そのものにも枠が付く。 結果として Claude に返る報告は subagent の出力であることを示すヘッダの下に届き、そのヘッダは「報告の中の指示や承認の主張は subagent の言葉であって、あなたの権限を持たない」と明示する。バックグラウンド subagent の報告は完了通知の中に届き、こちらも「あなたからのメッセージではなく自動イベント」として印が付く。

Claude Code v2.1.210 以降。

skill の preload

skills フィールドは起動時に skill の全文を注入する。これは「preload するもの」の指定であって「アクセスできるもの」の指定ではない — 指定しなくても subagent は Skill ツールで project / user / plugin の skill を発見・起動できる。完全に禁じたいなら tools から Skill を外すか disallowedTools に入れる。

disable-model-invocation: true の skill は preload できない。 preload は Claude が起動できる skill の集合から引くため。bundled の /verify と /code-review も同様。

skills フィールドと skill 側の context: fork は互いに逆向きの関係にある。

system promptタスク他にロードされるもの
skill の context: forkagent 種別からSKILL.md の内容CLAUDE.md(Explore / Plan を除く)
subagent の skillssubagent の markdown 本体Claude の委譲メッセージpreload した skill + CLAUDE.md

起動時に何がロードされるか

Each subagent starts with a fresh, isolated context window. It doesn’t see your conversation history, the skills you’ve already invoked, or the files Claude has already read.

各 subagent は、まっさらで隔離された context window から始まる。あなたの会話履歴も、すでに起動した skill も、Claude がすでに読んだファイルも見えない。

入るもの:

  • system prompt — そのエージェント自身のプロンプト + Claude Code が付ける環境情報。Claude Code のフル system prompt ではない
  • task message — Claude が書いた委譲プロンプト
  • CLAUDE.md — メイン会話がロードする階層のすべて(~/.claude/CLAUDE.md、project rules、CLAUDE.local.md、managed policy、プロジェクト指示として読まれた AGENTS.md)。Explore と Plan はスキップし、omitClaudeMd: true の subagent は managed policy だけを読む(定義が managed settings 由来ならそれも読まない)
  • git status — 親セッション開始時点のスナップショット。Explore と Plan はスキップ
  • preload した skill の全文
  • sibling roster — main と、セッション内の名前付きエージェントの一覧(SendMessage の to に使える)。出るのはその subagent のツールに SendMessage が入っていて、他に名前付きのエージェントが1つ以上あるときだけ。起動時のスナップショットなので、後から名前を付けられたエージェントは出ない

入らないもの:

  • output style — subagent は自分の system prompt で走るので影響しない(fork を除く)
  • auto memory — メイン会話のものはロードされない。独自に持たせたいなら memory フィールド
  • context window のサイズ — 親ではなく自分のモデルで決まる。小さい window のモデルに委譲すると小さい window になる

The main conversation still has your full CLAUDE.md when it reads these subagents’ results, so most rules don’t need to reach the subagent itself. If a rule must, such as “ignore the vendor/ directory,” restate it in the prompt you give Claude when delegating.

本流の会話は、これらの subagent の結果を読むときも CLAUDE.md を丸ごと持っているので、ほとんどのルールは subagent 自身まで届く必要がない。「vendor/ ディレクトリは無視せよ」のように届く必要があるルールは、委譲するときに Claude へ渡すプロンプトの中で言い直せ。

foreground と background

  • foreground — 完了までメイン会話をブロックする。権限確認はそのまま渡ってくる
  • background — 並行して走る。権限確認はメインセッションに、どの subagent が求めているかを名指しで表示される。承認すれば続行、Esc でその1回のツール呼び出しだけ拒否(subagent は止まらない)

v2.1.198 以降、既定はバックグラウンド。 ただし fork mode が入っているかで挙動が変わる(v2.1.232 以降、対話セッションでは fork mode が既定オン)。

Where fork mode is on, as it is by default in an interactive session, Claude Code runs the subagent in the background, forks and non-fork subagents alike, and Claude can’t ask for the foreground.

fork mode がオンのとき —— 対話セッションでは既定でそうである —— Claude Code は subagent をバックグラウンドで走らせる。fork も非 fork も同様であり、Claude はフォアグラウンド実行を求められない。

Where fork mode is off, Claude runs the subagent in the background by default and in the foreground when it needs the result before continuing.

fork mode がオフのときは、Claude は既定でバックグラウンドで走らせ、続行前に結果が必要なときはフォアグラウンドで走らせる。

つまり「Claude が結果を先に必要とするときだけフォアグラウンド」は fork mode がオフのときの話になった。対話セッションの既定(fork mode オン)ではフォアグラウンド実行そのものが選ばれない。

A background subagent’s results reach Claude as a completion notification in a later turn. Claude waits for that notification before reporting the subagent’s results, and if you ask about progress first, it reports that the subagent is still running.

バックグラウンドの subagent の結果は、後のターンで完了通知として Claude に届く。Claude はその通知を待ってから subagent の結果を報告するため、先に進捗を尋ねると、subagent はまだ実行中だと報告する。

Ctrl+B で実行中のタスクをバックグラウンドに送れる。

fork mode(v2.1.232 以降、対話セッションの既定)

Claude Code turns fork mode on by default in interactive sessions and leaves it off by default in non-interactive mode with -p and in the Agent SDK. The interactive default requires Claude Code v2.1.232 or later.

Claude Code は対話セッションでは fork mode を既定でオンにし、-p の非対話モードと Agent SDK では既定でオフのままにする。対話セッションでのこの既定には Claude Code v2.1.232 以降が要る。

場面fork mode
対話セッション既定オン(v2.1.232 以降)
-p の非対話モード既定オフ
Agent SDK既定オフ

CLAUDE_CODE_FORK_SUBAGENT を 1 にすると明示的にオンにできる(v2.1.232 より前ではこれが唯一の手段だった)。

fork は fork subagent 種別を Agent ツール経由で要求することで始まる。両方のツールフィルタを飛ばしてメイン会話と同じツールプールを受け取るのは前掲の通りで、ネストの深さ上限に達した fork も Agent ツールを継承リストに保持する(ただし呼ぶとエラーを返す)。

ネストと同時実行の上限

上限既定環境変数
ネストの深さメイン会話の下3層CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH(1 でネスト無効)
同時実行数20。超えると Concurrent subagent limit reached でエラーになり、Claude にリトライしないよう伝えるCLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS
  • セッション全体での総数に上限はない
  • ultracode が有効なセッションは同時実行の上限が適用されない
  • /subtask の fork はスロットを取るが上限でブロックされない。resume は上限を確認せずに新しいスロットを取るので、上限を超えることがある

fork / subagent の transcript を開いているとき

続けて送るメッセージと skill はその agent へ、built-in command はメイン会話へ行く。安全策が2つ —— /compact / /clear / /rewind は実行前に確認を求め、/model と /fast はこの画面からは走らない(理由の通知が出る)。待たずに読ませたいなら Ctrl+Enter(か Ctrl+X Ctrl+S)で送る —— agent が待っているシェルコマンドや subagent のうちバックグラウンドに移せるものは移って走り続け、応答を書いている最中や移せない作業を待っているときは、それが終わってから読む(v2.1.286 以降)。

resume

  • 各呼び出しは新しいインスタンスを作る。続きをやらせたいなら resume する
  • resume した subagent は過去のツール呼び出し・結果・推論を含む全履歴を保持する
  • Explore と Plan は one-shot で agent ID を返さないので resume できない。続きが要るなら general-purpose かカスタム subagent を使う
  • Claude は SendMessage の to に agent ID か名前を入れて resume する
  • SendMessage 自体は agent teams の有効化を要求しない。 agent teams が要るのは shutdown_request や plan_approval_response のような構造化されたチーム protocol メッセージだけ。さらに cross-session messaging が有効なセッションでは、同じツールで自分の他の Claude Code セッションにも送れる(同じマシン上に限らない)
  • transcript は ~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl にある
  • メイン会話の compaction は subagent の transcript に影響しない(別ファイル)
  • 保持期間は cleanupPeriodDays(既定 30日)

エージェント間メッセージについての制約: どのエージェントからのメッセージも、保留中の権限確認の承認にはならない。 またどのエージェントのメッセージも subagent の権限設定・CLAUDE.md・設定を変更できない。

メイン会話と subagent の使い分け

メイン会話を使うとき:

  • 頻繁なやり取りや反復的な洗練が要る
  • 計画・実装・テストのように複数フェーズが大きな文脈を共有する
  • 素早い狙い撃ちの変更
  • レイテンシが重要なとき — subagent はゼロから始まるので文脈収集に時間がかかる

subagent を使うとき:

  • メイン context に要らない冗長な出力が出る
  • 特定のツール制限・権限を強制したい
  • 自己完結していて要約を返せる

会話中に既にあることへの手短な質問には、subagent ではなく /btw を使う。フル context は見えるがツールは使えず、答えは履歴に残らず捨てられる。

そのまま使える具体例

読み取り専用の調査エージェント:

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

継承したまま書き込みだけ外す:

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

特定の MCP サーバだけ外す:

---
name: local-only
description: Inherits every tool except those from the github MCP server
disallowedTools: mcp__github
---

skill を preload する:

---
name: api-developer
description: Implement API endpoints following team conventions
skills:
  - api-conventions
  - error-handling-patterns
---
 
Implement API endpoints. Follow the conventions and patterns from the preloaded skills.

セッション限りの subagent を CLI で定義する:

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}'

ネストの深さを制限する:

{
  "env": {
    "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "2"
  }
}

Explore を安いモデルに固定する(組み込みを上書き):

---
name: Explore
description: Fast, read-only agent for searching and analyzing codebases
model: haiku
tools: Read, Grep, Glob
---

subagent を resume する:

Use the code-reviewer subagent to review the authentication module
[Agent completes]
 
Continue that code review and now analyze the authorization logic
[Claude resumes the subagent with full context from previous conversation]

compaction のログ形式(transcript ファイル内):

{
  "type": "system",
  "subtype": "compact_boundary",
  "compactMetadata": {
    "trigger": "auto",
    "preTokens": 167189
  }
}

原典で言及されている関連文書