カスタムサブエージェントの作成

• コンテキストを保持する ことで、探索と実装をメインの会話から分離します
• 制約を強制する ことで、サブエージェントが使用できるツールを制限します
• 設定を再利用する ことで、ユーザーレベルのサブエージェントをプロジェクト全体で再利用します
• 動作を特化させる ことで、特定のドメイン向けの焦点を絞ったシステムプロンプトを使用します
• コストを制御する ことで、Haiku のような高速で安価なモデルにタスクをルーティングします

​

組み込みサブエージェント

• 特定の組み込みタイプをブロックするには、特定のサブエージェントを無効にするに示されているように、permissions.denyに追加します。
• Claude がサブエージェントに委譲するのを防ぐには、permissions.denyでAgentツール自体を拒否します。
• 組み込みのExploreおよびPlanサブエージェントのみを削除するには、CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1を設定します。Claude はファイルを直接読み取り、探索し、サブエージェントに委譲しません。Claude Code v2.1.198 以降が必要です。
• 非インタラクティブモードおよびAgent SDKでは、CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1を設定して、すべての組み込みタイプを削除し、独自のタイプのみを提供します。

​

クイックスタート：最初のサブエージェントを作成する

Create a personal code-improver subagent in ~/.claude/agents/ 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. Make it read-only and have it use Sonnet.

---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---

You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.

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

​

サブエージェントを設定する

​

サブエージェントのスコープを選択する

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

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

• prompt: エージェントのシステムプロンプトです。ファイルベースのサブエージェントにおける markdown 本文に相当します。prompt は空でもかまいません。prompt が空で memory フィールドのないエージェントを --agent でセッションのエージェントとして選択した場合、セッションのシステムプロンプトは変更されません。空の prompt には Claude Code v2.1.281 以降が必要です。
• フロントマターフィールド: description、tools、disallowedTools、model、permissionMode、mcpServers、hooks、maxTurns、autoCompactWindow、skills、initialPrompt、memory、effort、background、omitClaudeMd、isolation。
• 無視されるフィールド: color と experimental はここでは受け付けられず、拒否されるのではなく無視されます。

​

サブエージェントファイルを作成する

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

• git をメインのチェックアウトにリダイレクトするコマンドをブロックします。
• コマンドが実行する git が worktree 内にとどまることをコマンドテキストから検証できない場合（たとえば、コマンド名が実行時に算出される場合）、そのコマンドを拒否します。

​

フロントマターリファレンス

• 読み込まれたサブエージェント内のスペルミスのあるフィールドを見つけるには、シェルで claude --debug を実行し、~/.claude/debug/<session-id>.txt にあるデバッグログで does not recognize or apply を検索します。デバッグログには、サブエージェントのファイル内で Claude Code が認識しないトップレベルフィールドが最大 5 つ示され、サポートされているフィールドに近い場合は意図されたと思われる名前も示されます。Claude Code v2.1.296 以降が必要です。
• サブエージェントファイルが読み込まれなかった理由を調べるには、Claude Code がスキップするサブエージェントファイルを参照してください。

---
name: repo-auditor
description: Audits a large repository and reports what it finds
experimental:
  cacheTtl: 1h
---

​

Claude Code がスキップするサブエージェントファイル

• name がない: Claude Code はそのファイルを、エージェントと並べて置かれたドキュメントとして扱います。
• 開始の --- がファイルの 1 行目にない: Claude Code はそのファイルをフロントマターのないものとして読み取り、ドキュメントとして扱います。
• name が - で始まる、: を含む、または 256 文字を超える: Claude Code はそのファイルをスキップし、デバッグログにエラーを書き込みます。
• name はあるが description がない: Claude Code はそのファイルをスキップし、デバッグログに理由を書き込みます。
• YAML を解析できない: Claude Code はそのファイルからフィールドを一切読み取らずにスキップし、デバッグログに解析エラーを書き込みます。

セッション前に agents ディレクトリをチェックする

​

モデルを選択する

