夜雨聆风阅读指南：每天与 AI 结对编程、受够了 AI “乱写瞎绕”的开发者，不敢让 AI 碰核心业务的架构师。
核心摘要：AI 写代码快，但守规矩难。本文拆解 OpenSpec（规矩制定者，管“写什么”）与 Superpowers（纪律执行者，管“怎么写”）双轨约束，讲透其组合价值与单向衔接打法，借实战推演，告别 AI 越权与上线血案。
引言：AI 代码库里裸奔，工程底线谁来守？
AI 写代码极快，但在真实工程中极易失控：绕过缓存、漏传上下文、越权调用……代码 locally 能跑，但你绝不敢推上线。
根本原因在于：自然语言是模糊的，Agent 执行是精确的。缺乏工程约束的 AI，就是在你的代码库里裸奔。
口头嘱咐“别越权”是对牛弹琴。必须用工程手段给 AI 定“交规”、装“刹车”。OpenSpec 和 Superpowers 正是为此而生的两套核心约束工具。
01. OpenSpec：契约起草者，划定业务边界
1. 它是什么？
一个规范驱动开发（SDD）框架。它不关心代码怎么实现，只强制 AI 在写代码前，必须先输出结构化的技术规范文档。
2. 做什么用？
解决 AI “瞎猜需求”和“上下文丢失”问题。把模糊需求拆解为四个具象化约束文件，作为开发的唯一真相源：
3. 与 CLAUDE.md 等项目规范的区别？
CLAUDE.md 是“项目宪法”：管全局通用规范，静态普适。OpenSpec 是“专项法案”：管当前具体变更的边界，动态跟随需求。宪法防不了临时越权，专项法案才能锁死单次执行红线。
4. 怎么用与怎么装？
完全显式触发。你不下令，它绝不动弹。
openspec new change 或对话中输入 /opsx:propose[bash]npm install -g @fission-ai/openspec@latestcd your-projectopenspec init --tools claude02. Superpowers：纪律执行者，守住工程流程
1. 它是什么？
植入 AI Agent 内部的纪律与技能框架。通过 Hard Gates（硬关卡），强制 Agent 遵循标准研发流程。
2. 做什么用？
解决 AI “上来就写代码”和“跳过测试审查”问题。拦截盲目生成，强制按工程最佳实践逐步推进。采用“隐式拦截 + 技能挂载”，强制调用内置技能包：
3. 怎么用与怎么装？
主要隐式自动拦截，也可通过斜杠命令手动激活。
[bash]# 方式一：Claude Code 官方插件/plugin install superpowers@claude-plugins-official# 方式二：社区中文增强版cd your-project && npx superpowers-zh03. 双剑合璧：契约与纪律的生死依存
如果只用其中一个，一定会陷入死局：
1. 单用 OpenSpec = 起草合同没人监督，AI 撕毁契约。死文件拦不住违规代码，业务对齐了，但执行跑偏了。
2. 单用 Superpowers = 严苛执行了一份错误的合同。没有契约约束，AI 会一丝不苟地测试一个违背业务的越权接口。有纪律，但方向错了。
组合价值：让 AI 在“正确的业务边界”内，保持“严格的工程纪律”。
一句话总结：OpenSpec 管“写什么”，Superpowers 管“怎么写”。
04. 衔接与桥接：构建单向契约流的四个动作
现实是：两工具间有重叠且不自动映射！这不是设计缺陷，而是强制人类把关的防火墙。必须建立“单向契约流”（OpenSpec 为尊，Superpowers 为从），落实 4 个动作：
动作 1：以 tasks.md 为上游，放弃 OpenSpec 自带 apply
不要并行维护两套任务系统。把 tasks.md 作为 writing-plans 的输入，展开为带 TDD 微步骤的原子计划。单向消费，不回写。
动作 2：按工程化程度选择桥接方式
动作 3：把 specs/ 变成 TDD 测试用例表（核心映射）
动作 4：把 specs/ 作为 Code Review 唯一判卷标准
05. 实战推演：一场“人机博弈”的四个阶段
场景：银行 IT 架构中，接入 ESB 底层接口实现 MCP Server 查询养老金明细，并对接给 H5 前端调用。
🚩 阶段一：需求澄清，截断默认发散立规矩
刚抛需求，AI 自动启动 brainstorming，准备排期。如果顺着走，AI 为求“接口完整”极可能顺手暴露状态变更操作。介入时机：按下 Esc 打断提问，用 OpenSpec 立规矩。
/opsx:propose pension-query（并在文件中补写红线）✅ 触发计划技能：/writing-plans✅ 输入提示词强指输入源：“请基于 OpenSpec 的 tasks.md 生成全局执行计划，仅实现只读查询，绝不能出现申领功能。”🚩 阶段二：接口设计，堵住穿透漏传补防线
执行 ESB 对接时，AI 偷懒漏掉必传的 channelId，没处理降级，易引发雪崩。介入时机：按下 Esc 强行打断，打回初稿补约束。
/writing-plans✅ 输入提示词：“基于刚更新的 specs/ 生成子任务计划，前置校验和降级逻辑安排在 ESB 调用之前。”AI 嫌麻烦想跳过，但 plan 依赖图卡住前置校验，最终代码乖乖补全兜底：
[java]EsbContext context = EsbContext.builder() .channelId("APP").txnSeqNo(...).build();🚩 阶段三：编码实现，TDD 砸碎架构大击穿
H5 前端时，AI 为图快绕过 MCP Client，直接拼 HTTP 调 ESB。介入时机：按下 Esc 打断执行，祭出 specs 变 TDD 用例表。
/test-driven-development✅ 输入提示词：“根据 specs/ 编写测试。明确断言：前端必须调用 MCP Client，禁止直连 HTTP！”AI 起初想写 Mock 糊弄，测试跑起直接 Red。没辙只能放弃直连，改回 MCP Client 调用，测试变 Green 才提交。
🚩 阶段四：上线兜底，左手打右手闭环审查
加缓存限流时，AI 凭感觉写，Redis 过期时间乱给。介入时机：按 Esc 终止编码主动触发审查。
/requesting-code-review✅ 输入提示词：“对照 specs/ 审查当前代码。Redis 过期时间与限流阈值不符则直接打回。”奇妙的一幕发生：AI 自审发现不符契约，自己打回自己并重写。极大降低人工成本。
06. 附录：决策与防雷清单
（以下为落地附录，实操遇阻时对照查阅）
📋 1. 什么时候用？（决策树）
核心判断标准：这个变更出错需要多久才能发现？越难发现，越值得先写 Spec。
⚡ 2. 怎么防走火？（实操雷区）
人定规矩，AI 守规矩，工程做兜底。 只有把“契约”和“监督”同时按进 AI 执行流里，你才敢真正把核心逻辑交到它手里。
