最近我尝试把 OpenSpec 和 Superpowers 结合起来，用 Claude Code 做一个“英语自然拼读学习网站”。这篇文章整理这次探索过程：为什么要同时使用这两个工具、每个阶段应该产出什么文件、提示词应该怎么写，以及实现完成后如何归档 spec。

核心结论很简单：

Superpowers 负责过程纪律。
OpenSpec 负责长期规格事实。
实现阶段只以 OpenSpec change 为需求来源。

如果只用 Superpowers，AI agent 的执行过程会更稳，但需求容易停留在聊天或临时设计文档里。
如果只用 OpenSpec，需求和规格更清楚，但 agent 执行时仍可能跳步骤、少测试或扩范围。
两者结合后，比较理想的分工是：

Superpowers：帮助想清楚、拆清楚、按 TDD 做清楚。
OpenSpec：把确认后的需求变成仓库里的正式规格。

整体流程

我最终采用的流程是：

Superpowers brainstorming/spec
  -> OpenSpec change
  -> OpenSpec validate/review
  -> Superpowers implementation plan
  -> Superpowers TDD execution
  -> Review/verify
  -> OpenSpec archive

每一步都有明确边界。最关键的一点是：Superpowers 先帮助形成设计共识，但一旦 OpenSpec change 被确认，OpenSpec 就成为唯一需求基线。

这样做是为了避免需求源冲突：

Superpowers 草稿说 A
OpenSpec change 说 B
代码到底按哪个做？

所以进入实现阶段后，规则应该是：

OpenSpec change 是唯一需求来源。
Superpowers implementation plan 是执行计划，不是需求源。
Superpowers design 文档只是历史草稿和推理记录。

阶段一：Superpowers 脑暴

第一步不要急着写代码，也不要直接创建前端项目。先用 Superpowers 做 brainstorming，把模糊想法变成可讨论的产品设计。

显式调用可以类似这样：

/brainstorming

我们要做一个“英语自然拼读学习网站”。

规则：
1. 全程使用中文。
2. 现在只做脑暴和产品设计，不写代码。
3. OpenSpec 将作为需求和规格的长期事实源。
4. 每次只问一个问题。
5. 信息足够后，给出 2-3 套方案，并说明取舍和推荐方案。

这一步的典型产物是：

docs/superpowers/specs/YYYY-MM-DD-phonics-learning-site-design.md

这个文件的作用是记录需求形成过程，例如：

  • 目标用户是谁
  • 学习路径是什么
  • MVP 做到什么程度
  • 哪些方案被比较过
  • 为什么选当前方案

但它不是最终需求源。它更像会议纪要、草案和推理记录。

阶段二：转换为 OpenSpec change

当脑暴方案确认后，要把 Superpowers 的设计共识转换成 OpenSpec change。

提示词可以这样写：

请把 Superpowers 设计文档转换成 OpenSpec change：create-phonics-learning-site-mvp。

要求：
1. OpenSpec 是需求和规格的唯一长期事实源。
2. Superpowers 设计文档只作为输入材料。
3. 生成 proposal.md、design.md、tasks.md 和 specs/**/spec.md。
4. 全部使用中文。
5. 只写规格，不写实现代码。

典型目录结构：

openspec/changes/create-phonics-learning-site-mvp/
  proposal.md
  design.md
  tasks.md
  specs/
    ...

各文件职责如下：

文件 职责
proposal.md 说明为什么做、目标用户、核心价值、范围和非目标
design.md 说明产品结构、信息架构、学习路径、内容模型、技术约束
tasks.md 把需求拆成可执行任务，但不等于马上执行
specs/**/spec.md 正式描述系统能力变化，包含 Requirement 和 Scenario

其中最重要的是 specs/**/spec.md。它要把自然语言需求转换成可验收场景。

例如脑暴文档里可能写：

孩子可以练习 CVC 拼读。

OpenSpec 里应该变成：

Requirement: 学习者可以进行 CVC 拼读练习

Scenario: 当学习者看到 cat 时，系统应引导其按 /c/ /a/ /t/ 分音，再合成 cat。
Scenario: 当学习者答错时，系统应给出音素级提示，而不是直接给答案。

这样后续测试就可以直接从 Scenario 推导出来。

阶段三：Validate 和人工审查

OpenSpec change 生成后，先做结构校验：

openspec validate create-phonics-learning-site-mvp --strict

注意，这通常是终端命令，不一定是 Claude Code slash command。

然后让 Claude Code 帮忙做内容审查：

请审查这个 OpenSpec change：

- openspec/changes/create-phonics-learning-site-mvp/proposal.md
- openspec/changes/create-phonics-learning-site-mvp/design.md
- openspec/changes/create-phonics-learning-site-mvp/tasks.md
- openspec/changes/create-phonics-learning-site-mvp/specs/**/*.md

要求：
1. 总结每个文件的核心内容。
2. 列出 MVP 范围和非目标。
3. 列出 Requirements 和 Scenarios。
4. 检查是否有范围过大、过度设计、验收不清、测试无法映射的问题。
5. 只审查，不写代码。

