基于SDD的Vibe Coding代码重构思考实践

用Claude/Cursor重构代码时，你有没有遇到这种情况？

给 coding agent下一个模块重构指令，比如要求对当前项目某个模块不合理的设计进行系统性修复或者更换升级为一套技术方案时，AI会立马给你生成新代码，并且信誓旦旦的回复已经完成了重构任务，单元测试也通过了没啥问题，但是一联调发现结果不太对，细看代码，满脸惊讶：这写的啥？

就不说各种防御性代码了，就从实际重构思路的实现本身来看，很多实现都偏离了你预期的方向，而如果此时不介入人工review，以"不报错就继续"的思路，基于这个版本往下迭代，那这个模块的错误设计就会持续放大，导致可读性，可维护性都越来越差。

那问题出在哪里呢？一方面是vibe coding依赖的底座模型能力还不够，模型在处理复杂改动，类似重构任务上错误率还比较高，这个确实没有办法进行直接优化。但另外一个原因是重构意图和AI实际理解并没内有对齐，这是可以通过工程实践来优化改善的。

例如你说"把observe函数拆分一下，职责太多了"，AI立马给你生成新代码。看起来很勤快，但运行一测就完全不是你想要的逻辑。问题不在AI能力，而是你们根本没对齐重构意图。

在Vibe Coding场景下，重构不是简单的"改代码"，而是一个"对齐意图理解"的过程。当这个意图理解是项目级的意图，不只是依赖单个文件或模块目录的理解就够了，而是需要基于对项目架构，逻辑结构以及模块关联，来把具体的规划与重构意图进行对齐。要实现这个对齐，SDD(Specification-Driven Development)是一种很切合的方式，本文就基于SDD方法论扩展实践总结为一个用于代码重构场景的方法模型，来说明如何实现对齐重构意图。先做好规范，再开始开发，是现阶段vibe coding提升稳定性和可控性的一种有效方式。

一、为什么需要新的SDD范式？

一般在重构模块化代码时：大多数时候可能会使用这样的命令来进行。

"这个agent的obs模块把山修改文管理也放到了observation种，应高保持obs的职责单一原则，帮我重构一下。"

AI立刻开始写代码。不到10分钟就会给你一个"重构版本"，实际实现也把obs的错误实现添加的上下文管理剥离出去了，看上去完成了预期需求。

但运行后发现结果还是不太对，细看代码发现：

• • 上下文管理直接在agent内部实现，没有任何封装
• • 原本不该持久化的临时状态被存到WorkingMemory
• • action_plan莫名其妙出现在observation里

这是什么原因呢？AI在还没有理解清楚你的重构意图就开始执行具体任务，按照它认为正确的方式去做修复改动，但这种“认为的正确”和“期望的正确”之间还隔着一条巨大的鸿沟，这条鸿沟中由各种不确定性构成：1.你不确定AI思考切入的思路对不对；2.AI不确定你给的需求这样实现是否合理，所以它选(猜)一个概率最大的；3.重构的防御性代码很可能掩盖了本质问题增加排查的不确定性。而这些不确定性，为LLM本身存在的next token prediction范式的不确定性继续增加不确定，导致系统熵的进一步增加。

SDD(Spec-Driven Development)提出的规范驱动开发范式，要求先明确需求规范，再根据这个规范进行设计和编码。这种范式在移动互联网时代并不受欢迎，因为严格的规范设计和文档管理让开发流程显得"繁琐"，不符合"快速开发，灵活迭代"的敏捷开发要求。

但在当下vibe coding逐渐成为一种日常开发模式模式之后，vibe coding暴露的上述问题刚好可以通过SDD来进行规范驱动的开发，这种规范不仅可以直接注入prompt生效(in-context leaning)，而且vibe coding本身的编码速度也能弥补规范制定需要投入的时间，是一种在模型的agentic能力还不足以满足复杂开发需求下的一种有效开发方式。

SDD工具的启发