• モデルエイリアス: 利用可能なエイリアスのいずれかを使用します: sonnet、opus、haiku、または fable
• 完全なモデル ID: claude-opus-5-5 や claude-sonnet-5 などの完全なモデル ID を使用します。--model フラグと同じ値を受け付けます
• inherit: メインの会話と同じモデルを使用します

1. 呼び出しごとの model パラメータ
2. サブエージェント定義の model フロントマター（inherit はメインの会話のモデルを選択します）
3. CLAUDE_CODE_SUBAGENT_MODEL 環境変数（モデルエイリアスまたはモデル ID に設定した場合）
4. メインの会話のモデル

• メインの会話のモデルがそのファミリーに属している場合: サブエージェントは [1m] サフィックスを含め、メインの会話とまったく同じモデルで実行されるため、メインの会話と同じ拡張コンテキストウィンドウを得られます。
• Anthropic API 以外のプロバイダーで、Claude Code がメインの会話のモデルファミリーを判別できない場合: これは、Amazon Bedrock で Claude Code が基盤モデルに解決していないアプリケーション推論プロファイル ARN を使用している場合に発生することがあります。このケースは opus エイリアスのみが対象で、ANTHROPIC_DEFAULT_OPUS_MODEL を設定している場合は適用されません。その場合、opus は設定したモデルに解決されるためです。

• ブロックされた値が opus などのファミリーエイリアスである場合、Claude Code は /model と同じ代替ルールとプロバイダーの範囲に従い、許可リストで許可されているそのファミリーの最新バージョンでサブエージェントを実行します。v2.1.222 より前は、ブロックされたファミリーエイリアスについても、Claude Code は継承されたモデルでサブエージェントを実行していました。
• その他のブロックされた値の場合、その代替が機能しないプロバイダーの場合、または許可リストでそのファミリーのどのバージョンも許可されていない場合、Claude Code は代わりに継承されたモデルでサブエージェントを実行します。CLAUDE_CODE_SUBAGENT_MODEL を設定している場合、Claude Code はこれらと同じルールの下でまずそのモデルを試します。

​

すべてのサブエージェントを 1 つのモデルで実行する

• 両方の変数を設定した場合、サブエージェントは CLAUDE_CODE_SUBAGENT_MODEL のモデルで実行されます。
• CLAUDE_CODE_SUBAGENT_MODEL_FORCE のみを設定した場合、サブエージェントはメインの会話のモデルで実行されます。ただし、組み込みの Explore サブエージェントは、組み込みサブエージェントに記載されているモデルで実行されます。

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  }
}

• フォーク
• model: inherit を指定したサブエージェントで実行されるスキル

​

effort レベルを選択する

​

サブエージェントに effort フィールドもパラメータもない場合

​

サブエージェントの機能を制御する

​

利用可能なツール

• Agent（サブエージェントが深さの上限に達している場合）。フォークではツールは一覧に残りますが、生成する代わりにエラーを返します
• AskUserQuestion
• EndConversation（メインの会話のみを終了できます。EndConversation ツールの動作を参照してください）
• EnterPlanMode
• ExitPlanMode（ただし、サブエージェントの permissionMode が plan の場合は削除されません）
• ScheduleWakeup
• WaitForMcpServers
• Workflow

​

サブエージェントが使用できるツールを制限する

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

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

名前に二重アンダースコアを含む MCP サーバー

• tools の場合: mcp__ に続けてサーバーの完全な名前と __* を記述します（例: mcp__reports__v2__*）。末尾の __* がないと、mcp__reports__v2 はそのサーバーのどのツールにも一致しません。
• disallowedTools の場合: reports という名前のサーバーを除外するエントリである mcp__reports または mcp__reports__* を探します。いずれかのエントリがあると、サブエージェントは reports__v2 のすべてのツールも失います。これらのツール名も mcp__reports__ で始まるためです。reports サーバーのツールのみを除外するには、代わりに mcp__reports__run_query のように 1 つずつ列挙します。

​

生成できるサブエージェントを制限する

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

tools: Agent, Read, Bash

​

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.

• --strict-mcp-config と --bare
• エンタープライズ管理 MCP 設定
• allowedMcpServers および deniedMcpServers ポリシー

