先说一个最近的感受:2025 年 AI 编程圈子的关键词,已经从"vibe coding"悄悄变成了"带约束的编码"。我自己也是从"把需求往对话框一扔,让 AI 自由发挥"开始玩起的,爽是真爽,但项目一旦过了两三个模块,问题就来了——代码倒是能跑,可谁也说不清某个功能当初为什么要这么写,AI 改了一处逻辑,另一处的行为悄悄变了,需求文档和代码之间仿佛隔了一堵墙。后来我认真试了 SDD(Specification-Driven Development,基于规范编程),配合 OpenSpec 管规范文件、SuperPowers 给 AI 装技能,才算把"能写代码的 AI"变成了"按契约写代码的 AI"。这篇文章不堆概念,就讲讲我是怎么把这套组合落地到真实项目的,以及踩过的那些坑。
适合什么人看:正在用 Claude Code、Cursor、opencode 这类 AI 编程工具写真实项目,对代码质量和需求可追溯性开始有要求的开发者。如果你只想让 AI 跑通 Demo,可能用不上这套;但如果你要交付的东西需要维护、需要给别人看、需要三个月后还能改得动,那 SDD 这条路径值得认真试一次。
1. 为什么"先写规范再写代码"正在成为 AI 编码的新范式
1.1 从 vibe coding 的狂欢到失控
vibe coding 最典型的场景是:你打开一个对话窗口,把需求用大白话描述一遍,AI 噼里啪啦生成一堆代码,你复制粘贴运行,发现报错就继续让 AI 修,来回几次项目跑起来了。这个过程的爽感来自"零门槛",但也埋了一个很深的雷——你几乎没有留下任何有意义的需求决策记录。
一旦项目开始膨胀,比如从单个脚本变成前端、后端加数据库的服务,对话式开发就开始失控。我印象很深的一次:让 AI 给内部工具加一个"数据过滤"功能,它自动把过滤逻辑塞进了原来的查询函数里,结果别的页面也调用了这个函数,整页数据少了一半。功能本身没错,但它的副作用完全超出了我提的需求边界。
这个问题的根源不是 AI 笨,而是需求上下文没有边界。对话天然是线性的、易丢失的,AI 在每一轮只能基于最近的聊天记录去猜,而代码库是一个高度耦合的结构。要让它在一个复杂的系统里做局部修改,必须有一个比"聊天记录"更可靠的东西来传递需求上下文。这就是规范文件。
1.2 SDD 是什么:规范不是文档,而是开发过程的"第一公民"
SDD,Specification-Driven Development,直译过来是基于规范编程。它和 TDD(测试驱动开发)经常被放在一起说,但两者约束的东西不一样:TDD 用测试约束"代码行为",SDD 用规范约束"需求边界和验收结果"。
一个典型 SDD 循环是这样的:
- 澄清需求,搞清楚"到底要解决什么问题";
- 把需求写成结构化的规范文件,明确功能范围、任务拆分、验收标准;
- 让 AI 或人工按规范实现,遇到偏差先改规范再改代码;
- 对照验收标准检查结果;
- 根据实际代码变更反向更新规范,保证它不腐化。
很多人一听"写规范"就本能抗拒,觉得这是重型流程、是文档负担。但这里的关键区别在于:传统文档是写给"人"看的,写完就躺在 Wiki 里发霉;SDD 里的规范文件是写给"AI 执行者"看的操作契约,它会直接参与每一次代码生成。换句话说,规范不是项目的附加产物,而是开发过程中的第一公民。
1.3 这套范式解决的真实痛点
我之前在团队里试着总结过,SDD 真正解决的痛点是这三个:
- 需求反复横跳:产品说"加个筛选",今天加,明天又改范围。有了规范的版本记录,每一次变更都对应到 spec 文件的某次修改,AI 不会再凭印象实现旧需求。
- 代码和需求对不上号:没有规范时,你很难回答"这个字段为什么存在"。有了 spec,你可以从代码反查到具体某条验收标准。
- 多人协作时语义不一致:规范就是团队间的共同语言。AI 编码工具再强,它也不会主动和别人对齐,只有一份显式的规范才能充当这个对齐锚点。
说白了,SDD 的本质是给 AI 的生成本能装一个"边界围栏"。围栏立在哪、能做什么不能做什么,全都写清楚,剩下的才是发挥空间。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. OpenSpec:把"需求讨论"固化成仓库里的规范资产
2.1 OpenSpec 在整套工具链里的位置
光有 SDD 理念还不够,规范放哪、按什么格式写、怎么写才能让 AI 高效读取,这需要一个具体工具来承载。OpenSpec 就是干这个的。
它本质上是一个规范生命周期管理 CLI,专门为 AI 编码时代设计。它不会替你想需求,但会帮你把需求讨论的产物变成一套有结构的、可版本化的、能被 AI 直接读取的规范文件。你可以理解成:Git 管代码版本,OpenSpec 管规范版本,两者并存于同一个仓库,代码提交和规范提交天然关联。
这比在 Confluence 之类的地方开一个"需求文档"页面要强太多。因为规范文件直接躺在代码仓库里,AI 编码工具在生成代码前能通过文件路径定位到它,不需要任何额外的检索步骤。
2.2 规范仓库的文件结构与生命周期
我用了 OpenSpec 之后,习惯把规范仓库分成两类区域:一类是项目级长期规范,描述整个项目的架构
