SDD 规范驱动：先定义正确，再让代码实现

SDD（Specification-Driven Development，规范驱动开发）不是“多写文档”，而是把规范变成开发的唯一事实来源。接口长什么样、输入输出是什么、什么算完成，都先写清楚。代码、测试、文档和 AI 生成物，都围绕这份规范展开。

传统开发里，需求在脑子里，代码是事实，文档容易过期。SDD 反过来：规范是事实，代码是规范的实现，测试是规范的证明。它不追求大而全的文档，而追求轻量、可执行、可迭代的契约。

核心公式

规范 = 接口 + 数据 + 行为 + 验收

接口定义“怎么调用”，数据定义“长什么样”，行为定义“做什么”，验收定义“怎样算对”。把这四件事写清楚，开发和 AI 才有共同边界。

少量代码：从规范到实现

先写一段 OpenAPI 规范，定义新增待办的接口：

paths:
  /todos:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [text]
              properties:
                text: { type: string, minLength: 1 }
      responses:
        "201": { description: Created }
        "400": { description: Bad Request }

实现只需要围绕规范填充：

@app.post("/todos", status_code=201)
def add(todo: dict):
    if not todo.get("text", "").strip():
        raise HTTPException(400)
    return repo.save(todo)

测试则验证规范是否被满足：

def test_empty_text():
    assert client.post("/todos", json={"text": ""}).status_code == 400

规范定义契约，代码实现契约，测试证明契约。三者不脱节，返工自然减少。

SDD 的工作流

1. 写规范：接口、数据、行为、边界、验收标准。
2. 评审规范：产品、开发、测试一起看，先消灭歧义。
3. 生成骨架：用 OpenAPI、JSON Schema、Protobuf 生成客户端、服务端骨架和文档。
4. 实现逻辑：只填业务逻辑，不重新定义接口。
5. 契约测试：验证实现是否符合规范。
6. 回写规范：需求变更先改规范，再改代码。

为什么 AI 时代更需要 SDD

AI 最怕歧义。你说“优化一下”，它只能猜；你给规范、边界和验收，它才能稳定执行。SDD 让 AI 智能体有明确目标、可验证结果和回滚依据。规范是提示词的上游，也是 AI 编码的护栏。

关键实践

• 单一事实来源：接口定义只写一次，代码和文档从它生成。
• 可执行规范：能生成测试、能校验请求、能跑契约测试。
• 版本化：规范变更要兼容性评估，破坏性变更要显式升级。
• 从最小规范开始：先覆盖核心接口，再逐步扩展。
• 人工审查关键路径：登录、支付、权限、数据删除不能只靠生成。

常见坑

规范太抽象，等于没写；规范和代码脱节，等于白写；过度设计，拖慢迭代；只关注接口，忽视安全、性能和错误处理；生成代码不审查，技术债越滚越大。

结语

SDD 的核心不是文档，而是“先定义正确，再实现正确”。少量代码就能启动，但真正价值在减少歧义、加速协作、让 AI 可靠执行。工具负责生成，规范负责方向，人负责边界。写清楚，往往就是最高效的编程。