OpenSpec + Superpowers 搭建 SDD+TDD 工作流教学文档

本教程将指导你从零搭建一套完整的 规范驱动开发（SDD）+ 测试驱动开发（TDD） 工作流，核心工具为 OpenSpec 和 Superpowers。这套组合的核心理念是：OpenSpec 负责决定"构建什么"，Superpowers 负责"如何高效构建它"。

一、前置条件

在开始安装前，请确保你的环境满足以下要求：

条件	要求
Node.js	20.19.0 或更高版本（运行 `node --version` 检查）
AI 编程助手	Claude Code、Cursor、OpenCode、Codex 等（本文以 Claude Code 为例）
Git	已安装并完成基本配置

为什么需要两套工具配合？ 单独使用 OpenSpec 时，/opsx:apply 会直接生成代码，但缺乏 TDD 的红-绿-重构循环和逐任务验证机制。Superpowers 补全了"怎么做"的执行细节------它通过子 Agent 驱动开发、强制测试先行、每任务独立审查，使代码实现既有规格约束又有质量保障。

二、安装步骤

2.1 安装 OpenSpec CLI

bash 复制代码

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

# 验证安装
openspec --version

如果遇到权限问题，需要根据提示使用 sudo 或调整 npm 全局目录配置。

2.2 安装 Superpowers

Superpowers 的安装方式因 AI 工具而异：

Claude Code（推荐方式） ：

bash 复制代码

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

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

Cursor：

bash 复制代码

/add-plugin superpowers

OpenCode：

让 OpenCode 执行：

ruby 复制代码

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

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

2.3 安装桥梁包（openspec-superpowers）

桥梁包的作用是将 OpenSpec 的规划产出与 Superpowers 的执行能力串联起来。它会在 OpenSpec 的 propose 和 archive 之间插入 write-plan 和 executing-plans 两个阶段。

bash 复制代码

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

这一步会自动检测项目中的 AI 工具目录（如 .claude/），并将桥接技能部署到正确位置。

三、项目初始化

3.1 初始化 OpenSpec

bash 复制代码

# 进入你的项目目录
cd your-project

# 初始化 OpenSpec（选择你使用的 AI 工具）
openspec init --tools claude

初始化后生成的目录结构：

bash 复制代码

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

3.2 使用 superspec 快速搭建（推荐）

社区提供了 superspec 工具，可一键完成 OpenSpec + Superpowers 的集成配置：

bash 复制代码

npx @sbswang2002/superspec init --tools claude

该命令会：

将 superpowers-driven schema 复制到 openspec/schemas/ 目录
安装 opsx 斜杠命令到 .claude/commands/opsx
生成 openspec/config.yaml 配置文件

3.3 配置 config.yaml

安装完成后，编辑 openspec/config.yaml，填入项目信息：

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 字段会注入到每个 artifact 的生成提示词中，信息越详细，AI 生成的规格文档越精准。

四、工作流详解

4.1 完整流程概览

安装完成后，SDD+TDD 工作流包含以下阶段：

bash 复制代码

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

4.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-* 命令无冲突。

4.3 关键机制：TDD 原子化任务

在配置了 TDD Schema 后，tasks.md 中的每个任务会被拆解为原子化的 TDD 步骤：

markdown 复制代码

## 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 必须严格交替。

五、实战示例：从需求到交付

以下用"给 Todo API 添加任务优先级功能"完整走一遍流程。

Step 1：需求探索

在 AI 对话中输入：

bash 复制代码

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

AI 会通过提问澄清需求：优先级如何排序？是否影响列表排序？是否需要筛选接口？

Step 2：生成规格文档

需求清晰后，执行：

bash 复制代码

/opsx:propose add-todo-priority

AI 会依次生成 5 个 artifact（约 2-3 分钟）：

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

人工审查要点：

proposal.md：WHEN/THEN 是否覆盖所有可测试行为？
design.md：测试文件路径是否正确？
tasks.md（最关键）：每个 - [ ] 是否只包含一个 TDD 阶段？RED 和 GREEN 是否交替？

Step 3：生成 TDD 执行计划

arduino 复制代码

/opsx:write-plan add-todo-priority

此命令会将 tasks.md 中的粗粒度任务拆解为可执行的 TDD 微步骤，写入 docs/superpowers/plans/ 目录。如果任务数超过 --max-tasks 的默认值 10，会拆分为多个计划文件并请求确认。

Step 4：执行 TDD 开发

bash 复制代码

/opsx:executing-plans add-todo-priority

AI 会按以下模式执行：

arduino 复制代码

子 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：归档

所有任务完成后：

bash 复制代码

/opsx:archive add-todo-priority

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

六、常用命令速查

OpenSpec CLI 命令

bash 复制代码

# 查看版本
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

AI 斜杠命令

bash 复制代码

# 需求探索
/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]

常见调试场景

场景	命令/操作
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 字段信息不足。

解决：补充技术栈、目录结构、测试框架等信息后重新执行。

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/ 目录下存在桥接技能文件。