多 Agent 协作：10 个编码 Agent 先崩在哪里？

同时运行 10 个编码 Agent，最先出现的通常不是 CPU 满载，而是没人能回答三个问题：谁正在改什么、这次改动该测哪里、哪一个结果允许进入主分支。电脑仍在运行，十个会话也都显示“进行中”，但整个交付已经失去控制。

多 Agent 协作不是把一个窗口复制十份，而是给多个执行者建立一套共同的控制面（control plane，决定任务、权限、预算、验收和恢复的规则层）。本文给出一套跨 Codex、Claude Code 与其他编码 Agent 都能使用的六层方法，并明确什么时候不该扩到十个。

要点速览

• 真正可用的并发数，取决于独立任务数、独立写入区、预算和合并能力中最小的那一个。
• Git worktree 能隔离文件工作区，不能自动解决任务重叠、接口冲突、共享密钥和漏测。
• 每个 Agent 开工前都要有任务合同；交付时要带变更、测试、成本、风险和提交证据。
• 先从一个 Agent 建基线，再扩到三至五个；只有控制面持续稳定，才值得把十个 Agent 当作压力档。

30 秒判断：现在该不该增加 Agent？

只要后两种现象存在，多开 Agent 通常不会缩短交付时间。此时真正的瓶颈已经从“生成代码”转移到“验证和合并代码”。

先崩的为什么不是电脑，而是协调状态？

因为编码工作不是十份互不相关的计算。需求、接口、数据结构、测试环境和主分支彼此相连；一个 Agent 的输出会改变另一个 Agent 的输入。并发增加后，等待可能减少，但沟通、冲突、复测和合并的工作同时增长。

Claude Code 的官方并行指南把 subagent、agent view、agent teams 和 worktree 分开介绍，正是因为它们解决的问题不同：有的隔离上下文，有的负责协调，有的隔离文件。单纯多开会话，只解决“同时有人干活”，没有解决“这些工作怎样组成一个正确版本”。

第一次接触这些名称时，可以先按用途区分：子 Agent适合把研究、检查等结果交回主任务；Agent 团队适合多个成员共享任务与消息；worktree只负责让不同分支拥有独立文件目录。它们可以组合，但任何一个都不能单独替代任务所有权、预算和验收。

可以用一个不带伪精度的判断式理解有效并发：

有效并发数 = 独立任务数、独立写入区数、预算容量、合并消化能力四者中的最小值。

如果需求只能拆成两个真正独立的任务，开十个 Agent 只会制造八个等待者或重复劳动者。如果十个任务都要改同一个核心接口，十个独立工作区也只是把冲突推迟到合并时发生。

💡 通俗讲：十个 Agent 像十支装修队。房间够多、图纸清楚、材料分开、验收有人负责，它们才会更快；如果十支队伍同时改同一面承重墙，工具越多，事故只会来得更快。

四个“已经失控”的领先信号

看到这些信号时，正确动作不是再加一个“主管 Agent”，而是暂停新增任务，修复控制面的缺口。

如果还没有历史基线，可以只在可丢弃的测试环境做一轮临时演练：运行 5 分钟没有状态变化就提醒，10 分钟没有有效进展就暂停，30 分钟到硬停止线；单任务预算暂设为 $1，低敏追踪元数据保留 7 天，超过 24 小时仍未合并的工作分支进入人工复查。这些数字只是演练配置，不是生产标准；第一次运行结束后必须用自己的成本、时长和返工记录重设。

第一层：用任务合同锁定所有权

任务合同（task contract，把任务边界和完成条件写成结构化约定）是多 Agent 协作的最小单位。每个任务只能有一个最终所有者；可以有研究者、审阅者和测试者，但必须有一个实体对完成状态负责。

一份能开工的任务合同至少包含七项：

下面是一份缩短后的合格示例。假设任务是“为 Ghost 登录接口增加限速”，它没有把责任交给一群角色，而是把一个可验证结果交给一个所有者：