关于SDD在vibe coding上的应用，已经有一些SDD工具：openSpec，Spec-Kit和Kiro，OpenSpec和Spec-Kit是可嵌入现有AI编码工具的框架/CLI，而Kiro则是Amazon推出的内置SDD工作流的完整IDE。三个工具的基本理念都是以SDD强调的文档规范作为核心驱动，但在设计理念和类型上存在一些差别。

openSpec[1]的设计理念是从1->n，基于大多数项目编码是基于现有代码库的，而Spec-kit[2]更偏向于项目启动，从0到1构建新项目。kiro[3]则是把SDD集成到IDE中，绑定了ide环境。

现在社区讨论比较活跃的是OpenSPec，采用 proposal → apply → archive 的工作流，将意图固化为持久化的规范，通过自动化流程将规范渗透进入到具体的规划和实现的上下文，但主要目的不是替代vibe coding，而是提供一个轻量级框架，对于不同难易程度的需求还是需要自己判断是否需要引入spec，因为有的任务(比如写一个工具函数)并没有必要引入规范，但是如果要重构模块，或者迭代新的技术方案就需要通过规范来提供更清晰明确的指导。

所以这些SDD工具的本质都是“先写规范，再写代码”，实际上实现的效果是给vibe coding加上确定性的约束：代码生成是概率的，SDD通过规范约束上下文让它趋向确定性。

二、ISPI四层规范模型：让AI理解你的架构意图

可以直接使用上面提到的SDD工具，但还是有一定学习迁移成本，同时也会存在对原生vibe coding工具的介入和制约，而且目前的项目我一般会使用多个vibe coding工具(其实对应不同的agent模型)来进行切换交叉验证，为了探索不同工具组合使用的效果，使用更轻量灵活的方法，我就提炼的是一套SDD的约束模型，核心思想是：不依赖特定工具，专注于"如何组织约束让AI真正理解架构意图"。

这套模型很简单，主要的适用场景是项目重构，而解决的问题也就是文章开头提到的"对齐重构意图"，目标就是实现与重构意图对齐的代码实现。

为什么选择重构这个场景，因为在实践中发现，如果一个项目通过vibe coding持续构建而很少干预，随着项目推进，这个项目越来越难以维护，虽然在交互的过程中也在持续修正一些问题，但是内部隐藏的问题也很多，如果不让AI对当前项目的状态，偏差有一个清晰的认知修正，与你的重构意图充分对齐，那重构就是在做"拆东墙补西墙"的工作。

于是结合最近对一个项目的重构，尝试了三次版本重构，因为前期很多代码都是一次放行，很少review，导致项目代码到了不得不改的时候才发现存在非常大的问题：agent的记忆模块，agent内部迭代存在各种耦合设计和实现，维护调试非常困难(后续的SDD模型实践也是基于这个项目)。前两次重构每次耗时两周，零散解决了一些问题，但是本质问题未解决，第三次重构采用SDD导向的方式，一周时间完成重构，基本达到重构目标。

那我自己提炼的这个SDD模型我把它叫做ISPI四层规范模型，采用从自顶向下的方法，Intent Definition->Structure anaysi->plan design->implement checklit。

Layer 1: Intent Definition（意图定义）

• • 明确"为什么做"和"为什么不做"
• • 存在什么问题，应该实现什么目标
• • 关键：让AI理解重构的目的是什么

Layer 2: Structure anaysis（结构分析）

• • 对现状，当前偏差进行分析
• • 宏观设计存在什么问题，子模块存在什么偏差
• • 关键：定位问题之所在，预期目标的难点

Layer 3: Plan design（方案设计）

• • 拆解任务，制定修复/迁移技术方案
• • 架构如何修改，不同模块如何解耦
• • 关键：从现状到预期如何实现

Layer 4: Implement checklit（行动清单）

• • 将任务转换为行动清单
• • 分阶段，分模块，分优先级
• • 关键：输出按优先级排序的行动列表

这四层构成了一个完整的对齐框架，接下来看实际应用。

三、实战案例：observe函数重构的四层对齐

