Subagent详解：用Subagent把Claude Code变成一支小团队

一、为什么你的 Agent 越聊越糊涂

你可能遇到过这种情况：

刚开始，Agent 很清楚你要什么。让它改功能、查 bug、解释代码，回答都还靠谱。

但任务一复杂，它就开始"降智"了。

你让它分析几个 Log 日志、改一个 Bug，又输出了一堆搜索结果和分析结果。导致当前上下文越来越长，信息越来越杂。

到最后，你会发现 Claude Code 越用越"健忘"，回答的问题越来越不准确。

并不是模型退化了，而是上下文被污染了

上下文越长，AI 从里面找重点的成本就越高。你以为它记住了更多，实际可能是它包含了一堆已经不重要的信息，核心内容早就被稀释了。

这就好比公司的核心架构师（主 Agent），本来正在写核心架构。此时你让他去翻几万行的日志定位一个 bug。结果，改完bug，回头架构师连刚才写到哪都忘了。正确的做法是：让模块Owner（Subagent）去定位修改，告诉架构师结果就行。

Subagent 解决的就是这个问题：

把这些容易产生大量中间信息的辅助任务拆出去，让它们在自己的上下文里完成。

这样一来，主对话不再被一堆日志、搜索结果和文件内容淹没，只需要拿到 Subagent 最后回报的摘要和结论即可。

二、Subagent 到底是什么

Subagents 是处理特定类型任务的"专职 AI 助手"。

它不是简单地多开一个聊天窗口，而是一个可以被主 Agent 调用的任务执行者。

主 Agent，也就是你当前正在操作的主对话，负责理解你的目标，判断下一步该做什么。当 Claude 发现某个任务正好匹配某个 Subagent 的描述时，就会把这个任务委派给它。

Subagent 负责在自己的上下文里完成某个具体任务，并把摘要和结论返回主对话。

三、Subagent 由什么组成

一个真实的 code-reviewer Subagent 大概长这样：

---
name: code-reviewer
description: 代码审查助手。用于在代码新增或修改后审查质量、安全性和可维护性。Use proactively after code changes.
tools: Read, Grep, Glob, Bash
model: sonnet
---

你是一个资深代码审查助手。

被调用时：
1. 运行 git diff 查看最近变更
2. 聚焦已修改文件
3. 立即开始审查

审查清单：
- 代码清晰且可读
- 函数和变量命名良好
- 没有重复代码
- 合理的错误处理
- 没有暴露 secrets 或 API keys
- 已实现输入验证
- 良好的测试覆盖率
- 已考虑性能

按优先级组织反馈：
- 严重问题（必须修复）
- 警告（应该修复）
- 建议（考虑改进）

包含如何修复问题的具体示例。

Subagent 本质上是一个 Markdown 配置文件，主要分成两部分。

第一部分是文件开头的 YAML frontmatter，也就是两个 --- 之间的内容。它是 Subagent 的元数据，用来定义名称、调用时机、工具权限、模型等配置。

第二部分是 YAML 下面的正文，也就是第二个 --- 后面的内容。它会成为这个 Subagent 的系统提示词，用来规定它的角色、工作方式和输出要求。

元数据

YAML frontmatter 里，最常用的几个字段：

name：Subagent 的名字

name 是必填字段。

建议用小写字母和连字符，比如：

name: code-reviewer

它是这个 Subagent 的标识符（唯一标识）。后面显式调用时，就是通过这个名字来指定。

description：决定 Claude 什么时候调用它

description 是必填字段。

这个字段非常重要。它不只是给人看的说明文字，也是 Claude 判断是否要自动委派任务的重要依据。描述越具体，越容易被正确调用。

比如：

description: 代码助手

就太泛了。更好的写法是：

description: 代码审查助手。用于在代码新增或修改后审查质量、安全性和可维护性。

tools：限制它能使用哪些工具

tools 是可选字段。

不是所有 Subagent 都需要完整工具权限。比如代码审查只需要读文件、搜代码，可以只给：

tools: Read, Grep, Glob

如果要让它修改文件，再考虑开放 Edit、Write；如果要运行测试或命令，再开放 Bash。

也可以反过来用 disallowedTools 写黑名单：继承大部分工具，只禁用某些工具。

