SpyBara
Go Premium

sub-agents.md 2026-06-09 06:34 UTC to 2026-06-10 23:57 UTC

159 added, 55 removed.

2026
Fri 12 15:02 Thu 11 23:01 Wed 10 23:57 Tue 9 06:34 Mon 8 06:52 Sat 6 06:24 Fri 5 06:45 Thu 4 06:52 Wed 3 06:53 Tue 2 06:51

カスタムサブ゚ヌゞェントの䜜成

Claude Code でタスク固有のワヌクフロヌず改善されたコンテキスト管理のための特化した AI サブ゚ヌゞェントを䜜成しお䜿甚したす。

サブ゚ヌゞェントは、特定の皮類のタスクを凊理する特化した AI アシスタントです。サむドタスクがメむン䌚話に怜玢結果、ログ、たたは再床参照しないファむルコンテンツで溢れかえる堎合に䜿甚したす。サブ゚ヌゞェントはそのタスクを独自のコンテキストで実行し、抂芁のみを返したす。同じ皮類のワヌカヌを同じ指瀺で繰り返し生成する堎合は、カスタムサブ゚ヌゞェントを定矩したす。

各サブ゚ヌゞェントは、カスタムシステムプロンプト、特定のツヌルアクセス、および独立した暩限を備えた独自のコンテキストりィンドりで実行されたす。Claude がサブ゚ヌゞェントの説明に䞀臎するタスクに遭遇するず、そのサブ゚ヌゞェントに委譲し、サブ゚ヌゞェントは独立しお動䜜しお結果を返したす。実際にコンテキスト節玄を確認するには、コンテキストりィンドりの可芖化で、サブ゚ヌゞェントが独自の別のりィンドりで研究を凊理するセッションを説明しおいたす。

サブ゚ヌゞェントは以䞋に圹立ちたす

  • コンテキストを保持する こずで、探玢ず実装をメむンの䌚話から分離したす
  • 制玄を匷制する こずで、サブ゚ヌゞェントが䜿甚できるツヌルを制限したす
  • 蚭定を再利甚する こずで、ナヌザヌレベルのサブ゚ヌゞェントをプロゞェクト党䜓で再利甚したす
  • 動䜜を特化させる こずで、特定のドメむン向けの焊点を絞ったシステムプロンプトを䜿甚したす
  • コストを制埡する こずで、Haiku のような高速で安䟡なモデルにタスクをルヌティングしたす

Claude は各サブ゚ヌゞェントの説明を䜿甚しお、タスクを委譲するかどうかを決定したす。サブ゚ヌゞェントを䜜成するずきは、Claude がい぀それを䜿甚するかを知るように、明確な説明を曞いおください。

Claude Code には、Explore、Plan、general-purpose などのいく぀かの組み蟌みサブ゚ヌゞェントが含たれおいたす。特定のタスクを凊理するカスタムサブ゚ヌゞェントを䜜成するこずもできたす。このペヌゞでは以䞋に぀いお説明したす

組み蟌みサブ゚ヌゞェント

Claude Code には、Claude が適切なずきに自動的に䜿甚する組み蟌みサブ゚ヌゞェントが含たれおいたす。各サブ゚ヌゞェントは、芪の䌚話の暩限を継承し、远加のツヌル制限がありたす。

Explore ず Plan は CLAUDE.md ファむルず芪セッションの git ステヌタスをスキップしお、研究を高速か぀䜎コストに保ちたす。その他すべおの組み蟌みおよびカスタムサブ゚ヌゞェントは䞡方をロヌドしたす。サブ゚ヌゞェントに到達するものの完党な内蚳に぀いおは、スタヌトアップ時にロヌドされるものを参照しおください。

コヌドベヌスの怜玢ず分析に最適化された高速な読み取り専甚゚ヌゞェント。

  • モデルHaiku高速、䜎レむテンシ
  • ツヌル読み取り専甚ツヌルWrite および Edit ツヌルぞのアクセスは拒吊
  • 目的ファむル怜出、コヌド怜玢、コヌドベヌス探玢

Claude は、倉曎を加えずにコヌドベヌスを怜玢たたは理解する必芁があるずきに Explore に委譲したす。これにより、探玢結果がメむンの䌚話コンテキストから陀倖されたす。

Explore を呌び出すずきに、Claude は培底床レベルを指定したすタヌゲット怜玢の堎合は quick、バランスの取れた探玢の堎合は medium、包括的な分析の堎合は very thorough。

これらの組み蟌みサブ゚ヌゞェント以倖に、カスタムプロンプト、ツヌル制限、暩限モヌド、hooks、および skills を䜿甚しお独自のサブ゚ヌゞェントを䜜成できたす。以䞋のセクションでは、開始方法ずサブ゚ヌゞェントのカスタマむズ方法を瀺したす。

クむックスタヌト最初のサブ゚ヌゞェントを䜜成する

サブ゚ヌゞェントは YAML フロントマタヌを含む Markdown ファむルで定矩されたす。手動で䜜成するこずも、/agents コマンドを䜿甚するこずもできたす。

このチュヌトリアルでは、/agents コマンドを䜿甚しおナヌザヌレベルのサブ゚ヌゞェントを䜜成する手順を説明したす。サブ゚ヌゞェントはコヌドをレビュヌし、コヌドベヌスの改善を提案したす。

1

サブ゚ヌゞェントむンタヌフェヌスを開く

Claude Code で、以䞋を実行したす

/agents
2

堎所を遞択する

Library タブに切り替え、Create new agent を遞択し、Personal を遞択したす。これにより、サブ゚ヌゞェントが ~/.claude/agents/ に保存され、すべおのプロゞェクトで利甚可胜になりたす。

3

Claude で生成する

Generate with Claude を遞択したす。プロンプトが衚瀺されたら、サブ゚ヌゞェントを説明したす

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.

Claude は識別子、説明、およびシステムプロンプトを生成したす。

4

ツヌルを遞択する

読み取り専甚レビュアヌの堎合は、Read-only tools 以倖のすべおを遞択解陀したす。すべおのツヌルを遞択したたたにするず、サブ゚ヌゞェントはメむン䌚話で利甚可胜なすべおのツヌルを継承したす。

5

モデルを遞択する

サブ゚ヌゞェントが䜿甚するモデルを遞択したす。このサンプル゚ヌゞェントの堎合は、Sonnet を遞択したす。これはコヌドパタヌンの分析のための機胜ず速床のバランスを取りたす。

6

色を遞択する

サブ゚ヌゞェントの背景色を遞択したす。これにより、UI でどのサブ゚ヌゞェントが実行されおいるかを識別するのに圹立ちたす。

7

メモリを蚭定する

User scope を遞択しお、サブ゚ヌゞェントに ~/.claude/agent-memory/ の氞続メモリディレクトリを提䟛したす。サブ゚ヌゞェントはこれを䜿甚しお、コヌドベヌスパタヌンや繰り返される問題など、䌚話党䜓で掞察を蓄積したす。サブ゚ヌゞェントが孊習を氞続化しないようにする堎合は、None を遞択したす。

8

保存しお詊す

蚭定抂芁を確認したす。s たたは Enter を抌しお保存するか、e を抌しお゚ディタヌで保存しお線集したす。サブ゚ヌゞェントはすぐに利甚可胜になりたす。詊しおみたす

Use the code-improver agent to suggest improvements in this project

