Claude Code 子代理适合把搜索、审查、调试、数据库查询这类高输出或可分工任务放到独立上下文里处理。通过 /agents、.claude/agents/、~/.claude/agents/ 或 claude --agents 创建，配合 tools、disallowedTools、mcpServers、permissionMode、memory 和 isolation: worktree 控制能力与作用域。

Claude Code 子代理怎么配置与排查

Claude Code 子代理（Subagents）是专门处理特定任务的 AI 助手。它们在自己的上下文窗口里运行，有独立系统提示、工具权限和权限上下文；Claude 识别到描述匹配的任务时，会把任务委托给对应子代理，最后只把摘要结果带回主会话。

适合用子代理的场景：

主对话里会出现大量搜索结果、日志或文件内容
你想限制某个任务只能读，不能写
想把同类工作流复用到多个项目
想让某类任务固定走更快、更便宜的模型
想把探索、验证、修改拆开处理，减少上下文污染

Claude Code 还带了几个内置子代理：Explore、Plan、general-purpose，以及一些辅助代理，比如 statusline-setup 和 claude-code-guide。

内置子代理

Claude Code 会在合适的时候自动使用这些内置子代理。它们继承父会话的权限，但会再加一层工具限制。

Explore 和 Plan 会跳过 CLAUDE.md 文件以及父会话的 git status，这样研究更快、成本更低。其他所有内置子代理和自定义子代理都会加载这些内容。完整加载范围见后面的“启动时加载了什么”。

Explore

一个快速、只读的代理，适合搜索和分析代码库。

模型：Haiku（快速、低延迟）
工具：只读工具，不允许 Write 和 Edit
用途：文件发现、代码搜索、代码库探索

Claude 在需要搜索或理解代码库、但不需要修改时，会把任务交给 Explore。这样探索过程中的大量输出不会占满主对话上下文。

调用 Explore 时，Claude 会指定探索深度：

quick：定向查找
medium：平衡探索
very thorough：全面分析

Plan

计划模式下使用的研究代理，用来在给出计划前收集上下文。

模型：继承主会话
工具：只读工具，不允许 Write 和 Edit
用途：计划前的代码库研究

当你在 plan mode 里，Claude 需要理解代码库时，会把研究任务交给 Plan 子代理。这样可以避免无限嵌套，因为子代理不能再生成子代理。

general-purpose

适合复杂、多步骤任务的全能代理。

模型：继承主会话
工具：所有工具
用途：复杂研究、多步操作、代码修改

Claude 会在任务既需要探索，也需要修改，或者需要复杂推理和多阶段执行时使用它。

其他辅助代理

Agent	Model	使用时机
statusline-setup	Sonnet	运行 `/statusline` 配置状态栏时
claude-code-guide	Haiku	询问 Claude Code 功能问题时

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

子代理定义在带 YAML frontmatter 的 Markdown 文件里。你可以手动创建，也可以用 /agents 命令生成。

下面这个流程会创建一个用户级子代理，用来审查代码并给出改进建议。

在 Claude Code 里运行：
```
/agents
```
切换到 Library 标签，选择 Create new agent，然后选 Personal。这样会把子代理保存到 ~/.claude/agents/，可在所有项目中使用。

选择 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 会帮你生成 identifier、description 和 system prompt。

如果只是只读审查器，就把工具只保留 Read-only tools。如果保留全部工具，子代理会继承主会话可用的全部工具。
选择子代理使用的模型。这个例子选 Sonnet，它在分析代码模式时兼顾能力和速度。
选择子代理颜色。这样在 UI 里更容易识别正在运行的是哪个子代理。
选择 User scope，会给子代理启用一个持久记忆目录 ~/.claude/agent-memory/。它可以在不同会话里累计对代码库模式和重复问题的认知。若不想持久保存学习结果，选 None。
检查配置摘要。按 s 或 Enter 保存；也可以按 e 保存后直接在编辑器里继续修改。保存后立即可用。然后试一下：
```
Use the code-improver agent to suggest improvements in this project
```
Claude 会把任务委派给新建的子代理，它会扫描代码库并返回改进建议。

现在你已经有了一个可以在本机所有项目里使用的子代理。它能分析代码库并建议改进。