如果 tools 和 disallowedTools 都设置了，会先应用 disallowedTools，再从剩余工具里解析 tools。

model：指定它使用哪个模型

model 是可选字段。

有 sonnet、opus、haiku 模型可以选择，如果使用与主对话相同的模型就用 inherit。

比如代码分析、审查这类任务，可以选择 Sonnet；如果只是简单搜索和整理，可以选择更轻量的模型 haiku。在分析代码时平衡能力和速度。

这里先理解这几个最常用的字段就够了。更多字段，比如 permissionMode、memory、hooks、isolation，可以需要时再查 Claude Code 官方文档。

系统提示词

YAML 下面的内容，是这个 Subagent 的 system prompt。

它决定这个 Subagent 到底扮演什么角色、按什么流程工作、检查哪些内容、最后用什么格式返回结果。

有一个容易误解的点：Subagent 不会继承完整的主对话上下文。

它启动时会拿到自己的系统提示词、Claude 写给它的任务说明，以及一些基础环境信息，比如当前工作目录。普通自定义 Subagent 还会加载相关的 CLAUDE.md、memory 和 git 状态。

四、Subagent 能帮你解决什么问题

很多人心里最大的疑问：

"平时我在主 Agent 也能做完所有的任务，搞一个 Subagent 把它和主 Agent 拆开，到底有什么区别？这不是多此一举吗？"

Subagent 的价值，不是多了一个 AI 助手，而是把复杂任务拆成更清晰、更可控的执行单元。

如果让一个主 Agent 一个人从头干到尾，它很快就会因为要处理的事情太多，开始胡言乱语或者漏掉核心指令。

按照 Claude Code 官方文档的说法，Subagent 主要帮你解决五类问题。

上下文隔离

主 Agent 连续执行任务时，搜索结果、错误日志、中间推理、临时计划都会不断堆积在同一个对话上下文里。

随着上下文越来越长，模型就越容易漏掉重点，甚至产生幻觉和不可靠的判断。

尤其是那些过程复杂但结果可压缩的任务，比如分析长日志、搜索多文件、排查代码调用链、阅读大量测试输出。过程里会产生大量搜索、筛选、试错和判断，但主对话真正需要的，通常只是少量结论、证据和建议。

Subagent 的价值就在这里：它可以在自己的上下文里完成探索，任务完成后，只把提炼好的摘要和结论返回给主对话。那些对后续决策没价值的噪音，比如冗长日志、搜索中间页、临时分析过程，都被隔离在 Subagent 自己的上下文里。

比如：分析一段很长的日志，它可能需要先筛选错误行，再追踪相关文件，再判断可能原因。这个过程会产生大量中间信息，但主对话真正需要的，可能只有一句话：

问题集中在登录模块，疑似是 token 过期后没有正确刷新。

领域专业化

每个 Subagent 都可以有自己的系统提示词，可以被配置成某个领域里的专职角色。

比如代码审查交给 code-reviewer，测试失败分析交给 test-debugger，安全检查交给 security-reviewer，文档一致性检查交给 docs-reviewer。

这类任务适合给 Subagent 配一套固定的提示词、检查标准和输出格式。任务越聚焦，输出越稳定。

如果这类任务会反复出现，就更适合沉淀成固定的 Subagent。

最小权限授予

主 Agent 往往拥有完整权限，但不是所有任务都需要完整权限。

比如代码审查、日志分析、安全检查，很多时候只需要读文件、搜代码、跑命令，不一定需要修改文件。这个时候就可以给 Subagent 更小、更明确的工具权限。

比如一个 code-reviewer，只给它读取和搜索能力就够了：

tools: Read, Grep, Glob

需要修改文件时开放 Edit、Write，需要跑测试或命令时再开放 Bash。

通过权限隔离，即使某个 Subagent 行为异常，影响范围也会被限制在它自己的工具权限内。

这就是权限的最小化授予：需要什么，才给什么。

权限要足够小，但必须够用。权限隔离可以降低风险；但如果权限小到无法完成任务，Subagent 也只能给出不完整判断，最后还是要转回主 Agent。

模块化复用

当 Subagent 以文件形式存在后，它就不再只是一次临时对话，而是一份可以复用的配置。

