三件套组合拳：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 编程的“Vibe Coding”模式——靠直觉写 Prompt、反复修改、直到“看起来能跑通”——在企业级后端系统中根本走不通。AI 在长对话中会遗忘早期约束，brainstorm 中否决的方案可能在第 50 轮对话时被重新提出；/clear释放上下文后，之前达成的共识全部丢失。AI 有能力写代码，但没有纪律维护工程质量——它不会主动先写测试，不会系统定位 bug 根因，也不会在写代码前检查 spec。

这就引出了本文的核心：Claude Code + OpenSpec + Superpowers 三件套。本文将基于最新的社区实践，从零到一带你搭建一套可落地、可复制的 SDD 工作流——包含环境准备、命令速查、后端专项案例和避坑指南，让你看完就能上手。

一、先看全景：三件套怎么分工？

在深入实践之前，先理解三者的角色分工，避免“装了插件不知道怎么用”。

1.1 OpenSpec：管“写什么”——规范的单一真相源

OpenSpec 是 Fission AI 推出的轻量级规范驱动开发框架，核心工作流围绕“提案-审查-实施-归档”展开：

openspec/ ├── specs/ # 主规范库（项目的“宪法”） └── changes/ # 变更目录（每一次功能迭代的完整记录） └── [change-name]/ ├── proposal.md # 为什么做、目标/非目标、影响范围 ├── design.md # 技术方案选择、替代方案对比 ├── specs/ # Delta Specs（ADDED/MODIFIED/REMOVED） └── tasks.md # checkbox 任务清单

最独特的是Delta Spec 体系：每个变更只描述相对于主规范的增量修改，归档后自动合并回主规范库。

1.2 Superpowers：管“怎么做”——AI 执行的纪律警察

Superpowers 是 Claude Code 官方认证插件，由核心开发者 Jesse Vincent 打造。其核心工作流是强制四步：Brainstorm → Git Worktree → Write a Plan → Execute，并内置四大强制规范技能库：TDD 铁律、系统化调试、验证闭环、上下文注入管理。

1.3 Claude Code：管“谁来跑”——SDD 的最佳执行引擎

Claude Code 是整个体系的运行平台，通过/plugin命令集成 OpenSpec 和 Superpowers 的技能体系。

1.4 三者协同的核心理念：Action Not Phases

SDD 的核心设计理念是Action Not Phases：每个操作是独立能力（action），不是必须按顺序完成的阶段（phase）。

依赖关系是enabler（前置 artifact 应存在），不是gate（缺失则阻断）。大特性可以走完整流程，小修复可以跳过头脑风暴直接sdd-propose——这不是“违规跳阶段”，而是根据需要选择能力组合。

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

2.1 前置条件

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

2.2 安装 Superpowers（最推荐方式：插件市场一键安装）

# 进入 Claude Code 会话后执行/plugin marketplaceaddobra/superpowers-marketplace /plugininstallsuperpowers@superpowers-marketplace

这是 2026 年 3 月后成功率最高的方式，10 秒搞定。

2.3 安装 OpenSpec CLI

npminstall-g@fission-ai/openspec@latest

2.4 在项目目录初始化 OpenSpec

cdyour-backend-project openspec init

2.5 配置项目级 CLAUDE.md（让规范在每个会话自动生效）

在项目根目录创建CLAUDE.md。社区共识是：CLAUDE.md 的重要性不亚于 .gitignore。

# 项目上下文 ## 工作流规范 本项目采用 SDD（规范驱动开发），使用 OpenSpec 管理规范变更，Superpowers 约束执行纪律。 ## 技术栈 - 语言：Go 1.21+ - 框架：Gin + GORM - 数据库：PostgreSQL - 架构：分层结构（handler → service → repository） ## 代码规范 - 错误处理：统一使用 pkg/errors 包装 - 数据库事务：必须通过 repository 层的 Tx 方法管理 - 外部 API 调用：必须有超时控制和重试策略 ## 规范引用 - API 规范：./docs/api/openapi.yaml - 数据模型：./docs/db/schema.sql ## 分支命名规范 - 功能分支：feature/功能简称 - 修复分支：fix/问题描述 - 与 SDD 工作流保持一致：分支名 = OpenSpec change name

三、完整工作流：从产品文档到上线

以下以“订单退款功能”为例，演示完整的六阶段 SDD 工作流。

3.1 需求梳理（两条路径可选）

路径 A：OpenSpec Explore（推荐用于“只有截图+字段表”的场景）

/opsx:explore

将产品的原型截图和字段文档拖入对话，Explore 模式是只读思考伙伴——从截图提取页面结构、画 ASCII 图理清状态流转、不写代码，只输出理解。这一步投入 30 分钟澄清“部分退款是否在范围内”“库存回滚失败如何处理”等问题，远比编码阶段返工划算。

路径 B：Superpowers Brainstorming

