Claude Code 多智能体并行开发实战指南

更新于 2026-07-10（agent-teams 时代版）。原发于 2025 年 9 月。

Claude Code 中的 subagent（子代理）是由你的会话生成的独立代理，用于完成一项定义明确的工作。它拥有自己的上下文窗口、自己的工具权限，可选地拥有自己的模型，并与你在进行的任何其他工作并行运行。完成后，你的主会话获得一份报告，而不是完整对话记录。

独立的工作片段同时进行，而不是依次进行。每个片段消耗自己全新的上下文，而不是挤进你试图掌控全局的那个窗口；单个会话读遍所有内容会在各处流失细节，而拥有干净上下文的专家则不会。

我每个工作日都会派遣 subagent，主要来自一个每个项目的长期存在的 orchestrator 会话——它分配工作并收集结果，而我来掌舵。接下来是 subagent 在 2026 年中期的工作方式、如何创建和调用它们、在日常使用中存活下来的最佳实践，以及并行化能达到的真实规模。

%%{init: {"look": "handDrawn"}}%%
graph TD
    O[Orchestrator session<br>holds the plan and context] --> S1[Subagent:<br>implement ticket A]
    O --> S2[Subagent:<br>implement ticket B]
    O --> S3[Subagent:<br>research the vendor API]
    O --> S4[Subagent:<br>review the diff]
    S1 --> R[Results converge]
    S2 --> R
    S3 --> R
    S4 --> R
    R --> O

一个会话分散到并行的 subagent；每个都在自己的上下文窗口中工作，然后报告总结。

Claude Code subagent 是什么（以及何时使用）

从机制上讲，派遣通过 Agent tool 进行（较早的 Claude Code 版本叫它 Task tool）。你可以让 Claude 即时启动一个通用 subagent，或定义命名的专家并按名字将工作交给他们。截至 2026 年中期，subagent 默认在后台运行：你继续在主会话中工作，Claude Code 在其中一个完成时通知你，你可以给特定代理发消息，让它继续用完整的上下文工作，而不是从头开始。一批重复出现的命名代理行为更像一个小型常设团队，而不是一次性流程。

当工作会淹没你的主上下文时，使用 subagent：全代码库搜索、供应商文档、一天的日志。当一个任务分成独立片段时，使用多个，每片一个代理。当一个角色必须不与它所判断的工作共享上下文时，故意使用一个；写过代码的审阅者在给自己改作业。

当你已经知道文件和问题时，跳过这些机制，因为直接阅读优于派遣。对于你想逐步引导的工作，以及编辑到处纠缠以至两个代理会互相重写文件的情况，也要跳过它。

Subagent 也常与 skill 混淆，但区别很重要，因为两者可以组合。Skill 是一个加载到代理上下文中的 markdown 文件，记录了流程知识：如何发货一个功能、如何组织备忘录。Subagent 是拥有自己上下文的另一套手。我的构建 subagent 加载我的主会话使用的相同 skill。

%%{init: {"look": "handDrawn"}}%%
graph TD
    W[New piece of work] --> K{Process knowledge the<br>agent should follow?}
    K -- yes --> SK[Write a skill]
    K -- no --> H{Independent enough to<br>hand off whole?}
    H -- no --> M[Keep it in the<br>main session]
    H -- yes --> L{Hours or days of work<br>on its own branch?}
    L -- no --> SA[Dispatch a subagent]
    L -- yes --> WT[Separate Claude Code instance<br>in a git worktree]

Skill 教授流程，subagent 增加人手，单独实例增加完整的工作流。

如何在 Claude Code 中创建 subagent

命名的 subagent 是 markdown 文件：仓库中的 .claude/agents/ 用于项目专家，~/.claude/agents/ 用于你想处处使用的。会话内的 /agents 命令以交互方式创建和编辑它们，但 git 中的文件是你可以审阅和回滚的版本。

这是我会实际运行的一个审阅者：

---
name: code-reviewer
description: Reviews a diff for correctness, security, and untested claims. Use after any nontrivial implementation task.
tools: Read, Grep, Glob
model: inherit
---

You are a code reviewer. You did not write this code and you have
no stake in it passing.

Read the ticket, the diff, and the tests. Verify the change does what
the ticket claims, not what the commit message claims.

Report verdict first, then findings ordered by severity, each with
file and line. If you cannot verify a claim, say so explicitly.
Never pad the report with praise.

Frontmatter 做实际的工作。name 是你如何调用它。description 是 Claude 如何自动决定委托，所以要像派遣规则一样写，而不是简历。tools 是权限边界：只读工具的审阅者无法悄悄"修复"它被要求判断的代码。model 为机械性角色指定一个更便宜的模型，或为需要判断的地方指定一个更强的模型。

正文是代理的系统提示。保持简短且有观点，像对待代码一样对待文件：版本化它、审阅 diff、当 subagent 出错时修补定义而不是在聊天中纠正，这样每个未来的派遣都继承该修复。

这些文件也很容易迁移。当我将工作流文档移到不同的编码代理时，它们在几分钟内就迁移了，因为它们只是 markdown。你编码的流程是资产；下面的工具是可互换的。

如何调用 subagent（附示例）

明确派遣是你提示中的一句话：

Use the code-reviewer subagent on the diff for ticket 142.

当任务与代理的 description 字段匹配时，Claude 也会自动委托，这就是为什么 description 应该像规则一样读。并行派遣很直接；独立派遣并发运行：

Spawn three subagents in parallel: one to map every caller of
exportReport, one to read the payment vendor's webhook docs, one to
draft the migration plan. Each writes its findings to docs/notes/
and reports back a summary.

