O'Reilly洞察：Agent开发需要多少"规格"才合适

我在与同行关于 Agent 的对话中反复看到同一个观点：详尽的规格说明在当今已经是旧世界的开销负担。给模型一个粗略的目标，让它自由探索，出了问题再修复，继续推进。这听起来很高效，但也隐藏了成本。

一个简单的 prompt 看起来很便宜、很诱人，因为它能立即启动实现。然后修正循环就开始了。你审查输出、澄清意图、要求修改、重新运行测试、发现下一个差距，然后再来一遍。最终总得有人来判断结果是否符合真正的目标。那个人就成了"神谕"。

另一个极端是完全的形式化规格，前期成本显然很高。编写验收标准、契约测试或行为驱动开发（BDD）场景需要真正的努力。但下游成本是不同的，因为更多的"神谕"部分变成了可执行的。一条测试每次都检查相同的条件。它不会在午饭前五分钟感到疲劳、匆忙或乐观。

这才是真正的权衡。问题不在于规格是好是坏，而在于最小总成本落在哪里。对于大多数 Agent 工作来说，答案在中间某处：足够的结构来约束工作，足够的例子来使意图具体化，足够的可执行检查来使审查不至于变成猜测。

零规格不是智能和精简，只是代价昂贵的 vibe-coding。

瓶颈转移了，没有消失

软件工程从来主要不是关于打字，甚至不是关于产出代码。它是关于决定什么应该存在、什么永远不应该发生、哪些权衡是重要的，以及当问题触及现实世界时"完成"意味着什么。

多年来，团队通过人类摩擦来发现缺失的规格。审查者注意到一个边缘情况，QA 发现了没有人描述过的路径，一位资深工程师在脑中携带了一半的真实需求，在每次会议中一点一点地翻译它们。这些都不优雅，但确实迫使歧义浮出水面。

Agent 从根本上改变了这一点。它们使实现变得更便宜、更快速。这也意味着一个规格不足的想法可以在任何人真正就系统应该意味着什么达成一致之前，就变成一个看似合理的系统。

在旧世界，模糊的需求撞上了人类的缓慢。在 Agent 世界，模糊的需求撞上了机器的速度。

这就是为什么规格突然再次变得重要。它一直都很重要。我们只是用实现成本作为一个粗略的强制函数，然后把结果称为流程。

随着实现变得更便宜，更多的困难转移到了决定正确意味着什么以及如何可靠地检查它。

写规格是不够的

这是我看到人们最常跳过的部分。他们谈论起来好像顺序很简单：写规格，然后让 Agent 实现它。缺失的那一步才是昂贵的。

规格本身需要审查。

即使是一份仔细的规格也可能以熟悉的方式失败。它可能自相矛盾，或者只覆盖了快乐路径，对重试、速率限制或部分失败语焉不详。它可能描述听起来精确但实际上无法验证的行为。有时它以恰恰错误的方式精确：它写的是你写下的内容，而不是你真正想说的。

当 Agent 忠实地执行一个有缺陷的规格时，失败更难诊断。实现可能看起来连贯。它甚至可能通过了你提供的检查。但真正的问题在上游，在规格里，所以修复它意味着要回滚代码并一起重新推理。

这就是为什么我认为规格验证值得拥有自己的一席之地。在实现开始之前，需要有人问几个简单的问题。它内部一致吗？对这个任务来说足够完整吗？哪些部分是可测试的？我们在哪里仍然依赖人类判断？哪些失败模式缺失了，因为每个人都默默假设了它们？

Agent 可以在这里提供帮助，但只有当我们把它们用于比"写需求"更有用的事情时。那个 prompt 通常产生的是打磨过的迷雾。更好的 prompt 要具体得多：

在此之后，把草稿交给另一个 Agent，告诉它攻击结果：

即使是这样的简单工作流，也降低了获得值得人工判断的规格的成本。

Agent 并没有消除对规格的需求。它们使达到真正有用的具体程度变得更便宜。

为什么多 Agent 系统需要更强的契约

单个 Agent 处理小型、有边界的任务时，通常可以从松散的指令中恢复。循环紧密，爆炸半径是局部的，人类通常可以在它偏离时将其拉回正轨。人类甚至可以很容易地发现偏离。

