作者逆境不可逃技术永无止境希望我的内容可以帮助到你大家吼 ! 我是 逆境不可逃 今天给大家带来文章《SDD 规范驱动开发 一篇让你彻底搞懂的全面解析提升自身实力的博文》近期文章 欢迎阅读Loop Engineering 从提示词工程到循环工程AI 编程的范式革命一句话总结SDDSpecification-Driven Development规范驱动开发是 AI 编程时代最重要的工作方法论 ——先写清晰的技术规范再让 AI 或人来写代码规范成为项目的 唯一真相来源。1. 为什么你需要了解SDD如果你正在使用或关注Claude Code、GitHub Copilot、Cursor、Codex CLI等 AI 编程工具你一定遇到过这些问题AI 生成的代码看起来对但实际偏离了你的意图对话一长AI丢失了上下文开始 胡说八道需求改了但你不知道该让 AI 重新生成哪部分AI 写的代码缺少边界处理、测试覆盖不全SDD 就是解决这些问题的。GitHub 首席产品工程师 Den Delimarsky 说过SDD 不是写没人看的需求文档也不是瀑布式的大规划 —— 它是把你的技术决策变得显式、可审查、可演进就像给你的思路做版本控制。ThoughtWorks 在 2025 年技术雷达中将 SDD 评为年度最重要工程实践之一。2. SDD 到底是什么2.1 权威定义根据Microsoft Learn的官方定义规范驱动开发SDD是一种结构化的软件开发方法它将规范Specification视为可执行的唯一真相来源Single Source of Truth代码只是规范在特定语言 / 框架中的表达。简单来说SDD 把传统的 先写代码文档后补 颠倒过来传统模式需求 → 代码 → (可能写)文档 SDD 模式需求 → 规范 → 计划 → 任务 → 代码2.2 核心思想意图即真理SDD 的最核心思想用一句话概括就是Intent is the Source of Truth意图即真理你的 意图想要什么功能、解决什么问题、有什么约束被记录在规范文件中成为驱动一切后续工作的源头。代码只是这个意图的执行结果而不是意图本身。2.3 一个直观的例子假设你要开发一个 用户登录 功能方式做法传统开发脑子里想清楚直接写代码。边写边调。Vibe Coding对 AI 说帮我写个登录功能看结果再说SDD先写规范支持什么登录方式、密码规则、错误处理、Token 策略、安全约束…… 然后按规范生成代码规范文档片段示例## 功能用户登录 ### 用户故事 作为注册用户我希望使用邮箱和密码登录以便访问个人数据。 ### 验收条件 - [ ] 用户可以使用邮箱密码登录 - [ ] 密码错误超过 5 次账户锁定 30 分钟 - [ ] 登录成功后返回 JWT Token有效期 2 小时 - [ ] 支持记住我功能7 天有效 ### 边界情况 - 邮箱格式不合法时返回 邮箱格式错误 - 账户被锁定时返回剩余解锁时间 - Token 过期时返回 401 并提示重新登录有了这样的规范无论是人还是 AI都能准确知道要做什么、怎么做、边界在哪。3. SDD vs 传统开发 vs Vibe Coding这是目前最受关注的三者对比维度传统开发Vibe CodingSDD核心驱动力经验与直觉自然语言描述结构化规范文档速度慢大量手工编码极快一句话生成较快写规范需要时间但生成快质量取决于个人水平参差不齐、难以预测可预期、可验证维护性依赖文档和代码注释差AI 输出缺乏上下文好规范即文档团队协作靠代码审查对齐困难每个人和 AI 对话不同容易规范是共同合约适用场景大型稳定系统原型探索、个人项目企业级开发、团队协作AI 友好度低代码上下文复杂高但不稳定极高且稳定SDD 的本质是取两者之长保留 Vibe Coding 的 AI 加速优势同时通过规范确保质量和可控性。4. SDD 的五大核心原则根据GitHub Spec Kit的官方设计哲学SDD 有五大核心原则原则一规范是通用语言Specifications as Lingua Franca规范是项目所有参与者产品经理、开发者、AI Agent、测试的共同语言。代码只是规范的一种实现形式。原则二规范必须可执行Executable Specifications规范不是模糊的 建议必须精确、完整、无歧义足以让 AI 直接生成可工作的系统。这意味着规范需要包含明确的数据结构清晰的输入 / 输出完整的边界条件具体的验收标准原则三持续精炼Continuous RefinementAI 代理持续分析规范中的模糊点、矛盾点、遗漏点主动提出澄清需求。规范在开发过程中不断被完善而不是 写一次就扔。原则四技术上下文驱动Research-Driven Context在制定规范之前先由 AI 代理搜集相关技术上下文 —— 现有代码库结构、组织内的技术规范、最佳实践等确保规范不是凭空想象。原则五双向反馈Bidirectional Feedback生产环境的指标、事故、用户反馈会回流到规范中形成持续改进的闭环。调试 修复规范重构 重组规范。5. SDD 的四阶段标准工作流SDD 采用严格顺序的闸门式流程每一阶段必须完成并通过验证才能进入下一阶段┌─────────┐ ┌─────────┐ ┌─────────┐ ┌──────────┐ ① 指定 ────▶ ② 计划 ────▶ ③ 任务 ────▶ ④ 实现 Specify Plan Tasks Implement (是什么) (怎么做) (分解) (写代码) └─────────┘ └─────────┘ └─────────┘ └──────────┘阶段一指定Specify—— 做什么为什么这是最关键的阶段。你需要定义用户故事谁、要什么、为什么功能需求具体要支持哪些操作验收条件怎样才算 做好了边界情况异常情况如何处理非功能需求性能、安全、可访问性等约束输出物spec.md功能规范文档阶段二计划Plan—— 怎么做用什么技术基于规范制定技术实现方案技术选型用什么语言、框架、数据库架构设计模块划分、数据流、接口设计实现策略从哪里开始、优先级顺序技术约束必须遵守的规则来自constitution.md输出物plan.md技术实现计划阶段三任务Tasks—— 拆成哪些小块将计划拆解为小而可测试的独立任务每个任务应该是原子性的不可再拆每个任务有明确的完成标准任务之间有清晰的依赖关系通常一个任务对应一次 AI 对话或一次 Commit输出物tasks.md任务清单阶段四实现Implement—— 写代码按照任务清单逐一实现每个任务独立实现、独立测试AI 代理每完成一个任务就对照规范验证规范更新时重新执行受影响的任务所有测试通过 功能完成为什么必须是严格顺序GitHub 团队在实践中的经验是跳过某个阶段会极大增加 AI 输出偏离意图的概率。计划阶段帮你提前发现架构问题任务阶段确保你不会遗漏细节。6. SDD 的三种层次策略ThoughtWorks 杰出工程师 Birgitta Böckeler 提出了 SDD 的三种成熟度层次帮助团队根据自身情况选择切入深度第一层Spec-first规格优先规格 → AI 辅助编码 → 代码做法写一个简短的功能规格然后让 AI 据此生成代码规格生命周期写完后在开发中使用开发完成后可能不再维护门槛⭐ 低适合刚开始尝试 SDD 的团队、中小型项目第二层Spec-anchored规格锚定规格 → AI 辅助编码 → 代码 → 规格持续维护做法规格不仅在开发初期使用还会伴随项目持续演进规格生命周期规格和代码一起版本管理功能变更时先改规格门槛⭐⭐ 中适合有一定 SDD 经验的团队、需要长期维护的项目第三层Spec-as-source规格为源规格即源码→ 完全自动化生成 → 代码做法规格本身成为主要源文件代码完全由 AI 从规格生成规格生命周期规格是唯一的真相来源代码可以随时丢弃重建门槛⭐⭐⭐ 高适合AI 工具非常成熟的场景、高标准化项目建议大多数团队从第一层开始逐步演进。不要一开始就追求最高层次找到适合自己团队的节奏最重要。7. 主流 SDD 工具一览7.1 GitHub Spec Kit官方推荐 ⭐GitHub 官方推出的开源 SDD 工具包目前生态最完整、社区最活跃命令作用/speckit.constitution创建项目 宪法—— 不可协商的技术原则/speckit.specify编写功能规范/speckit.plan制定技术实现计划/speckit.tasks拆解为可执行任务清单/speckit.implement按任务逐一实现支持平台Claude Code、GitHub Copilot、Gemini CLI7.2 社区 SDD 工具工具特点适合场景SDD Workflow(npm)11 个技能覆盖全流程支持自审查Claude Code 重度用户ccspec(npm)轻量级简化版 SDD快速上手、小型项目Agentic Sprint多 Agent 自主协作规格只减不增自治式开发团队SpecPulse完全本地运行隐私优先安全敏感项目SDDWCC18 个专业 Agent 协同大型复杂项目7.3 工具选择建议新手入门 → GitHub Spec Kit 或 ccspec Claude Code → SDD Workflow 或 Agentic Sprint 企业级团队 → GitHub Spec Kit 自定义 constitution 安全敏感 → SpecPulse完全本地8. SDD 实战从零开始的完整操作指南下面我们以GitHub Spec Kit Claude Code的组合为例展示一个完整的 SDD 操作流程。8.1 环境准备# 1. 安装 GitHub Spec Kit npm install -g spec-kit # 2. 在你的项目目录初始化 cd your-project speckit init初始化后会生成以下文件结构your-project/ ├── .speckit/ │ ├── constitution.md # 项目宪法 │ └── templates/ # 规范模板 ├── specs/ # 功能规范目录 └── README.md8.2 第一步建立项目宪法# 在 Claude Code 中执行 /speckit.constitution # 然后定义你的项目原则例如 - 所有 API 必须有 OpenAPI 文档 - 测试覆盖率要求 80% - 使用 TypeScript strict 模式 - 遵循 RESTful API 设计规范 - 所有用户输入必须做校验宪法的作用它是 AI 的行为约束决定了后续所有代码生成的质量底线。每个项目只需要设定一次。8.3 第二步编写功能规范假设我们要做一个 待办事项 API# 在 Claude Code 中执行 /speckit.specify 实现一个待办事项 REST API # AI 会引导你完成以下内容 ## 用户故事 1. 作为用户我希望创建待办事项以便记录要做的事 2. 作为用户我希望查看所有待办事项以便规划一天 3. 作为用户我希望标记事项完成以便追踪进度 4. 作为用户我希望删除不需要的事项以便保持列表整洁 ## 功能需求 - 支持 CRUD 操作创建、读取、更新、删除 - 每个事项包含标题、描述、优先级、截止日期、状态 - 支持按优先级和状态筛选 - 分页查询每页默认 20 条 ## 验收条件 - [ ] POST /todos 创建事项返回 201 完整对象 - [ ] GET /todos 返回分页列表支持 ?pagesizestatuspriority - [ ] PATCH /todos/:id 更新指定字段返回 200 - [ ] DELETE /todos/:id 删除事项返回 204 - [ ] 所有接口有统一的错误响应格式 - [ ] 请求体验证标题必填(1-200字符)、优先级枚举值 ## 边界情况 - 删除不存在的事项 → 返回 404 - 更新不存在的事项 → 返回 404 - 分页参数超出范围 → 使用默认值 - 请求体包含额外字段 → 忽略未知字段关键技巧✅ 用[NEEDS CLARIFICATION]标记不确定的地方AI 会主动提问✅ 边界情况写得越详细AI 生成的代码越健壮✅ 验收条件要可测试不要写 系统运行良好 这种模糊描述8.4 第三步制定技术计划/speckit.plan # AI 会根据规范和宪法生成技术计划 ## 技术栈 - 运行时Node.js 20 TypeScript - 框架Express.js - 数据库PostgreSQL Prisma ORM - 测试Vitest Supertest - 文档自动生成 OpenAPI 3.0 ## 项目结构 src/ ├── routes/ # 路由定义 ├── controllers/ # 业务逻辑 ├── models/ # 数据模型 ├── middleware/ # 中间件校验、错误处理 ├── utils/ # 工具函数 └── types/ # TypeScript 类型定义 ## API 设计 POST /api/v1/todos - 创建 GET /api/v1/todos - 列表分页筛选 GET /api/v1/todos/:id - 详情 PATCH /api/v1/todos/:id - 更新 DELETE /api/v1/todos/:id - 删除 ## 统一错误格式 { error: { code: NOT_FOUND, message: 待办事项不存在, details: { id: xxx } } }8.5 第四步拆分任务/speckit.tasks # AI 生成的原子化任务列表 - [ ] 1. 初始化项目结构和依赖安装 - [ ] 2. 定义 Prisma Schema 并生成迁移 - [ ] 3. 实现统一错误处理中间件 - [ ] 4. 实现请求体验证中间件 - [ ] 5. 实现 POST /todos创建 - [ ] 6. 实现 GET /todos列表分页筛选 - [ ] 7. 实现 GET /todos/:id详情 - [ ] 8. 实现 PATCH /todos/:id更新 - [ ] 9. 实现 DELETE /todos/:id删除 - [ ] 10. 编写集成测试所有接口 - [ ] 11. 生成 OpenAPI 文档8.6 第五步逐任务实现/speckit.implement # AI 会按照任务清单一个一个实现。 # 每完成一个任务AI 会 # 1. 生成代码 # 2. 运行对应测试 # 3. 对照规范检查 # 4. 标记任务为完成 # 全部完成后你得到的是一个可以直接运行的完整项目。8.7 实战要点总结步骤核心问题常见错误宪法我们的底线是什么写得太宽泛没有约束力规范用户到底要什么跳过了边界情况计划怎么实现最合理过早陷入实现细节任务能否独立完成和测试任务太大不够原子化实现代码是否符合规范不运行测试就标记完成9. 企业级实践案例9.1 民生银行的 SDD 实践民生银行于 2025 年启动 SDD 探索在银行核心系统的研发中采用了三层规格体系层级内容举例企业级全行统一的技术规范、安全策略、框架标准加密算法要求、日志规范领域级特定业务域的设计规范和工程知识账户模型设计、交易中间件选择项目级具体项目的需求、接口、数据结构规格转账接口的字段定义和验收条件实践成果单元测试行覆盖率接近70%符合私域规范的代码完成度超70%显著减少了代码审查中的规范性问题来源知乎 - 为什么银行科技研发需要 SDD9.2 Normal Computing 的生产级 SDD 经验这家公司在真实生产环境中实践 SDD 后提出了几个关键建议维护独立的 SDD 仓库作为全系统的唯一真相来源创建跨服务的系统级规范而不是每个微服务各自写混合规格同时包含产品意图和技术约束租户规则、集成限制、部署要求不要完全让 AI 设计数据库 Schema—— 如果你有生产数据和迁移历史10. SDD 的适用场景与局限性10.1 特别适合的场景场景为什么适合CRUD 类业务系统需求模式清晰规范容易标准化API 开发输入输出明确适合规格约束企业级系统对质量、安全、合规有高要求多团队协作规范是天然的对齐工具需要长期维护的项目规范作为文档持续保鲜AI 辅助开发规范是 AI 的最佳上下文10.2 不太适合的场景场景原因快速原型探索需求本身还不明确写规范为时过早创意性 UI 设计视觉美感难以用规范精确描述算法研究 / 性能调优需要大量实验和迭代规范跟不上微小的 Bug 修复写规范的成本超过收益一次性脚本写完就扔不需要规范10.3 务实建议 不需要 100% 的项目都用 SDD。建议采用混合策略探索阶段 → 快速 Vibe Coding 试方向方向明确后 → 切换到 SDD 模式稳定维护期 → 用 SDD 保证质量11. SDD 与其他方法论的关系很多人会把 SDD 和 TDD、BDD、DDD 混淆。它们不是竞争关系而是互补关系方法论关注点核心产物与 SDD 的关系SDD做什么、为什么What Why规范、计划、任务—BDD系统行为BehaviorGherkin 场景SDD 的验收条件可以用 BDD 格式写TDD代码正确性Correctness单元测试SDD 生成代码后TDD 保证质量DDD领域建模Domain限界上下文、聚合根SDD 的规范可以组织在 DDD 的领域边界内最佳组合DDD划领域→ SDD写规范→ BDD写验收→ TDD写测试→ AI 生成代码12. 12 条最佳实践与 6 个常见陷阱12 条最佳实践先立宪法在写任何规范前先定义项目的不可协商原则规范写在代码库里和代码一起版本管理不是单独的 Wiki关注 What不是 How规范描述 要什么不要写 用哪个函数实现用领域语言写规范用业务术语不是技术行话边界情况写得越细代码质量越高AI 需要这些来生成健壮的错误处理使用[NEEDS CLARIFICATION]标记强迫显式处理模糊点而不是靠 AI 猜测验收条件要可测试写 返回 400 错误信息不要写 处理异常每个任务都要能独立完成减少任务间的耦合代码改之前先改规范保持规范和代码的一致性规范写完后人工审查一遍5 分钟的审查能避免 5 小时的返工小步迭代从一个页面 / 一个 API 开始不要一开始就写全套系统规范把规范更新纳入完成的定义不更新规范 没做完6 个常见陷阱陷阱后果预防方法规范漂移代码改了规范没改越来越不一致规范更新纳入 Definition of Done过度规格化花 3 天写规范3 小时写代码关注关键约束细节留给任务阶段无人审查规范本身就有问题AI 忠实地实现了错误的意图规范和代码一样需要 Review一次性瀑布试图一开始就写完所有规范迟迟不进入编码按功能模块迭代边写规范边实现忽视多服务场景每个服务各自写规范缺乏全局一致性维护跨服务的顶层规范仓库空想功能在规范里加入 以后可能需要 的内容每个功能必须追溯到具体用户故事13. 未来展望13.1 SDD 正在成为行业标准GitHub将 SDD 作为 Spec Kit 的核心理念深度集成到 Copilot 生态Microsoft推出官方的 SDD 培训课程ThoughtWorks将其评为 2025 年最重要的工程实践Amazon Kiro正在构建以规范为中心的下一代 IDE13.2 开发者角色的转变在 SDD 时代开发者的角色正在从 代码打字员 转变为过去未来 手动编写每一行代码 意图设计者 逐行 Debug️ 架构把关人 靠注释和 Wiki 传递知识 AI 教练教 AI 理解领域知识⏱️ 工时 代码行数⏱️ 工时 意图清晰度13.3 尚待解决的问题大型规范的 Token 消耗完整规范 代码上下文可能超出 AI 窗口规范的自动验证如何自动检测规范自身的矛盾和不完整跨平台标准化不同 AI 工具对规范格式的理解尚未统一遗留系统的规格化如何为既没有规范也没有测试的旧系统补上规范14. 总结一张图理解 SDD项目宪法 (constitution.md) │ ▼ ┌──────────────────────────────────────────────┐ │ SDD 完整流程 │ │ │ │ 用户需求 ──▶ ① 规范 ──▶ ② 计划 ──▶ ③ 任务 │ │ (Spec) (Plan) (Tasks) │ │ │ │ ┌──────────────────┐ │ │ │ AI Agent 团队 │ │ │ │ 按任务清单实现 │ │ │ └──────┬───────────┘ │ │ ▼ │ │ ④ 工作代码 测试 │ │ │ │ │ ┌──────▼────────┐ │ │ │ 对照规范验证 │ │ │ │ 不通过 → 修改 │ │ │ │ 通过 → 上线 │ │ │ └───────────────┘ │ └──────────────────────────────────────────────┘核心要点SDD 的核心是 先写清楚要什么再决定怎么做规范是活的文档和代码一起演进AI 时代 SDD 不是可选项而是必选项—— 清晰的规范是 AI 准确性的保障不需要一步到位从一个小功能开始感受 SDD 的节奏SDD 不排斥其他方法它和 TDD、BDD、DDD 是互补关系现在就开始选择一个你正在做的小功能花 15 分钟写一份规范然后用它来驱动 AI 编码。你会惊讶地发现 —— 原来写代码可以这样清晰、高效、有底气。