SDD工程化落地：双环驱动开发流程

SDD（规格驱动开发）能不能指导AI和Agent在复杂业务系统做到真正的工程化落地？这需要在真实项目开发过程的实践中去验证。本文是我最近几个月在多个项目践行SDD的经验总结。

OpenSpec+Superpowers的选择

选择框架进行SDD（规格驱动开发）时，我同时选择了OpenSpec和Superpowers。之所以没有使用OpenSpec直接完成一个SDD的闭环迭代，在与它和Superpowers的配合，可以让这个闭环走得更稳健，具备编写更高质量代码的潜能。

二者在SDD过程中各有其优势。OpenSpec较好地遵循了SDD的设计思想和设计过程。OpenSpec在层级上对Spec的分解，隐含着对精益需求思想的遵守，对应关系如下：

MVP 对应 Change
Feature 对应 Capability
User Story  对应 Requirement
Scenario  对应 Scenario（GWT模式）
Task  对应 Task

OpenSpec引入Change和Archive，实现了对spec的版本管理，从propose（也包括ff和continue等）到archive，形成了完整的闭环。

但OpenSpec的propose过于简单，缺少足够深度的推理和分析，也缺少和开发者的有效互动，而仅仅是根据用户指定的需求，“想当然”地生成proposal、design与对应能力的业务需求spec，并由此快速地拆分为了task。

一旦用户确认了propose生成的spec，OpenSpec就会进入apply阶段，即从规格的生成直接转入代码实现阶段。这一转换稍显粗糙，虽然节奏更快，却失之于简单，难以保证设计和代码的质量。引入Superpowers，就能通过Brainstorming完成业务、架构、选型、迭代功能的反复确认，夯实方案，再通过TDD方式的Subagent-Driven Development放慢开发节奏，打磨代码质量。

增加软件工程的最佳实践

即便Superpowers采用了TDD的开发模式，但经过我的实际试验，发现它写出的代码质量仍有值得改进之处。从软件工程对代码内部质量的要求，即存在代码的“坏味道”，需要及时对它们进行重构。

同时，针对一个相对复杂的业务系统而言，倘若代码库只有单元测试的保护网，并不足以为质量兜底，更何况Superpowers编写单元测试的测试覆盖率也未尽如人意，同样在软件工程尤其是敏捷实践的指导下，需要在SDD的过程中增加遵循测试金字塔的自动化测试环节。

基于此，为了确保SDD在对真实且复杂的业务系统软件研发中达到工程化落地的目标，我又额外引入了由我自己开源的两个框架：Khufu和OpenMole。前者遵循测试金字塔的要求，能够为目标系统编写单元测试、集成测试、API测试和端到端测试UT、IT、API Test、E2E Test）；后者遵循我提出的坏味道驱动重构的方法，为已有代码库开展重构。

Khufu框架的github地址为：https://github.com/agiledon/khufu， 能够支持Agent智能生成自动化测试用例。一旦打造了这样一层防护网，就能为后续的重构实现安全兜底。OpenMole框架的github地址为：https://github.com/agiledon/openmole。

这两个框架都可以通过npm直接安装。

SDD的双环驱动开发流程

由此获得由意图环和执行环构成的双环驱动开发流程，它的绘制灵感来自DevOps的双环图。如下图所示，左侧为意图环，右侧为执行环。注意，两个环之间的转换点成为双环驱动开发的两个枢纽。枢纽A代表意图环到执行环的切换，枢纽B则由执行环切换回意图环。

除前置输入的准备阶段外，双环驱动开发流程一共分解为8个步骤。让我们以制造行业的MES系统的研发为例，依照步骤分别细述。

步骤0：三重前置输入

开发流程的起点可以输入三个内容：

• PRD（由用例组成）
• Harness（约束资产）
• UI原型（通过UIPro创建）

产品需求文档