多 Agent 系统是一个完全不同的问题。一旦一个 Agent 的输出成为另一个 Agent 的输入，解释性漂移就开始复合。Agent B 不知道 Agent A 误解了 10% 的需求。它只是把输出当作既成事实继续处理。当人类看到结果时，最初的错误可能已经埋在了几层看起来很称职的工作之下。

在这一点上，规格不再只是指导，而更像是契约。

那份契约需要的不仅仅是意图的一段落。它需要模式、不变式、允许的歧义、验证规则和明确的失败行为。在许多情况下，它还需要契约测试、类型化接口和机器可检查的交接格式。交接是产品的一部分，这不像人们希望的那么光鲜，但更接近现实。

这也是 BDD 和可执行验收测试的归属之处。它们的不仅仅是方法论的价值，而是把部分人类"神谕"转移到了可重复的东西中。当行为足够稳定可以精确指定时，可执行规格往往比又一轮审查更便宜。

一旦 Agent 开始把工作交给其他 Agent，交接本身就需要像真正的接口一样被指定和验证。

规格应该有到期日

还有另一个团队在这里犯的失败：它出现在他们不断在规格曲线上推进，好像更多的文本总是更安全。不是这样的。至少对于当前的模型来说不是。

Chroma 在 context rot 上的工作使问题的第一部分变得清晰：随着输入增长，模型性能变得不那么可靠，即使在简单任务上也是如此。在编码项目中，这还有第二个问题。你塞进上下文的越多设计文档、例子、计划、注释、工单和旧的验收标准，你就越难分辨哪些部分是指令，哪些部分是产物。

我不会称之为安全意义上的 prompt 注入。没有人试图攻击模型。它更像是自我造成的指令漂移。上下文包含旧的设计意图、当前的实现、半有效的例子、来自三个 session 前的生成计划，也许还有一份仍然描述着已不存在的类的过时软件设计文档。在那一点上，模型不是在读一份规格，而是在多个相互竞争的真实来源之间取平均。

这就是为什么过度规格化不再有帮助，开始混淆模型。Agent 无法再判断一个段落是活跃的需求、历史注释，还是代码已经替换掉的东西。

设计文档在早期是有用的，因为代码还不存在。后来，它需要缩小。一旦接口、测试和不变式成为真实的，详细的建设计划就应该开始消失。"保留的部分"代码单独很难表达：业务理由、非目标、安全约束、外部契约，以及你不想通过试错重新发现的少数不变式。删除那些只是重复类和方法的文档已经做的事情的散文。

否则，你最终会有两份规格。人类会在审查中抱怨这个。Agent 往往会尝试同时遵守两份。

API 可以让代码表现得像规格

这个故事还有一个更乐观的版本。有些代码库比其他代码库更快达到"代码即规格"的境界，而 API 设计是一个重要原因。

如果内部 API 把行为隐藏在约定、弱类型的参数、setup 魔法和通用错误背后，Agent 就不能把代码当作规格。它必须从分散的散文和试错中重建规则。这对人类来说很慢，对模型来说更糟。

反之亦然。具有显式名称、任务级方法、强类型、可读的验证、有用的例子和可操作的错误的 API，给了 Agent 一个可以站立的具体基础。如果 Agent 可以检查表面区域，看到一个方法做什么，理解什么输入是合法的，从错误中恢复而不需要猜测，那么代码本身就承载了更多规格的负载。

这就是 AI 友好 API 设计理念在实践中重要的地方。显式的可发现性胜过约定。方法应该与真实任务对齐，而不是强迫 Agent 通过十几个脆弱的步骤。类型和验证应该展示合法输入是什么样的。错误信息应该指向下一个修复，而不仅仅是宣布失败。 introspection 和例子帮助模型从它已经拥有的代码库中学习 API 的形状。性能透明度也很重要，因为如果 API 没有给出任何线索，Agent 会乐意围绕一个昂贵的调用写出一个正确但糟糕的循环。

这不仅仅是关于公共 SDK。它适用于内部服务边界、库客户端、仓库抽象，甚至大型 monorepo 中的 helper 类。API 越容易发现和检查，Agent 就越容易把代码当作权威规格，而不是把更多的散文拖进上下文。如果感兴趣，我之前已经更深入地写过所有这些。

