OpenSpec+Superpowers 自动化桥接：这次直接给你开箱即用模板

java金融

发布于 2026-06-24 14:13:34

4500

文章被收录于专栏：java金融java金融

上一篇文章里面《OpenSpec 管需求，Superpowers 管落地，中间还差一座桥》评论区有个问题很真实：

★看了好多文章，还是搞不懂自动化桥接，有没有开箱即用的？

我理解这个困惑。

因为很多文章讲 OpenSpec 和 Superpowers，一上来就说「一个管规范，一个管流程」。这句话没错，但读者真正卡住的不是概念。

真正卡住的是打开终端以后该怎么做：

Superpowers 装在哪里？
OpenSpec 装在哪里？
两个工具怎么互相知道对方存在？
OpenSpec 写出来的 proposal、design、tasks，怎么进入 Superpowers 的 TDD 流程？
有没有一个模板，复制过去就能跑？

如果这些问题没人讲清楚，「双框架配合」就会变成一句很漂亮但没法落地的话。

事情通常是这样的。

你已经在项目里装好了 AI 编程助手，也知道复杂需求最好先写规格，于是让 OpenSpec 生成了一个变更目录：

openspec/
  changes/
    add-payment-callback-idempotency/
      proposal.md
      design.md
      tasks.md
      specs/
        payment-callback/
          spec.md

然后你又装了 Superpowers，希望它按测试驱动开发、代码审查、分支收尾那套纪律来写代码。

听起来很稳，对吧。

但下一步 AI 可能直接开始改 PaymentCallbackService，并没有认真读 design.md 里的“必须做什么、禁止做什么”；也可能把 OpenSpec 的 tasks.md 当成普通待办，一口气改完表、服务、事件和测试；更糟的是，代码审查通过了，但实现违反了 proposal.md 里的“不做事项”。

这就是问题所在。

OpenSpec 和 Superpowers 本身不会天然自动桥接。真正开箱即用的，不是再装一个神奇框架，而是在项目里放一层很薄的桥接技能。

这篇文章就只解决一个问题：

从 0 安装 Superpowers、安装 OpenSpec，然后用一个可复制的桥接技能，把 OpenSpec 规格自动喂进 Superpowers 的执行链路。

先说结论：桥接层到底做什么

OpenSpec 负责回答：

这次改什么？
为什么改？
哪些明确不改？
业务场景怎么验收？
设计约束是什么？

Superpowers 负责回答：

先写哪个测试？
每一步怎么做到红绿重构？
什么时候做代码审查？
什么时候收尾？

中间缺的桥接技能，负责回答：

从哪个 OpenSpec 变更开始？
需要读取哪些规范文件？
OpenSpec tasks 怎么拆成 TDD 原子步骤？
每个任务完成后怎么做规格合规检查？
归档前要卡哪些闸门？

所以桥接不是玄学，也不是 MCP 一接就完事。

它本质上是一组强制执行的上下文规则。

最小闭环如下：

OpenSpec 变更
  -> 桥接技能读取 proposal/design/spec/tasks
  -> 生成 Superpowers plan
  -> superpowers:executing-plans 执行
  -> 代码审查
  -> 规格合规检查
  -> superpowers:finishing-a-development-branch 收尾
  -> 测试 + OpenSpec 校验
  -> 归档

这个链路里，最关键的是两句话：

OpenSpec 产物没有进入执行上下文，就等于没写。

违反规格不是建议，是缺陷。

第一步，安装 Superpowers：先装到你的 Agent 宿主里

Superpowers 不是一个普通的业务依赖。

它不是装进你的 Spring Boot 项目，也不是装进 pom.xml、package.json。

它要装到你正在使用的 AI 编程宿主里，比如 Claude Code、Codex CLI、Codex App、Gemini CLI、Cursor 等。

官方 README 里也写得很直白：如果你使用多个 Agent 宿主，需要分别安装。

Claude Code

如果你用 Claude Code，可以走官方插件市场：

/plugin install superpowers@claude-plugins-official

也可以先注册 Superpowers marketplace：

/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

Codex CLI

如果你用 Codex CLI，进入插件搜索界面：

/plugins

搜索：

superpowers

然后选择安装。

Codex App

如果你用 Codex App，在左侧 Plugins 里找到 Coding 分类下的 Superpowers，点击 + 安装。

Gemini CLI

Gemini CLI 的安装命令是：

gemini extensions install https://github.com/obra/superpowers

后续更新：

gemini extensions update superpowers

安装完以后，别急着让它写代码。

你先问 Agent 一句：

请确认 Superpowers 是否已启用，并列出当前可用的软件开发流程技能。

你要看到的不是某个版本号，而是 Agent 确实会在开发任务中触发需求澄清、计划拆解、测试驱动开发、代码审查、分支收尾这些流程。

否则后面桥接层写得再好，它也接不到施工队。

第二步，安装 OpenSpec：装 CLI，初始化项目规格目录

OpenSpec 是项目级的规格工作流。

它要进入你的代码仓库，生成 openspec/ 目录，让后续需求变更有地方沉淀。

按官方快速开始文档，前置要求是：

Node.js 20.19.0 or higher

先确认 Node 版本：

node -v

安装 OpenSpec CLI：

npm install -g @fission-ai/openspec@latest

进入你的项目：

cd your-project
openspec init

初始化后，项目里应该出现类似目录：

openspec/
  project.md
  specs/
  changes/

然后你就可以让 AI 开一个规格变更：

/opsx:propose add-payment-callback-idempotency

官方 README 的示例里，新工作流会生成这些产物：

proposal.md
specs/
design.md
tasks.md

这几个文件就是后面桥接技能要读取的核心输入。

如果你需要扩展工作流，可以再执行：

openspec config profile
openspec update

常见扩展命令包括 /opsx:new、/opsx:continue、/opsx:ff、/opsx:verify、/opsx:bulk-archive、/opsx:onboard。

这里不用一开始全开。

