Create custom subagents

概要

特定種類のタスクを専用のコンテキストウィンドウで処理する AI アシスタント。独自のシステムプロンプト、ツールアクセス、権限を持ち、結果の要約だけをメイン会話へ返す。

仕様

組み込み subagent

いずれも親会話の permission を継承する。多くは制限されたツールセットで動く。

• Explore と Plan は CLAUDE.md と親セッションの git status を読み込まない。他の組み込みとカスタム subagent は両方を読み込む
• v2.1.198 以降、Explore は常に Haiku ではなくメイン会話のモデルを継承する。Claude API では Opus が上限。他プロバイダでは直接継承する
• Explore という名前の user / project subagent は組み込みを上書きし、自身の model フィールドを保つ
• Explore 呼び出し時、Claude は thoroughness を指定する: quick / medium / very thorough

組み込みの制限:

• 特定の組み込み型をブロックするには permissions.deny に追加する
• どの subagent にも委譲させないには Agent ツール自体を permissions.deny で拒否する
• 組み込みの Explore と Plan のみを外すには CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1（v2.1.198 以降）
• 非対話モードと Agent SDK では CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1 ですべての組み込み型を外せる

配置場所と優先順位

• project subagent は作業ディレクトリから上へ辿り、リポジトリルートまでの各 .claude/agents/ が走査される。v2.1.178 以降、ネストしたディレクトリが同じ name を定義している場合は作業ディレクトリに最も近い定義が使われる
• --add-dir で追加したディレクトリ内の .claude/agents/ も project subagent と並んで読み込まれる
• .claude/agents/ と ~/.claude/agents/ は再帰的に走査される。サブディレクトリのパスは識別・呼び出しに影響しない（identity は name frontmatter のみから来る）
• 同一 .claude/agents/ 配下（サブフォルダを含む）で 2 つのファイルが同じ名前を宣言すると、ファイルシステムの読み取り順で片方だけが読み込まれる。/doctor は同一ディレクトリ内の名前重複を報告する
• plugin の agents/ も再帰走査され、サブフォルダは scoped identifier の一部になる（agents/review/security.md は my-plugin:review:security）
• CLI 定義（--agents）は JSON で渡し、そのセッションのみ存在しディスクに保存されない。ファイルベースと同じフィールド（description, prompt, tools, disallowedTools, model, permissionMode, mcpServers, hooks, maxTurns, skills, initialPrompt, memory, effort, background, isolation, color）を受け付ける。prompt がシステムプロンプト
• plugin subagent は hooks / mcpServers / permissionMode の frontmatter フィールドをサポートしない（読み込み時に無視される）

ファイルの書き方

• YAML frontmatter + markdown のシステムプロンプト
• subagent が受け取るのは、このシステムプロンプトと作業ディレクトリなどの基本的な環境情報だけで、Claude Code の完全なシステムプロンプトではない
• Claude Code は ~/.claude/agents/ と .claude/agents/ を監視する。ファイルを追加・編集すると数秒以内に検出され、次の委譲から反映される。ただしセッション開始時に存在しなかった agents ディレクトリの初回作成時と、--disable-slash-commands で起動したセッションでは再起動が必要
• 非対話モードでは --append-subagent-system-prompt がネストしたものを含む全 subagent のシステムプロンプト末尾にテキストを追記する（v2.1.205 以降）
• subagent はメイン会話の現在の作業ディレクトリで開始する。subagent 内の cd は Bash / PowerShell ツール呼び出し間で持続せず、メイン会話の作業ディレクトリにも影響しない

frontmatter フィールド

必須は name と description のみ。

モデルの解決順

1. CLAUDE_CODE_SUBAGENT_MODEL 環境変数（モデルエイリアスまたはモデル ID のとき）
2. 呼び出しごとの model パラメータ
3. subagent 定義の model frontmatter
4. メイン会話のモデル

• v2.1.196 以降、CLAUDE_CODE_SUBAGENT_MODEL を inherit にすることは未設定と同じ。以前は強制的にメイン会話のモデルにし、他の 2 つを無視していた
• これらの値は組織の availableModels allowlist と照合される。ブロックされた値が opus のようなファミリーエイリアスの場合、allowlist が許すそのファミリーの最新版で動く。それ以外の場合は継承モデルで動く
• 呼び出しごとの model パラメータは、subagent を resume したりフォローアップを送ったりしたときにも適用される（v2.1.211 以降）
• v2.1.198 以降、subagent はメイン会話の extended thinking 設定を継承する。subagent ごとの thinking 設定は無い

使えるツール

subagent はメイン会話の組み込みツールと MCP ツールを継承し、2 つのフィルタで絞られる。fork は両方のフィルタを飛ばして親の正確なツールプールを受け取る。

第 1 フィルタ（tools に列挙しても取り除かれる）:

