当 OpenSpec 遇上 Superpowers：AI 辅助编程的终极工作流

当 OpenSpec 遇上 Superpowers：AI 辅助编程的终极工作流

大家想学习更多AI知识，可以收藏下面两个网站：
GPTBUYS、ZeoAPI

对于一线工程师来说，AI 编程真正的瓶颈，早就不是“模型会不会写代码”，而是“需求是否被澄清”“设计是否可复用”“执行是否可审计”“多代理是否能协同”。如果这些环节仍然靠聊天窗口里的即时记忆，项目一复杂，输出就会失控。

OpenSpec 和 Superpowers 值得放在一起讨论，原因很直接：前者更像规格驱动的 planning layer，强调 proposal、spec、design、tasks 这些可落库的工件；后者则更像执行层的方法论与技能框架，强调 brainstorm → plan → execute → finish，并且正在强化 subagent-driven development。把两者组合起来，正好补上“从需求到实现”的完整链路。

摘要

摘要：OpenSpec 解决“先想清楚再写”，Superpowers 解决“按方法执行并审查”，两者叠加可形成面向 Claude Code、Codex、Cursor、Copilot 等多工具的一套工程化 AI 工作流。

这套工作流的核心思想不是让 AI 直接生成代码，而是先把需求、约束、设计决策沉淀为代码库中的活文档，再让执行型 agent 或 subagent 消费这些文档，分角色完成实现、测试、评审和收尾。

结合官方资料，可以把它概括为三层：

1. 规格层：OpenSpec

   • 入口推荐从/opsx:propose "your idea"开始。
   • 工件以 proposal、spec、design、tasks 为中心。
   • 流程强调 iterative、fluid、not waterfall。
   • 更适合 brownfield 场景中的增量演进。

2. 执行层：Superpowers

   • 官方主流程为 brainstorm → plan → execute → finish。
   • 新版本把 specs 与 plans 统一落到docs/superpowers/specs/和docs/superpowers/plans/。
   • 在支持 subagent 的环境中，正在强化 subagent-driven development。
   • 通过 EnterPlanMode 等机制，防止模型跳过设计阶段直接开写。

3. 宿主层：Claude Code / Codex / Copilot coding agent

   • Claude Code 提供 slash commands 与 subagents 作为底层机制。
   • Codex 侧，Superpowers 已采用 native skill discovery。
   • GitHub Copilot coding agent 则可以作为异步执行与 PR 生成层，把规范驱动的任务最终落到仓库协作流程中。

为什么要把 OpenSpec 放在前、Superpowers 放在后

摘要：OpenSpec 擅长把“问题定义清楚”，Superpowers 擅长把“解决过程制度化”，先后顺序决定了 AI 输出质量上限。

很多团队使用 AI 编程失败，不是因为模型能力差，而是因为把“需求分析、设计、任务拆解、编码、测试、审查”全部混成一轮对话。结果通常是：

• 需求边界不清；
• 设计决策无法复盘；
• 上下文只存在于聊天窗口；
• 代理一换，历史推理链路丢失；
• 代码虽能生成，但后续维护成本很高。

OpenSpec 的价值在于把“需求和设计”前置，并且把它们落成仓库工件。官方仓库已经重构为 artifact-guided workflow，推荐从 proposal 开始，再到 spec、design、tasks。这意味着它不是一个简单 prompt 集合，而是一套可评审、可提交、可迭代的规范层机制。[1][3]

Superpowers 的价值在于，把“怎么做”进一步标准化。它的 README 给出完整工作流 brainstorm → plan → execute → finish，近期版本还强化了 plan 阶段约束，并在支持 subagent 的环境中推动 subagent-driven development。[2][4]

所以更合理的组合方式不是二选一，而是：

• OpenSpec 负责定义问题
• Superpowers 负责推进解法
• 宿主 agent 负责实际落地与自动化协作

这是一个典型的工程分层，而不是工具堆叠。

OpenSpec：把需求、设计和任务从聊天记录变成仓库工件

摘要：OpenSpec 的本质是“规格即上下文”，让 AI 的前置理解不依赖会话记忆，而依赖可持久化的文档工件。

OpenSpec 官方将自身描述为 lightweight spec-driven framework，并明确强调它是通用 planning layer，可跨不同 coding agent 使用。[3] 这点非常关键：它不是绑定某一个模型，而是在代码库中建立一种稳定的上下文结构。

结合仓库与官网信息，OpenSpec 有几个工程上非常实用的特征：

1. 以 proposal 为入口

官方推荐从/opsx:propose "your idea"开始。[1]
这意味着任何稍大的改动，不再是“直接让 AI 改代码”，而是先提交一个变更意图：

