#OpenSpec + Superpowers 双层规划

对于中大型项目，单一工具往往不够。OpenSpec 负责顶层架构规划（做什么），Superpowers 负责执行细节落地（怎么做），两者形成双层规划模式。

#为什么需要双层规划

#适用场景

• 多模块、接口复杂的中大型工程
• 需要长期迭代维护的项目
• 多人协作、需要统一架构规范的团队
• 对接口契约和数据结构有严格要求的企业级项目

#七步工作流

以"企业级 Express 接口限流中间件"为例：

#第一步：OpenSpec 锁定架构契约

> /opsx:propose 设计企业级限流中间件，定义配置结构、接口类型、错误规范、模块拆分

产出：

• 完整模块架构划分（配置模块、限流计算模块、异常模块）
• 固定数据结构、入参出参、错误码、字段约束
• 顶层宏观实现方案，形成不可随意变更的技术契约

#第二步：Superpowers 细化执行计划

基于已固化的架构契约，Superpowers 将宏观设计拆解为可逐条执行的开发任务：

> /superpowers:writing-plans
> 基于 OpenSpec 的架构规范，拆分最小执行开发步骤

产出：

• 目录结构创建顺序
• 模块编码优先级
• 依赖注入与集成顺序
• 单元测试编写节点
• 集成调试里程碑

#第三步：TDD 驱动编码

> /superpowers:subagent-driven-development

严格依照细化步骤，逐模块创建文件、编写代码，所有实现严格匹配 OpenSpec 架构规范。

#第四步：系统化调试

> /superpowers:systematic-debugging
> 高并发下限流统计异常

定位代码问题，修改后校验是否符合原始架构契约。

#第五步：TDD 加固

> /superpowers:test-driven-development
> 限流核心计算逻辑的边界测试

为核心模块编写边界测试，保证架构设计的功能稳定性。

#第六步：代码审查

> /superpowers:requesting-code-review

校验代码与 OpenSpec 架构规范一致性，统一代码规范。

#第七步：归档

> /opsx:archive

将最终架构规范、接口文档、代码实现永久归档，作为后续迭代的唯一依据。

#双层规划的关系

OpenSpec（顶层）                    Superpowers（执行层）
  ┌─────────────────┐                ┌─────────────────┐
  │  /opsx:propose  │  锁定架构契约  │  /writing-plans │  拆解执行步骤
  │  specs/         │ ─────────────→ │  plans/         │
  │  design.md      │                │  TDD + 审查     │
  │  tasks.md       │                │  验证 + 收尾    │
  └─────────────────┘                └─────────────────┘
        ↓ 归档                              ↓ 代码
  openspec/specs/                     src/ + tests/
  （活文档，描述系统现状）            （可运行的代码）

1. OpenSpec 负责定大方向，解决项目"做成什么样"
2. Superpowers 负责拆小动作，解决代码"按什么顺序写"
3. 两层规划互不冲突，架构稳定且落地可控

#桥接配置：让两层真正连通

双层规划最大的风险是"两层断裂"——OpenSpec 生成了规格，Superpowers 却从零开始头脑风暴，完全浪费了规格文档。以下是让两层真正连通的配置方法。

#方案一：superpowers-bridge Schema

在 openspec/config.yaml 中指定 bridge schema：

schema: superpowers-bridge
context:
  stack: 'Express + TypeScript + Prisma'
  testing: 'Vitest'
  language: '中文（简体）'
bridge:
  apply_skill: 'superpowers:subagent-driven-development'

配置后，/opsx:apply 会自动调用 Superpowers 的子智能体驱动开发来执行 tasks.md 中的任务。

#方案二：手动串联

不使用 bridge schema，手动在 Apply 后调用 Superpowers：

> /opsx:propose add-payment
> 创建支付功能的规格文档

> （审阅规格文档后）

> 使用 Superpowers 子智能体驱动开发，按照 OpenSpec 的 tasks.md 逐个实现

这种方式更灵活，但需要你手动告诉 Superpowers 去读 OpenSpec 的规格。

#子智能体的职责

无论哪种方案，每个子智能体在执行任务时必须：

读取（输入）：

1. tasks.md 中的当前任务
2. proposal.md 中的目标和排除项
3. design.md 中的技术边界和架构决策
4. specs/ 中对应的需求规格
5. AGENTS.md / CLAUDE.md 中的项目规范

报告（输出）：

1. 修改了哪些文件
2. 运行了哪些验证命令及输出
3. 测试结果（通过/失败）
4. 未验证的路径（需要人工检查）
5. tasks.md 复选框是否可以勾选

#新手四步工作流

第一次使用双层规划？按以下步骤逐步引入：

#第 1 步：安装 Superpowers

> /plugin install superpowers@claude-plugins-official

用 brainstorming 先把需求梳理清楚。

#第 2 步：安装 OpenSpec

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

用 /opsx:propose 将梳理清楚的需求规格化。

#第 3 步：配置桥接

在 openspec/config.yaml 中配置 superpowers-bridge schema。

#第 4 步：执行并归档

> /opsx:apply
> （Superpowers 子智能体自动按规格 TDD 实现）

> /opsx:archive
> （归档规格，成为下次变更的基线）

#相关资源

• OpenSpec 规格驱动开发 — OpenSpec 完整文档
• Superpowers 插件 — Superpowers 完整文档
• 最佳实践：四阶段工作流 — 更多工具组合场景