这个示例最重要的不是字段齐全，而是每一项都能被外部检查。owner 是唯一责任归属，write_scope 是机器可比对的边界，acceptance 是可重复执行的完成证据。

任务合同的价值不在文档本身，而在于调度器可以据此做确定性判断：写入范围重叠就拒绝并行；依赖未完成就保持阻塞；验收命令缺失就不允许开工；交付证据不齐就不标记完成。

🎯 实战提示词：先拆任务，再决定并发数

请把需求拆成任务依赖图。每个任务填写唯一 task_id、单一所有者、允许修改的目录、输入依赖、机器可执行的验收条件、交付物和失败回退方式。只有写入范围不重叠且依赖已解除的任务才允许并行。最后给出建议并发数，并说明限制它的最小因素。

这段提示词的预期结果不是“自动生成十个角色”，而是一张能被人和程序共同检查的任务表。

第二层：隔离上下文、文件、权限和运行资源

工作区隔离只是四层隔离中的一层。一个可靠的多 Agent 环境需要同时处理：

1. 上下文隔离：每个 Agent 只接收完成本任务所需的信息，避免旧讨论和无关日志挤占判断空间。
2. 文件隔离：每个写任务使用独立分支与工作区，不直接共享未提交文件。
3. 权限隔离：每个任务只拿到所需工具与短期凭据，研究任务不应拥有生产写权限。
4. 运行资源隔离：测试数据库、端口、缓存目录和临时文件不能相互覆盖。

例如，三个 Agent 可以分别使用 app-agent-a、app-agent-b、app-agent-c 数据库，分配不同端口和缓存前缀；共享一个测试账号时，还要明确谁允许修改账号状态。文件隔离解决“写到哪里”，资源隔离解决“运行时会不会互相踩状态”。

Git 官方文档说明，一个仓库可以关联多个工作区；每个工作区有自己的 HEAD 和索引，同时共享仓库历史。它适合让多个 Agent 在不同分支工作，也说明了能力边界：共享历史不等于共享任务状态，更不等于自动理解接口语义。

Claude Code 的 worktree 指南还提醒，被 Git 忽略的环境文件是否复制，需要显式决定。生产环境里更稳妥的做法不是把同一份管理员密钥复制十次，而是让任务启动器按权限临时注入所需凭据。

⚠️ 常见踩坑：每个 Agent 都有独立 worktree，但共用同一个数据库、同一个端口或同一个云端测试账号。文件没有互相覆盖，运行状态却仍会串台。隔离检查必须同时覆盖代码和外部资源。

四层隔离检查表

第三层：把预算和速率限制放在 Agent 外面

预算必须是 Agent 不能自行绕过的硬边界。仅在月底查看账单，只能解释已经发生的消耗；运行中的控制面要能在单任务异常时提醒、暂停或降级。

建议分三层设置：

AWS 的 Codex + LiteLLM 实践把模型网关用于身份、模型白名单、预算、速率限制和遥测，同时把本地工具执行留在 Agent 的沙箱和审批边界内。这说明一个重要原则：模型调用和真实世界动作应分别受控。

LiteLLM 官方文档提供虚拟密钥、成本追踪、预算和速率控制，但网关不是个人开发者的必选项。小规模阶段可以先用模型供应商原生限额和本地任务预算；只有需要跨模型、多人归因或统一策略时，再承担网关、数据库、升级和可用性的运维成本。

🔍 深入一步：预算阈值不应从别人的博客复制。先跑一批单 Agent 基线，记录同类任务的成本、时长、成功率和返工率；再用自己的分布设置提醒线和停止线。没有基线时，宁可用保守上限，也不要假装有精确行业标准。

超限动作也要有固定顺序：先拒绝新请求，再保存当前证据，最后暂停或转人工。不要在预算已超时让 Agent 自己判断“再试一次是否值得”，否则硬边界会退化成一条可忽略的提示。

🎯 实战提示词：为任务生成止损规则

