对于长期在一线编写代码的工程师而言，AI 编程真正的瓶颈早已不是“模型能否生成代码”。更为核心的挑战，隐藏在一系列更棘手的问题中：需求是否得到了彻底澄清？设计思路能否被复用？整个过程是否可以追溯审计？当多个对话窗口并行运作时，它们之间能否实现协同？如果这些环节仍仅依赖聊天窗口中的即兴发挥与短暂记忆，一旦项目复杂度提升，输出质量必然失控。

之所以将 OpenSpec 与 Superpowers 这两个工具放在一起探讨，原因非常明确。前者更像一个由“规格”驱动的规划层，强调产出 proposal、spec、design、tasks 等可落地的“工件”；后者则更像一套执行层面的方法论与技能框架，强调从 brainstorm 到 plan，再到 execute 和 finish 的完整流程，并且正逐步强化基于子 Agent 的开发模式。将两者组合，恰好能补齐从“模糊需求”到“具体实现”之间的完整链路。

摘要

这套工作流的核心思想，并非让 AI 直接生成代码。其逻辑链条如下：首先，将需求、约束条件与设计决策，沉淀为代码仓库中一份份“活”的文档；然后，让负责执行的 Agent 或子 Agent 去“消化”这些文档，并扮演不同角色，分阶段完成实现、测试、评审与收尾工作。这才是更加工程化的实践。

结合官方资料，可将此工作流概括为三个清晰的层级：

1. 规格层：OpenSpec

   • 推荐的起点是 /opsx:propose “your idea” 这个命令。
   • 核心产出为 proposal、spec、design、tasks 等文档。
   • 整个流程强调迭代与流动，而非僵化的瀑布模型。
   • 特别适合在现有项目（brownfield）中进行增量式演进。

2. 执行层：Superpowers

   • 官方主流程为 brainstorm → plan → execute → finish。
   • 在新版本中，specs 与 plans 这两个“工件”会被统一输出到 docs/superpowers/specs/ 和 docs/superpowers/plans/ 目录。
   • 在支持子 Agent 的环境中，正强化基于子 Agent 的开发模式。
   • 通过 EnterPlanMode 等机制，强行避免模型跳过设计阶段直接编写代码。

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

   • Claude Code 提供 slash commands 与子 Agent 机制作为底层支持。
   • 在 Codex 一侧，Superpowers 已采用原生的技能发现方式。
   • GitHub Copilot coding agent 则可作为异步执行与生成 PR 的层，将规格驱动的任务最终落实到仓库的协作流程中。

为何将 OpenSpec 放在前、Superpowers 放在后

确实，不少团队在 AI 编程中遭遇挫折，原因往往并非模型能力不足，而是将“需求分析、设计讨论、任务拆解、编码实现、测试验证、代码审查”这些本应分头进行的工作，全部混合在一次对话中完成。这样做的后果，想必大家都不陌生：

• 需求边界模糊不清；
• 设计决策无法追溯；
• 上下文仅存在于短暂的聊天窗口中；
• 一旦切换对话，之前的推理链条便彻底断裂；
• 代码虽能运行，却为后续维护埋下隐患。

OpenSpec 的价值在于，它强制将“需求和设计”提前，并使其成为能被仓库管理的“工件”。官方仓库已重构为“工件驱动”的工作流，建议从 proposal 开始，再到 spec、design、tasks。这意味着它不再是一堆简单的 prompt 集合，而是一套可被评审、提交与迭代的规范化机制。

Superpowers 的价值，则在于它将“具体如何执行”也标准化了。其 README 提供了清晰的工作流：brainstorm → plan → execute → finish。最近更新的版本还强化了 plan 阶段的约束，并在支持子 Agent 的环境中，大力推动子 Agent 驱动的开发。

因此，更合理的组合并非在两者之间二选一，而是形成一个自然的工程分层：

• OpenSpec 负责清晰地定义问题
• Superpowers 负责稳妥地推进解决方案
• 宿主 Agent 负责实际的落地与自动化协作

这是典型的工程思维，而非简单的工具堆砌。