我更建议先把 propose -> apply -> verify -> archive 这条“提出变更、执行变更、校验变更、归档变更”的主链路跑通。

第三步，先跑一个最小 OpenSpec 变更

不要一上来拿“重构订单中心”这种大需求测试。

先拿一个可控但有工程价值的需求，比如：

给支付回调增加幂等控制。
同一个 channel + payTradeNo 重复回调，只能插入一条支付流水，只能发布一次 OrderPaidEvent。
已成功处理过的重复回调仍然返回 SUCCESS。
不改三方回调协议，不重构支付网关，不改变订单状态机。

执行：

/opsx:propose add-payment-callback-idempotency

你要重点检查四类文件。

proposal.md 要写清边界

一个能用的 proposal.md 至少要有背景、变更内容、不做事项。

# 提案：add-payment-callback-idempotency

## 背景

支付平台可能重复推送同一笔支付回调。当前系统只判断订单状态，
无法防住并发重复回调，存在重复支付流水和重复发货事件风险。

## 变更内容

- 新增 payment_callback_idempotency 幂等表
- 以 channel + pay_trade_no 建立唯一约束
- 重复成功回调返回 SUCCESS，但不重复写流水、不重复发事件
- 金额不一致或订单状态非法时记录异常，不触发后续业务动作

## 不做事项

- 不修改三方支付平台回调协议
- 不重构支付网关和支付渠道抽象
- 不改变订单主状态机定义
- 不处理历史脏数据迁移

“不做事项”很重要。

没有它，AI 很容易“顺手优化”支付网关，最后改出了一个不在需求范围内的新系统。

spec.md 要写成可验收场景

尤其要覆盖并发重复回调。

### 需求：支付回调幂等

系统必须保证同一笔支付回调只被业务处理一次。

#### 场景：同一笔回调并发到达

- 假设订单当前状态是 WAIT_PAY
- 并且两次回调的 channel 和 payTradeNo 完全相同
- 当这两次回调并发进入系统
- 那么系统只能插入一条支付流水
- 并且订单只能从 WAIT_PAY 变成 PAID 一次
- 并且只能发布一次 OrderPaidEvent
- 并且两次回调都要给支付渠道返回 SUCCESS

这段不是文档装饰。

它后面必须变成测试。

design.md 要写“必须”和“禁止”

桥接层最喜欢读这种硬约束。

## 幂等设计

- 必须使用数据库唯一约束作为幂等主闸门。
- 唯一键必须是 `(channel, pay_trade_no)`。
- 幂等记录写入和订单支付状态更新必须在同一个事务里完成。
- OrderPaidEvent 必须在事务提交后发布。
- 禁止用本地内存缓存作为主幂等方案，因为服务可能多实例部署。
- Redis 锁可以作为优化手段，但不能替代数据库唯一约束。

如果 AI 后面写出这个代码：

private final Set<String> processed = ConcurrentHashMap.newKeySet();

那不是“实现方式不同”。

它违反了 design.md。

tasks.md 不要写得太细，也不要太空

OpenSpec 的 tasks.md 是需求视角清单，不是最终测试驱动开发执行计划。

## 任务

- [ ] 新增支付回调幂等表
- [ ] 新增幂等记录的数据访问层
- [ ] 改造支付回调服务
- [ ] 补充重复回调测试
- [ ] 补充并发重复回调测试
- [ ] 归档前补充规格合规检查

这个粒度给需求评审够用。

但给 Superpowers 执行还太粗。

桥接技能要做的第一件事，就是把它转换成测试驱动开发原子步骤。

第四步，放入第一个开箱即用模板：spec-compliance-check

先建一个合规检查 skill。

如果你用的是 Codex 本地 skills，可以放在：

.codex/skills/spec-compliance-check/SKILL.md

如果你用的是 Claude Code 或其他宿主，就放到该宿主支持的 skill/plugin 指令目录里。目录不重要，规则内容重要。

模板如下：

---
name: spec-compliance-check
description: 对照当前 OpenSpec 变更检查实现是否合规。
---

# 规格合规检查

当实现或审查 OpenSpec 变更里的任意任务后，使用这个技能。

## 自动触发

遇到下面情况时自动使用，不需要用户手动点名：

- Superpowers 完成一个实现任务后
- Superpowers 进入代码审查前
- 用户执行 `/opsx:archive`
- 用户要求归档 OpenSpec 变更
- 用户要求检查某个 OpenSpec 变更是否可以归档

## 输入

- `openspec/changes/` 下的当前变更目录
- 本次代码差异或变更文件列表
- 如果已经运行测试，需要带上测试结果

## 工作流程

1. 在 `openspec/changes/` 下定位当前变更。
2. 读取：
   - `proposal.md`
   - `design.md`
   - `tasks.md`
   - 所有变更后的 `spec.md`
3. 对每个验收场景建立映射：
   - 对应测试文件
   - 对应实现路径
   - 当前可观察行为
4. 检查 `proposal.md` 里的每一条“不做事项”，确认变更文件没有越界。
5. 检查 `design.md` 里的每一条“必须”和“禁止”规则。
6. 发现不匹配时按“缺陷”报告，不要按“建议”报告。

## 输出

返回：

- 通过或失败
- 验收场景覆盖表
- 不做事项是否被违反
- 设计约束是否被违反
- 缺失的测试
- 归档前必须修复的问题

## 规则

如果实现违反 OpenSpec 规格，阻止归档。

这个 skill 解决一个很容易被忽略的问题：

Superpowers 的代码审查很擅长看代码质量，但它不一定知道这段代码是否符合 OpenSpec。

比如这段代码结构很顺：

@Transactional
public CallbackResult handle(PaymentCallbackCommand command) {
    Order order = orderRepository.findByOrderNo(command.orderNo())
        .orElseThrow(() -> new OrderNotFoundException(command.orderNo()));

    if (order.isPaid()) {
        return CallbackResult.success();
    }

    order.markPaid(command.payTradeNo(), command.paidAt());
    paymentRecordRepository.save(PaymentRecord.from(command));
    eventPublisher.publishEvent(new OrderPaidEvent(order.getOrderNo()));
    return CallbackResult.success();
}

