Claude Code子代理的使用指南，提升复杂任务效率

Claude Code 擅长处理复杂多步骤项目，但长时间会话会积累负担。每次文件读取、每次偏离主线的探索、每个未完成的想法都会留在上下文窗口中，拖慢响应速度并推高 token 成本。

考虑在大型 TypeScript monorepo 中构建新功能。主要工作是实现，但次要任务不断出现：追踪现有服务如何处理认证、查找用于日期格式化的共享工具、检查设计系统是否已有接近你需求的组件。这些都不需要完整的项目上下文，在主会话中运行这些会增加噪音。如果能让它们并行运行呢？

引入 子代理。子代理是具有自己上下文窗口的隔离 Claude 实例。它接收任务，执行工作，仅返回结果。可以把子代理想象成 Claude Code 会话中的浏览器标签页：在追求偏离主线的同时不丢失主线程。

在本文中，我们讨论何时使用子代理是合理的、如何调用它们，以及何时其开销不划算。

什么是子代理？

子代理是自包含的代理，在各自的上下文窗口中运行。当 Claude 生成子代理时，该助手独立工作来读取文件、探索代码或进行更改。完成任务后，子代理只将相关结果返回主对话。

每个子代理都是全新开始的，不受对话历史或调用技能的影响。多个子代理可以并行运行，并且每个子代理可以有不同的权限：研究子代理可能只读，而实现子代理则获得完全编辑能力。

Claude Code 包含几种内置子代理类型，包括：

• 通用代理 用于复杂的多步骤任务
• 计划代理 在提出实现策略之前研究代码库
• 探索代理 针对快速、只读代码搜索进行优化

Claude Code 通常会自行生成子代理来处理分配的任务。也可以明确引导该行为，并定义可重用的专家，让 Claude 自动委派。知道何时使用子代理才能使该功能发挥作用。

何时应该使用子代理？

某些类别的任务显然受益于子代理委派。学会识别这些任务将使该功能更加有效。

研究密集型任务

当理解某些东西的工作原理是更改它的先决条件时，子代理可以探索代码库并返回摘要，而不是将几十个文件转储到对话中。

信号：收集上下文需要读取几十个文件。

好处： 主对话保持整洁，收到的是汇总后的发现，而不是原始内容。

多个独立任务

当修复多个文件中的错误、更新多个组件中的模式或进行彼此不依赖的更改时，并行子代理能更快完成任务。

信号： 子任务之间没有依赖关系。

好处： 三个子代理同时工作通常能更快完成。

需要新的视角

当目标是对实现进行公正审查时，子代理提供干净的状态，因为它不继承主对话的假设、上下文或盲点。

信号： 需要在没有对话历史影响分析的情况下进行验证。

好处： 更干净、更客观的反馈。

专业提示： /clear 命令也会重置上下文和对话历史，提供同样公正的状态，但代价是完全丢失该历史。子代理实现了同样新的视角，同时主对话保持完整。

提交前验证

在最终确定更改之前，独立的子代理可以验证实现是否过度拟合测试或遗漏边缘情况。

信号： 提交代码前需要第二意见。

好处： 能发现因熟悉代码而可能被忽视的问题。

流水线工作流

当任务有不同阶段（例如设计、实现、测试）时，每个阶段都受益于专注。

信号： 顺序阶段且交接明确。

好处： 每个子代理专注于自己的阶段，不受其他阶段上下文带来的噪音。

‍专业提示： 当任务需要探索十个或更多文件，或涉及三个或更多独立工作时，这是强烈信号，应引导 Claude 使用子代理。

如何引导子代理的使用

存在多种调用子代理的方法，从简单的对话到自动化工作流。正确的起点取决于工作流，随着模式的出现可以逐步增加复杂性。

对话式调用

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

可靠触发子代理的自然语言模式包括：

• “使用子代理探索这个代码库中认证是如何工作的”
• “让一个单独的代理审查此代码的安全问题”
• “并行研究此问题。同时检查 API 路由、数据库模型和前端组件”
• “启动子代理修复不同包中的这些 TypeScript 错误”

明确很重要。指定范围，当任务独立时请求并行执行，并描述期望的输出。

这里有一个有效的提示结构：