你也可以手动写 Markdown 文件、通过 CLI 标志定义，或者通过插件分发。下面是完整配置项。

配置子代理

使用 /agents 命令

/agents 会打开一个带标签页的管理界面。

Running 标签会显示正在运行的子代理，并允许你打开或停止它们。
Library 标签可以：

查看所有可用子代理（内置、用户、项目、插件）
通过引导式流程或 Claude 生成创建新子代理
编辑已有子代理的配置和工具权限
删除自定义子代理
当存在重名项时查看哪个子代理处于激活状态

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

选择子代理作用域

子代理是带 YAML frontmatter 的 Markdown 文件。根据作用域不同，放在不同位置。同名子代理时，优先级更高的位置生效。

Location	Scope	Priority	How to create
Managed settings	Organization-wide	1 (highest)	Deployed via managed settings
`--agents` CLI flag	Current session	2	Pass JSON when launching Claude Code
`.claude/agents/`	Current project	3	Interactive or manual
`~/.claude/agents/`	All your projects	4	Interactive or manual
Plugin’s `agents/` directory	Where plugin is enabled	5 (lowest)	Installed with plugins

项目子代理（.claude/agents/）最适合和代码库绑定的任务。把它们提交到版本控制，团队就能一起使用和迭代。

项目子代理是从当前工作目录向上查找得到的。通过 --add-dir 加入的目录只会获得文件访问权限，不会被扫描为子代理位置。想跨项目共享子代理，可以放到 ~/.claude/agents/ 或做成插件。

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

Claude Code 会递归扫描 .claude/agents/ 和 ~/.claude/agents/，所以你可以把定义放进子目录，例如 agents/review/ 或 agents/research/。子目录路径不会影响子代理的识别和调用，因为身份只由 name frontmatter 字段决定。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 字段和文件型子代理的 frontmatter 一致：description、prompt、tools、disallowedTools、model、permissionMode、mcpServers、hooks、maxTurns、skills、initialPrompt、memory、effort、background、isolation、color。其中 prompt 对应文件型子代理 Markdown 正文里的系统提示。

Managed subagents 由组织管理员部署。把 Markdown 文件放到托管设置目录里的 .claude/agents/，格式和项目、用户子代理相同。它们的优先级高于同名的项目和用户子代理。

插件子代理来自你已安装的 plugins。它们会和你的自定义子代理一起出现在 /agents 里。创建插件子代理的细节见 plugins reference。

出于安全原因，插件子代理不支持 hooks、mcpServers 或 permissionMode 这几个 frontmatter 字段。加载插件子代理时，这些字段会被忽略。如果你需要它们，把 agent 文件复制到 .claude/agents/ 或 ~/.claude/agents/。你也可以把规则加到 settings.json 或 settings.local.json 的 permissions.allow，但那会作用于整个会话，不只对某个插件子代理生效。

这些作用域里的子代理定义，也可以给 agent teams 使用：在创建队友时引用某个子代理类型，队友会沿用该定义的 tools 和 model，并把定义正文追加到队友的系统提示中作为额外指令。哪些 frontmatter 字段会在这条路径上生效，见 agent teams。

编写子代理文件

子代理文件使用 YAML frontmatter 配置，后面跟 Markdown 形式的系统提示：

子代理在会话开始时加载。如果你直接在磁盘上新增或修改子代理文件，需要重启会话才能加载。通过 /agents 界面创建的子代理会立即生效，不需要重启。

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

frontmatter 定义子代理的元数据和配置，正文则是指导子代理行为的系统提示。子代理只接收这段系统提示，以及工作目录等基础环境信息，不会拿到完整的 Claude Code 系统提示。

子代理从主会话当前工作目录开始运行。在子代理内部，cd 命令不会在不同 Bash 或 PowerShell 工具调用之间保留，也不会影响主会话的工作目录。若想给子代理一个隔离的仓库副本，可以设置 isolation: worktree。

支持的 frontmatter 字段

下面这些字段都可写在 YAML frontmatter 中。只有 name 和 description 是必填项。

