三件套组合拳：Claude Code + OpenSpec + Superpowers 的 SDD 后端高质量开发最佳实践

三件套组合拳：Claude Code + OpenSpec + Superpowers 的 SDD 后端开发最佳实践

引言：从"能用 AI 写代码"到"能用 AI 写对代码"的工程鸿沟

2025 年 10 月，一个名为 Superpowers 的插件上线 Claude Code 插件市场，五个月内斩获 107,000 GitHub stars、8,600 forks，成为开发者工具仓库史上增长最快的项目之一。与此同时，Fission AI 推出的 OpenSpec 也在 AI 编码圈掀起波澜------二者共同指向同一个命题："AI 写代码"从来不是软件开发的难点，"写对代码"才是。

作为一名拥有 10 年经验的后端研发工程师，我深知后端系统开发的本质挑战：高耦合、强约束、重状态。一个订单服务的改动可能牵涉库存扣减、支付回调、消息推送等多个模块，任何一个环节的规范缺失都可能导致数据不一致或生产事故。在 AI 辅助编程时代，这个矛盾被进一步放大------AI 能秒出几百行代码，但这些代码真的是我们想要的吗？它符合设计意图吗？有没有超出范围？有没有遗漏场景？

更致命的问题是：AI 会说"完成了"，但这不代表真的完成了。

我在一周内上线了三次有问题的代码------每次 Claude 都说"should work"，每次我都信了。AI 生成代码可以表面上看起来正确，但往往隐藏着逻辑错误和不一致。当 AI 说"should work"，那不是验证，是猜测。

为了解决这个问题，Superpowers 内置了一个关键技能------verification-before-completion 。它强制执行一条铁律：在任何任务被标记为"完成"之前，必须提供可验证的证据 。本文将以 Claude Code 为运行平台，OpenSpec 为规范管理框架，Superpowers 为执行纪律引擎，深入剖析如何通过 verification-before-completion Skill 将"猜测式开发"转变为"证据驱动交付"。

一、认识 `verification-before-completion` Skill：AI 开发的质量基石

1.1 核心理念

verification-before-completion 是 Superpowers 插件内建的一项 Skill，它在任务即将被标记为"已完成"时自动触发（也可显式调用），执行一套强制性的验证检查流程。

该 Skill 的核心法则可以概括为：证据在前，结论在后。如果你在这一轮对话中没有运行过验证命令，就不能声称通过了验证。

它拦截了 AI 最常见的"幻觉式完成"行为：

AI 说"应该没问题了"，但从来没跑过测试
AI 说"看起来对了"，但从来没检查过编译输出
AI 说"修复完成了"，但从来没验证过 bug 是否复现

该 Skill 会识别并禁止使用以下"红牌词汇"：

❌ "should work"
❌ "probably fine"
❌ "I'm confident"
❌ "looks good"
❌ "seems correct"

这些词汇屏蔽的不是话术，而是一种错误的工程心态：用置信度替代证据。

1.2 Skill 的"五步验证法"

当 verification-before-completion 被触发时，它会引导 AI 执行以下步骤：

IDENTIFY ：明确能够证明任务成功的验证命令（例如 make test、go test ./...、curl 健康检查）。
RUN ：完整执行该命令（不能使用缓存结果，必须是全新、完整的运行）。
READ：读取完整输出，检查退出状态码，统计失败数量。
VERIFY ：判断输出是否证实了完成声称。
- 若否 → 如实陈述实际状态，并继续修复。
- 若是 → 带着具体证据（如"42 tests passed"）进行下一步。
ONLY THEN：做出"已完成"的声明，并将验证证据写入对话记录。

跳过任何一步 = 未通过验证，该 Skill 将阻止任务被标记为完成。

1.3 为什么这对后端开发尤其重要

后端系统的高耦合特性决定了：一个环节的"自以为正确"会在多个环节之后爆炸。订单退款功能可能涉及：

数据库事务边界是否正确？
库存回滚的幂等性是否保证？
并发场景下的锁机制是否生效？

