OpenSpec+Superpowers协同

前言

在我们对OpenSpec和Superpowers都有了初步的认识后，可能会产生一个疑问：这两个工作流，不都是先明确，再执行，有什么本质的区别吗？

简单来说，这两个工作流，在定位上，有以下几点区别

• **OpenSpec (做规划的总设计师)**：它负责制定开发规范和蓝图，解决“做什么”的问题，产出结构化的需求文档和任务清单
• **Superpowers (守纪律的执行官)**：它负责将蓝图转化为工程实践，解决“怎么做”的问题，通过强制 TDD（测试驱动开发）、头脑风暴、代码审查等技能，确保每一步都符合工程标准

特性	🔍 OpenSpec (做规划)	🚀 Superpowers (保执行)
核心定位	做规划的总设计师	守纪律的执行官
解决的问题	“做什么”	“怎么做”
核心能力	制定规范和蓝图，确保需求对齐与变更可追溯	确保工程纪律与执行质量，强制TDD、头脑风暴等
核心产出	proposal.md, design.md, tasks.md 等结构化文档	可执行的、细分的工作步骤，以及符合规范的最终代码
工作流程	提案 → 实施 → 归档	头脑风暴 → 写计划 → 子代理执行 → 验证/归档

OpenSpec武器库

命令	功能说明
/opsx:apply	应用一个已批准的变更，开始按照 tasks.md 中的任务清单实施代码。这是从规范到代码的“施工”阶段。
/opsx:archive	归档一个已完成的变更：将 proposal.md、design.md、tasks.md 以及增量规范（Delta Specs）移动到 changes/archive/，并更新主规范（specs/ 目录）。
/opsx:bulk-archive	批量归档多个已完成的变更，适用于一次性清理多个已合并或废弃的提案。
/opsx:continue	继续一个中断的 OpenSpec 工作流。例如，如果你在 propose 过程中退出，可以用该命令从中断处恢复。
/opsx:explore	启动需求探索阶段：分析现有代码、讨论多种方案、理清需求边界。不生成正式规范，适合前期调研。
/opsx:ff	“Fast‑Forward” 的缩写。快速推进一个变更，跳过某些交互式确认步骤，直接使用默认值或上次的选择。适用于有明确标准的重复操作。
/opsx:new	创建一个新的变更（change）。会生成一个变更 ID，并初始化 openspec/changes/<id>/ 目录结构。
/opsx:onboard	新手引导命令。首次使用 OpenSpec 时运行，它会检查环境、创建必要的目录（如 specs/、changes/），并给出快速上手指南。
/opsx:propose	基于 explore 的讨论（或直接输入需求），生成正式的提案文档：proposal.md、design.md、tasks.md 以及 specs/ 下的增量差异文件。
/opsx:sync	同步规范文件。当外部因素（如手动编辑、合并冲突）导致 specs/ 与归档的变更不一致时，用此命令重新对齐。
/opsx:verify	验证当前代码实现是否与 specs/ 中的规范（GIVEN/WHEN/THEN）完全一致。输出差异报告，帮助发现偏离设计的实现。
/opsx:onboard	新手教程

• 核心顺序

/opsx:explore   →   /opsx:new   →   /opsx:propose   →   /opsx:apply   →   /opsx:verify   →   /opsx:archive
     ↑                  ↑               ↑                   ↑                ↑                 ↑
  (可选调研)        (创建变更)       (撰写提案)          (实现代码)        (验证结果)        (归档完成)

而 continue、ff、sync、bulk-archive、onboard 是辅助命令，用于处理中断、快速操作、环境同步和新手配置等场景

在工作流中，它们的顺序是固定的：

1. **❓ 先 /opsx:explore**：当你对要解决什么问题还不完全确定时使用。用它来彻底思考，避免走弯路。
2. **✅ 再 /opsx:new**：当你思考成熟，明确了要做什么后，用它来正式创建一个变更任务，开启实施阶段。

• ⚖️ 选择 /opsx:propose or /opsx:new？

