OpenSpec+Superpowers实战：AI驱动SDD+TDD完整开发工作流

文章目录

• 一、先聊聊这俩工具到底是干嘛的
• 二、开工前的准备工作
• • [2.1 环境要求](#2.1 环境要求)
  • [2.2 为什么非得两个一起用](#2.2 为什么非得两个一起用)
• 三、安装三步走
• • [3.1 装 OpenSpec CLI](#3.1 装 OpenSpec CLI)
  • [3.2 装 Superpowers](#3.2 装 Superpowers)
  • [3.3 装桥梁包 openspec-superpowers](#3.3 装桥梁包 openspec-superpowers)
• 四、项目初始化
• • [4.1 初始化 OpenSpec](#4.1 初始化 OpenSpec)
  • [4.2 用 superspec 一键搞定（推荐）](#4.2 用 superspec 一键搞定（推荐）)
  • [4.3 配置 config.yaml](#4.3 配置 config.yaml)
• 五、工作流到底怎么跑
• • [5.1 完整流程一览](#5.1 完整流程一览)
  • [5.2 每个命令干啥的](#5.2 每个命令干啥的)
  • [5.3 核心机制：TDD 原子化任务](#5.3 核心机制：TDD 原子化任务)
• [六、实战走一遍：给 Todo API 加优先级](#六、实战走一遍：给 Todo API 加优先级)
• • [Step 1：需求探索](#Step 1：需求探索)
  • [Step 2：生成规格文档](#Step 2：生成规格文档)
  • [Step 3：生成 TDD 执行计划](#Step 3：生成 TDD 执行计划)
  • [Step 4：执行 TDD 开发](#Step 4：执行 TDD 开发)
  • [Step 5：归档](#Step 5：归档)
• 七、常用命令速查
• • [7.1 OpenSpec CLI 命令](#7.1 OpenSpec CLI 命令)
  • [7.2 AI 斜杠命令](#7.2 AI 斜杠命令)
  • [7.3 常见调试场景](#7.3 常见调试场景)
• 八、踩坑记录
• • • [Q1：/opsx:propose 生成的内容不准](#Q1：/opsx:propose 生成的内容不准)
    • [Q2：tasks.md 里出现 RED+GREEN 合并任务](#Q2：tasks.md 里出现 RED+GREEN 合并任务)
    • [Q3：执行 /opsx:executing-plans 报上下文过长](#Q3：执行 /opsx:executing-plans 报上下文过长)
    • [Q4：Superpowers 技能没自动触发](#Q4：Superpowers 技能没自动触发)

P.S. 推荐一个大神的教程给想要了解或者学习人工智能知识的读者，这个教程里内容讲解通俗易懂且风趣幽默，对我帮助很大。我想与大家分享这个宝藏教程，请点击下方链接查看，传送门https://blog.csdn.net/qq_74013365

一、先聊聊这俩工具到底是干嘛的

最近折腾了一套开发流程，用 OpenSpec 加 Superpowers 搭了个 SDD+TDD 的组合拳。说实话，一开始我也觉得这名字起得花里胡哨的，SDD、TDD，听着像某种神秘组织的暗号。

但用下来发现，这俩配合起来还真有点东西。简单说就是：OpenSpec 管"做什么"，Superpowers 管"怎么做"。一个画饼，一个烙饼，分工明确。

以前写代码什么状态？需求来了直接上手，写着写着发现理解错了，推倒重来。测试？那是上线前加班补的东西。现在这套流程逼你先想清楚再动手，虽然前期慢一点，但后期少踩坑。

二、开工前的准备工作

2.1 环境要求

先确认你的机器满足这些条件，不然后面报错报得你怀疑人生：

条件	要求
Node.js	20.19.0 或更高版本，跑 node --version 查一下
AI 编程助手	Claude Code、Cursor、OpenCode、Codex 都行，本文以 Claude Code 为例
Git	装了就行，别问为什么，问就是版本控制是底线

2.2 为什么非得两个一起用

有人可能问了，我用一个不行吗？还真不行。

单独用 OpenSpec 的话，/opsx:apply 直接给你生成代码，快是快，但没有 TDD 那套红绿重构的循环，也没有逐任务验证。就像做饭不尝咸淡，端上桌才发现盐放多了。

Superpowers 补上了执行这一环。它用子 Agent 驱动开发，强制测试先行，每个任务独立审查。代码既有规格约束，又有质量保障，双保险。

三、安装三步走

3.1 装 OpenSpec CLI

先全局安装 OpenSpec：

# 全局安装 OpenSpec
npm install -g @fission-ai/openspec@latest

# 验证安装
openspec --version

如果碰到权限问题，该用 sudo 用 sudo，该调 npm 全局目录就调，别硬刚。

3.2 装 Superpowers

这一步要看你用的是哪个 AI 工具，不同工具装法不一样，跟点菜似的，各取所需。

Claude Code（推荐）：

# 方式一：官方市场安装
/plugin install superpowers@claude-plugins-official

# 方式二：通过 Superpowers 市场安装
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

Cursor：

/add-plugin superpowers

OpenCode：

让 OpenCode 执行这条：

Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md

**Codex CLI：**打开插件搜索界面 /plugins，搜 superpowers 安装就行。

3.3 装桥梁包 openspec-superpowers

这步很关键。桥梁包干的事就是把 OpenSpec 的规划和 Superpowers 的执行串起来。它会在 propose 和 archive 之间插入 write-plan 和 executing-plans 两个阶段，相当于给两个工具牵了根线。

# 在项目根目录执行
npx openspec-superpowers

它会自动检测项目里的 AI 工具目录，比如 .claude/，然后把桥接技能部署到正确位置。省心。

四、项目初始化

4.1 初始化 OpenSpec

进到你的项目目录，执行初始化：

# 进入项目目录
cd your-project

# 初始化 OpenSpec，选你用的 AI 工具
openspec init --tools claude

初始化完目录结构长这样：

your-project/
├── openspec/
│   ├── changes/    # 进行中的变更
│   ├── specs/      # 已归档的规范，真相来源
│   └── config.yaml # 项目配置
└── .claude/
    └── commands/opsx/ # OpenSpec 斜杠命令

4.2 用 superspec 一键搞定（推荐）

社区有个 superspec 工具，能一键完成 OpenSpec + Superpowers 的集成配置，懒人福音：

npx @sbswang2002/superspec init --tools claude

这条命令会帮你干三件事：把 superpowers-driven schema 复制到 openspec/schemas/，装 opsx 斜杠命令到 .claude/commands/opsx，生成 openspec/config.yaml 配置文件。一条龙服务。

4.3 配置 config.yaml

装完之后编辑 openspec/config.yaml，把项目信息填进去：

project:
  test_commands: ["npm test"]       # 测试命令
  e2e_command: "npm run e2e"        # E2E 测试命令，可选
  custom_verification_checks: []     # 自定义检查
  context: |
    本项目是一个 [描述你的技术栈] 应用，使用 [语言/框架] 开发。
    采用 TypeScript + Jest 进行测试，遵循 TDD 开发流程。
    目录结构：src/ 存放源码，tests/ 存放测试文件。
  rules:
    tasks: |
      - 每个任务必须只包含一个 TDD 阶段（RED、GREEN 或 REFACTOR）
      - RED 和 GREEN 任务必须严格交替

这里 context 字段会注入到每个生成提示词里，信息越详细，AI 生成的规格越准。别偷懒随便写两句，后面生成出来的东西质量天差地别。

五、工作流到底怎么跑

5.1 完整流程一览

装好之后，整个 SDD+TDD 工作流是这样的：

/opsx:explore → /opsx:propose → /opsx:write-plan → /opsx:executing-plans → /opsx:archive
  探索需求       生成规格        制定TDD计划        执行TDD开发          归档变更

五步走，从需求到归档，每一步都有明确的输入输出。比以前"想到哪写到哪"强太多了。

5.2 每个命令干啥的

命令	功能	输出
/opsx:explore	需求探索，AI 提问澄清模糊需求	对话记录、决策要点
/opsx:propose	一键生成 proposal、design、specs、tasks	4 个 artifact 文件
/opsx:write-plan	把 tasks 转成可执行的 TDD 计划	plan.md，含 RED-GREEN 步骤
/opsx:executing-plans	逐任务执行 TDD 开发	代码变更 + 测试通过
/opsx:archive	归档变更，合并规范到主库	更新后的 specs/

注意，OpenSpec 原生命令以 opsx: 为前缀，跟官方 openspec-* 命令不冲突，放心用。

5.3 核心机制：TDD 原子化任务

配置了 TDD Schema 之后，tasks.md 里每个任务会被拆成原子化的 TDD 步骤，长这样：

## 2. 标题解析功能
- [ ] 2.1 RED --- 写失败测试
  - 测试文件: tests/parser.test.ts
  - 断言: markdownToHtml("# Hello") 返回 "<h1>Hello</h1>"
  - 预期失败: 函数尚未实现

- [ ] 2.2 GREEN --- 最小实现
  - 通过测试: 2.1
  - 实现代码: 添加 heading 正则匹配逻辑

- [ ] 2.3 REFACTOR --- 重构（可选）
  - 优化代码结构，保持测试通过

验证点就一个：每个 task 只能有一个 TDD 阶段，RED 和 GREEN 必须严格交替。别让 AI 偷懒把两个阶段合并成一个，那 TDD 就名存实亡了。

六、实战走一遍：给 Todo API 加优先级

光说不练假把式，拿"给 Todo API 添加任务优先级功能"完整走一遍，支持 high/medium/low 三个级别。

Step 1：需求探索

在 AI 对话里输入：

/opsx:explore 给 Todo API 添加任务优先级功能，支持 high/medium/low 三个级别

AI 会开始追问你：优先级怎么排序？影不影响列表排序？要不要筛选接口？这时候别嫌烦，回答得越细，后面生成的规格越靠谱。

Step 2：生成规格文档

需求聊清楚了，执行：

/opsx:propose add-todo-priority

AI 会依次生成 5 个 artifact，大概 2 到 3 分钟：

1. proposal.md --- 变更动机加可测试行为列表，WHEN/THEN 格式
2. specs/todo-api/spec.md --- 行为规格，GIVEN/WHEN/THEN 场景
3. design.md --- 技术设计，文件结构加测试策略
4. tasks.md --- 原子化 TDD 任务列表，RED 到 GREEN 交替
5. plan.md --- 执行计划，每步映射到具体任务

人工审查重点：

proposal.md 看 WHEN/THEN 有没有覆盖所有可测试行为。design.md 看测试文件路径对不对。最关键的是 tasks.md，每个 - 是不是只包含一个 TDD 阶段，RED 和 GREEN 交不交替。这步不审，后面执行全乱套。

Step 3：生成 TDD 执行计划

/opsx:write-plan add-todo-priority

这条命令把 tasks.md 里的粗粒度任务拆成可执行的 TDD 微步骤，写到 docs/superpowers/plans/ 目录。如果任务数超过 --max-tasks 默认值 10，会拆成多个计划文件并请求确认。

Step 4：执行 TDD 开发

/opsx:executing-plans add-todo-priority

AI 按这个模式跑：

子 Agent 1：执行 Task 1（RED）
  → 写失败测试 → 确认测试失败
子 Agent 2：执行 Task 2（GREEN）
  → 写最小代码 → 确认测试通过 → 提交
子 Agent 3：执行 Task 3（RED）
  → ...

每个子 Agent 独立运行、独立审查，完成后自动同步进度到 tasks.md。一个 OpenSpec task 只有在所有映射的 plan task 都完成后才会标记为 x。

执行模式有两种：

Subagent-Driven 是推荐模式，每个任务派一个独立子 Agent 加两阶段审查，规格合规性和代码质量都查。Inline Execution 是批量执行加人工检查点，适合简单任务。

Step 5：归档

所有任务跑完之后：

/opsx:archive add-todo-priority

变更移到 changes/archive/，增量规范合并到主规范 specs/。收工。

七、常用命令速查

7.1 OpenSpec CLI 命令

# 查看版本
openspec --version

# 列出所有进行中的变更
openspec list

# 查看某个变更的详细信息
openspec show add-todo-priority

# 验证变更的文档结构
openspec validate add-todo-priority

# 查看 schema 列表
openspec schemas

# 调试：查看 AI 收到的 instruction
openspec instructions tasks --change add-todo-priority --json

7.2 AI 斜杠命令

# 需求探索
/opsx:explore [需求描述]

# 生成全部规格文档
/opsx:propose [change-name]

# 生成 TDD 执行计划
/opsx:write-plan [--max-tasks N] [change-name]

# 执行 TDD 开发
/opsx:executing-plans [change-name]

# 归档变更
/opsx:archive [change-name]

7.3 常见调试场景

场景	命令/操作
tasks.md 生成不理想	openspec instructions tasks --change <name> --json 看 AI 收到的指令
验证 Schema 配置	openspec schema validate tdd-driven-v2
检查上下文占用	/acp context，需装 opencode-acp 插件

八、踩坑记录

Q1：/opsx:propose 生成的内容不准

大概率是 config.yaml 的 context 字段写得太敷衍。把技术栈、目录结构、测试框架这些信息补全了再重新跑。别指望 AI 猜你的项目结构，它又不是你肚子里的蛔虫。

Q2：tasks.md 里出现 RED+GREEN 合并任务

AI 偷懒了，没遵循原子化约束。在 config.yaml 的 rules.tasks 里明确写死约束，或者手动拆开再继续。这种事不能惯着，有第一次就有第二次。

Q3：执行 /opsx:executing-plans 报上下文过长

OpenCode 默认上下文窗口有限，任务多了就撑爆。装个 opencode-acp 插件做动态上下文剪枝，或者在 opencode.json 里配 experimental.disableAutoCompact: true。

Q4：Superpowers 技能没自动触发

桥梁包没装对。重新执行 npx openspec-superpowers，确认 .claude/skills/ 目录下有桥接技能文件。有时候就是差这一步，卡你半天。

以上就是这套 SDD+TDD 工作流的完整玩法。刚开始用可能觉得流程繁琐，五步走比直接写代码慢多了。但等项目大了、需求变了、人多了，你会发现前期花在规格和测试上的时间，后期全给你省回来。代码这东西，慢就是快。

P.S. 推荐一个大神的教程给想要了解或者学习人工智能知识的读者，这个教程里内容讲解通俗易懂且风趣幽默，对我帮助很大。我想与大家分享这个宝藏教程，请点击下方链接查看，传送门https://blog.csdn.net/qq_74013365