PRD（产品需求文档）本身没有严格的格式定义。同样基于软件工程的实践，个人建议使用UML中的用例规约，会是最佳选择。一方面，UML的用例本身被广泛用于业务建模和需求分析；另一方面，它也给出了全世界建模人员都遵循的标准格式。以MES系统的创建生成订单用例为例，其用例规约为：

用例编号：UC-01
用例名称：创建生产订单
参与者：计划员
简要描述：根据销售订单或预测需求在MES中创建生产订单。
前置条件：用户已登录且具有“创建生产订单”权限。
后置条件：新生产订单记录生成，状态为“已创建”。
基本流程：
1. 计划员进入“生产订单管理”界面。
2. 点击“新建订单”。
3. 输入订单基本信息（订单编号、产品编码、数量、交期）。
4. 选择工艺流程版本。
5. 保存订单信息。
6. 系统生成订单记录。
异常流程：
3a. 必填字段缺失 → 提示补全。
4a. 工艺流程不存在 → 提示选择有效流程。
业务规则：
- 订单编号唯一。
- 数量 > 0。
补充说明：支持Excel批量导入。

正如前面所讲，OpenSpec的一个change应等于精益需求的一个MVP，故而对PRD文档的管理可以按照MVP的要求进行分解。之所以使用MVP而非迭代的概念，是希望SDD的每个迭代都能输出一个最小可用产品（Minimal Viable Product），这正是MVP的定义，如此一来，在完成一个开发闭环之后，可以运行SDD开发出来的产品，及时进行验证，确认代码实现与规格意图没有出现偏差。

我建议将所有PRD分解的MVP文档都编写markdown文件，存放在目标系统主目录的docs/prd之下。

约束资产

Harness在AI软件工程中是一个重要方法论，此处则仅涉及到为SDD定义的约束资产，相当于为整个SDD过程立规矩。包括需求PRD和项目知识库在内的整个约束资产可参考如下结构：

目标项目/
├── AGENTS.md / CLAUDE.md              ← 你在这里（导航地图）
├── constitutions.md                   ← 项目宪法（最高原则）
├── docs/
│   ├── harness/                       ← 约束工程三件套
│   │   ├── context-package/           ← 约束信息（安全/架构/资源/业务）
│   │   ├── tool-schema/              ← AI Agent 工具定义与权限
│   │   └── eval-set/                 ← 质量门禁评测集
│   └── prd/                           ← 需求规格文档
│       ├── project.md                 ← 需求总导航
│       └── mvp-1.md                   ← MVP v1 需求规格
└── knowledge/                         ← 知识库
    ├── arch/                          ← 架构决策记录（ADR）
    ├── design-system/                 ← UI 设计规范
    ├── quality/                       ← 质量规范与测试策略
    ├── code-standard/                 ← 编码规范（TypeScript / Java）
    └── business-rule/                 ← 业务不变量

我借鉴了Spec-Kit框架的要求，为SDD要实施的项目规定了宪法（constitution）。以本文实施的MES项目为例，定义了项目上下文信息：

前后端以及基础设施的技术栈：

以及架构设计原则等：

如果你觉得创建约束资产的方法较为繁琐，也可以直接使用我的框架Khufu提供的khufu-harness技能，它可以探索你的项目情况，按照上述要求智能地为你创建约束资产。在需要变更约束资产时，也可以修订和补充约束资产。

UI原型

虽然OpenSpec和Superpowers都可以帮助我们设计UI原型，但专业的事情交给专业的做，选择UIPro能够更好地满足UI设计的要求。通过npm install -g uipro-cli可以安装该skill，并在项目主目录下运行uipro init，就可以使用/ui-ux-pro-max技能了。

例如：

/ui-ux-pro-max
帮我用 Next.js + shadcn/ui 做运营分析助手的对话界面：
 - 左侧：历史对话列表 + 输入框（placeholder="用一句话问我数据…"）
 - 右侧：上部 AI 回答（流式打字）+ 下部 表格（可排序/导出CSV）+ 图表区
 - 风格：SaaS 数据分析后台 / 专业蓝灰 / 高可读性 / a11y

