Claude Code Subagents 实战：什么时候该用 Agent，什么时候不该用

Claude Code 里的 Agent / subagent 很容易被误用。很多人一看到“可以派 Agent 并行干活”，第一反应就是：那是不是所有任务都应该分给多个 Agent？实际项目里恰好相反：Agent 是放大器，不是默认模式。任务边界清楚、输出可以独立验收，它才有价值；边界不清楚、需要连续确认、涉及高风险写入时，Agent 反而会制造更多返工。

这篇文章不把 subagent 当成炫技功能介绍，而是从真实开发任务出发，回答三个问题：哪些任务适合交给 Agent，哪些任务应该留在主上下文里直接做，以及怎么验收 Agent 的结果。

如果你还没熟悉基础用法，可以先看 Claude Code 怎么用：新手从安装到完成第一次改代码；如果任务需要先做方案确认，再参考 Claude Code Plan Mode 实战。

什么是 Claude Code 里的 Agent / Subagent

在 Claude Code 的工作流里，Agent 可以理解为一个被派出去完成特定子任务的独立执行者。它通常有自己的上下文窗口，可以读文件、搜索代码、整理结论，最后把结果返回给主会话。

它和主会话的区别不是“更聪明”，而是：

所以不要把 Agent 当成“自动完成所有事情”的黑盒。更准确的心态是：你让它去查一块区域、审一个维度、补一类测试，然后主会话负责判断能不能采纳。

使用 Agent 前先问 5 个问题

每次想派 Agent 之前，先问自己：

1. 这个子任务能不能独立完成？
2. Agent 的输出是不是可以被主会话快速验证？
3. 它是否需要修改文件？如果需要，是否有明确边界？
4. 如果 Agent 结果错了，会不会导致高成本返工？
5. 主会话是否已经清楚最终目标和验收标准？

如果这 5 个问题有两个以上答不上来，就不要急着派 Agent。先在主会话里澄清需求，或者进入 Plan Mode 做设计。

适合交给 Agent 的 5 类任务

1. 大范围只读代码搜索

这是最适合 Agent 的场景。比如你要知道“项目里所有和登录态相关的文件在哪里”“某个配置从哪里被读取”。主会话自己也能搜，但大量文件会占用上下文。Agent 可以专门负责搜索和总结。

适合的 prompt：

1
2
3

请只读搜索这个项目中和 authentication/session/login 相关的实现。
不要修改文件。
输出：入口文件、关键函数、调用关系、可能影响修改的文件列表。

注意重点是“只读”和“输出结构”。不要让 Agent 搜完顺手改。

2. 独立代码审查

代码审查也适合 Agent，因为它可以按维度独立判断。比如一个 Agent 看正确性，一个看性能，一个看测试覆盖。

更好的方式不是让三个 Agent 都泛泛说“review this code”，而是给清晰维度：

1
2
3
4

你只审查这次改动的正确性 bug。
忽略命名和格式。
只报告能复现或有明确代码证据的问题。
每个问题给出文件、行号、触发条件和建议修复方向。

这类任务的好处是输出可以被主会话复核，不会直接改变代码。

3. 测试补充和用例设计

如果你已经完成实现，可以让 Agent 从测试工程角度看缺口：边界值、失败路径、回归场景、用户输入异常。

不要直接说“帮我写测试”，可以说：

1
2
3
4

请分析当前实现缺少哪些关键测试。
只列测试计划，不写文件。
按高风险、中风险、低风险排序。
每个测试说明输入、期望输出和为什么重要。

这样主会话可以先判断测试计划是否合理，再决定是否写入文件。

4. 文档、迁移点和影响面清单

跨模块改动前，Agent 可以帮你整理影响面。例如函数签名改了，会影响哪些调用方；组件 props 改了，会影响哪些页面。

这类任务和 Claude Code Plan Mode 很配：主会话先规划，Agent 去补充影响面，最后主会话整合。

5. 并行调研和对比

如果你要比较几个方案，比如不同库、不同部署方式、不同 API 接入方式，可以让多个 Agent 分别调研一个选项。但最终取舍必须回到主会话。

例如：

1
2
3

你只研究方案 A 的落地成本。
不要比较方案 B/C。
输出：依赖、集成步骤、风险、验证方法、适合/不适合场景。

这样可以避免多个 Agent 互相重复，结果也更容易合并。

不适合交给 Agent 的 5 类任务

1. 用户意图还不清楚的任务

如果用户只是说“这个页面不好看”“内容质量不行”“优化一下性能”，不要马上派 Agent。Agent 会把不清楚的意图扩散成多个猜测，最后主会话还要收拾。

这时应该先问清楚目标，或给出可选方案。