特性	🚀 /opsx:propose (一站式快速路径)	🛠️ /opsx:new (精细化脚手架)
工作流类型	默认快速工作流（Core Profile），旨在提供顺畅的“Aha Moment”体验。	扩展工作流，属于“精细化控制”的一部分。
核心操作	合一：一个命令完成变更目录创建和所有规划文件（proposal, design, tasks等）的生成。	分离：仅负责创建目录结构，但不生成文件内容。
控制粒度	粗粒度：不提供中间环节，一次性产出所有结果。	细粒度：可以让你在每生成一个文件后都进行审查和调整。
适用人群	需求明确、思路清晰、追求效率的开发者。	需求复杂、希望审慎推进、喜欢精细控制的开发者。
扩展可能性	无法中断和干预。	灵活性极高，之后可选择继续生成文件 (/opsx:continue) 或批量生成 (/opsx:ff)。

如果把一个功能实现比作“盖房子”，这两种方式的区别就很形象了。

• 需求明确，即用即走 → 选 /opsx:propose
  它就像一个高效的机器人管家。你只需发出指令，它就能一键完成所有的蓝图设计，直接给出最终方案。最适合在目标明确，需要快速前进的场景。
• 需求模糊，慎重决策 → 选 /opsx:new
  它更像一位协助你、启发你的建筑师。它先帮你搭建起一个分区的办公空间，并引导你逐一填充内容。在每一步完成后，你都可以和AI一起审视、修改，确保大方向正确后再推进下一步，从而充分掌控项目的生命力。

总而言之，这不是一个技术对错之争，而是 “工作效率”与“过程控制”之间的权衡。

• 当你思路清晰、目标明确时，/opsx:propose 能让你快速行动。
• 当事情模糊、需要探索和反复推敲时，先使用 /opsx:new 能帮助你稳妥地思考并构建方案。

OpenSpec流程决策图

• /opsx:explore 完全可选：熟练后可跳过，直接用 propose 或 new。
• /opsx:propose 最省事：适合大多数日常开发。
• /opsx:new 系列：适合需要多次斟酌、或希望严格分步提交 PR 的复杂变更。
• /opsx:verify 不可忽略：它是确保实现与规范一致的最后防线。

Superpowers武器库

• 核心流程技能

技能名	作用
brainstorming	头脑风暴 - 用于任何创意工作前（创建功能、构建组件、添加功能）
writing-plans	编写计划 - 编写多步骤任务的实施计划
executing-plans	执行计划 - 在单独会话中执行实施计划
subagent-driven-development	子代理驱动开发 - 使用独立任务执行实施计划

• 质量保障技能

技能名	作用
test-driven-development	测试驱动开发 - 实现任何功能或修复前先写测试
systematic-debugging	系统化调试 - 遇到 bug 或异常行为时使用
verification-before-completion	完成前验证 - 声称完成前必须通过验证
requesting-code-review	请求代码审查 - 完成任务或重大功能后验证工作

• 特殊场景技能

技能名	作用
receiving-code-review	接收代码审查 - 收到审查反馈时使用
finishing-a-development-branch	完成开发分支 - 实现完成、测试通过后如何整合工作
using-git-worktrees	使用 Git Worktrees - 需要隔离工作空间时使用

• 开发者工具技能

技能名	作用
writing-skills	编写技能 - 创建、编辑或验证新技能

实战

先进入项目目录，执行：openspec init

明确要做什么：OpenSpec

最终生成如下几份文件，如果在OpenSpec流程的话，就直接使用 /opsx:apply，执行了，但现在，我们使用Superpowers来执行

这些文档，我们要一个个都去看一下。看看是否满足我们的要求。

干活：Superpowers

将上一步生成的tasks文件喂给Superpowers，编写执行计划

选择1，开干 此时自动加入 /superpowers:subagent-driven-development（含 TDD）

按照规划，一步步走

收尾：OpenSpec&Superpowers

• 完成后验证：/superpowers:verification-before-completion
• 规范一致性检查：/opsx:verify
  
• 归档并更新主规范：/opsx:archive
  记住这个归档前的目录

核心优势：OpenSpec 负责“做正确的事”（规范、可追溯），Superpowers 负责“正确地做事”（工程纪律、质量保障）。