步骤1：提案

提案是通过OpenSpec框架的opsx:propose命令发起的。发起提案时，应该通过@符号将项目要研发的当前MVP对应的prd文档路径告知框架，同时，也可以指定UIPro产出的UI原型设计文档的路径。

提案的产出物放在openspec的changes目录下，如下所示：

虽然OpenSpec在生成提案时，已经包括了上图所示的提案、设计、需求规格与任务，但我们需要Superpowers的Brainstorming技能对其细化和深化，以求获得更加细致、更加准确的规格。

步骤2：脑暴

Brainstorming是Superpowers最具亮点的功能，它以头脑风暴的方式启发各种idea，然后将其转换为设计方案，下图是执行该skill的一个思考过程：

针对UI界面的布局和样式，Brainstorming提供了一个特性，可以临时在浏览器以可视化显示mockup界面，以更加直观方式把UI的决策实时推送到浏览器，以便于用户更好地确认UI设计方案。这个过程的信息提示为：

Some of what we're working on might be easier to explain if I can show it to you in a web browser. I can put together mockups, diagrams, comparisons, and other visuals as we go. This feature is still new and can be token-intensive. Want to try it? (Requires opening a local URL)

在执行Brainstorming过程中，Agent会就各个问题和用户进行沟通和确认，如下所示：

确认所有问题之后，即可确定当前change的最终方案，如针对MES的MVP 1，为认证、库存和审核等功能的实现给出了最终的决策：

为确保你的意图得到真实表达，建议团队针对步骤1和2输出的产物做进一步的评审。规格是SDD开发的唯一事实来源，但如果在源头上，事实已经出现偏差，就会给整个研发过程带来致命伤害。

步骤3：计划

完成头脑风暴后，双环驱动的开发流程会进入到枢纽A，代表从意图环到执行环的切换。

虽说如此，但从头脑风暴转移到计划，都属于Superpowers连贯的执行环节。故而Agent在执行完头脑风暴后，会提示“Spec self-review 已通过（无占位符、无矛盾、无歧义）。请审阅后确认是否进入 implementation plan 阶段。”

回答“Ok”，会启用Superpowers的writing-plan的skill，它可以根据最新的spec生成与之对应的计划和任务，规格文档放在docs/superpowers/plans目录下。

这个计划文档非常详尽，内容涵盖了前后端的代码结构、依赖管理、数据库脚本、docker部署脚本、关键的领域模型类和API接口定义，并将其分解为下一阶段需要执行的task。下图是该文档的部分内容：

注意，到此为止，Agent都还没有开始编写代码，一直围绕Spec推进工作。这一做法符合复杂系统的软件开发生命周期迭代流程。

步骤4：执行

完成计划编写后，Agent会根据Superpowers的设定给出执行的选择项：

选择它推荐的方案1：Subagent-Driven，Agent会依据2026-07-11-mes-mvp1-design.md文档中划分任务的顺序开始编写代码。如下图所示，Todo项一共有11个：

它分别创建了mes-frontend和mes-backend的前后端代码（含单元测试），此外，还包括docker的部署文件。

完成功能的实现后，我们可以启动docker，完成部署，手动验证mvp1的功能是否顺利完成。Agent未必能够绝对忠实地执行spec，还是需要人进入到这个环中，对已经实现功能开展验收测试。在确定功能正确后，才能进入下一个环节。如果spec没有问题，功能实现却存在偏差，则可能Agent在执行意图时存在理解差异，除了可以通过Vibe Coding的方式修复问题之外，还说明你发现了AI执行的“坑”，应尽量将此问题放到约束资产中，成为后续的“避坑指南”。

运行后，可以得到如下图所示的操作界面：

步骤5：测试

在验证功能无误后，进入执行环的下一个环节：测试。