• 目标是什么；
• 为什么要做；
• 范围是什么；
• 风险在哪里；
• 哪些内容不做。

这一步非常适合需求澄清、方案预评审和影响面分析。

2. 工件化而不是流水账化

OpenSpec 的 proposal、spec、design、tasks 不是聊天摘要，而是可以进入代码库、被版本控制管理的“活文档”。[1][3]
这带来三个直接收益：

• agent 切换时不丢上下文；
• 团队评审时有明确锚点；
• 后续回溯时能知道“为什么这样设计”。

3. 不是瀑布流程

官方 README 明确强调流程是 fluid、iterative、not waterfall。[1]
也就是说，proposal 并不意味着必须一次写死全部设计。更合理的实践是：

• 先出 proposal；
• 经过讨论补成 spec；
• 在遇到技术细节时沉淀 design；
• 最后才落到 tasks。

这很适合老项目改造，因为 brownfield 场景往往需要边分析边发现约束。[3]

Superpowers：把执行阶段从“会写代码”升级到“会按流程写代码”

摘要：Superpowers 更像 AI 开发团队的操作系统，它不只提供 prompt，而是提供执行套路、技能分工和阶段约束。

Superpowers 官方把自己定义为 agentic skills framework & software development methodology。[2] 这里最重要的不是“skills”，而是 “methodology”。也就是说，它要解决的是：让 agent 在工程实践中按可控方式工作，而不是凭模型临场发挥。

1. 四阶段主流程

官方给出的主流程是：

• brainstorm
• plan
• execute
• finish

这四步对应工程团队常见的协作节奏：

• brainstorm：快速收敛问题空间；
• plan：形成实施方案与拆解；
• execute：编码、测试、修复；
• finish：收尾、验证、交付说明。

2. 文档工件开始标准化落地

根据 v5.0.0 发布说明，specs 与 plans 已重构输出到：

• docs/superpowers/specs/
• docs/superpowers/plans/

这说明 Superpowers 也在强化“可沉淀工件”的方向。[4]
这与 OpenSpec 并不冲突，反而天然互补：OpenSpec 可用于高层需求与设计，Superpowers 可用于执行期的 plan 和具体行动记录。

3. 强化“先 plan 再 execute”

发布说明特别提到加入 EnterPlanMode 拦截，避免模型直接跳过设计阶段进入原生 plan mode。[4]
这说明官方已经意识到一个常见问题：模型太容易“看起来很懂”，然后直接开始写。工程上最怕的就是这种“未设计先编码”。

4. subagent-driven development 成为重要方向

在支持 subagent 的环境里，Superpowers 把 subagent-driven development 变成强制路径之一。[4]
这和 Anthropic 官方对 subagents 的定义高度一致：subagent 可以有独立上下文、工具权限、定制提示，适合做任务专项委派。[5]

换句话说，Superpowers 的价值正在从“单代理技能包”升级为“多代理协作框架”。

从单代理走向多代理：为什么 subagents 是这套工作流的关键拼图

摘要：多代理不是噱头，它解决的是上下文拥塞、角色混杂和审查缺位三个现实问题。

Anthropic 官方文档对 subagents 的说明很明确：它们可以按任务定制，有独立上下文窗口、专门工具权限和定制系统提示。[5] 同时，Claude Opus 4.6 的官方新闻也提到，Claude Code 中已经可以组装 agent teams 一起处理任务。[9]

这对 OpenSpec + Superpowers 的组合非常关键，因为你终于可以把不同工件分发给不同角色：

• 需求代理：消费 proposal，补齐缺失边界；
• 设计代理：基于 spec/design 讨论架构取舍；
• 实现代理：只关注 tasks 和代码修改；
• 测试代理：负责补测试、跑 lint、分析失败；
• 审查代理：对照 spec 校验是否偏离；
• 安全代理：检查依赖、密钥、输入校验和危险调用。

这种拆分有三个明显收益：

1. 上下文隔离

实现代理不必背负全部需求讨论历史，只需消费稳定工件。
这能显著降低上下文窗口被噪声占满的风险。

2. 角色边界清晰

过去一个 agent 同时扮演 PM、架构师、开发、测试、Reviewer，结果常常自我确认偏误。多代理后，可以把“写代码”和“挑毛病”分离开。

3. 审查可制度化

你可以要求评审代理只根据 spec 和 diff 做审查，而不是根据主代理的“自述”来判断。这样更接近真实团队协作。

Key Comparison Table

摘要：选型关键不在“哪个更强”，而在“哪个放在哪一层最合适”。

