Claude Code Subagent 教程：什么时候该用子 Agent？怎么并行干活？

研究密集型任务

如果理解某个机制的运作方式是修改它的前提，可以让 Subagent 探索代码库并返回摘要，而不是把几十个文件的内容全都塞进对话。

判断信号： 收集 Context 需要读取几十个文件。

收益： 主对话保持整洁，收到的是整合后的发现，而不是原始内容。

多个相互独立的任务

如果需要修复多个文件中的错误、更新多个组件中的模式，或者进行互不依赖的修改，并行 Subagent 可以更快完成任务。

判断信号： 各项子任务之间没有依赖关系。

收益： 三个 Subagent 同时工作通常可以用更短的时间完成任务。

需要全新的视角

如果目标是对某项实现进行不带偏见的审查，Subagent 可以提供一张白纸，因为它不会继承主对话中的假设、Context 或盲点。

判断信号： 需要在不受对话历史影响的情况下进行验证。

收益： 获得更干净、更客观的反馈。

专业提示： /clear 命令也会重置 Context 和对话历史，提供一个同样不受偏见影响的全新起点，但代价是彻底丢失这些历史记录。Subagent 可以带来同样的新鲜视角，同时保留主对话。

提交前验证

在最终确定修改之前，可以让一个独立的 Subagent 验证实现是否为了通过测试而过度拟合，或者是否遗漏了边界情况。

判断信号： 提交代码之前值得再听取一份独立意见。

收益： 能发现因过于熟悉代码而可能被忽视的问题。

流水线工作流

如果一项任务包含多个明确阶段（即先设计，再实现，然后测试），每个阶段都能从聚焦的注意力中受益。

判断信号： 存在交接点明确的连续阶段。

收益： 每个 Subagent 都专注于自己的阶段，不会因其他阶段的 Context 而产生噪声。

‍专业提示： 当一项任务需要探索十个或更多文件，或者包含三个或更多相互独立的工作部分时，就很适合明确引导 Claude 使用 Subagent。

如何引导 Subagent 的使用

调用 Subagent 有多种方式，从简单的对话到自动化工作流不等。合适的起点取决于具体工作流；随着模式逐渐显现，还可以逐步增加复杂度。

通过对话调用

最灵活的方式就是在对话中直接要求 Claude 使用 Subagent。这适用于所有 Claude Code 界面：终端、VS Code、JetBrains、Web 和桌面应用程序。

以下自然语言表达通常能可靠地调用 Subagent：

• “使用一个 Subagent 探索这个代码库中的身份验证机制”
• “让一个单独的 Agent 审查这段代码是否存在安全问题”
• “并行研究这些内容。同时检查 API 路由、数据库模型和前端组件”
• “启动多个 Subagent，修复不同 package 中的这些 TypeScript 错误”

明确表达非常重要。请指定范围，在任务相互独立时要求并行执行，并描述期望的输出。

下面是一种有效的 Prompt 结构：

这个 Prompt 之所以有效，是因为它清楚定义了三个相互独立的任务，明确要求并行执行，并指定了输出格式。Claude 能理解其意图并启动合适的 Subagent。

有效地通过对话调用 Subagent，有以下技巧：

• 明确限定任务范围。 “探索支付机制如何运作”比“探索所有内容”更好。
• 明确要求并行处理。 可以说“这些任务可以并行运行”或“同时处理这三项任务”。
• 指定应返回的内容。 可以是摘要、具体发现或建议。明确输出格式有助于 Claude 按要求交付。
• 需要无偏见分析时，要求使用全新的 Context。 “使用一个看不到我们此前讨论的 Subagent”可以确保得到不受干扰的评估。

专业提示： 如果某个 Subagent 花费的时间较长，Ctrl+B 可以将它移至后台。它运行期间可以继续对话，完成后结果会自动显示。/tasks 命令可以显示所有正在后台运行的任务。

自定义 Subagent

如果经常需要请求同一类 Subagent（例如安全审查员、测试编写员或文档校对员），可以将其定义为自定义 Subagent，一次配置，重复使用。

之后，只要任务与其描述匹配，Claude 就会自动把任务委派给它，无需再通过 Prompt 明确要求。

自定义 Subagent 以 Markdown 文件形式保存在 .claude/agents/（项目级，可与团队共享）或 ~/.claude/agents/（用户级，可在所有项目中使用）中。每个 Subagent 都有自己的 System Prompt、工具权限，还可以选择使用自己的模型。

