Agent 开发需要多少规格说明？O'Reilly 的观点

Stack Overflow 博客发布了对 O'Reilly 的访谈，探讨了 Agent 开发中规格说明（spec）的合适量。核心观点是：当代码变得便宜时，困难的部分变成了定义"正确"是什么意思，以及建立可靠的检查方式。在 Agent 开发中，详细的规格说明不是旧时代的负担，而是确保 Agent 正确行为的关键。

背景：代码变便宜了

随着 AI 编程工具的普及，生成代码的成本大幅降低。以前需要开发者花费数小时编写的代码，现在 AI 可以在几分钟内生成。这带来了一个根本性的变化：

代码不再是瓶颈，定义"正确"才是瓶颈。

在传统的软件开发中，开发者需要花大量时间编写代码，规格说明可能相对简略。但在 AI 辅助开发的时代，代码生成变得容易，真正的挑战变成了：

• 如何明确地描述需求？
• 如何验证 AI 生成的代码是否正确？
• 如何确保 Agent 的行为符合预期？
• 如何建立可靠的测试和验证机制？

常见误区：规格说明是旧时代的负担

在 Agent 开发社区中，有一种常见的观点：

"详细的规格说明是旧时代的 overhead。给模型一个粗略的目标，让它自己探索和发现就好。"

这种观点有一定的道理——过度详细的规格说明可能限制 Agent 的创造力，增加维护成本。但 O'Reilly 的访谈指出，这种观点如果走向极端，会导致严重的问题：

1. 行为不可预测

没有清晰的规格说明，Agent 的行为就不可预测：

• 不同的运行可能产生不同的结果
• 边缘案例的处理方式不确定
• 错误的表现形式不可预期
• 难以调试和复现问题

2. 验证困难

没有规格说明，就无法判断 Agent 的行为是否正确：

• 什么是"正确"的输出？
• 如何衡量 Agent 的性能？
• 如何检测回归（regression）？
• 如何知道改进是否真的改进了？

3. 迭代无方向

没有规格说明，Agent 的改进就没有方向：

• 应该优化哪些方面？
• 如何评估变更的影响？
• 优先级如何确定？
• 什么时候算"足够好"？

4. 团队协作困难

没有规格说明，团队协作就变得困难：

• 不同成员对"正确"的理解不同
• 代码审查缺乏标准
• 知识传递困难
• 新人上手慢

合适的规格说明量

那么，Agent 开发到底需要多少规格说明？O'Reilly 的观点是：不是越多越好，也不是越少越好，而是要找到合适的平衡点。

规格说明的层次

可以将规格说明分为几个层次，每个层次有不同的详细程度：

第一层：目标和约束（必须有）

这是最基本的规格说明，定义 Agent 的目标和约束：

• 目标：Agent 要完成什么任务？
• 输入输出：Agent 接收什么输入？产生什么输出？
• 约束条件：有哪些硬性约束（时间、成本、安全、合规）？
• 成功标准：如何判断 Agent 是否成功完成了任务？
• 失败模式：Agent 可能以哪些方式失败？失败时应该如何处理？

这个层次的规格说明是必须的，没有它 Agent 就没有明确的方向。

第二层：行为规范（强烈建议）

这个层次定义 Agent 在各种情况下的行为方式：

• 正常流程：典型情况下的处理步骤
• 边缘案例：非典型输入或情况的处理方式
• 错误处理：各种错误情况下的响应策略
• 交互规范：与用户或其他系统的交互方式
• 优先级规则：多个目标冲突时的优先级
• 超时和重试：长时间运行或失败时的处理策略

这个层次的规格说明对于确保 Agent 行为的一致性和可预测性非常重要。

第三层：实现细节（按需）

这个层次涉及具体的实现细节：

• 算法选择：使用什么算法或方法
• 数据结构：使用什么数据结构
• 工具调用顺序：调用工具的具体顺序
• 提示词模板：具体的提示词内容
• 模型参数：温度、top-p 等模型参数

这个层次的规格说明应该按需提供。对于需要精确控制的部分，可以详细说明；对于 Agent 可以自主决策的部分，可以留给 Agent 自己决定。

规格说明的形式

规格说明不一定是冗长的文档。可以采用多种形式：

