文档索引

在此获取完整文档索引：https://code.claude.com/docs/llms.txt 使用此文件发现所有可用页面，然后再进一步探索。

创建自定义子代理

在 Claude Code 中创建和使用专业 AI 子代理，用于特定任务的工作流和改进的上下文管理。

子代理是处理特定类型任务的专业 AI 助手。当一个附带任务会用你不会再引用的搜索结果、日志或文件内容淹没你的主对话时使用它：子代理在自己的上下文中完成该工作，只返回摘要。当你不断以相同指令生成相同类型的工作者时，定义一个自定义子代理。

每个子代理在自己的上下文窗口中运行，有自定义系统提示、特定工具访问和独立权限。当 Claude 遇到匹配子代理描述的任务时，它委派给该子代理，后者独立工作并返回结果。要在实践中查看上下文节省，上下文窗口可视化展示了一个子代理在自己独立窗口中处理研究的会话。

子代理帮助你：

• 保留上下文，通过将探索和实现排除在主对话之外
• 强制约束，通过限制子代理可以使用哪些工具
• 重用配置，通过用户级子代理跨项目
• 专业化行为，通过针对特定领域的聚焦系统提示
• 控制成本，通过将任务路由到更快、更便宜的模型如 Haiku

Claude 使用每个子代理的描述来决定何时委派任务。当你创建子代理时，编写清晰的描述以便 Claude 知道何时使用它。

Claude Code 包含几个内置子代理如 Explore、Plan 和 general-purpose。你也可以创建自定义子代理来处理特定任务。本页涵盖：

• 内置子代理
• 如何创建你自己的
• 完整配置选项
• 使用子代理的模式
• 分叉子代理
• 示例子代理

内置子代理

Claude Code 包含内置子代理，Claude 在适当时自动使用。每个继承父对话的权限，并有额外的工具限制。

Explore 和 Plan 跳过你的 CLAUDE.md 文件和父会话的 git 状态，以保持研究快速和低成本。每个其他内置和自定义子代理加载两者。有关到达子代理的完整分解，请参阅启动时加载的内容。

除了这些内置子代理，你可以使用自定义提示、工具限制、权限模式、钩子和技能创建自己的。以下部分展示如何入门和自定义子代理。

快速开始：创建你的第一个子代理

子代理在带有 YAML 前置数据的 Markdown 文件中定义。你可以手动创建它们或使用 /agents 命令。

本指南引导你使用 /agents 命令创建用户级子代理。该子代理审查代码并为代码库建议改进。

1. 打开子代理界面

   在 Claude Code 中运行：

   /agents
   

2. 选择位置

   切换到库标签页，选择创建新代理，然后选择个人。这将子代理保存到 ~/.claude/agents/，使其在你所有项目中可用。

3. 使用 Claude 生成

   选择使用 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. 选择工具

   对于只读审查者，取消选择除只读工具之外的所有内容。如果你保持所有工具选中，子代理继承主对话可用的所有工具。

5. 选择模型

   选择子代理使用的模型。对于此示例代理，选择 Sonnet，它在分析代码模式时平衡能力和速度。

6. 选择颜色

   为子代理选择背景色。这帮助你在 UI 中识别哪个子代理正在运行。

7. 配置记忆

   选择用户范围以在 ~/.claude/agent-memory/ 给子代理一个持久记忆目录。子代理使用此来跨对话积累见解，如代码库模式和反复出现的问题。如果你不想让子代理持久化学习，选择无。

8. 保存并试用

   查看配置摘要。按 s 或 Enter 保存，或按 e 保存并在编辑器中编辑文件。子代理立即可用。试一试：

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

   Claude 委派给你的新子代理，后者扫描代码库并返回改进建议。

你现在有了一个可以在你机器上任何项目中使用的子代理，用于分析代码库和建议改进。

你也可以手动创建子代理作为 Markdown 文件，通过 CLI 标志定义它们，或通过插件分发它们。以下部分涵盖所有配置选项。

配置子代理

使用 /agents 命令

/agents 命令打开一个管理子代理的标签页界面。运行中标签页显示实时子代理并让你打开或停止它们。库标签页让你：