• Agent（subagent が depth limit にいるとき。fork ではツールは残るが spawn の代わりにエラーを返す）
• 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。

• agent team の teammate はさらに TaskCreate, TaskGet, TaskList, TaskUpdate, CronCreate, CronDelete, CronList を保つ
• tools と disallowedTools の両方を設定した場合、disallowedTools が先に適用され、残ったプールに対して tools が解決される。両方に列挙されたツールは取り除かれる
• 両フィールドとも MCP のサーバー単位パターンを受け付ける（mcp__<server> / mcp__<server>__*）。disallowedTools では mcp__* が全サーバーの全 MCP ツールを取り除く

spawn できる subagent の制限

• claude --agent でメインスレッドとして動く agent は Agent ツールで subagent を spawn できる。tools に Agent(worker, researcher) の形で書くと allowlist になる
• Agent を括弧なしで書くと制限なしに spawn できる。tools から Agent を省くと一切 spawn できない
• Agent(agent_type) の allowlist 構文が効くのは claude --agent のメインスレッドのみ。subagent 定義では Agent を書くと depth limit の範囲で spawn できるが、括弧内の型リストは無視される
• version 2.1.63 で Task ツールは Agent に改名された。既存の Task(...) 参照はエイリアスとして動く

permission mode

• 親が bypassPermissions または acceptEdits の場合それが優先され、上書きできない
• 親が auto mode の場合、subagent は auto mode を継承し frontmatter の permissionMode は無視される

永続メモリ

• subagent memory は auto memory の一部。autoMemoryEnabled や CLAUDE_CODE_DISABLE_AUTO_MEMORY で auto memory を切ると memory フィールドは効かない
• 有効時、subagent のシステムプロンプトにメモリディレクトリの読み書き手順が含まれ、メモリディレクトリの MEMORY.md の先頭 200 行または 25KB（早い方）が含まれる
• Read / Write / Edit ツールが自動的に有効になる

hooks

• frontmatter の hooks はその subagent がアクティブな間のみ動き、終了時に片付けられる
• settings.json のセッション全体の hooks も subagent 内で発火する。PreToolUse / PostToolUse は subagent のツール呼び出しでも動き、SubagentStart / SubagentStop は subagent の開始・終了で動く
• project レベルの subagent の frontmatter hooks を動かすには、agent ファイルを含むフォルダの workspace trust ダイアログを承認する。~/.claude/agents/ の user レベルと --agents で渡した定義は不要。承認するまで subagent は動くが frontmatter hooks はスキップされ、デバッグログにエラーが記録される（v2.1.218 以降）
• agent が subagent として呼ばれたとき、frontmatter の Stop hook は実行時に SubagentStop イベントへ変換される
• SubagentStart / SubagentStop の matcher は agent の frontmatter name、plugin subagent では my-plugin:db-agent のような scoped identifier。scoped 名はコロンを含むため anchor されない正規表現として評価される（^my-plugin:db-agent$ のように anchor する）
• db-agent のようなハイフン付き matcher は v2.1.195 以降で完全一致する。それ以前は anchor されない正規表現として評価され prod-db-agent にも発火した

明示的な呼び出し

• 自然言語: プロンプトで subagent 名を挙げる。委譲するかは Claude が判断する
• @-mention: @ を入力して typeahead から選ぶ。その subagent が確実に動く。メッセージ全体は Claude に届き、Claude がタスクプロンプトを書く。手入力では @agent-<name>、plugin subagent は @agent-my-plugin:code-reviewer
• セッション全体: claude --agent <name> でメインスレッド自体がその subagent のシステムプロンプト・ツール制限・モデルを引き受ける。システムプロンプトは既定の Claude Code システムプロンプトを完全に置き換える（--system-prompt と同じ）。CLAUDE.md とプロジェクトメモリは通常のメッセージフローで読み込まれる。agent 名は起動ヘッダーに @<name> として表示される
  • セッションを resume してもこの選択は持続する。resume 時に agent が存在しなければ既定のツールとシステムプロンプトで継続し、agent 名を挙げた警告を出す
  • 複数の plugin が同名の agent を提供する場合は scoped 名で曖昧さを解消する
  • プロジェクトの既定にするには .claude/settings.json に agent を設定する。CLI フラグは設定を上書きする

フォアグラウンド / バックグラウンド