2. 需要连续交互确认的 UI 决策

UI 调整经常需要来回看效果：间距、视觉层级、按钮位置、文案长度。如果 Agent 在独立上下文里改，很容易和用户真实偏好错开。

比如“把选项排版得好看一点”，这类最好主会话直接改、用户刷新看，再继续微调。

3. 高风险写操作

删除文件、迁移目录、改自动发布脚本、改认证逻辑、写外部平台提交脚本，都不适合直接交给 Agent 独立写。最多让 Agent 做只读风险分析。

主会话必须保留最终写入控制权。

4. 简单单文件修改

如果只是改一个 title、修一个按钮样式、补一行配置，派 Agent 是浪费。它会增加上下文和等待成本，还可能把简单任务复杂化。

简单任务直接做，复杂任务再拆分。

5. 需要统一口径的最终写作

文章、产品说明、对外文案、最终 PR 描述，都需要统一口吻和判断。Agent 可以做资料收集、审稿和问题发现，但最终稿最好由主会话整合。

否则很容易出现多个 Agent 写出来的段落风格不同、论点重复、结论不一致。

怎么写一个靠谱的 Agent prompt

一个靠谱的 Agent prompt 至少包含 6 个部分：

1
2
3
4
5
6

任务：你要完成什么？
范围：只看哪些目录/文件/主题？
禁止：不能做什么？比如不要修改文件、不要跑外部命令。
输出格式：表格、列表、JSON、结论摘要？
证据要求：需要文件路径、行号、引用还是复现步骤？
验收标准：什么结果算完成？

可复制模板：

1
2
3
4
5
6
7
8
9
10
11
12

请作为一个只读分析 Agent 完成以下任务：

目标：分析 <具体问题>。
范围：只检查 <目录/文件/模块>。
禁止：不要修改文件，不要运行会改变状态的命令，不要假设不存在的配置。
输出：
1. 结论摘要（3-5 条）
2. 关键证据（文件路径 + 行号）
3. 风险或不确定项
4. 建议下一步

如果证据不足，请明确说“无法确认”，不要编造。

这比“帮我看看这个问题”稳定得多。

Agent 输出怎么验收

Agent 输出不能直接当结论。至少做这 4 步：

1. 看范围是否符合要求：有没有越界读无关目录？
2. 看证据是否具体：有没有文件、行号、命令结果或明确来源？
3. 看结论是否可复现：bug 能不能触发？建议能不能落地？
4. 看是否需要主会话二次验证：尤其是写入、删除、发布、外部动作。

如果 Agent 只给“我认为”“可能”“建议优化”但没有证据，就当作线索，而不是结论。

一个实际开发流程示例

假设你要重构一个支付页面的表单校验。

不推荐这样做：

1

派几个 Agent 帮我重构支付页面。

更稳的流程是：

1. 主会话先明确目标：只改校验，不改支付接口；
2. 一个 Agent 只读搜索表单、schema、错误提示和测试；
3. 一个 Agent 审查潜在风险：支付状态、金额字段、异步提交；
4. 主会话整合结果，写计划；
5. 主会话执行代码修改；
6. 必要时再让 Agent 做代码审查；
7. 主会话跑测试和验证。

这个流程里，Agent 负责扩展视野，主会话负责决策和写入。这样既利用了并行能力，又不会把控制权交出去。

Agent、Workflow 和 Plan Mode 的边界

很多人会把这几个概念混在一起：

如果只是一次普通开发任务，不要为了“看起来高级”强行上 Workflow；如果只是小修，也不要开 Agent。

常见失败案例

失败 1：Agent 没有限定只读

结果：Agent 直接改了文件，主会话不知道它改了什么。

修正：prompt 里明确“不要修改文件”，写入必须回到主会话。

失败 2：多个 Agent 做同一件事

结果：三份重复结论，浪费 token。

修正：每个 Agent 分配不同维度，例如“正确性”“测试缺口”“性能风险”。

失败 3：Agent 输出没有证据

结果：主会话无法判断真假。

修正：要求文件路径、行号、复现条件或来源链接。

失败 4：把最终决策交给 Agent

结果：多个 Agent 结论冲突，主会话失去统一口径。

修正：Agent 只提供证据和建议，最终判断由主会话完成。

总结

Claude Code Subagents 的价值不在“把任务丢出去就不用管”，而在于把大任务拆成可验证的小任务。适合 Agent 的任务通常是只读、独立、可复核的；不适合 Agent 的任务通常需要连续确认、高风险写入或统一最终口径。

真正稳定的 Claude Code 工作流是：主会话负责目标、边界和验收，Agent 负责搜索、审查、调研和补充视角。Agent 用得越克制，结果反而越可靠。