OpenSpec + Superpowers 联合开发工作流

OpenSpec : 需求 → 结构化制品（proposal / spec / design / tasks），解决"做什么" Superpowers: brainstorming → worktree → plan → subagent → TDD → review → finish，解决"怎么做好" 本文档：二者如何结合，以及如何应对任务中断和上下文丢失

---

两套系统的关系

┌─────────────────────────────────────────────────────────┐
│                    OpenSpec (需求层)                      │
│                                                           │
│  explore → propose → continue → apply → verify → archive │
│     │          │                   │                      │
│  梳理需求   生成制品             逐任务实现               │
│             (proposal.md                                  │
│              design.md                                    │
│              tasks.md)                                    │
└─────────┬──────────────────────────┬────────────────────┘
          │                          │
          │ 制品 = 持久化的需求记忆   │ tasks.md = 进度跟踪
          │                          │
┌─────────▼──────────────────────────▼────────────────────┐
│                  Superpowers (工程层)                      │
│                                                           │
│  brainstorming → git-worktree → writing-plans             │
│       → subagent-driven-dev → TDD → code-review           │
│       → verification → finishing-branch                    │
│                                                           │
│  隔离工作区、子代理执行、测试驱动、代码审查、分支收尾      │
└─────────────────────────────────────────────────────────┘

简单理解：

• OpenSpec 管「需求到任务」的拆解和持久化
• Superpowers 管「任务到代码」的工程质量和执行效率
• 二者通过 磁盘上的 Markdown 文件 连接，这也是对抗 AI 遗忘的关键

---

完整流程（从产品文档到上线）

Phase 1: 需求梳理

有两条路径可选：

路径	工具	适用场景
A. OpenSpec Explore	/opsx:explore	需求模糊，想先讨论
B. Superpowers Brainstorming	自动触发	需求相对明确，直接设计

路径 A --- OpenSpec Explore（推荐用于"只有截图+字段表"的场景）：

/opsx:explore

产品给了「供应商审核」的原型截图和字段文档：
[拖入截图]
[粘贴字段表]

Explore 模式是只读思考伙伴：

• 从截图提取页面结构、字段、操作按钮
• 从字段文档结构化数据模型
• 画 ASCII 图理清状态流转
• 不写代码，只输出理解

梳理清楚后自然过渡到 Phase 2。

路径 B --- Superpowers Brainstorming：

直接告诉 AI 要做什么，Superpowers 自动进入 brainstorming 流程：

1. 探索项目现有结构
2. 一次问一个问题澄清需求
3. 提出 2-3 种方案 + 推荐
4. 分段展示设计，逐段确认
5. 写入 docs/superpowers/specs/ 并 commit

Phase 2: 生成结构化制品

使用 OpenSpec Propose 一步到位：

/opsx:propose supplier-review

开发 admin-portal 的「供应商审核」模块。
[截图 + 字段说明 + 业务规则]

自动生成：

openspec/changes/supplier-review/
├── proposal.md    ← 做什么、范围、能力列表
├── design.md      ← 文件结构、组件拆分、API 设计
└── tasks.md       ← checkbox 任务清单

或者，如果已经通过 Brainstorming 产出了设计文档，可以：

1. 将 docs/superpowers/specs/ 下的设计文档作为输入
2. 用 /opsx:propose 时附上，让 OpenSpec 制品与 Superpowers 设计保持一致

Phase 3: 工作区隔离

Superpowers 的 git-worktree 自动触发：

开始实现 supplier-review

Superpowers 会：

1. 创建 .worktrees/supplier-review 隔离工作区
2. 新建 feature/supplier-review 分支
3. 运行 pnpm install 安装依赖
4. 验证测试基线通过

为什么要隔离： 主工作区保持干净，多个功能可以并行开发互不干扰。

Phase 4: 逐任务实现

OpenSpec Apply + Superpowers Subagent 联合驱动：

/opsx:apply

执行引擎有两种模式：

模式 A --- Subagent-Driven（推荐，大功能用）：

