规范驱动开发（Specification-Driven Development, SDD）是把整个软件开发过程组织在单一规格中心上的一种做法：团队先协作产出结构化的 Spec——领域模型、API Contract、质量约束，然后反向驱动设计、实现、测试、运维。
说人话，Spec Coding 就是把 AI Coding 从”凭感觉写”拉到”看规范说话”，用一份可维护、可验证的 Spec 让 AI Coding 真正变得可靠。
为什么现在谈 Spec Coding
原理上 SDD 把 Design by Contract 的契约视角和 Specification by Example 的可执行 Spec 结合起来，要求 Spec 既能被工具消费，又能作为业务、测试、运维之间共享的通用语言。
这种实践本身我们并不陌生。API 设计优先流程、CI 里自动审计、从同一份规范派生文档/SDK/契约测试/监控配置——这些都是传统 SDD 在人类生产里的常见形态。真正变化的是 AI Coding 的普及：Vibe Coding 带来的漂移和不一致在小项目里还能容忍，到了生产级系统就会系统性地出问题，SDD 正是因为能对抗这种漂移才重新被放到台面上，成为 spec-first / documentation-first 路径的代表。
当代 SDD 的代表性项目包括 Spec Kit、OpenSpec，以及围绕 AWS Kiro 和 Specmatic 构建的各类示例仓库。往前的探索空间还很大。
Vibe Coding 的代价与 Spec 的两个角色
开发者给一串模糊 prompt、让 AI 生成代码、修修补补”感觉对了就收工”——对快速原型没问题，对生产系统立刻暴露几个硬伤：
- 质量参差：输出强依赖 prompt 质量和上下文完备性，结果不稳
- 维护黑洞：缺乏明确的设计意图，后续开发者（人或 AI）都很难接手
- 协作障碍：各自和 AI 互动就会各自形成心照不宣的做法，团队很难对齐
- 交付难验证：需求本身就模糊时，无从证明”交付是正确的”
SDD 把 Spec 推到 AI 协同开发的核心位置，扮演两个角色。一是可执行的上下文：一份好的 Spec 给 AI 提供了完成任务所需的全部背景、约束、验收标准，让它能一次就接近对的答案，减少来回磨。二是对齐契约：Spec 成为产品、开发、测试共同遵守的单一事实源，让人和 AI、人和人之间的目标保持一致。
好的 Spec 像是你为明天失忆的自己留下的笔记。
SDD 的指导原则
当我们自发地用一套文档描述项目，要求 agent 遵循流程和规范，并在过程中检查和校准，实际上已经在做 Spec Coding 了。SDD 的精髓不在文档本身，而在这套指导原则：
提供项目契约
- 目标为中心：Spec 的主要内容是”系统应该做什么”，“怎么实现”相对次要
- 面向用户故事：每个功能点都挂在具体用户场景和明确验收条件上（Given-When-Then 或类似格式）
明确约束与边界：清晰定义 contract、领域模型、边界条件、异常处理——这些都是 AI Coding 幻觉的重灾区，只要 Spec 里不写清楚，模型就会自己编。
面向验收标准：设计时提供可量化的 Gate，聚焦外部可观测行为和业务成果；流程上把检查和准出做成规范动作。
活文档：Spec 不是一次性产物，必须随项目演进持续更新、可追踪、可验证，和代码保持同步。这一条非常重要，腐化的 Spec 比没有 Spec 更糟。
Gate 这个词很好用。它同时包含”规范”、“通过后才准出”、“程序化检查”、“TDD”的意味。spec-kit 模板里用的是
## Delivery Workflow & Quality Gates——考虑到这种说法有知名度、可以扩散、进 coding 类训练数据，以后在 PE 里用 gate 触发”验收”类任务没准也有奇效。“人不读、但 AI 会读”的 AI Friendly 技巧本身就是个值得单独展开的话题。
SDD 不是替代，是既有实践的延伸
SDD 不是凭空发明的概念，而是把既有的好实践重新打包，让它在 AI 协同里站得住：
- BDD / TDD / SBE 都强调用具体例子和测试定义需求。SDD 继承了这个思想，把这些”例子构成的规格”作为喂给 AI 的核心输入。
- API-First & Contract Testing 强调先约定 API 契约（OpenAPI / GraphQL Schema）。SDD 把契约作为 Spec 的关键组成部分，再叠加 Pact 这类契约测试工具保证服务间交互符合约定。
可以把 SDD 理解成这些实践在 AI 时代的一次现代化打包升级——它提供的是一个更统一的框架，把需求、设计、编码、测试、文档串成一条线，再把 AI 智能体作为核心执行引擎。
端到端的 Spec Coding 流程
先看传统开发里 Spec 的生命周期：
| 阶段 | 做什么 |
|---|---|
| Specify / Spec | PM 和 RD 把模糊的 PRD 提炼成结构化 Spec，问答是常用手段 |
| Review & Sign-off | 各方评审达成共识，形成版本记录 |
| AI Generate | 以 Spec 为高质量上下文，喂给 AI Coding Agent，生成设计/框架/完整实现 |
| Gate / Verify | 按 Spec 的验收标准选合适的校验手段：单元测试、端到端测试、必要时人介入 |
| Version Management | 需求变更先落在 Spec 上，Spec 与代码一起纳入版本控制 |
| Measure & Improve | 持续度量 Spec 质量和 AI 生成对齐度，优化模板和 prompt 策略（这一步最重要） |
传统流程里 Spec 天然存在，但是人有容错——开发过程中不断有场外输入，未必需要严谨。AI 的容错差得多，所以 AI Coding 里的 SDD 新实践其实是把传统 SDD 进一步结构化和规范化，从人和 AI 的共同视角回答同一个问题：如何让 Spec 每个环节都尽量清晰、可准出、可复现。
示例：GitHub Spec Kit
github/spec-kit 提供了一个命令式 SDD 流程，Cross Agent 设计可以让 Codex、Claude Code、Gemini CLI 等多种 Coding Agent 基于同一份 Spec 协同工作。流程的核心是——开发者负责想清楚”AI 应该做什么”，并把它维护在一份高质量 Spec 里，剩下的从设计到编码到测试由 AI 围绕这份 Spec 完成。理论上，随着模型迭代，一份足够好的 Spec 就等于成品项目。
基于模板和 init 的 Sub Command 实现，是很聪明的一个设计。
# 1. 初始化项目并创建 spec，AI 生成初始的 spec.md
/specify "Create a coupon service API with endpoints for creating, retrieving, and applying coupons."
# 2. 迭代细化 spec，手动编辑 spec.md 添加业务规则、数据模型、验收标准
/refine "Add a validation rule that coupons cannot be applied to already discounted items."
# 3. 生成执行计划，AI 分析 spec.md 产出详细的实现步骤清单
/plan
# 4. 执行计划，AI 根据计划生成和修改代码
/implement
# 5. 验证，AI 根据 spec.md 的验收标准生成并运行测试
/verifyOpenSpec 走的路径类似。
工具选择
SDD 的工具生态还在快速发展，目前几条主要分支：
- Kiro：Agentic IDE，把 Spec 当一等公民，提供从原型到生产的端到端 SDD 体验。Kiro 是较早的 Spec 标准实践者，把 Spec 规范化带入了大众视野。适合需要高度集成开发环境的团队。
- GitHub spec-kit：开源、轻量、命令行式工具集，可以灵活嵌入既有流程和 IDE，适合渐进式引入 SDD、想保持工具链灵活性的团队。觉得 spec-kit 还是太重可以试 OpenSpec。
- 各类 Agent OS。
一份好的 Spec 长什么样
分层结构
复杂项目里 Spec 是分层体系，保证从宏观战略到微观实现的一致性。
和面向人的开发一样，好的体系要有一些横切面保证按预期运行。比如”观测”——追踪人的做事精准度时观测未必重要，基本就是匹配”人员/需求/技术实现”，统计意义大于实践指导。但对于几十上百个基于同一份 Spec 并行跑的 agent，情况完全不同。我们可能需要专门设计观测方法，确保代码变更都能追溯到具体的 Spec 定义，每个特性 Spec 都能对齐到产品目标。
在这样的背景下，Gate 就不再只是代码质量准出的概念，而会影响整个开发过程的方方面面，那是更大的话题，按下不表。
研发视角的典型结构
高质量的 Spec 通常是结构化的，信息完备且无歧义。按技术设计来看大致长这样：
| 组成 | 核心内容 | |
|---|---|---|
| 目标与需求 | 目标与范围（Goal & Scope） | 这次变更要解决的核心问题、业务价值，以及明确的”做”和”不做” |
| 技术标准 | 用户场景与业务规则（User Scenarios & Business Rules） | 典型用户如何与系统交互，背后必须遵守的业务逻辑 |
| 接口 / 数据模型（API / Data Models） | API 端点、请求 / 响应格式、数据结构、字段约束 | |
| 状态与错误处理（State & Error Handling） | 系统可能存在的状态，以及异常情况下的响应方式 | |
| 依赖与约束（Dependencies & Constraints） | 对外部系统、特定技术栈或环境的依赖和限制 | |
| 非功能需求（NFRs） | 性能（延迟、吞吐）、安全、可用性、合规性 | |
| 准出与观测 | 验收标准（Acceptance Criteria / Gate） | 用 Given-When-Then 或类似格式列出所有需要被满足、可测试的条件 |
| 迁移与回滚计划（Migration & Rollback） | 涉及数据结构或重大架构变更时，明确的上线和回滚策略 |
实际创建时应该取舍，不必每一项都顶格写。
如何落地
团队角色与 Spec 构建
把 agents 当成一个团队而不是工具，是写好 Spec 的起手式。各角色在 SDD 里的分工：
- 产品经理：提供清晰的业务目标和用户故事，参与验收标准的定义
- 开发工程师：主导 Spec 编写，把业务需求翻译成技术上可执行的细节，监督 AI 实现
- 测试工程师：保证 Spec 里的验收标准是可测的，构建自动化验证框架
- 架构师：评审 Spec 里的技术方案、接口设计、NFR，确保符合整体架构蓝图
其中相当一部分角色可以由 AI 替代。搭 Spec 某种程度上就是通过制定规范让 agent 替代更多角色——当 AI 无法替代的剩余部分能被一个人 cover，就变成了一人团队。我认为团队协作模式接下来会快速从”工种配合”过渡到”上下文配合”，每个人独特的价值主要来自他独特的上下文。
把 Spec 当代码管
Docs-as-Code 是关键。所有 Spec 文档进 Git，和对应源码放一起。重大变更走正式流程——RFC 或 ADR，评审通过才合并。决策因此是透明和可追溯的。
反模式与防御
不要过度设计
Spec 应该聚焦”刚好”的细节，不要陷入无休止的文档编写失掉敏捷性。我的经验是，Spec 往往是在过程中迭代出来的，而这恰恰是当前 Spec 系统处理得最不好的环节。
不要让 Gate 粗糙
- 避免描述偏差：实际描述过程中的偏差很常见。让 agent 一上来先复述规范是个不错的校验方式。不只写清楚直接目标，也要说明目标背后的目的——这和给人描述需求一样。
- 提供清晰的 Gate：“系统应该跑得很快”这种标准等于没有。标准必须具体、可量化。评测才是一切。
防止 Spec 腐败
- 避免腐坏：代码实现后要立刻更新 Spec，并且祭出”彻底实现、删除旧文件、不留任何 TODO”这样的清理指令。缺乏维护的 Spec 很快就会变得毫无价值，甚至反过来成为阻碍。
- 避免僵化：不要把 Spec 当成最终真理。实现过程中肯定会发现 Spec 里的问题，该更新就更新，并要求 agent 重新读取。
持续要回答的问题
底层逻辑还是做好 Context Engineering。怎么压缩、索引、动态加载这些都会让 Spec 变得更好执行。
怎么控制 Spec 粒度
遵循”刚好够用”原则，Spec 详细程度应和功能的复杂性、风险成正比——这里其实有点像做架构，有基本原则但妙到毫巅处法无定法。简单的 UI 调整甚至不需要 Spec；复杂的计费逻辑，把状态机、错误处理、代码实现一次写清楚也不为过。
这也说明了 AI Coding / PE 的手艺不会过时——Spec 的边界定义和描述方式很多时候取决于手感。
怎么让 AI 严格遵循
- 前提是提供高质量、结构化的 Spec，尤其避免规则内部互相冲突
- 通过多轮 prompt 纠偏，过程中注意：上下文是否脏了、任务是否已经不适合当前 agent（换 agent、拆任务、或补工具）、是否出现 Spec 偏差
- 建立 Gate，尤其是程序化 Gate。最有效的始终是 TDD——基于 Spec 生成自动化测试，从结果上保证 AI 生成的代码确实遵循了 Spec
初创 / 快速迭代阶段怎么避免过度设计
- 区分主干和枝节：主干是稳定且高风险的部分（核心业务规则、API Contract、数据/安全相关），按高粒度写；枝节是可接受精度损失、易变的部分（UI 布局这类），保持低粒度
- 留变更空间：容忍可控的模糊，不要过拟合
- 主动迭代：说清楚的标准未必会被一次性遵循；一定的开放性也可能带来意想不到的好结果。提前对这些情况保持开放心态，设想可能发生的状况，及时更新 Spec
怎么做快速迭代
SDD 不排斥探索，但要聪明地协调：
- 试原型：不确定性高的任务，利用 AI 快速产出大量实现的特点，做一个有时间限制的冲刺。过程中能拿到 insight，也能借机摸清 AI 在你这个场景是否擅长，或者哪个 AI 更擅长。
- 自上而下：改代码时要求先改文档，分层情况下从上往下改，确保文档一致无矛盾后再落实到具体实现
- 产出 Spec 而非代码：把这一轮的产出定位成”一份更清晰的 Spec”，然后基于新 Spec 走正式 SDD 流程
最简迁移路径
全面转到 SDD 不用一次到位，可以分阶段：
- 构建最简 Spec：新功能配一个极简 Spec，至少包含目标、关键 Contract、Gate。可以直接让 AI 总结，比写一份 AGENTS.md 还简单。
- 用 Spec 方式开发关键增量：选项目里新的、核心的或复杂的功能，强制走完整 Spec 编写和评审。这个阶段可以引入 OpenSpec 这类工具，但要删繁就简，聚焦效果。
- 重构并建立治理：找到或沉淀出心水的规范后推广到整个项目，建立完善 Spec，作为团队默认工作方式——通常会伴随一次重构。
还可以继续聊的话题
- 从 Spec Coding 的视角看，Vibe 还能做什么、适合做什么
- 打磨项目、提升完成度，从 80% → 95% → 99% → 99.9% 每一段各有什么技巧
- 做 AI 算法优化和用 AI Coding 之间有什么有趣的关联
- 人与 AI 的协作聊完了，非人类之间的 AI Coding 方式有哪些
小结
Spec 驱动把开发的核心从模糊的 Vibe 转到明确的 Spec 上，就有机会把系统做得更可靠、更可维护、更能适应变化。
再往外说一步，这套逻辑不仅用在软件开发上。它的底层是人与 AI 的高效协同，Spec XXX 会是一整套方法论——不再是一种选择，而是高效构建系统的必经之路。