​

インライン MCP サーバーに必要な信頼

• 信頼として扱われないもの: 親フォルダの信頼、および -p セッションや SDK セッションが設定ファイル内のフックのために得る自動的な信頼
• 信頼するまで: Claude Code はそのエージェントファイル内のすべてのインラインサーバーをスキップし、~/.claude.json 用の正確な projects["<path>"].hasTrustDialogAccepted キーをデバッグログに書き込みます
• --add-dir ディレクトリ: 信頼済みワークスペースのリポジトリ外にあるディレクトリには、独自の信頼エントリが必要です。その .claude/agents/ ファイルはワークスペースの信頼を継承しないためです

• 設定済みのサーバーを参照する名前
• ~/.claude/agents/ のエージェントファイル、--agents または SDK の agents オプションで渡したエージェントファイル、あるいは管理設定が提供するエージェントファイル内のインラインサーバー

​

権限モード

• メインの会話が bypassPermissions、acceptEdits、または auto モードの場合、サブエージェントはそれと同じモードで実行され、Claude Code は設定した permissionMode を無視します。auto モードでは、分類器がメインの会話のブロックルールと許可ルールを使用してサブエージェントのツール呼び出しを評価します。サブエージェントが終了すると、auto モードでのサブエージェントの扱いで説明されているとおり、分類器は最終レポートが配信される前に、サブエージェントの作業と最終レポートもレビューします。 メインの会話が bypassPermissions の状態でサブエージェントが権限を求める場合は、そのツール呼び出しがどのモードでも自動承認されない操作のいずれかに該当するかどうかを確認してください。
• メインの会話が plan モードの場合、サブエージェントがエージェントチームのルールの下でエージェントチームのチームメイトとして実行される場合を除き、設定した permissionMode にかかわらずサブエージェントは plan モードのままになります。dontAsk を設定した場合、サブエージェントはプロンプトも表示しません。plan モードで承認を求めることになる操作は、代わりに拒否されます。
• メインの会話が default または dontAsk モードの場合、サブエージェントは設定した権限モードで実行されます。ただし、次の場合は代わりにメインの会話の権限モードを維持します。
  • bypassPermissions を設定した場合。bypassPermissions の例外には Claude Code v2.1.267 以降が必要です。
  • auto を設定したが、設定ファイルで disableAutoMode が設定されている場合や、サブエージェントのモデルが auto モードをサポートしていない場合など、サブエージェントで auto モードが利用できない場合。

​

サブエージェントにスキルをプリロードする

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

​

永続メモリを有効にする

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

• サブエージェントのシステムプロンプトに、メモリディレクトリの読み書きに関する指示が含まれます。
• サブエージェントのシステムプロンプトには、メモリディレクトリ内の MEMORY.md の最初の 200 行または 25KB のいずれか先に達したほうも含まれ、その上限を超えた場合に MEMORY.md を整理するよう指示されます。
• サブエージェントがメモリファイルを管理できるように、Read、Write、Edit ツールが自動的に有効になります。

永続メモリのヒント

• project が推奨されるデフォルトのスコープです。サブエージェントの知識をバージョン管理を通じて共有できます。
• 作業を開始する前にメモリを参照するようサブエージェントに依頼します:「この PR をレビューして。以前に見たパターンがないかメモリを確認して。」
• タスクの完了後にメモリを更新するようサブエージェントに依頼します:「完了したら、学んだことをメモリに保存して。」時間が経つにつれて、サブエージェントをより効果的にするナレッジベースが構築されます。
• サブエージェントが自らのナレッジベースを積極的に維持するよう、サブエージェントの 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.
  

​

フックによる条件付きルール

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

#!/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

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

​

特定のサブエージェントを無効にする

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

claude --disallowedTools "Agent(Explore)"

​

サブエージェントのフックを定義する

• サブエージェントのフロントマター内: そのサブエージェントがアクティブな間のみ実行されるフックを定義します
• settings.json 内: サブエージェント内でも発火するセッション全体のフックを定義します。PreToolUse や PostToolUse などのツールイベントは、メインの会話と同じようにサブエージェントのツール呼び出しに対して発火し、SubagentStart と SubagentStop はサブエージェントの開始時または終了時に発火します