如果是项目专用的 Subagent，可以放在当前项目的 .claude/agents/ 目录里，跟代码一起纳入 Git 管理，方便团队共享和迭代。

比如一个团队可以在项目里维护这样一组 Subagent：

.claude/agents/
├── code-reviewer.md      # 代码审查
├── debugger.md           # 分析、修复问题
├── data-scientist.md     # 数据科学家
├── db-reader.md          # 数据库查询验证器
└── security-reviewer.md  # 安全检查

这些配置可以放进 Git，跟着项目一起管理。团队成员拉取项目后，就能使用同一套 Subagent。

如果是个人通用的 Subagent，比如代码审查、日志分析、测试失败排查，可以放在 ~/.claude/agents/，这样多个项目都能复用。

此时，Subagent 就变成了一种可共享、可迭代的工程资产。

模型成本控制

不同 Subagent 可以使用不同模型。

比如代码分析、代码审查这类任务，可以选择 Sonnet，在能力和速度之间取得平衡；

如果只是简单搜索、信息整理、初步扫描，则可以选择更轻量的模型。

复杂推理、架构设计、安全审查，再交给能力更强的模型。

这样主对话可以保留在更适合复杂决策的模型上，而一些边界清楚的辅助任务，则交给配置成本更低模型的 Subagent 处理。

五、Claude Code 的内置 Subagent

Claude Code 本身已经内置了一些 Subagent，在合适的时候会自动调用。

官方文档里提到，内置 Subagent 会继承主对话的权限，但会额外加上一些工具限制。比如有些 Subagent 只能读，不能改。

最常见的是这三个：

Explore：负责找代码

它是一个快速、只读的 Subagent，适合做文件发现、代码搜索、调用链分析。

比如你问："这个方法在哪里被调用？""这个功能入口在哪？"这类任务就很适合交给 Explore。

Plan：规划模式

它主要在 Claude 进入 Plan Mode（规划模式）时被自动调用。

当 Claude 需要理解代码库、收集上下文时，它会派 Plan 去执行这些具体的只读调研工作。（注：subagents 不能创建其他 subagents）

general-purpose：负责复杂任务

当任务既需要探索又需要修改、需要较复杂的推理来解释结果，或包含多个相互依赖的步骤时，Claude 会委派给 general-purpose。

除了这几个，Claude Code 还有一些更具体的辅助 Agent，比如 statusline-setup 和 claude-code-guide。这些通常会自动触发，你不用特别关心。

这里就不展开所有细节了。想看完整说明的话，可以去翻 Claude Code 官方文档里的 Built-in subagents 章节。

六、创建一个自己的 Subagent

创建 Subagent 有几种方式。

你可以直接手动创建文件，在 .claude/agents/ 目录下新建一个 Markdown 配置；也可以在启动 Claude Code 时通过 --agents 参数传入配置。后者只在当前会话中生效，不会保存到磁盘。

不过，对大多数人来说，最方便的方式还是直接在 Claude Code 的交互界面里输入 /agents

它会打开一个可视化的 Subagent 管理界面，你可以在里面创建、编辑和删除 Subagent。

根据引导，具体步骤大概是这样：

步骤 1：交互界面输入 /agents

它会打开 Subagent 管理界面。

步骤 2：选择 Create new agent

切换到 Library 标签页，选择 Create new agent。

步骤 3：选择存放位置

实际最常用的就是两个位置：

• Project ：保存到当前项目的 .claude/agents/，适合为当前项目定制的 Subagent，也方便团队共享。
• Personal ：保存到 ~/.claude/agents/，适合代码审查、日志分析这类通用能力，可以在自己的多个项目中复用。

需要注意的是，Claude Code 识别 Subagent 主要看 name 字段，不是文件名。

如果用户级和项目级里有同名 Subagent，项目级会优先生效。

所以，通用能力放用户级，项目专用能力放项目级；命名时尽量具体，避免不同位置出现同名配置。

步骤 4：选择创建方式

这里有两种方式：Generate with Claude 和 Manual configuration。

Generate with Claude 会根据你的描述，自动生成 Subagent 的标识符、描述和系统提示词；Manual configuration 则需要你手动填写这些内容。

