Create custom subagents

一行要約

subagent は「独自の context window・system prompt・ツール権限を持ち、要約だけを返すワーカー」であり、実務で効くのは frontmatter の細部（tools / permissionMode / skills / memory / isolation）と、foreground と background でツールセットが変わるという挙動。

要点

何のために使うか

Use one when a side task would flood your main conversation with search results, logs, or file contents you won’t reference again. 二度と参照しない検索結果・ログ・ファイルの中身で本流の会話が溢れそうなとき、subagent を使え。

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

組み込み subagent

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

agent	モデル	ツール	用途
Explore	メイン会話から継承（Claude API では Opus が上限）	読み取り専用。Write / Edit は拒否	ファイル発見、コード検索、コードベース探索
Plan	メイン会話から継承	読み取り専用	plan mode 中の調査
General-purpose	メイン会話から継承	subagent が使える全ツール	探索と変更の両方が要る複雑な作業
claude	継承	全ツール	より特化した agent に当てはまらないタスクの受け皿
statusline-setup	Sonnet	—	`/statusline` の設定時
claude-code-guide	Haiku	—	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 をサポートしない（セキュリティ上の理由で無視される）

frontmatter フィールド

必須は name と description のみ。

フィールド	説明
`name`	小文字とハイフン。hook はこれを `agent_type` として受け取る。ファイル名と一致していなくてよい。`:` は plugin スコープ用に予約されており使えない
`description`	いつこの subagent に委譲すべきか
`tools`	使えるツール。省略すると subagent が使える全ツールを継承。Skill を preload したいなら `Skill` を並べるのではなく `skills` フィールドを使う
`disallowedTools`	拒否するツール
`model`	`sonnet` / `opus` / `haiku` / `fable` / 完全なモデル ID / `inherit`。既定は `inherit`
`permissionMode`	`default` / `acceptEdits` / `auto` / `dontAsk` / `bypassPermissions` / `plan` / `manual`（`default` の別名）
`maxTurns`	停止するまでの最大 agentic ターン数
`skills`	起動時に context へ注入する skill。description ではなく全文が入る
`mcpServers`	この subagent が使える MCP server
`hooks`	この subagent に紐づく lifecycle hook
`memory`	`user` / `project` / `local`。セッションを跨いだ学習を可能にする
`background`	`true` で常にバックグラウンド実行。未設定なら Claude が選ぶ（既定はバックグラウンド）
`effort`	`low` / `medium` / `high` / `xhigh` / `max`
`isolation`	`worktree` で一時的な git worktree で走らせる。既定ブランチから分岐する（親セッションの `HEAD` ではない）。変更がなければ自動で片付けられる
`color`	タスク一覧・transcript での表示色
`initialPrompt`	`--agent` でメインセッションのエージェントとして走るとき、最初の user ターンとして自動送信される

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

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

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

モデルの解決順（4段階）

CLAUDE_CODE_SUBAGENT_MODEL 環境変数
呼び出しごとの model パラメータ
subagent 定義の model frontmatter
メイン会話のモデル

v2.1.198 以降、subagent はメイン会話の extended thinking 設定も継承する。subagent ごとの 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 / のようなルート/ホーム削除。

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: fork`	agent 種別から	SKILL.md の内容	CLAUDE.md（Explore / Plan を除く）
subagent の `skills`	subagent の 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）。Explore と Plan はスキップ
git status — 親セッション開始時点のスナップショット。Explore と Plan はスキップ
preload した skill の全文
sibling roster — main と、セッション内の名前付きエージェントの一覧（SendMessage の to に使える）

入らないもの:

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

The main conversation reads Explore and Plan results with full CLAUDE.md context, 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. 本流の会話は Explore と Plan の結果を CLAUDE.md の context 込みで読むので、ほとんどのルールは subagent 自身まで届く必要がない。「vendor/ ディレクトリは無視せよ」のように届く必要があるルールは、委譲するときに Claude へ渡すプロンプトの中で言い直せ。

foreground と background

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

v2.1.198 以降、既定はバックグラウンド。 Claude が結果を先に必要とするときだけ前景で走らせる。

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 で実行中のタスクをバックグラウンドに送れる。

ネストと同時実行の上限

上限	既定	環境変数
ネストの深さ	メイン会話の下3層	`CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`（`1` でネスト無効）
同時実行数	20。超えると `Concurrent subagent limit reached` でエラーになり、Claude にリトライしないよう伝える	`CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS`

セッション全体での総数に上限はない
ultracode が有効なセッションは同時実行の上限が適用されない
/subtask の fork はスロットを取るが上限でブロックされない。resume は上限を確認せずに新しいスロットを取るので、上限を超えることがある

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
  }
}

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

features-overview — subagent / agent teams / skill の使い分け
skills — context: fork と skills フィールドの逆向きの関係
context-window — subagent による context 節約の実測（6,100 → 420 トークン）
workflows — subagent を大規模に統率する仕組み
memory — CLAUDE.md 階層と auto memory
claude-code-best-practices — 「調査には subagent」
cross-session-messaging — 同じ SendMessage がセッションの外にも届く

未取得の派生リンク

https://code.claude.com/docs/en/agent-teams — agent teams
https://code.claude.com/docs/en/agent-view — background session / agent view
https://code.claude.com/docs/en/permission-modes — permission mode の詳細
https://code.claude.com/docs/en/worktrees — isolation: worktree
https://code.claude.com/docs/en/tools-reference — ツール一覧
https://code.claude.com/docs/en/env-vars — 環境変数

ai-docs

エクスプローラー