AI写代码总出错?不是AI不行,是你少了这份“施工图”
01SDD 的核心定位:AI 时代为什么要"先规范再编码"?
规范驱动开发(Specification-Driven Development,简称 SDD)是一种以结构化规格文档为核心驱动力的软件开发方法论。其核心理念是:在编写代码之前,先通过详尽、明确、可验证的规格文档定义系统"做什么"(What)和"为什么做"(Why),再以此作为开发的唯一事实来源,驱动后续的代码生成、测试验证与迭代维护。根据多个来源的描述,SDD 将传统"需求 → 代码"的模糊链路升级为"需求 → 规范 → 代码"的可验证闭环,让形式化、可执行的规范文档成为人、团队与 AI 之间的"动态契约"。
这种范式转变背后有一个关键背景:大语言模型在处理模糊需求时经常产生"看起来对但实际错"的代码。AI 极度擅长"按规格生成代码",但前提是规格必须清晰、结构稳定、上下文完整。没有规格约束的 AI 生成往往存在非确定性、上下文遗忘、隐性技术债务等问题。SDD 正是为了解决 AI "听不懂你到底要做什么"这一致命问题而生的。规范文档在此扮演的角色,类似于建筑领域的施工图——在正式动工之前,先把设计意图、技术要求、验收标准固化下来。1234
这种范式转变背后有一个关键背景:大语言模型在处理模糊需求时经常产生"看起来对但实际错"的代码。AI 极度擅长"按规格生成代码",但前提是规格必须清晰、结构稳定、上下文完整。没有规格约束的 AI 生成往往存在非确定性、上下文遗忘、隐性技术债务等问题。SDD 正是为了解决 AI "听不懂你到底要做什么"这一致命问题而生的。规范文档在此扮演的角色,类似于建筑领域的施工图——在正式动工之前,先把设计意图、技术要求、验收标准固化下来。1234
02从 Vibe Coding 到工程化:SDD 解决哪些痛点
Vibe Coding 是生成式 AI 兴起后的一种热门开发模式,其核心逻辑是"人类提意图 → AI 黑盒执行 → 验证运行结果 → 调整指令"。这种模式无需逐行编写代码,能快速启动项目,带来高效的心流体验,适合原型开发场景。然而,多个来源指出 Vibe Coding 存在三大"诅咒":非确定性(相同指令每次生成的代码可能完全不同)、上下文遗忘(项目规模扩大后 AI 容易遗忘前期设计逻辑)、隐性技术债务(为快速满足"运行通"的结果可能引入拙劣实现)。
SDD 的价值正在于此:它用确定性的规范约束非确定性的 AI 算力,从源头规避 AI 的能力缺陷。规范文档不再是代码的附属注释,而是"预编译的源代码",代码则成为规格经过 AI "编译"后的产物。这种关系反转使得维护软件本质上意味着演进规格,而非仅仅修补代码。人类角色也相应转变:从"代码产出者"转型为"文档定义者",聚焦"做什么、为什么做、要达到什么标准",而 AI 负责"怎么实现"。56
SDD 的价值正在于此:它用确定性的规范约束非确定性的 AI 算力,从源头规避 AI 的能力缺陷。规范文档不再是代码的附属注释,而是"预编译的源代码",代码则成为规格经过 AI "编译"后的产物。这种关系反转使得维护软件本质上意味着演进规格,而非仅仅修补代码。人类角色也相应转变:从"代码产出者"转型为"文档定义者",聚焦"做什么、为什么做、要达到什么标准",而 AI 负责"怎么实现"。56
03四大框架横向对比:设计理念与核心定位
| 对比维度 | Spec-Kit (GitHub) | OpenSpec | Kiro | Superpowers |
|---|---|---|---|---|
| 核心定位 | "蓝图派":从零开始的完整规划 | "园丁派":现有系统的增量改造 | 内置 SDD 工作流的完整 IDE | "全流程管家":需求到交付的完整管理 |
| 设计哲学 | 规格即法律,强调门控流程 | OPSX 灵活工作流,围绕变更提案 | 规格约束与 IDE 环境深度绑定 | 测试优先,证据驱动 |
| 适用场景 | 0-1 新项目、企业级项目 | 1-n 存量系统演进 | AI IDE 内的规格化流程 | 质量优先、快速迭代项目 |
| 规范形式 | 结构化 Markdown,支持复杂场景 | 极简 YAML,聚焦变更点 | 集成于 IDE 的结构化文档 | 自然语言 + 测试用例 |
| AI 集成 | 支持 15+ AI 编码助手 | 专注 Claude 和 Copilot | 深度绑定 IDE 环境 | 深度集成 GitHub Copilot |
| 学习曲线 | 较陡峭,适合流程意识强的团队 | 平缓,适合快速上手 | 中等,需适应 IDE 集成方式 | 中等,需理解测试驱动理念 |
| 典型用户 | 组织完善、有严格合规要求的大团队 | 敏捷团队、初创企业 | 使用特定 AI IDE 的开发者 | 质量导向团队、独立开发者 |
根据素材中的描述,Spec-Kit 由 GitHub 推出,旨在将软件开发从"不可预测的技艺"转变为可扩展的、受控的工程学科,其架构逻辑建立在"意图"与"实现"的物理隔离之上,强制执行分层工作流防止技术细节过早污染业务逻辑。OpenSpec 则由 Fission-AI 发起,定位为"极致极简主义",其核心使命是在不显著增加开发者认知负担的前提下为 AI 辅助编程引入工程纪律,尤其适合对已有系统做修改的场景。Kiro 由 Amazon 推出,将 SDD 集成到 IDE 中,围绕 requirements.md、design.md、tasks.md 组织需求、设计和任务。Superpowers 强调"测试优先,证据驱动",系统化降低复杂度。
值得注意的是,这四个框架并非互斥关系。有观点指出:"OpenSpec 比较适合用于对已有的系统做修改",而 Spec-Kit "适合做新项目";Superpowers 则"适合质量优先的团队"。在实际项目中,团队可根据项目类型、规模、规范复杂度等因素组合使用不同框架。78109
值得注意的是,这四个框架并非互斥关系。有观点指出:"OpenSpec 比较适合用于对已有的系统做修改",而 Spec-Kit "适合做新项目";Superpowers 则"适合质量优先的团队"。在实际项目中,团队可根据项目类型、规模、规范复杂度等因素组合使用不同框架。78109
04流程设计对比:五步法、七步法与三步法
- Spec-Kit 七步流程:constitution → specify → plan → tasks → implement → verify → evolve
- OpenSpec 三步流程:proposal → apply → archive
- Superpowers 五步流程:brainstorm → isolate → plan → TDD → review
- Kiro 集成式流程:requirements → design → tasks → 循环迭代
Spec-Kit 的流程最为完整,每个环节通过命令行工具与 AI 协作:宪法(constitution)定义项目原则、规格化需求(specify)产出用户故事与验收标准、计划(plan)确定技术栈与架构、任务拆解(tasks)分解为可独立验证的小任务、执行实现(implement)按任务逐一开发、验证(verify)确保符合规范、演进(evolve)持续迭代文档。
OpenSpec 则刻意保留极简三步,将一次具体的修改视为一个"提案"(Proposal),通过文件跟踪提案内容、关联的规格和模块、实现与验收情况,最后归档保存。这种设计使其对已有项目更友好,且天然适合 CI/CD 环境。Superpowers 的五步闭环强调"测试优先",内置 TDD 实践,要求 AI 在实现阶段先编写失败的测试再写代码。
从素材来看,这种流程差异直接影响了适用场景:Spec-Kit 适合需要完整工程管控的企业级项目,OpenSpec 适合需要快速迭代的敏捷团队,Superpowers 适合质量优先的项目。17911
OpenSpec 则刻意保留极简三步,将一次具体的修改视为一个"提案"(Proposal),通过文件跟踪提案内容、关联的规格和模块、实现与验收情况,最后归档保存。这种设计使其对已有项目更友好,且天然适合 CI/CD 环境。Superpowers 的五步闭环强调"测试优先",内置 TDD 实践,要求 AI 在实现阶段先编写失败的测试再写代码。
从素材来看,这种流程差异直接影响了适用场景:Spec-Kit 适合需要完整工程管控的企业级项目,OpenSpec 适合需要快速迭代的敏捷团队,Superpowers 适合质量优先的项目。17911
05SDD 与 TDD 的关系:是替代还是互补?
多个来源对 SDD 与 TDD(测试驱动开发)的关系进行了辨析。根据素材描述,SDD 与 TDD 并非替代关系,而是互补关系:SDD 在宏观层面(需求/功能级)提供方向,回答"我们要做什么";TDD 在微观层面(单元测试级)保障质量,回答"我们做得对吗"。
具体来说,SDD 的产出物是规格文档、任务列表,主要适用于需求澄清和架构设计阶段;TDD 的产出物是测试用例和通过测试的代码,聚焦代码正确性保障。有观点援引 Microsoft Learn 的说法:"你可以用 SDD 来产生明确的方向,同时在实现中仍使用 TDD 来提升代码质量。"
在实际工程中,GitCode 社区分享过一个案例:用 SDD+TDD 模式,4天开发了一个包含 21 个前端页面、33 个组件、32 个后端 API、10 个数据库表的评测系统,时间分配为写规格文档约 3 天、写代码+测试约 1 天。这说明 SDD 与 TDD 的组合能够在前期充分澄清需求,减少后期返工。1210
具体来说,SDD 的产出物是规格文档、任务列表,主要适用于需求澄清和架构设计阶段;TDD 的产出物是测试用例和通过测试的代码,聚焦代码正确性保障。有观点援引 Microsoft Learn 的说法:"你可以用 SDD 来产生明确的方向,同时在实现中仍使用 TDD 来提升代码质量。"
在实际工程中,GitCode 社区分享过一个案例:用 SDD+TDD 模式,4天开发了一个包含 21 个前端页面、33 个组件、32 个后端 API、10 个数据库表的评测系统,时间分配为写规格文档约 3 天、写代码+测试约 1 天。这说明 SDD 与 TDD 的组合能够在前期充分澄清需求,减少后期返工。1210
SDD与TDD关系对比
互补派观点
SDD 回答"做什么",TDD 回答"做得对不对",层级不同互补而非互斥
GitCode 实战案例显示 SDD+TDD 组合效率显著
规格先行可减少 TDD 测试用例的盲目性