普通代码审查可能会说：

结构清晰，事务注解存在，异常处理合理。

但合规检查必须继续追问：

是否存在 (channel, payTradeNo) 数据库唯一约束？
并发重复回调是否只能插入一条流水？
OrderPaidEvent 是否只发布一次？
事件是否在事务提交后发布？
是否违反“不重构支付网关”的不做事项？

这一步就是桥接的第一块拼图。

第五步，放入第二个开箱即用模板：openspec-superpowers-bridge

接下来放真正的桥接 skill。

推荐目录：

.codex/skills/openspec-superpowers-bridge/SKILL.md

模板如下：

---
name: openspec-superpowers-bridge
description: 把当前 OpenSpec 变更桥接到 Superpowers 执行流程。
---

# OpenSpec Superpowers 桥接

当用户希望用 Superpowers 实现某个 OpenSpec 变更时，使用这个技能。

## 触发场景

当用户说出类似下面的话时触发：

- 实现这个 OpenSpec 变更
- 用 Superpowers 执行这个变更
- 桥接 OpenSpec 和 Superpowers
- 开始实现 `openspec/changes/<change-id>`
- 执行 `/opsx:archive <change-id>`
- 执行 Superpowers 的实现、继续、审查、收尾流程，且当前项目存在 OpenSpec 变更
- 执行 Superpowers 命令时，如果当前目录存在 `openspec/changes/<change-id>`，先自动加载本桥接技能

## 必读输入

- `openspec/changes/<change-id>/proposal.md`
- `openspec/changes/<change-id>/design.md`
- `openspec/changes/<change-id>/tasks.md`
- 所有 `openspec/changes/<change-id>/specs/**/spec.md`

## 工作流程

1. 定位当前变更目录。
2. 修改代码前先读取 proposal、design、tasks 和变更规格。
3. 总结：
   - 目标
   - 不做事项
   - 必须做和禁止做的规则
   - 验收场景
4. 把每个 OpenSpec 任务转换成 Superpowers plan，并保存到类似目录：
   - `docs/superpowers/plans/<change-id>.md`
5. plan 文件开头必须写清执行入口：
   - 默认使用 `superpowers:executing-plans`
   - 如果团队明确启用了子 Agent 并行开发，再把执行入口替换为 `superpowers:subagent-driven-development`
   - 任务完成后使用 `superpowers:finishing-a-development-branch`
6. plan 里的每个任务必须拆成测试驱动开发步骤：
   - 先写一个失败测试
   - 运行目标测试并确认失败原因
   - 写最小实现代码
   - 再运行目标测试并确认通过
   - 重构命名和结构
   - 运行 `spec-compliance-check`
7. 执行 plan 时默认必须调用：
   - `superpowers:executing-plans`
8. `superpowers:executing-plans` 启动后，先读取 plan 文件、审查 plan 是否有问题，再逐项执行任务。
9. 每个任务完成后：
   - 更新任务状态
   - 能跑目标测试就运行目标测试
   - 运行 `spec-compliance-check`
10. 所有任务完成后：
   - 调用 `superpowers:finishing-a-development-branch`
   - 运行最终规格合规检查
11. 归档前：
   - 运行全量测试，无法运行时说明原因
   - 运行 OpenSpec 校验
   - 运行最终规格合规检查
   - 任一失败都阻止归档

## 约束

- 不要实现 proposal 范围之外的需求。
- 不要违反“不做事项”。
- 不要用其他实现选择替换 design 里的硬性规则。
- 测试或合规检查失败时不要归档。
- 如果存在多个活动变更，先让用户选择一个。

## 输出

返回：

- 选中的变更编号
- Superpowers plan 文件路径
- `superpowers:executing-plans` 执行状态
- `superpowers:finishing-a-development-branch` 收尾状态
- 当前任务状态
- 测试命令和结果
- 合规检查结果
- 是否满足归档条件

这段模板看起来不长，但它解决了三个核心问题。

第一，它强制 Agent 在改代码前读取 OpenSpec 文件。

第二，它把 OpenSpec 的需求任务转换成 Superpowers plan，再交给 superpowers:executing-plans 执行。

第三，它把规格合规检查加进每个任务后的验收环节。

这才叫自动化桥接。

不是“我记得读一下文档”。

而是“流程规则要求我必须读，并且每一步都要对照检查”。

第六步，加一个项目级启动提示

仅有 skill 还不够。

你最好在项目的 AGENTS.md、CLAUDE.md 或对应宿主的项目指令里，加一段项目级规则。

比如：

## OpenSpec + Superpowers 桥接

实现 OpenSpec 变更时：

- 总是使用 `openspec-superpowers-bridge`。
- 修改代码前先读取 `proposal.md`、`design.md`、`tasks.md` 和所有变更规格。
- 把 OpenSpec 任务转换成 Superpowers plan 文件。
- 执行 plan 时必须使用 `superpowers:executing-plans`。
- 所有任务完成后必须使用 `superpowers:finishing-a-development-branch` 收尾。
- 每个实现任务完成后运行 `spec-compliance-check`。
- 把违反规格视为缺陷。
- 测试、合规检查和 OpenSpec 校验通过前，不要归档。

这段是为了防止 Agent “忘了用桥”。

我自己的建议是：

项目级规则只写原则，具体流程放 skill。

否则 AGENTS.md 会越来越长，最后谁都不想读。

第七步，改成命令自动触发，不要每次手动喊 skill

前面那套写法已经能跑，但确实还有点别扭。

如果每次都要输入：

使用 openspec-superpowers-bridge，
每个任务后运行 spec-compliance-check……

那就不算真正开箱即用。