• 查看所有可用子代理（内置、用户、项目和插件）
• 使用引导设置或 Claude 生成创建新子代理
• 编辑现有子代理配置和工具访问
• 删除自定义子代理
• 当存在重复时查看哪些子代理处于活动状态

这是创建和管理子代理的推荐方式。对于手动创建或自动化，你也可以直接添加子代理文件。

选择子代理范围

子代理是带有 YAML 前置数据的 Markdown 文件。根据范围存储在不同的位置。当多个子代理共享相同名称时，更高优先级的位置获胜。

项目子代理（.claude/agents/）适合特定于代码库的子代理。将它们提交到版本控制，以便你的团队可以协作使用和改进它们。

项目子代理通过从当前工作目录向上遍历发现。使用 --add-dir 添加的目录仅授予文件访问权限，不会扫描子代理。要跨项目共享子代理，使用 ~/.claude/agents/ 或插件。

用户子代理（~/.claude/agents/）是在你所有项目中可用的个人子代理。

Claude Code 递归扫描 .claude/agents/ 和 ~/.claude/agents/，因此你可以将定义组织到子文件夹中，如 agents/review/ 或 agents/research/。子目录路径不影响子代理的识别或调用方式，因为身份仅来自 name 前置数据字段。保持 name 值在整个树中唯一：如果一个范围内的两个文件声明相同的名称，Claude Code 保留一个并丢弃另一个，不发出警告。

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

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 是必需的。

选择模型

model 字段控制子代理使用的 AI 模型：

• 模型别名：使用可用别名之一：sonnet、opus 或 haiku
• 完整模型 ID：使用完整模型 ID 如 claude-opus-4-7 或 claude-sonnet-4-6。接受与 --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 中。子代理获得工具；父对话不获得。

权限模式

permissionMode 字段控制子代理如何处理权限提示。子代理从主对话继承权限上下文并可以覆盖模式，除非父模式优先如下所述。

如果父使用 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.

每个列出的技能的完整内容在启动时注入子代理的上下文。此字段控制哪些技能被预加载，而非子代理可以访问哪些技能：没有它，子代理仍可在执行期间通过技能工具发现和调用项目、用户和插件技能。要完全防止子代理调用技能，从 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.

根据记忆应应用的广泛程度选择范围：

启用记忆时：

• 子代理的系统提示包含读取和写入记忆目录的指令
• 子代理的系统提示还包含记忆目录中 MEMORY.md 的前 200 行或 25KB（以先到者为准），并附有在超过该限制时管理 MEMORY.md 的指令
• Read、Write 和 Edit 工具自动启用，以便子代理可以管理其记忆文件

持久记忆提示

• project 是推荐的默认范围。它使子代理知识可通过版本控制共享。当子代理的知识广泛适用于项目时使用 user，当知识不应提交到版本控制时使用 local

• 让子代理在开始工作前查阅其记忆："Review this PR, and check your memory for patterns you've seen before."

• 让子代理在完成任务后更新其记忆："Now that you're done, save what you learned to your memory." 随着时间推移，这建立了一个使子代理更有效的知识库

• 直接在子代理的 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.
  

使用钩子的条件规则

要更动态地控制工具使用，使用 PreToolUse 钩子在操作执行前验证它们。当你需要允许工具的某些操作同时阻止其他操作时很有用。

此示例创建一个仅允许只读数据库查询的子代理。PreToolUse 钩子在每个 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 将钩子输入作为 JSON 通过 stdin 传递给钩子命令。验证脚本读取此 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

参见钩子输入了解完整输入模式，退出代码了解退出代码如何影响行为。在 Windows 上，用 PowerShell 编写钩子脚本并在钩子条目中添加 shell: powershell，如在 PowerShell 中运行钩子所示。

禁用特定子代理

你可以通过将特定子代理添加到设置中的 deny 数组来阻止 Claude 使用它们。使用格式 Agent(subagent-name)，其中 subagent-name 匹配子代理的 name 字段。

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

这适用于内置和自定义子代理。你也可以使用 --disallowedTools CLI 标志：

claude --disallowedTools "Agent(Explore)"

有关权限规则的更多详情，请参阅权限文档。

为子代理定义钩子