独立派观点
SDD 已内嵌质量保障逻辑,可独立运作
对于简单改动,无需引入 TDD 增加复杂度
Spec-as-Source 模式下规格本身已具备可执行性
06SDD 成熟度分层:不同深度的落地路径
- Spec-First(规格先行)- 入门版:所有功能开发前必须编写规格文档,明确需求与验收标准。规格定稿后启动开发,开发过程中规格不再同步更新。适合小团队、快速迭代业务,低成本落地,解决基础需求歧义问题。短板是代码迭代后规格会逐步过时。
- Spec-Anchored(规格锚定)- 标准版:规格作为系统常驻基准文档,代码、架构发生变更时必须同步修订规格文档。搭配 CI 流水线自动化校验代码是否符合规格,实现文档、代码、测试三者实时对齐。这是目前中大型研发团队、AI 辅助开发场景最优落地模式,平衡灵活性与规范性。
- Spec-as-Source(规格即源码)- 高阶版:规格成为真正意义上的源代码,人类不再直接手写业务代码,仅维护标准化 Spec。由 AI 智能体根据规格全自动生成代码、自测用例、接口文档;规格变更自动触发代码全域更新。适用于标准化中间件、通用业务组件、低代码平台,对规格质量和 AI 能力要求极高。
07选型参考:不同场景下如何选择 SDD 框架
- 适合 Spec-Kit 的场景:从零开始的完整规划项目;企业级项目,强调流程规范和架构控制;跨团队协作,需要完整的文档化和审计追踪;组织完善、有严格合规要求的大型团队。
- 适合 OpenSpec 的场景:对已有系统做增量改造(1-n 场景);遗留系统改造,兼容性要求高的项目;强调快速迭代和风险控制的敏捷团队;需要在 CI/CD 环境中自动验证规范一致性。
- 适合 Superpowers 的场景:质量优先的团队,强调自动化测试驱动;原型开发,需要快速验证假设;独立开发者,需要轻量但有结构的流程;AI 代理密集型项目。
- 适合 Kiro 的场景:已使用特定 AI IDE(如 Claude Code)的开发者;需要将规格工作流深度嵌入开发环境;偏好"边写代码边定义规格"的交互式体验。
08多智能体协作与 SDD 的结合趋势
多智能体协作是 SDD 生态中的一个新兴方向。根据素材描述,当前已有探索将多智能体协作模式与 SDD 流程结合。例如,在 OpenSpec 的工作流中,可以为不同角色(产品经理、架构师、开发者、测试者)配置专门的 AI 智能体,各智能体围绕同一份规格文档协作,生成各自负责的产出物(proposal.md、design.md、tasks.md 等)。
多智能体的协作模式本身也有多种形态:生成器-验证器模式(一个生成规格/代码、一个检查质量,适合验收标准清晰的工作)、编排器-子智能体模式(主智能体分解任务分配给子智能体,适合任务可拆解的场景)、智能体团队模式(多个常驻队友各自认活、持续干活,适合长线工作)。
不过,也有观点指出多智能体协作的工程挑战:协调开销(需合理控制智能体数量避免过度拆分)、信息丢失(需建立统一的上下文管理机制)、循环依赖(需设置最大迭代次数和终止条件)、成本飙升(需评估协作收益避免简单任务过度工程化)。因此,"不是所有场景都需要多智能体——简单任务用单体更经济高效"。161718
多智能体的协作模式本身也有多种形态:生成器-验证器模式(一个生成规格/代码、一个检查质量,适合验收标准清晰的工作)、编排器-子智能体模式(主智能体分解任务分配给子智能体,适合任务可拆解的场景)、智能体团队模式(多个常驻队友各自认活、持续干活,适合长线工作)。
不过,也有观点指出多智能体协作的工程挑战:协调开销(需合理控制智能体数量避免过度拆分)、信息丢失(需建立统一的上下文管理机制)、循环依赖(需设置最大迭代次数和终止条件)、成本飙升(需评估协作收益避免简单任务过度工程化)。因此,"不是所有场景都需要多智能体——简单任务用单体更经济高效"。161718
09各框架核心观点一览
以下整理各来源围绕 SDD 框架的核心观点,供读者参考比较:
- Spec-Kit 核心观点:"Spec-Kit 更像完整的工程体系,从宪法到进化,七步标准化流程确保需求、设计与实现的一致性。适合从零开始的 0-1 项目,但对于已有代码库的细粒度变更会感觉步骤偏多。"
- OpenSpec 核心观点:"OpenSpec 的核心是轻量化,通过 proposal → apply → archive 三步管理变更差异,对已有系统更友好。社区讨论活跃,采用 proposal → apply → archive 工作流,将意图固化为持久化规范。"
- Kiro 核心观点:"Kiro 把 SDD 集成到 IDE 中,绑定了 IDE 环境,流程围绕 requirements.md、design.md、tasks.md 组织。强调在编码过程中自然融入规格定义。"
- Superpowers 核心观点:"Superpowers 强调测试优先、证据驱动,系统化降低复杂度。深度集成 GitHub Copilot,支持苏格拉底式对话,更适合质量导向团队。"
综合来看,四个框架代表了 SDD 落地的不同路径:Spec-Kit 提供最完整的工程管控体系,OpenSpec 追求轻量与灵活的平衡,Kiro 强调 IDE 内置的无缝体验,Superpowers 侧重测试驱动的质量保障。团队在选型时,应综合考虑项目类型(新建 vs 存量)、团队规模与流程成熟度、规范复杂度要求、是否已有特定 AI 工具偏好等因素,选取最匹配自身需求的框架或组合。
值得注意的是,SDD 框架本身仍在快速演进中。素材显示,2025 年 GitHub 发布 Spec-Kit 正式将 SDD 从理论推向实践,随后 OpenSpec、Superpowers 等工具相继出现,SDD 工具生态逐渐繁荣。随着 AI 编码能力的持续提升,SDD 的最佳实践和工具链也将不断迭代。79
值得注意的是,SDD 框架本身仍在快速演进中。素材显示,2025 年 GitHub 发布 Spec-Kit 正式将 SDD 从理论推向实践,随后 OpenSpec、Superpowers 等工具相继出现,SDD 工具生态逐渐繁荣。随着 AI 编码能力的持续提升,SDD 的最佳实践和工具链也将不断迭代。79
当前文章无评论,是时候发表评论了