OpenSpec + Superpowers + Claude Code 如何深度整合，并提供 3 种针对不同场景的 CI/CD 集成方案，构建高质量、可复制的 SDD 工作流。

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

在开始之前，确保你的开发环境已经准备就绪：

# 1. 安装 OpenSpec CLI
npm install -g @fission-ai/openspec@latest

# 2. 在项目目录初始化 OpenSpec
cd your-backend-project
openspec init

# 3. 进入 Claude Code 会话，安装 Superpowers 插件
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

# 4. 配置项目级 CLAUDE.md（让规范在每个会话自动生效）
# 创建或编辑 CLAUDE.md，写入以下内容

CLAUDE.md 模板：

# 项目上下文

## 工作流规范
本项目采用 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

---

🤝 三种联合工作流模式

OpenSpec 与 Superpowers 的结合并非只有一种固定模式。根据项目规模、团队偏好和流程灵活性，我总结了以下三种主要的集成方式：

• 模式一：标准交接模式 (The Handoff)：OpenSpec 负责规划，Superpowers 负责执行。
  这是最经典的“各司其职”模式。/opsx:propose 后，OpenSpec 生成结构化的 tasks.md 文件，然后由 Superpowers 的 /superpowers:writing-plans 和 ...:subagent-driven-development 命令接管实现与质量审查。这种模式职责清晰，非常适合复杂功能开发。

• 模式二：嵌入式协作模式 (The Embedding)：以 OpenSpec 为主干，嵌入 Superpowers 的纪律 Skill。
  此模式将 Superpowers 的核心能力（如 TDD、代码审查）拆解为独立的 Skill，并以“检查点”的形式嵌入到 OpenSpec 的 /opsx:apply 流程中，从而在 OpenSpec 框架内引入质量保障机制。

• 模式三：轻量级 TDD 模式 (The Lite TDD)：全程使用 Superpowers，兼顾效率与质量。
  这是一个针对快速迭代的轻量级方案。它直接使用 Superpowers 的 TDD 技能驱动开发（/superpowers:tdd-xxx），同时利用其内置的 writing-plans 和 subagent-driven-development 命令进行任务拆解与实现。这种模式更灵活，适合中小功能开发。

---

🚀 实战演练：用“标准交接模式”完成一个后端需求

下面我们以“订单退款功能”为例，使用模式一（标准交接模式） 来演示一个完整的开发闭环。

阶段一：需求探索与提案 (OpenSpec 主导)

1. 探索：对于复杂需求，先用 /opsx:explore 与 AI 进行苏格拉底式对话，澄清边界。
2. 生成提案：执行 /opsx:propose add-order-refund-feature，OpenSpec 会自动生成 proposal.md, design.md, specs/, tasks.md。
   • 关键产出 (tasks.md):

     ## Tasks for add-order-refund-feature
     - [ ] 定义退款数据模型 (refund_records 表)
     - [ ] 实现 RefundService 接口
     - [ ] 实现退款申请、审核、回调等方法
     - [ ] 编写单元测试 (覆盖率 > 80%)
     

3. 配置 OpenSpec：为确保流程清晰，我们可以在 OpenSpec 配置中禁用其自带的 apply 命令，将实现阶段完全交由 Superpowers。

阶段二：任务执行 (Superpowers 主导)

1. 制定计划：执行 /superpowers:writing-plans，Superpowers 会读取 tasks.md，并将每个任务细化为 2-5 分钟可完成、带代码示例和测试方法的原子步骤。
2. 执行开发：执行 /superpowers:subagent-driven-development。Superpowers 会启动 Subagent，强制遵循 TDD（红-绿-重构），并为每个任务进行 Spec 合规与代码质量双重审查。

阶段三：验证与归档 (OpenSpec 收尾)

1. 验证：执行 /opsx:verify add-order-refund-feature，从完整性、正确性、一致性三个维度进行自动化检查。
2. 归档：执行 /opsx:archive add-order-refund-feature，将变更归档到 openspec/changes/archive/...，其 Delta Spec 也会自动合并回主规范库。

---

⚙️ CI/CD 集成：从本地开发到质量门禁

SDD 的价值不仅体现在本地开发，更在于将其作为质量门禁嵌入 CI/CD 流水线，实现自动化规范验证。

1. 核心原则

将 OpenSpec 和 Superpowers 的核心能力封装为 CI 步骤，并引入 Superpowers 作为 CI 中的“质量闸门”，通过其强制执行 TDD、代码审查、验证闭环等纪律，确保代码在进入主干前已通过工程规范检查。

2. 具体方案

以下是一套完整的 GitHub Actions 配置示例：

# .github/workflows/sdd-quality-gate.yml
name: SDD Quality Gate

on:
  pull_request:
    branches: [ main ]

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

      # 1. 安装依赖
      - name: Install OpenSpec CLI
        run: npm install -g @fission-ai/openspec@latest

      # 2. 验证 OpenSpec 规范合规性
      - name: Verify OpenSpec Change
        run: |
          # 提取 PR 关联的 change-name (例如从分支名)
          CHANGE_NAME=$(echo "${{ github.head_ref }}" | sed 's/feature\///g')
          # 运行 OpenSpec 验证
          openspec verify $CHANGE_NAME
        continue-on-error: false

      # 3. 运行 Superpowers 驱动的测试
      - name: Run Superpowers-Driven Tests
        run: |
          # 假设你的项目有一个 script 来运行 Superpowers 测试
          npm test
        continue-on-error: false

      # 4. 如果验证失败，在 PR 中评论
      - name: Comment PR on Failure
        if: failure()
        uses: actions/github-script@v6
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: '❌ **SDD 质量门禁失败**\n\nOpenSpec 验证或 Superpowers 测试未通过，请检查本地环境并修复。'
            })

3. 自动化运维：CI 与 AI 深度融合

更进一步，我们可以将 CI 流水线与 AI Agent 结合，形成“自动修复”的闭环。

• 定时检查：通过 GitHub Actions 的 schedule 事件，每周运行 OpenSpec 验证，确保文档与代码同步。
• 自动修复：当 CI 失败时，触发一个 GitHub Actions workflow，该 workflow 会调用 Claude Code 的 CLI 命令，让 AI 自动分析错误日志并尝试修复，然后创建一个新的 Pull Request。

---

🚧 避坑指南与最佳实践

1. 视情况选择模式：模式一（标准交接） 适合大型、复杂特性；模式二（嵌入式） 适合希望简化命令的团队；模式三（轻量级 TDD） 适合中小功能或独立模块。
2. 视情况跳过探索：对于已有清晰 PRD 的需求，可直接 /opsx:propose；对于模糊需求，务必先 /opsx:explore。
3. 使用 CLAUDE.md 固化上下文：将项目规范、技术栈、代码风格等写入 CLAUDE.md，确保 AI 每次会话都能获取相同上下文。
4. 善用 git-worktree 隔离环境：在开发新功能时，使用 git worktree 创建独立工作区，避免污染主分支。
5. 将 SDD 检查作为 PR 的强制门禁：确保每个 PR 都必须通过 OpenSpec 验证和 Superpowers 测试才能合并，从根本上保证主干代码质量。

通过以上三种模式和 CI/CD 集成方案，你可以根据团队和项目的具体情况，灵活地构建起一套高质量、可实践的 SDD 开发工作流。