• フォアグラウンド: 完了までメイン会話をブロックする。permission prompt はそのまま渡される
• バックグラウンド: 並行して動く。v2.1.186 以降、permission が必要なツール呼び出しに達するとメインセッションにプロンプトが出て、どの subagent が求めているかを示す。承認すると継続し、Esc でその 1 回のツール呼び出しだけを拒否する（subagent は止まらない）。v2.1.186 より前はプロンプトが必要な呼び出しを自動拒否していた
• v2.1.198 以降、既定でバックグラウンド実行。Claude は結果が必要なときにフォアグラウンドで動かす
• バックグラウンドの結果は後のターンで完了通知として Claude に届く。Claude はその通知を待ってから結果を報告する
• Ctrl+B で実行中のタスクをバックグラウンド化できる
• 完了したバックグラウンド subagent は /tasks に done として残り、実行中の作業の下に並ぶ。失敗または停止した subagent は一覧から消える
• CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 ですべてのバックグラウンドタスク機能を無効化できる
• CLAUDE_CODE_FORK_SUBAGENT=1 のとき、すべての subagent がバックグラウンドで動き frontmatter の background は効かない。CLAUDE_CODE_DISABLE_BACKGROUND_TASKS はフォークモードより優先される

ネストと同時実行の制限

• 既定でメイン会話の 3 層下まで subagent が自分の subagent を spawn できる。depth limit では fork を除く全 subagent から Agent ツールが取り除かれる
• 上限は CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH で変更する。1 でネストを無効にする
• v2.1.172〜v2.1.216 は既定 5 層で変更不可、v2.1.217〜v2.1.218 は既定 1、v2.1.219 で既定 3 になった
• 同時実行の既定上限は 20。超えると Agent ツールでの spawn が Concurrent subagent limit reached で失敗し、再試行しないよう Claude に伝える。CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS で変更する。ultracode がアクティブなセッションは対象外。v2.1.217 以降が必要
• セッション全体で spawn できる総数に制限は無い
• /subtask で始めたセッション内 fork はスロットを占めるが、この上限でブロックされない。完了済み subagent の resume は上限を確認せず新しいスロットを取る

起動時に読み込まれるもの（fork 以外）

• System prompt: agent 自身のプロンプトと Claude Code が付ける環境情報
• Task message: 委譲時に Claude が書くプロンプト
• CLAUDE.md files: メイン会話が読み込む CLAUDE.md 階層のすべて。Explore と Plan はスキップする
• Git status: 親セッション開始時のスナップショット。git リポジトリでない場合や includeGitInstructions が false の場合は無い。Explore と Plan は常にスキップする
• Preloaded skills: skills フィールドに挙げた skill の全内容。組み込み agent は preload しない
• Sibling roster: main とセッション内の他の名前付き agent を列挙する system reminder。SendMessage の to に使える。v2.1.206 以降が必要。subagent のツールに SendMessage が含まれ、他に名前付き agent が 1 つ以上あるときのみ現れる。subagent 起動時のスナップショット

メイン会話から届かないもの:

• Output style: subagent は独自のシステムプロンプトで動く（fork を除く）
• Auto memory: メイン会話の auto memory は読み込まれない
• Context window size: subagent のコンテキストウィンドウは親ではなく自身のモデルで決まる

subagent の resume

• 各呼び出しは新しいインスタンスを作る。既存の作業を続けるには Claude に resume を依頼する
• resume された subagent は過去のツール呼び出し・結果・推論を含む会話履歴全体を保つ
• 完了時に Claude は agent ID を受け取る。組み込みの Explore と Plan は one-shot で agent ID を返さないため resume できない
• Claude は SendMessage ツールに agent の ID または名前を to として渡す。SendMessage に agent teams の有効化は不要（shutdown_request などの構造化チームプロトコルメッセージのみ必要）
• 完了した subagent が SendMessage を受け取ると、新しい Agent 呼び出しなしにバックグラウンドで自動 resume される。TaskStop で Claude が止めた subagent も同様
• v2.1.191 以降、/tasks の x や SDK の stop_task で自分が止めた subagent は自動 resume しない。SendMessage は拒否を返す。subagent パネルのトランスクリプトに入力すると自分で resume でき、stop が解除される
• resume は同じ ID で新しい run を開始するため、失敗・完了していた subagent がタスク一覧で再び running になる
• v2.1.199 以降、SendMessage は名前が会話内で以前到達したのと同じ agent を指しているかを確認する。新しい agent が名前を取っていた場合は送信を拒否し、その名前が現在どの agent に届くかを報告する。このチェックは現在の会話にスコープされ /clear でリセットされる
• v2.1.198 以降、subagent は自分を起動した agent からのメッセージを通常のタスク指示（途中の方向修正を含む）として扱い、自身の permission 設定の範囲で行動する。ただし、どの agent からのメッセージも保留中の permission prompt への承認にはならず、subagent の permission 設定・CLAUDE.md・構成を変えることもできない
• agent ID はトランスクリプトファイル ~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl でも確認できる
• subagent のトランスクリプトはメイン会話の compaction の影響を受けず、別ファイルに保存される。セッション内で持続し、同じセッションを resume すれば Claude Code 再起動後も subagent を resume できる。cleanupPeriodDays（既定 30 日）の保持期間後に削除される
• subagent はメイン会話と同じロジックで自動 compaction をサポートする。CLAUDE_AUTOCOMPACT_PCT_OVERRIDE も適用される。compaction イベントは compact_boundary としてトランスクリプトに記録され、preTokens が compaction 前のトークン数を示す