请根据任务的可逆性、外部写入风险和验收复杂度，设计单任务、单 Agent、团队/模型三层预算。每层给出观测指标、提醒条件、硬停止条件和停止后必须回传的证据。不要引用通用百分比；缺少历史基线时，明确标注为临时阈值。

第四层：沿依赖图计算回归范围

多个分支各自通过测试，仍可能在合并后失败，因为 Agent 通常只看自己改过的文件。真实影响还会沿接口、配置、提示词、数据结构和调用链向下游扩散。

原始选题中的提示词依赖图案例提供了一个有用思路：把可变资产画成节点，把引用与调用画成边；某个节点变化后，沿下游边得到需要重测的集合。文章标题中的数字属于该案例，不能外推成所有系统都会影响相同数量。

回归范围（regression scope，变更后必须重新验证的功能集合）可以分成四圈：

影响范围越大，越不适合与相关任务同时合并。对核心契约的变更，应先由单一所有者落定版本，再让下游 Agent 基于同一个快照开工。

仍以上面的登录限速为例：直接圈要测限速函数；契约圈要测登录接口的 429 响应和客户端处理；共享圈要测 Redis 前缀、反向代理与安全配置；全局圈至少要走一次注册、登录、退出和找回密码。只测新增函数，即使分支全绿，也不能证明用户登录链路仍然正确。

🎯 实战提示词：生成影响面测试计划

请读取本次变更清单和仓库依赖关系，把影响分为直接圈、契约圈、共享圈和全局圈。每一圈列出必须运行的检查、失败时阻断哪个合并步骤，以及哪些依赖无法从代码静态推断、需要人工确认。不要只复述已有测试文件名。

第五层：用一条追踪链串起任务、成本和提交

可观测的目标不是“日志很多”，而是一次异常能够从用户需求一路定位到具体 Agent、模型调用、工具动作、代码提交和测试结果。

最小追踪链（trace，把跨步骤动作关联起来的记录）建议包含：

OpenTelemetry 语义约定的价值在于让不同服务用一致字段表达操作、错误和资源。Agent 相关约定仍在演进，因此本文借用的是“统一命名、可关联、低基数”的原则，而不是把某一版实验字段写死。

⚠️ 常见踩坑：为了追踪而默认永久保存完整提示、响应、工具参数和源码，会把观测系统变成新的敏感数据池。优先记录低敏元数据、哈希和受控引用；确需保存正文时，再补脱敏、加密、访问控制和保留期限。

判断追踪是否合格，可以做一个简单演练：拿任意失败的测试记录，能否在几分钟内找到它属于哪个任务、哪个分支、哪次模型调用和哪次合并。如果还要翻十个聊天窗口，控制面并未真正建立。

追踪字段应尽量使用稳定枚举，例如把状态固定为 running、blocked、needs_review、failed、done，而不是让每个 Agent 自由写一句近义描述。字段可统计，正文按需引用；这比永久保存所有对话更容易治理，也更少暴露敏感信息。

第六层：让合并和恢复保持串行

执行可以并行，主分支合并应保持受控串行。每次只合并一个经过验收的变更，合并后重跑它的影响面测试，再允许下一个依赖分支进入。这样一旦失败，影响半径（blast radius，一次错误可能扩散的范围）仍然可定位。

GitHub 受保护分支可以要求状态检查或评审通过后才合并。无论使用哪种托管平台，核心都是把下面这些条件变成系统规则：

• 任务合同状态是 completed，而不是 Agent 的自然语言“已完成”。
• 必需检查全部通过，且检查对应当前提交。
• 写入范围与实际变更一致；超范围变更必须重新审查。
• 依赖任务已经合并，当前分支已基于最新主线复测。
• 回滚对象明确，必要时能撤销单次合并而不是整批回退。

恢复也不能只写“失败后重试”。重试前要判断失败类别：临时网络错误可以在上限内重试；契约不一致要退回任务拆分；权限错误要停止并修正授权；不确定副作用是否已经发生时，必须先回读真实业务状态。

