SDD规范驱动开发：当规范成为可执行的事实来源

一、SDD的核心判断：规范从“文档”变成“主要工件”

传统软件开发中，规范文档的地位是尴尬的。瀑布模型强调先写规范，但规范写完就逐渐与代码脱节；敏捷模型承认变化是常态，但规范往往被压缩到“足够就好”的程度。无论哪种流程，规范都是辅助物——代码才是事实来源，文档是围绕代码的注释。

SDD做了一个根本性的颠倒：规范本身就是主要工件，代码从规范中派生，人类决定“做什么和为什么”，AI辅助实现“怎么做” -1。

这个颠倒之所以在2026年才变得可行，原因只有一个：AI让规范驱动开发在经济上变得可行。过去写规范是一回事，把规范变成代码是另一回事，成本高到让规范驱动只能停留在理想层面。AI能够从规范生成代码之后，这道成本壁垒被打破了-1。

SDD用三个理想来定义规范与代码之间的关系：规范与代码始终同步，不留下过时文档；规范与代码之间保持最优平衡，既不过度文档化也不过度实现化；规范的精度足以驱动自动化生成。它不是对瀑布或敏捷的替代，而是一种与开发过程正交的方法——无论你使用哪种流程，规范都可以成为可靠的基础-1。

二、SDD的技术架构：三要素、四原则、七流程

理解SDD不能停留在“先写文档再写代码”的浅层描述。它有一套系统化的技术架构，可以概括为三要素、四原则和七流程。

三个技术要素构成了SDD的结构基础。声明性控制平面是整个体系的核心，正式定义接口契约、数据模式和不变量、事件拓扑、安全边界和兼容性规则。规范编译器将声明性规范转化为可执行的验证逻辑、代码生成输入和测试用例。验证与反馈回路持续检查实现代码是否仍然满足规范声明，偏离即刻报警。

四个原则定义了SDD的工作哲学。规范是“活文档”，持续更新以反映项目当前状态；规范是“单一事实来源”，所有实现决策回溯到规范；规范必须精确、完整、无歧义，足以驱动自动化生成；规范与代码之间的映射必须是可追踪的，任何实现都能回答“这是哪条规范的要求”-。

七个流程覆盖从需求捕获到部署验证的完整链路，核心可以压缩为一条结构化工作流：Proposal → Spec → Design → Tasks → Implement → Verify → Archive。这条工作流的本质是把每一次变更变成一个独立的、可版本化的代码单元，包含完整的上下文——为什么要做、做什么、怎么做、做哪些-2。

三、SDD工作流实战：从规范到类型安全代码

理解SDD最直接的方式是看一条规范如何转化为可运行的代码。以下使用TypeScript场景，展示SDD工作流中规范到代码的完整链路。

第一步：编写规范。 规范不是模糊的需求描述，而是精确的契约定义。一个用户查询接口的规范可以写成：

// specs/user-query.spec.ts
export interface UserQuerySpec {
  endpoint: "/api/v1/users/search";
  method: "GET";
  input: {
    keyword: string;
    page: number;
    pageSize: number; // 1-100, default 20
    sortBy: "createdAt" | "name";
  };
  output: {
    items: UserDto[];
    total: number;
    page: number;
  };
  invariants: [
    "pageSize 必须在 1 到 100 之间",
    "keyword 长度不超过 128 字符",
    "返回的 items 中每个 user.id 唯一"
  ];
}

这份规范是声明性的，不含实现细节。它定义了什么，不定义怎么做。

第二步：规范编译器生成类型与验证逻辑。 SDD工具链中的规范编译器读取上述声明，自动生成TypeScript类型定义和运行时校验：

// __generated__/user-query.types.ts
export interface UserQueryInput {
  keyword: string; // maxLength: 128
  page: number;
  pageSize: number; // min: 1, max: 100
  sortBy: "createdAt" | "name";
}

export interface UserQueryOutput {
  items: UserDto[];
  total: number;
  page: number;
}

// 运行时校验函数，由规范中的 invariants 编译生成
export function validateUserQueryInput(input: UserQueryInput): ValidationResult {
  const errors: string[] = [];
  if (input.pageSize < 1 || input.pageSize > 100) {
    errors.push("pageSize must be between 1 and 100");
  }
  if (input.keyword.length > 128) {
    errors.push("keyword must not exceed 128 characters");
  }
  return { valid: errors.length === 0, errors };
}

这不是手写的样板代码。类型定义、校验逻辑、错误消息全部从规范中派生。当规范中的pageSize范围发生变化时，类型定义和校验逻辑同步更新，不会出现“文档说50，代码写100”的偏离-。

第三步：AI基于规范生成实现。 规范和生成的类型作为输入，AI编码助手按照契约实现业务逻辑：

// src/services/user-query.service.ts
import { UserQueryInput, UserQueryOutput, validateUserQueryInput } from
  "../__generated__/user-query.types";

export async function searchUsers(
  input: UserQueryInput
): Promise<UserQueryOutput> {
  const validation = validateUserQueryInput(input);
  if (!validation.valid) {
    throw new ValidationError(validation.errors);
  }

  const { keyword, page, pageSize, sortBy } = input;
  const offset = (page - 1) * pageSize;

  const [items, total] = await Promise.all([
    db.user.findMany({
      where: { name: { contains: keyword } },
      orderBy: { [sortBy]: "asc" },
      skip: offset,
      take: pageSize,
    }),
    db.user.count({ where: { name: { contains: keyword } } }),
  ]);

  return { items, total, page };
}