这一阶段的目标不是“让 AI 继续做”，而是让人确认规格是否合理。

阶段四：生成 Superpowers implementation plan

确认 OpenSpec change 后，再让 Superpowers 生成实施计划。

这里要特别强调：从这一步开始，不再以 Superpowers design 草稿作为需求来源。

提示词：

我确认 OpenSpec change：create-phonics-learning-site-mvp。

请进入 Superpowers 的 implementation plan 阶段，但仍然不要写代码。

要求：
1. 以 openspec/changes/create-phonics-learning-site-mvp 作为唯一需求来源。
2. 不要再以 docs/superpowers/specs 中的设计草稿作为需求来源。
3. 每个实施任务都要映射到 OpenSpec Requirement 或 Scenario。
4. 计划要包含 TDD 顺序。
5. 计划要包含每阶段验证命令。
6. 计划要明确哪些功能属于 MVP，哪些不做。
7. 生成 implementation plan 后停止，等待确认。

典型产物：

docs/superpowers/specs/YYYY-MM-DD-phonics-learning-site-impl-plan.md

这个文件是施工计划，不是需求源。它回答的是：

  • 按什么阶段做
  • 每个阶段对应哪个 Requirement/Scenario
  • 哪些测试先写
  • 每个阶段怎么验证
  • 做到哪里必须停下来给人审查

阶段五：缩减 MVP，防止范围膨胀

AI 很容易把一个学习网站扩成完整平台。例如自然拼读网站可能被扩成：

  • 10 个以上页面
  • 大规模课程库
  • 登录系统
  • PostgreSQL
  • Whisper 发音评分
  • 班级管理
  • IPA 完整课程
  • 离线缓存

如果 plan 看起来过大，要先让它缩 scope，而不是直接开始 coding。

提示词：

暂停，不要执行实现。

请审查 implementation plan。我担心当前 MVP 范围过大。

请基于 OpenSpec change 重新审查计划，并区分：
1. 必须做的 MVP
2. 可以延后的 v1.1
3. 明确不做的内容

保留核心闭环：
- 字母音
- CVC 拼读
- 听音辨识
- 简单进度反馈
- 家长/老师概览

优先减少页面数、课程数、练习类型数和外部 API 依赖。
不要修改代码。
如需修改计划，只修改 implementation plan 文档。
修改后停止，等待确认。

对于这个项目，合理的 MVP 可以收敛成：

页面：
1. 首页 / 学习入口
2. 字母音学习
3. CVC 拼读练习
4. 听音辨识练习
5. 进度概览

内容：
- 5-8 个字母音
- 6-10 个 CVC 词
- 2-3 种练习类型

暂不做：
- IPA 系统课
- Whisper API
- 登录账号
- 数据库
- 班级管理
- 离线缓存
- 句子朗读
- 复杂评分系统

阶段六：Coding 前最终自检

开始写代码前，再做一次最终自检：

请做实施计划最终自检，不要写代码。

请读取：
- openspec/changes/create-phonics-learning-site-mvp/
- docs/superpowers/specs/YYYY-MM-DD-phonics-learning-site-impl-plan.md

检查：
1. 每个 MVP Phase 是否都映射到 OpenSpec Requirement 或 Scenario。
2. 是否还有超出 MVP 的内容。
3. TDD 顺序是否清楚：先测试、再实现、再重构。
4. 每个 Phase 的验证命令是否明确。
5. 是否还需要修改 OpenSpec change；如果不需要，请明确说“不需要修改 OpenSpec”。

只输出自检结果，不要写代码。

通过后再开始执行 Phase。

阶段七：按 Phase 执行代码

实现时不要一次让 agent 做完整 MVP。建议一次只做一个 Phase。

提示词：

请执行 Phase 1。

约束：
1. 以 openspec/changes/create-phonics-learning-site-mvp 为唯一需求来源。
2. 按 docs/superpowers/specs/YYYY-MM-DD-phonics-learning-site-impl-plan.md 执行。
3. 当前只做 Phase 1，完成后停止。
4. 按 TDD 执行：先写测试，再实现，再跑通。
5. 不要引入后端、数据库、认证、Whisper 或复杂 UI/课程系统。

完成后汇报：
- OpenSpec Requirement/Scenario 映射
- 文件变更
- 验证命令
- 测试是否经历 red -> green
- 是否偏离 OpenSpec

这里的 TDD 不要求人手写测试，而是要求 agent 按顺序执行：

OpenSpec Scenario -> failing test -> minimal implementation -> passing test -> refactor

你的角色主要是审查和确认，不是亲手写每一个测试。

文件优先级

整个流程中会产生多类文件。它们的优先级应该明确：

OpenSpec specs/proposal/design
  > OpenSpec tasks
  > Superpowers implementation plan
  > Superpowers design 草稿
  > 聊天记录

如果这些文件发生冲突，按上面的优先级处理。

如果发现 Superpowers 草稿里有重要内容但 OpenSpec 漏了，不应该直接实现，而应该先更新 OpenSpec change。

