1. 从“写完再补文档”到“文档即代码”SDD 到底在解决什么问题第一次接触 SDDSpec-Driven Development规范驱动开发这个概念是在一个跨团队协作项目里。当时我们前后端加测试一共十几个人接口文档散落在三个不同的在线文档平台需求变更靠群里吼一声结果上线前一天发现两个模块的字段定义完全对不上。那次事故之后我开始认真思考一个问题为什么我们写了那么多文档却依然对不齐SDD 的核心主张其实很朴素——规范不是开发完成后的附属产物而是驱动开发流程的第一等公民。传统模式下需求文档写完就锁进文件夹代码才是唯一真相SDD 反过来把规范文件当作“可执行的契约”代码、测试、文档全部从规范派生或围绕规范展开。OpenSpec 就是在这个思路下被我们引入的一套工程实践框架它不绑定特定语言或平台更像是一套“用规范约束协作”的方法论加工具链组合。这篇文章适合三类人看一是正在被接口对齐、需求漂移折磨的研发团队负责人二是想引入规范化流程但不知道从哪下手的工程师三是对 SDD 概念好奇、想看看真实落地长什么样的技术管理者。我会把我们在 OpenSpec 工程实践中的完整思路、踩过的坑、可复用的配置和流程都摊开讲尽量做到你读完就能在自己项目里试起来。需要先说明一点SDD 不是银弹OpenSpec 也不是开箱即用的万能工具。它的价值在于把“规范”从一个静态文档变成一条贯穿需求、设计、编码、测试的流水线。理解这一点后面的所有实践才有意义。2. 整体设计与思路拆解为什么选择规范驱动而不是文档驱动2.1 传统文档驱动开发的三个死结在讲 OpenSpec 怎么落地之前得先说清楚我们为什么要换思路。传统文档驱动开发有三个绕不过去的死结这也是我们决定转向 SDD 的直接原因。第一个死结是文档与代码的时序错位。绝大多数团队的流程是产品写 PRD开发看完写技术方案然后开始编码文档在编码过程中逐渐过时。等到测试阶段想拿文档做验收依据时发现文档描述的接口和实际实现已经差了好几个版本。这不是谁不认真而是流程本身决定了文档天然滞后。第二个死结是规范缺乏可验证性。一份 Word 或在线文档里的接口定义机器读不懂CI 流水线没法校验只能靠人工 review。人工 review 的漏检率在字段多、变更频繁的场景下高得吓人。我们统计过一个中等规模项目接口字段级的不一致有将近三成是在联调阶段才暴露的。第三个死结是跨角色语义损耗。产品说的“用户状态”后端理解成数据库枚举前端理解成 UI 展示态测试理解成可切换的操作集合。同一个词在三份文档里含义不同沟通成本全耗在解释上。2.2 OpenSpec 的核心设计哲学OpenSpec 的思路是把规范从“给人看的文档”升级为“给人和机器共同读的契约”。它的设计哲学可以概括为三条。第一条规范先行代码派生。在写任何业务代码之前先把接口规范、数据模型、状态机用结构化格式定义清楚。这份规范是后续所有工作的唯一真相源代码实现是对规范的“翻译”测试用例是对规范的“验证”。第二条规范即配置可被工具链消费。OpenSpec 的规范文件采用结构化描述我们用的是 YAML JSON Schema 的组合可以被 lint 工具校验、被代码生成器消费、被 CI 流水线拦截。规范不再是死文档而是活的配置。第三条变更可追溯影响可计算。每次规范变更都走版本控制配合依赖分析能自动算出这次变更影响了哪些接口、哪些模块、哪些测试用例。这一点在多人协作时价值巨大。2.3 方案选型为什么是 OpenSpec 而不是自研或其它方案我们评估过三条路线纯自研规范工具链、采用通用 API 描述语言如 OpenAPI、引入 OpenSpec 这类规范驱动框架。纯自研的问题在于维护成本。规范工具链涉及解析、校验、代码生成、依赖分析多个环节自研等于养一个小型基础设施团队对多数业务团队不划算。通用 API 描述语言如 OpenAPI解决的是接口描述问题但 SDD 的范围比接口描述大——它还涵盖数据模型、业务规则、状态流转。OpenAPI 只能覆盖其中一部分剩下的还得另找方案容易形成工具碎片化。OpenSpec 吸引我们的点是它把规范的范围定义得比较完整同时保持了工具链的开放性。它不强制你用某一种描述格式而是提供了一套规范组织方式和配套的校验、生成、分析能力。我们最终选择它是因为它能在“规范完整度”和“落地成本”之间取得一个可接受的平衡。提示选型时不要只看功能列表一定要拿自己项目里最复杂的一个模块做 PoC概念验证。我们当时用订单状态流转模块做验证发现 OpenSpec 对状态机的描述能力刚好够用这才拍板。3. 核心细节解析与实操要点规范文件到底怎么写3.1 规范文件的组织结构OpenSpec 实践里规范不是一个大文件而是按领域拆分的目录结构。我们项目的规范目录大致长这样specs/ user/ model.yaml # 用户数据模型 api.yaml # 用户相关接口 rules.yaml # 用户业务规则 order/ model.yaml api.yaml state-machine.yaml # 订单状态机 rules.yaml common/ errors.yaml # 全局错误码 types.yaml # 公共类型定义这个结构的关键在于按业务领域拆分而不是按技术层次拆分。早期我们试过按 controller、service、dao 分层组织规范结果发现改一个业务功能要跨好几个目录非常别扭。改成领域拆分后一个功能的规范集中在一个目录下变更影响范围一目了然。3.2 数据模型的描述要点数据模型是规范的基石。我们用的是 YAML 描述加 JSON Schema 约束的组合。以用户模型为例User: type: object required: - id - username - status properties: id: type: string format: uuid description: 用户唯一标识 username: type: string minLength: 3 maxLength: 32 pattern: ^[a-zA-Z0-9_]$ status: type: string enum: [active, inactive, locked] default: active createdAt: type: string format: date-time这里有几个实操要点值得展开。第一字段约束要写全。minLength、maxLength、pattern 这些约束不是可选项它们是后续代码生成和校验的依据。我们早期偷懒只写 type结果生成的校验代码形同虚设前端传个空字符串都能过。第二枚举值要显式列出。status 用 enum 而不是 string这样代码生成器能直接生成枚举类型测试也能自动覆盖所有状态分支。第三description 要写人话。这个字段是给协作者看的别写“用户状态”这种废话要写“active 表示可正常登录locked 表示因安全原因被锁定需管理员解锁”。3.3 接口规范的描述要点接口规范描述的是请求响应契约。我们的 api.yaml 大致结构createUser: method: POST path: /api/v1/users request: body: $ref: #/specs/user/model.yaml#/UserCreateInput response: 200: $ref: #/specs/user/model.yaml#/User 400: $ref: #/specs/common/errors.yaml#/ValidationError 409: $ref: #/specs/common/errors.yaml#/ConflictError auth: required rateLimit: 10/min实操中容易踩的坑是错误响应定义不全。很多团队只定义 200 响应400、409、500 全靠开发临场发挥结果前端处理错误时各种猜。我们的经验是每个接口至少定义成功响应和两类错误响应错误响应的结构必须统一。3.4 业务规则与状态机的描述业务规则和状态机是 SDD 区别于普通 API 描述的关键。以订单状态机为例OrderStateMachine: initial: created states: created: transitions: - to: paid trigger: payment_success - to: cancelled trigger: user_cancel paid: transitions: - to: shipped trigger: ship - to: refunded trigger: refund shipped: transitions: - to: completed trigger: confirm_receipt这份状态机定义可以直接生成状态流转的校验代码也能生成状态覆盖测试用例。我们实测下来状态机描述清楚之后状态相关的 bug 减少了大概六成。注意状态机描述一定要和业务方一起过一遍。我们第一次写的时候漏了“支付超时自动取消”这条流转上线后才发现补的时候已经产生了脏数据。4. 实操过程与核心环节实现从规范到代码的完整链路4.1 环境准备与工具链搭建落地 OpenSpec 的第一步是把工具链搭起来。我们用的核心组件包括规范校验器lint、代码生成器、依赖分析器、CI 集成脚本。安装过程不复杂关键是配置要对。# 初始化规范目录 openspec init --dir ./specs # 校验规范文件 openspec lint ./specs # 生成代码 openspec generate --spec ./specs --lang typescript --out ./src/generated # 分析变更影响 openspec diff --base main --head feature/xxx配置文件的重点是生成规则映射。你需要告诉工具哪个规范文件生成哪种语言的代码生成到哪个目录用什么模板。我们的配置大致是generate: - spec: specs/user/model.yaml lang: typescript out: src/generated/models template: model - spec: specs/user/api.yaml lang: typescript out: src/generated/api template: api-client - spec: specs/order/state-machine.yaml lang: typescript out: src/generated/state template: state-machine4.2 规范编写的工作流规范编写不是一个人闷头写而是一个协作过程。我们的工作流是产品提需求产品在需求文档里描述功能但不写技术规范。开发写规范草案对应模块的开发根据需求写规范草案提交 MR合并请求。跨角色评审前端、后端、测试一起评审规范重点看字段定义、错误处理、状态流转。规范合入主干评审通过后合入触发代码生成。代码实现开发基于生成的代码骨架填充业务逻辑。这个流程的关键在于规范评审要当成代码评审一样严肃。我们早期把规范评审当走过场结果规范里的问题到编码阶段才暴露返工成本翻倍。4.3 代码生成与手工实现的边界代码生成能覆盖多少手工要写多少这个边界要划清楚。我们的原则是结构性代码全部生成业务逻辑全部手写。生成的部分包括数据模型的类型定义、接口的请求响应类型、参数校验代码、状态机流转校验、API 客户端。手写的部分包括业务逻辑实现、数据库访问、外部服务调用、复杂计算。这样划分的好处是规范变更时生成的部分自动更新手写的部分通过类型系统强制适配。比如给 User 模型加一个字段生成的类型定义会变手写代码里用到这个类型的地方编译就会报错逼着你去处理。4.4 CI 流水线集成CI 集成是让 SDD 真正“活”起来的关键。我们在流水线里加了三个卡点卡点一规范校验。每次提交都跑 lint规范格式错误、引用断裂、约束冲突直接拦截。卡点二生成代码一致性检查。跑一遍代码生成如果生成的代码和仓库里的不一致说明有人手工改了生成代码或者忘了重新生成拦截。卡点三变更影响分析。如果规范有变更自动分析影响的模块和测试用例在 MR 里贴出影响报告提醒 reviewer 重点关注。# CI 配置片段 spec-check: script: - openspec lint ./specs - openspec generate --check - openspec diff --base $CI_MERGE_REQUEST_TARGET_BRANCH --head $CI_COMMIT_REF这三个卡点上线后规范相关的低级错误基本绝迹联调阶段的不一致问题也大幅减少。5. 常见问题与排查技巧实录5.1 规范与代码不同步怎么办这是落地 SDD 最常见的问题。表现是规范改了代码没跟上或者代码临时改了规范没回写。我们的解决办法是把同步检查做成硬卡点同时降低回写成本。硬卡点就是前面说的 CI 一致性检查。降低回写成本的做法是提供一个命令能从代码反向生成规范草案人工确认后合入。这样临时改动也能快速回写到规范不至于积累成技术债。5.2 规范粒度怎么把握粒度太粗规范没约束力粒度太细维护成本爆炸。我们的经验是按“变更频率”和“协作边界”两个维度决定粒度。变更频繁且跨团队协作的部分粒度要细比如对外接口的字段定义。变更少且团队内部消化的部分粒度可以粗比如内部工具函数的参数。判断标准很简单如果这个地方出过协作事故粒度就细一点。5.3 团队抵触怎么破推行 SDD 最大的阻力往往不是技术而是人。开发觉得写规范是额外负担产品觉得规范看不懂测试觉得规范不能直接当用例。我们的破局点是先找一个痛点最明显的模块做样板。我们选了订单模块因为它接口多、状态复杂、协作方多。做完之后联调时间从三天缩短到半天bug 率明显下降。拿着这个结果去推其它模块阻力小了很多。另外规范编写工具要尽量友好。我们给规范文件配了 IDE 插件支持语法高亮、自动补全、实时校验写规范的体验接近写代码抵触情绪自然降低。5.4 常见问题速查表问题现象可能原因排查方向解决建议生成代码编译报错规范类型定义有误检查 model.yaml 的 type 和 required修正规范后重新生成CI 一致性检查失败手工改了生成代码对比生成代码和仓库代码回滚手工改动改规范联调字段对不上规范未覆盖该字段检查 api.yaml 的 request/response补全规范并重新生成状态流转异常状态机描述遗漏检查 state-machine.yaml补全流转并加测试规范评审效率低规范太冗长检查是否按领域拆分拆分规范聚焦变更部分5.5 几个独家避坑技巧技巧一规范文件也要 code review但 review 重点不同。代码 review 看实现逻辑规范 review 看契约完整性。我们专门整理了一份规范 review checklist包括字段约束是否完整、错误码是否覆盖、状态流转是否闭环等。技巧二给规范变更打标签。我们在 MR 里给规范变更打上 breaking / non-breaking 标签breaking 变更需要更严格的评审和更长的观察期。这个习惯帮我们避免了好几次线上事故。技巧三定期做规范健康度检查。每个月跑一次全量规范分析看哪些规范长期没更新但代码在变哪些规范引用已经失效。这些“规范腐化”信号早发现早处理。技巧四新人入职先读规范。我们把规范目录作为新人了解系统的入口比读代码快得多。新人读完规范再去看代码理解成本大幅降低。6. 落地效果与适用边界SDD 不是万能药6.1 我们实测下来的收益落地 OpenSpec 实践大概半年后我们做了一次复盘。几个可量化的收益接口联调阶段的不一致问题减少了约七成状态相关的 bug 减少了约六成新人上手时间从两周缩短到一周左右规范变更的影响分析从人工排查变成自动生成。不可量化但同样重要的收益是协作心智的转变。以前大家默认“代码是真相”现在默认“规范是真相代码是规范的实现”。这个转变带来的沟通效率提升比任何工具都值钱。6.2 什么场景不适合 SDDSDD 不是所有项目都适合。我们总结了几类不适合的场景探索性项目需求本身还在快速变化写规范等于浪费单人项目没有协作成本规范的收益有限一次性脚本或工具生命周期短投入产出比低。适合 SDD 的场景特征是多人协作、接口多、状态复杂、变更频繁、生命周期长。符合这些特征的项目SDD 的投入是值得的。6.3 后续可以扩展的方向如果你们团队已经跑通了基础的 SDD 流程可以考虑往几个方向扩展。一是规范驱动的测试生成从规范直接生成契约测试用例二是规范驱动的 Mock 服务前端不用等后端就能基于规范开发三是规范驱动的文档站点规范变更自动更新对外文档。我个人在实际操作中的体会是SDD 的落地难点从来不在工具而在团队是否愿意把规范当成一等公民。工具可以慢慢搭流程可以慢慢调但这个认知转变必须一步到位。踩过几次坑之后我越来越确信规范驱动开发的价值不在于规范写得多漂亮而在于它逼着团队在写代码之前先把事情想清楚。这个“想清楚”的过程才是质量真正的来源。