Field	Required	Description
`name`	Yes	唯一标识符，只能用小写字母和连字符。Hooks 会把它作为 `agent_type` 接收。文件名不必和它一致
`description`	Yes	Claude 什么时候应该委托给这个子代理
`tools`	No	子代理可用的 Tools。如果省略，会继承所有工具。要预加载 Skills，请用 `skills` 字段，不要把 `Skill` 写到这里
`disallowedTools`	No	要禁止的工具，会从继承或显式指定的工具列表中移除
`model`	No	要使用的 Model：`sonnet`、`opus`、`haiku`、完整模型 ID（例如 `claude-opus-4-7`）或 `inherit`。默认 `inherit`
`permissionMode`	No	Permission mode：`default`、`acceptEdits`、`auto`、`dontAsk`、`bypassPermissions` 或 `plan`。插件子代理会忽略此项
`maxTurns`	No	子代理停止前最多可进行的代理回合数
`skills`	No	启动时预加载到子代理上下文里的 Skills。会注入技能的完整内容，不只是描述。子代理仍然可以通过 Skill 工具调用未列出的项目、用户和插件技能
`mcpServers`	No	子代理可用的 MCP 服务器。每个条目要么是已配置服务器的名称引用（例如 `"slack"`），要么是以内联方式定义的完整 MCP server config
`hooks`	No	仅对此子代理生效的 lifecycle hooks。插件子代理会忽略此项
`memory`	No	Persistent memory scope：`user`、`project` 或 `local`。支持跨会话学习
`background`	No	设为 `true` 时总是作为 background task 运行。默认 `false`
`effort`	No	子代理激活时的 effort level。覆盖会话级 effort level。默认继承会话。可选 `low`、`medium`、`high`、`xhigh`、`max`；具体可用项取决于模型
`isolation`	No	设为 `worktree` 时，在临时 git worktree 中运行，获得隔离的仓库副本。如果子代理没有修改，会自动清理 worktree
`color`	No	子代理在任务列表和转录里的显示颜色。可选 `red`、`blue`、`green`、`yellow`、`purple`、`orange`、`pink` 或 `cyan`
`initialPrompt`	No	当此代理作为主会话代理运行时（通过 `--agent` 或 `agent` 设置），自动作为第一轮用户输入提交。会处理 Commands 和 skills，并追加到用户输入前面

选择模型

model 字段控制子代理使用哪种 AI model。

模型别名：可用 sonnet、opus、haiku
完整模型 ID：例如 claude-opus-4-7 或 claude-sonnet-4-6。支持和 --model 标志相同的取值
inherit：和主会话使用同一模型
省略：默认 inherit

当 Claude 调用子代理时，也可以给这次调用单独传 model 参数。Claude Code 解析模型的优先级如下：

如果设置了环境变量 CLAUDE_CODE_SUBAGENT_MODEL
单次调用传入的 model 参数
子代理定义里的 model frontmatter
主会话模型

控制子代理能力

可以通过工具权限、权限模式和条件规则来控制子代理能做什么。

可用工具

子代理可以使用 Claude Code 的任意 internal tools。默认情况下，子代理会继承主会话的全部工具，包括 MCP 工具。

要限制工具，可以用 tools（白名单）或 disallowedTools（黑名单）。下面的例子只允许 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) 语法。

从 2.1.63 开始，Task 工具改名为 Agent。settings 和 agent 定义里已有的 Task(...) 写法仍然可作为别名使用。

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

这是一个白名单：只能生成 worker 和 researcher 子代理。如果它尝试生成其他类型，调用会失败，而且它在提示里只能看到允许的类型。若要阻止某些代理、但允许其他全部代理，使用 permissions.deny。

如果想允许生成任意子代理，不加限制地使用 Agent 即可：

tools: Agent, Read, Bash

如果 tools 列表里完全没有 Agent，这个代理就不能生成任何子代理。这个限制只对 claude --agent 启动、作为主线程运行的代理生效。子代理本身不能再生成子代理，所以在子代理定义里写 Agent(agent_type) 没有效果。

给子代理限定 MCP 服务器

用 mcpServers 字段可以给子代理配置主会话里没有的 MCP 服务器。这里写的内联服务器只会在子代理启动时连接，结束时断开。字符串引用则复用父会话已有连接。

mcpServers 字段在 agent 文件可运行的两种场景里都生效：

作为子代理，通过 Agent 工具或 @ 提及触发

作为主会话，通过 --agent 或 agent 设置启动