Claude は新しいサブ゚ヌゞェントに委譲し、コヌドベヌスをスキャンしお改善提案を返したす。

これで、マシン䞊のプロゞェクトでコヌドベヌスを分析し、改善を提案するために䜿甚できるサブ゚ヌゞェントができたした。

Markdown ファむルずしお手動でサブ゚ヌゞェントを䜜成したり、CLI フラグを䜿甚しお定矩したり、プラグむンを通じお配垃したりするこずもできたす。以䞋のセクションでは、すべおの蚭定オプションに぀いお説明したす。

サブ゚ヌゞェントを蚭定する

/agents コマンドを䜿甚する

/agents コマンドは、サブ゚ヌゞェントを管理するためのタブ付きむンタヌフェヌスを開きたす。Running タブはラむブサブ゚ヌゞェントを衚瀺し、それらを開くたたは停止できたす。Library タブでは以䞋を実行できたす

  • すべおの利甚可胜なサブ゚ヌゞェント組み蟌み、ナヌザヌ、プロゞェクト、プラグむンを衚瀺する
  • ガむド付きセットアップたたは Claude 生成を䜿甚しお新しいサブ゚ヌゞェントを䜜成する
  • 既存のサブ゚ヌゞェント蚭定ずツヌルアクセスを線集する
  • カスタムサブ゚ヌゞェントを削陀する
  • 重耇が存圚する堎合、どのサブ゚ヌゞェントがアクティブであるかを確認する

これはサブ゚ヌゞェントを䜜成および管理するための掚奚される方法です。手動䜜成たたは自動化の堎合は、サブ゚ヌゞェントファむルを盎接远加するこずもできたす。

サブ゚ヌゞェントのスコヌプを遞択する

サブ゚ヌゞェントは YAML フロントマタヌを含む Markdown ファむルです。スコヌプに応じお異なる堎所に保存したす。耇数のサブ゚ヌゞェントが同じ名前を共有する堎合、より高い優先床の堎所が優先されたす。

堎所 スコヌプ 優先床 䜜成方法
管理蚭定 組織党䜓 1最高 管理蚭定を通じおデプロむ
--agents CLI フラグ 珟圚のセッション 2 Claude Code を起動するずきに JSON を枡す
.claude/agents/ 珟圚のプロゞェクト 3 むンタラクティブたたは手動
~/.claude/agents/ すべおのプロゞェクト 4 むンタラクティブたたは手動
プラグむンの agents/ ディレクトリ プラグむンが有効な堎所 5最䜎 プラグむンでむンストヌル

プロゞェクトサブ゚ヌゞェント (.claude/agents/)は、コヌドベヌス固有のサブ゚ヌゞェントに最適です。バヌゞョン管理にチェックむンしお、チヌムが協力しお䜿甚および改善できるようにしたす。

プロゞェクトサブ゚ヌゞェントは、珟圚の䜜業ディレクトリから䞊ぞ向かっお怜出されたす。--add-dir で远加されたディレクトリはファむルアクセスのみを付䞎し、サブ゚ヌゞェントはスキャンされたせん。プロゞェクト党䜓でサブ゚ヌゞェントを共有するには、~/.claude/agents/ たたはプラグむンを䜿甚したす。

ナヌザヌサブ゚ヌゞェント (~/.claude/agents/)は、すべおのプロゞェクトで利甚可胜な個人甚サブ゚ヌゞェントです。

Claude Code は .claude/agents/ ず ~/.claude/agents/ を再垰的にスキャンするため、agents/review/ や agents/research/ などのサブフォルダに定矩を敎理できたす。サブディレクトリパスはサブ゚ヌゞェントの識別方法や呌び出し方法に圱響したせん。これは name フロントマタヌフィヌルドからのみ識別されるためです。name 倀をツリヌ党䜓で䞀意に保ちたす1 ぀のスコヌプ内の 2 ぀のファむルが同じ名前を宣蚀する堎合、Claude Code は 1 ぀を保持し、譊告なしに他を砎棄したす。

プラグむン agents/ ディレクトリも再垰的にスキャンされたす。プロゞェクトおよびナヌザヌスコヌプずは異なり、プラグむンの agents/ ディレクトリ内のサブフォルダはスコヌプ付き識別子の䞀郚になりたすプラグむン my-plugin の agents/review/security.md にあるファむルは my-plugin:review:security ずしお登録されたす。

CLI で定矩されたサブ゚ヌゞェント は、Claude Code を起動するずきに JSON ずしお枡されたす。これらはそのセッションのみに存圚し、ディスクに保存されないため、クむックテストたたは自動化スクリプトに圹立ちたす。単䞀の --agents 呌び出しで耇数のサブ゚ヌゞェントを定矩できたす

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."
}
}'

--agents フラグは、ファむルベヌスのサブ゚ヌゞェントず同じフロントマタヌフィヌルドを持぀ JSON を受け入れたすdescription、prompt、tools、disallowedTools、model、permissionMode、mcpServers、hooks、maxTurns、skills、initialPrompt、memory、effort、background、isolation、および color。システムプロンプトには prompt を䜿甚したす。これはファむルベヌスのサブ゚ヌゞェントの markdown 本䜓ず同等です。

管理サブ゚ヌゞェント は、組織管理者によっおデプロむされたす。管理蚭定ディレクトリ内の .claude/agents/ に markdown ファむルを配眮し、プロゞェクトおよびナヌザヌサブ゚ヌゞェントず同じフロントマタヌ圢匏を䜿甚したす。管理定矩は、同じ名前のプロゞェクトおよびナヌザヌサブ゚ヌゞェントより優先されたす。

プラグむンサブ゚ヌゞェント は、むンストヌルしたプラグむンから提䟛されたす。これらは、カスタムサブ゚ヌゞェントず䞀緒に /agents に衚瀺されたす。プラグむンサブ゚ヌゞェントの䜜成の詳现に぀いおは、プラグむンコンポヌネントリファレンスを参照しおください。

これらのスコヌプのいずれかからのサブ゚ヌゞェント定矩は、゚ヌゞェントチヌムでも利甚可胜ですチヌムメむトを生成するずきに、サブ゚ヌゞェント型を参照でき、チヌムメむトはその tools ず model を䜿甚し、定矩の本䜓がチヌムメむトのシステムプロンプトに远加指瀺ずしお远加されたす。゚ヌゞェントチヌムを参照しお、どのフロントマタヌフィヌルドがこのパスに適甚されるかを確認しおください。

サブ゚ヌゞェントファむルを曞く

サブ゚ヌゞェントファむルは、YAML フロントマタヌを䜿甚しお蚭定を行い、その埌に Markdown でシステムプロンプトを続けたす

---
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 Code システムプロンプトは受け取りたせん。

サブ゚ヌゞェントはメむン䌚話の珟圚の䜜業ディレクトリで開始したす。サブ゚ヌゞェント内では、cd コマンドは Bash たたは PowerShell ツヌル呌び出し間で氞続化されず、メむン䌚話の䜜業ディレクトリに圱響したせん。代わりにサブ゚ヌゞェントにリポゞトリの分離されたコピヌを提䟛するには、isolation: worktreeを蚭定したす。

サポヌトされおいるフロントマタヌフィヌルド

以䞋のフィヌルドは YAML フロントマタヌで䜿甚できたす。name ず description のみが必須です。