两种方式后面的流程基本一样，都会继续选择工具、模型和保存位置。

为了降低上手成本，这里我们选择 Generate with Claude。

选择 Generate with Claude 后，你只需要告诉 Claude 这个 Subagent 是干什么的，什么时候应该使用它。如：

一个代码改进的Agent，通过扫描文件，在可读性、性能和最佳实践方面提出改进建议。它应该解释每个问题、展示当前代码，并提供优化后的版本。

步骤 5：选择工具

这一步很关键。

如果它只是做代码审查，通常只需要只读工具，比如 Read、Grep、Glob。

如果它要负责修改文件，才考虑给 Edit、Write；如果需要运行测试或命令，再开放 Bash。

不要一上来就给所有权限。

步骤 6：选择模型

根据任务复杂度选择模型。

比如代码分析、审查这类任务，可以选择 Sonnet；如果只是简单搜索和整理，可以选择更轻量的模型 haiku。在分析代码时平衡能力和速度。

步骤 7：选择背景颜色

为Subagent选择背景颜色，作用：在后续的终端交互或日志输出中，当有多个智能体协同工作时，系统会用不同的颜色来高亮区分谁在说话。

此时，底部的 Preview: 中的 code-improvement-advisor，就是系统生成的Subagent标识符（name）。

步骤 8：配置持久记忆

• Project scope -- 保存到项目级别
• None -- 不保存
• User scope -- 保存到用户级别
• Local scope -- 保存到本地级别

这里的记忆范围和前面的存放位置不是同一个概念。存放位置决定 Subagent 配置文件放在哪里；记忆范围决定它是否保存长期记忆，以及记忆保存到项目级、用户级还是本地级。

步骤 9：确认配置并保存

大功告成！最后检查 name、description、工具权限、模型和系统提示词。确认没问题后保存，这个 Subagent 就可以使用了。

默认生成是英文的，如果要转成中文，告诉AI转中文即可（但是要告诉 AI 不要翻译关键字）。

七、Subagent 如何使用

Subagent 创建好以后，接下来的问题就是：怎么启动它，以及启动后它怎么运行。

启动方式

第一类：自动委派

Claude 会根据当前请求中的任务描述 、subagent 配置中的 description 字段 以及当前上下文判断要不要把任务交给它。

注意：如果你希望 Claude 更主动 地把任务交给某个 Subagent，description 就要写得明确一些。

官方文档也建议，可以在描述里加入类似 use proactively 的表达（如"Subagent 由什么组成"章节的例子），告诉 Claude：遇到这类任务时可以主动使用它。

第二类：显式调用

显式调用，就是你直接告诉 Claude 使用哪个 Subagent。

1. 自然语言

通过自然语言直接说 Subagent 的名字，Claude 决定是否委派：

使用 test-runner subagent 修复失败的测试
让 code-reviewer subagent 查看我最近的变更

2. @-mention

使用@选择Subagent，可以确保运行指定 Subagent，而不是由 Claude 自行选择：

# 通过提示中选择
@"code-reviewer (agent)" 查看 auth 变更

# 不使用提示，手动输入
`@agent-<name>`

如果是插件中的Subagent，提示类似这样：my-plugin:code-reviewer

第三类：会话级使用

前面说的都是在当前主对话里调用 Subagent。

还有一种方式，是直接启动一个以某个 Subagent 为主配置的新会话。这个会话会使用该 Subagent 的系统提示词、工具限制和模型。

claude --agent code-reviewer

# 对于插件提供的 subagent，你可以只传 agent name，Claude Code 会找到它：
claude --agent security-reviewer

# 如果有重名，请传入作用域名称来避免歧义
claude --agent my-plugin:security-reviewer

如果每次启动会话都希望启动 Subagent，可以将 Subagent 配置到 .claude/settings.json 中：

{
  "agent": "code-reviewer"
}

如果 CLI flag 和 setting 同时存在，CLI flag 会覆盖 setting。

运行方式

Subagent 启动后，有两种运行方式：前台运行和后台运行。

前台运行

前台运行时，主对话会被阻塞，直到 Subagent 完成并返回结果。

如果过程中需要权限确认，也会直接提示你。

这种方式适合那些结果会影响下一步决策的任务，比如代码审查、测试失败分析、日志排查。