当 agent 作为主会话运行时，内联服务器定义会在启动时和来自 .mcp.json 及 settings 文件的服务器一起连接。

列表中的每一项要么是内联 server 定义，要么是对当前会话里已配置 MCP server 的字符串引用：

---
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 中服务器条目相同的 schema（stdio、http、sse、ws），以 server name 为键。

如果你想让某个 MCP server 完全不进入主会话、也不占用主会话里的工具描述上下文，可以把它以内联方式定义在这里，而不是写进 .mcp.json。这样子代理能拿到工具，父会话拿不到。

权限模式

permissionMode 控制子代理怎么处理权限提示。子代理会继承主会话的权限上下文，并且可以覆盖模式，但下面说的父级优先级例外。

Mode	Behavior
`default`	标准权限检查和提示
`acceptEdits`	自动接受工作目录或 `additionalDirectories` 路径下的文件编辑和常见文件系统命令
`auto`	Auto mode：后台分类器会审查命令和受保护目录写入
`dontAsk`	自动拒绝权限提示（显式允许的工具仍可用）
`bypassPermissions`	跳过权限提示
`plan`	计划模式（只读探索）

使用 bypassPermissions 要小心。它会跳过所有权限提示，允许子代理在未经批准的情况下执行操作，包括写入 .git、.claude、.vscode、.idea 和 .husky。对根目录和 home 目录的删除，比如 rm -rf /，仍会像安全熔断一样继续提示。详细内容见 permission modes。

如果父会话使用 bypassPermissions 或 acceptEdits，它们的优先级更高，子代理不能覆盖。若父会话使用 auto mode，子代理会继承 auto mode，且 frontmatter 里的 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 会跳过它并在调试日志里写警告。

这和在子代理中运行技能是反过来的。子代理里的 skills 是由子代理控制系统提示并加载技能内容；技能里的 context: fork 则是把技能内容注入到你指定的代理里。两者底层用的是同一套系统。

启用持久记忆

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.

根据记忆应该作用到多广，选择不同作用域：