数据库迁移尤其不能把“回滚”简化成 git revert：代码可以撤回，已经写入或删除的数据未必会随提交恢复。任务合同必须分别写明代码回退、配置回退和数据恢复对象；没有可验证的数据恢复路径，就不应把迁移任务放进无人值守的并行队列。

合并前交付包

10 个编码 Agent 的三阶段运行清单

十个不是起步目标，而是压力档。只有下面三阶段检查能稳定执行，才值得增加并发。

启动前

• [ ] 任务依赖图已生成，没有把顺序任务伪装成并行任务。
• [ ] 每项任务只有一个最终所有者。
• [ ] 写入范围无重叠；共享契约有单一版本和所有者。
• [ ] 每个 Agent 有独立上下文、工作区和运行命名空间。
• [ ] 权限与凭据按任务最小化，不共享生产管理员密钥。
• [ ] 预算、速率、超时和最大重试已设置。
• [ ] 每项任务都有机器可执行验收与回滚方式。

运行中

• [ ] 调度器能看到 running、blocked、needs-review、failed 等状态。
• [ ] 同一失败没有被多个 Agent 重复尝试。
• [ ] 共享契约变化会阻塞受影响任务，并要求重新基线化。
• [ ] 成本、时长或重试偏离基线时会提醒或暂停。
• [ ] 人工可以取消单个任务，而不终止整个运行。

合并前

• [ ] 每个任务交回完整交付包。
• [ ] 影响面测试覆盖直接、契约、共享和全局四圈。
• [ ] 分支按依赖和风险顺序逐个合并。
• [ ] 每次合并后都基于最新主线复测。
• [ ] 失败能定位到单次任务并单独回滚。

这份清单通过，不代表十个 Agent 一定更快；它只代表增加并发不会首先把系统变成不可解释的黑盒。

如果运行中出现三类任一信号——同一写入范围被重复认领、合并队列持续增长、失败无法归属到单一 task_id——应立即停止创建新任务并降低并发。停止线要由调度器执行，不依赖某个 Agent 主动承认自己失控。

哪些任务不适合拆给多个 Agent？

不适合并行的共同特征，是任务之间缺少稳定边界：

1. 需求仍在频繁变化，连完成定义都无法固定。
2. 多个任务必须修改同一个核心文件或同一个共享契约。
3. 后一个任务必须读取前一个任务的真实结果。
4. 验收主要依赖主观判断，无法形成可重复检查。
5. 外部动作不可逆，且不能为每个任务建立独立权限和幂等保护。
6. 合并者处理结果的速度，已经低于 Agent 产出速度。

此时更好的方案通常是一个 Agent 推进主线，必要时用只读研究或审阅 Agent 提供独立意见。让十个写入者围绕一个不稳定目标工作，不是并行，是排队等待冲突。

🔍 深入一步：Anthropic 的 agent teams 文档指出，团队更适合能独立开展的研究、审查、新模块和跨层任务；顺序任务、同文件编辑或依赖密集工作，更适合单会话或较小团队。官方建议多数工作流先从三至五个队友起步，而不是直接追求十个。

从 1 个到 3 个，再到 10 个的演进路线

合理的扩容顺序不是按机器配置，而是按控制成熟度。

这里的阶段数量是操作性路线，不是性能定律。不同仓库、任务和团队会停在不同位置。真正应该优化的是“可验证交付/总成本”，而不是“同时在线 Agent 数量”。

扩容复盘时至少同时看四个数：独立任务完成数、合并等待时间、返工次数和总成本。如果并发增加后生成更快，但合并等待与返工同步上升，就应该退回上一档；只有可验证交付增加，扩容才成立。

这篇文章的生产流水线如何验证控制面？

本文自身没有伪装成“十 Agent 编码实验”。它采用的是可审计的内容生产状态机：选题先经过搜索立意，研究材料按读者、技术负责人和批评者三档核验，正文再依次进入静态质检、动态精修、配图、发布、公开页 QA 和异地备份。