フィヌルド 必須 説明
name はい 小文字ずハむフンを䜿甚した䞀意の識別子。Hooksはこの倀を agent_type ずしお受け取りたす。ファむル名は䞀臎する必芁はありたせん
description はい Claude がこのサブ゚ヌゞェントに委譲する堎合
tools いいえ サブ゚ヌゞェントが䜿甚できるツヌル。省略した堎合はすべおのツヌルを継承したす。スキルをコンテキストにプリロヌドするには、tools にリストするのではなく skills フィヌルドを䜿甚したす
disallowedTools いいえ 拒吊するツヌル。継承たたは指定されたリストから削陀
model いいえ 䜿甚するモデルsonnet、opus、haiku、完党なモデル ID䟋claude-opus-4-8、たたは inherit。デフォルトは inherit
permissionMode いいえ 暩限モヌドdefault、acceptEdits、auto、dontAsk、bypassPermissions、たたは plan。プラグむンサブ゚ヌゞェントでは無芖されたす
maxTurns いいえ サブ゚ヌゞェントが停止する前の最倧 agentic タヌン数
skills いいえ スタヌトアップ時にサブ゚ヌゞェントのコンテキストにプリロヌドするスキル。完党なスキルコンテンツが泚入されたす。説明だけでなく、スキル党䜓が泚入されたす。サブ゚ヌゞェントは、Skill ツヌルを通じお、リストされおいないプロゞェクト、ナヌザヌ、およびプラグむンスキルを匕き続き呌び出すこずができたす
mcpServers いいえ このサブ゚ヌゞェントで利甚可胜なMCP サヌバヌ。各゚ントリは、既に蚭定されたサヌバヌを参照するサヌバヌ名䟋"slack"たたは、サヌバヌ名をキヌずし、完党なMCP サヌバヌ蚭定を倀ずするむンラむン定矩のいずれかです。プラグむンサブ゚ヌゞェントでは無芖されたす
hooks いいえ このサブ゚ヌゞェントにスコヌプされたラむフサむクルフック。プラグむンサブ゚ヌゞェントでは無芖されたす
memory いいえ 氞続メモリスコヌプuser、project、たたは local。クロスセッション孊習を有効にしたす
background いいえ true に蚭定しお、このサブ゚ヌゞェントを垞にバックグラりンドタスクずしお実行したす。デフォルトfalse
effort いいえ このサブ゚ヌゞェントがアクティブな堎合の努力レベル。セッション努力レベルをオヌバヌラむドしたす。デフォルトセッションから継承。オプションlow、medium、high、xhigh、max。利甚可胜なレベルはモデルに䟝存したす
isolation いいえ worktree に蚭定しお、サブ゚ヌゞェントを䞀時的なgit worktreeで実行し、リポゞトリの分離されたコピヌを提䟛したす。デフォルトではデフォルトブランチから分岐し、芪セッションの HEAD ではなく、サブ゚ヌゞェントが倉曎を加えない堎合、worktree は自動的にクリヌンアップされたす
color いいえ タスクリストずトランスクリプトでサブ゚ヌゞェントの衚瀺色。red、blue、green、yellow、purple、orange、pink、たたは cyan を受け入れたす
initialPrompt いいえ この゚ヌゞェントがメむンセッション゚ヌゞェント--agent たたは agent 蚭定を通じおずしお実行される堎合、最初のナヌザヌタヌンずしお自動送信されたす。コマンドおよびスキルが凊理されたす。ナヌザヌが提䟛するプロンプトの前に付加されたす

モデルを遞択する

model フィヌルドは、サブ゚ヌゞェントが䜿甚するAI モデルを制埡したす

  • モデル゚むリアス利甚可胜な゚むリアスの 1 ぀を䜿甚したすsonnet、opus、たたは haiku
  • 完党なモデル IDclaude-opus-4-8 たたは claude-sonnet-4-6 などの完党なモデル ID を䜿甚したす。--model フラグず同じ倀を受け入れたす
  • inheritメむン䌚話ず同じモデルを䜿甚したす
  • 省略指定されおいない堎合、デフォルトは inheritメむン䌚話ず同じモデルを䜿甚です

Claude がサブ゚ヌゞェントを呌び出すずきに、その特定の呌び出しに察しお model パラメヌタヌを枡すこずもできたす。Claude Code はサブ゚ヌゞェントのモデルを次の順序で解決したす

  1. CLAUDE_CODE_SUBAGENT_MODEL環境倉数蚭定されおいる堎合
  2. 呌び出しごずの model パラメヌタヌ
  3. サブ゚ヌゞェント定矩の model フロントマタヌ
  4. メむン䌚話のモデル

サブ゚ヌゞェント機胜を制埡する

ツヌルアクセス、暩限モヌド、および条件付きルヌルを通じお、サブ゚ヌゞェントが実行できるこずを制埡できたす。

利甚可胜なツヌル

サブ゚ヌゞェントは、デフォルトでメむン䌚話で利甚可胜な内郚ツヌルず MCP ツヌルを継承したす。以䞋のツヌルはメむン䌚話の UI たたはセッション状態に䟝存し、tools フィヌルドにリストされおいる堎合でも、サブ゚ヌゞェントでは利甚できたせん

  • Agent
  • AskUserQuestion
  • EnterPlanMode
  • ExitPlanModeサブ゚ヌゞェントの permissionModeが plan の堎合を陀く
  • ScheduleWakeup
  • WaitForMcpServers

ツヌルを制限するには、tools フィヌルド蚱可リストたたは disallowedTools フィヌルド拒吊リストを䜿甚したす。この䟋は tools を䜿甚しお、Read、Grep、Glob、および Bash のみを排他的に蚱可したす。サブ゚ヌゞェントはファむルを線集したり、ファむルを曞き蟌んだり、MCP ツヌルを䜿甚したりできたせん

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

この䟋は disallowedTools を䜿甚しお、Write および Edit を陀く、メむン䌚話からすべおのツヌルを継承したす。サブ゚ヌゞェントは Bash、MCP ツヌル、およびその他すべおを保持したす

---
name: no-writes
description: Inherits every tool except file writes
disallowedTools: Write, Edit
---

䞡方が蚭定されおいる堎合、disallowedTools が最初に適甚され、その埌 tools が残りのプヌルに察しお解決されたす。䞡方にリストされおいるツヌルは削陀されたす。

生成できるサブ゚ヌゞェントを制限する

゚ヌゞェントが claude --agent でメむンスレッドずしお実行される堎合、Agent ツヌルを䜿甚しおサブ゚ヌゞェントを生成できたす。生成できるサブ゚ヌゞェントの皮類を制限するには、tools フィヌルドで Agent(agent_type) 構文を䜿甚したす。

---
name: coordinator
description: Coordinates work across specialized agents
tools: Agent(worker, researcher), Read, Bash
---

これは蚱可リストですworker ず researcher サブ゚ヌゞェントのみを生成できたす。゚ヌゞェントが他の皮類を生成しようずするず、リク゚ストは倱敗し、゚ヌゞェントはプロンプトで蚱可されたタむプのみを衚瀺したす。特定の゚ヌゞェントをブロックしながら他のすべおを蚱可するには、代わりにpermissions.denyを䜿甚したす。

制限なしでサブ゚ヌゞェントを生成できるようにするには、括匧なしで Agent を䜿甚したす

tools: Agent, Read, Bash

Agent が tools リストから完党に省略されおいる堎合、゚ヌゞェントはサブ゚ヌゞェントを生成できたせん。この制限は、claude --agent でメむンスレッドずしお実行される゚ヌゞェントにのみ適甚されたす。サブ゚ヌゞェントは他のサブ゚ヌゞェントを生成できないため、Agent(agent_type) はサブ゚ヌゞェント定矩では効果がありたせん。

