Specification——把决策翻译给 AI

上一篇文章讨论了 Decision——在信息不完整的情况下，如何做出最好的工程决策。

但决策做出来之后，问题还没完。决策是在人脑子里完成的——带着判断、权衡、以及对系统上下文的理解。而下一环 Execution，是由 AI 来执行的——AI 需要精确、完整、无歧义的输入

人脑子里的决策，和 AI 需要的输入，是两种不同的东西。二者之间存在一个翻译鸿沟

在整个链路中：

1 2	Knowledge → Context → Decision → Specification → Execution 收集筛选判断翻译执行

Specification 就是这个翻译层。它回答的问题是：如何把工程决策，变成 AI 可以精确执行、不会误解的描述？

先划清边界：这不是什么

在讨论 Specification 是什么之前，有必要先说明它不是什么。因为「Specification」这个词在软件开发里有很重的历史包袱，容易被理解成已有的概念

不是需求文档。 需求文档（PRD，产品需求文档；SRS，软件需求规格说明）描述的是「系统应该做什么」，属于 Knowledge 空间中的需求层。它是 Context 构建时的输入之一，是支撑 Decision 的原材料——而不是 Decision 的结果

不是技术方案。 技术方案讨论的是方案选型和架构设计——方案 A 还是方案 B，同步还是异步——属于 Decision 层。Specification 是 Decision 确定之后才开始的：方案已经定了，现在要把它写成 AI 能执行的描述

不是伪代码。 伪代码是给人类看的逻辑示意，可以省略细节、容忍歧义——因为人读伪代码时会自动补全缺失的信息。但 AI 不会。你漏掉的部分，AI 要么猜（可能猜错），要么问（打断流程），要么照字面执行（你只写了主流程但没写不能动幂等校验——它就真的把幂等校验删了）

Specification 是一个在传统流程中没有精确对应物的东西。因为传统流程根本不需要它

为什么传统流程不需要

在传统流程里，做决策的人和写代码的人是同一个。整个翻译过程发生在他脑子里：

传统流程：
  Decision → 脑子里的翻译 → 代码
            ↑
      这一步是隐式的、即时的、不言说的

他知道「在这里加校验」意味着什么——他知道不能破坏现有的幂等逻辑、知道测试需要覆盖哪些场景、知道改了这里要去改 MQ 消费者。这些都不是从决策文档里读到的——这些是他基于自己对系统的理解，在敲键盘的过程中自动补全的。

但在 AI Native 流程里，做决策和写代码的不是同一个主体：

AI Native 流程：
  Decision → 翻译 → AI 读取 → 代码
              ↑
      这一步必须显式化

AI 不会自动补全你没说的东西。你如果只说了「在 refund() 方法里加一个超 30 天校验」，AI 看到一个 hasRefunded() 幂等检查但你没提它——它会怎么处理？它可能保持不动（最好情况），可能删除它以简化代码（中等情况），可能在重构时不小心绕过了它（最坏情况）

Specification 的存在理由，就是填补这个「人知道但 AI 不知道」的隐性知识缺口

四种决策的序列化

Specification 不是凭空产生的——它是对四个 Decision 的结构化翻译。

回到上一篇讨论的四种决策：

Location Decision   → 在 Spec 中：精确指定改哪些文件、哪些方法、哪些行
Approach Decision   → 在 Spec 中：指定改法、遵循的模式、以及禁止的操作
Impact Decision     → 在 Spec 中：标注必须同步修改的地方、不能破坏的依赖
Verification Decision → 在 Spec 中：指定测试场景、边界条件、回归范围

拿退款校验这个例子来看，四种决策做完之后，Specification 大概长这样：

位置：RefundService.refund() 方法，第 42 行 validateOrder() 调用之后。

方案：新增校验方法 validateOrderAge(Order order)，抛出 OrderNotRefundableException。不可删除或移动 PaymentUtil.hasRefunded() 的幂等检查——它必须在新增校验之前执行

影响面：

RefundEventConsumer.handleRefundEvent() 需要同步更新——它直接调用了退款逻辑，需确认校验同样生效

RetryCompensationJob 的退款补偿分支不受影响——它只处理已通过校验的退款

RefundReportService 需要新增统计维度——退款被拒原因需要体现在报表里