更顺手的方式，是把触发规则写进项目指令或命令封装里。这样你照常执行 OpenSpec 和 Superpowers 的命令，Agent 自动把两个 skill 带起来。

但这里要先纠正一个容易踩的坑：

/opsx:apply <change-id>

这不是“只生成 Superpowers plan”的命令。

它是 OpenSpec 原生的执行命令，通常会进入代码实现阶段。

所以如果你想先审查 plan，再让 Superpowers 执行，最好单独封装：

/bridge:plan <change-id>
/bridge:execute <change-id>

方案 A：用项目指令自动触发

在 AGENTS.md、CLAUDE.md 或当前 Agent 宿主支持的项目指令里，加这一段：

## OpenSpec + Superpowers 自动触发规则

当用户执行或提到下面动作时，自动使用 `openspec-superpowers-bridge`：

- `/opsx:archive <change-id>`
- `/bridge:plan <change-id>`
- `/bridge:execute <change-id>`
- 实现 `openspec/changes/<change-id>`
- 继续当前 OpenSpec 变更实现
- 用 Superpowers 实现当前 OpenSpec 变更
- 执行 Superpowers 的实现命令、继续命令、审查命令、收尾命令

当用户执行 Superpowers 相关命令时，先检查当前项目是否存在活动 OpenSpec 变更：

- 如果只有一个 `openspec/changes/<change-id>`，自动使用它。
- 如果有多个活动变更，先让用户选择一个。
- 如果没有活动变更，就按普通 Superpowers 流程执行，不强行桥接。

桥接规则：

- `/bridge:plan` 只读取当前变更的 `proposal.md`、`design.md`、`tasks.md` 和所有 `spec.md`，然后生成 Superpowers plan 文件，不写业务代码。
- `/bridge:execute` 读取已经生成并确认过的 plan 文件，再调用 `superpowers:executing-plans` 执行。
- 如果用户直接执行 `/opsx:apply`，要提醒这是 OpenSpec 原生实现命令，会进入代码实现；不要把它当成“只生成 plan”的命令。
- Superpowers 实现命令启动时，先自动读取当前 OpenSpec 变更，再生成或加载 plan 文件。
- Superpowers 继续命令启动时，先恢复当前 OpenSpec 变更上下文，再调用 `superpowers:executing-plans` 继续 plan。
- Superpowers 每完成一个任务后，自动运行 `spec-compliance-check`。
- Superpowers 进入代码审查时，自动运行 `spec-compliance-check`。
- Superpowers 收尾时，先调用 `superpowers:finishing-a-development-branch`，再运行最终 `spec-compliance-check`。
- `/opsx:archive` 前，必须运行测试、OpenSpec 校验和最终 `spec-compliance-check`。
- 任一检查失败时，阻止归档。

加完以后，如果你只想先生成计划，用户只需要这样说：

/bridge:plan add-payment-callback-idempotency

Agent 应该自动理解成：

这是桥接计划生成命令。
先启动 openspec-superpowers-bridge。
读取 OpenSpec 变更文件。
把 OpenSpec tasks 转成 Superpowers plan 文件。
停下来等待用户确认，不要写业务代码。

确认 plan 没问题后，再执行：

/bridge:execute add-payment-callback-idempotency

这时才调用 superpowers:executing-plans 进入实现。

归档时也一样。

用户只需要说：

/opsx:archive add-payment-callback-idempotency

Agent 应该自动理解成：

归档前先跑最终规格合规检查、测试和 OpenSpec 校验。
任何一项不过，都不能归档。

这已经比手动喊两个 skill 顺很多。

方案 B：封装一个更短的桥接命令

如果你的 Agent 宿主支持自定义 slash command，我更建议再封装两个命令。

第一个叫：

/bridge:plan <change-id>

含义是：

读取 openspec/changes/<change-id>。
自动使用 openspec-superpowers-bridge。
把 tasks.md 转成 Superpowers plan 文件。
只生成和审查 plan，不写业务代码。

第二个叫：

/bridge:execute <change-id>

含义是：

读取已经确认过的 Superpowers plan 文件。
调用 superpowers:executing-plans 执行 plan。
每个任务后自动运行 spec-compliance-check。
任务完成后调用 superpowers:finishing-a-development-branch。

第三个叫：

/bridge:archive <change-id>

含义是：

读取 openspec/changes/<change-id>。
运行最终 spec-compliance-check。
运行测试。
运行 OpenSpec 校验。
全部通过后才允许执行归档。

这样读者真正要记的是三条：

/bridge:plan add-payment-callback-idempotency
/bridge:execute add-payment-callback-idempotency
/bridge:archive add-payment-callback-idempotency

OpenSpec 仍然负责规格，Superpowers 仍然负责执行，但用户不用每次手动拼一大段提示词。

这里有个细节一定要写清楚：

openspec-superpowers-bridge 不是直接替 Superpowers 执行任务，而是先生成 Superpowers plan 文件。

plan 文件开头可以这样写：

# Plan: add-payment-callback-idempotency

> 执行入口：必须使用 `superpowers:executing-plans` 逐项执行本计划。
> 收尾入口：全部任务完成后使用 `superpowers:finishing-a-development-branch`。
> 合规要求：每个任务完成后运行 `spec-compliance-check`。

## OpenSpec 来源

- 变更目录：`openspec/changes/add-payment-callback-idempotency/`
- 需求边界：读取 `proposal.md`
- 设计约束：读取 `design.md`
- 验收场景：读取 `specs/**/spec.md`
- 需求任务：读取 `tasks.md`

## Task 1：新增支付回调幂等表

- [ ] 写一个验证 `(channel, pay_trade_no)` 唯一约束的失败测试
- [ ] 运行目标测试，确认失败原因是缺少幂等表或唯一约束
- [ ] 新增 `payment_callback_idempotency` 建表脚本
- [ ] 再次运行目标测试，确认通过
- [ ] 运行 `spec-compliance-check`

这样 superpowers:executing-plans 拿到的不是一句“实现幂等”，而是一个可以逐项执行、逐项验证的计划。

