【AI助编程-工具篇】紧急叫停 AI 架构重构:OpenSpec + Superpowers 翻车救援现场实录

阅读指南:本文适合架构师、全栈开发者及AI编程实践者阅读。文中包含大量AI交互实录与架构决策推演，建议预留10分钟沉浸阅读。

核心摘要：本文实录了一次AI架构重构的“翻车救援”。当AI脱离契约生成 3000 行失控计划时，我利用OpenSpec与Superpowers紧急叫停，重建契约并打通自动化审查闭环，验证了“契约先行”在 AI 编程时代的不可替代性。

昨天写那篇《告别 AI 裸奔...》时，我心里其实是有遗憾的。虽然借着养老金查询项目做了一次初步推演，我知道 OpenSpec 和 Superpowers 能约束 AI，但我没摸透它们的前后顺序，更不知道该在什么时机按下“Esc”键手工介入。

带着这个疑问，今天我决定在这个项目上继续深挖，补齐昨天没走完的工程化流程。本以为只是一次常规的重构演练，结果却演变成了一场惊心动魄的“翻车救援”。

我抱着试一试的心态，对着养老金查询项目输入了这样一条指令：

[指令]/opsx:explore 帮我看下 ./pension-h5的module,本意是想用vue3实现一个能流式体验，调用pension-mcp-server实现查询养老金的H5前端。

原本，/opsx:explore 只是个只读的探索模式，我只想让它扫一眼代码。没想到，这轻轻一敲，却推开了一扇新大门。

指令下达后，AI 没有急着给方案，而是像个细心的老中医，逐个把脉项目里的关键文件，迅速梳理出了整个系统的架构全貌。它不仅给出了全景图，还敏锐地指出了几处致命的架构断层与隐患：

[交互]AI：探索上下文总结：从刚才的分析，我已经看到：pension-h5 → 单 HTML + CDN Vue + fetch 轮询pension-mcp-server → Spring Boot + MiniMax LLM + ESB 调用PensionWorkflowConfig (🪦 悬空配置)PensionQuerySkill (🪦 悬空代码)sessionStore (⚠️ 无 TTL)

看着屏幕上跳出的“🪦 悬空配置”和“⚠️ 无 TTL”，我瞬间有一种发现宝藏的爽感。AI 不急于写代码，而是先审视架构隐患的克制感，让我极度舒适。随后，它给出了下一步的行动选项：

[交互]AI：不过，我现在是 explore mode（探索模式），不能写代码实现。按照规则，你需要先退出探索模式，然后我可以：- 用 brainstorming skill 做需求分析和设计- 或直接进入 writing-plans 写实现计划- 或用 subagent-driven-development 并行执行多个任务你想怎么推进？A) 退出探索模式 → 用 brainstorming skill 完整设计后再实现B) 退出探索模式 → 直接写实现计划C) 先在探索模式里继续聊 → 把设计思路聊透再退出

我毫不犹豫地选择了 A。AI 顺势切入了 Superpowers 的 brainstorming 技能，抛出了一场连环追问。当时我沉浸在被 AI “懂业务”的爽感中，却没意识到一个关键的违规操作：虽然走了正式的设计流程，但我们直接进入了需求澄清，跳过了 OpenSpec 规定的先确立 proposal.md 和 specs/ 契约的前置环节。

“直接写代码前再补这些文档不行吗？”当时的我满不在乎，带着这种走捷径的侥幸心理，满心欢喜地开始了对答。

为了缓解长问答的阅读疲劳，我将这 10 轮追问分为三个阶段：

阶段一：边界收敛（Q1-Q3）

[交互]AI：Q1 前端除了登录+聊天核心功能外，还需要预留其他页面/能力吗？(A:最小集 B:加历史 C:多页面)User：cAI：Q2 关于 H5 多页面设计，你期望包含哪些功能模块？(A:基础 B:进阶 C:完整版)User：bAI：Q3 Vue3 前端和后端的模块关系怎么组织？(A:前端独立 B:合并为Maven子模块 C:其他)User：B

关键决策时刻：AI 试图做大而全的方案，我选择了 C，确认前端是多页面应用。随后 AI 用“做减法”的建议，引导我用进阶版收敛了边界，锁定四个核心页面。工程结构上，我拒绝了前端独立仓库，选择保留 Maven 多模块结构，降低初期复杂度。

阶段二：体验与安全（Q4-Q7）

[交互]AI：Q4 SSE 流式场景下，界面应该怎么呈现？User：A和B，你推荐哪个呢AI：我推荐 B。先显示"正在思考..."，然后显示"正在查询养老金..."，最后出结果。老年人场景清晰反馈降低焦虑。AI：Q5 Workflow Engine 怎么实现？(A:自研 B:Spring AI Workflow C:状态机)User：第四、五个问题我都选BAI：Q6 Memory 增强需要做到什么程度？(A:TTL B:持久化 C:多端同步)User：你觉得老年人场景要么？AI：我倾向于 A。老年人每次查询独立性强，不存储长期记忆反而是防诈骗的安全优势。AI：Q7 Skill 拦截失败时的处理策略？(A:静默 B:阻断 C:日志+降级)User：好，第六个问题采纳你的建议。第七个问题我选C

关键决策时刻：在用户体验上，AI 主动考虑到了“老年人心智模型”，建议用阶段性反馈降低焦虑；在记忆设计上，AI 主动否决了复杂的持久化，从防诈骗安全角度给出务实建议；面对安全与可用性的权衡，我选择了日志+降级，既保留可审计性，又不阻断核心流程。AI 真正懂了业务痛点。

阶段三：技术选型与扩展性（Q8-Q10 及 SSE 事件）