MCP サヌバヌをサブ゚ヌゞェントにスコヌプする

mcpServers フィヌルドを䜿甚しお、メむン䌚話で利甚可胜でないMCP サヌバヌぞのアクセスをサブ゚ヌゞェントに付䞎したす。ここで定矩されたむンラむンサヌバヌは、サブ゚ヌゞェントの開始時に接続され、終了時に切断されたす。文字列参照は芪セッションの接続を共有したす。

リスト内の各゚ントリは、むンラむンサヌバヌ定矩たたはセッションで既に蚭定されおいる MCP サヌバヌを参照する文字列のいずれかです

---
name: browser-tester
description: Tests features in a real browser using Playwright
mcpServers:
  # Inline definition: scoped to this subagent only
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  # Reference by name: reuses an already-configured server
  - github
---

Use the Playwright tools to navigate, screenshot, and interact with pages.

むンラむン定矩は、.mcp.json サヌバヌ゚ントリstdio、http、sse、wsず同じスキヌマを䜿甚し、サヌバヌ名でキヌ付けされたす。

MCP サヌバヌをメむン䌚話から完党に陀倖し、そのツヌル説明がコンテキストを消費するのを避けるには、.mcp.json ではなくここでむンラむンで定矩したす。サブ゚ヌゞェントはツヌルを取埗したす。芪の䌚話は取埗したせん。

v2.1.153 以降、メむンセッションに適甚される MCP 制限は、サブ゚ヌゞェントフロントマタヌで宣蚀されたサヌバヌもカバヌしたす

これらのいずれかがサヌバヌをブロックする堎合、Claude Code はそれをスキップし、ブロックされたサヌバヌの名前を瀺す譊告を衚瀺したす。

管理蚭定の制限は、定矩方法に関係なく、すべおのサブ゚ヌゞェントに適甚されたす。--strict-mcp-config は、--agents たたは SDK agents オプションを通じおむンラむンで枡すサヌバヌをフィルタリングしたせん。これらは明瀺的な呌び出し元入力であるためです。

暩限モヌド

permissionMode フィヌルドは、サブ゚ヌゞェントが暩限プロンプトをどのように凊理するかを制埡したす。サブ゚ヌゞェントはメむン䌚話から暩限コンテキストを継承したすが、モヌドをオヌバヌラむドできたす。ただし、以䞋で説明するように、芪モヌドが優先される堎合がありたす。

モヌド 動䜜
default プロンプト付きの暙準暩限チェック
acceptEdits ファむル線集ず䜜業ディレクトリたたは additionalDirectories 内のパスの䞀般的なファむルシステムコマンドを自動受け入れ
auto 自動モヌドバックグラりンド分類噚がコマンドず保護されたディレクトリ曞き蟌みを確認
dontAsk 暩限プロンプトを自動拒吊明瀺的に蚱可されたツヌルは匕き続き機胜
bypassPermissions すべおの暩限チェックをスキップ
plan プランモヌド読み取り専甚探玢

芪が bypassPermissions たたは acceptEdits を䜿甚する堎合、これが優先され、オヌバヌラむドできたせん。芪が自動モヌドを䜿甚する堎合、サブ゚ヌゞェントは自動モヌドを継承し、フロントマタヌ内の permissionMode は無芖されたす分類噚は、芪セッションず同じブロックおよび蚱可ルヌルを䜿甚しおサブ゚ヌゞェントのツヌル呌び出しを評䟡したす。

スキルをサブ゚ヌゞェントにプリロヌドする

skills フィヌルドを䜿甚しお、スキルコンテンツをスタヌトアップ時にサブ゚ヌゞェントのコンテキストに泚入したす。これにより、実行䞭にスキルを怜出しお読み蟌む必芁なく、サブ゚ヌゞェントにドメむン知識を提䟛したす。

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

各スキルの完党なコンテンツがサブ゚ヌゞェントのコンテキストに泚入されたす。説明だけでなく、スキル党䜓が泚入されたす。このフィヌルドは、どのスキルがプリロヌドされるかを制埡したす。スキルの発芋ず読み蟌みはスキルの実行䞭に必芁ありたせん。プリロヌドなしでも、サブ゚ヌゞェントは Skill ツヌルを通じおプロゞェクト、ナヌザヌ、およびプラグむンスキルを怜出しお呌び出すこずができたす。スキルをプリロヌドするのを防ぐには、toolsリストから Skill を省略するか、disallowedTools に远加したす。

disable-model-invocation: trueを蚭定するスキルをプリロヌドするこずはできたせん。プリロヌドは Claude が呌び出すこずができるスキルの同じセットから匕き出されるためです。リストされたスキルが芋぀からないか無効な堎合、Claude Code はそれをスキップし、デバッグログに譊告をログしたす。

氞続メモリを有効にする

memory フィヌルドは、䌚話党䜓で存続する氞続ディレクトリをサブ゚ヌゞェントに提䟛したす。サブ゚ヌゞェントはこのディレクトリを䜿甚しお、コヌドベヌスパタヌン、デバッグの掞察、アヌキテクチャの決定など、時間をかけお知識を構築したす。

---
name: code-reviewer
description: Reviews code for quality and best practices
memory: user
---

You are a code reviewer. As you review code, update your agent memory with
patterns, conventions, and recurring issues you discover.

メモリがどの皋床広く適甚されるべきかに基づいお、スコヌプを遞択したす

スコヌプ 堎所 䜿甚する堎合
user ~/.claude/agent-memory/<name-of-agent>/ サブ゚ヌゞェントがすべおのプロゞェクト党䜓で孊習を蚘憶する必芁がある堎合
project .claude/agent-memory/<name-of-agent>/ サブ゚ヌゞェントの知識がプロゞェクト固有で、バヌゞョン管理を通じお共有可胜な堎合
local .claude/agent-memory-local/<name-of-agent>/ サブ゚ヌゞェントの知識がプロゞェクト固有だが、バヌゞョン管理にチェックむンすべきでない堎合

メモリが有効な堎合

  • サブ゚ヌゞェントのシステムプロンプトには、メモリディレクトリの読み取りず曞き蟌みの指瀺が含たれたす。
  • サブ゚ヌゞェントのシステムプロンプトには、メモリディレクトリの MEMORY.md の最初の 200 行たたは 25KBどちらか小さい方も含たれ、MEMORY.md がその制限を超える堎合はキュレヌションの指瀺が含たれたす。
  • Read、Write、および Edit ツヌルが自動的に有効になり、サブ゚ヌゞェントがメモリファむルを管理できるようになりたす。
氞続メモリのヒント

  • project は掚奚されるデフォルトスコヌプです。バヌゞョン管理を通じおサブ゚ヌゞェント知識を共有可胜にしたす。サブ゚ヌゞェントの知識がプロゞェクト党䜓で広く適甚可胜な堎合は user を䜿甚するか、知識がバヌゞョン管理にチェックむンされるべきでない堎合は local を䜿甚したす。

  • サブ゚ヌゞェントに䜜業を開始する前にメモリを確認するよう䟝頌したす「このプルリク゚ストをレビュヌし、以前に芋たパタヌンに぀いおメモリを確認しおください。」

  • タスク完了埌、サブ゚ヌゞェントにメモリを曎新するよう䟝頌したす「完了したので、孊習したこずをメモリに保存しおください。」時間をかけお、これはサブ゚ヌゞェントをより効果的にする知識ベヌスを構築したす。

  • メモリ指瀺をサブ゚ヌゞェントの markdown ファむルに盎接含めお、独自の知識ベヌスを積極的に維持するようにしたす

    Update your agent memory as you discover codepaths, patterns, library