如何写专业提示词

这类提示词不是普通聊天，更像给 AI agent 的流程控制脚本。好的提示词要回答：

现在在哪一步？
该读哪些文件？
哪个文件说了算？
这一步只允许做什么？
这一步绝对不能做什么？
结果怎么验收？
做到哪里必须停下来？

我一般按 6 块写：

模块 作用
当前阶段 告诉 agent 现在是 brainstorm / spec / plan / coding / archive 哪一步
事实来源 指定要读取哪些文件，以及哪个文件是唯一需求来源
禁止事项 明确不要写代码、不要进入下一阶段、不要扩范围
目标输出 说明这一步要产出审查、计划、测试还是实现
质量标准 要求映射 Requirement/Scenario，列出验证命令和风险
停止条件 要求完成后停止，等待人工确认

通用模板：

当前阶段：<阶段名称>

请读取：
- <文件或目录>

事实来源：
- <哪个文件或目录是唯一需求来源>
- <哪些文件只作为参考，不作为需求来源>

请完成：
1. <任务 1>
2. <任务 2>
3. <任务 3>

约束：
1. 不要 <禁止事项>
2. 不要 <禁止事项>
3. 如果发现 <异常情况>，先汇报，不要自行扩大范围

质量标准：
1. 每个输出必须映射到 <Requirement/Scenario/任务>
2. 必须说明验证方式
3. 必须列出风险或不确定点

停止条件：
- 完成后停止，等待我确认
- 不要进入下一阶段

如果不知道下一步怎么写，可以先让 Claude Code 或 Codex 只生成提示词：

请不要执行任何项目操作。

你现在是我的 OpenSpec + Superpowers 流程教练。
请根据当前项目状态，帮我生成下一条应该发给 Claude Code 的提示词。

要求：
1. 提示词使用中文。
2. 明确当前阶段。
3. 明确事实来源文件。
4. 明确禁止事项。
5. 明确输出格式。
6. 明确停止条件。
7. 给我一个“完整版”和一个“简短版”。

实现完成后如何归档 OpenSpec

每个 Phase 完成后都应该检查：

1. 对应的 OpenSpec Requirement/Scenario 是否实现。
2. 是否有测试覆盖。
3. 验证命令是否通过。
4. 是否做了超出 MVP 的内容。
5. 是否需要更新 OpenSpec。

全部 MVP 完成后，先做最终审查：

请做 MVP 完成审查。

检查：
1. OpenSpec change 中所有 Requirements/Scenarios 是否已实现。
2. 每个 Scenario 是否有测试或明确的验证方式。
3. 是否存在超出 MVP 的实现。
4. 是否有未完成 tasks。
5. 是否需要更新 OpenSpec specs。
6. 是否可以进入 OpenSpec archive。

只审查，不要归档，等待我确认。

确认后执行：

openspec validate create-phonics-learning-site-mvp --strict
npm test
npm run lint
npm run build

具体命令以项目实际技术栈为准。

然后归档：

openspec archive create-phonics-learning-site-mvp --yes

如果不想跳过确认，可以去掉 --yes：

openspec archive create-phonics-learning-site-mvp

归档后再验证：

openspec validate --strict

归档的意义是：

这个 change 不再是待实现需求；
它已经成为系统当前事实。

之后再做新功能，比如“AI 发音评分”或“教师班级管理”，应该创建新的 OpenSpec change，而不是继续修改旧 change。

下次继续时的恢复提示词

如果中断后重新开始，可以用：

我们继续英语自然拼读学习网站项目。

当前工作流是 OpenSpec + Superpowers：
- OpenSpec 是唯一需求来源。
- Superpowers 负责计划、TDD、review 和执行纪律。

请读取：
- openspec/changes/create-phonics-learning-site-mvp/
- docs/superpowers/specs/YYYY-MM-DD-phonics-learning-site-impl-plan.md

请先汇报：
1. 当前 OpenSpec change 状态。
2. 当前 implementation plan 状态。
3. 已完成哪些 Phase。
4. 下一步应该执行哪个 Phase。
5. 执行前是否需要我确认。

不要写代码，先等待我确认。

总结

这套流程的价值不是多写文档，而是把 AI coding 从“边聊边写”变成：

先形成共识
再正式化需求
再按计划实现
再验证归档

对于小修小改，这套流程可以简化。
对于新功能、跨模块改动、长期维护项目，建议完整执行。

长期规则可以总结为：

1. Superpowers design 是草案，不是最终需求源。
2. OpenSpec change 确认后，实现阶段只看 OpenSpec。
3. Implementation plan 是施工计划，不是需求源。
4. 每个实现任务必须映射到 Requirement 或 Scenario。
5. 如果实现中发现需求变化，先改 OpenSpec，再改代码。
6. 每次只执行一个 Phase，完成后停下来审查。
7. MVP 要主动缩减范围，外部 API、数据库、认证、复杂课程系统默认不做。
8. 完成后必须 validate、测试、review，再 archive。