验证：

TC1：正常退款（订单 15 天）→ 成功

TC2：超 30 天退款 → 拒绝，异常码正确

TC3：MQ 重复消息 → 幂等检查生效，不重复处理

回归范围：退款全流程 + 积分扣回 + 优惠券作废

每一段都是从对应的 Decision 翻译过来的。不是描述「用户要什么」，而是精确描述「这个决策怎么落地，以及为什么改这里不能动那里」

四种决策的序列化，解决的是「不要漏」的问题——把该说的都写进 Spec。但一个紧跟着的问题是：多说了怎么办？

约束与自由的平衡

Specification 最难的地方不是写得多详细——而是知道什么是必须写的，什么可以留给 AI

写得太多：每一行代码的写法都规定死了，AI 变成了打字机。而且你写的实现方案，有可能不如 AI 基于当前代码库风格生成的方案自然

写得太少：关键约束没提到，AI 自由发挥，把不该动的东西改了

一个有用的区分是：精确描述约束，留给 AI 实现自由

约束（必须在 Spec 中明确的事）：
  - 不能做什么（负面约束）——"不可删除 hasRefunded()"
  - 必须保持什么（模式约束）——"保持与现有校验方法一致的异常处理方式"
  - 必须同步什么（影响约束）——"同步更新 RefundEventConsumer"
  - 必须覆盖什么（验证约束）——"需要 TC1/TC2/TC3"

自由（可以留给 AI 的事）：
  - 方法内部的具体实现细节（变量命名、代码组织）
  - 辅助方法的抽取和命名
  - 日志、注释的风格和位置（遵循项目现有风格即可）
  - 单元测试的具体写法（只要场景覆盖到位）

这和开车导航有点像：你告诉目的地和必经点（约束），但具体走哪条路（实现），由导航自己计算

一个好的 Specification，不是最详细的，而是约束刚好够——多说一句就限制了 AI 更好的实现，少说一句就让 AI 踩了坑

AI 参与 Specification

Specification 本身，能不能由 AI 辅助生成？

答案是能，而且应该。因为 Specification 的原材料——Context 和 Decision——AI 在之前的环节里已经掌握了大部分。

Context 构建阶段，AI 读了代码、追踪了依赖、检索了历史文档。Decision 阶段（至少是辅助部分），AI 给出了候选方案和风险评估。基于这些信息，AI 完全可以草拟一份 Specification。

但有一件事 AI 做不了，也不该做：签字确认，而人在 Specification 环节要做的事情，不是从头写——是 review。对着 AI 草拟的 Specification，逐条确认：

位置对不对？有没有遗漏的入口？
约束全不全？有没有没提到的限制？
影响面有没有漏？AI 只能标注它追踪到的依赖——跨仓库的、配置中心里的间接依赖它可能没发现
验证场景够不够？有没有需要补充的边界条件？

AI 起草，人签字。这个分工模式让 Specification 不再是沉重的文档负担——因为 AI 承担了大部分写作劳动，人只需要做判断

而这个「人签字」的动作，也是 Decision 环节中「人对决策负责」的延伸。Specification 上的每一个约束、每一个验证场景——签字意味着你确认这就是你想要的东西。如果 AI 按照这份 Specification 执行出了错，不是 Specification 写得不够细，是签字的人没有把约束说清楚

写在最后

这篇文章讨论了 Specification——Decision 和 Execution 之间的翻译层，一个在传统流程中不需要存在、但在 AI 写代码的流程中变得必要的东西。

它不是需求文档，不是技术方案，不是伪代码。它是四类决策的结构化序列化：位置精确到什么地步、方案有什么必须遵守的约束、影响面有多少地方要同步、验证需要覆盖什么场景。

它的核心张力是约束和自由的平衡——多说了限制 AI，少说了留着坑。一个好的 Specification 是约束刚好够。

下一个问题：Specification 有了，AI 如何把它变成精确运行的代码？

这就是 Execution 要解决的问题。下一篇继续。

这是 AI Native 软件开发系列的第五篇。前四篇分别讨论了软件开发管理的对象是知识、知识的六个层次、从知识到上下文的筛选、工程决策——在不确定中做最好的选择。如果你有不同的理解或者实践经验，欢迎一起讨论。