Subagents (サブエージェント)

各サブエージェントは独自のコンテキストウィンドウで動き、独自のシステムプロンプト、使えるツールの範囲、独立した権限を持ちます。Claude はサブエージェントの説明に合うタスクに出会うと、そのサブエージェントに作業を委任します。サブエージェントは作業を終えると、要約だけをメインの会話に返します。

Claude Code には、Claude が適切な場面で自動的に使う組み込みのサブエージェントがあります。そのひとつの Explore は、コードベースの検索と分析に特化した、高速な読み取り専用のエージェントです。

独自のサブエージェント (custom agents) は、YAML frontmatter を持つ Markdown ファイルとして定義します。frontmatter で必須の項目は name と description だけです。ディスク上のサブエージェントファイルを追加・編集すると、Claude Code は数秒以内に変更を検出し、再起動なしで次の委任から新しい定義を使います。

同じ名前のサブエージェントが複数あるときは、優先度の高い保存場所のものが使われます。--agents で CLI から渡したサブエージェントはそのセッションの間だけ存在し、ディスクには保存されません。

frontmatter では、次のような項目を指定できます。

• model: サブエージェントが使うモデルを指定します。
• tools / disallowedTools: 使えるツールを、許可リスト (tools) または拒否リスト (disallowedTools) で制限します。
• MCP サーバーのインライン定義: .mcp.json ではなくサブエージェント内で定義すると、その MCP サーバーはメインの会話に入らず、ツールの説明がメインの会話のコンテキストを消費しません。
• skills: 起動時にスキルの内容をサブエージェントのコンテキストへ注入します。
• memory: 会話をまたいで残る永続ディレクトリをサブエージェントに与えます。
• hooks: frontmatter に定義した hooks は、そのサブエージェントが動作している間だけ実行され、終了時に片付けられます。
• omitClaudeMd: カスタムやプラグインのサブエージェントを、user・project・local の CLAUDE.md なしで実行します (--agents の JSON でも指定できます)。
• autoCompactWindow: サブエージェントは自動コンパクトに対応しており、この項目でメインの会話より早い時点で自動コンパクトさせられます。

Claude は、サブエージェントの description に合うタスクに出会うと、そのサブエージェントに委任します。積極的な委任を促すには、description に「use proactively」のような語句を含めます。Claude に選択を任せず特定のサブエージェントを動かしたいときは、@メンションします。@メンションの入力候補には名前付きサブエージェントが表示されます。プロジェクトのすべてのセッションで既定のエージェントにするには、.claude/settings.json で agent を設定します。

フォアグラウンドのサブエージェントは、完了までメインの会話をブロックし、権限確認はその都度ユーザーに渡されます。バックグラウンドのサブエージェントは、ユーザーが作業を続けている間に並行して動きます。先に結果が必要なときは、「run the reviewer subagent and wait for its report」のように、待つよう Claude に依頼します。

fork は、白紙から始めるのではなく、それまでの会話全体を引き継ぐサブエージェントです。fork mode の有効・無効に関係なく、/subtask の後にタスクを書いて自分で fork を開始できます。fork はプロンプトの下のパネルに表示され、作業を続けている間バックグラウンドで動きます。fork mode を無効にするには、settings.json などで CLAUDE_CODE_FORK_SUBAGENT を 0 に設定します。

再開したサブエージェントは、以前のツール呼び出し・結果・推論を含む会話履歴をすべて保持しています。再開するには、以前の作業の続きを Claude に依頼します。

• サブエージェントは、既定で親セッションの権限モードを継承します。
• バックグラウンドのサブエージェントの権限確認は、自動で拒否されず、メインセッションに表示されます。
• auto モードでは、サブエージェントの起動前に分類器が評価します。
• 特定のサブエージェントを無効にするには、settings の deny 配列に Agent(subagent-name) の形式で項目を追加します。subagent-name はサブエージェントの name フィールドと一致させます。
• Claude Code は、各サブエージェントの最終報告を Claude が読む前にスキャンします。
• 既定では、サブエージェントはメインの会話から 3 階層下まで、自分のサブエージェントを起動できます。変更するには、CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH に必要な階層数を設定します。
• 同時に実行できるサブエージェントの数は既定で 20 で、CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS で変更できます。
• CLAUDE_CODE_SUBAGENT_EFFORT で、ほかに指定がないときにサブエージェントが使う effort レベルを、セッションの設定を継承する代わりに設定できます。
• サブエージェントからの API リクエストには、x-claude-code-agent-id / x-claude-code-parent-agent-id ヘッダーが付きます。

最初のサブエージェントを作成して使う流れは次のとおりです。

1. Claude Code で、作りたいサブエージェントの内容と保存先 (例: ~/.claude/agents/) を Claude に伝えます。
2. 作成されたファイル (例: ~/.claude/agents/code-improver.md) を開き、frontmatter が依頼どおりになっているか確認します。
3. 新しいサブエージェントへの委任を Claude に依頼します。例: 「Use the code-improver agent to suggest improvements in this project」。