# 从 OpenSpec 到 OpenSpec × Superpowers：一套让 AI 编码流程"长出肌肉记忆"的工作流

从 OpenSpec 到 OpenSpec × Superpowers：一套让 AI 编码流程"长出肌肉记忆"的工作流

TL;DR

单用 OpenSpec 只能保证"规格存在"，但从规格到代码、并行开发、测试纪律、质量兜底都是真空地带。

把 Superpowers 的 brainstorming / writing-plans / subagent-driven-development / test-driven-development / code-reviewer 嵌进 OpenSpec 的建档 → 归档骨架，得到一条从想法到归档的 7 阶段流水线。

TDD 不再是"写完代码补几个测试"的事后行为，而是三层嵌入（契约 / 实现 / 集成）贯穿全流程。

对比单用 OpenSpec：规格覆盖率、并行效率、测试可追溯性、Review 严谨度 全面升级。

一、起点：一个真实困境

如果你用过 OpenSpec（或类似的 spec-driven 工具）配合 AI 编码，大概率遇到过这些痛点：

规格写完，AI 写代码却不看规格
proposal / design / tasks 四份工件写得整整齐齐，但真到写代码的时候，AI 只看了一眼 tasks.md 就开干，具体实现偏离 design 里的决策。
多任务不知道怎么并行
明明 tasks.md 里有 6 条独立任务，AI 只会一条一条串行做，耗时 10 分钟的活干了 40 分钟。
测试永远是"事后补"
实现完了才问"要不要写测试？"——于是测试成了给已经写好的代码做确认，而不是驱动开发。
Review 靠主会话瞄一眼
没有独立的 review pass，主会话既当裁判又当运动员，质量问题容易漏。
归档时发现对不上
代码写了一堆，回头翻 tasks.md，有一半任务其实没做或做了没勾选；specs/ 里的基线规格也没同步。

这些问题都不是 OpenSpec 的错——OpenSpec 的定位是"规格管理"，它管好了自己那一段。但规格和代码之间的这段"施工"才是最容易翻车的地方。

二、破局思路：让规格、计划、开发、质量各司其职

这套流程的核心观念：每个环节用最擅长它的工具，工具之间用明确的"工件"衔接。

环节	最擅长的工具	产出的工件
探索需求、定设计方向	`superpowers:brainstorming`	`docs/superpowers/specs/<date>-<topic>-design.md`
调研旧代码、澄清需求	`/opsx:explore`	探索结论（写入 change 前置备忘）
建档、生成四份工件	`/opsx:propose`	`openspec/changes/<name>/{proposal,design,specs,tasks}.md`
写实施计划	`superpowers:writing-plans`	`docs/superpowers/plans/<date>-<topic>-plan.md`
并行开发独立任务	`superpowers:subagent-driven-development`	多个子 agent 返回的实现代码
单文件高内聚逻辑	`superpowers:test-driven-development`	先测后码的实现
自动化验证	`superpowers:verification-before-completion`	测试 / lint / 构建证据
代码审查	`code-reviewer` 子代理	P0/P1 必修清单
归档	`/opsx:verify` → `/opsx:archive`	归档后的 specs + CHANGELOG

关键设计：这些工具之间通过工件引用串联——后一环节读前一环节的产物，不靠主会话把内容复制粘贴过来。这样 AI 上下文再长也不会丢失信息链。

三、完整流程：7 阶段拆解

🟠 Phase 1：入口选择（并行双入口）

            需求 / 想法
                │
       ┌────────┴────────┐
       │                  │
  [新功能?]           [旧代码?]
       │                  │
       ▼                  ▼
superpowers:       /opsx:explore
brainstorming

为什么需要两个入口？
brainstorming 偏"设计新功能"，强项是从零探索方案、对比权衡、定稿设计。
opsx:explore 偏"理解现有系统"，强项是读代码、梳理既有架构、澄清模糊需求。

两者不是互斥的——复杂改造可以先 brainstorm 定方向，再 explore 挖代码。

通用纪律（两个入口都要遵守）：

逐个提问：不要一次抛 5 个问题让用户晕，问完一个等用户答完再问下一个
✅ / ⏳ 标注机制：用户已确认的打 ✅ [已确认]，识别出但未确认的打 ⏳ [待确认]
结束前不能有 ⏳：所有疑问必须由用户拍板