Scope	Location	Use when
`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
可以让子代理开始前先查记忆：“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 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 会通过 stdin 把 hook 输入作为 JSON 传给 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 input，退出码如何影响行为见 exit codes。

在 Windows 上，hook 脚本要写成 PowerShell，并在 hook 条目里添加 shell: powershell，示例见 running hooks in PowerShell。

禁用特定子代理

如果你想阻止 Claude 使用某些子代理，可以把它们加入 settings 里的 deny 数组。格式是 Agent(subagent-name)，其中 subagent-name 要和子代理的 name 字段一致。

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

这对内置和自定义子代理都生效。你也可以用 --disallowedTools CLI 标志：

claude --disallowedTools "Agent(Explore)"

更多权限规则见 Permissions documentation。

给子代理定义 hooks

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

写在子代理 frontmatter 里：只在这个子代理运行期间生效
写在 settings.json 里：在主会话中监听子代理启动和停止事件

写在子代理 frontmatter 里的 hooks

可以直接写在子代理的 Markdown 文件里。这些 hooks 只在该子代理激活时运行，结束后会被清理。

当代理通过 Agent 工具或 @ 提及作为子代理被唤起时，frontmatter 里的 hooks 会触发；当代理通过 --agent 或 agent 设置作为主会话运行时，也会触发。主会话场景下，它们会和 settings.json 里定义的 hooks 一起运行。

所有 hook events 都支持。对子代理最常见的是这些事件：

Event	Matcher input	When it fires
`PreToolUse`	Tool name	子代理使用某个工具之前
`PostToolUse`	Tool name	子代理使用某个工具之后
`Stop`	(none)	子代理结束时（运行时会转换成 `SubagentStop`）

下面这个例子用 PreToolUse 验证 Bash 命令，并在文件编辑后用 PostToolUse 运行 lint：

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

当代理作为子代理被调用时，frontmatter 里的 Stop hooks 会在运行时自动转换成 SubagentStop 事件。

项目级 hooks 监听子代理事件

可以在 settings.json 里配置 hooks，响应主会话中的子代理生命周期事件。

Event	Matcher input	When it fires
`SubagentStart`	Agent type name	子代理开始执行时
`SubagentStop`	Agent type name	子代理完成时

这两个事件都支持 matcher，可按代理类型名称定向匹配。下面这个例子只在 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”之类的措辞。

显式调用子代理

自动委托不够时，你可以自己指定子代理。常见有三种方式，从一次性提示到会话级默认，强度逐级提升：

自然语言：在提示词里直接点名子代理，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 根据你的请求生成子代理任务提示。@ 提及控制的是调用哪个子代理，不是它收到什么提示。

如果启用了 plugin，插件里的子代理会按作用域名称显示在自动补全里，例如 my-plugin:code-reviewer，或者当插件把 agent 按子目录组织时显示成 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 标志，CLI 会覆盖设置项。

前台运行或后台运行

子代理可以以前台（阻塞）或后台（并发）方式运行：

前台子代理会阻塞主对话直到完成。权限提示会在出现时透传给你。
后台子代理会并发运行，你可以继续工作。它们只使用会话里已经授予的权限，并会自动拒绝任何本来会弹出权限提示的工具调用。如果后台子代理需要澄清问题，这次工具调用会失败，但子代理会继续运行。

如果后台子代理因为缺少权限而失败，你可以用同样任务再起一个前台子代理，重新走交互式提示。

Claude 会根据任务决定子代理以前台还是后台运行。你也可以：

直接要求 Claude “run this in the background”
按 Ctrl+B 把正在运行的任务放到后台

如果要禁用所有后台任务，把环境变量 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS 设为 1。见 Environment variables。

启用fork mode 时，所有子代理都会在后台运行，不管 background 字段怎么写。Fork 仍然会在终端里实时显示权限提示；命名子代理会自动拒绝任何需要弹窗确认的操作，如上所述。

常见用法

隔离高输出任务

子代理最有效的用途之一，是把会产生大量输出的操作隔离出去。运行测试、抓文档、处理日志文件都可能消耗大量上下文。把这些任务交给子代理后，冗长输出会留在子代理上下文里，主对话只收到相关摘要。

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 汇总结论。这个模式最适合各条研究路径互不依赖的任务。

子代理完成后，结果会返回主对话。起很多个子代理、而且每个都返回详细结果，会消耗大量上下文。

如果任务需要持续并行，或者已经超过你的上下文窗口，可以用 agent teams 让每个 worker 拥有自己的独立上下文。

串联子代理

多步骤工作流里，可以让 Claude 按顺序使用多个子代理。一个子代理完成后返回结果，Claude 再把相关上下文交给下一个子代理。

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

子代理和主会话怎么选

适合放在主会话里的任务：

需要频繁来回确认或逐步打磨
多个阶段共享大量上下文（计划 → 实现 → 测试）
只是快速、定向的小改动
对延迟敏感。子代理要重新建立上下文，可能需要额外时间

适合放在子代理里的任务：

输出很多，不想占用主上下文
需要严格的工具限制或权限控制
工作自包含，最后只要摘要
适合并行处理

如果你想要的是可复用的提示词或工作流，而且它要在主会话上下文里运行，而不是隔离的子代理上下文，考虑用 Skills。

如果只是想问一个当前对话里已经出现过的小问题，用 /btw 比起起子代理更合适。它能看到完整上下文，但没有工具权限，而且答案不会写入历史。

子代理不能再生成子代理。如果工作流需要嵌套委托，请改用 Skills 或者在主对话里串联子代理。

管理子代理上下文

启动时加载了什么

每个子代理都会从一个全新的、隔离的上下文窗口开始。它看不到你的对话历史、你已经调用过的技能，也看不到 Claude 已经读过的文件。Claude 会先生成一条委托消息，概括任务内容，然后子代理基于这条消息工作。例外是 fork，它会继承父会话，而不是从零开始。

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

System prompt：代理自己的提示词，以及 Claude Code 追加的环境信息，不包含完整的 Claude Code system prompt。自定义子代理的 system prompt 写在 Markdown 正文或 prompt 字段里；内置代理有预置提示词。
Task message：Claude 在委派任务时写入的提示。
CLAUDE.md 和 memory：主会话加载的 memory hierarchy 每一层内容，包括 ~/.claude/CLAUDE.md、项目规则、CLAUDE.local.md 和托管策略文件。内置 Explore 和 Plan 会跳过这些内容。
Git status：在父会话开始时拍摄的快照。如果当前目录不是 Git 仓库，或者 includeGitInstructions 为 false，这部分不会加载。Explore 和 Plan 无论如何都跳过它。
Preloaded skills：在代理 skills 字段里列出的技能的完整内容。内置代理不会预加载技能。

Explore 和 Plan 是唯一会省略 CLAUDE.md 和 git status 的子代理。没有任何 frontmatter 字段或单独设置能改变哪些代理跳过它们。

主会话会带着完整的 CLAUDE.md 上下文读取 Explore 和 Plan 的结果，所以大多数规则不需要直接传给子代理本身。如果某条规则必须被遵守，比如“忽略 vendor/ 目录”，那就要在委托给 Claude 的提示里重新写一遍。

恢复子代理

每次调用子代理都会创建一个全新实例，使用全新的上下文。要继续已有子代理的工作，而不是重头开始，可以让 Claude 恢复它。

恢复后的子代理会保留完整对话历史，包括之前所有工具调用、结果和推理。子代理会从停止处原样继续，而不是重新开始。

当子代理完成时，Claude 会拿到它的 agent ID。Claude 会使用 SendMessage 工具，并把 agent ID 放到 to 字段里来恢复它。SendMessage 只有在通过 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 启用 agent teams 时才可用。

要恢复子代理，可以让 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 要 agent ID，或者在 ~/.claude/projects/{project}/{sessionId}/subagents/ 下的转录文件里找。每个转录都会保存成 agent-{agentId}.jsonl.

子代理转录会独立于主会话持久保存：

主会话压缩：主会话压缩时，子代理转录不受影响。它们存放在单独文件里。
会话持久化：子代理转录会在会话内持续保留。重启 Claude Code 后，只要恢复同一个会话，就能继续恢复子代理。
自动清理：转录会按 cleanupPeriodDays 设置清理，默认 30 天。

自动压缩

子代理支持和主会话相同逻辑的自动压缩。默认在大约 95% 容量时触发。想更早触发，可以把 CLAUDE_AUTOCOMPACT_PCT_OVERRIDE 设成更低的百分比，比如 50。详情见 environment variables。

压缩事件会记录到子代理转录文件里：

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

preTokens 表示压缩前已经使用了多少 token。

Fork 当前对话

Forked subagents 是实验性功能，要求 Claude Code v2.1.117 或更高版本。行为和配置未来可能变化。通过设置环境变量 CLAUDE_CODE_FORK_SUBAGENT 为 1 启用。该变量在交互模式、SDK 和 claude -p 下都会生效。

Fork 是一种子代理：它不是从零开始，而是继承当前为止的整段对话。这会降低普通子代理那种输入隔离的特性。Fork 会看到和主会话一样的系统提示、工具、模型和消息历史，所以你可以把侧边任务交给它，而不用重新解释背景。Fork 自己的工具调用仍然不会进入你的主对话，只有最终结果会回来，因此主上下文窗口仍然保持干净。适合在命名子代理需要太多背景才能有用时，或者你想从同一起点并行尝试多个方案时使用。

启用 fork mode 后，Claude Code 会有三点变化：

只要原本会使用 general-purpose 子代理，就会改成 spawn 一个 fork。像 Explore 这样的命名子代理仍然按原方式生成。
所有子代理 spawn 都会在后台运行，不管它是不是 fork。想保持同步，可把 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS 设为 1。
/fork 命令会真正生成 fork，而不再只是 /branch 的别名。

你可以直接用 /fork 加上一条指令来启动 fork。Claude Code 会用这条指令的前几个词给 fork 命名。下面这个例子会在你继续主会话实现功能时，让 fork 去起草测试用例：

/fork draft unit tests for the parser changes so far

Fork 会出现在输入框下方的面板里，后台运行，而你可以继续工作。完成后，它的结果会作为一条消息回到主对话。下一节会讲如何在运行时观察和引导这些 fork。

观察和操作运行中的 fork

运行中的 fork 会显示在输入框下方的面板里，每一行对应主会话或一个 fork。可用这些按键操作：

Key	Action
`↑` / `↓`	在各行之间移动
`Enter`	打开选中 fork 的转录并继续发消息
`x`	关闭已完成的 fork，或停止正在运行的 fork
`Esc`	返回输入框

Fork 和命名子代理有什么不同

Fork 会继承它生成那一刻主会话已经拥有的一切。命名子代理则从自己的定义开始。

	Fork	命名子代理
Context	完整对话历史	带着你传入提示的新上下文
System prompt and tools	与主会话相同	来自子代理定义文件
Model	与主会话相同	来自子代理的 `model` 字段
Permissions	提示会直接显示在终端	后台运行时会自动拒绝需要弹窗的操作
Prompt cache	与主会话共享	独立缓存

因为 fork 的 system prompt 和工具定义与父会话完全相同，它的第一次请求会复用父会话的 prompt cache。这让 fork 在需要同样上下文的任务上，比重新起一个新子代理更省。

当 Claude 通过 Agent 工具生成 fork 时，还可以传入 isolation: "worktree"，让 fork 的文件修改写到单独的 git worktree，而不是当前 checkout。

限制

设置 CLAUDE_CODE_FORK_SUBAGENT=1 后，fork mode 会在交互式会话、非交互模式和 Agent SDK 中生效。Fork 不能再生成 fork。

示例子代理

下面这些例子展示了构建子代理的有效模式。你可以直接拿来做起点，也可以让 Claude 生成一个定制版本。

最佳实践：

设计聚焦子代理：每个子代理只擅长一件事

写清楚 description：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 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 会通过 stdin 把 hook 输入作为 JSON 传给 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。见 running hooks in PowerShell。

hook 会通过 stdin 接收 JSON，tool_input.command 里是 Bash 命令。退出码 2 会阻止操作，并把错误消息回传给 Claude。退出码行为见 Hooks，输入结构见 Hook input。

下一步

理解子代理之后，可以继续看这些相关功能：

通过插件分发子代理在团队或项目间共享子代理
用 Agent SDK 程序化运行 Claude Code 做 CI/CD 和自动化
使用 MCP 服务器给子代理接入外部工具和数据

常见问题

Claude Code 子代理怎么创建？

最常见的方式是运行 /agents，在 Library 里选择 Create new agent，按提示生成并保存。你也可以直接在 .claude/agents/ 或 ~/.claude/agents/ 里创建 Markdown 文件，用 frontmatter 写 name、description、tools、model 等配置。

子代理为什么没有按预期被调用？

Claude 会根据请求内容、子代理的 description 和当前上下文自动决定是否委托。要提高命中率，可以把 description 写清楚，并加入 “use proactively” 这类明确触发语句；如果要强制执行，用 @ 提及或直接用 --agent。

子代理和主会话能用不同模型吗？

可以。model 可以设成 sonnet、opus、haiku，也可以写完整模型 ID 或 inherit。如果省略，默认继承主会话模型；如果设置了 CLAUDE_CODE_SUBAGENT_MODEL，它会优先于子代理定义。

Claude Code 子代理怎么配置与排查 #

内置子代理 #

Explore #

Plan #

general-purpose #

其他辅助代理 #

快速创建你的第一个子代理 #

配置子代理 #

使用 /agents 命令 #

选择子代理作用域 #

编写子代理文件 #

支持的 frontmatter 字段 #

选择模型 #

控制子代理能力 #

可用工具 #

限制可以生成哪些子代理 #

给子代理限定 MCP 服务器 #

权限模式 #

给子代理预加载技能 #

启用持久记忆 #

持久记忆使用建议 #

用钩子做条件规则 #

禁用特定子代理 #

给子代理定义 hooks #

写在子代理 frontmatter 里的 hooks #

项目级 hooks 监听子代理事件 #

使用子代理 #

理解自动委托 #

显式调用子代理 #

前台运行或后台运行 #

常见用法 #

隔离高输出任务 #

并行研究 #

串联子代理 #

子代理和主会话怎么选 #

管理子代理上下文 #

启动时加载了什么 #

恢复子代理 #

自动压缩 #

Fork 当前对话 #

观察和操作运行中的 fork #

Fork 和命名子代理有什么不同 #

限制 #

示例子代理 #

代码审查器 #

调试器 #

数据科学家 #

数据库查询校验器 #

下一步 #

常见问题 #

Claude Code 子代理怎么创建？ #

子代理为什么没有按预期被调用？ #

子代理和主会话能用不同模型吗？ #