SDD驱动编程实战：用OpenSpec将硬编码业务重构为流程引擎
在AI编程（Vibe Coding）盛行的今天，我们似乎习惯了“提示词即代码”的快节奏。然而，当面对复杂的业务逻辑重构时，这种“即兴发挥”的模式往往会带来巨大的维护灾难。
最近，我在负责一个特定领域的AI Agent项目重构时，尝试引入SDD（Spec-Driven Development，规范驱动开发）模式，并使用了OpenSpec这一轻量级框架。这次实践的核心任务是将原本散落在代码中的“硬编码业务流程”重构为“流程引擎驱动”。
本文将分享我是如何利用OpenSpec驾驭这次复杂重构的，并对比同类工具，探讨SDD在AI编程时代的真实价值。
一、 什么是OpenSpec？为何选择它？
在深入实战之前，先简单介绍一下OpenSpec。简单来说，OpenSpec是一个面向AI编程助手的SDD开源框架。它的核心理念非常清晰：意图先行，结构化变更。
在传统AI编程中，流程通常是：需求 -> AI生成代码 -> 结果不可控。而OpenSpec将其转变为：需求 -> 规范文档 -> AI基于规范生成代码 -> 可控可审计。
OpenSpec vs. 同类竞品
在SDD领域，目前主要有三款热门工具：OpenSpec、Superpowers和Spec Kit。为了更直观地理解它们的定位，我做了一个简单的对比：
| 维度 | OpenSpec | Superpowers | Spec Kit |
|---|---|---|---|
| 核心定位 | 轻量级规范驱动框架 | AI编程助手的工程工作流 | 规范驱动开发工具箱 |
| 主要解决 | 变更意图管理、存量项目迭代 | AI执行质量、工程纪律约束 | 建立完整的规范开发流程 |
| 适用场景 | 存量项目重构、快速迭代 | 复杂新功能开发、TDD实践 | 组织级流程建设 |
| 上手难度 | ⭐⭐ (轻量，CLI安装) | ⭐⭐⭐ (依赖特定插件/环境) | ⭐⭐⭐⭐ (流程较重) |
选择OpenSpec的理由：
我的项目是一个已经运行已久的AI Agent（存量项目），需要对其进行核心架构的重构。Superpowers虽然工程纪律性强，但更偏向于从零开始的执行流；Spec Kit则显得过于厚重。OpenSpec的**“Brownfield-first”**（面向存量项目优先）设计理念，以及它将specs（当前规范）与changes（变更提案）分离的机制，非常适合这种需要逐步演进、精确控制变更范围的重构任务。
二、 重构前夜：硬编码带来的“至暗时刻”
在使用OpenSpec之前，这个AI Agent项目的业务流程处理非常“原始”。所有的业务逻辑都是通过大量的if-else和switch-case硬编码在代码里的。
遇到的核心痛点：
- 逻辑纠缠，牵一发而动全身：业务规则与执行代码高度耦合。当产品经理提出“修改审批流程的节点顺序”时，我需要在几千行代码中小心翼翼地寻找逻辑断点，稍有不慎就会破坏原有的状态机逻辑。
- AI“幻觉”导致代码腐化：我尝试直接用Cursor或Copilot进行重构，提示词是“帮我把这段代码改成策略模式”。结果AI虽然生成了类结构，但往往遗漏了某些边缘情况的处理，或者因为上下文窗口限制，导致新生成的代码与旧代码风格割裂，甚至引入新的Bug。
- 需求追溯困难：为什么这里要加这个判断？是因为三个月前的一个临时需求。但在聊天记录里根本找不到当时的上下文。
我意识到，如果不先定义好“流程引擎”的规范，直接让AI写代码，只会制造出一堆难以维护的“类库垃圾”。
三、 引入OpenSpec：重构实战
引入OpenSpec后，我将重构过程标准化，不再直接让AI写代码，而是先让它写“规范”。
1. 初始化与提案
首先，我在项目中运行openspec init，建立了openspec/目录结构。接着，我发起了一个变更提案：/openspec:propose
我告诉AI：“我们需要重构订单处理流程，目标是引入流程引擎，支持动态编排。”
2. 编写规范
OpenSpec强制要求AI生成结构化的规范文档。在这个过程中，AI不再是盲目写代码，而是输出了详细的proposal.md和specs。
例如，它定义了新的流程节点结构：
## 场景：流程节点执行 **WHEN** 流程引擎接收到“订单创建”事件 **AND** 当前节点配置为“库存预占” **THEN** 引擎应调用InventoryAdapter的reserve方法 **AND** 若成功，流转至下一节点“支付检查” **AND** 若失败，触发“异常处理”子流程这种Gherkin风格的描述，让我在代码生成前就确认了逻辑的完备性。我指出了AI在“异常回滚”机制上的设计漏洞，它在规范阶段就修正了，而不是等到代码写完才发现。
3. 应用变更
规范确认无误后，我执行：/openspec:apply
此时，AI严格按照刚才敲定的规范文档进行编码。它将硬编码的逻辑剥离，生成了ProcessEngine、NodeContext等核心类，并实现了基于配置文件的流程编排。由于有了明确的Spec作为上下文，AI生成的代码结构非常严谨，几乎没有出现“幻觉”代码。
4. 归档
重构完成并测试通过后，执行：/openspec:archive
这次变更被合并到主规范库中。现在，项目的openspec/specs目录下，清晰地记录了流程引擎的所有行为边界。
四、 总结：SDD在AI编程中的得与失
通过这次实战，我对SDD驱动编程有了更深的体感。
优点：
- 遏制AI的“即兴发挥”：OpenSpec强制AI在写代码前先“想清楚”。对于重构这种高风险操作，Spec文档充当了设计图纸，极大地降低了代码生成的错误率。
- 上下文持久化：规范文件存储在代码库中，而不是散落在AI的聊天窗口里。这意味着无论过多久，新加入的开发者（或AI）都能通过阅读Spec理解业务流程的来龙去脉。
- 变更可追溯：
changes目录就像一个需求版本的Git历史，清晰地记录了“为什么要改这里”。
缺点与挑战：
- 前期成本增加：对于简单的修改（如改个文案、调个颜色），走一遍SDD流程显得杀鸡用牛刀，效率反而不如直接手写。
- 规范维护压力：Spec文档必须与代码保持同步。如果代码手动修改了但没更新Spec，久而久之会产生“文档债务”。这需要团队有极强的纪律性。
- 学习曲线：需要理解OpenSpec的目录结构、命令以及规范文档的写法，对团队成员有一定的认知门槛。
结语
OpenSpec并不是银弹，它不适合所有场景。但在处理像“硬编码转流程引擎”这样复杂的架构重构时，它就像给AI戴上了“紧箍咒”，让原本不可控的生成能力变成了精准的手术刀。在AI编程时代，“写好文档”可能比“写好代码”更重要。