上面背景部分介绍的第三次重构就是对这个SDD模型的实践，实践也验证了用更短的时间完成了既定重构目标，但其实也不代表投入精力的降低，但确实更高效也更具针对性了。未使用SDD驱动开发时，很多工作是与AI来回的拉扯，使用这套模型，70%的时候都是在定义规范，但是定义规范的过程就是在把AI与你的意图拉回到同一对齐的空间，一旦对齐之后，实现的效率就会比之前高很多。下面就看一下以agent项目的observation和记忆耦合，需要进行解耦的重构需求为例，如何构建ISPI规范来实现重构。

Layer 1: Intent Definition（意图定义）

先让AI理解目标状态，明确"为什么做"和"为什么不做"。

当前问题：

• • observe函数定义错误：承担上下文管理、自建状态视图，读取工作记忆
• • 承担了3个不同层次的职责，违反单一职责原则

预期目标：

• • observe只负责生成当轮观察快照
• • 上下文管理、agent状态视图管理交给独立模块
• • 重构observation与记忆交互通道

硬性约束（不能做什么）：

• • action_plan不能进入observation结构（plan是意图，obs是事实）
• • observe不能做跨轮状态管理（只处理当轮）
• • 状态视图不能耦合在agent内部

验证标准：

• • 将上下文管理从observe函数剥离
• • 状态视图抽象到agent外部
• • obersation存入工作记忆，上下文管理与agent解耦

让AI复述这个预期，确认它理解了"为什么改"和"改成什么样"。

Layer 2: Structure Analysis（结构分析）

让AI先描述现状，检验它是否"看懂"了代码结构，定位问题之所在。

我问："请分析当前_observe函数的职责范围，如何与记忆模块交互，当前存在哪些问题"

AI应该能识别出：

1. 1. 调用build_react_context_view从WM读取并拼接历史
2. 2. 合并上轮的act_log（通过action_facts传入）
3. 3. 调用_observe_current_state做领域特定增强
4. 4. 从工作记忆中读取上下文塞入obs

基于预期和现状，明确具体偏差：

如果AI的分析和你的理解对不上，则可以回到Layer 1重新对齐。

Layer 3: Plan Design（方案设计）

基于偏差分析，让AI提出方案："基于上述偏差，你认为应该如何调整架构？修复思路是什么"

AI随后给出3个备选方案，并说明了各自的trade-off。

方案A：拆分为多个独立函数

• • 优点：改动最小，容易理解
• • 缺点：职责边界可能还是不够清晰

方案B：引入独立的ContextManager

• • 优点：职责分离彻底，可测试性高
• • 缺点：增加了抽象层级，理解成本提升

方案C：简化observe，逻辑下沉到utils

• • 优点：最小化改动，保持向后兼容
• • 缺点：utils层可能承担过多职责

重点是让AI基于理解意图和分析偏差之后给出适配的技术方案，证明它理解了代码内部关联逻辑，可以从正确的方向切入设计技术方案。

我选择了方案B，因为长期可维护性更重要。但关键是这个选择是在对齐理解后做出的，不是一上来就盲目给出的技术解决方案。

架构护栏：

• • observe的输入限定为：input_data + iteration + action_facts
• • observe的输出限定为：current_state（当轮快照）
• • 不允许observe内部继续读取wm维护上下文

技术方案设计：

• • 实现独立上下文模块context_manager
• • 基于工作记忆实现独立状态管理模块agent_statu_view
• • 为工作记忆添加领域适配层，负责维护obs与context_manager,agent_statu_view间交互

Layer 4: Implement Checklist（行动清单）

确认方案后，让AI生成详细实施计划，生成行动清单。

改动清单：

• • 修改文件：react_agent.py(以及子类agent)
• • 新增文件：context_builder.py（ContextManager实现），agent_statu_view.py（）
• • 影响范围：agent迭代中所有调用_observe的地方

迁移步骤（按优先级排序）：

1. 1. 创建ContextManager，封装build_react_context_view逻辑
2. 2. 修改_observe签名：移除内部WM读取，改为接收pre-built context
3. 3. 调整_execute_impl：先用ContextManager构建上下文，再传给_observe
4. 4. 更新_observe_current_state接口：明确输入是已构建的context
5. 5. 新增agent_statu_view.py构建agent状态视图加入上下文
6. 6. 更新单元测试和集成测试

