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

您可能遇到过类似情况： 刚开始，Agent 很清楚地知道您需要什么。让它改功能、查 Bug、解释代码，回答都还比较可靠。 但任务一复杂，它就开始“降智”了。 您让它分析几条日志、修改一个 Bug，同时又输出了一大堆搜索结果和分析结果。当前上下文越来越长，信息越来越杂乱。 到最后，您会发现 Claude Code 越用越“健忘”，回答的问题越来越不准确。 这并不是模型退化了，而是上下文被污染了。 上下文越长，AI 从里面精确提取重点的难度就越高。您以为它记住了更多信息，实际上可能塞满了大量已经无关紧要的内容，核心信息早就被稀释了。 这就好比公司的核心架构师（主 Agent），本来正在编写核心架构。此时您让他去翻几万行的日志定位一个 Bug。结果，改完 Bug 后，架构师连刚才写到哪都忘了。正确的做法是：让模块负责人（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 自己的上下文里。 比如：分析一段很长的日志，它可能需要先筛选错误行，再追踪相关文件，再判断可能原因。这个过程会产生大量中间信息，但主对话真正需要的，可能只有一句话。 ### 领域专业化 每个 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-` ``` 如果是插件中的 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 就不再只是一个聊天窗口，而更像一支可以协作的小团队。