OpenSpec：将需求、设计与任务，从聊天记录变为仓库工件

OpenSpec 官方将其描述为一个轻量级、规格驱动的框架，并明确强调它是一个通用的“规划层”，可跨不同的编码 Agent 使用。这一点至关重要：它并非绑定某个特定模型，而是在代码仓库中建立一套稳定的上下文结构。

根据仓库与官网信息，OpenSpec 具备几个在工程上非常实用的特点：

1. 以 proposal 为入口

官方建议从 /opsx:propose “你的想法” 开始。这意味着，任何稍大的改动都不再是“直接让 AI 修改代码”，而是先提交一个明确的变更意图：目标是什么、为何要做、范围多大、风险何在、哪些内容刻意不做。这一步非常有利于需求的澄清、方案的预评审以及影响面的分析。

2. 工件化而非流水账化

OpenSpec 输出的 proposal、spec、design、tasks，并非聊天记录的摘要，而是可进入版本控制系统、被管理的“活文档”。这样做有三个直接好处：Agent 切换时不丢失上下文；团队进行评审时有明确锚点；后续回溯时能清晰了解“当时为何如此设计”。

3. 并非瀑布流程

官方 README 明确强调，此流程是流动的、迭代的，而非瀑布式。也就是说，proposal 完成后并不要求一次性将全部设计写死。更合理的实践是：先出 proposal，经过讨论逐步补全 spec，遇到具体技术难点再沉淀 design，最后才落到可执行的 tasks。这种模式非常适合老项目的改造，因为 brownfield 场景往往需要一边分析一边发现隐藏的约束。

Superpowers：将执行阶段从“能写代码”升级为“按流程写代码”

Superpowers 官方将其定义为“Agent 技能框架与软件开发方法论”。这里最重要的词不是“技能”，而是“方法论”。它要解决的核心问题是：让 Agent 在工程实践中以可控的方式工作，而非仅凭模型的临场发挥。

1. 四阶段主流程

官方给出的核心流程为：brainstorm → plan → execute → finish。这四步对应着工程团队常见的协作节奏：brainstorm 快速收敛问题空间，plan 形成实施方案与任务拆解，execute 负责编码、测试与修复，finish 则是收尾、验证与撰写交付说明。

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

根据 v5.0.0 版本的发布说明，specs 与 plans 已被重构并输出到 docs/superpowers/specs/ 与 docs/superpowers/plans/ 目录。这表明 Superpowers 也在强化“可沉淀工件”这一方向。这与 OpenSpec 非但不冲突，反而天然互补：OpenSpec 更适合处理高层级的需求与设计，而 Superpowers 则是执行期 plan 与具体行动记录的最佳载体。

3. 强化“先 plan 再 execute”

发布说明中特别提到加入了 EnterPlanMode 拦截机制，目的是避免模型直接跳过设计阶段就进入编码。这说明官方也意识到一个常见问题：模型太容易“看起来很懂”，然后直接动手写代码。而工程上最怕的，恰恰就是这种“未设计先编码”的状况。

4. 子Agent驱动的开发成为重要方向

在支持子 Agent 的环境中，Superpowers 已将子 Agent 驱动的开发变为强制路径之一。这与 Anthropic 官方对子 Agent 的定义高度一致：子 Agent 可拥有独立的上下文、工具权限以及定制化的提示，非常适合处理专项任务。

换言之，Superpowers 的价值正从一个“单一对话技能包”升级为一个“多对话协作框架”。

从单袋里走向多袋里：为何子Agent是这套工作流的关键拼图

Anthropic 官方文档对子 Agent 的说明非常清晰：它们可根据任务进行定制，拥有独立的上下文窗口、专门的工具权限与定制化的系统提示。同时，Claude Opus 4.6 的官方新闻也提到，在 Claude Code 中已可组装 Agent 团队来共同处理任务。

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

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

这种拆分带来的好处显而易见：

1. 上下文隔离

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

2. 角色边界清晰

过去一个 Agent 同时扮演产品经理、架构师、开发、测试与 Reviewer，结果往往产生自我确认偏误。多 Agent 模式后，可将“写代码”与“挑毛病”这两个角色分离开来。