​

サブエージェントのフロントマター内のフック

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

​

サブエージェントイベント用のプロジェクトレベルのフック

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

​

サブエージェントを使う

​

自動委任を理解する

​

サブエージェントを明示的に呼び出す

• 自然言語: プロンプト内でサブエージェントの名前を挙げます。委任するかどうかは Claude が判断します
• @ メンション: 1 つのタスクについて、そのサブエージェントが確実に実行されます
• セッション全体: --agent フラグまたは agent 設定により、セッション全体がそのサブエージェントとして実行されます

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

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

claude --agent code-reviewer

claude --agent security-reviewer

claude --agent my-plugin:security-reviewer

{
  "agent": "code-reviewer"
}

​

サブエージェントをフォアグラウンドまたはバックグラウンドで実行する

• フォアグラウンドサブエージェントは、完了するまでメインの会話をブロックします。権限プロンプトは発生した時点でユーザーに渡されます。
• バックグラウンドサブエージェントは、ユーザーが作業を続けている間に並行して実行されます。バックグラウンドサブエージェントが権限を必要とするツール呼び出しに達すると、Claude Code はメインセッションにそのプロンプトを表示し、要求しているサブエージェントの名前を示します。承認するとサブエージェントは続行します。Esc を押すと、サブエージェントを停止することなく、その 1 つのツール呼び出しだけを拒否できます。

​

どのサブエージェントがバックグラウンドで実行されるか

• claude -p と Agent SDK: Claude は自身の判断で、またはユーザーが求めたときに、待機できます。
• ローカルマシン上のインタラクティブなターミナルセッション、VS Code、デスクトップアプリのセッション: Claude がサブエージェントを待機できるようにするには、デフォルトでオンになっているフォークモードをオフにします。

​

Claude にサブエージェントを待機させる

1. CLAUDE_CODE_FORK_SUBAGENT を 0 に設定して、フォークモードをオフにします。たとえば settings.json で次のように設定します。
   {
     "env": {
       "CLAUDE_CODE_FORK_SUBAGENT": "0"
     }
   }
   
2. シェルから claude を再度実行するか、VS Code で新しい会話を開きます。
3. 先に結果が必要な場合は、Claude に待機するよう依頼します。たとえば「run the reviewer subagent and wait for its report」のように依頼します。

​

バックグラウンドサブエージェントのツール、権限、結果

​

パネルとタスクリストにおける完了したサブエージェント

• サブエージェントが正常に終了すると、Claude Code はその行を直ちに削除し、スクリーンリーダーモードの場合を除き、フッターに /tasks to see subagents を 30 秒間表示します。この 30 秒の間に /tasks を実行し、サブエージェント上で Enter を押すと、そのトランスクリプトを開けます。v2.1.232 より前では、Claude Code は失敗したサブエージェントと同様に、終了後 30 秒間その行を保持し、フッターのヒントは表示していませんでした。
• サブエージェントが失敗した場合、またはユーザーが停止した場合、Claude Code はその行を 30 秒間保持します。もっと早く行を消去するには、行を選択して x を押します。

​

サブエージェント名

​

サブエージェントでの API エラー

• フォアグラウンド: すでにテキスト出力を生成していたサブエージェントがレート制限、過負荷、またはサーバーエラーによって途中で途切れた場合、Agent ツールはその部分的な出力を、サブエージェントが途中で途切れてタスクを完了しなかったという注記とともに返します。何も生成しなかったサブエージェント、または出力がツール呼び出しのみだったサブエージェントは、Agent terminated early due to an API error とそれに続くエラーの詳細で失敗します。
• バックグラウンド: サブエージェントは失敗としてマークされ、終了時に Claude が受け取るメッセージには API エラーの名前とサブエージェントの最後の出力が含まれるため、途中までの作業は失われません。

⚠ This agent switched to <model> because its earlier model could not be used.

​