主 Agent（协调者，上下文最小化）
  │
  ├─ 读 tasks.md，提取 Task 1 的完整描述
  │
  ├─ 派发 Subagent 1 实现 Task 1
  │   └─ Subagent 遵循 TDD：写测试 → 红 → 实现 → 绿 → 重构
  │
  ├─ 派发 Spec Reviewer 检查是否符合 design.md
  │   └─ 不符合 → Subagent 修复 → 再审
  │
  ├─ 派发 Code Reviewer 检查代码质量
  │   └─ 有问题 → Subagent 修复 → 再审
  │
  ├─ tasks.md 中 Task 1 打勾 [x]
  │
  ├─ 派发 Subagent 2 实现 Task 2 ...
  │
  └─ 全部完成后 → Phase 5

模式 B --- 直接执行（小功能用）：

/opsx:apply

AI 直接在当前会话中逐任务实现，每完成一个打勾。

Phase 5: 验证 + 收尾

/opsx:verify supplier-review

三维度检查：完整性 × 正确性 × 一致性

通过后，Superpowers 接管收尾：

实现完成，准备收尾

Superpowers finishing-a-development-branch 自动：

1. 运行全量测试
2. 提供四个选项：合并 / 创建 PR / 保留分支 / 丢弃
3. 清理 worktree

最后：

/opsx:archive supplier-review

---

任务中断与恢复（核心问题）

问题本质

┌──────────────────────────────────────────────┐
│           AI 的上下文窗口 (有限)              │
│                                                │
│  对话开始 ───────────────────── 对话结束/中断  │
│  记住一切           逐渐遗忘        全部丢失   │
└──────────────────────────────────────────────┘

AI 有两个致命限制：

1. 上下文窗口有限 --- 长对话后期忘记前面内容
2. 会话不持久 --- 关窗口 / 新对话 = 一切归零

解决方案：三层持久化

┌─────────────────────────────────────────────┐
│ 第 1 层：项目级永久记忆                       │
│                                               │
│ openspec/config.yaml                          │
│ ├── 技术栈、代码约定                          │
│ ├── 每次新对话 AI 自动读取                    │
│ └── 相当于"置顶备忘录"                        │
│                                               │
│ CLAUDE.md / .cursor/rules/                    │
│ └── IDE 自动注入的项目规则                    │
└─────────────────────────────────────────────┘

┌─────────────────────────────────────────────┐
│ 第 2 层：功能级需求记忆                       │
│                                               │
│ openspec/changes/<name>/                      │
│ ├── proposal.md  → "这个功能是干嘛的"         │
│ ├── design.md    → "代码怎么组织"             │
│ └── tasks.md     → "做到哪了" (checkbox)      │
│                                               │
│ docs/superpowers/specs/<design>.md            │
│ └── Brainstorming 产出的设计文档              │
└─────────────────────────────────────────────┘

┌─────────────────────────────────────────────┐
│ 第 3 层：代码级状态记忆                       │
│                                               │
│ git worktree + branch                         │
│ ├── 分支名就是功能名                          │
│ ├── commit 历史就是实现进度                   │
│ └── worktree 路径就是工作区位置               │
└─────────────────────────────────────────────┘

中断恢复操作手册

场景 1：对话中途中断（关闭窗口 / 网络断开）

恢复方式： 新开对话，一句话搞定

/opsx:apply

AI 自动执行的恢复链：

1. openspec list → 找到活跃变更
2. 读 proposal.md → 恢复"做什么"
3. 读 design.md → 恢复"怎么做"
4. 读 tasks.md → 扫描 checkbox，定位到第一个 - [ ]
5. 从断点继续实现

场景 2：跨天开发（每天做一点）

完全相同，每天开工直接：

/opsx:apply supplier-review

场景 3：长对话上下文不够了（AI 开始"犯糊涂"）

症状： AI 忘记了之前的约定，代码风格不一致，重复问已回答过的问题

解决方式： 不要在旧对话中挣扎，直接新开对话

/opsx:apply supplier-review

新对话有全新的上下文窗口，从磁盘读取制品文件，比继续在被污染的旧对话中好。