这套机制能让需求模糊的改造也能收敛到一个清晰的起点。

🔵 Phase 2：建档（OpenSpec 工件生成）

/opsx:propose "add-douyin-material-selection"

一步生成 4 份工件：

工件	回答什么
`proposal.md`	Why / What（为什么做、影响哪些模块）
`design.md`	关键技术决策与权衡（浓缩版）
`specs.md`	规格 Scenario（WHEN / THEN，QA 可执行）
`tasks.md`	任务清单 + 🧪 验收契约（TDD 第 1 层）

🔑 重要改进：tasks.md 的每条任务必须附验收契约。

什么是验收契约？就是 1-3 句 SHALL / MUST 断言，写清这条任务"做完算做完"的判定标准。例：

- [ ] **任务 A.2**：在 `src/api/material/index.js` 新增 `fetchMaterialList` 方法
  - **验收契约**：
    - MUST 返回 `{ list, total }` 结构
    - SHALL 支持 `page_info` 分页参数（`page`、`page_size`）
    - MUST 在 `status_code !== 1` 时 throw 并带错误消息

这条契约就是 TDD 的第 1 层——实现者拿到任务第一件事，不是写代码，而是按契约写测试。

🟢 Phase 3：写实施计划（可跳过）

superpowers:writing-plans  # 读 tasks.md，产出 plan.md

plan.md 和 tasks.md 有本质区别：

文件	回答什么	类比
`tasks.md`	做什么 + 验收契约 + 完成状态	施工合同
`plan.md`	怎么做 + Phase 划分 + 派单策略 + 检查点	施工图

合同定义交付物，施工图定义怎么造——这是一个软件工程里常见的分层。

逃生口：如果是"单文件改个 bug"这种极简变更（≤3 任务且无并行），可以跳过 plan，直接按 tasks.md 串行执行。不是所有变更都需要施工图。

🟢 Phase 4：开发阶段（并行 + 串行混合）

这是整条流水线最耗时也收益最大的阶段。分两步走：

4a. 创建 worktree

superpowers:using-git-worktrees

整个 change 共享一个 worktree，所有子 agent 在同一分支工作——不为每个子 agent 开独立 worktree。理由：

git 历史清晰（一条分支 = 一个 change）
merge 成本低（无需跨分支合并）
并发冲突可控（主线做协调）

4b. 按 plan 逐 Phase 派单

根据 plan.md 的 Phase 分类，选不同派单方式：

Phase 类型	特征	派单方式
独立纯函数 / 重命名 / 文件迁移	无共享状态，可并行	`superpowers:subagent-driven-development`
单文件高内聚逻辑	需整体思考	主线 `superpowers:test-driven-development`
手工 e2e 验证	需浏览器/人工	主线，截图归档

🔑 TDD 第 2 层嵌入：每个任务内部都走 TDD 循环——

写单元测试（按 tasks.md 的验收契约）
    → 跑测试 → 红（期待失败）
    → 写实现代码
    → 跑测试 → 绿（期待通过）
    → 重构（可选）

🔑 tasks.md 状态更新规则：

并行子 agent 不直接写 tasks.md——避免多个 agent 同时改同一个文件导致 git 冲突
子 agent 返回完成报告 → 主线在接收后统一勾选 - [ ] → - [x]

这是从无数次并发冲突翻车经验里总结出的铁律。

🟣 Phase 5：验证（机器检查）

superpowers:verification-before-completion

🔑 TDD 第 3 层嵌入：跨模块集成测试 + lint + 构建 + 手工 e2e（截图归档）。

核心原则：有证据才算通过。不是说"测试应该都过了吧？"，而是真的跑一次把输出贴出来。

🟣 Phase 6：Code Review（独立审查 pass）

派 code-reviewer 子代理 → 全量 review

为什么要独立的 review pass？

写作者和审稿人不能是同一个人——不然你写的 bug 你一定看不出来。

主会话刚写完代码，大脑里全是"这样写对"的假设。换一个无上下文的 code-reviewer 子代理从零看代码，能发现主线盲区。

P0 / P1 必修：严重问题必须修，修完回 Phase 5 重跑验证。
高危变更（认证、核心 request、大跨模块）额外在关键 Phase 做轻 review。

⚪ Phase 7：归档

/opsx:verify     # 确认 tasks 全勾选、代码与 specs 对齐
/opsx:archive    # change 入 archive，specs 同步，CHANGELOG 追加

