团队AI开发进阶利器：超能力+OpenSpec实战指南

AI 编程进阶：OpenSpec + Superpowers 组合方案深度使用教程

你有没有遇到过这种局面：需求写得挺清楚，AI也很努力，但产出还是"看起来能跑、实际不敢上线"？或者相反：代码写得飞快，但回头一看，没人说得清"为什么要这么做、做到什么程度算完成"？

这不是AI能力不够，而是你的AI开发流程还停留在"凭感觉推进"的阶段。今天要给大家介绍的OpenSpec + Superpowers组合，目标不是"更酷"，而是更稳：把AI开发从"黑盒魔法"拉回到可追溯、可验证、可复用的工程流水线上。

本文是我经过三次迭代、踩过无数坑后总结的实战指南，从核心概念到完整工作流，从最佳实践到踩坑修复，看完就能直接上手。

痛点一：需求定义模糊，AI自由发挥

• 你说"做个登录功能"，AI给你做了第三方登录、双因素认证，唯独没做你要的邮箱密码登录
• 代码"看起来都对"，但和实际需求差了十万八千里
• 返工率高达50%以上，改代码的时间比自己写还长

痛点二：执行过程失控，质量无法保证

• AI跳过测试直接写实现，上线后bug满天飞
• 没有代码审查，代码风格混乱，难以维护
• 变更没有记录，出了问题不知道是谁改的、为什么改

单独用OpenSpec：能把需求管得很清楚——proposal、design、specs、tasks一条龙生成。但到执行阶段，OpenSpec的apply只是逐个勾选task，没有TDD强制，没有子代理隔离，也没有自动审查。AI一步完成整个功能是完全合理的，因为一个task可能就包含了RED+GREEN混合内容。

单独用Superpowers：TDD纪律很严——RED-GREEN-REFACTOR强制循环，子代理隔离执行，两阶段自动审查。但Superpowers没有spec管理，没有变更追溯，需求全靠对话，换个会话就忘了。

1.3 组合的核心价值

一句话总结：OpenSpec解决"做什么/做到什么程度算完成"，Superpowers解决"怎么稳稳做完并保证质量"，两者组合把返工率与偏离风险压到最低。

痛点

OpenSpec方案

Superpowers方案

组合效果

需求不明确

✅ 结构化规格文档

❌ 无专门机制

✅ 规格驱动

AI偏离需求

✅ 变更追溯

✅ 两阶段审查

✅ 双重保障

代码质量差

⚠️ 行为验证

✅ TDD强制

✅ 测试覆盖

上下文混乱

✅ 变更隔离

✅ Git Worktree

✅ 完全隔离

返工率高

✅ 先设计后实现

✅ 先测试后实现

✅ 一次做对

二、核心概念快速入门2.1 OpenSpec是什么？

定位：轻量级规格驱动的变更管理框架核心思想：不依赖prompt约束AI的行为，而是用结构化规格约束要构建什么这件事本身。

核心工作流：

explore（探索）→ propose（提案）→ design（设计）→specs（规格）→ tasks（任务）→ apply（实现）→verify（验证）→ archive（归档）

核心产物：

openspec/├── changes/│   ├── /│   │   ├── proposal.md      # 为什么做│   │   ├── design.md        # 怎么做│   │   ├── specs/           # 做成什么样│   │   │   └── /│   │   │       └── spec.md│   │   └── tasks.md         # 分几步做│   └── archive/             # 已归档变更└── specs/                   # 主规格库

核心命令：

• /opsx:explore "想法"：探索模式，澄清需求边界
• /opsx:propose "需求"：创建提案，生成所有artifacts
• /opsx:ff "需求"：快速通道，一次性生成所有文件
• /opsx:apply：开始实现
• /opsx:verify：验证实现是否符合规格
• /opsx:archive：归档变更，更新主规格库

定位：多代理协作的完整开发工作流核心思想：用精心设计的markdown技能文件注入到LLM上下文，强制agent走标准化流程。

核心工作流：

brainstorming（头脑风暴）→using-git-worktrees（Git隔离）→writing-plans（任务规划）→subagent-driven-dev（子代理开发）→finishing-branch（收尾）