在 Claude Code、Codex、Copilot 中如何落地这套组合

摘要：真正可用的工作流，必须依赖宿主工具提供的命令入口、技能发现和异步执行机制。

1. Claude Code：最适合做“主控台”

Anthropic 官方文档说明，Claude Code 支持 project-level 和 user-level 的自定义 slash commands，命令可直接由 Markdown 文件定义。[6]
这意味着 OpenSpec 和 Superpowers 这类命令驱动系统，不再依赖“模型记得流程”，而是依赖明确命令入口。

同时，Claude Code 对 subagents 的支持，使它非常适合承担：

• 提案生成；
• 规格补全；
• 多角色拆分执行；
• 审查代理调用。

2. Codex：更轻的原生技能接入

Superpowers 的 Codex 安装说明显示，其已改用 native skill discovery，通过~/.agents/skills/superpowers软链接接入，而不是旧的 bootstrap 方案。[7]
这说明生态方向已经很明确：尽量贴近宿主原生能力，减少额外包装层。

工程意义是：

• 安装链路更短；
• 技能发现更稳定；
• 与 OpenSpec 的组合更轻量。

3. Copilot coding agent：最适合做异步执行层

GitHub 官方文档指出，Copilot coding agent 可根据 issue 或聊天提示独立完成编码任务、执行测试并发起 PR。[8][10]
这非常适合放在工作流后半段：

1. 人类或主代理先用 OpenSpec 生成 proposal/spec/design/tasks；
2. 再用 Superpowers 做 plan 与执行约束；
3. 最后把任务投递给 Copilot coding agent；
4. 由其在 GitHub 环境中完成实现并提交 PR；
5. 再由人工或审查代理按 spec 审核。

这是一种非常实用的“同步规划 + 异步编码”模式。

实战代码示例

摘要：下面给出一个可操作的最小落地示例，覆盖 OpenSpec 提案、Claude Code 命令和 GitHub 异步执行衔接。

示例 1：在 Claude Code 中定义 OpenSpec 风格命令入口

<!-- 文件示例：.claude/commands/propose-feature.md --> <!-- 作用：把“先提案再开发”固化为团队命令入口 --> 请基于用户输入生成一个变更 proposal，要求： 1. 明确目标、非目标、影响范围 2. 标识风险与待确认问题 3. 输出到仓库约定目录，例如 docs/openspec/proposals/ 用户需求：$ARGUMENTS

# 作用：在 Claude Code 中通过 slash command 触发提案# 关键点：让需求分析走稳定入口，而非临时聊天/propose-feature"为支付服务增加幂等键校验与重试保护"

这个做法利用了 Claude Code 的自定义 slash commands 能力。[6]
它的好处是：团队成员都从同一个命令入口生成 proposal，格式和约束更统一。

示例 2：把 OpenSpec 输出衔接到 Superpowers 执行阶段

# 作用：先产出规格，再进入执行计划# 关键点：避免一上来直接让 agent 修改代码# Step 1: 用 OpenSpec 风格命令生成 proposal/opsx:propose"在订单服务中新增取消原因审计字段"# Step 2: 基于 proposal 补充 spec/design/tasks# 注：这里可以由主代理或子代理逐步完成/opsx:spec"补充接口变更、数据库迁移、回滚策略"/opsx:design"评估是否采用事件补偿而非同步更新"/opsx:tasks"拆分后端、测试、文档任务"# Step 3: 进入 Superpowers 的 plan/execute 阶段# 注：让执行代理只消费已沉淀工件，减少上下文漂移/superpowers:plan"根据 docs 中的规格生成实施计划"/superpowers:execute"按计划修改代码、补测试、运行 lint"

上面这套命令链背后的思路是：

• OpenSpec 管前置澄清与设计；
• Superpowers 管执行与收尾；
• 命令就是流程边界。

示例 3：把任务交给 GitHub 异步执行

# 作用：示意如何把规格链接放入 issue，供 GitHub agent 消费# 文件类型：issue 模板片段或任务描述模板title:实现订单取消原因审计字段body:-需求规格:docs/openspec/specs/order-cancel-audit.md-设计说明:docs/openspec/designs/order-cancel-audit.md-执行计划:docs/superpowers/plans/order-cancel-audit-plan.md-验收标准:-API 返回字段兼容旧客户端-数据库迁移可回滚-单元测试与集成测试通过

这样做的意义在于：Copilot coding agent 的上下文不只是 issue 文本，还能结合相关仓库上下文工作。[8][10]
如果 issue 里直接引用 OpenSpec 和 Superpowers 工件，agent 的输入质量会比“帮我改一下这个模块”高得多。

