从 Vibe Coding 到 SDD：为什么需要规范

一句话：SDD（Specification-Driven Development，规范驱动开发）把「做什么、什么算做完」提前写成可验收的契约，让 AI 在约束内实现；换来的是可预测和可审计，代价是前期时间与规范维护。

适用范围：本文讨论用 AI 编码工具做工程交付的团队。工具能力与命令以各自官方文档为准。

为什么需要

把「做一个用户登录」直接丢给 AI，通常会发生三件事：

1. 模型用自己的默认值填空。 它可能选 JWT、可能选 Session；密码可能用 bcrypt、也可能用 SHA-256。这些默认值来自训练语料，不一定是你系统的约束。
2. 同一需求多次生成，结构不同。 没有共同基准，Review 只能凭感觉判断「像不像」。
3. 三个月后没人记得当时的取舍。 代码在，决策的理由不在，改动只能靠猜。

根因不是模型笨，是输入里缺少两样东西：边界和完成定义。LLM 按概率补全，缺什么补什么，而且补得很像样。规范的作用是把这些空位提前填上，或者明确写「不做」。

Vibe Coding 这个概念由 Andrej Karpathy 在 2025 年初提出，原意是「跟着感觉让 AI 写，先不深究代码」。它适合探路，不适合签合同。

核心机制

1. 规范是契约，不是散文

能约束行为的是可验收的标准，不是形容词。对比：

差：登录失败要有锁定机制。
好：WHEN 同一账户连续 5 次密码错误，THEN 返回 HTTP 423，
    并锁定 30 分钟；锁定期间即使密码正确也拒绝。

后者能直接翻译成测试，前者只能靠人理解。验收标准是规范里唯一不能省的部分。

2. 阶段门控：在便宜的地方发现错误

需求 → 设计 → 任务 → 实现，每个阶段确认后再进入下一步。原因不是流程仪式，而是错误发现得越晚，返工面越大：需求里改一句话，和代码、测试、文档都写完再改，涉及的范围不同。

具体放大倍数取决于项目，不要背固定数字。判断是否需要加门，看一个问题：这一步的错误如果留到下一步才被发现，要重做多少东西？

3. 规范要能被工具读到

规范放在仓库里（如 specs/），再由各工具的规则文件指向它：

specs/<feature>/spec.md     ← 唯一权威
AGENTS.md                   ← 通用约束（支持的工具会自动读）
CLAUDE.md                   ← Claude Code 的项目指令
.cursor/rules/*.mdc         ← Cursor 规则

换工具时只改指针，不改规范。规范与工具解耦，是跨工具复用的前提。

4. 变更是增量的

全量重写规范是维护成本的主要来源。更可持续的做法是只描述变化：ADDED / MODIFIED / REMOVED，合入后再合并进当前规范。OpenSpec 把这套做法产品化了，但格式本身与工具无关。

关键取舍：规范越精确，AI 越不容易跑偏；越精确，需求变化时维护成本越高。粒度应跟「改错的代价」走，而不是跟「写得爽」走。

最小上手

10 分钟，用任何 AI 编码工具：

1. 建 specs/login/spec.md，只填四块。
2. 给 AI 的提示固定为三段：先读 spec；先复述理解并列不超过 3 个澄清问题；确认后再写代码。
3. 验收标准至少有一条能在本地跑。

# 功能：登录失败锁定

## 目标
防止密码被在线爆破，同时不误伤正常用户。

## 范围
做：连续失败计数、临时锁定、锁定提示。
不做：IP 封禁、验证码、管理员解锁后台。

## 约束
- 锁定时间 30 分钟，计数窗口 15 分钟。
- 锁定状态存 Redis，key 带账户 ID。
- 不做永久锁定。

## 验收
- GIVEN 同一账户已失败 4 次 WHEN 第 5 次密码错误
  THEN 返回 423，且后续正确密码也返回 423。
- GIVEN 锁定已满 30 分钟 WHEN 再次登录 THEN 正常放行，计数归零。

跑通的标志：AI 先复述需求和歧义点，而不是直接生成代码；你确认后，它产出的测试能对应到每一条 GIVEN/WHEN/THEN。

生产动作

• 规范进 git，和代码同 PR。 只改代码不改规范时，CI 至少给出警告；是否阻塞由团队决定。
• 每个 specs/ 子目录有 Owner。 没有 Owner 的规范一定会腐烂，工具只能提醒，不能负责。
• 主规范不写实现细节。 类名、参数默认值、表结构放 design.md。判断方法：这行内容变了，用户可感知的行为变不变？不变就不该在主规范里。
• 按代价分级。 支付、认证、数据变更的验收标准必须可执行；普通 CRUD 写清数据模型和接口契约即可。
• 定期清理。 合并已完成的增量、删除过期规范。规范数量增长快于代码，通常说明粒度太细。

边界

• 一次性脚本、黑客松原型、生命周期很短的探索：写规范的时间可能超过收益。
• 需求完全没方向时：先做原型探路，方向定了再补规范。此时规范是记录决定，不是替代探索。
• SDD 保证「按约定做对」，不保证「约定本身是对的」。 产品方向错了，规范只会让你更快地做错。
• 规范不能替代测试。 验收标准是测试的输入，不是测试本身；没有执行的验收标准仍然是文档。

讲清楚

SDD 解决的是 AI 编码里的输入质量问题。一句话需求会让模型用自己的默认值填空，导致产出不稳定、假设不可见、事后不可追溯。SDD 把这些默认值换成写下来的目标、范围、约束和验收标准，让输出有可检查的基准。它的核心不是文档格式，而是三件事：验收标准可执行、阶段之间有确认、规范跟代码一起进仓库。代价是前期多花时间，而且规范会腐烂，需要 Owner 和自动检查。原型和方向未定的探索不适合上全套，先探路再补规范更划算。

---

初稿 2026-07 | 最后修订 2026-10 | 事实核查：移除无出处的通过率/返工率统计与模型名