AI 辅助编程

spec 驱动开发

kp-011核心25 分钟03-工程工作流最小路径

一句话定义

spec 驱动开发（spec-driven development）是先写一份可执行规格——目标、接口、行为清单、边界与错误处理、验收条件——再让 AI 按规格实现、按规格验收的工作流。

为什么重要

对话式生成「想到哪写到哪」：模型边写边做隐含设计决策，人与模型对设计的理解各自漂移，最后 diff 无法评审、行为无法预期。spec 把设计决策前置并显式化：规格是人机之间的合同，实现只是合同的机械履行，验收是合同的逐条核对。它把 AI 从「猜你心思」变成「照图施工」，是中大型任务最可靠的主干工作流。

前置知识

kp-007（三类场景提示模板——spec 是新功能模板的完整形态）。

核心概念

规格五要素（最小模板）：

  1. 目标：一句话用户可见结果与动机。
  2. 接口：函数/API 签名、数据结构定义。
  3. 行为清单：编号列出每条可观察行为（正常路径 + 边界）。
  4. 错误处理：每类非法输入的期望行为（错误码/异常类型）。
  5. 验收条件：可运行的判定——测试名、命令、性能阈值。

流程四步：需求 → 规格（AI 草拟、人逐条修改）→ AI 按规格实现 → 按规格逐条验收。角色分工：人负责「规格正确性」（做什么、对不对），AI 负责「实现正确性」（怎么写、编不编得过）。

可判定性标准：规格的每一条都必须能转化为一次检查。「响应要快」不合格；「P95 < 500ms（压测脚本 bench.py）」合格。

原理与机制

spec 驱动把 kp-003 三元组的「验收」从一句结论扩展为一份逐条文档，并前移到生成之前。其失效模式的分析也清晰：实现发散的根源是规格缺条目——模型对空白处自由发挥；因此「行为清单要编号到每条边界」比「描述要详细」更重要。规格同时是评审对象：评审 30 行规格的成本远低于评审 300 行代码，而且评审规格时人是在「决定行为」，评审代码时人只是在「确认没有错」——前者才是工程师不可替代的判断。

实例或案例

Before（无规格）：「给订单加个取消功能」→ AI 自行决定：谁能取消、取消后状态、是否退款、超时规则……产出与业务规则冲突，返工三轮。

After（规格节选）：

# 订单取消规格 v1
1. 目标：买家可取消未发货订单，释放库存并发起原路退款。
2. 接口：POST /orders/{id}/cancel，鉴权沿用现有 middleware。
3. 行为：
   3.1 状态为 pending/paid → 取消成功，状态置 cancelled。
   3.2 状态为 shipped/completed → 返回 409，不改状态。
   3.3 取消成功必须同步释放库存（复用 Inventory.release）。
   3.4 paid 订单触发退款任务（异步，写 refunds 表）。
4. 错误：订单不存在 → 404；非本人订单 → 403；重复取消 → 幂等返回成功。
5. 验收：test_order_cancel.py 8 用例全绿；并发取消仅一次退款（见 5.2 压测脚本）。

操作步骤：

  1. 让 AI 先草拟规格：「只写规格不写代码」，对照业务规则逐条改。
  2. 把规格存为 specs/<feature>.md 入库，随 PR 一起评审。
  3. 实现时提示明确绑定：「严格按规格 3.1-3.4 实现，每条行为对应一个测试」。
  4. 验收时让 AI 输出「规格条目 → 测试用例」映射表，人工核对覆盖。

排错清单：

  • 实现仍偏离规格 → 检查偏离条目是否可判定；不可判定就改写规格而非责怪模型。
  • 规格越写越大 → 只规格化本次要做的行为，未定行为明确写「不做」。
  • 验收对不上 → 用映射表定位缺口，补测试或补实现。

公式或模型

本节不适用：spec 是流程约定；量化收益（返工率下降）在 kp-026 观测。

图示

需求 ──▶ 规格(人改 AI 拟) ──▶ 实现(AI) ──▶ 逐条验收
            ▲ 合同：评审规格=决定行为    │
            └────── 偏离即回改规格或实现 ──┘

直观类比

spec 驱动是装修先出图纸：没有图纸工头凭经验刷墙，返工不可避免；图纸（规格）评审便宜、施工（实现）有据、验收（逐条）客观。

常见误区

  • 把规格写成散文：必须是编号行为清单，否则无法逐条验收。
  • AI 写规格人签字：规格必须人逐条改——AI 草拟省的是打字时间，不是决策责任。
  • 规格一次定终身：实现中发现规格不合理，改规格并记录版本，而不是默许实现偏离。

与其他知识点的关系

kp-012 TDD 是 spec 的可执行化（行为条目→测试）；kp-013 审查的对象由「整段实现」缩小为「规格与 diff 的一致性」。

自测题

要点：目标、接口、行为清单、错误处理、验收条件。

要点：评审规格是在决定系统行为（人不可替代的判断），评审实现只是核对正确性；且规格评审成本低一个数量级。

  1. 规格五要素是什么？
  2. 为什么「评审规格」比「评审实现」更有工程价值？

延伸阅读

《Software Requirements（第3版）》Karl Wiegers——需求规格化的经典方法（本节仅取其可判定性原则应用于 AI 协作场景）。

#spec驱动#规格#验收