场景 4：Subagent 执行到一半中断

Subagent 每完成一个 task 就在 tasks.md 中打勾并 commit。中断后：

/opsx:apply

主 Agent 读 tasks.md，跳过已完成的 [x]，从下一个 [ ] 继续派发 Subagent。

场景 5：需求变更（产品改了文档）

/opsx:explore supplier-review

产品说审核从一级改成两级，新流程截图如下：
[拖入新截图]

评估对 design.md 和 tasks.md 的影响。

确认后手动或让 AI 更新制品文件，再 /opsx:apply 继续。

---

上下文优化策略

策略 1：Subagent 隔离（Superpowers 核心能力）

主 Agent                    Subagent 1           Subagent 2
  │                             │                     │
  │ 只保留协调信息              │ 全新上下文           │ 全新上下文
  │ (tasks列表+当前进度)        │ (Task 1完整描述      │ (Task 2完整描述
  │                             │  + design.md片段)    │  + design.md片段)
  │                             │                     │
  │ 上下文消耗：极小            │ 上下文消耗：中等     │ 上下文消耗：中等

核心原理： 主 Agent 把任务的完整描述"打包"给 Subagent，Subagent 用全新上下文执行。执行完毕后 Subagent 的上下文被释放，不会污染主 Agent。

策略 2：制品文件 ＞ 对话记忆

方式	上下文消耗	可靠性	可恢复
"之前我们讨论过..."	高（需回溯对话历史）	低（可能遗忘）	否
读 design.md	低（只读一个文件）	高（磁盘持久化）	是

实践建议： 当你在对话中做了重要决策，但还没到 propose 阶段时，让 AI 立刻写入文件：

把刚才讨论的结论写入 openspec/changes/supplier-review/notes.md

策略 3：config.yaml 是跨会话记忆

# openspec/config.yaml
context: |
  这里的内容，每次新对话 AI 都会读到。
  等于给 AI 的"永久记忆"。

适合写入：

• 技术栈版本号
• 代码约定（命名、目录结构、import 顺序）
• 团队特有术语
• 常见的坑（"Ant Design 的 Table 组件在 xx 情况下需要 yy"）

---

命令速查

OpenSpec 命令

命令	作用	典型场景
/opsx:explore	思考伙伴，只读不写	拿到截图/文档，先梳理
/opsx:propose <name>	一键生成 proposal + design + tasks	需求明确，开始规划
/opsx:continue	生成下一个制品	propose 没一步到位时
/opsx:apply	按 tasks.md 逐任务实现	开始写代码 / 中断后恢复
/opsx:verify	检查实现 vs 制品	觉得做完了
/opsx:archive	归档已完成的变更	功能上线后

Superpowers 自动触发的 Skills

Skill	触发时机	作用
brainstorming	开始构建任何功能时	苏格拉底式需求对话
using-git-worktrees	设计确认后	隔离工作区 + 新分支
writing-plans	设计确认后	生成精细到 2-5 分钟粒度的计划
subagent-driven-dev	执行计划时	每 task 一个子代理 + 双审
test-driven-development	实现代码时	红-绿-重构循环
verification-before-completion	声称完成前	强制验证，杜绝"应该没问题"
finishing-a-development-branch	全部完成后	合并/PR/清理四选一

---

执行组合策略

四个执行工具的定位

需求拆解层                          执行层
                               ┌────────────────────────────┐
/opsx:apply ──────────────────►│  直接执行（内置简单模式）     │
  读 tasks.md                   │  逐 task 在当前会话实现      │
  逐 task 实现                  └────────────────────────────┘

                               ┌────────────────────────────┐
writing-plans ────────────────►│  生成精细计划文件             │
  把 task 拆成                  │  (每步 2-5 分钟粒度)         │
  2-5 分钟的步骤                └──────────┬─────────────────┘
                                           │
                                 ┌─────────┴──────────┐
                                 ▼                    ▼
                        executing-plans      subagent-driven-dev
                        (批量执行+检查点)    (每 task 派子代理+双审)

