如何在开发团队中扩展 AI 编码代理

一个开发者使用编码代理是一个生产力故事。这很容易讲述，演示效果很好，并且确实真实。

五个开发者使用二十个代理则完全是另一回事。这是一个协调问题，而协调问题并不能通过创造它的工具来解决。这是没人写的部分，因为它只在热情阶段之后出现：个人收益是真实的，它们立即到来，然后在第三或第四个开发者左右，团队开始花费新的速度来清理自己的后果。

接下来是失败顺序。这不是抽象中的最佳实践列表，而是事情实际破裂的顺序，因为以错误的顺序修复它们会浪费一个季度。

首先破裂的是什么：共享上下文

每个运行代理的开发者都在悄悄地教它自己版本的代码库。

一个人告诉他们的代理项目使用服务器操作而不是 API 路由。另一个人从未提及，因此他们的代理编写 API 路由。第三个人提到过一次，在三天前结束的会话中。没有人是错的，没有人是在撒谎，而代码库现在包含了对同一约定的三种解释。你会在审查队列中注意到这一点，而这并不是注意到它的正确地方：到那时代码已经存在。

修复方法很无聊，但这是本页上最高效的事情。将约定放在一个文件中，提交该文件。

CLAUDE.md 用于 Claude Code，AGENTS.md 用于 Codex 和大多数其他 CLI 代理，实际上很多团队保持 一个便携上下文文件，而不是维护两个逐渐分离的文件。机制比文件名更重要：指令存储在代码库中，因此它们随着 git pull 到达，而不是通过任何恰好在房间里的人到达。

它应该包含的内容：

• 代理无法从阅读代码中推断出的约定，特别是代码库当前在某些地方违反的约定
• 命令：如何运行测试、构建、代码检查器，以及哪些可以自动运行
• 代码库中危险的部分，以及原因
• 团队不想要的内容：没有人要求的重构，绝对不能添加的依赖，正在迁移的模式

不应该包含的内容，而这正是团队遭遇问题的地方：任何特定于一台机器的内容。绝对路径、个人 API 令牌、本地端口、某人的首选编辑器。当机器特定的值出现在提交的上下文文件中时，其他每个开发者都会继承一个对他们来说错误的设置，而代理在忠实执行不再适用的指令方面非常出色。

在添加一行之前的有用测试：如果一个队友拉取这个，它是帮助他们还是破坏他们？

其次破裂的是什么：两个代理，一个文件

代理不会进行协商。它们不会检查是否有人正在编辑。两个指向同一模块的代理将相互覆盖，而不会提及，因为从每个代理的角度来看，工作成功完成。

单独使用时，这种情况是不可见的。你一次运行一个代理，或者你运行几个，它们恰好接触不同的内容。在团队中，这变得结构化，并产生最糟糕的错误类型：在两个绿色测试运行之间悄然消失的工作。

有两种机制可以修复它，你需要两者。

隔离。 Git 工作树 为每个任务提供其自己的代码库检出，因此并行代理在物理上无法碰撞。这是解决方案的便宜部分，没有理由不这样做。

所有权。 隔离阻止了覆盖；但它并不能阻止两个人以两种不兼容的方式在两个分支中两次解决同一个问题。这个问题在分配时解决，通过将每个任务的范围限制在一组文件中，并在任务本身中说明。不是“改善检出流程”，而是“更改支付步骤，在这三个文件中，不要触碰购物车”。

第二部分是团队跳过的部分，而这部分决定了合并是形式上的还是一个下午的工作。

第三破裂的是什么：审查

团队规模的审查一切都源于一个数字：每小时到达的差异量。

一个开发者阅读每一行是可以的。五个开发者每人运行四个代理，每天生成的差异量超过团队可以阅读的量，诚实的结果不是仔细审查，而是批准剧场。一个人在下午六点快速浏览九百行差异，产生一个签名却没有产生知识，这比不审查更糟，因为它制造了一个没有的保证。

存活下来的政策不是“审查所有内容”，也不是“信任代理”。而是将审查移至工作的两个边界：在代理开始之前阅读计划，因为一个错误的计划完美执行是最昂贵的失败模式，然后根据变更可能破坏的程度阅读差异。营销文案和 CSS 只需快速浏览。身份验证、支付、权限、个人数据和迁移每次都需逐行阅读，无论差异看起来多么干净。

这值得单独讨论，我们单独写了这篇文章：你还应该审查你的 AI 代理的代码吗 讨论了十个客观迹象，表明更改出现了问题，以及团队可以直接采用的爆炸半径表。