子代理可以定义在子代理生命周期内运行的钩子。有两种配置钩子的方式：

1. 在子代理的前置数据中：定义仅在该子代理激活时运行的钩子
2. 在 settings.json 中：定义在子代理启动或停止时在主会话中运行的钩子

子代理前置数据中的钩子

直接在子代理的 markdown 文件中定义钩子。这些钩子仅在该特定子代理激活时运行，并在完成时清理。

所有钩子事件都受支持。子代理最常见的事件是：

此示例使用 PreToolUse 钩子验证 Bash 命令，使用 PostToolUse 在文件编辑后运行 linter：

---
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 钩子自动转换为 SubagentStop 事件。

子代理事件的项目级钩子

在 settings.json 中配置响应主会话中子代理生命周期事件的钩子。

两个事件都支持匹配器以按名称定向特定代理类型。此示例仅在 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" }
        ]
      }
    ]
  }
}

有关完整的钩子配置格式，请参阅钩子。

使用子代理

理解自动委派

Claude 根据你请求中的任务描述、子代理配置中的 description 字段和当前上下文自动委派任务。要鼓励主动委派，在子代理的描述字段中包含"use proactively"等短语。

显式调用子代理

当自动委派不够时，你可以自己请求子代理。三种模式从一次性建议升级到会话范围默认：

• 自然语言：在提示中命名子代理；Claude 决定是否委派
• @-提及：保证子代理为一个任务运行
• 会话范围：整个会话使用该子代理的系统提示、工具限制和模型，通过 --agent 标志或 agent 设置

对于自然语言，没有特殊语法。命名子代理，Claude 通常会委派：

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

@-提及子代理。 输入 @ 并从自动完成中选择子代理，与你 @-提及文件的方式相同。这确保特定子代理运行，而非将选择留给 Claude：

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

你的完整消息仍发送给 Claude，后者根据你要求的内容编写子代理的任务提示。@-提及控制 Claude 调用哪个子代理，而非它接收什么提示。

由启用的插件提供的子代理在其范围名称下出现在自动完成中，如 my-plugin:code-reviewer 或当插件将代理组织到子文件夹中时的 my-plugin:review:security。当前在会话中运行的命名后台子代理也出现在自动完成中，在名称旁边显示其状态。你也可以不使用选择器手动输入提及：本地子代理用 @agent-<name>，插件子代理用 @agent- 后跟范围名称，例如 @agent-my-plugin:code-reviewer。

将整个会话作为子代理运行。 传递 --agent <name> 以启动主线程本身承担该子代理的系统提示、工具限制和模型的会话：

claude --agent code-reviewer

子代理的系统提示完全替换默认的 Claude Code 系统提示，与 --system-prompt 的方式相同。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"在后台运行这个"
• 按 Ctrl+B 将正在运行的任务置于后台

要禁用所有后台任务功能，将 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS 环境变量设置为 1。参见环境变量。

当启用分叉模式时，每个子代理生成都在后台运行，无论 background 字段如何。分叉仍在你的终端中显示权限提示；命名子代理自动拒绝任何会提示的内容，如上所述。

常见模式

隔离高量操作

子代理最有效的用途之一是隔离产生大量输出的操作。运行测试、获取文档或处理日志文件会消耗大量上下文。通过将这些委派给子代理，详细输出留在子代理的上下文中，只有相关摘要返回到你的主对话。

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，后者然后将相关上下文传递给下一个子代理。

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

在子代理和主对话之间选择

使用主对话当：

• 任务需要频繁的来回或迭代改进
• 多个阶段共享大量上下文（计划 -> 实现 -> 测试）
• 你正在做快速、有针对性的更改
• 延迟很重要。子代理从零开始，可能需要时间收集上下文

使用子代理当：

• 任务产生你不需要在主上下文中的详细输出
• 你想强制执行特定的工具限制或权限
• 工作是自包含的，可以返回摘要

当你想要可重用的提示或在主对话上下文中运行而非隔离子代理上下文的工作流时，考虑使用技能。

对于已经在对话中的内容的快速问题，使用 /btw 代替子代理。它看到你的完整上下文但没有工具访问权限，答案被丢弃而非添加到历史。