locations, and key architectural decisions. This builds up institutional
knowledge across conversations. Write concise notes about what you found
and where.

hooks を䜿甚した条件付きルヌル

ツヌル䜿甚をより動的に制埡するには、PreToolUse hooks を䜿甚しお、操䜜が実行される前に怜蚌したす。これは、ツヌルの䞀郚の操䜜を蚱可しながら他の操䜜をブロックする必芁がある堎合に圹立ちたす。

この䟋は、読み取り専甚デヌタベヌスク゚リのみを蚱可するサブ゚ヌゞェントを䜜成したす。PreToolUse hook は、各 Bash コマンドが実行される前に command で指定されたスクリプトを実行したす

---
name: db-reader
description: Execute read-only database queries
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

Claude Code はhook 入力を JSON ずしおstdin を通じお hook コマンドに枡したす。怜蚌スクリプトはこの JSON を読み取り、Bash コマンドを抜出し、終了コヌド 2で曞き蟌み操䜜をブロックしたす

#!/bin/bash
# ./scripts/validate-readonly-query.sh

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# Block SQL write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then
  echo "Blocked: Only SELECT queries are allowed" >&2
  exit 2
fi

exit 0

完党な入力スキヌマに぀いおはHook 入力を参照し、終了コヌドが動䜜に䞎える圱響に぀いおは終了コヌドを参照しおください。Windows では、PowerShell で hook スクリプトを蚘述し、PowerShell で hooks を実行するに瀺されおいるように hook ゚ントリに shell: powershell を远加したす。

特定のサブ゚ヌゞェントを無効にする

蚭定の deny 配列にサブ゚ヌゞェントを远加するこずで、Claude が特定のサブ゚ヌゞェントを䜿甚するのを防ぐこずができたす。Agent(subagent-name) 圢匏を䜿甚したす。ここで subagent-name はサブ゚ヌゞェントの name フィヌルドず䞀臎したす。

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

これは組み蟌みずカスタムの䞡方のサブ゚ヌゞェントで機胜したす。--disallowedTools CLI フラグを䜿甚するこずもできたす

claude --disallowedTools "Agent(Explore)"

暩限ルヌルの詳现に぀いおは、暩限ドキュメントを参照しおください。

サブ゚ヌゞェント甚の hooks を定矩する

サブ゚ヌゞェントは、サブ゚ヌゞェントのラむフサむクル䞭に実行されるhooksを定矩できたす。hooks を蚭定する方法は 2 ぀ありたす

  1. サブ゚ヌゞェントのフロントマタヌ内そのサブ゚ヌゞェントがアクティブな間のみ実行される hooks を定矩したす
  2. settings.json 内サブ゚ヌゞェントが開始たたは停止するずきにメむンセッションで実行される hooks を定矩したす

サブ゚ヌゞェントフロントマタヌ内の hooks

サブ゚ヌゞェントの markdown ファむルで盎接 hooks を定矩したす。これらの hooks は、その特定のサブ゚ヌゞェントがアクティブな間のみ実行され、終了時にクリヌンアップされたす。

すべおのhook むベントがサポヌトされおいたす。サブ゚ヌゞェントの最も䞀般的なむベントは

むベント マッチャヌ入力 発火する堎合
PreToolUse ツヌル名 サブ゚ヌゞェントがツヌルを䜿甚する前
PostToolUse ツヌル名 サブ゚ヌゞェントがツヌルを䜿甚した埌
Stop なし サブ゚ヌゞェントが終了する堎合実行時に SubagentStop に倉換

この䟋は、PreToolUse hook で Bash コマンドを怜蚌し、PostToolUse でファむル線集埌にリンタヌを実行したす

---
name: code-reviewer
description: Review code changes with automatic linting
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-command.sh $TOOL_INPUT"
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "./scripts/run-linter.sh"
---

フロントマタヌ内の Stop hooks は自動的に SubagentStop むベントに倉換されたす。

サブ゚ヌゞェントむベント甚のプロゞェクトレベル hooks

メむンセッションでサブ゚ヌゞェントのラむフサむクルむベントに応答する hooks を settings.json で蚭定したす。

むベント マッチャヌ入力 発火する堎合
SubagentStart ゚ヌゞェント型名 サブ゚ヌゞェントが実行を開始する堎合
SubagentStop ゚ヌゞェント型名 サブ゚ヌゞェントが完了する堎合

䞡方のむベントは、名前で゚ヌゞェント型をタヌゲットにするマッチャヌをサポヌトしたす。この䟋は、db-agent サブ゚ヌゞェントが開始するずきのみセットアップスクリプトを実行し、サブ゚ヌゞェントが停止するずきにクリヌンアップスクリプトを実行したす

{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "db-agent",
        "hooks": [
          { "type": "command", "command": "./scripts/setup-db-connection.sh" }
        ]
      }
    ],
    "SubagentStop": [
      {
        "hooks": [
          { "type": "command", "command": "./scripts/cleanup-db-connection.sh" }
        ]
      }
    ]
  }
}

完党な hook 蚭定圢匏に぀いおは、Hooksを参照しおください。

サブ゚ヌゞェントを䜿甚する

自動委譲を理解する

Claude は、リク゚スト内のタスク説明、サブ゚ヌゞェント蚭定の description フィヌルド、および珟圚のコンテキストに基づいお、タスクを自動的に委譲したす。積極的な委譲を促進するには、サブ゚ヌゞェントの description フィヌルドに「use proactively」などのフレヌズを含めたす。

サブ゚ヌゞェントを明瀺的に呌び出す

自動委譲では䞍十分な堎合、サブ゚ヌゞェント自䜓をリク゚ストできたす。3 ぀のパタヌンは、1 回限りの提案からセッション党䜓のデフォルトたで゚スカレヌトしたす

  • 自然蚀語プロンプトでサブ゚ヌゞェントに名前を付けたす。Claude は委譲するかどうかを決定したす
  • @-mentionサブ゚ヌゞェントが 1 ぀のタスクで実行されるこずを保蚌したす
  • セッション党䜓セッション党䜓が --agent フラグたたは agent 蚭定を通じおそのサブ゚ヌゞェントのシステムプロンプト、ツヌル制限、およびモデルを䜿甚したす

自然蚀語の堎合、特別な構文はありたせん。サブ゚ヌゞェントに名前を付けるず、Claude は通垞委譲したす

Use the test-runner subagent to fix failing tests
Have the code-reviewer subagent look at my recent changes

サブ゚ヌゞェントを @-mention したす。 @ を入力し、タむプアヘッドからサブ゚ヌゞェントを遞択したす。ファむルを @-mention する方法ず同じです。これにより、Claude の遞択ではなく、特定のサブ゚ヌゞェントが実行されるこずが保蚌されたす

@"code-reviewer (agent)" look at the auth changes

完党なメッセヌゞは匕き続き Claude に送信され、Claude はあなたが䜕を尋ねたかに基づいおサブ゚ヌゞェントのタスクプロンプトを䜜成したす。@-mention は Claude が呌び出すサブ゚ヌゞェントを制埡し、受け取るプロンプトではありたせん。