3. 审查可制度化

你可要求评审袋里仅根据 spec 与代码 diff 进行审查，而非依据主袋里的“自述”来判断。这更接近真实团队中的协作模式。

Key Comparison Table

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

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

Anthropic 官方文档说明，Claude Code 支持项目级别与用户级别的自定义 slash commands，命令可直接由 Markdown 文件定义。这意味着 OpenSpec 与 Superpowers 这类命令驱动系统，不再依赖“模型记得流程”，而是依赖明确的命令入口。同时，Claude Code 对子 Agent 的出色支持，使其非常适合承担提案生成、规格补全、多角色拆分执行与审查袋里调用等任务。

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

Superpowers 的 Codex 安装说明显示，它已改用原生的技能发现方式，通过 ~/.agents/skills/superpowers 的软链接接入，取代了旧的 bootstrap 方案。这说明生态方向已很明确：尽量贴近宿主原生能力，减少额外的包装层。从工程角度看，这意味着安装链路更短、技能发现更稳定、与 OpenSpec 的组合也更轻量。

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

GitHub 官方文档指出，Copilot coding agent 可根据 issue 或聊天提示，独立完成编码任务、执行测试并发起 PR。这非常适合放在工作流的后半段：人类或主袋里先用 OpenSpec 生成 proposal/spec/design/tasks；再用 Superpowers 制定 plan 与执行约束；最后将任务投递给 Copilot coding agent，由它在 GitHub 环境中完成实现并提交 PR；最后由人工或审查袋里按 spec 进行审核。这是一种非常实用的“同步规划 + 异步编码”模式。

实战代码示例

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



请基于用户输入生成一个变更 proposal，要求：
1. 明确目标、非目标、影响范围
2. 标识风险与待确认问题
3. 输出到仓库约定目录，例如 docs/openspec/proposals/
用户需求：$ARGUMENTS

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

此做法利用 Claude Code 的自定义 slash commands 能力。其好处在于，团队所有成员都从统一的命令入口生成 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 文本，还能结合相关的仓库上下文工作。若 issue 中直接引用了 OpenSpec 与 Superpowers 的工件，Agent 的输入质量会比一句“帮我改一下这个模块”高得多。

代码块注释规范

在技术博客与团队文档中，建议遵守以下几条规则：

1. 每个代码块先写“作用”注释，例如 # 作用：生成 proposal 并固化需求边界，这样读者与 Agent 都能先理解目的，再看细节。
2. 关键步骤必须有“为什么”注释，不只写“做什么”，还要解释“为何这样做”，例如 # 关键点：避免直接跳过设计阶段进入编码。
3. 注释控制在 1-2 行，避免淹没主逻辑。注释是为了辅助理解，不应将代码变成大段说明文。
4. 路径、命令、输出目录要标明约定，例如说明 docs/openspec/、docs/superpowers/plans/ 的用途。这对团队协作与保持 Agent 行为一致性非常重要。
5. 示例代码尽量体现可复制的最小闭环，一个代码块最好只解决一个问题，比如生成提案、触发计划、提交 issue、运行测试，避免将多个动作混在一起。

常见问题与排障

1. OpenSpec 文档写了很多，但 Agent 仍直接开写

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

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

确认当前宿主是否真的启用了对应的技能发现与工作流机制。特别是在 Codex 中，需按官方文档切换到原生的技能发现方式。

3. 多袋里协作后，结果反而更混乱

这通常是角色定义不清所致。不要让实现袋里同时负责需求澄清与代码审查，应按照“工件”来拆分角色。

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

检查 issue 或任务描述是否明确引用了 spec/design/plan。GitHub Agent 依赖 issue、PR 评论及相关上下文来构建提示，输入模糊会直接影响输出质量。

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

OpenSpec 官方强调流程是迭代的、非瀑布式的，也强调其对 brownfield 项目的友好性。实践中，可只从 proposal + tasks 开始，不必一开始就将所有工件全部补齐。

结论：一套更稳的 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”开始。你会明显感觉到，后续的代码质量、评审效率与返工率，都会有质的提升。