方案 C：继续使用原生命令，但让 Agent 自动补桥

如果你不想新增 /bridge:* 命令，也可以继续用原生 OpenSpec 命令。

关键是项目指令里要写清楚：

看到 /bridge:plan，就只生成 Superpowers plan，不写业务代码。
看到 /bridge:execute，就调用 superpowers:executing-plans 执行 plan。
看到 /opsx:apply，要提醒用户这是 OpenSpec 原生实现命令，会直接进入代码实现。
看到 /opsx:archive，就自动启动 spec-compliance-check。
看到 Superpowers 开始实现 OpenSpec 任务，就自动读取当前 OpenSpec 变更，并生成 plan 文件。
看到 Superpowers 继续命令，就先恢复当前 OpenSpec 变更上下文，再调用 superpowers:executing-plans。
看到 Superpowers 审查命令，也先恢复当前 OpenSpec 变更上下文。
看到 Superpowers 收尾命令，就先恢复当前 OpenSpec 变更上下文，再调用 superpowers:finishing-a-development-branch。

这不是修改 OpenSpec 或 Superpowers 源码。

它是在 Agent 的项目规则层做自动分流。

对大多数个人项目和团队项目来说，这已经够用了。

方案 D：Superpowers 命令反向触发桥接

还有一种更符合直觉的方式：

你不从 OpenSpec 命令入口开始，而是直接执行 Superpowers 的实现流程。

这时桥接规则也应该生效。

比如用户说：

用 Superpowers 继续实现当前任务

Agent 不应该直接进入普通实现流程，而应该先做一次轻量检测：

1. 当前项目是否存在 openspec/changes/？
2. 是否只有一个活动变更？
3. 如果有活动变更，是否已经读取 proposal、design、tasks、spec？
4. 如果没有读取，先自动加载 openspec-superpowers-bridge。
5. 如果还没有 plan 文件，先把 OpenSpec tasks 转成 Superpowers plan 文件。
6. 调用 superpowers:executing-plans 执行 plan。
7. 任务完成后调用 superpowers:finishing-a-development-branch 收尾。

这样触发路径就变成双向的：

OpenSpec 命令 -> 自动加载桥接 -> superpowers:executing-plans
Superpowers 命令 -> 自动检测 OpenSpec -> 加载桥接 -> superpowers:executing-plans

这才是真正少心智负担的版本。

第八步，先用 TodoList 跑一个完整闭环

支付回调幂等适合讲工程边界，但第一次验证桥接链路，最好别上来就搞这么重。

先拿 TodoList 跑一遍。

目标很简单：

实现一个 TodoList：
- 可以新增 todo
- 可以查看 todo 列表
- 可以把 todo 标记为完成
- 已完成 todo 在列表里要能看出来
- 暂时不做登录、权限、数据库持久化

如果你用的是 ccgui，可以先别手动敲一堆命令。

前提是两件事已经具备：

1. 当前项目已经可以使用 OpenSpec。
2. 当前 ccgui 连接的 Agent 宿主已经启用 Superpowers。

如果缺任何一个，下面这段提示词会要求 Agent 先停下来提醒你，不要假装已经配置好了。

直接把下面这一整段复制进去：

我要用 OpenSpec + Superpowers 做一个最小 TodoList 功能，请按下面流程自动执行。

目标：
- 实现一个本地 TodoList
- 可以新增 todo
- 可以查看 todo 列表
- 可以把 todo 标记为完成
- 已完成 todo 在列表里要能看出来

不做事项：
- 不做登录
- 不做权限
- 不接数据库
- 不做多人协作
- 不做复杂标签、搜索、排序
- 不引入新的生产依赖，除非先征求我确认

请按这个桥接流程执行：

1. 先检查当前项目是否已经初始化 OpenSpec；如果没有，请提醒我执行 `openspec init`，不要直接乱建目录。
2. 先确认当前 Agent 宿主是否已经启用 Superpowers；如果没有，请提醒我安装或启用 Superpowers，不要继续实现。
3. 创建 OpenSpec 变更：`add-todo-list`。
4. 生成并检查这些文件：
   - `openspec/changes/add-todo-list/proposal.md`
   - `openspec/changes/add-todo-list/design.md`
   - `openspec/changes/add-todo-list/tasks.md`
   - `openspec/changes/add-todo-list/specs/todo-list/spec.md`
5. `proposal.md` 必须写清楚“不做事项”。
6. `design.md` 必须写清楚：
   - 使用内存存储
   - todo 包含 id、title、completed
   - 新增 todo 时 completed 默认为 false
   - 标记完成时只修改 completed，不修改 title
   - 禁止引入用户、权限、数据库、网络 API
7. `spec.md` 至少包含两个验收场景：
   - 新增 todo 后能在列表中看到，状态为未完成
   - 标记 todo 为完成后，状态变成已完成
8. 只生成 Superpowers plan 文件，不要写业务代码：
   - `docs/superpowers/plans/add-todo-list.md`
9. plan 文件开头必须写：
   - 执行入口：`superpowers:executing-plans`
   - 收尾入口：`superpowers:finishing-a-development-branch`
   - 合规要求：每个任务完成后运行 `spec-compliance-check`
10. plan 生成后先停下来，输出 plan 摘要，等待我确认。
11. 我确认后，再调用 `superpowers:executing-plans` 逐项执行 plan。
12. 每个任务完成后运行 `spec-compliance-check`，检查：
    - 是否覆盖 OpenSpec 验收场景
    - 是否违反“不做事项”
    - 是否违反 design.md 的必须/禁止规则
13. 所有任务完成后，调用 `superpowers:finishing-a-development-branch`。
14. 归档前先运行：
    - 目标测试
    - 全量测试，无法运行时说明原因
    - OpenSpec 校验
    - 最终 `spec-compliance-check`
15. 全部通过后，再执行 OpenSpec 归档。