这些问题，光靠"should work"是检测不出来的。verification-before-completion Skill 强制 AI 在每次完成声明前运行测试、检查日志、验证行为，从根本上杜绝了"猜测式上线"。

二、环境准备：10 分钟搭好三件套

2.1 前置条件

bash 复制代码

node --version  # 需要 Node.js v16 或更高
claude --version  # 确保 Claude Code CLI 已安装并能运行

2.2 安装 OpenSpec CLI

bash 复制代码

npm install -g @fission-ai/openspec@latest

2.3 在项目目录初始化 OpenSpec

bash 复制代码

cd your-backend-project
openspec init

2.4 安装 Superpowers 插件（包含 verification-before-completion Skill）

bash 复制代码

# 进入 Claude Code 会话后执行
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

安装完成后，Superpowers 的所有内置 Skill（包括 verification-before-completion）将自动生效。你可以通过以下命令查看已安装的 Skill 列表：

bash 复制代码

/plugin list

2.5 配置项目级 CLAUDE.md（激活 Skill 上下文）

在项目根目录的 CLAUDE.md 中明确验证要求，确保该 Skill 在每个会话中都能被正确触发：

markdown 复制代码

# 项目上下文

## 工作流规范
本项目采用 SDD（规范驱动开发），使用 OpenSpec 管理规范变更，Superpowers 约束执行纪律。
**核心 Skill：verification-before-completion ------ 任何"完成"声明必须有新鲜验证证据支持。**

## 技术栈
- 语言：Go 1.21+
- 框架：Gin + GORM
- 数据库：PostgreSQL
- 架构：分层结构（handler → service → repository）

## 代码规范
- 错误处理：统一使用 pkg/errors 包装
- 数据库事务：必须通过 repository 层的 Tx 方法管理
- 外部 API 调用：必须有超时控制和重试策略

## 验证要求（由 verification-before-completion Skill 强制执行）
- 每次声称"完成"前，必须运行完整的测试套件并提供输出证据
- 禁止使用"should work"、"probably fine"、"looks good"等置信度话术
- PR 合并前必须通过 `/opsx:verify` 检查，并提供验证报告
- 任何 Bug 修复必须先编写复现测试，验证修复后测试通过

## 规范引用
- API 规范：./docs/api/openapi.yaml
- 数据模型：./docs/db/schema.sql

三、三种联合工作流模式（均嵌入 verification-before-completion Skill）

OpenSpec 与 Superpowers 的结合并非只有一种固定模式。根据项目规模、团队偏好和流程灵活性，我总结了以下三种主要的集成方式，每种都强制嵌入了 verification-before-completion Skill 作为质量闸门。

3.1 模式一：标准交接模式（The Handoff）

职责划分：OpenSpec 负责规划，Superpowers 负责执行与验证。

工作流与 Skill 触发点：

阶段	命令	verification-before-completion 触发点
需求探索	`/opsx:explore`	人工确认理解
生成提案	`/opsx:propose <name>`	OpenSpec 自动校验格式
制定执行计划	`/superpowers:writing-plans`	计划可执行性校验
执行开发	`/superpowers:subagent-driven-development`	每个子任务完成前自动触发该 Skill
规范验证	`/opsx:verify <name>`	四层完整性验证
归档	`/opsx:archive <name>`	合并前最终检查

适用场景：大型、复杂特性开发，需要严格的职责分离和质量审计。

Skill 强化机制：

在执行开发阶段，Superpowers 启动的 Subagent 会在每个任务完成后自动调用 verification-before-completion Skill。该 Skill 要求 Subagent 提供 TDD 测试通过的证据（如测试运行日志），否则任务无法标记为完成。
在归档前，/opsx:verify 执行四层验证，同样会触发该 Skill 的变体验证，确保规范与实现完全一致。

3.2 模式二：嵌入式协作模式（The Embedding）

职责划分：以 OpenSpec 为主干，将 Superpowers 的验证 Skill 作为"检查点"嵌入。

工作流与 Skill 触发点：