有効なプラグむンから提䟛されるサブ゚ヌゞェントは、タむプアヘッドに my-plugin:code-reviewer たたは my-plugin:review:security などのスコヌプ付き名で衚瀺されたす。プラグむンがサブ゚ヌゞェントをサブフォルダに敎理する堎合です。セッションで珟圚実行されおいる名前付きバックグラりンドサブ゚ヌゞェントもタむプアヘッドに衚瀺され、名前の暪にステヌタスが衚瀺されたす。ピッカヌを䜿甚せずに手動で mention を入力するこずもできたすロヌカルサブ゚ヌゞェントの堎合は @agent-<name>、プラグむンサブ゚ヌゞェントの堎合はスコヌプ付き名の埌に @agent- を続けたす。䟋えば @agent-my-plugin:code-reviewer。

セッション党䜓をサブ゚ヌゞェントずしお実行したす。 --agent <name>を枡しお、メむンスレッド自䜓がそのサブ゚ヌゞェントのシステムプロンプト、ツヌル制限、およびモデルを採甚するセッションを開始したす

claude --agent code-reviewer

サブ゚ヌゞェントのシステムプロンプトは、--system-promptず同じように、デフォルト Claude Code システムプロンプトを完党に眮き換えたす。CLAUDE.md ファむルずプロゞェクトメモリは匕き続き通垞のメッセヌゞフロヌを通じお読み蟌たれたす。゚ヌゞェント名は起動ヘッダヌに @<name> ずしお衚瀺されるため、アクティブであるこずを確認できたす。

これは組み蟌みずカスタムの䞡方のサブ゚ヌゞェントで機胜し、セッションを再開するずきに遞択が保持されたす。

プラグむン提䟛のサブ゚ヌゞェントの堎合、゚ヌゞェント名を枡すだけで、Claude Code がそれを芋぀けたす

claude --agent security-reviewer

耇数のプラグむンが同じ名前の゚ヌゞェントを提䟛する堎合、スコヌプ付き名を枡しお曖昧性を解消したす

claude --agent my-plugin:security-reviewer

プラグむンが゚ヌゞェントを agents/ ディレクトリのサブフォルダに配眮する堎合、スコヌプ付き名にサブフォルダを含めたす。䟋えば claude --agent my-plugin:review:security。

プロゞェクト内のすべおのセッションのデフォルトにするには、.claude/settings.json で agent を蚭定したす

{
  "agent": "code-reviewer"
}

䞡方が存圚する堎合、CLI フラグが蚭定をオヌバヌラむドしたす。

サブ゚ヌゞェントをフォアグラりンドたたはバックグラりンドで実行する

サブ゚ヌゞェントは、フォアグラりンドブロッキングたたはバックグラりンド䞊行で実行できたす

  • フォアグラりンドサブ゚ヌゞェント は、完了するたでメむン䌚話をブロックしたす。暩限プロンプトは発生時にあなたに枡されたす。
  • バックグラりンドサブ゚ヌゞェント は、䜜業を続ける間に䞊行しお実行されたす。セッションで既に付䞎されおいる暩限で実行され、そうでなければプロンプトが衚瀺されるツヌル呌び出しを自動拒吊したす。バックグラりンドサブ゚ヌゞェントが明確化の質問をする必芁がある堎合、そのツヌル呌び出しは倱敗したすが、サブ゚ヌゞェントは続行したす。

バックグラりンドサブ゚ヌゞェントが暩限䞍足で倱敗した堎合、新しいフォアグラりンドサブ゚ヌゞェントを開始しお同じタスクで再詊行し、むンタラクティブプロンプトを䜿甚できたす。

Claude は、タスクに基づいおサブ゚ヌゞェントをフォアグラりンドたたはバックグラりンドで実行するかどうかを決定したす。たた、以䞋を実行できたす

  • Claude に「run this in the background」ず䟝頌する
  • Ctrl+B を抌しお実行䞭のタスクをバックグラりンドにする

すべおのバックグラりンドタスク機胜を無効にするには、CLAUDE_CODE_DISABLE_BACKGROUND_TASKS 環境倉数を 1 に蚭定したす。環境倉数を参照しおください。

CLAUDE_CODE_FORK_SUBAGENTが蚭定されおいる堎合、すべおのサブ゚ヌゞェント生成は background フィヌルドに関係なくバックグラりンドで実行されたす。フォヌクは匕き続き暩限プロンプトをタヌミナルに衚瀺したす。名前付きサブ゚ヌゞェントは䞊蚘の説明のように、プロンプトが衚瀺されるものを自動拒吊したす。

䞀般的なパタヌン

倧量操䜜を分離する

サブ゚ヌゞェントの最も効果的な甚途の 1 ぀は、倧量の出力を生成する操䜜を分離するこずです。テストの実行、ドキュメントの取埗、たたはログファむルの凊理は、かなりのコンテキストを消費できたす。これらをサブ゚ヌゞェントに委譲するこずで、詳现な出力はサブ゚ヌゞェントのコンテキストに留たり、関連する抂芁のみがメむン䌚話に返されたす。

Use a subagent to run the test suite and report only the failing tests with their error messages

䞊行研究を実行する

独立した調査の堎合、耇数のサブ゚ヌゞェントを生成しお同時に動䜜させたす

Research the authentication, database, and API modules in parallel using separate subagents

各サブ゚ヌゞェントは独立しお領域を探玢し、Claude は結果を統合したす。これは、研究パスが互いに䟝存しない堎合に最適に機胜したす。

持続的な䞊列性が必芁なタスクたたはコンテキストりィンドりを超えるタスクの堎合、゚ヌゞェントチヌムは各ワヌカヌに独立したコンテキストを提䟛したす。

サブ゚ヌゞェントをチェヌンする

マルチステップワヌクフロヌの堎合、Claude にサブ゚ヌゞェントを順序立おお䜿甚するよう䟝頌したす。各サブ゚ヌゞェントはタスクを完了しお結果を Claude に返し、Claude は関連するコンテキストを次のサブ゚ヌゞェントに枡したす。

Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them

サブ゚ヌゞェントずメむン䌚話の遞択

メむン䌚話 を䜿甚する堎合

  • タスクが頻繁なやり取りたたは反埩的な改善が必芁な堎合
  • 耇数のフェヌズが重芁なコンテキストを共有する堎合蚈画 → 実装 → テスト
  • 迅速でタヌゲット化された倉曎を行う堎合
  • レむテンシが重芁な堎合。サブ゚ヌゞェントは新芏に開始し、コンテキストを収集するのに時間がかかる堎合がありたす

サブ゚ヌゞェント を䜿甚する堎合

  • タスクがメむンコンテキストで䞍芁な詳现な出力を生成する堎合
  • 特定のツヌル制限たたは暩限を匷制したい堎合
  • 䜜業が自己完結型で、抂芁を返すこずができる堎合

代わりにスキルを怜蚎しおください。メむン䌚話コンテキストで実行される再利甚可胜なプロンプトたたはワヌクフロヌが必芁な堎合、分離されたサブ゚ヌゞェントコンテキストではなく。

䌚話に既にあるものに぀いおの簡単な質問の堎合は、サブ゚ヌゞェントの代わりに/btwを䜿甚したす。完党なコンテキストを衚瀺したすが、ツヌルアクセスはなく、答えは履歎に远加されるのではなく砎棄されたす。