来自我自己使用的四个例子：

独立的审阅者。 在构建者发货 UI 后，一个全新的只读审阅者获得证据路径和狭窄的授权。其中一个关卡捕获了一个被裁剪的移动标签。它还发现提供作为证明的截图从未显示该工作声称要修复的部分。一个证据缺口和一个实现 bug，由一个没有建立任何东西的记忆的代理干净地分离。

干净室第二概念。 在一个会话中的设计两次迭代后，我生成一个拥有我蒸馏的偏好、看不到现有草稿的全新 subagent，告诉它找到自己的论点。在一个上下文中迭代会收敛到第一个想法的局部最大值；有偏好简报的干净室多样化，我最终逐项判断两个真实概念。

廉价的索赔检查员。 状态文档膨胀，因为"完成"悄悄地意味着"存在"。我把状态页交给一批在便宜模型上运行的小检查 subagent，并让他们验证每一个具体索赔与代码库的对应。在一次扫描中，大多数索赔在代码存在级别成立，而最进取的交付索赔几乎没有或没有支持；每个完成单元都将已注册与已验证混为一谈。

规划三人组。 这篇文章的第一个版本是围绕这个派遣构建的：一个产品经理角色和一个设计师角色在任何构建者开始之前都从真实构件中各写一份备忘录。那个预构建步骤如何曾经重定向整个重建是它自己的文章。

Claude Code subagent 最佳实践

首先在真实构件中接地 subagent

给 subagent 一个角色但没有内容可读，它会发明自己的审阅，而且到达速度很快。每个派遣都要命名它的输入：diff、文件路径、截图、工单。对于判断角色，要求代理在形成意见前阅读构件；无根据的意见到达速度快，会让你重新运行。

给每个文件一个写者

并行 subagent 编辑同一文件是工作消失的方式。在派遣前按所有权分割：这个代理拥有 API 路由，那个拥有组件，没有人共享。如果两个片段真的需要同一文件，它们从来就不独立；按顺序运行。

派遣结果，不是步骤列表

Subagent 是代理，不是宏。如果我委托给一个高级工程师，我不会规定按键，相同的规则在这里成立：陈述结果、约束、反目标和要带回什么证明。然后坚守证明的界线。以测试输出、截图路径或写入的文件结尾的报告是可检查的；仅一份总结是虚无。

让无人看管的代理决定和记录

因澄清问题而失速的后台代理浪费了成为后台的意义。我的代理会做合理的判断并将其记录到审阅者稍后读的假设文件中。交互式运行可能会提问；自主运行会记录。

派遣真实工作前进行健康检查

在扇出规模上，死亡会话是正常的，它们默认失败。在分配真实工作前，用"准确回复：MODEL_OK"ping 每个代理。在我早期的一个扇出运行中，三个 ping 中有两个回来空白，每个死亡会话需要约一分钟来捕获，而不是几小时后才作为神秘的零进度浮现。

在判断所在的地方花费模型质量

大规模使用时你会开始关注成本。机械验证、索赔检查和日志梳理正是便宜、快速模型并行运行的工作。Orchestrator 角色——那个拥有设计决策和集成上下文的——是我保留强模型的地方。Frontmatter model 字段是旋钮。

实际上你能并行运行多少个 Claude Code 代理？

比民间传说说的多。出现在搜索结果顶部的"2 到 5 个代理是现实的天花板"建议描述了一个看工人的人，一旦你改为管理 orchestrator，它就停止适用。

我在 2026 年中期的常规方式：3 或 4 个项目同时活跃，每个项目一个长期存在的 orchestrator 会话，每个 orchestrator 一次运行大约 5 个 subagent。称之为 20 个活跃工单，由于 subagent 可以在其工具允许的地方生成 subagent，计数每个活跃代理时，通常是几十个。

纸面上是几十个代理；实际上感觉像管理 4 个人，因为你与 orchestrator 交谈，不是工人。我问 orchestrator"这完成了吗？我对此有反馈"，它会用完整上下文重新派遣。

限制是真实的，只是不在民间传说声称的地方。在我的 32GB Mac mini 上，RAM 在我的注意力之前耗尽。回来的一切都需要审阅：最近的一个周日从 6 个会话中产生了 66 个提交跨 4 个仓库，跟上的唯一方式是按 PR 审阅证据包而不是逐行读代码，这是自己的主题。我学到的管理 20 个代理群体的规则在这个规模上仍然成立。

Subagent 对比并行运行多个 Claude Code 实例

搜索并行 Claude Code 代理通常意味着两种设置之一，它们解决不同的问题。Subagent 是会话内扇出：一个 orchestrator、一个工作目录、一个共享计划、并行工人报告。在单独的 git worktree 中运行多个 Claude Code 实例是流程级扇出：完全隔离、每个一个分支，为持续几小时或几天的独立工作流构建。我每天都运行两者，worktree 工作流有足够的自己的纪律、合并顺序、清理和失败模式，以至于它应该有自己的文章而不是这里的一段。

从上面的例子创建 .claude/agents/code-reviewer.md，并通过它运行你的下一个非平凡 diff。一个在代码通过中没有利益关系的法官会告诉你你的主会话永远不会的事情，派遣习惯由此开始。

或跳过打字：把你的编码代理指向这篇文章，并要求它设置这里描述的代理定义和派遣习惯，适应你的仓库。这篇文章是规范。整个模式终究是一个习惯：停止在你保持计划的窗口中做工作。

从 zach wills 发现更多

订阅以获取最新文章到你的电子邮件。