我强烈相信的是，没有单一正确的规格数量。答案取决于你正在做的工作。对于小型、边界清晰的任务，最佳点通常是结构化的意图：目标、几个例子、非目标，以及清晰的验收标准。这通常足以保持 Agent 的生产力，而不会让设置比任务本身更重。

对于 CRUD 流程、API 集成和数据转换等确定性工作，最佳点向右移动。这些领域易于约束、易于测试。更多的规格很快就能收回成本，因为它减少了重复的审查和返工。这就是 BDD、契约测试和可执行验收标准最有帮助的地方。

对于架构选项、研究综合或新颖产品想法等探索性工作，最佳点再次向左移动。过度规格化可能扼杀使 Agent 有用的灵活性。在这种情况下，我宁愿指定边界而不是结果：什么是必须为真的，什么是必须不发生的，需要什么证据，哪些决策仍然需要人类。

对于多 Agent 管道，最佳点再次向右移动。每个 Agent 之间的边界都需要契约。没有这个，你不是在协调一个系统，你是在堆叠解释并希望它们相互抵消。

所有四种情况的共同规则很简单：在扩大实现规模之前验证规格。

Agile 和 XP 中保留了什么

我不认为 Agent 使 Agile 或 XP 变得无关。它们使人容易分离出有用的部分，和人们已经在容忍的部分。

第一个牺牲品是那些主要为了按小时协调人类努力而存在的仪式。每日状态会议、膨胀的待办事项仪式、以及以比信息更多信心呈现的估算，不会因为 Agent 写了代码而变得更强。它们反而变弱了。Agent 可以如此迅速地改变任务的形态，以至于旧的估算比以前更快地变成虚构。这不意味着规划消失了。它意味着规划必须停止假装它可以像代码还是慢部分时那样以同样的舒适度预测实现成本。

Agile 中保留下来的是反馈逻辑。短周期仍然重要。薄垂直切片仍然重要。客户或利益相关者审查仍然重要。工作的软件仍然比进度剧场好，因为 Agent 可以非常快速地生成大量令人信服的错误。事实上，我认为快速反馈现在更重要了，而不是更不重要。如果一个团队可以在一个上午从模糊的想法变成大规模实现，它也需要一种方法来在午餐时间发现这个想法是错误的。

XP 存活得更好，因为它一直是关于让学习靠近代码。测试先行思维仍然重要，因为随着实现变得更便宜，可执行检查变得更有价值。持续集成仍然重要，因为每个 Agent 变更都需要一个关卡。重构仍然重要，因为 Agent 可以愉快地生成通过了一些测试但仍然留下没有人想在下个月维护的结构的代码。机器在这里没有骄傲。它会以完美的信心生成一团乱麻。

结对编程改变了形态，但核心思想保留了下来。我仍然希望设计判断靠近代码生成。有时这看起来像是一个人直接与一个编码 Agent 一起工作。有时这看起来像一个模型生成代码，而另一个模型以更窄的简报审查它。无论哪种方式，结对的有用部分从来不是两个人在键盘上和谐共鸣，旁边是喝咖啡的人类。是代码定型之前快速的設計反馈。

小发布也保留了下来，也许原因不那么浪漫。当 Agent 可以非常便宜地做出非常大的更改时，接受非常大的差异的诱惑也是如此。这是一个坏主意。审查、回滚和诊断更容易在小批次中完成。一个短期存在的功能分支比 4000 行的怪物更容易推理。

消退的是作为安慰剂的方法论。保留的是作为错误检测的方法论。Agile 和 XP 在它们使发现团队对问题理解得很差变得更便宜方面做得最好。这仍然是工作。Agent 时代只是移除了一些借口，并以更高的速度增加了新的出错方式。

Agent 开发的承诺是真实的。Agent 可以使实现显著变得更便宜，但一旦代码变得便宜，规格和验证就成为项目成功或失败的地方。

最能发挥杠杆作用的团队不会是规格写得最少的团队。他们会是知道什么时候三个要点就够了、什么时候需要一个真正的契约、以及什么时候契约必须变得可执行的团队。

Agent 正在变得更好。决策仍然是我们的。