openspec与superpowers配合使用示例

OpenSpec(opsx) + Superpowers 完整协同实战示例

整体协同流程总链路

1. /opsx:explore 技术预研、架构评估、方案选型（只调研，不落地编码）
2. /opsx:propose 输出正式架构/技术规范 Spec 文档（锁定技术约束）
3. /superpowers:brainstorm 基于 Spec 约束做业务功能标准化设计
4. /superpowers:write-plan 拆分开发任务
5. /superpowers:execute 编码实现，严格遵循 Spec 规范
6. /superpowers:review 代码校验是否符合 OpenSpec 约束
7. /opsx:archive 归档 Spec、设计方案、代码变更全套资料

实战场景背景

现有 SpringBoot + Redis + MySQL 项目，需求：新增每日签到积分模块
约束：

• 高并发签到防重复
• 积分变更必须记录流水
• 接口统一 Bearer Token 鉴权
• 禁止数据库频繁行锁，优先 Redis 前置拦截

步骤1：/opsx:explore 技术预研（OpenSpec 调研阶段）

输入指令：

/opsx:explore
需求：实现每日用户签到发积分，现有SpringBoot+Redis+MySQL。对比两种防重复方案：
方案1：数据库唯一索引+事务
方案2：Redis 当日签到标记 + 异步落库签到日志
分析并发、锁冲突、性能、运维成本、数据一致性风险，给出选型结论

输出内容：

1. 两套方案对比矩阵（并发上限、DB压力、故障兜底、开发复杂度）
2. 风险清单：DB索引方案高峰期锁等待、慢SQL；Redis方案存在缓存丢失风险及兜底策略
3. 最终选型：Redis标记+异步日志，搭配定时任务补全不一致数据
4. 技术约束清单：Key命名规范、过期时间、异步线程池配置、积分事务规则

阶段目标：敲定底层技术路线，产出不可突破的技术边界。

步骤2：/opsx:propose 生成正式 OpenSpec 规范文档

输入指令：

/opsx:propose
基于上面explore调研结论，生成签到积分模块OpenSpec规范文档，存放于specs/sign-point.spec.md
规范包含：缓存Key规范、数据库表结构、积分变更事务规则、异步日志要求、接口鉴权统一标准、异常码规范

AI 行为：

1. 生成标准化 spec 文档写入项目 specs/sign-point.spec.md
2. 定义全局强制约束，后续所有开发必须遵循此 Spec
3. 输出 Spec 摘要，明确不可修改的技术规则

示例 Spec 片段约束：

# 缓存Key规范
sign:uid:{userId}:date:{yyyyMMdd} 过期时间24h
# 强制规则
1. 签到判定先走Redis，禁止直接查DB判断当日签到
2. 积分增减必须生成point_flow流水记录，不可省略
3. 日志落库采用@Async，主线程不阻塞

步骤3：/superpowers:brainstorm 基于Spec做业务设计（Superpowers门禁）

输入指令：

/superpowers:brainstorm
开发每日签到积分发放接口，严格遵循 specs/sign-point.spec.md 所有技术约束
业务需求：每日首次签到+10积分，重复签到不发分；Bearer Token鉴权；返回当前用户总积分、今日是否已签到

AI 执行逻辑：

1. 自动读取 specs/sign-point.spec.md，所有设计不能违反Spec约束
2. 分步澄清接口请求方式、异常返回、分页/拓展字段等业务细节
3. 输出2套业务实现方案，但两套方案底层均采用Spec规定的Redis前置逻辑
4. 分段展示完整业务设计（接口定义、表变更、业务流程、异常处理），每段等待确认
5. 全部确认后自动归档业务设计文档到 docs/plans/sign-in-plan.md

关键协同点：Superpowers 会主动校验设计是否冲突 OpenSpec，若你提出违背Spec的方案，会主动拦截并提示规范要求。

步骤4：/superpowers:write-plan 生成开发任务清单

输入：

/superpowers:write-plan

产出任务清单，每一条任务都会标注对应 Spec 条款：

1. 数据库：创建point_flow积分流水表（Spec 3.2）
2. DTO：签到请求/返回实体
3. 鉴权拦截器校验Bearer Token（Spec 4.1）
4. Redis工具封装签到Key生成逻辑（Spec 2.1 Key规范）
5. Service签到主逻辑：Redis前置判断+异步日志（Spec 3.1）
6. Controller暴露POST签到接口
7. 全局异常统一错误码（Spec 4.2）
8. 单元测试：重复签到、Redis失效兜底场景

步骤5：/superpowers:execute 编码落地（严格对齐Spec）

输入：

/superpowers:execute

AI 编码时自动遵守 OpenSpec 全部约束：

• Redis Key 严格按 spec 命名，过期时间24小时
• 签到判断优先查Redis，不会写出直接查数据库的逻辑
• 积分变动强制插入流水，使用异步保存日志
  所有代码变更完成后输出文件变更清单。

步骤6：/superpowers:review 代码合规校验（联动OpenSpec）

输入：

/superpowers:review

评审重点分两层：

1. 业务逻辑bug、空值、并发漏洞
2. OpenSpec合规检查：扫描代码是否违反specs/sign-point.spec.md规则
   若发现代码不满足Spec约束，会直接给出修复补丁并标注对应规范条款。

步骤7：/opsx:archive 全链路资料归档（OpenSpec收尾）

输入指令：

/opsx:archive
本次签到积分模块变更，归档内容：explore调研记录、sign-point.spec.md、superpowers业务设计plan文档、本次所有代码变更记录、review评审报告

AI 行为：

1. 打包本次完整交付资产，生成归档变更记录
2. 标记 Spec 版本，便于后续迭代追溯架构源头
3. 流程闭环，本次预研-规范-设计-开发-评审全链路留存可追溯文档

组合使用核心优势总结

1. OpenSpec 管底层技术约束：统一架构、中间件、存储规范，防止开发随意选技术方案
2. Superpowers 管上层业务交付：标准化需求梳理、编码任务拆分、强制设计确认
3. 强约束联动：Superpowers 自动读取 Spec，业务设计、编码、评审全程受技术规范限制，架构不跑偏
4. 完整追溯链路：从前期技术调研 → 架构规范 → 业务设计 → 代码 → 归档，全流程可复盘

极简快速协同模板（日常复用）

# 1. 技术调研选型
/opsx:explore [你的技术问题/改造需求]

# 2. 锁定架构规范
/opsx:propose 输出xxx.spec.md

# 3. 业务功能标准化设计
/superpowers:brainstorm 基于xxx.spec.md开发[业务需求]

# 4. 开发落地三步骤
/superpowers:write-plan
/superpowers:execute
/superpowers:review

# 5. 归档全流程资产
/opsx:archive