组合 1：/opsx:apply（单独使用）

适合： 小功能、占位页替换、简单 CRUD

/opsx:propose supplier-review
/opsx:apply

AI 读 tasks.md，在当前对话中逐个实现，每完成一个打勾。

优点	缺点
最快启动，零开销	长任务上下文膨胀，没有质量审查

典型任务量： 3-5 个 task，单次对话能搞定

组合 2：/opsx:apply + subagent-driven-dev

适合： 中等功能，需要质量保证

/opsx:propose material-library
/opsx:apply                        ← AI 自动用 subagent 模式执行

主 Agent 读 tasks.md，每个 task 派一个全新 Subagent 实现，完成后再派 reviewer 审查：

主 Agent（协调，上下文极小）
  │
  ├─ Subagent → Task 1: 注册路由    → Spec Review ✓ → Code Review ✓ → [x]
  ├─ Subagent → Task 2: API hooks   → Spec Review ✓ → Code Review ✓ → [x]
  ├─ Subagent → Task 3: 列表页面    → Spec Review ✗ → 修复 → 再审 ✓ → [x]
  └─ ...

优点	缺点
每 task 全新上下文（不膨胀），双重审查保证质量	消耗更多 token（每 task = 实现 + 2 次审查）

典型任务量： 5-15 个 task，跨 1-3 天

组合 3：writing-plans + executing-plans

适合： 需要极其精细控制的功能，或要交给别人/别的 AI 执行

先生成精细计划：

我要实现供应商审核模块，设计文档在 openspec/changes/supplier-review/design.md，
请用 writing-plans 生成实现计划。

产出 docs/superpowers/plans/2026-04-16-supplier-review.md，每个步骤精确到：

• 具体文件路径和完整代码块
• 运行命令 + 预期输出
• commit message

然后执行：

按 docs/superpowers/plans/2026-04-16-supplier-review.md 执行

executing-plans 批量执行，到检查点暂停让你审核。

优点	缺点
计划可人工审核、可交接、可复用	生成计划本身消耗大量 token，计划可能因代码变化过时

典型场景： 团队协作、需要人工审批的关键模块

组合 4：writing-plans + subagent-driven-dev（最高质量）

适合： 大功能，质量要求高，需要全自动执行

我要实现供应商审核模块，设计文档在 openspec/changes/supplier-review/design.md，
请用 writing-plans 生成实现计划，然后用 subagent-driven-development 执行。

writing-plans 生成精细计划
  │
  ▼
subagent-driven-dev 执行
  │
  ├─ Subagent 实现 Step 1 (TDD: 写测试→红→实现→绿)
  ├─ Spec Reviewer 审查是否符合设计
  ├─ Code Reviewer 审查代码质量
  ├─ [x] Step 1 完成
  │
  ├─ Subagent 实现 Step 2 ...
  └─ ...

优点	缺点
计划精确 + 执行隔离 + 双重审查 = 最高质量	token 消耗最大（计划生成 + 每 task 三个 agent）

典型场景： 核心业务模块、不允许返工的功能

组合 5：/opsx:propose + writing-plans + subagent-driven-dev（全链路）

适合： 从零开始的大模块，完整走一遍

Phase 1: OpenSpec 生成需求制品
/opsx:propose supplier-review + 截图/字段文档

Phase 2: Superpowers 生成精细计划
请根据 openspec/changes/supplier-review/ 的制品，
用 writing-plans 生成实现计划

Phase 3: Subagent 执行
用 subagent-driven-development 执行计划

Phase 4: 验证 + 收尾
/opsx:verify supplier-review
finishing-a-development-branch
/opsx:archive supplier-review

选择决策树