创建自定义 Subagent 最简单的方式是使用 /agents 命令。它会以交互方式引导完成设置，并能根据描述生成初稿。也可以手动编写该文件，例如：

完成此配置后，Claude 会自动把匹配的工作交给该 Subagent。也可以按名称调用它：“让 security-reviewer 检查暂存的修改。”

自定义 Subagent 最适合以下情况：

• 当任务匹配时，应当有一个专家可供 Claude 自动委派
• 工作能受益于范围严格限定的 System Prompt 和受限工具
• 配置需要在团队中共享或跨项目复用

专业提示： Claude 会根据 description 字段决定何时委派任务。请具体说明触发条件，而不只是能力。“在提交前审查代码中的安全问题”比“安全专家”更容易被正确匹配。

如需查看完整的配置参考，包括权限模式以及项目级和用户级 Subagent 如何交互，请参阅我们的 Claude Code Subagent 文档。

CLAUDE.md 指令

自定义 Subagent 定义了有哪些专家，而 CLAUDE.md 文件定义了 Claude 应该在什么时候调用它们。如果每次代码审查都应交给只读 Subagent，或者每个架构问题都应先触发一次研究，那么这类策略就应该写在 CLAUDE.md 中。Claude 会在每次对话开始时读取该文件，因此无须任何人记得主动提出要求，其行为就能在不同会话和团队成员之间保持一致。

在以下情况下，很适合通过 CLAUDE.md 编写 Subagent 指令：

• 代码审查应始终使用只读 Subagent
• 项目有 Claude 应遵循的特定研究模式
• 需要在不同团队成员和会话之间保持一致行为

下面是一个简单的 CLAUDE.md 文件示例，它会在满足特定条件时触发 Subagent：

使用上述 CLAUDE.md 文件后，每个代码审查请求都会自动使用定义好的模式，不再需要每次单独指定。

如需进一步了解 CLAUDE.md 文件，请参阅为你的代码库自定义 Claude Code：设置 CLAUDE.md 文件，以及我们的 Claude Code CLAUDE.md 文件文档。

Skills

对于会反复执行的复杂多步骤工作流，Skills 提供了一种可复用的接口。只需在 .claude/skills/ 中定义一次 Skill，之后即可使用 /skill-name 调用；当任务与其描述匹配时，也可以让 Claude 自动加载它。

Skills 与 CLAUDE.md 文件的区别在于作用范围。CLAUDE.md 文件始终会被加载，并影响每一次交互。Skill 则按需加载：要么因为它被显式调用，要么因为 Claude 判断当前任务与该 Skill 的 description 字段匹配。因此，对于那些应当随时可用、但不应应用于每个 Prompt 的工作流，Skills 是合适的存放位置。

Skills 很适合以下情况：

• 某些操作需要定期执行
• 不同团队成员需要使用同一个复杂操作
• 团队需要统一某些任务的执行方式

下面是一个用于全面代码审查的 deep-review Skill 示例：

在上述代码片段中，/deep-review 会按需触发由三个部分组成的 Subagent 分析。由于 description 提到了提交前审查暂存的修改，当出现相关 Context 时，Claude 也可以自动使用这个 Skill。

Skill 是一个目录，而不是单个文件。除 SKILL.md, 外，其中还可以包含供 Claude 填写的模板、展示预期格式的示例输出，或者 Claude 作为工作流一部分执行的脚本。旧版 .claude/commands/ 格式只支持单个扁平文件，因此所有内容都必须放在 Prompt 本身之中。

如需进一步了解如何在 Claude Code 中使用 Skills，请参阅我们的 Claude Code Skills 文档。

Hooks

Hooks 是用户定义的 shell 命令、HTTP endpoint 或 LLM Prompt，会在 Claude Code 生命周期的特定节点自动执行。Hooks 可以根据事件自动执行 Subagent 工作流。Hooks 会由特定操作触发，无需手动调用即可运行 Subagent 任务。

在以下情况下，Hooks 是合适的工具：

• 每次 commit 创建之前都应自动进行审查
• 安全检查应自动运行，无须任何人记得提出要求
• 类似 CI 的质量门禁应该纳入本地开发流程

下面是一个 Stop hook 示例，它会阻止 Claude 结束当前轮次，直到测试通过：

以及位于 .claude/hooks/check-tests.sh 的脚本：