回滚预案：

• • 保留旧_observe为_observe_legacy
• • 通过配置开关控制使用新旧版本
• • 如果新版本有问题，可立即切回旧版

验证标准：

• • 所有现有单元测试通过
• • 集成测试：完整ReAct循环运行无报错
• • 联调任务执行成功

这个SDD模型执行的过程中需要与AI进行多轮交互分别产生阶段产出，然后将四层阶段产出输出组合到一个文档中，这个文档就可以作为SDD的规范文件来指导coding agent开始按照行动清单开启开发任务。

四、关键发现：对齐过程的隐藏价值

和之前的开发模式相比，用这套SDD驱动的流程后，我发现了几个在直接让AI写代码时不会浮现的问题：

发现1：职责理解偏差 AI一开始认为"从WM读取事实"是observe的职责。经过Layer 2和Layer 3的对齐后，它理解了这应该是ContextManager的职责，observe只消费构建好的上下文。自顶向下的交互过程也是在逐步对齐概念偏差的过程。

发现2：概念混淆 关于action_plan该不该进observation，我们讨论了三轮才对齐。关键洞察是：

• • plan是"意图"（what AI intends to do）
• • observation是"事实"（what actually happened）
• • 混在一起会导致后续REFLECT阶段无法区分"计划"和"实际" 这种概念层面的混淆，不对齐就会导致整个ReAct循环逻辑错乱。

发现3：隐藏的技术债 在分析现状时，一开始并未发现状态视图的问题，observation默认从wm中读取构建上下文，并行在agent内部构建了维护状态视图的一个字典。这个字典本身是维护agent迭代过程中的产出统计，而且是在agent内部维护，这种设计不但不符合agent的上下文应该是从工作记忆读取的设计原则，也不具备通用性，每个agent内部都自己实现。 如果没有层层剥茧式的规范驱动的分析，这些隐藏的问题就会成为技术债，影响后续迭代开发。

五、从临时对话到持久化约束

使用这套模型的时间过程，还发现对齐过程的最大价值不只是当次重构，而是可复用的架构知识。

在五步对齐完成后，我们就可以把规范中项目可复用的知识写入coding工具的rule，例如codex就可以写入到agents.md中。

# Agent Observe职责边界

## Hard Constraints
- observe函数不得直接读写WorkingMemory
- action_plan不需要加入observation中
- observe只处理当轮快照，不做跨轮状态管理

## Architecture Pattern
- 上下文构建由ContextManager负责
- observe消费pre-built context生成observation
- agent状态视图由独立于agent之外的模块负责

## Property Invariants
- observation只承担单轮实时观察职责
- 工作记忆是当前agent上下文的唯一事实来源
- 上下文管理作为独立模块维护工作记忆加入到agent上下文

这样下次遇到类似重构，或者新增功能时，就可以直接复用这些规范，而且这些规范还能持续积累为经验知识实现项目级经验复用。

结语

本文主要分享了手SDD启发的一套vibe coding模型思路，主要思想总结为：**Don't code first, align first.**先对齐理解，再写代码。用SDD作为对齐脚手架，让AI成为真正理解你架构意图的协作者，而不是只会照搬指令的代码生成器。

从OpenSpec的"lock intent"到Kiro的"spec-driven"，再到Cursor Rules[4]的"persistent context"，整个行业都在探索同一件事：如何让概率性的代码生成趋向确定性。在重构场景下，这意味着：不要急着让AI改代码，先花时间对齐架构理解。SDD驱动模式看起来慢，实际上比反复返工快得多。

这套方法未必适合通用场景，但可以作为一个重构思路的参考，在自己的业务场景中，还是需要更多实践来总结高效的vibe coding协作方式，同时随着模型能力的提升，也许这些方法就会逐步失效，但是探索实践过程的意义就在于看到你与AI在协同创造更有意思的东西。

参考文献： [1] https://github.com/Fission-AI/OpenSpec [2] https://github.com/github/spec-kit [3] https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html [4] https://link.zhihu.com/?target=https%3A//cursor.com/docs/context/rules