核心Skills：

Skill

职责

核心规则

brainstorming

苏格拉底式提问，输出设计文档

不提问不设计

using-git-worktrees

创建隔离工作空间

每个变更独立 worktree

writing-plans

拆分为 2-5 分钟小任务

任务必须 bite-sized

subagent-driven-dev

派遣独立子代理实现

上下文隔离

test-driven-development

强制 TDD 流程

先写测试再写实现

requesting-code-review

两阶段代码审查

Spec 合规→代码质量

verification-before-completion

验证前置

提供证据才能声明完成

2.3 为什么需要组合？

两者的互补关系非常清晰，一个管"定义质量"，一个管"执行质量"：

维度

OpenSpec

Superpowers

组合效果

规格管理

✅ 强（增量规格）

❌ 弱

✅ 强

行为约束

❌ 弱

✅ 强（TDD）

✅ 强

变更追溯

✅ 强（归档）

❌ 弱

✅ 强

代码质量

⚠️ 中

✅ 强（审查）

✅ 强

上下文隔离

⚠️ 中

✅ 强（Worktree）

✅ 强

终止条件

✅ 验证门禁

❌ 缺失

✅ 双重保障

三、OpenSpec + Superpowers协同工作流

下面是完整的协同工作流程图，清晰展示了两者如何配合：

四、安装与配置（10分钟搞定）4.1 系统要求

组件

要求

检查命令

Node.js

≥ 20.19.0

node --version

npm

≥ 9.0

npm --version

Git

≥ 2.30

git --version

AI工具

Claude Code / Codex / Cursor

4.2 安装OpenSpec

# 全局安装OpenSpecnpm install -g @fission-ai/openspec@latest# 验证安装openspec --version# 查看可用命令openspec --help

方式一：使用npx skills工具（推荐）

# 安装skills工具npm install -g @vercel-labs/skills# 搜索Superpowersnpx skills find superpowers# 安装Superpowersnpx skills add obra/superpowers# 验证安装npx skills list

方式二：手动安装

# 克隆Superpowers仓库git clone https://github.com/obra/superpowers.git ~/.claude/superpowers# 创建符号链接（Claude Code）ln -s ~/.claude/superpowers/skills ~/.claude/skills/superpowers

# 步骤1：创建项目目录mkdir my-awesome-projectcd my-awesome-project# 初始化Gitgit init# 步骤2：初始化OpenSpecopenspec init# 配置profile（选择完整工作流）openspec config profile# 更新agent指令openspec update# 步骤3：配置Superpowers# 在项目目录创建.claude目录mkdir -p .claude# 选择核心Skills（不要全量加载）npx skills add obra/superpowers# 步骤4：验证配置# 检查OpenSpec配置openspec status# 检查Superpowers Skillsnpx skills list

下面我们通过一个真实的"用户认证功能"案例，完整走一遍整个流程。

5.1 阶段一：规格定义（OpenSpec）

步骤1：探索需求在Claude Code中输入：

/opsx:explore "添加用户登录功能，支持邮箱和密码，需要JWT认证"

输出示例：

## 探索报告### 核心需求- 用户注册/登录- 邮箱 + 密码认证- JWT Token管理### 技术考虑- 密码加密（bcrypt）- Token过期处理- 刷新Token机制### 影响范围- 后端：用户认证模块- 前端：登录/注册页面- 数据库：users表

步骤2：创建提案使用快速通道一次性生成所有artifacts：

/opsx:ff "添加用户登录功能，支持邮箱和密码，需要JWT认证"

生成的文件结构：

openspec/changes/user-auth/├── proposal.md          # 变更提案├── design.md            # 设计决策├── specs/│   └── user-auth/│       └── spec.md      # 需求规格└── tasks.md             # 任务清单

步骤3：审查规格这是最关键的一步，花5分钟仔细审查以下文件：

proposal.md示例：