一个团队特定的补充。当多个代理共享一个代码库时，审查需要归属：哪个代理，哪个任务，哪个开发者。没有它，差异没有作者，审查变成考古学。这是你在通过三或四个并发代理后，设置中最有用的修复。

第四破裂的是什么：成本，以及关于成本的对话

代币支出在出现在团队发票上的那一刻就不再是个人细节。

陷阱在于发票是每月和汇总的，因此它产生的对话也是每月和汇总的，这意味着它产生的是政策而不是修复。有人提出一个更便宜的模型供所有人使用。另一个人提议限制会话。两者都是猜测。

实际分布几乎从来不是均匀的。它是少数几个长期运行的会话，集中在一两个项目上，背景整天增长且从未重置。这是一个可修复的行为，只有在你能够看到每个会话和每个项目的支出，而不是每月的支出时，才能修复它。我们在 如何检查代币使用情况 和 如何在不减慢速度的情况下减少它 中涵盖了这个机制。

在它成为管理主题之前，让产生它的人看到这个数字。一个开发者如果看到一次会话的费用超过他们整个前一天的费用，会自行改变他们的习惯，而这对团队在政治上没有任何成本。

团队仪式中实际改变的内容

根据我们的经验和团队的报告，有三件事。

站会从状态转向解除阻碍。 每个人昨天做了什么在分支中大致可见。值得花五分钟的是哪些代理被卡住，以及卡住的原因。

提示成为共享资产。 为一个开发者带来良好结果的指令对团队的价值超过了它产生的代码，而这正是那种在私人终端历史中蒸发的内容。保持 共享提示库 的团队不再每周重新发现相同的措辞。

专业化从个人转向角色。 一旦代理处理写作，值得关注的问题是谁审查什么，团队自然倾向于将角色分配给代理，就像他们将角色分配给人一样：一个负责实施，一个负责审查，一个负责测试。这就是 代理团队 的理念，在这个理念中，一个任务从开发角色转交给 QA 角色，附带差异、风险和测试提示，质量门由你的测试套件决定，而不是由代理对其工作的看法决定。

可持续的设置

简明扼要，按重要性排序：

前四个只需达成一致即可。最后两个是团队最终希望在终端之上获得某种东西的原因：不是因为终端不好，而是因为终端一次只显示一个代理，并且没有办法回答“现在谁在运行什么，在哪个项目上”。

这就是 AgentsRoom for teams 构建的核心问题：在一个视图中查看每个项目中的每个代理，附带其角色、状态和成本，以及在团队不在桌子前时的移动伴侣。它与 Claude Code 和 Codex 的工作方式相同，这比听起来更重要：大多数团队最终会同时运行两者，而假设一个提供者的设置会悄然成为下一个破裂的事情。

不过，从上下文文件开始。这是免费的，花一个下午的时间，并且比你这个季度可以安装的任何工具减少了更多摩擦。

常见问题

如何在整个工程团队中使用编码代理？

从上下文开始，而不是工具。将共享的指令文件（CLAUDE.md 或 AGENTS.md）提交到仓库，以便每个机器上的每个代理都能读取相同的约定。然后定义每个任务拥有的文件，以便两个代理不会同时编辑同一个模块。工具选择远不如这两个决定重要。

CLAUDE.md 或 AGENTS.md 应该提交到仓库吗？

是的。整个要点是新队友或新代理在不询问任何人的情况下继承团队的约定。将机器特定的值排除在外：绝对路径、个人令牌、本地端口和个人偏好应放在本地未跟踪的文件中，而不是共享文件中。

如何防止两个代理编辑同一文件？

为每个任务提供自己的工作树，使用 git worktrees，并在分配时将每个任务的范围限制在一组文件内。代理之间不进行协商，因此如果两个代理可以访问同一个模块，它们最终会以一种都不报告的方式覆盖彼此的工作。

当团队运行编码代理时，代码审查会改变吗？

数量会改变，因此政策也必须改变。阅读每一行在五个代理并行运行时无法生存。保持控制的团队在工作开始前审查计划，然后根据变更可能破坏的程度审查差异，将注意力集中在身份验证、支付、权限、个人数据和迁移上。

如何跟踪每个开发者的 AI 编码代理成本？

按会话和项目，而不是按月。每月的发票告诉你总额，但没有任何可操作的信息。你需要的是哪个项目和哪种任务消耗了令牌，因为答案通常是少数几个长时间运行的会话，具有膨胀的上下文，而不是整个团队。

当团队扩展编码代理时，首先会出现什么问题？

共享上下文，优先于其他任何问题。每个开发者在自己的头脑和提示中积累本地约定，因此同一仓库会有三种不兼容的解释。你会在代码审查队列中注意到这一点，但原因在上游。