你要做多大的功能？
│
├─ 很小（改个按钮/加个字段）
│   └─ 不用 OpenSpec 也不用 Superpowers，直接写
│
├─ 小（1-3 个组件）
│   └─ /opsx:apply 单独用                          ← 组合 1
│
├─ 中（一个完整页面模块）
│   │
│   ├─ 赶时间？
│   │   └─ /opsx:apply + subagent                  ← 组合 2
│   │
│   └─ 要求高？
│       └─ writing-plans + subagent                ← 组合 4
│
├─ 大（多个页面/跨模块）
│   └─ /opsx:propose + writing-plans + subagent    ← 组合 5
│
└─ 需要交接给别人执行？
    └─ writing-plans + executing-plans             ← 组合 3

中断恢复对照

组合	进度保存位置	恢复方式
组合 1	tasks.md checkbox	/opsx:apply
组合 2	tasks.md checkbox	/opsx:apply
组合 3	plan 文件 checkbox	继续执行 docs/superpowers/plans/xxx.md
组合 4	plan 文件 checkbox	继续执行 docs/superpowers/plans/xxx.md
组合 5	两份 checkbox	/opsx:apply 或 继续执行 plan

所有组合的进度都通过 磁盘上的 checkbox 持久化，新对话一句话恢复。

---

FAQ

Q: OpenSpec 和 Superpowers 的 brainstorming/writing-plans 功能重叠了吗？

有部分重叠，但侧重不同：

• OpenSpec propose 生成的 tasks.md 是按功能域拆分的粗粒度任务（每个 task ≈ 5-15 分钟）
• Superpowers writing-plans 生成的 plan 是每步 2-5 分钟的精细粒度（含完整代码块和命令）

推荐：用 OpenSpec 管需求到任务的拆解，用 Superpowers 管每个任务内部的 TDD 执行。两层粒度互补而非冲突。

Q: 一定要用 Subagent 吗？

不一定。Subagent 的价值在于：

1. 隔离上下文 --- 每个 task 用全新上下文，不被前面的对话污染
2. 双重审查 --- spec reviewer + code reviewer 保证质量
3. 对抗遗忘 --- 主 Agent 上下文消耗最小

如果功能很小（3 个以下 task），直接在当前对话执行即可（组合 1）。

Q: writing-plans 生成的计划和 OpenSpec 的 tasks.md 有什么区别？

tasks.md（OpenSpec）              plan.md（Superpowers）
┌──────────────────┐            ┌─────────────────────────────┐
│ - [ ] 注册路由    │            │ Step 1: 创建路由文件          │
│ - [ ] API hooks  │──细化──▶  │   创建 src/app/router.tsx     │
│ - [ ] 列表页面    │            │   添加以下代码：              │
│                  │            │   ```tsx                     │
│                  │            │   export const routes = ...  │
│                  │            │   ```                        │
│                  │            │   运行: pnpm exec tsc        │
│                  │            │   预期: 无错误                │
└──────────────────┘            └─────────────────────────────┘
粗粒度，描述"做什么"            精细粒度，描述"怎么做每一步"

选择建议：

• 只有 tasks.md 就够 → 组合 1 或 2
• 需要精确控制每一步 → 先 writing-plans 再执行 → 组合 3、4、5

Q: executing-plans 和 subagent-driven-dev 怎么选？

	executing-plans	subagent-driven-dev
执行方式	批量执行 + 检查点暂停	每 task 单独 subagent
上下文管理	同一上下文累积	每 task 全新上下文
审查机制	检查点由人工审核	自动 spec + code review
token 消耗	中	高
适合场景	需要人工审批、交接	全自动、高质量要求

Q: 中断后有些代码写了一半怎么办？

git 状态就是证据：

• 有 commit → task 已完成，tasks.md 应该已打勾
• 有未 commit 的改动 → task 做了一半，新对话中让 AI 检查 git diff 后继续

Q: tasks.md 里的任务太粗/太细怎么办？

直接编辑文件。粒度标准：每个 task 能在一次 AI 对话中完成（约 5-15 分钟）。OpenSpec 不锁定制品格式，随时可修改。

Q: 能不能混用组合？

可以。例如前 3 个简单 task 用组合 1 直接做，后面复杂的 task 切到组合 2 用 subagent。OpenSpec 的 tasks.md 是唯一进度源，无论哪种组合都通过 checkbox 同步进度。