OpenSpec与Superpowers整合的SDD自定义工作流实践

SDD 实践：用 OpenSpec + Superpowers 打造你的专属开发工作流

AI 编码助手如今已能一次性完成整个功能的编写。然而，当需要它承担更复杂、更具长期性的任务时，两个令人困扰的问题便会逐渐暴露。

第一个问题是，随着对话深入，设计共识会逐渐流失。AI 在长对话中容易“遗忘”，之前头脑风暴阶段已经否决的方案，可能在第五十轮对话时又被它重新提出。当你执行一个 /clear 清空上下文后，之前来之不易的共识便荡然无存。 第二个问题更为根本：AI 虽然能编写代码，却缺乏主动维护工程质量的“自觉性”。它不会自动优先编写测试，不会系统性地定位 Bug 的根本原因，更不会在动手编码前查阅设计文档。如果没有外部规则加以约束，最终的产出质量完全依赖于人类工程师在每次交互中是否保持足够的警惕和细致。 这两个问题恰好被两个工具精准解决： - **OpenSpec** 负责“定义做什么”。它通过结构化的文档链（从提案到规格说明，再到设计文档和任务）来管理每一次变更，采用“增量规格”模式适配代码库的日常演进，并利用 GIVEN/WHEN/THEN 这类场景化描述确保每个需求都可验证。 - **Superpowers** 负责“指导怎么做”。它通过一套严格的执行纪律（例如 TDD 铁律、系统化调试方法、双阶段代码审查）来约束 AI 的行为模式。 然而，单独使用其中任何一个都不够完整。OpenSpec 拥有完善的需求规格流程，却缺少 TDD 的纪律性；Superpowers 具备强大的执行方法论，但设计共识却缺乏持久的存储载体。SDD 的整合目标，正是让这两个工具的能力形成互补，而非各自为战。

整合的核心理念

**Action Not Phases（行动而非阶段）** SDD 的每一个操作都是一个独立的能力单元（action），而非必须按顺序执行的阶段（phase）。这意味着你可以根据当前需求灵活组合。 依赖关系被定义为“前置条件”（enabler），而非“阻断关卡”（gate）。开发大型功能时，你可以从头到尾完整走一遍流程；但修复一个小问题，完全可以跳过头脑风暴，直接使用 sdd-propose。这并非“违规跳阶段”，而是按需选择最匹配的能力组合。 **产物接力** 每个 action 的输出即是下一个 action 的输入。最关键的是，所有中间状态都会被持久化为文件，而非停留在对话历史中。 这带来了两个关键优势： 1. 在两个步骤之间的任何时刻，你都可以安全地执行 /clear。因为所有状态都保存在文件系统里，而非对话历史中。 2. 每个 action 是“无状态”的——它只读取文件，不依赖之前的对话记忆。这从根本上解决了 AI 的“失忆”问题。 **不修改底层工具** SDD 是一个纯粹的编排层。它不会修改 OpenSpec 或 Superpowers 的任何原始文件。这样一来，两个底层工具都可以独立升级，互不影响。

薄编排架构

为什么要强调“薄”？在早期设计中，SDD 的 skill 复制了大量 OpenSpec 和 Superpowers 的核心逻辑，例如自己实现一套苏格拉底式提问流程。这导致上游工具一升级，SDD 就得跟着修改，修一个 Bug 也需要在多处改动。 薄编排的思路非常简单：**SDD skill 只负责编排，核心工作全部委托给底层的 skill。** 对用户而言，只需认识 sdd-* 这一套指令，完全不需要关心背后是 OpenSpec 还是 Superpowers。SDD 保留了编排控制权（例如 review 循环、决策追溯检查），而底层 skill 则专注于做它们最擅长的事情。 每个 SDD skill 都遵循一个统一的三段式结构： | 阶段 | 执行方 | 职责 | | :--- | :--- | :--- | | 前置逻辑 | SDD | 定位变更目录、读取已有产物、检查前置条件 | | 核心执行 | 底层 skill | 把核心工作交给 OpenSpec 或 Superpowers | | 后置逻辑 | SDD | 执行 review 循环、校验产物格式、提供下一步引导 | 这种分层设计，使整个系统既灵活又稳健。

三层架构与委托关系

整个系统分为三层：最上层是 SDD 的编排层，中间一层是 Superpowers 的纪律层，最下层是 OpenSpec 的规格层。每个 SDD 的 action 都清晰地定义了它委托给谁，以及自己完成了哪些工作。 从 sdd-doctor 的环境检查，到 sdd-brainstorm 的深度探索，再到 sdd-ship 的最终归档，每一个环节都有明确的委托关系和自有逻辑，形成了一条完整的、可追溯的开发链路。