# 变更提案：用户认证模块## 为什么做- 当前系统无用户认证机制- 需要保护敏感数据和功能## 目标- ✅ 实现邮箱 + 密码注册/登录- ✅ JWT Token认证- ✅ Token刷新机制## 非目标- ❌ 第三方登录（Google/GitHub）- ❌ 双因素认证（2FA）- ❌ 密码找回功能## 影响范围- 新增：UserController, AuthService, JWT中间件- 修改：路由配置，数据库schema

tasks.md示例：

# 任务清单## Phase 1: 后端基础- [ ] 1.1 创建User模型（email, password_hash）- [ ] 1.2 实现密码加密（bcrypt）- [ ] 1.3 创建JWT工具类- [ ] 1.4 实现注册接口POST /api/auth/register- [ ] 1.5 实现登录接口POST /api/auth/login## Phase 2: 前端界面- [ ] 2.1 创建登录页面组件- [ ] 2.2 创建注册页面组件- [ ] 2.3 实现表单验证- [ ] 2.4 集成认证API## Phase 3: 测试与文档- [ ] 3.1 编写单元测试- [ ] 3.2 编写集成测试- [ ] 3.3 更新API文档

步骤4：启动Superpowers工作流在Claude Code中输入：

开始实现用户认证功能

AI会自动响应：

 检测到开发任务，启动Superpowers工作流...1. ✅ Planning技能：加载OpenSpec tasks.md2. ✅ Git Worktree技能：创建隔离分支3. ✅ TDD技能：准备测试框架

步骤5：Git Worktree隔离Superpowers会自动执行：

git worktree add ../my-awesome-project-feature-user-auth -b feature/user-authcd ../my-awesome-project-feature-user-auth

为什么需要Worktree？

• ✅ 每个任务独立工作空间
• ✅ 避免上下文污染
• ✅ 可以并行开发多个功能
• ✅ 基线验证（确保编译通过）

步骤6：TDD流程（核心）这是保证代码质量的关键，Superpowers会严格遵循RED-GREEN-REFACTOR循环：

Step 1: RED（写失败测试）

// auth.test.jsdescribe('AuthService', () => {it('should register user with valid email and password', async () => {const user = await authService.register('test@example.com', 'password123');expect(user.email).toBe('test@example.com');expect(user.password).not.toBe('password123'); // 加密// ❌ 测试失败（因为还没实现）

Step 2: GREEN（写最小实现）

// AuthService.jsclass AuthService {async register(email, password) {const password_hash = await bcrypt.hash(password, 10);return User.create({email,password_hash// ✅ 测试通过

Step 3: REFACTOR（重构优化）

// 添加输入验证// 添加错误处理// 优化代码结构// ✅ 测试仍然通过

步骤7：两阶段代码审查

第一阶段：Spec合规审查

## Spec Review报告### 对照OpenSpec specs/user-auth/spec.md✅ 需求1：邮箱格式验证- 实现：email-validator库- 测试：覆盖有效/无效邮箱✅ 需求2：密码强度要求（≥8字符）- 实现：密码验证中间件- 测试：覆盖边界情况❌ 需求3：Token过期处理- 问题：未实现刷新Token机制- 建议：添加refresh_token字段### 审查结果⚠️ DONE_WITH_CONCERNS- 需要补充刷新Token功能- 建议添加Token黑名单机制

第二阶段：代码质量审查

## Code Quality Review报告### 代码质量✅ 代码规范：符合ESLint规则✅ 命名规范：变量/函数命名清晰✅ 错误处理：try-catch完整### 安全性✅ 密码加密：使用bcrypt✅ SQL注入：使用ORM参数化⚠️ XSS风险：前端需要转义### 测试覆盖✅ 单元测试：15个测试用例✅ 覆盖率：92%⚠️ 边界测试：需要补充### 审查结果✅ APPROVED（Minor问题可后续修复）

步骤8：OpenSpec验证

/opsx:verify

验证报告：

## 验证报告：user-auth### 规格覆盖检查✅ proposal.md目标全部实现✅ design.md技术决策已执行✅ specs/*.md需求全部覆盖✅ tasks.md任务全部完成### 行为验证✅ 编译通过✅ 测试通过（15/15）✅ Lint通过### 验证结果✅ 验证通过，可以归档

步骤9：归档变更