[交互]AI：Q8 登录认证怎么做？(A:Cookie B:JWT C:短信)User：选B，但是预留将来支持对接发送验证码和手机号接收验证码的扩展。AI：Q9 Vue3 项目初始化的方式？(A:手动 B:create-vue C:使用UI框架模板)User：c的话，将来使用对象从老年人扩展到其他对象，会有什么问题吗？AI：好问题！Vant 扩展可能显"廉价"。建议选 B + 自定义 Design Token，与组件库解耦。User：同意AI：Q10 前端技术栈选型：Axios vs fetch？User：拦截器在前端具体表现场景是？AI：统一添加 token、401 跳转登录页等。自己写拦截器等于造个 Axios。User：选AAI：SSE 事件设计：三事件(thinking/tool_call/token) vs 两事件？User：你会怎么设计呢？AI：推荐 A，微调为 status/token/tool_result。分开减少老年人焦虑感。User：合理，就选A吧。

关键决策时刻：这是整个设计中最爽的环节。AI 洞察了技术选型对业务扩展的长期影响，主动提出了 Design Token 解耦方案，避免了将来重写前端的灾难。立足当下（JWT），但为未来业务演进（短信网关）预留扩展点，体现了架构设计的前瞻性。

经过 10 轮高密度的脑力激荡，需求边界、技术栈、安全策略全部锁定。AI 完美地收敛了发散思维，而我始终把控着最终决策权。

需求对齐后，AI 分 6 节完整展示系统架构。就在第一节，它露出了马脚——它默认把后端的 LlmClient 写死成了 MiniMax 单一实现。

[交互]AI：第一节 系统架构概览架构图显示：...底部的 LlmClient (MiniMax)。User：LlmClient不局限于只支持某一个大模型哦AI：你说得对！LlmClient 不应该写死 MiniMax。让我更新架构：修订：LLM 抽象层 LlmGateway... 新增 Provider 只需实现接口 + 注册，无需修改调用方。

关键决策时刻：业务绝不能绑死单一供应商，这是架构红线！

AI 迅速领会，紧急重构出 LlmGateway 抽象层。如果没有探索模式对齐边界，AI 此时已经开始写死供应商的烂代码了。随后，接下来的5节架构设计（前端项目结构、后端SSE架构、Workflow Engine、Memory+Session、LlmGateway多Provider），我全部绿灯放行。

6节架构图如行云流水般展开，悬空配置全部落地，前期的连环追问在这一刻转化为精确的代码蓝图。

到了落盘阶段，引言中那个“跳过契约会有什么影响”的疑问，终于迎来了残酷的答案。

设计确认后，AI 习惯性地走向了 Superpowers 的 writing-plans 技能。几分钟后，它洋洋洒洒生成了 3000 多行的详细计划。但就在准备进入 TDD 时，致命问题爆发了。

[交互]User：我没看到proposal.md、design.md、tasks.mdAI：你说得对！我们的设计文档和计划是放在 docs/superpowers/ 下的，但 OpenSpec 标准格式应该是在 openspec/changes/ 下生成。

关键决策时刻：前期跳过 OpenSpec 契约确立的恶果显现了！因为没有了 specs/ 的边界约束，Superpowers 的 writing-plans 彻底“脱缰”，另起炉灶在 docs/ 下建了一套任务系统。这不仅导致 OpenSpec 的契约流断链，更致命的是——如果没有契约在前，我现在让它补写的文档，就会变成对它已经写好的 3000 行计划的“事后追认”，彻底失去约束力！

[交互]User：选A，帮我检查下原来创建过的相关文件是否要清除掉。

我果断叫停，强制要求 AI 将设计文档转换为 OpenSpec 标准格式，把缺失的文件全部补齐。AI 随后创建了对应目录，补齐了四件套，并删除了 docs 下的残骸文件。但代价是，那 3000 行详细计划必须废弃重写。迟到的契约，终究要付出双倍的 Token 代价。

就在以为对齐成功时，AI 吐出了一个残酷的现实：刚生成的 tasks.md 只是一份 Checkbox 清单，根本无法指导 AI 写代码！而之前的 3000 行详细计划已经被删了。

[交互]AI：tasks.md vs writing-plans 差异... tasks.md 是粗粒度清单，无代码。OpenSpec 的 tasks.md 适合人类阅读追踪进度，但不足以让 AI 直接执行。User：/writing-plans 请基于 OpenSpec 的 tasks.md 生成全局执行计划.

关键决策时刻：这就是昨天我没想通的“两工具不自动映射”的终极坑位！OpenSpec 的 tasks.md 是给人看的进度表，Superpowers 的 writing-plans 是给 AI 看的执行图。必须通过人工下达指令，强行建立单向契约流！

单向流打通后，我输入 /test-driven-development 和执行指令“1”，利用这份计划触发subagent-driven-development，开启了TDD的红-绿-重构循环。

在此后的执行中，AI 展现了极强的纪律性。以任务 1.1 为例，AI 不仅实现了代码，还自动发起了两阶段审查：

这种“左手打右手”的自我审查机制，极大降低了人工 Review 的成本，也让 OpenSpec 的契约真正落地到了代码行级。

从昨天的“摸不着头脑”到今天的“掌控全局”，这次探索之旅，让我彻底体会到了双轨约束的爽感。AI 会在工具的重叠地带反复横跳，但只要我们在关键决策时刻手工介入，用 OpenSpec 锁死业务边界，用 Superpowers 守住工程流程，AI 就能成为最可靠的结对编程伙伴。工具再强，也代替不了人为的红线把控，而这正是我们存在的价值。