サブエージェント出力のスキャン

• バックスラッシュの挿入: <system-reminder> タグや、Human: または Assistant: で始まる行など、Claude Code 自身の出力を模倣したテキストに、スキャンがバックスラッシュを挿入します。これにより、その模倣は会話の一部と誤認されることなく、通常のテキストとして読まれます。
• マーカー行: レポートが <system-reminder> のようなタグを模倣している場合、または bypassPermissions や --dangerously-skip-permissions などの権限設定に言及している場合、スキャンは [harness: subagent output matched instruction-shaped pattern(s): で始まる行を先頭に追加します。権限設定への言及にはマーカー行が付きますが、テキスト自体は書かれたとおりのままです。

​

一般的なパターン

​

大量の出力を伴う操作を分離する

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

​

サブエージェントを連鎖させる

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

​

サブエージェントとメインの会話のどちらを使うか

• タスクに頻繁なやり取りや反復的な改善が必要な場合
• 計画、実装、テストなど、複数のフェーズがかなりのコンテキストを共有する場合
• すばやく的を絞った変更を行う場合
• レイテンシが重要な場合。フォークではないサブエージェントはまっさらな状態から開始するため、コンテキストの収集に時間がかかることがあります

• タスクが、メインのコンテキストには不要な冗長な出力を生成する場合
• 特定のツール制限や権限を適用したい場合
• 作業が自己完結しており、要約を返せる場合

​

サブエージェントに独自のサブエージェントを生成させる

• インタラクティブなターミナルセッション: バックグラウンドサブエージェントを起動したサブエージェントは終了する前にそれらの結果を待つため、ユーザーに返されるのは最上位のサブエージェントの要約だけです。
• claude -p と Agent SDK: フォークモードがオンの間、生成元のサブエージェントは待機します。フォークモードをオフにすると、ネストされたサブエージェントは代わりにバックグラウンドで開始されます。生成元のサブエージェントはバックグラウンドのネストされたサブエージェントを待たず、そのネストされたサブエージェントは生成元より長く実行された場合、メインの会話に報告します。

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

​

同時実行サブエージェントの上限

• /subtask で開始したセッション内のフォークは、実行中に枠を 1 つ占有し、上限によってブロックされることはありません。
• すでに終了したサブエージェントの再開は、上限を確認せずに新しい枠を占有するため、再開によって実行中の数が上限を超えることがあります。

​

サブエージェントのコンテキストを管理する

​

起動時に読み込まれるもの

• システムプロンプト: Claude Code のシステムプロンプトではなく、エージェント自身のプロンプトに Claude Code が追加する環境の詳細を加えたものです。カスタムサブエージェントは、markdown 本文または prompt フィールドでこれを定義します。組み込みエージェントには定義済みのプロンプトがあります。
• タスクメッセージ: 作業を引き渡すときに Claude が作成する委任プロンプトです。
• CLAUDE.md ファイル: ~/.claude/CLAUDE.md、プロジェクトのルール、CLAUDE.local.md、管理ポリシーファイル、プロジェクトの指示として読み込まれる AGENTS.md ファイルなど、メインの会話が読み込む CLAUDE.md の階層のすべてのレベルです。組み込みの Explore エージェントと Plan エージェントはこれをスキップします。定義で omitClaudeMd が設定されているサブエージェントは、管理ポリシーファイルのみを読み込みます。定義が管理設定から来ている場合は、何も読み込みません。
• Git ステータス: サブエージェントの開始時に Claude Code がリポジトリから読み取るスナップショットです。そのリポジトリの独自の worktree 内のサブエージェントの場合、スナップショットには worktree のブランチ、ステータス、最近のコミットが表示されます。Git リポジトリの外にいる場合や、スナップショットがオフになっている場合は含まれません。includeGitInstructions を参照してください。Explore と Plan は、いずれにしてもこれをスキップします。
• プリロードされたスキル: エージェントの skills フィールドで指定されたスキルの全内容です。組み込みエージェントはスキルをプリロードしません。
• 兄弟エージェントの一覧: main と、セッション内の他のすべての名前付きエージェントを列挙するシステムリマインダーです。それぞれが SendMessage の有効な to 値になります。この一覧は、サブエージェントのツールに SendMessage が含まれていて、かつ少なくとも 1 つの他のエージェントが名前を持っている場合にのみ表示されます。その名前は、Claude が生成時に付けたものでも、エージェントチームのチームメイトとして実行されていることによるものでもかまいません。これはサブエージェントの開始時に取得されたスナップショットであるため、後から名前が付けられたエージェントは表示されません。

• 出力スタイル: サブエージェントは独自のシステムプロンプトで実行されるため、フォークの場合を除き、出力スタイルはその応答に影響しません。
• 自動メモリ: メインの会話の自動メモリは読み込まれません。サブエージェントに独自の永続的なメモリを持たせるには、memory フィールドを使います。
• コンテキストウィンドウのサイズ: サブエージェントのコンテキストウィンドウのサイズは、親のモデルではなく、サブエージェント自身のモデルによって決まります。より小さなウィンドウを持つモデルに委任すると、そのサブエージェントのウィンドウは小さくなります。

​

サブエージェントを再開する

• サブエージェントが完了すると、Claude はそのエージェント ID を受け取ります。
• 組み込みの Explore エージェントと Plan エージェントは 1 回限りのもので、エージェント ID を返さないため、Claude はそれらを再開できません。作業を続ける必要がある場合は、general-purpose またはカスタムサブエージェントを使います。
• サブエージェントが maxTurns の上限で停止すると、Claude Code は返された出力を部分的なものとしてマークし、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]

