单体仓库真的最适合编码代理吗？
今年初，我认为单体仓库是 AI 原生开发的明显选择。
原因在于上下文封闭。
当代码、测试、设计决策、基础设施以及开发规则在同一执行环境中可用时，编码代理的工作效果会更好。它不应该必须等待有人从 Slack 粘贴一个决策、解释某人脑中存在的约定，或从其无法更新的系统中检索需求。
单体仓库让这变得更容易。将产品及其开发上下文放在同一位置，为代理提供搜索工具，仓库就成为代理可以工作的封闭环境。
我仍然相信上下文封闭很重要。改变的是我对仓库所封闭内容的看法。
我参与了一项关于在大型仓库中引入共享代理 harness 的讨论。技术提案不是最难的部分。更难的问题是，工程师们已经使用的工作流会发生什么。
如果共享 harness 要求人们停止使用他们的个人技能、说明和工作流，他们实际上会这样做吗？
没有人有信心说是的。
到那时，仓库已经不仅仅包含代码。它包含了几种部分重叠的告诉代理如何工作的方式，有些由团队提交，有些由个人维护。引入一个通用的 harness 不再是安装。而是远离人们每天依赖的系统的迁移。
我也见过相反的失败。在组织尚未知道如何设计、评估和维护可靠 harness 之前就进行集中化，共享系统就会成为天花板。糟糕的说明会影响所有人。审查者会吸收纠正成本。AI 使用仍然停留在浅层，因为批准的路径不如有能力的个人能够为自己构建的有效。
这两种方法似乎朝相反的方向失败。过早集中化，组织会标准化它尚未学会做好的事情。过晚标准化，本地工作流会变得太根深蒂固而无法替换。
代码存放的位置变得不如谁能够定义代理在其上应如何工作、解决冲突上下文以及在代码和模型变化时保持系统正确性重要。
仓库不再是上下文边界
当编码代理能力较弱时，单体仓库的论点更有力。
一个只能维持短任务的智能体从拥有一切近在咫尺中获益良多。仓库边界是实际的上下文边界。跨越它们的工作需要更多的提示、更多的检索基础设施和更多的人员协调。将相关系统放在一起可以降低智能体遗漏重要事项的概率。
我目前使用的长时间运行模型表现不同。在获得相关仓库和工具的访问权限后，它们可以跨项目搜索、追踪依赖、比较实现并进行协调更改，而不必将每个仓库视为独立任务。访问仍然需要设计，但仓库边界不再是同一种能力边界。
跨仓库的访问并不会使周围的结构变得可选。在单一仓库（monorepo）中，广泛搜索仍然需要包、所有权和领域边界来将相关代码与类似但无关的代码分开。跨仓库搜索依赖于可信的清单和依赖图，否则不完整的结果可能会显得完整。更好的模型需要较少的帮助来遵循该图。它们并不会消除维护它的必要性。
此声明涉及上下文获取和编辑协调。仓库边界在原子提交、CI、兼容性和部署方面仍然重要，更好的模型不会移除这些限制。它们确实改变了 AI 开发中单一仓库的权衡。
代码可见性仍然有用，但可见性不再专属于单一仓库。智能体可以跨仓库发现 API 或检查依赖服务。它可以在一次运行中更新多个仓库。生成这些编辑通常比确定它们是否可以一起部署更容易，而这一点涉及必须保留的兼容性窗口以及如何排序发布。
随着仓库边界不再成为编码智能体的上下文边界，单一仓库的主要 AI 优势从检索转向了治理。
单一仓库为产品范围的说明、共享技能、架构上下文和防护措施提供了一个共同的家。同一个仓库可以承载使其保持最新的评估和维护工作。这是一个真正的优势。这也是大多数组织最缺乏准备去运营的部分。
上下文封闭不是上下文治理
在 什么使得开发成为 AI 原生？，我将上下文封闭描述为在 LLM 工作流中产品上下文可搜索、可读取且可更新的条件。
这仍然是必要的。但可用性仅回答一个问题：智能体能否到达上下文？
治理回答了在它能够之后变得重要的问题：
- 哪个上下文具有权威性？
- 它适用于哪里？
- 谁拥有它？
- 当两条指令不一致时会发生什么？
- 如何删除过时的规则？
- 它是如何被评估的，以及当本地上下文改变产品范围行为时，谁负责？
存储库可以在不回答这些问题的情况下关闭上下文。
随着组织的增长，这变得更加困难。足以证明单一仓库合理性的产品通常由多个团队开发。这些团队被刻意保持足够松散，以便在无需持续协调的情况下工作。他们的代码、架构、发布流程、领域知识和代理工作流会出现分歧，因为一定程度的分歧是自治所必需的。
一个团队创建了一项技能来修复反复出现的故障。一名工程师添加了一条个人指令，因为更改团队的工作流程会影响所有人。另一个团队以不同的方式解决了类似的问题。每个补充在局部看来都是合理的。随着时间的推移，存储库、团队和个人层面会积累关于工作应如何计划、审查、测试和完成的重叠假设。
工程师在日益狭窄的上下文中变得孤立：
product context
-> system context
-> team context
-> personal context
本地系统越深入，该工程师就越难以改变共享系统。个人的变通方案成本低廉。纠正仓库范围的工作流程需要达成一致、进行迁移，并对所有受影响的人承担责任。
本地的便利逐渐削弱了否则会改进共享系统的力量。
更好的模型使冲突的上下文代价更高
缺失的上下文仍然危险。模型无法可靠地遵守它无法发现的约束。
但缺失的上下文不再是唯一的重要失效模式。错误的上下文、冲突的上下文和过度控制可能更糟，因为一个强大的模型能够更彻底地执行它们。
我在当更好的模型使旧的代理工作流程变得更糟中描述了这一转变。为弥补早期模型失效而编写的规则可能会变成产生工作的约束，导致模型生成它们所暗示的文档、测试、评审、重试、批准和抽象。同样的问题在单体仓库的组织规模中也会出现。
一个团队的技能可能要求每个更改都要经过几个审查阶段。另一个可能指示代理仅选择最窄的证明边界。产品级规则可能保留公共合同，而本地工作流则优化为内部替换。个人指令可能要求一个共享 harness 不再使用的规划工件。
每条指令在孤立情况下都可以被辩护。它们的组合可能会在看起来更成熟的同时降低执行质量，因为存在更多的上下文和更多的流程。
AGENTS.md 至少提供了一种基于目录的偏好。Codex 从仓库根目录向工作目录加载指令，且越接近工作目录的指令优先级越高。这并不能证明本地规则是正确的；产品范围的规则可能才是应该获胜的那个。但当两者发生分歧时，它为模型提供了一个确定性的指南。
由于技能使用渐进式披露，因此更难进行推理。代理最初会看到名称和描述，然后决定为任务加载哪些完整的指令。进入上下文的内容取决于任务的解释方式。当多个技能适用时，没有等价的语义层次结构来规定产品级决策必须覆盖团队工作流或个人偏好。
因此，进入任务的指令可能难以预测。任务措辞、工作目录或模型版本的变化可能激活不同的组合，使组织能够在悄然降低性能的同时改进其共享 harness。
在能力存在之前进行集中化
自然的反应是将一切集中化，但针对大型产品的共享 harness 需要远超 prompt 文件。维护者需要具备足够的产品知识，以区分持久边界与旧的补偿规则，并使上下文与代码库保持一致。他们还需要具有代表性的评估，以暴露模型回归以及不再产生收益的工作流。
提示和上下文工程技能是必要的，但不足够。理解模型行为但未参与产品开发的人无法创建准确的领域上下文。了解产品但无法评估代理行为的人可能会将每一起历史事件都编码为另一条永久规则。
小型中心团队无法在深入理解大型单一代码库中每个领域的同时，跟上模型变化的步伐。如果该团队成为唯一的作者和把关人，人类将成为瓶颈。共享 harness 会偏离实际开发，团队会绕过它，而标准化会抑制改进它所必需的实验。
即使结果停滞不前，使用量和支出仍可能增加。当一个薄弱的工作流被集中化时，其局限性将变得组织范围内普遍。
在本地系统嵌入之后进行标准化
让团队和个人自行寻找有效的方法能够加快初步采用。工程师可以在不改变他人流程的情况下进行实验，有用的实践来源于实际工作，而非来自中央设计练习。然而，缺乏收敛路径的自主性会产生自身的锁定。
个人技能不仅仅是围绕它塑造日常工作后的一个文件。它包含习得的行为、可信的快捷方式以及对代理将如何响应的假设。团队工作流成为计划、审查和交付的一部分。即使替代方案更好，替换它也会产生切换成本。
当组织需要全仓库范围的 harness 时，它已经推迟了艰难的决策：哪些本地行为应成为共享的，谁有权退役旧系统，以及如何证明迁移不会降低性能。如果没有这些答案，共享 harness 将加入现有工作流，而不是取代它们。
这让我想起了最初讨论中的问题：工程师会放弃他们已经依赖的个人系统吗？这听起来像是一个采纳问题。实际上，这是关于迁移权威的问题。组织想要一个统一的 harness，但从未确定谁有权退役它将取代的系统。
集中治理，分散维护
如果单一代码库（monorepo）要提供一个通用的 AI 开发环境，其上下文和 harness 需要一个共同的权威。产品范围的约束不能因为一个团队偏好另一种工作流而变成可选的。组织需要一种方式来决定什么是规范，如何解决冲突，以及何时规则过时。然而，共同的权威并不意味着中央团队可以完成所有工作。
共享权威需要分布式能力
工程师不仅需要能够向模型请求代码的能力。他们还需要理解任务框架、上下文选择、指令范围、渐进式披露、验证以及模型行为如何影响结果。
不是每个人都需要成为代理评估的专家。向共享系统贡献上下文的每个人都需要具备足够的技能，以免将局部偏好或历史失败转化为产品范围的义务。
这种能力不能被平台团队隐藏。产品和系统上下文有所有者、消费者、兼容性需求以及生命周期。当个人偏好影响展示或可逆的工作方式时，它们可以保持个人化，但它们不能悄然重新定义正确性、产品行为、批准边界或完成标准。
拥有某个领域的团队也必须拥有描述该领域的上下文的准确性。一些成员需要超越即时交付的显式能力：维护共享指令、审查跨域假设、贡献代表性任务以及在仓库范围的 harness 中解决冲突。治理是集中的；其证据和维护在组织内部是分布式的。
harness 应该随时间推移需要更少的上下文
上下文质量不能依赖于偶尔的手动清理。引用、所有权、重复、模式以及已退役的文件可以通过机械方式检查。代表性任务可以检测模型更新是否会改变行为。冲突用例可以在产品、系统和团队指令不一致时测试哪条规则获胜。harness 可以衡量一条规则是否改善了被接受的结果，或者仅仅是制造了更多工作。
自动化应将人类判断集中在它能够改变真实决策的地方，而不是花费在常规一致性检查上。评估集必须随着代码库和模型一起演进。六个月前通过的技能并未获得永久权威。
持续评估仅是工作的一半。上下文和测试框架无法无限期地弥补不一致的代码库。
当系统的两个部分以不同方式解决同一问题时，一条指令可以解释差异。当五个部分如此时，更多的指令将成为未解决设计债务的地图。模型必须花费更多的 token 来发现哪个示例是当前的，哪个异常是故意的，以及哪种模式可以安全地扩展。
持久的应对方式是减少不一致本身。公共契约应当明确。无效的依赖应当被机械地拒绝。类型、测试、构建边界、模式和权限应当强制执行目前提示必须解释的内容。临时的兼容路径应当被移除，而不是在其周围积累永久的上下文。
最强的代理指令往往是指：错误的更改无法融入的代码库。
以结果成本来评判治理
组织应如何知道这种治理是否有效？使用情况、生成的代码行数、完成的任务以及总支出奖励活动。相关的经济单位是指在无需人工干预的情况下，以所需质量生成一个被接受的结果所需的总推理成本。
这包括模型选择、重试、中止的运行、评审代理、不必要的制品、过度探索以及由过时指令生成的工作。其中部分成本是合理的。探索可以确定无需更改，但它仍然属于达到该结果的成本。如果更好的上下文可以防止，则重复探索应随时间减少。一个不佳的测试框架可能仍通过消耗更多推理来完成任务，但组织实际上是在购买其开发环境本应使之变得不必要的推理。
该数字是健康指标，而非优化目标。只有在接受标准得到保持且被接受的结果在审查后仍然正确时，较低的成本才算是改进。
如果审查者需要重建结果，则自主工作流未能产生被接受的结果。此指标也为组织的克制行为提供了认可。正确的结果可能是一个小的更改、重用、移除冲突的工作流，或决定不构建任何东西。随着模型能够承担更多工作，防止不必要的工作成为良好运营它们的一部分。
单一仓库本身并不是答案
我仍然认为在 AI 原生开发中，单体仓库有很强的理由。一个仓库可以提供规范的 harness，通过与代码相同的工作流保持产品范围内的上下文可维护，并使共享评估和机械执行更易于操作。
实现这些好处需要共享的上下文所有权和分布式的产品知识。没有它们，单体仓库可能包含比代理能够可靠调和的更多矛盾，而共享的 harness 可能在所有地方强制执行错误的工作流。具有 deliberate 跨仓库访问、明确的合同和良好治理的上下文的多仓库系统，可能不再对有能力的代理施加曾经的劣势。
仅凭仓库拓扑无法决定结果。关键在于组织是否能够运营该拓扑所可能实现的上下文系统。
康威定律在执行者成为模型时并未停止适用。组织的沟通结构塑造了代码库；它现在也塑造了代理用来更改该代码库的指令、技能、工作流和评估系统。
如果团队仅负责本地交付，他们的代理上下文将优化为本地交付。如果个人因个人生产力而受到奖励，他们的最佳工作流将保持个人化。如果中央团队在没有领域团队参与的情况下拥有 harness，则 harness 将反映中央团队对产品的有限视角。
因此，AI 原生开发不仅仅是分发一个编码工具或将一套技能签入仓库。开发过程本身必须成为一种工程责任。团队必须将产品范围内的质量视为其工作的一部分，维护将意图转化为自主执行的系统，并使代码库足够一致，以至于随时间推移需要更少的解释。
单体仓库曾经看起来像是答案，因为它把代理所需的一切放在一个地方。
现在代理可以达到更远的范围。
更难的问题是，组织是否能够就代理到达时应该发现的内容达成一致。
仓库不再是上下文边界。
组织才是。