1. 自然语言描述：简洁的需求描述
2. 示例：输入输出示例（few-shot examples）
3. 测试用例：可执行的测试用例，既是规格说明又是验证手段
4. 状态机：定义 Agent 的状态和转换
5. 流程图：可视化的处理流程
6. 约束清单：必须满足的约束条件列表
7. 评估指标：量化的性能指标和目标

最好的规格说明往往是多种形式的组合。

规格说明与 Agent 自主性的平衡

关键问题是：规格说明和 Agent 自主性之间如何平衡？

过度规格说明的问题

如果规格说明过于详细，可能会：

• 限制创造力：Agent 无法探索更好的解决方案
• 增加维护成本：规格说明本身需要维护，变更成本高
• 降低适应性：Agent 无法灵活应对未预料到的情况
• 扼杀涌现：无法利用 Agent 的涌现能力
• 本末倒置：花在写规格说明上的时间超过了节省的时间

规格说明不足的问题

如果规格说明不足，可能会：

• 行为不可预测：Agent 的行为不一致，难以信任
• 验证困难：无法判断 Agent 是否正确工作
• 调试困难：问题难以复现和定位
• 迭代无方向：改进缺乏明确的目标和衡量标准
• 安全风险：Agent 可能做出不安全或不合规的行为

找到平衡点

找到平衡点的方法是：

1. 明确什么必须控制：安全、合规、核心业务逻辑必须精确控制
2. 明确什么可以放手：实现细节、优化方法、探索路径可以放手给 Agent
3. 使用测试作为规格：可执行的测试用例既是规格说明又是验证手段，比自然语言描述更精确
4. 渐进式细化：从粗略的规格开始，在发现问题时逐步细化
5. 定期回顾：定期回顾规格说明，移除不必要的细节，补充缺失的部分

规格说明驱动的 Agent 开发流程

基于合适的规格说明，可以建立以下开发流程：

1. 定义目标和约束

首先明确 Agent 的目标和约束：

• 要解决什么问题？
• 有哪些硬性约束？
• 成功的标准是什么？
• 可能的失败模式有哪些？

2. 编写测试用例

在实现 Agent 之前，先编写测试用例：

• 正常情况的测试
• 边缘案例的测试
• 错误处理的测试
• 性能和安全的测试

测试用例既是规格说明，又是验证手段。

3. 实现 Agent

基于规格说明和测试用例，实现 Agent：

• 使用 AI 辅助生成代码
• 让 Agent 在测试用例上运行
• 根据测试结果调整 Agent

4. 验证和迭代

持续验证和迭代：

• 运行测试用例，确保所有测试通过
• 监控 Agent 在生产环境中的行为
• 发现问题时，先补充测试用例，再修复问题
• 定期回顾和更新规格说明

5. 持续改进

随着对问题理解的深入，持续改进：

• 细化规格说明中模糊的部分
• 添加新的测试用例
• 优化 Agent 的性能和可靠性
• 扩展 Agent 的能力范围

总结

O'Reilly 关于 Agent 开发中规格说明的观点，可以总结为以下几点：

1. 代码变便宜了，定义"正确"变难了：AI 让代码生成变得容易，但明确需求和验证正确性变得更加重要
2. 规格说明不是旧时代的负担：在 Agent 开发中，合适的规格说明是确保 Agent 正确行为的关键
3. 不是越多越好，也不是越少越好：需要在规格说明和 Agent 自主性之间找到平衡
4. 测试是最好的规格说明：可执行的测试用例既是规格说明又是验证手段，比自然语言描述更精确
5. 渐进式细化：从粗略的规格开始，在实践中逐步细化，避免过度设计
6. 明确什么必须控制，什么可以放手：安全、合规、核心逻辑必须控制，实现细节可以放手

对于正在构建 AI Agent 的团队来说，这个观点提供了有价值的参考。在 AI 让代码变得便宜的时代，规格说明和验证机制的价值反而上升了。好的规格说明不是限制 Agent 的创造力，而是为 Agent 的创造力提供明确的方向和可靠的保障。

正如 O'Reilly 所说：当代码变得便宜时，困难的部分是决定"正确"是什么意思，以及建立可靠的方式来检查它。 这正是规格说明的价值所在。

原文链接：https://stackoverflow.blog/2026/08/21/dispatches-from-o-reilly-the-right-amount-of-spec-for-agentic-development/