• メインの会話のコンテキスト圧縮: メインの会話が圧縮されても、サブエージェントのトランスクリプトは影響を受けません。これらは別のファイルに保存されています。
• セッションの永続性: サブエージェントのトランスクリプトは、そのセッション内で保持されます。同じセッションを再開することで、Claude Code を再起動した後でもサブエージェントを再開できます。
• 自動クリーンアップ: Claude Code は、保持期間のスイープルールに従い、cleanupPeriodDays の保持期間（デフォルトは 30 日）が過ぎたサブエージェントのトランスクリプトを削除します。

再起動後に名前でサブエージェントにメッセージを送る

​

自動圧縮

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

1 つのサブエージェントに自動圧縮のウィンドウを設定する

---
name: log-reader
description: Reads long log files and reports the errors it finds
autoCompactWindow: 200000
---

• 値が、サブエージェントが本来継承する自動圧縮のウィンドウより小さくない: より早く圧縮させるには、そのウィンドウより小さい値を設定します。
• --agent または agent 設定で、セッション全体をこのサブエージェントとして実行している: その場合、このフィールドは効果を持ちません。セッションのウィンドウを設定するには、自動圧縮のウィンドウを設定するを参照してください。

​

現在の会話をフォークする

/subtask draft unit tests for the parser changes so far

​

実行中のフォークを観察して操作する

• /compact、/clear、/rewind はメイン会話に対して動作するため、このビューからこれらのいずれかを実行する前に、Claude Code は確認を求めます。
• /model と /fast は、表示しているエージェントではなくメイン会話のモデルと fast mode を設定するため、このビューからは実行されません。その理由は通知で表示されます。

​

フォークと他のサブエージェントの違い

​

フォークモードをオフにする

• フォークのみを停止する：設定の permissions.deny に "Agent(fork)" を追加します。
• フォークモードをオフにする：Claude にサブエージェントを待機させるの手順に従って、CLAUDE_CODE_FORK_SUBAGENT を 0 に設定します。

​

サブエージェントの例

​

コードレビュアー

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

​

デバッガー

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

​

データサイエンティスト

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

​

データベースクエリバリデーター

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

#!/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

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

​

次のステップ

• プラグインでサブエージェントを配布することで、チームまたはプロジェクト全体でサブエージェントを共有します
• Claude Code をプログラムで実行することで、Agent SDK を使用して CI/CD と自動化を行います
• MCP サーバーを使用することで、サブエージェントに外部ツールとデータへのアクセスを提供します