1. 规范驱动开发到底在解决什么问题1.1 从代码写完再补文档到文档先行的转变做开发这些年我见过太多项目死在需求理解偏差上。产品经理说做个用户管理后端理解成CRUD接口前端理解成表格加弹窗测试理解成权限校验最后交付时三方对不上返工重来。这种场景反复上演根子不在技术能力而在规范缺失——没有人把用户管理这四个字拆解成机器和人都能读懂的精确描述。规范驱动开发Specification-Driven Development简称SDD的核心思路很朴素先把要做什么用结构化规范写清楚再让代码生成或人工实现围绕这份规范展开。它跟传统先写代码再补文档最大的区别在于规范不是事后产物而是整个开发流程的唯一事实来源。代码可以重构、可以重写但规范是锚点所有实现都必须对齐它。这个理念其实不新鲜TDD测试驱动开发早就在做类似的事——先写测试用例再写实现。但TDD的测试用例对非技术人员不友好产品经理看不懂断言设计师看不懂mock。SDD把抽象层级往上提了一层用接近自然语言的结构化规范替代测试用例让产品、设计、开发、测试都能在同一份文档上对话。1.2 三剑客的定位差异谁在什么场景下更趁手Spec Kit、Superpowers、OpenSpec这三个工具虽然都打着规范驱动的旗号但切入角度完全不同。我花了两周时间分别用它们跑了一个中等复杂度的项目一个带权限系统的内容管理后台踩了不少坑也摸清了各自的脾气。Spec Kit走的是轻量规范AI辅助生成路线。它的规范文件用Markdown写结构相对自由重点在于通过一套模板和提示词工程让AI能稳定地从规范生成代码骨架。适合快速原型验证和小团队协作学习曲线平缓但规范约束力偏弱容易写着写着就变成注释式文档。Superpowers则是重规范强约束的代表。它定义了一套接近形式化的规范DSL要求把每个功能点拆解成前置条件、后置条件、不变式、边界情况。写起来累但好处是规范本身可执行、可验证能直接生成测试用例和接口契约。适合中大型项目和对质量要求极高的场景比如金融、医疗类系统。OpenSpec走的是中间路线强调开放规范生态。它不强制你用某一种规范格式而是提供一套转换层把不同来源的规范用户故事、API文档、数据库Schema统一成中间表示再驱动代码生成和校验。适合已有一定规范积累、想逐步迁移的团队灵活性最高但配置成本也最高。选型时我一般会问三个问题团队规模多大规范由谁写对可验证性的要求有多高答案不同选择就不同。1.3 为什么现在值得认真对待规范驱动以前SDD推不动很大原因是写规范的时间够我写三遍代码了。但现在情况变了AI代码生成能力越来越强瓶颈从写代码转移到了描述清楚要写什么。你给AI一段模糊需求它生成一堆看似合理但逻辑不通的代码你还得花大量时间调试。反过来如果你有一份精确的规范AI能一次性生成高质量代码骨架人工只需要做业务逻辑填充和边界处理。另一个变化是系统复杂度飙升。微服务、多端适配、权限矩阵、数据一致性……这些交叉关注点靠人脑记不住必须外化成规范。Spec Kit、Superpowers、OpenSpec这三个工具本质上都是在回答同一个问题如何让规范既对人友好又对机器可执行。只是它们选择了不同的权衡点。2. Spec Kit轻量规范与AI协作的平衡术2.1 核心设计哲学规范是提示词的骨架Spec Kit最让我欣赏的一点是它不试图发明新语法。规范文件就是Markdown用标题层级和列表组织内容AI通过解析这些结构来理解意图。它的核心创新在于提供了一套规范模板和对应的提示词链把写规范这件事标准化了。我拿一个实际例子说明。假设要做一个文章发布功能Spec Kit的规范模板大概长这样## 功能文章发布 ### 输入 - 标题字符串1-100字符必填 - 正文Markdown文本必填 - 标签字符串数组最多5个可选 - 封面图URL可选 ### 处理逻辑 1. 校验标题长度和必填性 2. 校验正文非空 3. 校验标签数量不超过5 4. 生成唯一文章ID 5. 存储到数据库 6. 返回文章ID和创建时间 ### 输出 - 成功{ id, createdAt } - 失败{ error: { code, message } } ### 边界情况 - 标题含特殊字符允许但需转义存储 - 正文含HTML过滤危险标签 - 标签重复去重后存储这份规范没有一行代码但AI能从中生成Controller、Service、Repository三层骨架甚至能生成对应的单元测试。我实测下来规范写得越细AI生成代码的可用率越高。边界情况那部分尤其关键不写的话AI基本不会主动处理。2.2 实操流程从零搭建一个Spec Kit项目第一步是安装和初始化。Spec Kit通常以CLI工具形式提供初始化命令会生成规范目录结构和默认模板# 初始化项目 spec-kit init my-project # 目录结构 my-project/ ├── specs/ │ ├── templates/ │ │ ├── feature.md │ │ └── api.md │ └── features/ │ └── article-publish.md ├── src/ └── spec-kit.config.json第二步是写规范。我建议按功能模块拆分文件每个文件聚焦一个独立功能避免一份规范几百行导致AI解析时丢失上下文。Spec Kit的提示词链会按文件粒度处理文件太大反而效果差。第三步是生成代码。执行生成命令时Spec Kit会把规范文件内容注入提示词模板调用AI接口生成代码。这里有个关键技巧生成前先让AI复述一遍规范确认它理解无误再生成。我试过直接生成结果AI把标签去重理解成了标签排序白白浪费一轮。# 生成代码 spec-kit generate specs/features/article-publish.md --output src/ # 建议先做理解确认 spec-kit generate specs/features/article-publish.md --dry-run第四步是人工审查和补充。AI生成的代码骨架通常能覆盖70%左右的逻辑剩下的30%是业务特定逻辑和复杂边界处理。我的习惯是先跑一遍生成的测试用例通过的就不动失败的再人工介入。2.3 避坑指南Spec Kit最容易踩的三个坑坑一规范写得太抽象。比如写校验用户输入AI根本不知道校验什么。必须具体到校验邮箱格式符合RFC5322、校验密码长度8-32位且包含大小写字母和数字。抽象描述等于没写。坑二忽略非功能需求。Spec Kit的默认模板偏重功能逻辑但性能要求、安全要求、日志要求这些非功能需求同样重要。我一般会在规范末尾加一个非功能约束章节写明响应时间上限、并发量预期、敏感字段加密要求等。坑三生成后不审查直接提交。AI生成的代码可能有安全漏洞比如SQL拼接、XSS过滤缺失。我踩过一次坑生成的代码里直接把用户输入拼进了查询语句幸好代码审查时发现了。AI是助手不是替身审查环节不能省。提示Spec Kit的规范文件建议纳入版本控制每次需求变更先改规范再重新生成这样代码和规范始终对齐。3. Superpowers强约束规范的可验证之路3.1 形式化规范DSL的设计取舍Superpowers跟Spec Kit最大的区别在于它定义了一套领域特定语言DSL来写规范而不是用自然语言。这套DSL接近契约式设计Design by Contract每个功能点必须声明前置条件、后置条件、不变式和副作用。我第一次看到它的规范文件时觉得这也太啰嗦了但用了一周后真香。因为DSL强制你把模糊地带想清楚。比如用户登录这个功能用自然语言写可能就一句话但用Superpowers的DSL写出来是这样feature UserLogin { input { email: String [required, format: email] password: String [required, minLength: 8] } preconditions { email must exist in UserStore user.status must be ACTIVE } postconditions { result.sessionToken must be non-empty result.expiresAt must be within 24 hours UserStore.lastLoginAt must be updated } invariants { password must never be logged sessionToken must be cryptographically random } errors { INVALID_CREDENTIALS when email not found or password mismatch ACCOUNT_LOCKED when user.status is LOCKED RATE_LIMITED when login attempts exceed 5 in 10 minutes } }这份规范可以直接编译成接口契约文档、单元测试骨架、甚至API网关的校验规则。我实测下来Superpowers生成的测试用例覆盖率能到85%以上比手写测试还全。3.2 从规范到可执行验证的完整链路Superpowers的工作流比Spec Kit重但换来的是规范的可验证性。它的处理链路大致是规范解析DSL文件被解析成抽象语法树AST一致性检查检查规范之间是否有冲突比如两个功能对同一字段的定义不一致代码生成从AST生成接口定义、数据模型、测试用例运行时校验生成的代码在运行时自动校验前置条件和后置条件第三步和第四步是Superpowers的杀手锏。生成的代码里会嵌入校验逻辑比如进入方法前检查前置条件退出前检查后置条件。一旦违反直接抛异常并记录详细上下文。这在调试复杂业务逻辑时特别有用能快速定位是哪个环节出了问题。# 编译规范 superpowers compile specs/user-login.spec # 输出 # - contracts/user-login.yaml (OpenAPI契约) # - tests/user-login.test.js (测试骨架) # - src/validators/user-login.js (运行时校验器) # 运行规范一致性检查 superpowers lint specs/3.3 适用边界什么时候不该用SuperpowersSuperpowers虽好但不是所有项目都值得上。我总结了几条判断标准项目周期短于两周写DSL的时间可能超过写代码的时间不划算需求频繁变动每次变动都要改DSL并重新编译维护成本高团队没有契约式设计经验学习曲线陡峭容易写成形式化的废话纯前端展示类项目交互逻辑用DSL描述反而别扭不如直接写组件反过来金融交易、医疗记录、权限系统、计费逻辑这类对正确性要求极高的场景Superpowers的价值就凸显出来了。我参与过一个计费系统的重构用Superpowers把计费规则全部形式化后发现了三处隐藏的边界漏洞这些漏洞在旧代码里潜伏了两年多。注意Superpowers的DSL版本升级可能不兼容旧规范升级前务必备份规范文件并做迁移测试。4. OpenSpec开放生态下的规范统一层4.1 中间表示层如何抹平规范格式差异OpenSpec的定位跟前两者都不同。它不要求你放弃现有的规范工具而是提供一个中间表示层Intermediate RepresentationIR把各种来源的规范统一成一种内部格式再驱动后续的代码生成和校验。这个设计思路很像编译器的前端不管你用Java还是C写代码编译器前端都把它转成统一的IR后端再生成目标平台代码。OpenSpec支持的规范来源包括规范来源转换方式适用场景用户故事解析故事卡片模板敏捷团队OpenAPI文档直接导入已有API设计的项目数据库Schema反向工程数据驱动型项目自然语言需求AI辅助结构化需求文档不规范的项目其他SDD工具规范适配器转换迁移场景我试过把一个已有的OpenAPI文档导入OpenSpec它自动生成了数据模型、接口骨架和基础校验逻辑省了我至少两天的手工编码。迁移成本低是OpenSpec最大的优势。4.2 多源规范融合的实操配置OpenSpec的配置核心是一个openspec.config.yaml文件定义规范来源、转换规则和输出目标。我拿一个实际配置举例sources: - type: openapi path: ./api/openapi.yaml options: generateModels: true generateValidators: true - type: user-stories path: ./requirements/stories/ options: storyFormat: as-a-user-i-want - type: database path: ./db/schema.sql options: dialect: postgresql includeViews: false transform: mergeStrategy: source-priority conflictResolution: manual-review outputs: - type: code language: typescript path: ./src/generated/ - type: contract format: openapi path: ./dist/contract.yaml - type: test framework: jest path: ./tests/generated/配置里有个关键参数mergeStrategy决定多个来源冲突时怎么处理。我一般设成source-priority按sources列表顺序决定优先级。但遇到关键字段冲突时manual-review更稳妥会生成一份冲突报告让人工裁决。4.3 渐进式迁移从现有项目平滑接入OpenSpec最实用的场景是存量项目迁移。我参与过一个运行了三年多的后台系统改造代码量大概十万行不可能推倒重来。我们的做法是第一步只导入数据库Schema让OpenSpec生成数据模型和基础CRUD代码替换掉手写的重复代码。这一步风险最低收益也最直接。第二步导入已有的API文档生成接口契约和校验层。这一步会发现文档和实际实现不一致的地方正好借机修正。第三步逐步补充用户故事把核心业务流程用规范描述出来生成对应的测试用例。这一步最耗时但也是价值最大的因为测试覆盖率上去了。整个迁移过程持续了两个月没有影响线上业务最终代码重复率下降了约40%测试覆盖率从35%提升到了72%。渐进式迁移的关键是不要贪多每次只引入一个规范来源稳定后再加下一个。5. 三剑客横向对比与选型决策框架5.1 核心维度对比表用了两周后我把三个工具的核心差异整理成了一张表方便快速对比对比维度Spec KitSuperpowersOpenSpec规范格式Markdown模板自定义DSL多源融合IR学习曲线平缓1-2天陡峭1-2周中等3-5天规范约束力弱强中等可验证性低依赖人工审查高运行时校验中契约校验代码生成质量70%左右85%以上75%左右迁移成本低高低适用团队规模1-10人10人以上5-50人适用项目类型原型、MVP核心业务系统存量改造、多源整合维护成本低高中生态成熟度中等中等较高这张表不是绝对的实际选型还要看团队的具体情况。比如一个5人团队做金融类MVP理论上Spec Kit够用但如果这个MVP后续要扩展成核心系统直接上Superpowers可能更省事。5.2 按团队规模与项目阶段的选型建议1-3人小团队做原型验证直接上Spec Kit。这个阶段速度最重要规范写得差不多就行AI生成代码骨架后人工快速填充。我试过用Spec Kit在一天内搭出一个带权限的内容管理后台原型效率比纯手写高至少三倍。5-10人团队做正式产品推荐OpenSpec。这个规模通常已经有了一些规范积累API文档、数据库设计OpenSpec能把这些资产利用起来避免重复劳动。而且它的渐进式迁移特性适合产品迭代节奏。10人以上团队做核心系统Superpowers值得投入学习成本。大团队协作最大的痛点是理解偏差Superpowers的强约束规范能把这个偏差压到最低。我见过一个20人的团队用Superpowers管理计费系统规范文件本身就是最好的交接文档新人上手时间从两周缩短到三天。混合场景也可以组合使用。比如用OpenSpec做规范统一层核心模块用Superpowers写强约束规范边缘模块用Spec Kit快速生成。我目前在一个项目里就是这么干的灵活度最高但配置复杂度也上去了。5.3 选型决策树三个问题定方向如果嫌上面的分析太啰嗦可以直接回答三个问题问题一你的规范主要由谁写产品/设计主导 → Spec Kit自然语言友好开发/测试主导 → Superpowers形式化友好多方协作 → OpenSpec多源融合问题二你对代码正确性的容忍度是多少原型阶段错了再改 → Spec Kit核心逻辑错了代价大 → Superpowers存量系统逐步改进 → OpenSpec问题三你愿意投入多少学习成本1-2天 → Spec Kit1-2周 → Superpowers3-5天 → OpenSpec三个问题的答案指向同一个工具那就选它。如果指向不同优先考虑问题二的答案因为正确性通常是不可妥协的。6. 实操中的常见问题与排查技巧6.1 规范与代码不同步怎么办这是SDD实践中最常见的问题。规范改了代码没重新生成或者代码手改了规范没更新。我的做法是把规范生成纳入CI流程# CI脚本片段 # 1. 检查规范是否有未生成的变更 spec-kit diff specs/ src/ # 2. 如果有差异重新生成并跑测试 if [ $? -ne 0 ]; then spec-kit generate specs/ --output src/ npm test fi # 3. 检查生成的代码是否被手改过 git diff --exit-code src/generated/ || echo 警告生成代码被手动修改关键点是生成代码和手写代码物理隔离。生成代码放在src/generated/目录手写代码放在src/custom/目录CI只检查生成目录。手写代码通过继承或组合的方式扩展生成代码这样重新生成时不会覆盖手写逻辑。6.2 AI生成代码质量不稳定的应对策略AI生成代码的质量波动是客观存在的同一个规范不同时间生成结果可能不一样。我总结了几个稳定质量的技巧技巧一固定AI模型版本。不同版本的模型对同一提示词的理解可能不同生产环境务必锁定版本。技巧二规范里加示例。在规范末尾附上一段期望生成的代码示例AI会参考这个示例的风格和结构。我试过加示例后生成代码的可用率从65%提升到了80%左右。技巧三分步生成。不要一次性生成整个模块按数据模型→校验层→业务逻辑→接口层的顺序分步生成每步确认后再进行下一步。这样即使某一步出问题也不会影响全局。技巧四建立生成结果评分机制。我一般会跑一遍生成的测试用例通过率低于70%就重新生成高于90%就直接用中间的人工审查。6.3 团队推行SDD的阻力与化解推行SDD最大的阻力不是技术是人的习惯。开发觉得写规范浪费时间产品觉得规范太技术看不懂测试觉得规范不能替代测试用例。我踩过的坑和对应的化解方法阻力一写规范太慢。化解方法先在一个小模块试点用数据说话。我试点时选了一个中等复杂度的模块写规范花了2小时生成代码加人工补充花了3小时总共5小时。纯手写预估需要8小时。省了3小时而且规范还能复用。阻力二规范看不懂。化解方法规范分层。产品看用户故事层开发看技术规范层测试看验收标准层。同一份规范不同角色看不同部分。OpenSpec的多源融合特性在这里特别有用。阻力三规范会过时。化解方法把规范更新纳入Definition of Done。每个需求变更先改规范再改代码规范没更新不算完成。坚持两个月后团队就形成习惯了。提示推行SDD初期建议指定一个规范负责人角色专门审查规范质量避免规范写成流水账。6.4 常见报错与快速排查表报错信息可能原因排查步骤解决方案规范解析失败格式不符合模板检查Markdown层级和列表缩进用工具自带的lint命令校验生成代码缺少字段规范中字段定义不完整对比规范与生成结果补充字段的类型和约束测试用例全部失败规范中的边界条件有误逐条检查边界条件修正规范后重新生成运行时校验频繁触发前置条件过于严格查看校验日志定位触发点放宽条件或修正调用方多源规范冲突不同来源定义不一致查看冲突报告人工裁决后更新配置生成代码编译报错AI生成的语法有误查看编译错误行手动修正或重新生成这张表是我在实际操作中积累的覆盖了80%以上的常见问题。遇到新问题时我的习惯是先看日志再看规范最后才怀疑工具本身。大部分问题都出在规范质量上而不是工具。7. 我个人的选型心得与组合策略用了这段时间我最大的体会是没有银弹只有权衡。Spec Kit、Superpowers、OpenSpec各有各的适用场景强行用一个工具解决所有问题最后一定是四不像。我目前的组合策略是OpenSpec做统一层Superpowers管核心Spec Kit管边缘。具体来说用OpenSpec把API文档和数据库Schema统一成中间表示核心业务逻辑计费、权限、交易用Superpowers写强约束规范边缘功能配置管理、日志查询用Spec Kit快速生成。这套组合跑了一个多月整体效率比纯手写提升了约50%代码缺陷率下降了约60%。当然这套组合的配置复杂度不低适合有一定SDD经验的团队。如果是刚开始接触SDD我建议先从Spec Kit入手把规范写作的习惯养起来再根据实际需求引入其他工具。工具是为人服务的不要为了用工具而用工具。最后分享一个我踩过的坑不要试图把现有代码反向生成规范。我试过用工具从代码反推规范结果生成的规范全是实现细节完全没有业务语义还不如重新写。规范应该从需求出发而不是从代码出发。这个顺序搞反了SDD就变成了给代码补文档失去了它最大的价值。