执行约束：
- 修改代码前先阅读相关文件。
- 不要擅自覆盖用户已有改动。
- 一次只执行一个 plan task。
- 如果发现多个 OpenSpec 活动变更，先让我选择。
- 如果任何合规检查失败，不要归档，先报告失败原因和修复建议。

这段提示词的效果，是让 ccgui 里当前 Agent 自动走完整链路：

OpenSpec 变更
  -> 生成 proposal/design/spec/tasks
  -> 生成 Superpowers plan
  -> 等待用户确认 plan
  -> superpowers:executing-plans
  -> spec-compliance-check
  -> superpowers:finishing-a-development-branch
  -> OpenSpec 校验和归档

如果你已经把自动触发规则写进项目指令，那提示词还能更短：

用 OpenSpec + Superpowers 实现 add-todo-list。
需求：新增 todo、查看列表、标记完成。
不做：登录、权限、数据库、多人协作、复杂标签搜索排序。
请自动生成 OpenSpec 变更和 Superpowers plan，先停下来等我确认。
我确认后，再用 superpowers:executing-plans 执行。
每个任务后运行 spec-compliance-check，收尾使用 superpowers:finishing-a-development-branch。

这个例子小，但它能把完整链路跑通：

/opsx:propose add-todo-list
  -> 生成 OpenSpec 变更

/bridge:plan add-todo-list
  -> 自动触发 openspec-superpowers-bridge
  -> 生成 Superpowers plan 文件

人工确认 plan

/bridge:execute add-todo-list
  -> 调用 superpowers:executing-plans
  -> 每个任务后运行 spec-compliance-check

/opsx:archive add-todo-list
  -> 最终合规检查
  -> 测试
  -> OpenSpec 校验
  -> 归档

1. 创建 OpenSpec 变更

先执行：

/opsx:propose add-todo-list

你要让 OpenSpec 生成类似这样的结构：

openspec/
  changes/
    add-todo-list/
      proposal.md
      design.md
      tasks.md
      specs/
        todo-list/
          spec.md

proposal.md 可以长这样：

# 提案：add-todo-list

## 背景

当前项目还没有最小任务管理能力。需要先实现一个本地 TodoList，
用于验证 OpenSpec + Superpowers 的桥接开发流程。

## 变更内容

- 新增 todo 数据结构
- 支持新增 todo
- 支持查看 todo 列表
- 支持标记 todo 为完成
- 已完成 todo 在列表中有明确状态

## 不做事项

- 不做用户登录
- 不做权限系统
- 不接数据库
- 不做多人协作
- 不做复杂标签、搜索、排序

spec.md 写成验收场景：

### 需求：TodoList 基础能力

系统必须支持新增、查看、完成 todo。

#### 场景：新增 todo 后能在列表中看到

- 假设当前 todo 列表为空
- 当用户新增一个内容为“写文章”的 todo
- 那么 todo 列表中应该出现“写文章”
- 并且它的状态应该是未完成

#### 场景：标记 todo 为完成

- 假设 todo 列表里有一个未完成的“写文章”
- 当用户把它标记为完成
- 那么 todo 列表中“写文章”的状态应该变成已完成

design.md 不需要复杂，但要写边界：

## TodoList 设计

- 必须先使用内存存储，避免引入数据库依赖。
- todo 必须包含 id、title、completed 三个字段。
- 新增 todo 时 completed 默认为 false。
- 标记完成时只能修改 completed，不要修改 title。
- 禁止引入用户、权限、数据库、网络 API 等额外能力。

tasks.md 保持需求视角：

## 任务

- [ ] 新增 Todo 数据结构
- [ ] 新增 TodoList 服务
- [ ] 支持新增 todo
- [ ] 支持查看 todo 列表
- [ ] 支持标记 todo 为完成
- [ ] 补充规格合规检查

2. 先生成 Superpowers plan，不要直接 apply

这里不要执行：

/opsx:apply add-todo-list

因为 /opsx:apply 会进入 OpenSpec 原生实现流程，可能直接开始改代码。

我们要先生成并审查 Superpowers plan。

执行：

/bridge:plan add-todo-list

如果你的环境没有自定义 /bridge:plan 命令，就在 ccgui 里直接说：

请使用 openspec-superpowers-bridge 读取 openspec/changes/add-todo-list，
只生成 docs/superpowers/plans/add-todo-list.md，
不要写业务代码，等我确认 plan 后再执行。

桥接技能应该先生成一个 plan 文件，比如：

docs/superpowers/plans/add-todo-list.md

plan 文件开头要明确写执行入口：

# Plan: add-todo-list

> 执行入口：必须使用 `superpowers:executing-plans` 逐项执行本计划。
> 收尾入口：全部任务完成后使用 `superpowers:finishing-a-development-branch`。
> 合规要求：每个任务完成后运行 `spec-compliance-check`。

## OpenSpec 来源

- 变更目录：`openspec/changes/add-todo-list/`
- 需求边界：读取 `proposal.md`
- 设计约束：读取 `design.md`
- 验收场景：读取 `specs/todo-list/spec.md`
- 需求任务：读取 `tasks.md`

## Task 1：新增 Todo 数据结构

- [ ] 先写一个失败测试，验证 Todo 包含 id、title、completed
- [ ] 运行目标测试，确认失败
- [ ] 新增 Todo 数据结构
- [ ] 再次运行目标测试，确认通过
- [ ] 运行 `spec-compliance-check`

## Task 2：支持新增 todo

- [ ] 先写一个失败测试：新增“写文章”后，列表能查到它
- [ ] 运行目标测试，确认失败
- [ ] 实现新增 todo 的最小逻辑
- [ ] 再次运行目标测试，确认通过
- [ ] 运行 `spec-compliance-check`

## Task 3：支持标记完成

- [ ] 先写一个失败测试：标记完成后 completed 变成 true
- [ ] 运行目标测试，确认失败
- [ ] 实现标记完成逻辑
- [ ] 再次运行目标测试，确认通过
- [ ] 运行 `spec-compliance-check`