这段一手实践说明了同一个原则：工作量可以由不同能力分担，但阶段顺序、采用版本、发布审批和最终验收必须只有一个真源。只有“完成证据”落盘，状态才会从“待处理”进入“已完成”；中断后根据状态继续，而不是重新猜已经做到哪里。

本次复核实际运行覆盖了 16 个独立网址，搜索结果页（SERP）前 7 条完成正文级抓取，并分别从进阶读者、技术负责人和批评者三种视角整理证据。第一次元标题检查还发现 32 字超过站内 30 字门槛，我们换成了 30 字版本。这个小失败比一句“AI 已审核”更有价值：它留下了输入、判据、失败结果和修正后的可复查证据。

我认为控制面比继续增加 Agent 更重要，因为多一个执行者只会增加局部产出，只有可验证的所有权、预算、测试和恢复规则才能提高整体交付。多 Agent 系统不应把“同时在线数量”当作成功指标；真正有意义的指标是可验证交付是否增加、返工与成本是否仍在边界内，以及一次失败能否被定位和单独撤回。

常见问题

多 Agent 协作和多开几个聊天窗口有什么区别？

多开窗口只增加执行者。协作系统还需要任务所有权、共享状态、写入隔离、预算、验收和合并规则，否则多个窗口只是彼此不可见的孤岛。

Git worktree 能完全避免代码冲突吗？

不能。它隔离工作目录和索引，但不同分支仍可能修改同一接口、数据结构或提示契约，并在合并后产生语义冲突。

什么时候应该从一个 Agent 扩到多个？

当任务能够独立拆分、验收可机器执行、合并路径清晰，而且单 Agent 的等待确实成为瓶颈时再扩。

10 个编码 Agent 是固定推荐并发数吗？

不是。十个是压力场景。多数项目应先从较小并发建立冲突、成本、阻塞和返工基线，再决定是否增加。

多 Agent 预算应该设在哪一层？

至少覆盖单任务、单 Agent、团队或模型三层。每层都要预先定义提醒、暂停、降级或转人工动作。

为什么多个 Agent 各自测试通过，合并后还会失败？

因为各分支往往只验证局部改动，遗漏接口、提示词、共享配置和数据迁移的间接依赖。合并后必须重新跑影响面回归。

追踪必须保存完整提示词吗？

不必须。优先保存任务、Agent、模型、工具、成本、提交和测试等低敏元数据；敏感正文按需脱敏、加密并限期保留。

个人开发者需要自建模型网关吗？

通常不需要。先用供应商原生预算、速率和权限控制；出现跨模型、多人归因或统一策略需求后，再评估网关的收益与运维成本。

什么情况下应该立即降低并发？

写入范围频繁重叠、共享契约不断变化、合并队列持续增长、单任务成本异常或失败无法关联到具体任务时，应先降并发并修复控制面。

上线前自检清单

• [ ] 标题里的“10 个”被明确说明为压力场景，不是虚构实测结论。
• [ ] 每个 Agent 都有唯一任务合同和最终所有者。
• [ ] 上下文、文件、权限、运行资源四层隔离均已检查。
• [ ] 任务、Agent、团队/模型三级预算有硬停止动作。
• [ ] 回归范围覆盖直接、契约、共享和全局四圈。
• [ ] 任一提交都能关联到任务、成本、测试和审阅记录。
• [ ] 主分支合并串行执行，且每次合并后重新验证。
• [ ] 回滚对象具体，人工接管入口可用。
• [ ] 并发数由真实瓶颈和基线决定，而不是展示效果。

相关教程

• AI Agent 基础设施：从 Demo 到生产的 6 层检查表：补齐运行、工具、身份、记忆、观测和恢复的上位框架。

参考来源

• Git：git-worktree 官方文档
• Claude Code：Run agents in parallel
• Claude Code：Run parallel sessions with worktrees
• Claude Code：Orchestrate teams of sessions
• Claude Code：Manage costs effectively
• AWS：Set up Codex with LiteLLM on ECS and Bedrock
• LiteLLM 官方文档
• GitHub：About protected branches
• OpenTelemetry：Semantic conventions