#双框架踩坑指南

预计阅读时间: 12 分钟

OpenSpec + Superpowers 的组合能显著提升 AI 编程质量，但两套框架原生无自动联动机制，直接混用极易踩坑。本文基于真实项目迭代经验，梳理最常见的问题和修复方案。

#先理清分工

核心准则： OpenSpec 锁定方向，Superpowers 守住落地质量。

#7 大踩坑速查表

#详细踩坑分析

#踩坑 1：跳过 Explore 直接 Propose

场景： 存量 Go 微服务新增 JWT 认证，直接执行 /opsx:propose 跳过 /opsx:explore。

现象： AI 自主选用无黑名单纯 JWT 方案，无法满足主动踢人需求，提案反复修改 3 次。

根因： 缺少前置方案研讨，AI 依靠默认经验生成规范。

解决方案： 固定流程：先 /opsx:explore 研讨方案，确认细节后再 /opsx:propose。

#踩坑 2：Proposal 缺失排除范围

现象： 未标注「不改动前端 Web 登录逻辑」，AI 落地时擅自改造原有 Web 端代码。

根因： 无边界约束，AI 习惯性补充额外功能。

解决方案： 提案中细化「不做什么」，排除范围后续会被 Superpowers 合规审查引用。

#踩坑 3：任务粒度不匹配

现象： OpenSpec 单条「实现 JWT 签发函数」，无法直接对接 Superpowers 六步 TDD 开发。

解决方案： 通过衔接层做粒度转换——由 Superpowers writing-plans 自动拆解原子开发步骤（编写失败测试 → 执行报错 → 最小代码实现 → 测试通过 → 代码重构 → 提交代码）。

#踩坑 4：Superpowers 空跑

现象： 无视 design.md 中 Redis 黑名单约定，AI 改用内存 Map 存储失效 Token。

根因： 无规范上下文，AI 自主选用实现方案。

解决方案： 启动开发前强制加载 OpenSpec 全套规范文档（design.md + specs + tasks.md）。

#踩坑 5：原生代码审查不校验规范合规

现象： 代码质量无问题，但实现逻辑和 specs/design 不符，常规 CR 无法识别。

解决方案： 新增 spec-compliance-check 自定义 Skill，强制审查时比对全套规范文档。详见下方「自动化 Skill 方案」。

#踩坑 6：二选一执行审查/校验

现象： 代码 CR 满分但实现偏离规范，或 Verify 合规但代码无法运行。

根因： 混淆「代码质量」与「规范合规」的校验目标。

解决方案： 固定顺序：代码质量审查 → 规范合规审查 → OpenSpec 全量 Verify。

#踩坑 7：Archive 前未跑全量测试

现象： Verify 校验合规，但存在隐性代码 BUG，上线后暴露。

根因： OpenSpec 归档无内置全量测试强制校验。

解决方案： 归档前强制触发 Superpowers 全量测试校验，测试全量通过才可归档。

#失败路径修复手册

以下 5 个场景是最常见的卡点，每个都包含症状、根因、修复步骤和防复发策略。

#场景 1：Implementer 偏离需求

症状：

• 代码「看起来都对」，但和 specs/*.md 的约束对不上
• PR 里出现「顺便加了个功能/顺便改了个结构」

高频原因：

• tasks.md 只有「做什么」，缺少「做到什么算完成」（DoD）
• 实现阶段一次性加载太多上下文，注意力漂移

修复步骤：

1. 回到 tasks.md：给每个任务补 1 行 DoD（Definition of Done）（状态码/错误分支/测试覆盖点/日志）
2. Implementer 只做「减法」：把非目标移出本变更
3. Spec Reviewer 用「对照打勾」方式审：只判定是否满足 specs + DoD

防复发： 把 proposal.md 的「非目标」同步到 tasks.md 顶部，作为实现阶段护栏。

#场景 2：TDD 卡住

症状：

• 红灯阶段写不出一个合理的失败测试
• 测试依赖 DB/网络，跑不稳定

高频原因：

• 一个任务包含多个行为，测试无法聚焦
• 依赖未隔离，很难 mock

修复步骤：

1. 把任务拆到 2–5 分钟粒度：一条测试只覆盖一个行为
2. 先写「纯校验/纯映射」测试，再写 I/O
3. 对 DB/网络：先做「内存实现 + 契约测试」，最后再换真实实现

防复发： 在 tasks.md 每个任务里写明：1 个失败用例 + 1 个边界用例。

#场景 3：Worktree 管理混乱

症状：

• 同一变更出现多个 worktree，或在错误 worktree 上改代码
• 合并时发现漏文件/漏 commit

修复步骤：

1. 约定命名：../<repo>-<change>-<yyyyMMdd> 或 ../<repo>-feature-xxx
2. 每次开工先 git worktree list，确认路径 ↔ 分支
3. 只保留 ≤ 3 个活跃 worktree：完成一个就删一个

防复发： 在变更任务清单顶部写清楚 worktree 路径 + 分支名。

#场景 4：Verify 不通过

症状： 验证报告提示某些任务未覆盖，或测试/构建失败。

修复步骤：

1. 把失败项映射回 tasks.md——哪个任务的 DoD 没满足
2. 先修「便宜失败」（lint/类型/单测），再修系统性失败（集成/架构）
3. 修复后补 1 条「回归测试点」

防复发： 每完成 2–3 个小任务就做一次快速验证，不要堆到最后。

#场景 5：Spec Reviewer 与 Code Reviewer 意见冲突

症状： 一个说「满足规格就行」，另一个说「结构不行要重构」。

修复步骤：

1. 先过规格：只讨论「是否满足 specs + DoD」
2. 再过质量：限定重构边界（不改行为、不改外部接口）
3. 若确需大改：回到 design.md 补一条决策记录

防复发： 固定两阶段审查输出——Spec 只给「缺口清单」，Quality 只给「风险清单」。

#自动化 Skill 方案

上述 7 个踩坑中，5 个可通过自定义 Skill 自动化处理（仅坑 1、坑 2 需人工在需求阶段把控）。

#Skill 1：spec-compliance-check（规范合规校验）

解决： 踩坑 5（原生审查不校验规范合规）

触发时机： 代码审查前

功能：

1. 读取项目主规范 + 本次增量 spec 文档
2. 逐条核对 spec「假设-当-则」场景落地、design 架构方案、proposal 排除范围
3. 发现违规直接标记 BUG

部署路径：

• Claude Code：~/.claude/skills/ 目录
• Cursor：.cursor/rules/ 目录

#Skill 2：openspec-superpowers-bridge（双框架衔接桥梁）

解决： 踩坑 3、4、6、7

触发时机： 启动 Superpowers 实现任务时

功能：

1. 自动检索 openspec/changes 目录未归档变更文档，全量加载 design、spec、tasks
2. 已完成 Explore/Propose 则自动跳过 Superpowers brainstorming
3. 自动把 spec 业务场景转换为 TDD 测试用例，拆分 tasks 至 Superpowers 标准粒度
4. 单任务完成自动调用合规审查，全任务结束强制 Verify + 全量测试后才可 Archive

#实测数据对比

以 JWT 认证功能为例，三种落地模式的实测对比：

#场景选型指南

简易判断标准： 代码生命周期 ≥ 1 个月、≥ 3 位开发者参与，优先双框架联用。

#相关资源

• OpenSpec + Superpowers 双层规划 — 桥接配置详解
• Comet 自动化流水线 — 一键自动串联
• 自定义技能 — 编写自定义 Skill
• 工作流故障排除 — 通用故障修复手册