这段实现代码的每一个决策——参数范围、排序字段、分页逻辑——都可以回溯到规范中的对应声明。代码审查时，审查者不需要猜测“为什么pageSize上限是100”，他可以直接打开规范文件查看。

第四步：验证与追踪。 SDD工具链提供规范到代码的追踪能力。SpecKit的/speckit.trace命令可以回答一个具体的问题：当前实现覆盖了规范中的哪些条款，哪些条款尚未被实现或验证-。这种可追踪性是传统开发方式无法提供的——在传统方式中，你无法自动回答“这段代码对应哪条需求”。

四、工具生态：SpecKit与OpenSpec的路线分化

2026年SDD工具生态已经形成了清晰的格局。GitHub SpecKit在2026年6月突破115,000 stars，不到一年时间从零成为类别锚点。OpenSpec以55,900 stars紧随其后，BMAD-METHOD和Task Master AI分别以49,500和27,700 stars占据各自的生态位-6。

两条主流路线代表了不同的设计哲学。SpecKit走的是标准化工程规约路线，提供端到端的结构化流程，强制六个阶段顺序执行：/speckit.constitution定义项目原则，/speckit.specify创建功能规格，/speckit.plan制定技术方案，/speckit.tasks拆解任务清单，/speckit.implement执行实现-。每个阶段产出一个可审查、可版本控制的工件，阶段之间不能跳跃-。

SpecKit在一个成熟Java项目中的实践数据显示，通过“定义原则→明确需求→制定计划→拆解任务→执行实现”的有序步骤，团队实现了风格统一、可追溯的AI辅助编码-30。这条路的代价是“仪式感”较重——每次变更都要走完完整流程。

OpenSpec走的是轻量增量路线，核心工作流只有三到五个命令：/opsx:propose创建变更提案，/opsx:apply让AI按照任务清单实现，/opsx:archive归档已完成的变更。OpenSpec不强制每个变更都走完整流程，而是把每次变更视为一个可版本化的单元，包含Proposal、Specs、Design、Tasks四个制品，整个开发过程透明、可审查、可追溯-2。

两条路线不是竞争关系，而是适配不同场景。SpecKit适合需要严格流程控制的企业级项目，OpenSpec适合快速迭代的增量开发。共同点是它们都把规范提升到了代码之上的地位。

五、SDD与Harness：规范驱动与驾驭工程的协同

SDD解决的是“给AI什么才能让它做对”，但还有一个同样重要的问题：怎么管AI才能让它持续做对。

这正是Harness Engineering（驾驭工程）的领域。来自南洋理工大学和阿里巴巴联合实验室的论文将Harness分解为三层结构：Control层是持久存在的制约物，包括AGENTS.md、架构规则、权限策略和验收标准；Agency层是模型被允许做什么，包括代码执行、文件读写、工具调用；Runtime层是任务执行过程中的动态机制，包括上下文组装、状态恢复、审批流程和执行轨迹记录。

SDD和Harness的协同关系可以用一个具体的场景来说明。SDD产出的规范文档是Control层的核心输入——规范定义了接口契约、数据模式和安全边界，这些正是Harness Control层需要持久维护的制约物。而Harness Runtime层在任务执行中持续检查实现是否偏离规范，偏离即刻触发纠正流程。没有SDD，Harness的Control层缺少精确的约束来源；没有Harness，SDD的规范可能在执行过程中被AI“逐步遗忘”。

一个真实的团队级实践案例来自国内某公司的AI研发转型。他们引入SDD+Harness组合后，AI出码率从不到25%拉升到90%以上。关键变化不是模型变强了，而是SDD提供了精确的规范输入，Harness提供了持续的质量控制-。另一个案例中，得物技术团队使用Harness+SDD+多仓管理模式的组合，实现了一个全栈功能的端到端AI交付——从后端接口到前端入口，规范作为唯一的事实来源贯穿始终-。

六、SDD的工程边界

任何方法论都有其边界，诚实面对边界比夸大适用范围更有价值。

SDD不适合探索性原型开发。当你还不清楚要做什么、需要快速试错的时候，写规范本身就是浪费。Vibe Coding在“快速验证一个想法是否可行”的场景中仍然有效。SDD适合的是需求相对明确、需要长期维护、有多个开发者协作的场景-。

SDD也不解决“规范写错了”的问题。如果规范本身定义了一个错误的接口契约，AI会忠实地生成错误的实现。SDD的价值在于让错误更容易被发现——当实现偏离规范时你能立刻知道，当规范本身有缺陷时你可以在规范层面修正并让代码自动同步。但它不替代人类对“做什么”的判断。

更根本的边界是：SDD要求团队具备写出精确规范的能力。规范不是需求文档的另一种格式，它是可执行的契约。写出精确规范需要的是对系统的理解，这种理解只能来自工程经验，不能来自工具。

结语

SDD的核心贡献不在于发明了新的开发流程，而在于在AI能够生成代码之后，重新定义了规范的工程地位。规范从“写给人看的文档”变成了“写给机器执行的契约”，从辅助材料变成了主要工件。

这个转变的深层含义是：工程师的核心工作正在从“写代码”转向“写规范”。代码的质量取决于规范的质量，规范的质量取决于工程师对系统的理解。工具可以生成代码，但无法替代对“做什么”和“为什么做”的判断。

当规范成为可执行的事实来源，SDD改变的不仅是一套工具链，而是工程师在AI时代的位置——从代码的生产者，变成系统的定义者。