归档条件：

tasks.md 全部 - [x]
delta specs 已同步到 openspec/specs/
openspec/CHANGELOG.md 已追加本次记录

不满足任何一条都不能归档。

四、TDD 的三层嵌入：为什么这么设计

很多人把 TDD 理解成"先写测试再写代码"，然后在流程里开辟一个"TDD 阶段"放在派单前或派单后——这是对 TDD 最大的误解。

TDD 是贯穿全流程的纪律，不是某一个节点。它在这套流程里分成三层：

┌─────────────────────────────────────────────────────────┐
│ 第 1 层｜契约层（Phase 2 建档时）                        │
│   在 tasks.md 写清每条任务的"做完的判定标准"             │
│   → 接口签名、边界条件、预期断言                         │
│   → 类比：还没施工，先把验收单写好                       │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│ 第 2 层｜实现层（Phase 4 开发中）                        │
│   每个子 agent / 主线在自己的任务内部：                  │
│     写测试 → 跑红 → 实现 → 跑绿 → 重构                   │
│   → 类比：按验收单施工，每步都拿验收单对照               │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│ 第 3 层｜集成层（Phase 5 验证时）                        │
│   跨模块集成测试 + lint + 构建 + 手工 e2e                │
│   → 类比：所有子承包商完工，总包跑一遍整体验收           │
└─────────────────────────────────────────────────────────┘

三层缺一不可：

没有契约层，实现层无从开始（测试写什么？）
没有实现层，代码和测试脱节
没有集成层，子模块间的契约不一致会漏

五、这套流程解决了哪些问题

原来的痛点	这套流程怎么解
规格写完 AI 不看	proposal / design / tasks 都强制 Markdown 链接引用上游 `design.md`；工件之间明确的引用链防止信息断层
任务不并行	plan.md 明确标注哪些 Phase 可并行，`subagent-driven-development` 负责派单
测试事后补	TDD 三层嵌入，契约在建档时就写进 tasks.md，实现时按契约先写测试
Review 靠自己瞄	独立的 `code-reviewer` 子代理 pass，无上下文视角发现主线盲区
归档对不上	`/opsx:verify` 强制校验 tasks 全勾选、代码与 specs 对齐，不合格不能归档
并发写 tasks.md 冲突	规则：子 agent 只返回报告，主线统一勾选
worktree 乱	规则：整个 change 共享单一 worktree，不为每个子 agent 开独立分支

六、对比：只用 OpenSpec vs OpenSpec × Superpowers

6.1 能力维度对比

能力	只用 OpenSpec	OpenSpec × Superpowers
需求探索	`/opsx:explore`	`brainstorming`（新功能）+ `opsx:explore`（旧代码）
规格生成	✅ `/opsx:propose`	✅ 同上，且自动带验收契约
实施计划	❌ 无	✅ `writing-plans` 产出 plan.md
并行开发	❌ 无	✅ `subagent-driven-development` 派单
测试驱动	❌ 无	✅ TDD 三层嵌入
自动验证	❌ 手工	✅ `verification-before-completion`
独立 Review	❌ 无	✅ `code-reviewer` 子代理 pass
归档校验	✅ `/opsx:archive`	✅ `/opsx:verify` + `/opsx:archive`
工件完整性	proposal + design + specs + tasks	同上 + design 外部 spec + plan + review 报告

6.2 典型场景对比：新增"抖音物料选择"功能

🔴 只用 OpenSpec

1. /opsx:explore 问几个问题 → 写下结论
2. /opsx:propose → 4 份工件
3. /opsx:apply  → AI 开始实现
     └ AI 自由发挥：一条条任务做，偶尔参考 design
     └ 测试？做完代码才想起来要不要写
     └ 6 条独立任务全串行，慢
4. /opsx:archive → 归档
     └ 回头看 tasks，有 2 条没勾选（忘了）
     └ specs 没有同步到基线

典型问题：规格和实现脱节、速度慢、测试覆盖靠运气、归档对不上。

🟢 OpenSpec × Superpowers

1. brainstorming → 逐个提问定方案 → design.md 持久化
2. /opsx:propose（引用 design.md）→ 4 份工件 + 验收契约
3. writing-plans → plan.md（标注 6 条任务可 3+3 分 Phase 并行）
4. worktree + subagent-driven-development
     ├ Phase 1：3 个子 agent 并行（每个内部 TDD）
     │   └ 返回完成报告 → 主线勾选 tasks
     ├ Phase 2：3 个子 agent 并行
     │   └ 同上
     └ Phase 3：主线串行（涉及跨模块）