直接告诉 AI 要做什么，Superpowers 自动进入 brainstorming 流程：探索项目结构 → 一次问一个问题澄清需求 → 提出 2-3 种方案 → 分段展示设计逐段确认 → 写入docs/superpowers/specs/并 commit。

3.2 生成结构化制品

使用 OpenSpec Propose 一步到位：

/opsx:propose add-order-refund-feature

自动生成三个核心文件：

proposal.md 示例（订单退款功能）：

# Proposal: add-order-refund-feature ## Why 当前系统缺少订单退款能力，用户和客服都需要手动处理退款流程。 ## Goals - 支持用户发起退款申请 - 支持客服审核并执行退款 - 退款成功后自动回滚库存 - 完整记录退款流水 ## Non-Goals - 不支持部分退款（本次范围外） - 不支持自动审核 ## Impact - 订单模块：新增 refund 子模块 - 库存模块：新增回滚接口 - 数据库：新增 refund_records 表

specs/ 中的场景定义（采用 GIVEN/WHEN/THEN 格式，确保可验证）：

### Scenario: 退款成功时回滚库存 - GIVEN 订单状态为“已支付”且退款申请通过审核 - WHEN 系统执行退款操作 - THEN 订单状态更新为“已退款” - AND 库存数量增加对应数量 - AND 退款记录状态为“成功” ### Scenario: 重复退款请求的幂等性 - GIVEN 订单已存在一条“处理中”的退款记录 - WHEN 再次发起退款申请 - THEN 返回已有退款记录，不创建新记录 - AND 不重复扣减/回滚任何数据

3.3 工作区隔离

Superpowers 的 git-worktree 自动触发：

开始实现 add-order-refund-feature

Superpowers 会自动：

• 创建.worktrees/add-order-refund-feature隔离工作区
• 新建feature/add-order-refund-feature分支
• 运行依赖安装
• 验证测试基线通过

为什么要隔离？主工作区保持干净，多个功能可以并行开发互不干扰。

3.4 逐任务实现

OpenSpec Apply + Superpowers Subagent 联合驱动：

模式 A：Subagent-Driven（推荐，大功能用）

/opsx:apply

执行流程：

1. 主 Agent 读取tasks.md，提取每个任务的完整描述
2. 派发 Subagent 实现任务（遵循 TDD：写测试 → 红 → 实现 → 绿 → 重构）
3. 派发 Spec Reviewer 检查是否符合design.md
4. 派发 Code Reviewer 检查代码质量
5. tasks.md中对应任务打勾[x]
6. 循环直到全部完成

模式 B：直接执行（小功能用）

AI 直接在当前会话中逐任务实现，每完成一个打勾。

3.5 验证 + 收尾

/opsx:verify add-order-refund-feature

三维度检查：完整性 × 正确性 × 一致性。

通过后，Superpowers 接管收尾：自动运行全量测试，提供四个选项（合并 / 创建 PR / 保留分支 / 丢弃），清理 worktree。

3.6 归档

/opsx:archive add-order-refund-feature

归档后，变更目录移动到openspec/changes/archive/2026-04-19-add-order-refund-feature/，Delta Spec 自动合并回主规范库。从此任何人（包括未来的 AI）都能追溯到：当初为什么设计退款功能、做了哪些技术选型、考虑了哪些替代方案。

四、后端开发专项案例

4.1 案例一：API 接口设计与实现（以用户登录接口为例）

# 1. 需求探索（如果已有清晰 PRD 可跳过）/opsx:explore# 2. 生成提案/opsx:propose add-user-login-api

在生成的design.md中明确 JWT 鉴权方式、Token 过期策略、错误码规范，specs/中定义接口场景：

### Scenario: 登录成功返回 Token - GIVEN 用户输入正确的用户名和密码 - WHEN 调用 /api/v1/login 接口 - THEN 返回 200 状态码 - AND 返回 JWT Token，有效期 24 小时 ### Scenario: 密码错误返回 401 - GIVEN 用户输入正确的用户名但错误的密码 - WHEN 调用 /api/v1/login 接口 - THEN 返回 401 状态码 - AND 错误信息为“用户名或密码错误”

# 3. 隔离工作区开始实现 add-user-login-api# 4. 实现（TDD 先行）/opsx:apply# 5. 验证 + 归档/opsx:verify add-user-login-api /opsx:archive add-user-login-api

核心收益：API 规范成为单一真相源，OpenAPI 文件与代码实现始终同步，彻底告别“文档与代码不一致”。

4.2 案例二：数据库 Schema 变更（添加字段）

/opsx:propose add-user-avatar-field

specs/中定义字段约束：

### Requirement: users 表新增 avatar 字段 - 字段类型：VARCHAR(512) - 默认值：空字符串 - 是否可空：是 - 索引：无需单独索引

tasks.md自动生成：

• 生成迁移 SQL（ALTER TABLE users ADD COLUMN avatar VARCHAR(512) DEFAULT ''）
• 更新 DAO 层的 User 结构体
• 更新 API 响应结构
• 编写迁移回滚脚本