这段代码块只是 plan，不应该直接改业务代码。

确认 plan 没问题后，再执行：

/bridge:execute add-todo-list

如果没有 /bridge:execute，就在 ccgui 里说：

请使用 superpowers:executing-plans 执行 docs/superpowers/plans/add-todo-list.md。
每完成一个任务后运行 spec-compliance-check。

注意，这里真正执行计划的不是桥接技能。

桥接技能只是生成计划和上下文。

真正进入开发执行时，必须调用：

superpowers:executing-plans

3. 执行过程中自动合规检查

每做完一个任务，都要跑一遍 spec-compliance-check。

比如 Task 2 完成后，合规检查至少要问：

新增 todo 后是否能在列表中看到？
completed 是否默认为 false？
是否违反“不接数据库”的不做事项？
是否引入了登录、权限、网络 API 等额外能力？

如果 AI 顺手加了数据库表，比如：

todo_item 表
todo_user 表

这不是“实现更完整”。

这是违反了 proposal.md 和 design.md。

应该直接判失败。

4. 收尾和归档

所有 plan 任务完成后，先进入 Superpowers 收尾：

superpowers:finishing-a-development-branch

然后再执行：

/opsx:archive add-todo-list

归档前至少卡住：

- TodoList 的验收场景都有测试覆盖
- 没有违反“不做事项”
- design.md 里的“必须/禁止”都满足
- 目标测试通过
- OpenSpec 校验通过
- spec-compliance-check 通过

这个 TodoList 例子虽然简单，但它已经把开箱即用的桥接链路完整跑了一遍。

你后面再换成支付回调幂等、优惠券规则、订单状态机，本质上只是规格和测试变复杂了。

链路不变：

OpenSpec 产物 -> 桥接技能 -> Superpowers plan -> superpowers:executing-plans -> 合规检查 -> 收尾 -> 归档

第九步，再看一个更真实的支付回调场景

假设你已经有这个 change：

openspec/changes/add-payment-callback-idempotency/

如果没有配置自动触发，你可以直接对 Agent 说：

使用 openspec-superpowers-bridge，
实现 openspec/changes/add-payment-callback-idempotency。
先读取 proposal.md、design.md、tasks.md 和 specs，
只把 tasks 转成 Superpowers plan 文件，
不要写业务代码，
等我确认 plan 后再调用 superpowers:executing-plans。

如果已经配置了自动触发，先执行这一句生成 plan：

/bridge:plan add-payment-callback-idempotency

确认 plan 没问题后，再执行：

/bridge:execute add-payment-callback-idempotency

这里不要把 /opsx:apply 当成“只生成 plan”的命令，它会进入 OpenSpec 原生实现阶段。

一个合格的桥接输出，不应该马上开始改代码。

它应该先给你这种摘要：

选中的变更：add-payment-callback-idempotency

目标：
- 防止重复回调产生重复支付流水和重复 OrderPaidEvent。

不做事项：
- 不修改支付渠道回调协议。
- 不重做 PaymentGateway 抽象。
- 不改变订单状态机定义。

设计约束：
- 必须使用数据库唯一约束。
- 唯一键必须是 (channel, pay_trade_no)。
- 必须在事务提交后发布 OrderPaidEvent。
- 禁止把本地内存幂等作为主方案。

验收场景：
- 首次回调处理成功。
- 重复成功回调返回 SUCCESS，但没有副作用。
- 同一笔回调并发到达时只处理一次。
- 金额不一致时不触发发货。

Superpowers plan 文件：
- docs/superpowers/plans/add-payment-callback-idempotency.md

执行入口：
- superpowers:executing-plans

收尾入口：
- superpowers:finishing-a-development-branch

计划任务：
1. 数据库唯一约束测试
2. 重复回调服务测试
3. 并发重复回调服务测试
4. 事务提交后事件发布测试
5. 最终规格合规检查和 OpenSpec 校验

你看，这时候 Superpowers 才真正有了施工图。

如果没有桥接，它拿到的是一句“实现幂等”。

有了桥接，它拿到的是带边界、约束、验收场景和测试顺序的 plan 文件，再由 superpowers:executing-plans 执行，最后用 superpowers:finishing-a-development-branch 收尾。

桥接层怎么把 tasks.md 转成 TDD 原子步骤

OpenSpec 的任务：

- [ ] 新增支付回调幂等表

不能直接丢给实现 Agent。

桥接技能要展开成：

任务 1：新增支付回调幂等表

1. 先写一个针对 channel + payTradeNo 唯一约束的失败测试。
2. 运行目标数据访问层测试，并确认它按预期失败。
3. 新增 payment_callback_idempotency 建表脚本。
4. 新增实体和数据访问层插入方法。
5. 再运行目标数据访问层测试，并确认通过。
6. 运行 `spec-compliance-check` 检查设计约束。
7. 更新 OpenSpec 任务进度。

OpenSpec 的任务：

- [ ] 补充并发重复回调测试

桥接技能要展开成：

任务 4：补充并发重复回调测试

1. 先写一个同 channel + payTradeNo 的并发失败测试。
2. 断言只插入一条支付流水。
3. 断言只发布一次 OrderPaidEvent。
4. 断言两次回调结果都是 SUCCESS。
5. 运行目标测试，并确认它按预期失败。
6. 实现最小的唯一键冲突处理逻辑。
7. 再运行目标测试，并确认通过。
8. 运行 `spec-compliance-check` 检查验收场景覆盖情况。

这就是很多人说“自动化桥接”时没讲清楚的地方。

桥接不是把两个工具名字连起来。

桥接是做粒度转换：

需求任务 -> TDD 任务
业务场景 -> 测试断言
设计约束 -> 代码审查闸门
不做事项 -> 代码差异审查规则

最容易失败的 6 个位置

我把实际落地里最容易翻车的位置画成一张表。