Claude 完成当前轮次时，会触发 Stop 事件。该脚本会运行测试套件——如果测试失败，它会返回包含 decision: "block" 和 reason 的 JSON。Claude Code 读取这些内容后，不会允许 Claude 停止，并会把原因反馈到对话中，作为继续工作的指令。顶部的 stop_hook_active 防护可以避免无限循环：如果 Claude 已经因为先前的 stop-hook 阻止而继续工作，该脚本便会允许它退出。

Hooks 是自动化程度最高的 Subagent 编排方式。通过对话调用或使用 CLAUDE.md 指令更适合作为起点；等工作流成熟后，再考虑使用 Hooks。

如需查看完整的 Hooks 配置，请参阅 Claude Code 高级用户自定义：如何配置 Hooks或我们的 Claude Code Hooks 文档。

使用 Subagent 的实用模式

以下模式展示了如何在常见场景中引导 Subagent。

实现前先研究

在不熟悉的代码中添加功能时，先把研究工作委派给 Subagent，可以让实现讨论建立在充分信息之上，而不是边探索边讨论，例如：

收到的会是一份整合后的摘要，而不是二十个文件的原始 Context；实现讨论也能从坚实的基础开始。

并行修改

如果需要在多个文件中更新同一种模式，并行 Subagent 可以更快完成任务并保持专注，例如：

三个 Subagent 并行工作，完成时间大致与单个 Subagent 相同。每个 Subagent 都专注于自己的文件，不会因其他 Subagent 的 Context 而产生混乱或不一致。

独立审查

完成复杂实现后，让一个未受实现过程影响的 Subagent 进行验证，可以发现因熟悉代码而被掩盖的问题，例如：

审查 Subagent 会在不知道考虑过哪些权衡、否决过哪些方案或做过哪些假设的情况下评估代码。这种外部视角能够暴露主对话可能遗漏的问题。

流水线工作流

对于多阶段任务，通过明确的阶段交接串联多个 Subagent，可以让每个阶段保持专注，例如：

使用流水线工作流后，任务的每个阶段都会获得聚焦的 Context。设计 Subagent 不会被实现方面的考虑干扰，实现 Subagent 根据一份干净的规格开展工作，而测试 Subagent 则独立评估结果。

什么时候不应该使用 Subagent？

尽管 Subagent 是一项实用功能，但它们也会带来额外开销。每个 Subagent 都会启动自己的 Context、消耗 Token，并在开发者与工作之间增加一层间接关系。只有当 Context 隔离、并行处理或全新视角确实有帮助时，这些成本才值得付出。

对于规模较小或顺序依赖紧密的任务，坚持使用主对话通常更简单，例如：

• 连续且相互依赖的工作。 如果第二步需要第一步的完整输出，而第三步又同时依赖前两步，那么让单个会话处理整个链条，通常比让多个 Subagent 通过文件传递状态更简洁。
• 同一文件中的编辑。 让两个 Subagent 并行编辑同一个文件很容易引发冲突。在这种场景下，应把紧密耦合的修改放在同一个 Context 窗口中完成。
• 小型任务。 对于快速修复或聚焦的问题，委派的额外开销会超过其收益。直接在主对话中发出 Prompt 或提问即可。
• 过多的专家 Agent。 人们很容易想为所有事情都定义一个自定义 Subagent，但给 Claude 塞入过多选项会降低自动委派的可靠性。大多数团队最终只会保留少量范围明确的 Agent，而不是建立一个庞杂的 Agent 名册。
• 需要 Agent 相互协调的工作。 Subagent 会向主对话汇报，但彼此之间无法沟通。对于需要 Subagent 相互通信的任务，请使用 Agent Teams。使用 Agent Teams 时，Subagent 会跨多个独立会话协调，而不是在单个会话内部协调，因此更加重量级，成本也更高。如需进一步了解何时使用 Subagent、何时使用 Agent Teams，请参阅我们的 Claude Code Agent Teams 文档。

前面介绍的判断信号（即需要第二意见、子任务之间不存在依赖，以及需要进行大量研究）可以清楚地表明什么时候值得把任务委派给 Subagent。

从对话开始，之后再自动化

只有有意识地使用 Subagent，才能充分发挥其价值。Claude 提供的自动调用功能很有帮助，但知道何时委派研究、并行处理工作以及请求全新视角，会比完全交给偶然性带来更好的结果。

使用 Subagent 时，应从对话式 Prompt 开始。留意哪些请求会反复出现，并随着这些模式逐渐清晰而构建自动化。目标是让 Subagent 委派变得毫不费力，使你的注意力始终集中在真正重要的工作上。