Claude Code 子代理：何时以及如何运行智能体团队

上次更新: June 28, 2026

Claude Code subagent 是一个独立的 Claude 会话，主代理会为完成一项专注任务而启动它，然后将结果折叠回你的工作流中。上周我并行部署了三个这样的子代理，用于将一次重构拆分为 schema、API 和测试部分，它们在单个长会话完成规划之前就完成了。本文介绍了如何定义和调度子代理、我用来模拟小型团队的编排模式，以及子代理成本超过其节省效益的临界点。

快速答案：什么是 Claude Code subagent？

子代理是一个拥有自己上下文窗口、自己系统提示词和狭窄工具集的 Claude 实例。主会话在运行它时不会丢失上下文，因为子代理是在隔离环境中工作的，并且只返回摘要。你可以把它想象成将任务委托给了一位永远不会打断你屏幕的队友。

官方机制很简单。你将一个带有 YAML frontmatter 的 markdown 文件放入 .claude/agents/ 中，当一个任务符合其描述时，Claude Code 可以通过 Task tool 调用它。sub-agents documentation 是字段的权威来源，而 Claude Code repo 则跟踪格式的变化。

一个最小的子代理定义如下：

---
name: migration-writer
description: Writes and runs database migrations for this repo. Use for schema changes.
tools: Read, Edit, Bash
model: inherit
---
You are a migration specialist. Always check existing migrations first, never drop columns without a confirmation step, and run the migration against the local DB before reporting done.

一旦该文件存在，我就会要求主代理“使用 migration-writer 子代理添加 orders 表”，它就会调度一个范围受限的工作进程，而不是在行内笨拙地处理。model: inherit 这一行保持了成本和质量与主会话一致；如果在一个以读取为主的子代理上固定一个更便宜的模型（如 haiku），这是一个非常有效的杠杆点，尤其当你运行大量子代理时。

何时应该使用子代理而不是单个会话？

当任务是长时间运行的、上下文密集型的或需要主会话中不包含的工具集时，就应考虑使用子代理。如果工作量较小、与你正在做的事情紧密耦合，或者需要与你进行频繁的来回沟通时，则保持在一个会话中即可。

我使用子代理处理那些否则会用日志、大量读取或反复尝试和错误污染我的主上下文的工作。对整个代码库进行审计而 greps 200 个文件就是一个完美的候选对象，因为子代理会读取所有内容并返回一份两段式的摘要，而我的主会话保持干净。

如果你对代理本身是新手，Claude Code ultimate guide 在你添加子代理之前涵盖了基础知识。

如何在 Claude Code 中调度子代理？

调度的方式有两种。主代理可以在任务符合子代理描述时自行调用 Task tool，或者你可以在提示词中明确命名它。我更喜欢明确命名，因为隐式调度有时会跳过我想要的某个代理。

一些我经常使用的模式包括：

• "Use the code-reviewer subagent on the diff in this branch, then apply its suggestions."（使用此分支的差异上的代码审查子代理，然后应用其建议。）
• "Dispatch migration-writer to add a users.email_verified column, and dispatch test-writer to cover it. Run both."（调度 migration-writer 添加一个 users.email_verified 列，并调度 test-writer 来覆盖它。运行两者。）
• "Spin up the api-docs subagent against src/routes/ and return only the OpenAPI skeleton."（针对 src/routes/ 启动 api-docs 子代理，只返回 OpenAPI 骨架。）

子代理在自己的上下文中运行，因此除非你在提示词中传递细节，否则它看不到你正在进行中的对话。这种隔离性就是重点。当它完成时，你会得到一个结果，而不是一串中间噪音的流。

我用于团队式工作流的模式

诀窍是模仿真实团队的工作拆分方式，然后将每个角色映射到一个子代理。以下是我反复使用的模式。

研究，然后发散。 我调度一个子代理来收集上下文，阅读其摘要，然后针对共享接口调度多个实现子代理。这模拟了技术负责人在分配任务之前进行范围界定。

基于合同构建。 首先定义 API 或组件属性（props），然后并行运行一个后端子代理和一个前端子代理，它们都以该合同为基础。两者互不阻塞，冲突很少发生，因为它们触及不同的文件。

作为独立角色审查。 我保留了一个只具有读取工具的代码审查子代理。在进行任何非平凡的更改后，我都会让它针对差异（diff）运行。限制其工具意味着它根本无法编辑，从而保持了审查的客观性。

对于这种可重复的工作流程，可以将子代理与 Claude Code skills 结合使用：一个 skill 来编码步骤，而子代理则执行隔离工作。如果子代理需要外部数据，就按照 Claude Code MCP integration guide 的描述将其连接到 MCP 服务器。

一个实战示例：订单和支付