失败点	表现	解决办法
Superpowers 没装到当前宿主	Agent 不触发测试驱动开发 / 代码审查流程	先确认宿主插件或扩展已启用
OpenSpec 没初始化到项目	没有 openspec/ 目录	在项目根目录执行 openspec init
proposal 没写“不做事项”	AI 顺手扩大需求	在桥接前补齐“不做事项”
design 没写“必须/禁止”	实现方案可随意替换	把硬约束写成可检查规则
tasks 粒度太粗	一次改动过大，难审查	桥接技能转成 TDD 原子步骤
归档前没验收	错误规范进入主线	测试、合规检查、OpenSpec 校验全部通过

这张表有个重点：

不要把所有问题都甩给工具。

工具能做的是强制流程。

但业务边界、不做事项、关键设计约束，仍然需要你拍板。

一套可以直接复制的工作流

如果你只想要命令清单，可以照这个跑。

1. 安装 Superpowers

按你的宿主选择一种。

Claude Code：

/plugin install superpowers@claude-plugins-official

Codex CLI：

/plugins

Gemini CLI：

gemini extensions install https://github.com/obra/superpowers

2. 安装 OpenSpec

node -v
npm install -g @fission-ai/openspec@latest
cd your-project
openspec init

3. 创建 OpenSpec 变更

/opsx:propose add-payment-callback-idempotency

人工检查：

proposal.md 是否有“不做事项”
spec.md 是否有可验收场景
design.md 是否有“必须/禁止”
tasks.md 是否是需求视角清单

4. 放入两个 skill，并配置自动触发

.codex/skills/spec-compliance-check/SKILL.md
.codex/skills/openspec-superpowers-bridge/SKILL.md

如果你不是 Codex，就放到当前 Agent 宿主支持的技能目录。

然后在项目指令里加自动触发规则：

看到 /bridge:plan，就只生成 Superpowers plan，不写业务代码。
看到 /bridge:execute，就调用 superpowers:executing-plans 执行 plan。
看到 /opsx:apply，要提醒用户这是 OpenSpec 原生实现命令，会直接进入代码实现。
看到 /opsx:archive，就自动启动 spec-compliance-check。
看到 Superpowers 开始实现 OpenSpec 任务，就自动读取当前 OpenSpec 变更并生成 plan 文件。
看到 Superpowers 继续命令，就先恢复当前 OpenSpec 变更上下文，再调用 superpowers:executing-plans。
看到 Superpowers 审查命令，也先恢复当前 OpenSpec 变更上下文。
看到 Superpowers 收尾命令，就先恢复当前 OpenSpec 变更上下文，再调用 superpowers:finishing-a-development-branch。
如果存在多个 OpenSpec 活动变更，先让用户选择一个。

5. 启动桥接实现

先生成 plan：

/bridge:plan add-payment-callback-idempotency

人工确认 plan 后，再执行：

/bridge:execute add-payment-callback-idempotency

这个两阶段流程不会把“生成 plan”和“写代码”混在一起。

如果你是从 Superpowers 入口启动，也应该自动触发：

用 Superpowers 实现当前 OpenSpec 变更
用 Superpowers 继续当前任务
用 Superpowers 审查当前实现
用 Superpowers 收尾当前分支

这些命令的第一步都不是直接写代码，而是先检查 openspec/changes/，恢复当前 OpenSpec 变更上下文。

6. 归档前卡闸

归档闸门：

- proposal.md 的“不做事项”没有被违反
- 所有 spec.md 验收场景均有测试或明确说明
- design.md 的“必须/禁止”规则全部满足
- 目标测试通过
- 全量测试通过，或明确说明无法运行原因
- OpenSpec 校验通过
- Superpowers 代码审查无阻断问题

只有这些都过了，再执行归档。

对应命令可以是：

/opsx:archive add-payment-callback-idempotency

或者：

/bridge:archive add-payment-callback-idempotency

这个方案的边界

这套桥接能解决“执行链路不稳定”的问题。

但它不是银弹。

它不能替你判断一个业务需求是不是合理。

它不能替你决定支付幂等到底用数据库唯一键、分布式锁，还是状态机重构。

它也不能保证 AI 每次都写出完美代码。

它真正能保证的是：

AI 改代码前必须读规格。
AI 执行任务时必须按 TDD 粒度拆。
AI 做代码审查时必须检查 OpenSpec 合规。
AI 归档前必须通过测试和 OpenSpec 校验。

这已经足够解决大部分“我看了很多文章，但还是不知道怎么桥接”的问题。

因为开箱即用的关键不是少写几个命令。

而是把该人工记忆的流程，沉淀成 Agent 必须遵守的规则。

最后回到评论区那个问题

“自动化桥接有没有开箱即用的？”

有。

但不是一个装完就万事大吉的魔法按钮。

更现实的开箱即用，是三件东西：

Superpowers 装到 Agent 宿主里
OpenSpec 初始化到项目仓库里
桥接技能放到项目或个人技能目录里
项目指令写好自动触发规则

然后先用这一句生成 plan：

/bridge:plan <change-id>

确认 plan 后，再执行：

/bridge:execute <change-id>

如果你的团队已经在用 AI 写复杂需求，我建议先别急着追更多 Agent。

先把这条桥接链路跑顺。

因为大型项目里，真正稀缺的不是会写代码的 AI。

而是让 AI 不越界、不漏测、不把错误规范归档成系统事实的工程纪律。

参考资料

Superpowers GitHub README：https://github.com/obra/superpowers
OpenSpec GitHub README：https://github.com/Fission-AI/OpenSpec
OpenSpec installation docs：https://github.com/Fission-AI/OpenSpec/blob/main/docs/installation.md
OpenSpec opsx workflow：https://github.com/Fission-AI/OpenSpec/blob/main/docs/opsx.md

本文参与腾讯云自媒体同步曝光计划，分享自微信公众号。

原始发表：2026-06-15，如有侵权请联系 cloudcommunity@tencent.com 删除

并发