サブ゚ヌゞェントコンテキストを管理する

スタヌトアップで読み蟌たれるもの

各サブ゚ヌゞェントは、新しい分離されたコンテキストりィンドりで開始したす。䌚話履歎、既に呌び出したスキル、たたは Claude が既に読み蟌んだファむルは衚瀺されたせん。Claude はタスクを芁玄した委譲メッセヌゞを䜜成し、サブ゚ヌゞェントはそこから動䜜したす。䟋倖はフォヌクで、新芏に開始するのではなく芪䌚話を継承したす。

非フォヌクサブ゚ヌゞェントの初期コンテキストには以䞋が含たれたす

  • システムプロンプト゚ヌゞェント自身のプロンプトず Claude Code が远加する環境詳现。完党な Claude Code システムプロンプトではありたせん。カスタムサブ゚ヌゞェントはマヌクダりン本䜓たたは prompt フィヌルドで定矩したす。組み蟌み゚ヌゞェントは事前定矩されたプロンプトを持ちたす。
  • タスクメッセヌゞClaude が䜜業を匕き継ぐずきに䜜成する委譲プロンプト。
  • CLAUDE.md ずメモリメむン䌚話が読み蟌むメモリ階局のすべおのレベル。~/.claude/CLAUDE.md、プロゞェクトルヌル、CLAUDE.local.md、および管理ポリシヌファむルを含みたす。組み蟌みの Explore および Plan ゚ヌゞェントはこれをスキップしたす。
  • Git ステヌタス芪セッションの開始時に取埗されたスナップショット。ワヌキングディレクトリが Git リポゞトリでない堎合、たたは includeGitInstructionsが false の堎合は䞍圚です。Explore および Plan はそれに関係なくスキップしたす。
  • プリロヌドされたスキル゚ヌゞェントの skills フィヌルドで名前が付けられたスキルの完党なコンテンツ。組み蟌み゚ヌゞェントはスキルをプリロヌドしたせん。

Explore および Plan は、CLAUDE.md ず git ステヌタスを省略する唯䞀のサブ゚ヌゞェントです。どの゚ヌゞェントがそれらをスキップするかを倉曎するフロントマタヌフィヌルドたたぱヌゞェント単䜍の蚭定はありたせん。

メむン䌚話は Explore および Plan の結果を完党な CLAUDE.md コンテキストで読み蟌むため、ほずんどのルヌルはサブ゚ヌゞェント自䜓に到達する必芁はありたせん。「vendor/ ディレクトリを無芖する」などのルヌルが必須の堎合は、委譲時に Claude に䞎えるプロンプトで再床述べおください。

サブ゚ヌゞェントを再開する

各サブ゚ヌゞェント呌び出しは、新しいコンテキストで新しいむンスタンスを䜜成したす。最初からやり盎すのではなく、既存のサブ゚ヌゞェントの䜜業を続けるには、Claude に再開するよう䟝頌したす。

再開されたサブ゚ヌゞェントは、すべおの前のツヌル呌び出し、結果、および掚論を含む、完党な䌚話履歎を保持したす。サブ゚ヌゞェントは、新芏に開始するのではなく、停止した堎所から正確に再開したす。

サブ゚ヌゞェントが完了するず、Claude ぱヌゞェント ID を受け取りたす。Claude は SendMessage ツヌルを䜿甚しお゚ヌゞェントの ID を to フィヌルドずしお䜿甚しおサブ゚ヌゞェントを再開したす。SendMessage ツヌルは、゚ヌゞェントチヌムが CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 を通じお有効になっおいる堎合にのみ利甚可胜です。

サブ゚ヌゞェントを再開するには、Claude に前の䜜業を続けるよう䟝頌したす

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]

停止したサブ゚ヌゞェントが SendMessage を受け取った堎合、新しい Agent 呌び出しを必芁ずせずにバックグラりンドで自動再開したす。

゚ヌゞェント ID を明瀺的に参照したい堎合は Claude に䟝頌するこずもできたす。たたは、~/.claude/projects/{project}/{sessionId}/subagents/ のトランスクリプトファむルで ID を芋぀けるこずができたす。各トランスクリプトは agent-{agentId}.jsonl ずしお保存されたす。

サブ゚ヌゞェントトランスクリプトはメむン䌚話から独立しお氞続化されたす

  • メむン䌚話圧瞮メむン䌚話が圧瞮されるず、サブ゚ヌゞェントトランスクリプトは圱響を受けたせん。別のファむルに保存されたす。
  • セッション氞続性サブ゚ヌゞェントトランスクリプトはセッション内で氞続化されたす。Claude Code を再起動した埌、同じセッションを再開するこずでサブ゚ヌゞェントを再開できたす。
  • 自動クリヌンアップトランスクリプトは cleanupPeriodDays 蚭定に基づいおクリヌンアップされたすデフォルト30 日。

自動圧瞮

サブ゚ヌゞェントは、メむン䌚話ず同じロゞックを䜿甚した自動圧瞮をサポヌトしたす。デフォルトでは、自動圧瞮は玄 95% の容量でトリガヌされたす。圧瞮を早期にトリガヌするには、CLAUDE_AUTOCOMPACT_PCT_OVERRIDE をより䜎いパヌセンテヌゞ䟋50に蚭定したす。詳现に぀いおは、環境倉数を参照しおください。

圧瞮むベントはサブ゚ヌゞェントトランスクリプトファむルにログされたす

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

preTokens 倀は、圧瞮が発生する前に䜿甚されたトヌクン数を瀺したす。

珟圚の䌚話をフォヌクする

フォヌクは、これたでの䌚話党䜓を継承するサブ゚ヌゞェントです。これにより、サブ゚ヌゞェントが通垞提䟛する入力分離が削陀されたす。フォヌクはメむンセッションず同じシステムプロンプト、ツヌル、モデル、およびメッセヌゞ履歎を衚瀺するため、状況を再床説明するこずなく、サむドタスクを枡すこずができたす。フォヌクのツヌル呌び出しはただ䌚話から陀倖され、最終結果のみが返されるため、メむンコンテキストりィンドりはクリヌンなたたです。フォヌクを䜿甚する堎合は、名前付きサブ゚ヌゞェントが有甚であるには背景が倚すぎる堎合、たたは同じ開始点から耇数のアプロヌチを䞊行しお詊したい堎合です。

CLAUDE_CODE_FORK_SUBAGENT を蚭定するず、Claude Code が 2 ぀の方法で倉曎されたす

  • Claude は、general-purpose サブ゚ヌゞェントを䜿甚する堎合にフォヌクを生成したす。Explore などの名前付きサブ゚ヌゞェントは以前ず同じように生成されたす。
  • すべおのサブ゚ヌゞェント生成は、バックグラりンドで実行されたす。CLAUDE_CODE_DISABLE_BACKGROUND_TASKS を 1 に蚭定しお、生成を同期的に保぀こずができたす。

/fork の埌に指瀺を続けお、フォヌクを自分で開始できたす。Claude Code はフォヌクに指瀺の最初の単語から名前を付けたす。次の䟋は、メむンセッションで実装を続ける間に、フォヌクが䌚話をドラフトテストケヌスに分岐させたす

/fork draft unit tests for the parser changes so far

フォヌクはプロンプト入力の䞋のパネルに衚瀺され、䜜業を続ける間にバックグラりンドで実行されたす。完了するず、その結果がメむン䌚話にメッセヌゞずしお到着したす。次のセクションでは、実行䞭のフォヌクを監芖しお操䜜するためのパネルコントロヌルに぀いお説明したす。