API エラー

v2.1.199 以降、API エラー（使用量上限、繰り返されるサーバーエラーなど）で終わった subagent は、エラーテキストを findings として返すのではなく失敗として報告する。

• フォアグラウンド: 既にテキスト出力を出していた場合、Agent ツールはその部分出力に「打ち切られ、タスクを完了しなかった」旨の注記を付けて返す。何も出力していない、またはツール呼び出しのみだった場合は Agent terminated early due to an API error とエラー詳細で失敗する
• バックグラウンド: subagent は failed としてマークされ、Claude が受け取るメッセージに API エラー名と subagent の最後の出力が含まれる

subagent 出力のスキャン

Claude が読む前に、Claude Code が各 subagent の最終レポートをスキャンする。v2.1.210 以降が必要。

• Backslash insertion: <system-reminder> タグや Human: / Assistant: で始まる行など、Claude Code 自身の出力を模した文字列にバックスラッシュを挿入する
• Marker line: <system-reminder> のようなタグを模している場合や、bypassPermissions / --dangerously-skip-permissions などの permission 設定に言及している場合、[harness: subagent output matched instruction-shaped pattern(s): で始まる行を先頭に付ける
• スキャンは内容の削除も言い換えも行わず、悪意の有無も判定しない。レポート内の指示が Claude に行わせるツール呼び出しは、引き続きセッションの permission チェックと sandboxing を通る

fork

• fork は新規のコンテキストではなく、それまでの会話全体を継承する subagent。メインセッションと同じシステムプロンプト・ツール・モデル・メッセージ履歴を見る
• fork 自身のツール呼び出しは会話に入らず、最終結果だけが返る
• /subtask <task> で開始する（v2.1.212 以降。v2.1.161〜v2.1.211 では /fork）。agent view が無効な場合 /subtask は使えず /fork が forked subagent を開始する
• CLAUDE_CODE_FORK_SUBAGENT を 1 で明示的に有効、0 で無効にする。対話モード、SDK、claude -p で有効
• フォークモードを有効にすると、Claude が fork subagent 型を明示的に要求して fork を spawn できるようになり、fork か named subagent かを問わずすべての subagent がバックグラウンドで動く。Claude が型を要求しなかった場合は従来どおり general-purpose subagent になり、Explore などの named subagent もこれまでどおり spawn される
• Claude 自身に fork を spawn させる機能は experimental で、将来のリリースで変更されうる。 段階的ロールアウトの一環として、対話セッションでもこの機能が有効化されることがある
• fork はさらに fork を spawn できない
• Claude が Agent ツールで fork を spawn するとき isolation: "worktree" を渡せる

実行中の fork のパネル操作:

• fork / subagent のトランスクリプトを開いている間、フォローアップメッセージと skill はその agent に届くが、組み込みコマンドはメイン会話で動く。v2.1.199 以降、そのビューで /model や /fast を打つと、閲覧中の agent ではなくメイン会話に対する変更である旨の通知が出る

設定

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

---
name: browser-tester
description: Tests features in a real browser using Playwright
mcpServers:
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  - github
---

{
  "permissions": {
    "deny": ["Agent(Explore)", "Agent(my-custom-agent)"]
  }
}

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

{
  "agent": "code-reviewer"
}

制約・注意点

• /agents は v2.1.198 以降、対話的な作成ウィザードを開かず、Claude に依頼するか .claude/agents/ を直接編集するようリマインダーを出す
• disable-model-invocation: true の skill は preload できない（bundled の /verify と /code-review を含む）。存在しない・無効な skill は skip され、デバッグログに警告が出る
• isolation: worktree の subagent は Bash / PowerShell コマンドを worktree 内で実行する。作業ディレクトリがメイン checkout に解決されるコマンドはエラーで失敗する。このチェックは、Claude Code を起動したディレクトリを含むリポジトリ全体を対象とする（v2.1.210 以降）
• 多数の subagent がそれぞれ詳細な結果を返すと、メイン会話のコンテキストを大きく消費する

関連

• facts/claude-code/skills.md
• facts/claude-code/hooks.md
• facts/claude-code/permissions.md
• facts/claude-code/permission-modes.md
• facts/claude-code/mcp.md
• facts/claude-code/model-config.md
• facts/claude-code/worktrees.md
• facts/claude-code/tools-reference.md
• facts/claude-code/memory.md
• facts/claude-code/settings.md
• facts/claude-code/env-vars.md
• facts/claude-code/context-window.md