/opsx:apply /opsx:verify add-user-avatar-field /opsx:archive add-user-avatar-field

核心收益：每次 Schema 变更都有完整的提案和设计文档，迁移脚本可回滚。

4.3 案例三：微服务间接口契约变更

/opsx:propose update-order-service-api-v2

在specs/中使用 Delta Spec 标记接口字段的ADDED/MODIFIED/DEPRECATED：

## MODIFIED Requirements ### Requirement: 订单查询接口响应 新增字段 `refund_status`，类型为字符串，可选值：NONE/PENDING/SUCCESS/FAILED

多个服务团队基于同一份规范协同开发，消费者服务可提前感知变更影响。

五、任务中断与恢复：AI 不会“失忆”的秘密

这是 SDD 工作流最核心的价值之一。AI 有两个致命限制：上下文窗口有限（长对话后期忘记前面内容）、会话不持久（关窗口 = 一切归零）。

5.1 解决方案：三层持久化

第 1 层：项目级永久记忆——CLAUDE.md+openspec/config.yaml，每次新对话 AI 自动读取，相当于“置顶备忘录”。

第 2 层：功能级需求记忆——openspec/changes/[change-name]/下的 proposal.md（功能是干嘛的）、design.md（代码怎么组织）、tasks.md（做到哪了，checkbox 就是进度）。

第 3 层：代码级状态记忆—— git worktree + branch，分支名就是功能名，commit 历史就是实现进度。

5.2 中断后如何恢复

# 1. 重新进入 Claude Code 会话cdyour-backend-project# 2. 查看当前变更状态openspec list# 3. 继续上次未完成的任务/opsx:continue add-order-refund-feature

AI 会读取tasks.md中的 checkbox 状态，自动从未完成的任务继续执行。任意步骤之间可以安全/clear，状态在文件系统中，不在对话历史里。

六、经验与教训：资深后端工程师的避坑指南

6.1 不要试图跳过探索阶段

/opsx:explore看似“浪费时间”，实则是整个流程中 ROI 最高的环节。在退款功能的实践中，探索阶段花了 30 分钟澄清边界条件——如果这些问题等到编码阶段才发现，返工成本至少翻三倍。想清楚再动手，永远比边做边改快。

6.2 充分利用 Action Not Phases 的灵活性

不要被“必须按顺序走完所有阶段”的思维束缚。小修复可以跳过 brainstorm 直接sdd-propose，紧急 hotfix 甚至可以直接sdd-code（前提是有现成的规范文件）。SDD 的依赖关系是 enabler，不是 gate。

6.3 规范文件要“可验证”，不要“写散文”

OpenSpec 的 specs 文件建议采用GIVEN/WHEN/THEN格式，确保每个需求场景都可被自动化测试验证。让 AI 明确知道“验收标准是什么”，也让 verify 阶段有据可依。

6.4 谨慎使用/clear和 Subagent

• 主动使用/compact在上下文接近满载前压缩历史
• 对于会产生大量中间输出的子任务，使用 Sub-agent 隔离上下文
• 新任务开新会话，不要试图在一个会话里完成所有事情
• 提升 Claude Code 效率的本质，是将有限的上下文用在刀刃上

6.5 代码审查：AI 写代码，人做 Gatekeeper

AI 能写代码，但不能替代人对架构和业务的理解。SDD 工作流中，代码审查的角色从“找 Bug”转变为“审查架构一致性”——检查 AI 生成的代码是否遵循了规范中定义的架构决策。

6.6 别忘了测试

AI 生成的代码最容易被诟病的是“不知道对不对”。解决之道恰恰是回归最经典的后端工程实践——测试驱动开发。在 SDD 流程中，测试用例本身就是规范的一部分。让 AI 先根据规范生成测试代码，再生成实现代码，最后运行测试验证。

七、命令速查表

结语：从“写代码的人”到“定义规则的人”

Claude Code + OpenSpec + Superpowers 的组合，代表的不是工具的简单堆叠，而是AI 辅助软件开发的工程范式跃迁。

OpenSpec 解决了“写什么”——让规范成为单一真相源，每一次代码变动都有完整的决策追溯链。Superpowers 解决了“怎么做”——让 AI 拥有工程纪律，TDD、代码审查、系统化调试不再依赖人工提醒。Claude Code 解决了“谁来跑”——作为统一的代理平台，让规范和纪律无缝落地。

对于有 10 年经验的后端工程师来说，这套体系恰恰将我们从“代码的生产者”升级为“规范的定义者”。我们最值钱的从来不是打字速度，而是理解复杂业务、设计稳健架构、做出正确技术决策的能力。

2026 年的后端开发，拼的不再是“谁加班多”，而是“谁的规范更清晰、谁的 AI 协作更高效、谁的工程纪律更严谨”。

作者注：本文基于 2026 年 4 月的最新实践经验撰写。OpenSpec、Superpowers 和 Claude Code 均处于快速迭代中，具体命令和功能建议以各项目官方文档为准。