在执行khufu init初始化时，框架会自动检测项目使用的开发语言，并选择对应的测试框架，然后选择自己使用的Agentic Coding Tool，如OpenCode。

完成框架的初始化后，进入OpenCode，可看到khufu框架提供的诸如khufu-ut、khufu-it等命令。加入要编写集成测试，可运行khufu-it命令，此时，Agent会要求用户对数据库策略、测试范围提出自己的看法，如测试范围的确认：

框架使用了H2数据库作为集成测试的数据源，分别为BOM/Process Repository、Scheduling Repository以及Order/Dispatch/Material/Progress Repository等生成了37个集成测试。

运行mvn test -pl mes-start -Dtest="com.mes.it.*IT"，测试全部通过：

为OrderRepository编写的集成测试如下所示：

你还可以运行khufu-api和khufu-e2e为项目编写API测试和端到端测试。

步骤6：重构

建立由各级自动化测试组成的测试安全网后，就可以对现有代码开展重构了。

遵循坏味道驱动重构的方法，整个重构过程分为：

1. explore：探索整个项目，识别代码坏味道，对应命令为：mole-explore
2. plan：根据识别出来的代码坏味道开展计划，定义重构任务，对应命令为：mole-plan
3. verify：交叉校验重构任务和坏味道，对应命令为：mole-verify
4. apply：执行重构任务，对应命令为：mole-apply
5. archive：将当前重构任务和坏味道归档，对应命令为：mole-archive

这实际上形成了重构自身的一个小闭环。OpenMole框架同样提供了openmole init完成框架的初始化。仍然使用OpenCode，进入后执行mole-explore命令，会扫描代码库：

扫描后，识别出来的坏味道如下所示：

从以上识别出来的坏味道可以看出，即便我们采用Superpowers的TDD模式进行代码编写，仍然可能出现大量违背坏味道的糟糕代码。这也凸显了双环驱动流程中重构的价值。

识别出来的坏味道规格文档放在openmole/changes/explore-mvp1-initial-smells目录下。一个典型的坏味道如下所示：

下一步，执行mole-plan进行任务分解。由于OpenMole框架给出了执行流程建议，你可以在Agent的对话框中直接输入“下一步”即可。

分解任务时，它会对当前识别的坏味道根据依赖合并分组，拆解为一个个重构任务，并生成tasks.md文档。

下一步是mole-verify。Agent会对比badsmells.md和tasks.md，确保它们是一致的，并在校验后，生成analysis.md文档。确认无误后，即可通过mole-apply命令执行重构。默认情况下，Agent会串行地执行每个任务，每个任务执行完毕后，需要用户确认。

重构的过程仍然遵循TDD，如此可确保重构的每一步尽可能走得稳健，走得安全。当然，这一做法必然要消耗更多的token。

以重构任务B-T01为例，消除的坏味道是BS-BE-003和BS-BE-015，它们都违背了Martin Fowler在《重构》一书中归纳的“基本类型偏执”坏味道，包括“ProductionPlan 使用 String 状态（Primitive Obsession）”和“业务逻辑中使用中文字符串作为状态键值”。

从下图可以看出，任务B-T01已经给出了重构的步骤以及重构涉及到的类：

重构时，创建了PlanStatus和ProductionLine值对象。如下就是它定义的ProductionLine值对象：

package com.mes.domain.common.valueobject;

import com.mes.common.exception.BusinessException;
import java.util.Objects;

public class ProductionLine {
    private final String value;

    public ProductionLine(String value) {
        if (value == null || value.isBlank()) {
            throw new BusinessException("产线不能为空");
        }
        this.value = value;
    }

    public String getValue() {
        return value;
    }

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof ProductionLine that)) return false;
        return Objects.equals(value, that.value);
    }

    @Override
    public int hashCode() {
        return Objects.hash(value);
    }

    @Override
    public String toString() {
        return "ProductionLine{" + value + "}";
    }
}