5. verification-before-completion → 跑测试/lint/build 证据
6. code-reviewer 子代理全量 review → P0/P1 修完
7. /opsx:verify → /opsx:archive

典型效果：

速度：6 条串行 40 分钟 → 3+3 并行 + 主线 15 分钟，约 2.5 倍加速
测试覆盖：三层 TDD 保证契约、实现、集成都有测试
质量：独立 review pass 发现主线盲区
对账：归档前强制校验，不合格不能归档

6.3 文档体系对比

文档类型	只用 OpenSpec	OpenSpec × Superpowers
为什么要做	`proposal.md`	`design.md`（完整设计）+ `proposal.md`（摘要）
怎么做（技术）	`design.md`	`design.md`（浓缩决策）+ 引用完整 `design.md`
做什么（任务）	`tasks.md`	`tasks.md` + 验收契约（TDD 契约层）
怎么执行	❌ 无（靠 AI 临时决策）	`plan.md`（Phase + 派单 + 检查点）
Review 记录	❌ 无	`code-reviewer` 子代理返回的结构化报告

七、这套流程的适用边界

✅ 适合：

业务功能开发（新增 / 修改 / 重构）
跨 2 个以上文件的改动
涉及接口 / 权限 / 路由变更
多人协作、AI 协作重度使用的项目

❌ 不适合（过重）：

一行改动的 bug 修复
配置文件微调（如 .env 改个变量）
纯文档排版
紧急线上事故修复（走独立的 hotfix 流程）

边界判断：CLAUDE.md 里写明了"业务功能、行为变更、接口变更或非平凡重构"走全流程，其它 case 可以根据变更复杂度自行取舍。极简变更允许跳过 writing-plans。

八、落地成本与回报

落地成本

项目	成本
新增依赖	0 —— 所有工具（OpenSpec、Superpowers skills）都是现有的
文档更新	`.claude/CLAUDE.md`（+10 行）、`openspec/config.yaml`（+11 行）
学习曲线	约 1-2 次完整跑流程即可熟悉
每次变更开销	额外 5-10 分钟（写 plan、跑 verify、派 review）

回报

项目	回报
并行效率	独立任务 2-3 倍加速
测试覆盖	三层 TDD 保证契约 / 实现 / 集成都有测试
质量兜底	独立 review pass 发现主线盲区
归档严谨度	`/opsx:verify` 强制校验，告别"归档后发现没对齐"
规格 ⇌ 代码一致性	工件引用链保证信息不丢失

粗算 ROI：单次变更额外开销约 10% 时间，换来 2-3 倍加速 + 显著更高质量——收益正向。

九、给正在考虑落地的读者

如果你也想用这套流程，建议按这个顺序走：

先只用 OpenSpec 跑 1-2 个变更，体会"规格存在但不管施工"的痛点
把 Superpowers 的 skills 装好（brainstorming、writing-plans、subagent-driven-development、test-driven-development、code-reviewer）
修改项目的 CLAUDE.md，写清 7 阶段流程和每阶段的 skill 调用
修改 openspec/config.yaml，加验收契约、上游引用、brainstorming 段等规则
找一个中等规模的变更试跑一次，体会完整流程
复盘，根据实际情况调整（比如 worktree 策略、并行阈值、review 粒度）

最重要的一条：流程是为了让你不用每次重新思考，把精力花在业务上。如果流程让你觉得"好累"，说明哪里错了——是流程过重还是工具没配好？该优化就优化，别让流程变成新的负担。

十、参考

本项目落地文件

文件	作用
`.claude/CLAUDE.md`	7 阶段强制工作流、派单策略、TDD 三层约定
`openspec/config.yaml`	验收契约规则、上游引用规则、brainstorming 段
`docs/superpowers/specs/2026-04-30-workflow-redesign-design.md`	本次流程重设计的完整设计文档
`/Users/jinduoxia/Desktop/文档/流程图/openspec/openspec-superpowers-workflow/`	流程图（drawio + png）

# 从 OpenSpec 到 OpenSpec × Superpowers：一套让 AI 编码流程"长出肌肉记忆"的工作流