代码块注释规范

摘要：AI 时代的代码块示例，不仅要能跑，还要让人和代理都能快速理解意图。

建议在技术博客和团队文档里遵守以下规则：

1. 每个代码块先写“作用”注释

   • 例如：# 作用：生成 proposal 并固化需求边界
   • 这样读者和 agent 能先理解目的，再看细节。

2. 关键步骤必须有“为什么”注释

   • 不只写“做什么”，还要写“为什么这样做”。
   • 例如：# 关键点：避免直接跳过设计阶段进入编码

3. 注释控制在 1-2 行，避免淹没主逻辑

   • 代码块注释应帮助理解，不应把代码变成大段说明文。

4. 路径、命令、输出目录要标明约定

   • 例如说明docs/openspec/、docs/superpowers/plans/的用途。
   • 这对团队协作和 agent 一致性非常重要。

5. 示例代码尽量体现可复制的最小闭环

   • 一个代码块最好只解决一个问题：生成提案、触发计划、提交 issue、跑测试。
   • 避免把多个动作混在一起。

常见问题与排错

摘要：多数落地失败并非模型不够强，而是工件、命令和角色边界没有建立好。

1. OpenSpec 文档写了很多，但 agent 还是直接开写

检查是否给了稳定命令入口。没有 slash command 或明确流程约束时，模型容易跳过 proposal/spec 阶段。[6]

2. Superpowers 已安装，但执行时像普通聊天一样失控

确认当前宿主是否真的启用了对应技能发现与工作流机制。尤其在 Codex 中，需要按官方文档切到 native skill discovery 方式。[7]

3. 多代理协作后，结果反而更混乱

通常是角色定义不清。不要让实现代理同时负责需求澄清和代码审查，应按工件拆角色。[5][9]

4. Copilot coding agent 提交了 PR，但和预期偏差很大

检查 issue 或任务描述是否明确引用了 spec/design/plan。GitHub agent 依赖 issue、PR 评论和相关上下文构成提示，输入模糊会直接影响输出。[8][10]

5. 老项目里觉得 OpenSpec 太“重”

OpenSpec 官方强调流程是 iterative、not waterfall，也强调 brownfield-first。[1][3]
实践上可以只从 proposal + tasks 开始，不必一开始就把全部工件补齐。

结论：一套更稳的 AI 编程闭环，应该从“规范化上下文”开始

摘要：别再把 AI 当成只会补全代码的工具，而要把它纳入可审计、可协作、可复用的工程流程。

如果只用一个强模型直接写代码，你得到的是“短期快感”；如果把 OpenSpec、Superpowers 和宿主 agent 机制组合起来，你得到的是“团队可持续的生产力系统”。

一个非常实用的落地顺序是：

1. 先在仓库中引入 OpenSpec
   • 从 proposal 开始，不要求一步到位。
2. 再接入 Superpowers
   • 把 execute 前的 plan 阶段强制化。
3. 在 Claude Code 或 Codex 中固化命令入口
   • 用 slash commands 或 native skills 替代口头约定。
4. 最后接入 GitHub 异步 agent
   • 让 issue → 实现 → PR 成为自动化后半段。

下一步建议很明确：
挑一个真实的中小型需求，不要从“让 AI 写页面”开始，而是从“让 AI 先写 proposal 和 spec”开始。你会明显感觉到，后面的代码质量、评审效率和返工率都不一样。

参考资料

• Fission-AI/OpenSpec: Spec-driven development (SDD) for AI coding assistants
  https://github.com/Fission-AI/OpenSpec
• OpenSpec — A lightweight spec-driven framework
  https://openspec.dev/
• obra/superpowers: An agentic skills framework & software development methodology that works
  https://github.com/obra/superpowers
• superpowers/RELEASE-NOTES.md
  https://github.com/obra/superpowers/blob/main/RELEASE-NOTES.md
• Subagents - Anthropic
  https://docs.anthropic.com/en/docs/claude-code/sub-agents
• Slash commands - Anthropic
  https://docs.anthropic.com/en/docs/claude-code/slash-commands
• Installing Superpowers for Codex
  https://github.com/obra/superpowers/blob/main/.codex/INSTALL.md
• About GitHub Copilot coding agent
  https://docs.github.com/en/copilot/concepts/about-copilot-coding-agent
• Responsible use of GitHub Copilot coding agent on GitHub.com
  https://docs.github.com/en/copilot/responsible-use/copilot-coding-agent
• Claude Opus 4.6
  https://www.anthropic.com/news/claude-opus-4-6