后台运行

后台运行时，Subagent 会和主对话并发执行，主对话不会被阻塞。你可以一边让它跑完整测试并整理失败原因，一边继续在主对话里完善实现方案。

后台运行适合耗时较长、相对独立、暂时不影响主线决策的任务。

你可以直接告诉 Claude：

把这个日志分析任务放到后台跑

也可以在运行过程中按 Ctrl+B，把当前 Subagent 切到后台。

需要注意的是，后台 Subagent 只能使用当前会话里已经授权的权限。如果遇到本来需要你确认的工具调用，会自动拒绝。

如果后台任务因此失败，可以用同样的任务重新启动一个前台 Subagent，让它正常弹出权限确认。

继续之前的 Subagent

有一个容易忽略的点：每次调用 Subagent，默认都会启动一个新的独立上下文。也就是说，它不会天然记得上一次审查时看到的所有内容。

如果你希望它接着上一次的工作继续，而不是重新开始，可以明确告诉 Claude：继续之前那个 Subagent 的任务。比如：

继续刚才那个 code-reviewer 的审查，现在重点看授权逻辑。

这样 Claude 才会尝试恢复之前的 Subagent，而不是重新启动一个新的实例。

底层实现上，Claude 会通过 agent ID 找到之前的实例；日常使用时，你通常不需要手动处理这个 ID。

八、什么时候用 Subagent，什么时候留在主对话

Subagent 不是越多越好。

每次启动 Subagent，都需要分发任务、收集上下文、等待它返回结果。用对了是分工，用错了就是额外开销。

按照 Claude Code 官方文档的建议，是否使用 Subagent，主要看下面几类情况。

适合交给 Subagent 的任务

第一，任务会产生大量输出，但主对话不需要保留这些中间内容。

比如跑测试、分析长日志、搜索大量文件、阅读一堆文档。这类任务会产生很多中间信息，但主对话真正需要的，通常只是结论、证据和下一步建议。

第二，需要明确限制工具或权限。

比如代码审查、安全检查、日志分析。它们很多时候只需要读文件、搜代码、跑命令，不一定需要修改文件。交给 Subagent 后，可以只开放必要工具，降低误操作风险。

第三，任务相对独立，最后能返回摘要。

比如认证模块、数据库模块、API 层可以分别调查，再由主 Agent 汇总结论。只要这些任务边界清楚、彼此不强依赖，就可以交给不同 Subagent 处理，甚至并行执行。

能不能并行，不是判断是否使用 Subagent 的核心标准。真正要看的是任务边界是否清楚、能否独立完成、最后能否返回可汇总的结论。

适合留在主对话的任务

第一，需要频繁沟通。

比如一边设计方案，一边不断确认取舍。这类任务需要持续共享上下文，拆给 Subagent 反而会增加沟通成本。

第二，多个阶段强依赖同一段上下文。

比如规划、实现、测试连续推进，而且每一步都依赖前面的细节。这种任务更适合留在主对话里完成。

第三，只是一个快速小改动。

比如改一行代码、查一个变量、解释一小段逻辑。启动 Subagent 也有成本，小任务直接让主 Agent 做就行。

第四，对响应速度很敏感。

如果你需要马上得到反馈，Subagent 未必合适。它会从新的上下文开始工作，可能还要先花时间补齐背景信息。

如果你只是想复用一套提示词或工作流程，并且希望它直接运行在主对话上下文里，那更适合用 Skill，而不是 Subagent。

注意事项

被主对话派出去执行任务的 Subagent，不能再创建新的 Subagent。

Claude Code 不支持 Subagent 继续分派其他 Subagent。如果一个复杂流程需要多个 Subagent，应该由主对话负责串联和汇总。

九、小结

到这里，我们已经掌握了 Subagent 的核心概念、配置方式、创建流程和使用边界。

真正用好 Subagent 的关键，不是创建很多 Agent，而是把边界清楚、过程繁重、结果可汇总的任务拆出去，让主对话负责目标判断和最终决策。

当你把代码审查、日志排查、安全检查等能力沉淀成固定 Subagent 后，Claude Code 就不再只是一个聊天窗口，而更像一支可以协作的小团队。

公众号：澄旭