管理子代理上下文

启动时加载的内容

每个子代理以全新的隔离上下文窗口开始。它看不到你的对话历史、你已调用的技能或 Claude 已读取的文件。Claude 编写总结任务的委派消息，子代理从那里开始工作。例外是分叉，它继承父对话而非从零开始。

非分叉子代理的初始上下文包含：

• 系统提示：代理自己的提示加上 Claude Code 附加的环境详情，而非完整的 Claude Code 系统提示。自定义子代理在 markdown 正文或 prompt 字段中定义它们。内置代理有预定义提示。
• 任务消息：Claude 在移交工作时编写的委派提示。
• CLAUDE.md 和记忆：主对话加载的记忆层次结构的每个级别，包括 ~/.claude/CLAUDE.md、项目规则、CLAUDE.local.md 和托管策略文件。内置的 Explore 和 Plan 代理跳过此项。
• Git 状态：在父会话启动时拍摄的快照。当工作目录不是 Git 仓库或 includeGitInstructions 为 false 时不存在。Explore 和 Plan 无论如何都跳过它。
• 预加载技能：代理的 skills 字段中命名的任何技能的完整内容。内置代理不预加载技能。

Explore 和 Plan 是唯一省略 CLAUDE.md 和 git 状态的子代理。没有前置数据字段或每代理设置可以更改哪些代理跳过它们。

主对话使用完整的 CLAUDE.md 上下文读取 Explore 和 Plan 结果，因此大多数规则不需要到达子代理本身。如果规则必须到达，如"忽略 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 调用。

你也可以向 Claude 请求代理 ID，如果你想显式引用它，或在 ~/.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：

• 当 Claude 否则会使用通用子代理时，它生成分叉。命名子代理如 Explore 仍如之前一样生成。
• 每个子代理生成都在后台运行，无论是分叉还是命名子代理。设置 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS 为 1 以保持生成同步。
• /fork 命令生成分叉而非作为 /branch 的别名。

你可以用 /fork 后跟指令自己开始分叉。Claude Code 从指令的第一个词命名分叉。以下示例分叉对话以起草测试用例，同时你在主会话中继续实现：

/fork draft unit tests for the parser changes so far

分叉出现在提示下方的面板中，在你继续工作时在后台运行。完成时，其结果作为消息到达你的主对话。下一部分介绍运行时监视和引导分叉的面板控件。

观察和引导运行中的分叉

运行中的分叉出现在提示输入下方的面板中，主会话一行，每个分叉一行。使用这些键与面板交互：

分叉与命名子代理的区别

分叉继承生成时主会话拥有的一切。命名子代理从自己的定义开始。

因为分叉的系统提示和工具定义与父相同，其第一个请求重用父的提示缓存。这使得对于需要相同上下文的任务，分叉比生成新的子代理更便宜。

当 Claude 通过 Agent 工具生成分叉时，它可以传递 isolation: "worktree"，这样分叉的文件编辑写入单独的 git 工作树而非你的检出。

限制

设置 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，因为修复 bug 需要修改代码。提示提供了从诊断到验证的清晰工作流。

---
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 钩子进行条件验证。

---
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 将钩子输入作为 JSON 通过 stdin 传递给钩子命令。验证脚本读取此 JSON，提取正在执行的命令，并根据 SQL 写入操作列表检查它。如果检测到写入操作，脚本以代码 2 退出以阻止执行，并通过 stderr 向 Claude 返回错误消息。

在项目中的任何位置创建验证脚本。路径必须与钩子配置中的 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 编写验证脚本并在钩子条目中添加 shell: powershell。参见在 PowerShell 中运行钩子。

钩子通过 stdin 接收 JSON，Bash 命令在 tool_input.command 中。退出代码 2 阻止操作并将错误消息反馈给 Claude。有关退出代码的详情，请参阅钩子，有关完整输入模式，请参阅钩子输入。

后续步骤

现在你了解了子代理，探索这些相关功能：

• 使用插件分发子代理以跨团队或项目共享子代理
• 以编程方式运行 Claude Code使用 Agent SDK 进行 CI/CD 和自动化
• 使用 MCP 服务器让子代理访问外部工具和数据