阶段	命令	verification-before-completion 触发点
生成提案	`/opsx:propose <name>`	OpenSpec 自动校验
执行开发	`/opsx:apply`	pre_tasks 与 post_tasks 中显式调用该 Skill
规范验证	`/opsx:verify <name>`	四层完整性验证
归档	`/opsx:archive <name>`	合并检查

OpenSpec 配置调整 （在 openspec/config.yaml 中）：

yaml 复制代码

workflows:
  apply:
    pre_tasks:
      - superpowers:verification-before-completion   # 在开始实现前验证环境就绪
    post_tasks:
      - superpowers:tdd-red-green-refactor
      - superpowers:request-code-review
      - superpowers:verification-before-completion   # 最终验证门禁

适用场景：希望简化命令数量的团队，通过配置将验证能力内嵌到 OpenSpec 流程中。

Skill 强化机制：

pre_tasks 中的 verification-before-completion 会检查当前 git 状态、测试环境是否干净，确保后续开发的基础可靠。
post_tasks 中的该 Skill 会在所有任务完成后，要求 AI 提供本轮所有测试通过的汇总证据，否则整个 apply 流程标记为失败。

3.3 模式三：轻量级 TDD 模式（The Lite TDD）

职责划分：全程使用 Superpowers 驱动，兼顾效率与质量。

工作流与 Skill 触发点：

阶段	命令	verification-before-completion 触发点
需求探索	`/superpowers:brainstorming`	交互式确认
制定计划	`/superpowers:writing-plans`	可执行性校验
TDD 开发	`/superpowers:tdd-red-green-refactor`	每个红-绿-重构循环结束前触发
代码审查	`/superpowers:request-code-review`	审查前必须通过验证
最终验证	自动触发该 Skill	强制运行全量测试并提供证据

适用场景：中小功能开发、独立模块、快速迭代场景。

Skill 强化机制：

在 TDD 循环中，当 AI 完成"绿阶段"后，verification-before-completion Skill 会被自动调用，要求 AI 展示测试通过的证据。如果测试未通过，循环将回退到实现阶段。
最终验证阶段，该 Skill 会拒绝任何无证据的"完成"声明，强制 AI 运行 make test && make lint 并截图输出。

四、实战演练：用"标准交接模式"完成一个后端需求

下面以"订单退款功能"为例，演示 verification-before-completion Skill 如何在完整开发闭环中发挥作用。

4.1 阶段一：需求探索与提案（OpenSpec 主导）

bash 复制代码

# 1. 探索需求边界
/opsx:explore
# 输出：需求理解文档
# 验证点：人工确认理解文档无误

# 2. 生成提案
/opsx:propose add-order-refund-feature

关键产出（采用 GIVEN/WHEN/THEN 格式，为后续验证提供标准）：

markdown 复制代码

### Scenario: 退款成功时回滚库存
- GIVEN 订单状态为"已支付"且退款申请通过审核
- WHEN 系统执行退款操作
- THEN 订单状态更新为"已退款"
- AND 库存数量增加对应数量
- AND 退款记录状态为"成功"

4.2 阶段二：任务执行（Superpowers 主导 + TDD + Skill 强制验证）

bash 复制代码

# 1. 制定详细执行计划
/superpowers:writing-plans

# 2. 执行开发（Subagent 模式）
/superpowers:subagent-driven-development

Superpowers 执行流程（每个任务均受 verification-before-completion Skill 约束）：

红阶段：Subagent 编写测试，运行测试 → 预期失败。此时 Skill 检查失败是否为预期（RED），若意外通过则标记异常。
绿阶段 ：编写实现代码，运行测试 → 必须通过。此时 verification-before-completion Skill 被触发 ：
- IDENTIFY：运行 go test ./... -run TestRefundSuccess
- RUN：执行命令
- READ：读取输出 PASS: TestRefundSuccess (0.02s)
- VERIFY：确认所有相关测试通过
- ONLY THEN：允许任务标记为 [x]
重构阶段：优化代码，再次运行测试 → 必须保持绿色。Skill 再次验证。
审查阶段：Spec Reviewer 和 Code Reviewer 检查。
完成标记：tasks.md 中对应任务打勾。