文档依赖链与模板设计

文档之间存在明确的依赖关系。有几个文档是必需的：`proposal.md`、`specs/`、`tasks.md`，它们是整个规格流程的骨架。其他文档如 `brainstorm.md`、`design.md`、`plan.md` 则是可选的，可以根据变更的复杂度按需生成。 这里需要特别说明 `tasks.md` 和 `plan.md` 的区别，很多人容易混淆它们。它们回答的是不同层级的问题，不能合并： - **tasks.md** 回答“**做什么**”，是 OpenSpec 的产物。它的颗粒度是“规格需求”级别，每个任务都关联到一个具体的 spec 场景。 - **plan.md** 回答“**怎么做**”，是 Superpowers 的产物。它的颗粒度是“工程师 2-5 分钟的具体操作”，例如“在哪个文件的哪个方法里编写测试”、“运行什么命令来验证”。 `tasks.md` 中的一条任务可能是“实现主题切换 API”，而 `plan.md` 会将它展开为具体的 RED、GREEN、重构步骤以及运行命令。这种分工让规划既清晰又可执行。

Review 机制

SDD 中的 review 分为两种，设计意图各不相同。 一种是“内嵌 Review”，它不是一个独立的步骤，而是 action 内部的质量保障机制。例如在 `sdd-brainstorm` 完成后，会自动触发一次 review 来判断方案是否完整、决策是否清晰。在 `sdd-plan` 完成后也会有类似的 review 来检查计划质量。 另一种是“独立 Review”，它是一个可选的 action，按需触发。对于大型特性，在实施前推荐执行 `sdd-review-spec` 来审查规格质量；在每个批次实施后，执行 `sdd-review-code` 来审查代码。 值得一提的是代码审查的双阶段设计。`sdd-review-code` 会分两步走：第一阶段先做“Spec 合规审查”，判断代码是否真正实现了规格文档中描述的场景；第二阶段再做“代码质量审查”，关注可读性、设计模式等。这个顺序很重要：如果代码本身就没写对，讨论代码质量就毫无意义。**先确认“做对了”，再讨论“做好了”**。

信息丢失与上下文卫生

这是一个非常实际的挑战。从 `brainstorm.md` 到 `plan.md`，中间可能经历多次 /clear，早期的关键约束很容易丢失。 SDD 通过两层机制来防护。第一层是在模板层面设置“决策追溯”必填节，强制要求每个决策都要引用来源。第二层是后置逻辑的自动检查，例如 `sdd-propose` 完成后会验证提案是否引用了头脑风暴中的所有关键决策。 关于上下文清理，AI 辅助开发时，对话上下文膨胀是一个大问题。SDD 的解决方案非常干脆：**将所有信息持久化，然后安心清空**。每个 action 完成后，你可以放心地执行 /clear，因为所有的产物都保存在文件系统里。对话历史从来都不是可靠的状态存储。

完整工作流与渐进采用

一个大型特性的标准路径可能会经历：头脑风暴、快进生成文档、审查规格、细化计划、分批 TDD 实施、代码审查，直到最后的全面验证和归档。 而一个小修复的路径则可以非常短：直接走提案、快进、计划、实施、归档，跳过所有不必要的环节。 你不需要一开始就使用全部 11 个 action。SDD 推荐分阶段引入： - **第一阶段**：建立核心习惯，使用 propose → ff → plan → code → ship，实现 Spec 驱动和 TDD。 - **第二阶段**：加入 review 纪律，引入 review-spec 和 review-code。 - **第三阶段**：建立完整的工程纪律，引入 brainstorm 和 verify。 每个阶段都能独立地带来价值。

适用场景

SDD 在以下几种场景中价值最为突出： - **开发复杂特性**：当需求复杂、边界条件较多时，完整的 brainstorm → spec → TDD 流程能有效降低风险。 - **维护长期项目**：归档机制能将每一次变更的历史转化为“制度记忆”，新成员可以通过查阅 archive 来了解当年那些设计决策的来龙去脉。 - **团队协作**：统一的文档体系提供了共同的语言，review 也让代码审查更具焦点。 当然，对于简单的一次性脚本或快速原型验证，走完完整流程的开销可能大于收益。这正是渐进采用策略的意义所在——让每个团队和项目都能找到最适合自己的平衡点。