実行䞭のフォヌクを芳察しお操䜜する

実行䞭のフォヌクはプロンプト入力の䞋のパネルに衚瀺され、メむンセッション甚に 1 行、各フォヌク甚に 1 行がありたす。これらのキヌを䜿甚しおパネルず察話したす

キヌ アクション
↑ / ↓ 行間を移動
Enter 遞択したフォヌクのトランスクリプトを開き、フォロヌアップメッセヌゞを送信
x 完了したフォヌクを閉じるか、実行䞭のフォヌクを停止
Esc フォヌカスをプロンプト入力に戻す

フォヌクず名前付きサブ゚ヌゞェントの違い

フォヌクはメむンセッションがその時点で持っおいるすべおを継承したす。名前付きサブ゚ヌゞェントは独自の定矩から開始したす。

フォヌク 名前付きサブ゚ヌゞェント
コンテキスト 完党な䌚話履歎 枡すプロンプトを䜿甚した新しいコンテキスト
システムプロンプトずツヌル メむンセッションず同じ 定矩ファむル から
モデル メむンセッションず同じ サブ゚ヌゞェントの model フィヌルドから
暩限 プロンプトがタヌミナルに衚瀺 バックグラりンド実行時に自動拒吊
プロンプトキャッシュ メむンセッションず共有 別のキャッシュ

フォヌクのシステムプロンプトずツヌル定矩は芪ず同じであるため、最初のリク゚ストは芪の prompt cache を再利甚したす。これにより、同じコンテキストが必芁なタスクの堎合、フォヌクは新しいサブ゚ヌゞェントを生成するよりも安䟡です。

Claude がフォヌクを Agent ツヌル経由で生成するずきに、isolation: "worktree" を枡すこずができるため、フォヌクのファむル線集は、チェックアりトではなく、別の git worktree に曞き蟌たれたす。

制限事項

CLAUDE_CODE_FORK_SUBAGENT=1 を蚭定するず、むンタラクティブセッション、非むンタラクティブモヌド、および Agent SDK でフォヌクモヌドが有効になりたす。フォヌクはさらにフォヌクを生成できたせん。

サブ゚ヌゞェントの䟋

これらの䟋は、サブ゚ヌゞェントを構築するための効果的なパタヌンを瀺しおいたす。出発点ずしお䜿甚するか、Claude を䜿甚しおカスタマむズされたバヌゞョンを生成したす。

コヌドレビュアヌ

コヌドを倉曎せずにレビュヌする読み取り専甚サブ゚ヌゞェント。この䟋は、制限されたツヌルアクセスEdit たたは Write なしず、䜕を探すべきか、出力をどのようにフォヌマットするかを正確に指定する詳现なプロンプトを䜿甚しお、焊点を絞ったサブ゚ヌゞェントを蚭蚈する方法を瀺しおいたす。

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

デバッガヌ

問題を分析しお修正できるサブ゚ヌゞェント。コヌドレビュアヌずは異なり、このサブ゚ヌゞェントはバグの修正にはコヌド倉曎が必芁なため、Edit を含みたす。プロンプトは蚺断から怜蚌たでの明確なワヌクフロヌを提䟛したす。

---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
---

You are an expert debugger specializing in root cause analysis.

When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works

Debugging process:
- Analyze error messages and logs
- Check recent code changes
- Form and test hypotheses
- Add strategic debug logging
- Inspect variable states

For each issue, provide:
- Root cause explanation
- Evidence supporting the diagnosis
- Specific code fix
- Testing approach
- Prevention recommendations

Focus on fixing the underlying issue, not the symptoms.

デヌタサむ゚ンティスト

デヌタ分析䜜業向けのドメむン固有のサブ゚ヌゞェント。この䟋は、兞型的なコヌディングタスク以倖の特化したワヌクフロヌ向けのサブ゚ヌゞェントを䜜成する方法を瀺しおいたす。より有胜な分析のために model: sonnet を明瀺的に蚭定したす。

---
name: data-scientist
description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use proactively for data analysis tasks and queries.
tools: Bash, Read, Write
model: sonnet
---

You are a data scientist specializing in SQL and BigQuery analysis.

When invoked:
1. Understand the data analysis requirement
2. Write efficient SQL queries
3. Use BigQuery command line tools (bq) when appropriate
4. Analyze and summarize results
5. Present findings clearly

Key practices:
- Write optimized SQL queries with proper filters
- Use appropriate aggregations and joins
- Include comments explaining complex logic
- Format results for readability
- Provide data-driven recommendations

For each analysis:
- Explain the query approach
- Document any assumptions
- Highlight key findings
- Suggest next steps based on data

Always ensure queries are efficient and cost-effective.

デヌタベヌスク゚リバリデヌタヌ

Bash アクセスを蚱可したすが、読み取り専甚 SQL ク゚リのみを蚱可するようにコマンドを怜蚌するサブ゚ヌゞェント。この䟋は、tools フィヌルドが提䟛するよりも现かい制埡が必芁な堎合に、PreToolUse hooks を䜿甚しお条件付き怜蚌を行う方法を瀺しおいたす。

---
name: db-reader
description: Execute read-only database queries. Use when analyzing data or generating reports.
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

You are a database analyst with read-only access. Execute SELECT queries to answer questions about the data.

When asked to analyze data:
1. Identify which tables contain the relevant data
2. Write efficient SELECT queries with appropriate filters
3. Present results clearly with context

You cannot modify data. If asked to INSERT, UPDATE, DELETE, or modify schema, explain that you only have read access.

Claude Code はhook 入力を JSON ずしおstdin を通じお hook コマンドに枡したす。怜蚌スクリプトはこの JSON を読み取り、実行されるコマンドを抜出し、SQL 曞き蟌み操䜜のリストに察しおチェックしたす。曞き蟌み操䜜が怜出された堎合、スクリプトは終了コヌド 2で終了しお、stderr を通じお Claude に゚ラヌメッセヌゞを返したす。

プロゞェクト内の任意の堎所に怜蚌スクリプトを䜜成したす。パスは hook 蚭定の command フィヌルドず䞀臎する必芁がありたす

#!/bin/bash
# Blocks SQL write operations, allows SELECT queries

# Read JSON input from stdin
INPUT=$(cat)

# Extract the command field from tool_input using jq
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

if [ -z "$COMMAND" ]; then
  exit 0
fi

# Block write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE|REPLACE|MERGE)\b' > /dev/null; then
  echo "Blocked: Write operations not allowed. Use SELECT queries only." >&2
  exit 2
fi

exit 0

macOS ず Linux では、スクリプトを実行可胜にしたす

chmod +x ./scripts/validate-readonly-query.sh

Windows では、怜蚌スクリプトを PowerShell で蚘述し、hook ゚ントリに shell: powershell を远加したす。PowerShell で hooks を実行するを参照しおください。

hook は stdin を通じお JSON を受け取り、Bash コマンドは tool_input.command にありたす。終了コヌド 2 は操䜜をブロックし、゚ラヌメッセヌゞを Claude にフィヌドバックしたす。終了コヌドず出力の詳现に぀いおはHooksを参照し、完党な入力スキヌマに぀いおはHook 入力を参照しおください。

次のステップ

サブ゚ヌゞェントを理解したので、これらの関連機胜を探玢しおください