Claude Code 子代理（Subagent）
在 Claude Code 中，你可以创建专门的 AI 子代理（Subagent），用于处理特定类型的任务，从而获得更好的上下文管理、更强的约束控制和更高的执行效率。
子代理是运行在独立上下文窗口中的专用 AI 助手。每个子代理都可以拥有：
- 独立的系统提示（System Prompt）
- 独立的上下文（不污染主对话）
- 指定的模型（Sonnet / Haiku / Opus）
- 明确的工具访问权限
- 独立的权限模式
- 生命周期钩子（Hooks）
- 跨会话持久记忆（Memory）
当 Claude 判断你的请求符合某个子代理的描述（description）时，就会自动将任务委托给该子代理，由它独立完成并返回结果。
重要：子代理只接收自身的系统提示和基础环境信息（如工作目录），不会继承完整的 Claude Code 系统提示。这保证了行为的纯净和可控。
为什么要使用子代理？
子代理的核心价值在于隔离 + 专业化。它可以帮助你：
保留主对话上下文
- 把探索、扫描、日志分析等"重任务"放到子代理中，主对话只接收结论摘要
- 研究表明，并行运行三个子代理分析 5 万行项目约需 45 秒，而串行执行需要 3 分钟
强制执行约束
- 例如：只读分析、禁止写文件、禁止执行危险命令
跨项目复用
- 用户级子代理一次配置，所有项目可用
行为专业化
- 为特定领域（代码审查、调试、数据分析）设计专用 AI
- 在系统提示中明确指出该代理的弱点和边界，避免不必要的调用
控制成本
- 将简单任务交给 Haiku，将复杂分析交给 Sonnet
- 通过环境变量
CLAUDE_CODE_SUBAGENT_MODEL统一设置所有子代理使用的模型
子代理 = 专门干某一类事的 AI 工具人
子代理 vs 多代理（Multi-agent）
这两个概念容易混淆，区别在于任务粒度和运行范围：
| 对比项 | 子代理（Subagent） | 多代理（Multi-agent） |
|---|---|---|
| 运行范围 | 在单个 Claude Code 会话内启动，处理子任务后返回结果 | 多个 Claude Code 会话并行或串行运行，通常由编排器管理 |
| 上下文 | 独立上下文窗口，与主对话隔离 | 各会话上下文完全独立 |
| 嵌套 | 子代理不能再创建子代理（需嵌套时使用 Skills） | 可由编排器协调多层级任务 |
| 适用场景 | 聚焦子任务、大量输出隔离、专业分析 | 全功能开发流水线（设计→实现→测试→发布） |
Claude Code 内置的子代理
Claude Code 已内置多种子代理，通常会自动使用，你不需要手动配置。
1、Explore（探索代理）
用途：只读搜索与分析代码库
- 模型：Haiku（速度快、延迟低）
- 工具：只读工具（不能 Edit / Write）
- 场景：搜索文件、理解代码结构、查找定义和引用
Claude 会在需要看代码但不改代码时自动使用 Explore。支持不同探索深度：quick / medium / very thorough。
2、Plan（规划代理）
用途：计划模式下的代码库研究
- 模型：继承主对话
- 工具：只读工具
- 场景：在 Plan 模式中理解项目，为后续方案制定收集上下文
在不产生嵌套代理的前提下，安全收集规划所需信息。
3、General-purpose（通用代理）
用途：复杂、多步骤任务
- 模型：继承主对话
- 工具：全部工具
- 场景：需要"看 + 改 + 推理"、多步骤代码修改、综合分析后给出结论
4、其他内部代理（无需手动使用）
| 代理 | 说明 |
|---|---|
| Bash | 在独立上下文中运行命令 |
| statusline-setup | 配置状态栏 |
| Claude Code Guide | 解答 Claude Code 使用问题 |
快速入门：创建你的第一个子代理
推荐方式：使用 /agents 命令
1、打开子代理管理界面
/agents
/agents 命令提供完整的子代理管理能力：查看所有可用子代理（内置/用户级/项目级/插件）、创建、编辑、查看同名冲突时哪个生效。
2、创建用户级子代理
- 选择 Create new agent
- 选择 User-level
- 保存位置：
~/.claude/agents/（所有项目可用）
3、使用 Claude 自动生成
示例描述：
一个代码改进代理，扫描项目文件， 针对可读性、性能和最佳实践提出建议， 并给出改进示例。
Claude 会生成系统提示和初始配置，你可以按 e 手动编辑。
4、选择工具权限
- 只做代码审查 → 仅勾选只读工具
- 需要改代码 → 保留 Edit / Write
5、选择模型
推荐：Sonnet（分析能力与速度平衡）
6、选择记忆范围（可选）
- 选择 User：在
~/.claude/agent-memory/建立持久记忆，跨所有项目积累经验 - 选择 None：不保留学习成果，每次从零开始
7、保存并使用
使用 code-improver 子代理为此项目提出改进建议
子代理会独立运行并返回结果。
子代理的作用范围
子代理本质是带 YAML frontmatter 的 Markdown 文件，不同位置代表不同作用范围。
| 位置 | 范围 | 优先级 |
|---|---|---|
CLI --agents 标志 |
当前会话 | 最高 |
.claude/agents/ |
当前项目 | 高 |
~/.claude/agents/ |
所有项目 | 中 |
| 插件 agents | 插件作用域 | 最低 |
当同名子代理存在冲突时，优先级高的会覆盖低的。可通过 /agents 查看当前哪个版本生效。
使用建议
项目子代理（.claude/agents/）
- 跟代码一起提交，团队共享
- 可引用项目专属工具和领域知识
- 自动继承项目
CLAUDE.md中的编码规范和架构规则
用户子代理（~/.claude/agents/）
- 个人习惯与通用工具，跨项目生效
CLI 子代理（--agents）
- 临时测试 / 自动化脚本，不保留到磁盘
子代理配置文件结构
配置文件由两部分组成：YAML frontmatter（元数据与配置）+ Markdown 正文（系统提示）。
---
name: code-reviewer
description: Reviews code for quality, best practices, and security issues.
Invoke when the user asks to review, audit, or check code quality.
tools: Read, Grep, Glob
model: sonnet
permissionMode: default
memory: project
---
You are a senior code reviewer.
Analyze code and provide actionable feedback organized by severity: Critical / Major / Minor.
Update your agent memory with recurring patterns, conventions, and known issues you discover.
必填字段
name：唯一标识（小写 + 连字符，如code-reviewer）description：最重要的字段，Claude 是否以及何时调用该代理完全依赖于此；建议写成"何时调用 + 能做什么"的动作式描述
完整字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
name |
string（必填） | 唯一标识，也是显式调用时的名称 |
description |
string（必填） | 决定 Claude 何时自动调用此代理，务必写清楚使用场景 |
tools |
string | 工具白名单；设置后只能使用列出的工具，MCP 工具也会被排除 |
disallowedTools |
string | 工具黑名单；继承主对话全部工具，但排除列出的工具（含 MCP） |
model |
string | haiku / sonnet / opus / 完整模型 ID / inherit（默认，继承主对话） |
permissionMode |
enum | 权限行为控制（见权限模式章节） |
memory |
enum | 持久记忆范围：user / project / local（见记忆章节） |
background |
bool | 为 true 时始终以后台方式运行 |
isolation |
string | 设为 worktree 时在临时 git worktree 中运行，完全隔离主仓库 |
skills |
list | 声明在此代理启动时自动加载的 Skills 列表 |
hooks |
object | 生命周期钩子（SubagentStart / SubagentStop / PreToolUse / PostToolUse） |
tools 与 disallowedTools 的区别
| 配置方式 | 行为 | 典型场景 |
|---|---|---|
| 两者均不设置 | 继承主对话全部工具，含 MCP 工具 | 通用代理，不需要限制 |
仅设置 tools |
只能使用白名单内的工具，MCP 工具被排除 | 只读分析代理、严格约束场景 |
仅设置 disallowedTools |
继承全部工具，但排除黑名单内的工具（MCP 工具保留） | 保留 MCP 能力但禁止写操作 |
| 两者同时设置 | 先应用 disallowedTools，再从剩余工具中按 tools 筛选 |
精细控制 |
示例：只允许只读操作
--- name: safe-researcher description: Research agent with read-only access tools: Read, Grep, Glob, Bash ---
示例：继承所有工具但禁止写文件
--- name: no-writes description: Inherits every tool except file writes disallowedTools: Write, Edit ---
权限模式（务必理解）
| 模式 | 行为 | 适用场景 |
|---|---|---|
default |
正常权限提示，每次操作前询问 | 通用场景 |
acceptEdits |
自动接受文件编辑，无需每次确认 | 频繁改动文件的代理 |
dontAsk |
自动拒绝未授权操作，不中断流程 | 严格只读场景 |
bypassPermissions |
跳过所有权限检查 | 仅限完全可信、受控环境 |
plan |
只读规划模式，不执行任何写操作 | 方案制定、架构分析 |
注意：
bypassPermissions只适合完全可信的子代理。另外，子代理会继承父会话的权限模式——如果主会话开启了 bypass，所有子代理也会跟着 bypass。
持久记忆（Memory）
通过 memory 字段，子代理可以在会话之间积累知识，例如代码库规律、调试经验、架构决策等，无需每次重新探索。
| 范围值 | 存储位置 | 适用场景 |
|---|---|---|
user |
~/.claude/agent-memory/<name>/ |
代理的知识适用于所有项目（如通用代码审查规范） |
project |
.claude/agent-memory/<name>/ |
知识与项目绑定且可 git 共享（推荐默认值） |
local |
.claude/agent-memory-local/<name>/ |
知识与项目绑定但不提交 git（个人本地经验） |
配置示例：
--- 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.
使用技巧：
- 开始任务时：
请先查阅你的记忆，再开始审查 - 任务结束时：
任务完成后，把你发现的规律保存到记忆中 - 也可直接在系统提示里写入"主动维护记忆"的指令，让代理自动执行
worktree 隔离模式
设置 isolation: worktree 后，子代理会在临时 git worktree 中运行，与主仓库完全隔离。适合以下场景：
- 需要大量文件修改但不确定结果的探索性任务
- 并行跑多个方案对比，互不干扰
- 自动化测试、CI 验证等需要干净环境的操作
--- name: experimental-refactor description: Tries refactoring approaches in an isolated worktree isolation: worktree tools: Read, Write, Edit, Bash --- You are a refactoring agent working in an isolated environment. Feel free to make changes—they won't affect the main branch.
后台运行（Background）
前台 vs 后台
| 运行方式 | 行为 | 限制 |
|---|---|---|
| 前台（Foreground） | 阻塞主对话直到完成，权限提示和澄清问题会透传给你 | 无特殊限制 |
| 后台（Background） | 并行执行，不打断主对话；启动前会预先确认所需权限 | 无 MCP、无交互式澄清；权限不足时任务失败而非暂停 |
Claude 会根据任务特性自动决定前台还是后台。你也可以主动控制：
Ctrl + B：将当前运行的子代理切换到后台Ctrl + F（按两次确认）：终止所有后台代理- 在 frontmatter 中设置
background: true：该代理始终以后台方式运行 - 消息开头加
&：将该任务作为后台任务发送给 claude.ai 网页端 - 通过
/tasks命令随时查看后台任务进度
如需彻底禁用后台任务功能：
export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1
如需统一设置所有子代理的模型：
# 主对话用 Opus 做复杂推理，子代理用 Sonnet 节省成本 export CLAUDE_CODE_SUBAGENT_MODEL="claude-sonnet-4-6"
禁用特定子代理
如果你不希望 Claude 调用某个特定的子代理，可以在 .claude/settings.json 中将其加入 deny 列表：
{
"subagents": {
"deny": ["explore", "plan"]
}
}
生命周期钩子（Hooks）
子代理支持以下钩子事件，可用于日志、验证、通知等自动化场景：
| 钩子事件 | 触发时机 | 典型用途 |
|---|---|---|
SubagentStart |
子代理启动时 | 记录启动日志、初始化环境 |
SubagentStop |
子代理完成时 | 记录结果、触发下游任务、发送通知；字段含 agent_id 和 agent_transcript_path |
PreToolUse |
工具调用前 | 校验操作合法性，退出码 2 可阻止执行 |
PostToolUse |
工具调用后 | 格式化输出、生成变更记录 |
钩子高级用法——通过 PreToolUse 动态控制工具行为。例如，让代理只允许只读 SQL 查询：
--- name: db-analyst description: Read-only database analysis agent tools: Bash --- You are a database analyst. Only run SELECT queries. # hooks defined in .claude/settings.json: # PreToolUse on Bash -> validate-readonly-query.sh # Script exits with code 2 to block write operations
如何使用子代理
自动委托
Claude 会根据 description 字段自动判断，无需你手动指定：
帮我检查最近的代码改动质量
显式调用
在提示中明确指定代理名称：
让 code-reviewer 子代理检查最近的改动
典型使用模式
1、隔离高输出任务
使用子代理运行测试，只返回失败的测试和根因分析
2、并行研究
并行使用子代理分别分析认证模块、数据库模块和 API 模块，汇总后给出整体架构建议
3、串联子代理（流水线）
先用 code-reviewer 找问题，再用 optimizer 修复问题
串联工作流的设计原则：每个代理只做一件事，通过清晰的"输入 → 处理 → 输出 → 交接规则"定义接口。
完整流水线示例（来自 PubNub 的生产实践）：
- pm-spec：读取需求，生成工作规格，确认后标记
READY_FOR_ARCH - architect-review：验证设计约束，产出架构决策记录（ADR），标记
READY_FOR_BUILD - implementer-tester：实现代码和测试，更新文档，标记
DONE
通过 SubagentStop 钩子监听队列文件，自动触发下一个代理。
4、并行代码审查
同时启动 style-checker、security-scanner、test-coverage 三个子代理并行审查， 将审查时间从数分钟压缩到数十秒
子代理上下文与恢复
- 每次调用 = 新子代理实例（无法感知之前的调用）
- 子代理上下文独立存储，不污染主对话
- 中间工具调用和结果只留在子代理内部，主对话只收到最终摘要
- 可通过 session ID 和 agent ID 恢复继续执行（SDK 场景）
会话继续示例：
继续刚才的 code-reviewer 分析，重点看授权逻辑部分
存储位置示例：
~/.claude/projects/{project}/{sessionId}/subagents/
什么时候该用子代理？
用主对话，当：
- 需要频繁来回调整，交互性强
- 多阶段任务有强依赖关系，上下文需要连续
- 快速、小改动，启动代理的开销不值得
- 实际经验：超过 3～4 个子代理后，管理成本可能反而降低效率
用子代理，当：
- 任务自包含，可以给出明确的输入和期望输出
- 输出量很大，会显著占用主对话上下文
- 需要强约束（只读、隔离 worktree 等）
- 同类任务会重复出现，值得固化为代理
- 涉及多个独立子域，可以并行处理
注意：子代理不能再创建子代理（防止无限嵌套）。如需嵌套逻辑，请使用 Skills。
最佳实践
description 怎么写
- 用动作式描述：
当用户要求审查/分析/检查代码质量时调用 - 说明前置条件：
在规格文档确认后使用，产出架构决策记录 - 写清楚代理的边界和不擅长的场景，防止被错误调用
工具权限设计
- 只读代理（审查、审计）：
Read, Grep, Glob - 研究代理（信息收集）：
Read, Grep, Glob, WebFetch, WebSearch - 实现代理（写代码）：
Read, Write, Edit, Bash, Glob, Grep - 遵循最小权限原则，只给代理完成任务所需的工具
单一职责
- 每个代理只做一件事，给出清晰的输入/输出/交接规则
- 不要试图用一个代理包办所有事情
system prompt 建议
- 在系统提示中明确代理的性格：
请保持批判性，不要只说好话 - 指出代理的弱点和局限，避免过度自信
- 如果启用了记忆，在系统提示里写入"主动维护记忆"的指令
并行 vs 串行
- 域之间相互独立 → 并行，节省时间
- 下一步依赖上一步结果 → 串行，保证质量
- 避免为了并行而并行：10 个并行代理处理简单任务反而浪费 token 和协调成本