🔧 其他技能的使用场景（补充说明）

1. systematic-debugging

场景：在 loadConfig() 合并对象时，发现配置中某些字段丢失。
使用：输入 /superpowers:systematic-debugging，AI 会：

• 要求你复现 bug 并提供日志。
• 提出假设（例如：合并逻辑是浅拷贝导致深层字段丢失）。
• 设计实验（写一个最小测试用例）。
• 修复并验证。

效果：避免随机改代码，快速定位根源。

2. using-git-worktrees

场景：你同时需要维护两个分支：一个紧急修复 hotfix，一个开发配置功能。
使用：输入 /superpowers:using-git-worktrees，AI 会：

• 指导你用 git worktree add 创建一个新的工作目录，独立检出 hotfix 分支。
• 在新目录中修改、测试、提交，完全不影响当前 config-management 分支的工作区。
• 完成后删除 worktree。

效果：无需频繁 stash 或切换分支，并行开发无干扰。

3. writing-skills

场景：团队想定制一个“自动生成 API 文档”的技能。
使用：输入 /superpowers:writing-skills，AI 会：

• 引导你描述新技能的目的、输入输出。
• 生成标准的 SKILL.md 文件，包含指令、示例、验证步骤。
• 帮你放置到 ~/.claude/skills/ 目录，并测试新技能。

效果：轻松扩展 Claude 的能力，适配团队特殊流程。

4. finishing-a-development-branch

场景：配置管理功能完成，测试通过，准备合并到 main。
使用：输入 /superpowers:finishing-a-development-branch，AI 会：

• 检查未提交的更改、运行完整的测试套件。
• 提示你更新 CHANGELOG。
• 执行 git checkout main && git merge --no-ff，打 tag（按语义化版本）。
• 删除本地功能分支。

效果：标准化的收尾流程，避免遗漏。

总结

✅ 什么时候必须使用 OpenSpec？

• 多人协作项目：规范是团队的共同语言。
• 长期维护：需要追溯“为什么这么做”。
• 需求频繁变更：OpenSpec 能检测规范冲突。
• 需要交付设计文档：提案和设计文件可直接用于评审。

✅ 什么时候只用 Superpowers 就够了？

• 个人项目或原型开发，不需要长期规范。
• 简单的 bug 修复、微小的功能增强（1-2 个文件改动）。
• 实验性代码，随时可能推翻重写。

⚠️ 常见陷阱与解决方案

陷阱	解决方案
误以为两个工具必须串联所有步骤	灵活裁剪：小需求可跳过 /opsx:explore，直接用 /opsx:propose；超小改动甚至只用 Superpowers 的 subagent-driven-development。
忘记手动衔接 writing-plans 与 tasks.md	养成习惯：/superpowers:writing-plans openspec/changes/.../tasks.md。
using-git-worktrees 自动创建 .worktrees/ 导致困惑	在 CLAUDE.md 中配置全局 worktree 目录，或直接删除该文件夹（不影响主仓库）。
忽略 /opsx:verify 直接归档	务必先 verify，确保代码与规范一致，否则归档后规范会“说谎”。
计划文件 plan.md 被随意丢弃	保留在 openspec/changes/<id>/ 下，与规范一起归档，供日后审计。

• 极简模板

# 如果需求模糊的话，讨论清楚后再 propose
/opsx:explore



# 1. 开始一个变更
/opsx:propose add-user-auth

# 2. 细化计划（将 tasks.md 喂给 Superpowers）
/superpowers:writing-plans openspec/changes/add-user-auth/tasks.md

# 3. 执行开发
/superpowers:subagent-driven-development

# 4. 验证
/opsx:verify add-user-auth

# 5. 归档
/opsx:archive add-user-auth

OpenSpec 把需求变成可追溯的蓝图，Superpowers 按蓝图施工并确保工程质量。两者结合 = 规范驱动的高质量交付。

这套流程特别适合中大型项目、团队协作、需要长期维护的场景。对于个人小项目，你完全可以只用 Superpowers 快速迭代；而对于企业级应用，引入 OpenSpec 能让技术决策和变更历史清晰可查，大幅降低协作成本。