一旦创建了封装了字符串值的值对象，Agent会为其添加单元测试，然后重构需要调用这些值对象的实体类，重构摘要如下所示：

完成一个重构任务后，用户可以手动执行mvn test，确保重构没有破坏已有测试。确认无误后，告诉Agent继续执行下一个重构任务，重复以上流程，直到重构任务全部执行完毕。最后，通过mole-archive将已经完成的坏味道规格归档。如果重构任务没有完成就执行了归档，Agent也会提示你：

归档后，本次重构产生的所有规格文档都会转移到archive目录下。

步骤7：验证

完成重构后，来到枢纽B，从执行环回到意图环。此时应执行OpenSpec的opsx-verify命令。运行后，它会请用户确认要验证的change，并检查：

• 完整性：任务完成度 + 规格覆盖
• 正确性：需求是否已经实现 + 场景覆盖
• 一致性：是否遵循设计方案 + 代码是否一致

注意，openspec的verify会检查change下task的完成情况。该文档的任务状态由openspec的opsx-apply执行后更新。由于双环驱动使用了Superpowers的执行功能，在它通过subagent-driven执行任务后，并不会显式更新openspec规格目录下的tasks.md文档。例如，针对示例项目，倘若现在执行opsx-verify命令，可能会提示“Tasks not tracked(0/70 marked)”。

如果没有更新任务同步状态，执行后面的归档命令也会给出同样提示。

为此，可以在执行验证之前通过对话框输入如下提示词：

根据 @docs/superpowers/plans/2026-07-11-mes-mvp1-design.md 的内容，检查任务完成情况，同步更新 @openspec/changes/mes-mvp1-production-execution/tasks.md ，将已经完成的任务更新为done。 

Agent会根据实际的完成情况更新tasks.md的任务状态，并得到如下所示结果：

更新完成。69/70 已完成，仅 14.1（E2E 验证）待做。
同步依据：对照 docs/superpowers/plans/2026-07-11-mes-mvp1-design.md 中列出的全部文件与代码路径，与 mes-backend/ 和 mes-frontend/ 目录下实际存在的 Java/TS 源码文件进行交叉比对。所有 7 个领域模块的后端 DDD 完整四层架构（domain→infrastructure→application→interface）以及前端 7 个页面模块（pages + services + types + router + layout）均已实现。
仅第 14.1 项「端到端验证完整闭环」尚未执行，保持 [ ]。

验证时，如果存在问题，Agent会根据严重程度对这些未完成或未解决的问题进行归类，例如提示CRITICAL的问题在于没有为项目编写E2E测试；WARNING级别的问题则包括：

• Scheduling uses stub data — not production-ready
• DispatchService: first-dispatch → order status transition not implemented
• 其他……

同时，Agent还会给出合理的建议，如：

• Seed data reduced scope
• let reason = '' closure trap in OrderList.tsx
• 其他……

之所以出现这些问题，是Agent在执行规格划分的任务时，出现了漂移，又或者规格的验收标准或执行命令写得不够清楚，使得Agent未能正确理解其意图，导致实现出现偏差。这些问题应及时解决。可以在当前会话下编写如下提示：

根据以上分析报告，解决所有Issues，并遵循建议。

以下是执行结果：

修复这些问题后，应再次运行opsx-verify命令做进一步确认。以示例项目为例，执行结果提示除了E2E测试未编写外，其余问题都得到了解决。如果你认可这一验证结果，就可以执行归档了。

步骤8: 归档

执行归档命令时，Agent仍然会检查任务的完成情况，如果任务存在未完成状态，会提示用户做选择：

归档并非简单地将规格文档移动到archive目录下，它还会调用openspec-sync-specs技能对当前change下各个capability的规格文档进行同步，最终完成规格文档的归档。

至此，针对当前mvp的整个双环驱动流程就完成了，接下来可以根据此流程开启对新mvp的开发。