如果任何一步验证失败，Skill 会阻止任务完成，并要求 Subagent 返回修复。

4.3 阶段三：验证与归档（OpenSpec 收尾 + 最终闸门）

bash 复制代码

# 关键质量闸门：执行 /opsx:verify
/opsx:verify add-order-refund-feature

/opsx:verify 执行四层验证，其内部同样调用了类似 verification-before-completion 的机制来确认每项检查。

验证通过示例：

复制代码

✅ 提案意图验证通过：退款功能的实现与 proposal.md 目标一致
✅ 设计决策验证通过：分层架构正确，事务管理符合 design.md 要求
✅ 任务完成验证通过：tasks.md 中 5/5 任务已完成
✅ Delta Spec 验证通过：3 个 ADDED 需求格式正确

验证结果：通过 ✅

如果验证失败，Skill 会要求进入修复循环，直到通过为止。

最终归档：

bash 复制代码

/opsx:archive add-order-refund-feature

五、CI/CD 集成：将 verification-before-completion Skill 延伸到流水线

verification-before-completion Skill 不仅用于本地开发，更可作为 CI/CD 流水线的质量门禁，阻断不合格代码进入主干。

5.1 三层验证架构

层级	触发时机	验证内容	Skill 角色
Pre-commit	本地 git commit	运行 lint + 单元测试	本地 Skill 自动验证
PR 门禁	创建/更新 Pull Request	`/opsx:verify` + 全量测试	CI 调用该 Skill 逻辑
定时巡检	Cron 定时触发	规范与代码一致性检查	自动创建修复 Issue/PR

5.2 完整的 GitHub Actions 配置示例

yaml 复制代码

# .github/workflows/sdd-quality-gate.yml
name: SDD Quality Gate (verification-before-completion)

on:
  pull_request:
    branches: [ main ]

jobs:
  verify-change:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '20'

      - name: Install OpenSpec CLI
        run: npm install -g @fission-ai/openspec@latest

      - name: Verify OpenSpec Change
        id: verify
        run: |
          CHANGE_NAME=$(echo "${{ github.head_ref }}" | sed 's/^feature\///')
          openspec verify $CHANGE_NAME 2>&1 | tee verify.log
          if grep -q "验证结果：通过" verify.log; then
            echo "✅ OpenSpec 验证通过"
          else
            echo "❌ OpenSpec 验证失败"
            exit 1
          fi

      - name: Run Full Test Suite (verification-before-completion evidence)
        run: |
          make test 2>&1 | tee test.log
          if [ ${PIPESTATUS[0]} -ne 0 ]; then
            echo "❌ 测试套件未通过"
            exit 1
          fi
          echo "✅ 测试套件通过"

      - name: Comment PR on Failure
        if: failure()
        uses: actions/github-script@v6
        with:
          script: |
            const fs = require('fs');
            const verifyLog = fs.readFileSync('verify.log', 'utf8').slice(-2000);
            await github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `❌ **SDD 质量门禁失败**\n\n## 验证日志\n\`\`\`\n${verifyLog}\n\`\`\`\n\n**verification-before-completion Skill 要求提供通过证据，请修复后重新推送。**`
            });

六、避坑指南与最佳实践（Skill 使用篇）

6.1 不要禁用或绕过该 Skill

verification-before-completion 是 Superpowers 的强制安全网。即使你"觉得"没问题，也要让 Skill 执行完验证。绕过它直接声称完成，会导致后续任务依赖不可信的状态。

6.2 学会显式调用 Skill 进行手工验证

有时 AI 可能没有自动触发该 Skill，你可以显式调用：

复制代码

/superpowers:verification-before-completion

然后告诉 AI 你想验证什么（例如："验证刚刚修改的订单退款幂等性测试是否通过"）。Skill 会引导 AI 按照五步法执行。

6.3 将验证证据作为团队沟通的共同语言