/opsx:archive

归档后结构：

openspec/changes/archive/2026-04-21-user-auth/├── proposal.md├── design.md├── specs/user-auth/spec.md└── tasks.md

步骤10：Git收尾

# 切换回主工作区cd ../my-awesome-project# 删除worktreegit worktree remove ../my-awesome-project-feature-user-auth# 合并功能分支git merge feature/user-auth# 或者创建PRgh pr create --title "feat: 添加用户认证功能" \--body "实现邮箱 + 密码认证，JWT Token管理"

不要全量加载14个Skills！推荐组合（5个核心Skills）：

{"always_active": ["test-driven-development",        // TDD强制"verification-before-completion"  // 验证前置],"on_demand": ["writing-plans",                   // 任务拆分"requesting-code-review",          // 代码审查"systematic-debugging"             // 系统调试],"optional": ["brainstorming",                   // 复杂需求时使用"using-git-worktrees"              // 大型项目使用

Token消耗对比： | 组合 | Token消耗 | 适用场景 | |------|-----------|----------| | 全量14 Skills | ~50K tokens | ❌ 不推荐 | | 5核心Skills | ~15K tokens | ✅ 推荐 | | 3最小Skills | ~8K tokens | ⚠️ 基础保障 |

6.2 变更管理策略

小型变更（<1天）：

# 使用OpenSpec快速通道/opsx:ff "修复登录接口密码验证bug"# 使用Superpowers简化流程# - TDD（必选）# - Verification（必选）

中型变更（1-3天）：

# 使用OpenSpec完整流程/opsx:propose "添加用户个人资料功能"# 使用Superpowers标准流程# - Planning# - TDD# - Code Review# - Verification

大型变更（>3天）：

# 使用OpenSpec多变更管理/opsx:propose "用户系统重构"# 拆分为多个子变更# - user-profile（个人资料）# - user-settings（用户设置）# - user-notifications（通知系统）# 使用Superpowers完整流程# - Brainstorming# - Git Worktree# - Planning# - TDD# - Code Review# - Verification

很多"组合方案"教程只写顺风局，但你真正需要的是：出问题时能把项目拉回正轨。下面5个场景，是团队里最常见、也最容易导致返工的卡点。

场景1：Specs写得很全，但Implementer还是偏离需求

症状：

• 代码"看起来都对"，但和specs/*.md的约束对不上（字段、边界、非目标被顺手做了）
• PR里出现"顺便加了个功能/顺便改了个结构"

高频原因：

• tasks.md只有"做什么"，缺少"做到什么算完成"（DoD）
• 实现阶段一次性加载太多上下文，注意力漂移

修复步骤：

1. 回到tasks.md：给每个任务补1行DoD（Definition of Done）（状态码/错误分支/测试覆盖点/日志）
2. Implementer只做"减法"：把非目标移出本变更（写进后续任务或明确不做）
3. Spec Reviewer用"对照打勾"方式审：只判定是否满足specs + DoD

防复发：

• 把proposal.md的"非目标"同步到tasks.md顶部，作为实现阶段护栏

场景2：TDD卡住（写不出合理测试，或测试很脆弱）

症状：

• 红灯阶段写不出一个合理的失败测试
• 测试依赖DB/网络，跑不稳定，大家开始想"先把功能做了再补"

高频原因：

• 一个任务包含多个行为，测试无法聚焦
• 依赖未隔离（缺接口/可替换实现），很难mock

修复步骤：

1. 把任务拆到2–5分钟粒度：一条测试只覆盖一个行为
2. 先写"纯校验/纯映射"测试（参数校验、状态机、DTO mapping），再写I/O
3. 对DB/网络：先做"内存实现 + 契约测试"，最后再换真实实现

防复发：

• 在tasks.md每个任务里写明：1个失败用例 + 1个边界用例

场景3：Worktree管不住（目录/分支混乱、改错地方）

症状：

• 同一个变更出现多个worktree；或在错误worktree上改代码
• 合并时发现漏文件/漏commit

高频原因：

• worktree命名缺少映射规则，无法"一眼看懂"

修复步骤：

1. 约定命名：../-- 或 ../-feature-xxx
2. 每次开工先git worktree list，确认路径↔分支
3. 只保留≤3个活跃worktree：完成一个就删一个

防复发：

• 在变更任务清单顶部写清楚：worktree路径 + 分支名

场景4：verify不通过（测试挂了 / lint挂了 / 行为没覆盖）

症状：

• 验证报告提示某些任务未覆盖，或测试/构建失败

高频原因：

• 把验证当成"最后一步"，导致失败集中爆雷

修复步骤：

1. 把失败项映射回tasks.md：属于哪个任务的DoD没满足
2. 先修"便宜失败"（lint/类型/单测），再修系统性失败（集成/架构）
3. 修复后补1条"回归测试点"，避免同类问题复发

防复发：

• 每完成2–3个小任务就做一次快速验证，不要堆到最后

场景5：Spec Reviewer与Code Reviewer意见冲突，推进停滞

症状：

• 一个说"满足规格就行"，另一个说"结构不行要重构"

高频原因：

• 审查标准没分层：规格合规 vs 代码质量混在一起

修复步骤：

1. 先过规格：只讨论"是否满足specs + DoD"
2. 再过质量：限定重构边界（不改行为、不改外部接口）
3. 若确需大改：回到design.md补一条决策记录，减少口头争论成本

防复发：

• 固定两阶段审查输出：Spec只给"缺口清单"，Quality只给"风险清单"

Q1: 技能没有自动触发？

原因：

• Skills配置路径不正确
• 触发关键词不匹配

解决方案：

# 检查Skills路径ls -la ~/.claude/skills/# 重新安装Superpowersnpx skills remove superpowersnpx skills add obra/superpowers# 手动触发技能/skill:using-superpowers

Q2: OpenSpec与Superpowers规则冲突？

场景：

• OpenSpec tasks.md说"跳过测试"
• Superpowers TDD技能说"必须写测试"

解决方案：优先级规则：用户指令 > 技能规则 > 项目默认行为

# 明确指定优先级用户："这次变更不需要TDD，直接实现"→ 遵循用户指令# 或者修改技能配置// .claude/skills/tdd-config.json"enabled": true,"exceptions": ["hotfix", "typo-fix"]

Q3: Worktree太多如何管理？

解决方案：

# 列出所有worktreegit worktree list# 清理已完成的worktreegit worktree remove ../project-feature-agit worktree prune# 设置worktree上限（建议≤3）# 在.gitconfig中[worktree]maxCount = 3

Q4: 如何衡量组合方案的效果？

指标体系： | 指标 | 测量方式 | 目标值 | |------|----------|--------| | 需求覆盖率 | specs条目 vs 实现功能 | ≥95% | | 测试覆盖率 | 单元测试覆盖率报告 | ≥80% | | 返工率 | 返工任务数 / 总任务数 | <20% | | 代码审查通过率 | 一次通过审查的任务比例 | ≥70% | | 变更归档率 | 已归档变更 / 总变更 | 100% |

八、总结与行动建议8.1 核心要点

1. 分工明确：OpenSpec管规格，Superpowers管执行
2. 按需加载：不要全量加载Skills，选择5个核心即可
3. TDD强制：这是Superpowers的核心价值，不要跳过
4. 变更追溯：每次变更都要归档，形成知识库
5. 持续优化：根据项目反馈调整Skills组合

# 1. 安装OpenSpecnpm install -g @fission-ai/openspec@latest# 2. 安装Superpowersnpx skills add obra/superpowers# 3. 创建测试项目mkdir test-combo && cd test-comboopenspec init# 4. 尝试第一个变更/opsx:ff "添加Hello World功能"

AI编程的质量问题，本质上是两件事：定义不清楚和执行不到位。Superpowers把执行流程做到了极致，OpenSpec把定义质量做到了程序化。两个工具的组合逻辑很简单：OpenSpec用硬约束定义清楚做什么，Superpowers用结构化流程确保怎么做。

如果你也在为AI生成的代码质量不稳定而烦恼，不妨试试这个组合方案。它可能不是最快的，但一定是最稳的。