OpenSpec + Superpowers 的一个使用思路

OpenSpec + Superpowers

下面按 Codex + OpenSpec + Superpowers 当前工作流整理。OpenSpec 默认 core 流程包含 explore → propose → apply → sy:contentReference[oaicite:0]{index=0}x 的 OpenSpec 配置可以安装到 ​.codex/skills/，Superpowers 则提供 TDD、调试、计划、子代理开发和分支收尾等 Skills；Codex 还可用 ​/review` 做最终代码审查。(GitHub)按阶段分别执行*，把方括号占位符替换为实际内容。如果没有依赖 请先让ai安装依赖

0. 项目全局工作规则

本项目使用 OpenSpec 管理需求和变更，使用 Superpowers 管理开发过程。

执行任何开发任务前：

1. 检查并读取相关 OpenSpec artifacts。
2. 检查并使用适用的 Superpowers Skills。
3. 不得擅自扩大需求范围。
4. 不得跳过测试、降低断言、隐藏错误或删除失败测试。
5. 未运行最新验证命令前，不得声称任务完成。
6. 发现规格冲突、环境问题或阻塞时，停止受影响的工作并明确报告。
7. 保留用户已有代码和未提交修改，不执行破坏性操作。

---

1. 从空目录创建项目

请从当前空目录创建项目：

• 项目名称：[项目名称]
• 项目目标：[项目目标]
• 技术栈：[技术栈]
• 包管理器：[包管理器]
• 运行环境：[运行环境]

使用 brainstorming 明确架构、目录结构、测试策略和关键技术选择。对于未指定的普通工程选项，采用该技术栈的稳定主流实践；涉及产品行为、安全、数据模型或不可逆决策时，不要自行猜测。

创建：

• Git 仓库和合理的 .gitignore
• 最小可运行项目骨架
• README 和启动说明
• 环境变量示例文件
• 测试框架和至少一个冒烟测试
• 项目适用的 lint、格式化、类型检查和构建脚本
• 必要的基础配置

不要实现项目的具体业务功能。完成后运行项目已有的全部基线验证，并报告项目结构和验证结果。

---

2. 初始化 OpenSpec 和检查 Superpowers

请为当前项目准备 OpenSpec + Superpowers 工作环境。

要求：

1. 检查 OpenSpec CLI 是否可用；未安装时安装当前稳定版本。

2. 执行 openspec init，选择 Codex 作为目标工具。

3. 配置需要的工作流，至少包含：

   • explore
   • propose
   • apply
   • sync
   • archive
   • verify

4. 执行必要的 openspec update。

5. 检查 .codex/skills/openspec-* 和对应 OPSX prompts 是否生成。

6. 检查以下 Superpowers Skills 是否可用：

   • brainstorming
   • using-git-worktrees
   • writing-plans
   • test-driven-development
   • subagent-driven-development
   • systematic-debugging
   • requesting-code-review
   • receiving-code-review
   • verification-before-completion
   • finishing-a-development-branch

本步骤只配置开发工作流，不实现业务代码。缺少能力时停止并明确列出缺失项及安装方式。

---

3. 探索项目需求

执行 /opsx:explore​，并使用 brainstorming 分析以下项目构想：

[项目或功能构想]

请：

• 阅读现有代码和项目配置。
• 明确用户目标、使用场景、约束和非目标。
• 比较可行方案及其利弊。
• 识别安全、性能、兼容性和维护风险。
• 避免过度设计。
• 给出推荐方案和选择理由。

本阶段只进行探索和设计，不创建正式变更，不修改业务代码。

---

4. 创建正式 OpenSpec 变更

执行：

/opsx:propose [change-name]

变更目标：

[需求描述]

请生成并保持一致：

• proposal.md
• delta specs
• design.md
• tasks.md

要求：

• 规格必须描述可观察行为和验收场景。
• 明确范围、非目标、异常行为和边界条件。
• 设计必须对应规格，不得引入未批准功能。
• 任务必须覆盖测试、实现、验证和必要文档。
• 不要修改业务代码。

完成后列出需要人工确认的重要决策。

---

5. 审查 OpenSpec artifacts

请审查当前 OpenSpec 变更中的 proposal.md​、specs​、design.md​ 和 tasks.md。

检查：

• 需求是否完整且无歧义。
• artifacts 之间是否相互一致。
• 每项需求是否有对应验收场景。
• 异常路径、边界条件和兼容性是否明确。
• 设计是否满足需求且没有过度设计。
• tasks.md 是否覆盖全部需求和测试。
• 是否存在无法验证的描述。

只修改 OpenSpec artifacts，不修改业务代码。发现需要产品决策的内容时明确列出，不要自行决定。

---

6. 创建隔离开发环境

请使用 using-git-worktrees，为当前 OpenSpec change 创建独立 Git worktree 和功能分支。

要求：

• 不得直接在主分支开发。
• 检查并保护现有未提交修改。
• 分支名称与 OpenSpec change 名称对应。
• 遵循项目现有 worktree 目录约定。
• 安装必要依赖。
• 运行项目当前的完整基线验证。
• 记录基线提交 SHA 和验证结果。

如果已经位于正确的隔离 worktree，只验证环境，不重复创建。基线失败时停止，不开始实现。

---

7. 制定详细实施计划

请使用 writing-plans​，读取当前 OpenSpec change 的全部 artifacts，将 tasks.md 细化为可直接执行的实施计划。

要求：

• 不改变或扩展 OpenSpec 需求。

• 明确每一步的文件路径和修改目标。

• 按 test-driven-development 规划：

  1. 编写失败测试；
  2. 确认测试因预期原因失败；
  3. 编写最小实现；
  4. 确认测试通过；
  5. 重构并重新验证。

• 标明任务顺序、依赖和验证命令。

• 将任务拆成小而独立的步骤。

• 标明可能并行的独立任务。

• 发现规格问题时明确指出。

本阶段只输出和保存实施计划，不修改业务代码。

---

8. 正常实施代码

执行 /opsx:apply​，以当前 OpenSpec change 的 proposal​、specs​、design​ 和 tasks 为实施依据。

使用：

• subagent-driven-development：按任务逐项实施并进行规格、代码质量审查。
• test-driven-development：严格执行 RED → GREEN → REFACTOR。
• systematic-debugging：出现失败或异常时先定位根因。
• verification-before-completion：声明完成前取得最新验证证据。

要求：

• 按 tasks.md 顺序实施并更新任务状态。
• 不得编写规格之外的功能。
• 不得跳过失败测试直接实现。
• 不得通过删除测试、降低断言或忽略错误使验证通过。
• 每项任务完成后运行相关测试。
• 任务之间存在独立性时才允许并行。
• 遇到阻塞时保留已完成工作并明确报告。

---

9. 最终代码审查

请使用 requesting-code-review​ 对当前分支全部变更进行最终审查，也可以结合 Codex /review。

以以下内容为审查依据：

• 当前 OpenSpec change 的全部 artifacts
• 实施计划
• 基线提交与当前提交之间的 diff

重点检查：

• 规格是否完整实现。
• 是否存在规格外实现。
• 测试是否真实覆盖需求和异常路径。
• 是否存在 Bug、安全问题或兼容性回归。
• 代码职责、接口和错误处理是否清晰。
• 是否存在重复代码、过度设计或无必要依赖。

按 Critical、Important、Minor 分类报告。Critical 和 Important 未处理前，不得进入归档或合并。

---

10. 完成前工程验证

请使用 verification-before-completion 对当前分支进行最终验证。

首先读取项目配置，确定项目实际支持的验证命令，然后运行适用的：

• 单元测试
• 集成测试
• 端到端测试
• lint
• 类型检查
• 构建
• 数据库或迁移验证
• 其他项目规定的检查

要求：

• 使用最新、完整的命令输出作为证据。
• 不得根据之前的运行结果推断当前状态。
• 不得跳过失败项。
• 列出运行的命令、结果和未运行项目的原因。
• 任一必要验证失败时，不得声称完成。

---

11. 验证 OpenSpec 与实现一致

执行：

/opsx:verify [change-name]

检查：

• tasks.md 是否全部完成。
• 每项规格是否有对应实现和测试。
• 实现是否符合 design.md 的关键决策。
• 是否存在未记录的行为变化。
• 是否存在已实现但未写入规格的功能。
• 文档、配置和迁移是否同步。

发现问题时，不要归档。区分是代码错误还是 artifacts 错误，修复正确的一方，然后重新运行工程验证和 /opsx:verify。

---

12. 同步并归档 OpenSpec 变更

确认代码审查、工程验证和 OpenSpec 验证均通过后：

1. 执行 /opsx:sync [change-name]，预览并同步 delta specs。
2. 检查主规格是否准确反映最终实现。
3. 执行 /opsx:archive [change-name]。
4. 确认变更已移动到 archive 目录。
5. 确认归档文件和主规格均包含在 Git 变更中。

存在未完成任务、规格冲突或验证失败时，不得归档。

---

13. 合并或创建 Pull Request

请使用 finishing-a-development-branch 完成当前开发分支。

要求：

• 再次确认最新完整验证通过。

• 汇总实现内容、测试结果、OpenSpec change 和风险。

• 根据当前仓库流程选择：

  • 合并到目标分支；
  • 推送并创建 Pull Request；
  • 保留分支和 worktree；
  • 放弃修改。

• 未经明确允许，不得 force push。

• 合并后验证合并结果。

• 仅在工作安全保存后清理 worktree。

---

14. 创建 Bug 修复变更

针对以下 Bug 创建并实施 OpenSpec change：

[Bug 描述和复现方式]

流程：

1. 使用 systematic-debugging 稳定复现并定位根因。
2. 执行 /opsx:propose fix-[bug-name]，记录当前错误行为和期望行为。
3. 先编写能够复现 Bug 的失败测试。
4. 执行 /opsx:apply，使用 test-driven-development 完成最小修复。
5. 运行回归测试和完整验证。
6. 执行 /opsx:verify，确认修复符合规格。
7. 审查、同步并归档。

不得只掩盖症状，也不得顺便进行无关重构。

---

15. 创建纯重构或技术债变更

针对以下重构目标创建 OpenSpec change：

[重构目标]

要求：

• 明确保证哪些外部行为保持不变。
• 在 proposal 中说明动机、范围和非目标。
• 在 specs 或验收条件中记录兼容性要求。
• 先补足关键行为的特征测试。
• 使用 test-driven-development 小步重构。
• 每一步都运行相关回归测试。
• 不同时引入未批准的新业务行为。
• 使用 requesting-code-review 检查行为漂移。
• 完成后执行完整验证和 /opsx:verify。

---

16. 依赖升级或数据迁移

针对以下升级或迁移创建 OpenSpec change：

[依赖、框架、数据库或数据迁移内容]

要求：

• 调查当前版本、目标版本和官方迁移要求。
• 明确兼容性、停机、回滚和数据风险。
• 在 design 中记录迁移顺序和回滚方案。
• 对破坏性修改提供备份或恢复策略。
• 先编写兼容性和迁移测试。
• 分阶段实施，不混入无关功能。
• 验证旧数据、现有接口和部署流程。
• 完成前不得删除旧路径，除非规格明确批准。

---

17. /opsx:* 命令或 Skill 不可用

当前请求依赖 OpenSpec 或 Superpowers，但对应命令或 Skill 不可用。

请：

1. 检查 OpenSpec 和 Superpowers 是否已正确安装到 Codex。
2. 检查 .codex/skills/openspec-*、Codex prompts 和插件状态。
3. 运行 OpenSpec 状态或更新命令，确认当前 profile。
4. 不要假装已经执行不存在的命令或 Skill。
5. 命令入口不可用但对应 Skill 文件存在时，读取并遵循该 Skill。
6. /opsx:verify 未安装时，先启用对应工作流并执行 openspec update。
7. 仍无法使用时停止，列出缺失组件和最小修复步骤。

不要在工作流能力缺失时直接绕过规格开始编码。

---

18. 工作区存在未提交修改

检测到当前仓库或 worktree 存在未提交修改。

请：

• 显示修改文件和当前分支。
• 判断这些修改是否属于当前任务。
• 不覆盖、不移动、不暂存、不提交用户已有修改。
• 可以安全隔离时，使用 using-git-worktrees 创建新 worktree。
• 无法安全隔离时停止并说明冲突。
• 不得擅自执行 reset、clean、stash、checkout 或删除文件。

只有确认工作安全后才能继续。

---

19. 基线测试在实施前失败

当前功能尚未实施，但基线验证已经失败。

请使用 systematic-debugging：

1. 保存完整失败输出。

2. 确认失败是否可重复。

3. 判断是环境、依赖、配置还是已有代码问题。

4. 不将基线失败归因于当前未开始的功能。

5. 不修改当前 OpenSpec change 的业务代码来掩盖基线问题。

6. 给出：

   • 失败命令；
   • 根因或当前假设；
   • 是否阻塞实施；
   • 建议的独立修复方式。

基线恢复前，不开始当前功能实现。

---

20. 规格存在冲突、缺失或歧义

当前 OpenSpec artifacts 存在冲突、缺失或无法实施的描述。

请：

• 停止受影响任务。
• 指出冲突所在文件和具体条目。
• 说明不同解释会导致的行为差异。
• 根据已有上下文提出最小修订建议。
• 只修改 OpenSpec artifacts，不先修改业务代码。
• 保持 proposal、spec、design 和 tasks 一致。
• 修订后重新审查 artifacts，再执行 /opsx:apply。

不要自行选择产品语义或隐藏冲突。

---

21. 实施中发现设计需要调整

实施过程中发现 design.md 无法满足规格，或存在更安全、简单的实现方式。

请：

1. 暂停受影响任务。
2. 说明原设计的问题和证据。
3. 确认需求本身是否变化。
4. 需求不变时，仅修订 design.md 和相关 tasks。
5. 行为变化时，同时修订 proposal 和 delta specs。
6. 审查所有 artifacts 的一致性。
7. 重新制定受影响部分的实施计划。
8. 重新执行 /opsx:apply。

不得先改变代码，再事后让规格迁就代码。

---

22. 任务过大或无法直接执行

当前任务跨越多个子系统、文件过多或无法在一次独立步骤内安全完成。

请使用 writing-plans：

• 分析任务边界和依赖。
• 将任务拆为可独立测试的小步骤。
• 将不同能力或不同发布周期的需求拆为独立 OpenSpec changes。
• 标明共享接口和集成顺序。
• 只有无共享状态、无顺序依赖的任务才能并行。
• 不通过增加临时复杂度来强行一次完成。

更新 tasks.md 和实施计划后再继续。

---

23. 测试失败、Bug 或异常行为

出现测试失败、Bug 或异常行为时，使用 systematic-debugging。

严格执行：

1. 稳定复现问题。
2. 收集错误输出、日志和相关状态。
3. 沿调用和数据流定位根因。
4. 提出一个可验证假设。
5. 用最小实验验证假设。
6. 为问题编写失败测试。
7. 修改最少代码修复根因。
8. 运行相关测试和完整回归验证。

不要连续尝试无依据的修改，不要增加 sleep 掩盖竞态，也不要只处理表面错误。

---

24. 测试偶发失败或存在竞态

当前测试存在间歇性失败、时间依赖或竞态。

请使用 systematic-debugging：

• 重复运行并记录失败频率。
• 检查共享状态、异步任务、时间、随机数、端口和外部资源。
• 使用条件等待替代固定 sleep。
• 隔离测试数据和全局状态。
• 固定必要的时间、随机源或环境。
• 不通过增加重试次数隐藏真实问题。
• 修复后重复运行相关测试，证明稳定性。
• 再运行完整测试套件。

---

25. 依赖安装、网络或外部服务失败

当前任务被依赖安装、网络、数据库或第三方服务阻塞。

请：

• 区分项目代码问题和外部环境问题。
• 保存失败命令及原始错误。
• 检查锁文件、版本、凭证、代理和服务状态。
• 不删除锁文件或随意升级依赖作为第一反应。
• 不在代码中硬编码凭证。
• 可使用本地 mock 或测试替身时，确保其行为由规格定义。
• 外部阻塞无法解除时，完成不依赖该服务的安全工作，并明确列出未验证项。
• 不得声称完整验证通过。

---

26. 已经先写了实现，违反 TDD

发现生产代码在失败测试之前已经编写。

请使用 test-driven-development 纠正：

1. 暂停继续扩展实现。
2. 确认新增行为尚未被可靠测试覆盖。
3. 在不丢失用户工作前提下，隔离或暂时撤回未验证实现。
4. 编写能够因缺少该行为而失败的测试。
5. 确认测试失败原因正确。
6. 再进行最小实现。
7. 运行测试并重构。
8. 检查是否还有"先实现后补测试"的代码。

不得编写永远不会失败的形式化测试。

---

27. 安全、认证、支付或隐私敏感变更

当前 change 涉及安全、认证、授权、支付、密钥、个人信息或敏感数据。

请：

• 在 OpenSpec 中明确威胁边界、授权规则和失败行为。
• 默认拒绝未授权访问。
• 不记录密码、令牌、支付信息或敏感个人数据。
• 检查输入验证、输出编码、权限绕过和信息泄漏。
• 编写正常路径、拒绝路径和越权测试。
• 检查密钥和环境变量处理。
• 使用独立代码审查重点检查安全回归。
• 运行项目已有安全检查。
• 无法证明安全属性时，不得声称完成。

---

28. 收到代码审查意见

请使用 receiving-code-review 处理以下审查意见：

[审查意见]

要求：

• 逐条理解意见，不机械接受或拒绝。
• 在代码、规格和测试中验证意见是否成立。
• Critical 和 Important 优先处理。
• 成立时进行最小修复并补充测试。
• 不成立时提供技术证据和具体理由。
• 修复后重新运行相关测试和完整验证。
• 更新 OpenSpec artifacts，仅限审查揭示了真实规格缺失时。
• 输出每条意见的处理状态。

---

29. /opsx:verify 发现实现与规格不一致

/opsx:verify 发现代码、测试、设计或任务状态不一致。

请：

1. 逐条分类：

   • 实现缺失；
   • 实现错误；
   • 测试缺失；
   • artifacts 已过时；
   • 存在规格外功能。

2. 以批准后的实际需求为判断依据。

3. 代码错误时修复代码和测试。

4. artifacts 错误时修订 artifacts，并说明原因。

5. 删除无意引入的规格外行为。

6. 重新运行完整工程验证。

7. 再次执行 /opsx:verify。

问题全部解决前不得同步或归档。

---

30. 任务只能部分完成或被阻塞

当前 OpenSpec change 无法全部完成。

请：

• 保留已经验证通过的安全修改。

• 不勾选未完成任务。

• 为每个阻塞项记录原因、证据和继续条件。

• 区分：

  • DONE
  • DONE_WITH_CONCERNS
  • BLOCKED
  • NEEDS_CONTEXT

• 不用临时代码假装完成。

• 不归档未完成 change。

• 可以独立交付的部分应先确认是否需要拆成单独 change。

• 输出当前状态和后续最小行动。

---

31. 多个独立任务需要并行

当前计划包含多个真正独立、没有共享写入状态的任务。

请使用 dispatching-parallel-agents​ 或 subagent-driven-development：

• 明确每个子任务的输入、输出、文件范围和验收条件。
• 不让多个代理同时修改同一文件或共享接口。
• 每个代理独立运行相关测试。
• 主代理负责集成、冲突检查和完整验证。
• 发现依赖关系时立即停止并行，恢复顺序执行。
• 不并行执行需要先后决策的设计任务。

---

32. 多个 OpenSpec changes 存在冲突

检测到多个 active changes 修改相同规格、文件或行为。

请：

• 列出冲突的 changes 和冲突位置。
• 读取各自 proposal、spec、design 和实际实现。
• 确定依赖顺序和最终期望行为。
• 不通过简单覆盖文件解决语义冲突。
• 必要时先同步或归档基础 change，再更新后续 change。
• 多个 change 均已完成时，可以使用 /opsx:bulk-archive，但必须先检查实际实现。
• 冲突未解决前不得归档。

---

33. 本地通过但 CI 失败

本地验证通过，但 CI 失败。

请使用 systematic-debugging：

• 获取完整 CI 日志和失败步骤。
• 比较运行环境、版本、环境变量、缓存和命令差异。
• 在本地尽可能复现 CI 环境。
• 检查测试顺序、时区、文件大小写、路径和并行执行问题。
• 不通过重新运行 CI 碰运气。
• 编写或调整测试，使问题能够稳定复现。
• 修复后同时运行本地验证和相关 CI 流程。

---

34. 合并冲突

当前分支与目标分支存在合并冲突。

请：

• 获取目标分支最新状态。
• 列出冲突文件及双方意图。
• 结合 OpenSpec artifacts 判断正确语义。
• 不机械选择 ours 或 theirs。
• 保留双方兼容且必要的修改。
• 冲突解决后运行相关测试及完整验证。
• 再执行 OpenSpec 一致性检查。
• 未验证前不得提交合并结果。

---

35. 性能回归

当前变更可能引入性能回归。

请：

• 明确需要保护的性能指标和场景。
• 建立可重复的基准或性能测试。
• 先测量基线，再测量当前实现。
• 使用分析工具定位瓶颈，不凭直觉优化。
• 不牺牲正确性、安全性或可维护性换取无证据优化。
• 在 OpenSpec 中记录必要的性能要求。
• 修复后报告基线、变更后结果和测试条件。

---

36. 中断后恢复实施

请恢复当前 OpenSpec change 的开发工作。

开始前：

1. 读取当前分支、worktree 和 Git 状态。
2. 读取全部 OpenSpec artifacts。
3. 检查 tasks.md 已完成和未完成项。
4. 阅读实施计划和最近提交。
5. 运行与最近完成任务相关的验证。
6. 不假设之前声称完成的内容仍然有效。
7. 从第一个未完成且无依赖阻塞的任务继续。
8. 保留并报告任何未提交修改或异常状态。

---

37. 放弃或回滚当前开发

请使用 finishing-a-development-branch 安全处理当前失败或取消的 change。

要求：

• 显示当前分支、worktree、提交和未提交修改。
• 区分用户已有工作与本次 change 的工作。
• 在执行删除、reset、revert 或清理前说明影响。
• 未经明确授权，不删除分支、worktree 或未提交文件。
• 已合并的变更优先使用可审计的 revert，而不是改写历史。
• OpenSpec change 不再实施时，记录取消原因；不要将其标记为成功完成。
• 确认所有需要保留的内容已经安全保存后再清理。

其中第 ​1---13 部分是正常主线 ​，第 ​14---37 部分按实际异常单独调用，不需要每次全部发送给 Codex。