这个提示之所以有效，是因为它清晰定义了三个独立任务，明确请求并行执行，并指定了输出格式。Claude 理解意图并生成适当的子代理。

有效对话式调用的提示包括：

• 清晰界定任务范围。 “探索支付如何工作”优于“探索一切”。
• 明确请求并行化。 说“这些可以并行运行”或“同时处理所有三个”。
• 指定应返回的内容。摘要、具体发现或建议。指明输出格式有助于 Claude 交付。
• 当需要公正分析时，要求提供新鲜上下文。“使用看不到我们之前讨论的子代理”可确保评估干净。

专业提示：当子代理耗时较长时，按 Ctrl+B 可将其发送到后台。对话可继续，运行完成后结果自动显示。/tasks 命令可显示后台运行的任务。

自定义子代理

当反复需要同类子代理（如安全审查员、测试编写者、文档校对员）时，可将其定义为一次自定义子代理。

之后，只要任务匹配其描述，Claude 就会自动委派给它，无需提示。

自定义子代理以 Markdown 文件形式存放在 .claude/agents/ （项目级，与团队共享）或 ~/.claude/agents/ （用户级，适用于所有项目）。每个子代理有自己的系统提示、工具权限，还可选配自己的模型。

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

有了这个配置后，Claude 会自动将匹配的工作路由给子代理。也可以按名称调用：“让安全审查员看一下暂存的更改。”

自定义子代理在以下情况下效果最佳：

• 当任务匹配时，应有专家可供 Claude 自动委派
• 工作受益于范围严格的系统提示和受限工具
• 配置应在团队间共享或在项目间复用

专业提示：描述字段是 Claude 用来决定何时委派的内容。要明确触发条件，而不仅仅是能力。“在提交前审查代码安全问题”比“安全专家”路由更好。

有关完整配置参考（包括权限模式以及项目和用户子代理如何交互），请参阅我们的 Claude Code 子代理文档。

CLAUDE.md 指令

自定义子代理定义了专家是谁。CLAUDE.md 文件定义了 Claude 何时应使用它们的规则。如果每次代码审查都应通过只读子代理，或者每个架构问题都应先触发研究，那么 CLAUDE.md 就是该策略所在。Claude 在每次对话开始时读取它，因此行为在会话和团队成员间保持一致，无需任何人记得去要求。

CLAUDE.md 适用于子代理指令的情况：

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

以下是一个简单的 CLAUDE.md 文件示例，在特定条件下触发子代理：

使用上述 CLAUDE.md 文件，每次代码审查请求都会自动使用定义的模式，无需每次都指定。

有关 CLAUDE.md 文件的更多信息，请参阅 为你的代码库自定义 Claude Code：设置 CLAUDE.md 文件 以及我们的 Claude Code CLAUDE.md 文件文档。

技能

对于反复运行的复杂多步骤工作流，技能提供了可复用的接口。在 .claude/skills/ 中定义一次技能，然后用 /技能名称 调用，或当任务匹配其描述时让 Claude 自动加载。

技能与 CLAUDE.md 文件在范围上不同。CLAUDE.md 文件始终加载并影响每次交互。技能则按需加载，要么显式调用，要么 Claude 将当前任务与技能描述匹配。因此，技能适合那些应可用但不适用于每个提示的工作流。

技能在以下情况适用良好：

• 某些操作定期运行
• 不同团队成员需要访问相同的复杂操作
• 在团队中标准化某些任务的执行方式很重要

以下是一个用于全面代码审查的深度审查技能示例：

在上面的代码片段中，/deep-review 按需触发三部分子代理分析。因为描述提到在提交前审查暂存更改，所以当该上下文出现时，Claude 也可以自动使用此技能。

技能是一个目录，而不是单个文件。除了 SKILL.md， 它还可以包含 Claude 填写的模板、显示预期格式的示例输出，或 Claude 在工作流中执行的脚本。旧版 .claude/commands/ 格式是单个平面文件，因此所有内容都必须放在提示中。

有关在 Claude Code 中使用技能的更多信息，请参阅我们的 Claude Code 技能文档。

钩子

钩子是用户定义的 shell 命令、HTTP 端点或 LLM 提示，在 Claude Code 生命周期的特定点自动执行。钩子 可以基于事件自动化子代理工作流。钩子触发特定操作并运行子代理任务，无需手动调用。