上个月，我将一个包含订单和支付的功能拆分成了三个子代理，它们都基于一个类型化的合同。该合同是一个针对 Order 的单个 TypeScript 接口，包含 status、totalCents 和 paymentId。我调度了：一个后端子代理来实现订单创建和状态转换；一个 payments 子代理来连接 Stripe 调用并存储 paymentId；以及一个测试子代理来覆盖正常路径和退款的边缘情况。所有三个都触及了不同的文件，因此合并只是三次干净的复制粘贴操作，而不是一次冲突解决会话。整个运行耗时 14 分钟；而前一周在单个串行会话中完成相同的工作则需要 41 分钟，因为单一上下文不断重新加载 Stripe 文档。

如何在不丢失上下文的情况下编排并行工作？

主会话是你的协调员。它的工作是分解任务、分配范围受限的提示词，并将结果重新粘合在一起。保持协调员精简，让子代理承担大量的读取工作。

对我来说，典型的并行运行流程如下：

1. 在主会话中编写合同和文件边界。
2. 调度两个到四个子代理，每个都有一个切片和一个明确的成功条件。
3. 读取每个返回的摘要，而不是在运行过程中阅读。
4. 在主会话中合并，自己解决接缝处的问题。
5. 最后让测试子代理针对集成后的结果运行。

只有当这些切片真正独立时，并行化才会发挥作用。如果两个子代理都编辑了 schema.prisma，那你就没有拆分工作，而是制造了一个合并问题。在文件和合同上画出边界，然后在提示词中强制执行它们。

子代理何时会增加超过其节省的开销？

子代理增加了延迟、tokens 和协调成本。摘要传递会导致细节丢失，因此任何需要深度连续性的场景都不适合使用。在求助于它们之前，要对这种权衡保持诚实。

我曾经在一个功能分支上运行了一个基准测试：每个微服务一个子代理，对比单个会话按顺序处理它们。对于五个松散耦合的服务，并行模式在实际时钟时间上领先了约 40%。但对于三个共享数据模型的服务，单个会话更快，因为合并和重新解释消耗掉了并行带来的优势。

经验教训是：并行化奖励独立性并惩罚耦合性。如果你的切片共享状态，就不要将其并行化。

常见的错误是什么？

• 子代理过多。 我将一次运行限制在三到五个。超过这个数量，协调成本就会超过并行带来的收益。
• 提示词模糊。 "Fix the auth"（修复认证）会失败。"Add a JWT refresh endpoint at /auth/refresh, returning { token }, with a test"（在 /auth/refresh 添加一个返回 { token } 的 JWT 刷新端点，并附带测试）则成功。
• 没有成功标准。 说明“完成”意味着什么。“Migration applied locally and rollback tested”（迁移已本地应用且可回滚）优于“handle the schema”（处理模式）。
• 工具集错误。 给审查者只提供读取工具。给部署代理它需要的确切命令，不要更宽泛的权限。
• 忽略失败。 如果子代理返回了错误，请阅读它。盲目重试会消耗 tokens 并掩盖真正的问题。
• 跳过合并。 子代理返回结果；你仍然负责集成。为它分配实际的时间。

最昂贵的错误是将子代理视为任何事情的免费并行化工具。它们是位于摘要边界后的范围受限工作进程，而这个边界是有成本的。

总结

子代理将 Claude Code 变成了一个感觉像小型团队的东西：一个精简的协调员调度范围受限的工作进程，每个工作进程都携带自己的上下文并报告结果。在 .claude/agents/ 中定义它们，使用 Task tool 调度它们，并通过将大量读取和重复角色推入子代理来保持主会话的干净。

当工作时间长、上下文密集或需要限制工具集时使用它们。对于总结传递丢失太多细节的短小、耦合、交互式任务，请跳过使用它们。在文件和合同上画出边界，将一次运行限制在少数几个代理，并始终预留时间自己合并结果。

一个真正的注意事项是：子代理增加的是吞吐量，而不是判断力。它们会快乐地在四个隔离的上下文中并行构建错误的东西。协调工作、合同定义和最终审查仍然落在你身上，因此杠杆效应只有在切片真正独立且成功标准精确时才会体现出来。如果你想了解驱动大量工具连接协议的更深层次背景知识，MCP explainer 是一个好的阅读材料，而 Claude Code docs 涵盖了我这里没有重复设置的部分。

图片来源

• A team of developers working together at computers in a modern tech office — photo by Rebrand Cities on Pexels
• Colorful programming code on a computer monitor — photo by inna mykytas on Pexels
• A developer writing code on a laptop in front of multiple monitors — photo by Christina Morillo on Pexels
• Two programmers focused on coding side by side in a modern office — photo by Rebrand Cities on Pexels