SDD#

SDD 的核心思想为：在AI编写代码之前，必须先将人类模糊的想法转换为清晰，无歧义的结构化规范，让AI 在可控的轨道上运行。

SDD要求在编写代码前，先创建一份详尽、可验证的规格文档，这份文档起到技术契约的作用，是AI生成代码和验证的约束，将规格文档作为唯一真实来源，代码作为其派生产物。

SDD主要由4个步骤：定义规范，指定计划，执行落地，验证闭环。

1. Specify（定义规范）：定义问题、边界、成功标准。 产出：spec.md 文档
2. Plan（制定计划）： 架构选型，模块划分，接口定义。 产出：plan.md 文档
3. Implement（执行落地）：按照Plan 逐个任务实现。 产出：生成代码+测试(通常由TDD生成)
4. Validate（验证闭环）：自动化测试。产出：测试报告

Spec Coding 三条铁律：

1. No Spec, No Code — 没有文档，不准写代码
2. Spec is Truth — 文档和代码冲突时，错的一定是代码
3. Reverse Sync — 发现 Bug，先修文档，再修代码

spec的质量决定了后续的项目效率，好的spec遵循以下六大要素：

• Problem Statement 定义 “为什么做”
• Success Metrics 定义 “做到什么程度算完”
• User Stories 定义 “谁在什么场景下用”
• Acceptance Criteria 定义 “怎么验证”
• Non-Goals 定义 “什么不做”
• Constraints 定义 “技术约束”

TDD#

TDD用于保证 AI生成代码的质量。先写测试用例，让AI根据测试用例生成代码，保证生成的代码能够通过所有的测试用例，简单来说，就是先告诉AI什么是正确的，然后再去实施。

在实际开发中，SDD和TDD是共同使用的，SDD确保AI要做什么，保证行为规范，TDD确保AI做的对不对，保证正确性。

SDD 工具使用#

手工维护spec.md、plan.md等规范文档，手工创建目录结构、分支和任务列表，会比较繁琐麻烦，因此有很多支持 SDD 方法论的工具，下面介绍的三款是 OpenSpec、Spec-kit 和 Superpowers

1. OpenSpec是一款轻量级 SDD 工具，所有阶段手动实现

2. Spec-kit 是 github 官方github开发的 SDD 工具，所有阶段手动实现

3. Superpowers 是一个 AI skills 框架，所有阶段由AI触发调用实现

   头脑风暴 -> 工作树隔离 -> 编写实现计划 -> 子智能体执行 -> 测试驱动开发 -> 验证收尾

   三种工具对比

Vibe Coding 的适用边界#

Vibe Coding 最大的问题不是“AI 会不会写错”，而是没有足够的结构让错误暴露出来。需求不清、上下文不完整、没有测试、没有代码审查时，AI 生成越快，技术债可能累积越快。

Spec Coding 的核心制品#

好的 Spec 应该能让另一个人或另一个 AI 在不反复追问的情况下理解目标、边界和验收方式。

SDD + TDD 的组合流程#

1
需求想法
2
  -> spec.md 明确目标和验收
3
    -> plan.md 设计模块和接口
4
      -> tests 定义正确行为
5
        -> implement 编码实现
6
          -> validate 测试、审查、修正文档

TDD 在 AI 编程中的价值更明显：测试相当于给 AI 一个可执行的“正确性边界”。AI 可以生成实现，但测试负责持续判断实现是否偏离预期。

RAG、上下文和工具调用#

AI 编程质量很大程度取决于上下文质量。常见上下文来源包括：

• 仓库代码：现有架构、命名、封装、测试风格。
• 文档：需求、接口、设计规范、运行手册。
• 运行结果：测试日志、编译错误、lint 输出、性能数据。
• 外部知识：官方文档、版本说明、规范。

RAG 的作用不是让 AI “知道更多”，而是让 AI 在当前项目中拿到更相关、更可信、更可引用的材料。没有检索和验证的 AI 编程，很容易把通用答案误套到具体项目。

工具对比补充#

实践建议#

• 低风险探索可以 vibe，高风险或长期项目必须写 spec。
• AI 生成代码前，先让它读相关文件并说明现有模式。
• 复杂任务要拆成可验证的小任务，不要一次生成整套系统。
• 把测试、lint、类型检查、构建作为默认验证闭环。
• 代码和文档冲突时，先更新规范，再改实现。
• 不要把密钥、生产数据、不可公开业务细节随意放进 prompt。