钩子在以下情况是合适的工具：

• 每次提交都应自动审查后才创建
• 安全检查应自动运行，无需任何人记得要求
• 类似 CI 的质量门禁应属于本地开发流程

以下是一个 Stop 钩子示例，它阻止 Claude 在测试通过前结束回合：

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

当 Claude 结束回合时，Stop 事件触发。脚本运行测试套件——如果测试失败，它返回带有 decision: "block" 和 reason 的 JSON。Claude Code 读取该内容，不让 Claude 停止，并将原因反馈到对话中作为继续工作的指令。顶部的 stop_hook_active 防护可防止无限循环：如果 Claude 已因先前的 stop 钩子阻止而继续，脚本会让其退出。

钩子代表了子代理编排的最自动化方法。会话式调用或 CLAUDE.md 指令是更好的起点；钩子稍后随着工作流成熟而加入。

有关完整的钩子配置，请参阅 Claude Code 高级用户自定义：如何配置钩子 或我们的 Claude Code 钩子文档。

使用子代理的实用模式

以下模式展示了子代理方向在常见场景中的应用。

先研究后实施

当向不熟悉的代码添加功能时，先委托子代理进行研究，可以使实施讨论基于信息而非探索，例如：

综合摘要会代替二十个原始上下文文件出现，实施讨论从坚实基础开始。

并行修改

当需要在多个文件中更新相同模式时，并行子代理完成更快且保持专注，例如：

三个并行工作的子代理大约在一个代理所需的时间内完成。每个代理专注于其文件，不会因其他代理的上下文造成混乱或不一致。

独立审查

在实现复杂内容后，从未受实现过程影响的子代理进行验证，可以发现熟悉性掩盖的问题，例如：

审查子代理在不知道考虑过哪些权衡、拒绝过哪些方法或做过哪些假设的情况下评估代码。这种外部视角能发现主对话可能忽略的问题。

流水线工作流

对于多阶段任务，将子代理链接起来并在阶段间进行明确交接，使每个阶段保持专注，例如：

使用流水线工作流，任务中的每个阶段都获得专注的上下文。设计子代理不会被实现问题分散注意力，实现子代理依据清晰的规格说明工作，测试子代理独立评估结果。

什么时候不应该使用子代理？

虽然子代理是一个有用的功能，但子代理会带来开销。每个子代理都会启动自己的上下文，消耗令牌，并在开发者和工作之间增加一层间接性。当上下文隔离、并行性或新视角确实有帮助时，它们值得这个成本。

对于较小或严格顺序的任务，通常坚持在主对话中处理更简单，例如：

• 顺序、依赖的工作。当第二步需要第一步的完整输出，第三步需要两者的输出时，单一会话处理链条通常比子代理通过文件传递状态的接力更清晰。
• 同一文件的编辑。两个子代理并行编辑同一文件是冲突的根源。在这种情况下，将紧密耦合的更改保留在一个上下文窗口中。
• 小任务。对于快速修复或针对性问题，委派的开销超过收益。只需在主对话中提示或询问即可。
• 太多专业代理。为每件事定义自定义子代理很诱人，但给 Claude 提供太多选项会使自动委派可靠性降低。大多数团队会选择少数几个范围明确的代理，而不是庞大的阵容。
• 需要代理相互协调的工作。子代理向主对话报告但彼此不能通信。对于子代理需要通信的任务，使用代理团队。使用代理团队时，子代理在独立会话中协调而不是在单个会话内，这使它们更重且更昂贵。有关何时使用子代理与代理团队的更多指导，请查看我们的Claude Code 代理团队文档。

前面提到的信号（即需要第二意见、子任务之间缺乏依赖以及广泛研究）清楚地表明何时值得委派给子代理。

先对话，后自动化

子代理在有意使用时能发挥全部价值。Claude 提供的自动调用很有帮助，但知道何时委派研究、并行工作和请求新视角，比放任自流产生更好的结果。

使用子代理时，从对话式提示开始。注意哪些请求反复出现，并随着这些模式清晰化构建自动化。目标是使子代理委派变得轻松，让你的注意力集中在重要的工作上。