在 Code Review 中，用验证证据替代主观判断：

传统 Review 评论	验证驱动 Review 评论
"看起来没问题"	"`verification-before-completion` 通过，测试覆盖率 85%，可以合并"
"这里可能有 bug"	"运行退款幂等性测试时 Skill 报告失败，日志见附件"

6.4 结合 OpenSpec 的 verify 命令形成双重保险

/opsx:verify 侧重规范一致性，verification-before-completion 侧重行为正确性。二者结合使用，构成完整的质量防御体系。

七、命令速查表（含 verification-before-completion Skill）

命令	作用	与 Skill 的关系
`/plugin install superpowers@...`	安装 Superpowers	自动包含该 Skill
`/superpowers:verification-before-completion`	显式调用该 Skill	手工触发验证流程
`/superpowers:subagent-driven-development`	Subagent 执行开发	每个子任务完成前自动触发该 Skill
`/opsx:verify <name>`	OpenSpec 全面验证	内部调用类似验证机制
`/opsx:apply`	执行开发（模式二）	通过配置嵌入该 Skill
`make test`	运行测试	是该 Skill 最常见的验证命令

结语：用 `verification-before-completion` 重塑 AI 开发的信任模型

Claude Code + OpenSpec + Superpowers 的组合，赋予了我们驾驭 AI 编写复杂后端系统的能力。而 verification-before-completion Skill 则是这套能力的安全阀------它用工程纪律替代了 AI 的"自信幻觉"，用不可辩驳的证据替代了模糊的"should work"。

对于有 10 年经验的后端工程师来说，我们的价值不在于与 AI 比打字速度，而在于定义什么是"正确"，并建立一套让 AI 必须证明自己正确的流程。当你习惯了每次完成都有证据支撑，你就会发现：上线不再靠运气，迭代不再靠加班。

记住：在没有运行 verification-before-completion 之前，没有任何任务真的完成了。

三件套组合拳：Claude Code + OpenSpec + Superpowers 的 SDD 后端高质量开发最佳实践

三件套组合拳：Claude Code + OpenSpec + Superpowers 的 SDD 后端开发最佳实践

引言：从"能用 AI 写代码"到"能用 AI 写对代码"的工程鸿沟

一、认识 verification-before-completion Skill：AI 开发的质量基石

1.1 核心理念

1.2 Skill 的"五步验证法"

1.3 为什么这对后端开发尤其重要

二、环境准备：10 分钟搭好三件套

2.1 前置条件

2.2 安装 OpenSpec CLI

2.3 在项目目录初始化 OpenSpec

2.4 安装 Superpowers 插件（包含 verification-before-completion Skill）

2.5 配置项目级 CLAUDE.md（激活 Skill 上下文）

三、三种联合工作流模式（均嵌入 verification-before-completion Skill）

3.1 模式一：标准交接模式（The Handoff）

3.2 模式二：嵌入式协作模式（The Embedding）

3.3 模式三：轻量级 TDD 模式（The Lite TDD）

四、实战演练：用"标准交接模式"完成一个后端需求

4.1 阶段一：需求探索与提案（OpenSpec 主导）

4.2 阶段二：任务执行（Superpowers 主导 + TDD + Skill 强制验证）

4.3 阶段三：验证与归档（OpenSpec 收尾 + 最终闸门）

五、CI/CD 集成：将 verification-before-completion Skill 延伸到流水线

5.1 三层验证架构

5.2 完整的 GitHub Actions 配置示例

六、避坑指南与最佳实践（Skill 使用篇）

6.1 不要禁用或绕过该 Skill

6.2 学会显式调用 Skill 进行手工验证

6.3 将验证证据作为团队沟通的共同语言

6.4 结合 OpenSpec 的 verify 命令形成双重保险

七、命令速查表（含 verification-before-completion Skill）

结语：用 verification-before-completion 重塑 AI 开发的信任模型

一、认识 `verification-before-completion` Skill：AI 开发的质量基石

结语：用 `verification-before-completion` 重塑 AI 开发的信任模型