AI 规范驱动开发（SDD）实战指南

前言：为什么要用这套组合？

传统的 AI 辅助编程模式是：你提需求 → AI 直接写代码 → 你发现不对 → 反复修改。这种模式下，设计共识会随着长对话消失，且 AI 缺乏主动写测试和维护工程质量的纪律，最终往往变成"AI 制造技术债"。为了破局，我们需要引入规范驱动开发（SDD, Spec-Driven Development）：

OpenSpec 定方向（管"写什么"）：锁定你的设计意图，把模糊的想法翻译成结构化的规格文档。
Superpowers 定纪律（管"怎么做"）：作为 AI 执行的"纪律警察"，强制 AI 走 TDD（测试驱动开发）流程，先写测试再写实现，确保代码质量。

一、环境准备

我们将以 Claude Code 作为底层执行引擎来实践。

1. 前置环境检查

确保你的电脑已安装 Node.js (v16 及以上) 和 Claude Code CLI。

复制代码

复制node --version
claude --version

2. 安装 Superpowers 插件

进入 Claude Code 会话后，通过官方插件市场一键安装（这是成功率最高的方式）：

复制代码

/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

3. 安装 OpenSpec CLI

全局安装 OpenSpec 命令行工具，用于管理规格文档链：

复制代码

复制npm install -g @fission-ai/openspec

二、核心工作流实战：6 步跑通完整闭环

SDD 的核心设计理念是 Action Not Phases（按需调用独立能力，而非死板的阶段）。以下是标准的从零到一开发流程（propose → apply → archive）：

Step 1: 头脑风暴与需求提案 (Propose)

千万不要一上来就让 AI 写代码！第一步是理清思路。

操作：向 AI 描述你的自然语言需求，并执行提案生成（如使用 sdd-propose 命令）。
产物：AI 会生成 proposal.md（变更提案）。
目的：明确"为什么做"、"目标/非目标"以及"影响范围"，确保你和 AI 在大方向上达成共识。

Step 2: 技术设计与规格拆解 (Design & Specs)

基于提案，让 AI 输出具体的技术方案和业务场景。

操作：让 AI 细化设计（如使用 sdd-plan 相关的设计指令）。
产物：

- design.md：记录技术方案选择、替代方案对比和风险评估。
- specs/*.md：采用 Given/When/Then 格式描述的具体场景需求。

最佳实践：作为开发者/架构师，你此时只需做一件事------审批方案。如果不满意，直接让 AI 修改文档，而不是修改代码。

Step 3: 任务原子化拆分 (Tasks)

将规格转化为可执行的清单，任务粒度直接决定了 AI 的成功率。

产物：生成 tasks.md（包含 Checkbox 的任务清单）。
避坑指南：任务必须原子化。一个任务不能包含太复杂的功能，必须拆分到可以独立进行"RED（失败测试）+ GREEN（通过测试）"的粒度。

Step 4: Superpowers 强制 TDD 执行 (Code)

规范锁定后，Superpowers 接管代码生成。

操作：触发代码实施（如使用 sdd-code）。
执行逻辑：Superpowers 会强制 AI 按照 tasks.md 逐个打勾。对于每个任务，AI 必须严格遵守 TDD 铁律：先写测试用例 → 运行测试（必然失败） → 编写业务代码 → 运行测试（通过）。这彻底杜绝了 AI "一口气写完代码再补测试"的敷衍行为。

Step 5: 全面验证与审查 (Verify)

代码跑通后，建立验证闭环。

操作：执行验证（如 sdd-verify）。
执行逻辑：Superpowers 会自动运行单元测试、E2E 测试，甚至对比 UI 视觉规格，确保生成的代码与 specs 中定义的契约完全一致。

Step 6: 归档合并与清理 (Archive)

开发完成并验收签字后，进行文档收尾。

操作：执行归档（如 opsx:archive 或 sdd-ship）。
执行逻辑：本次开发产生的"增量规范（Delta Spec）"会被自动合并回主规范库，并带有日期前缀的归档路径。这保证了项目的文档永远是最新的，永远与代码保持一致。

三、高阶避坑指南与经验总结

利用 Subagent 隔离上下文：在执行复杂的 tasks.md 时，建议利用子代理（Subagent）隔离不同的原子任务。每次 Dispatch 一个子代理只做一件事，做完后销毁，这能有效防止 AI 在长对话中产生幻觉或偏离 design.md 的架构决策。
不怕对话丢失，共识全在文档里：如果你在长对话中觉得 AI 开始胡言乱语，可以直接 /clear 清理上下文。因为你的所有设计共识都已经持久化在 Artifact 链（proposal → design → specs）中，AI 重新读取文档即可满血复活[5]。
把最佳实践固化为 Workflow：你可以将常用的检查流程（如 code-review.md、deploy-check.md）封装成 Superpowers 的 Workflow。把"最佳实践"变成"可执行的代码"，直接调用命令，彻底告别手工作坊[7]。

通过这套流程，你不仅获得了一个不知疲倦的 AI 程序员，还同时配备了一个严谨的架构师和苛刻的 QA 测试员，真正实现了一人团队的极简、高质量开发[3]。如果你在长对话中觉得 AI 开始胡言乱语，可以直接 `/clear` 清理上下文。因为你的所有设计共识都已经持久化在 Artifact 链（proposal → design → specs）中，AI 重新读取文档即可满血复活[citation:5]。 3. **把最佳实践固化为 Workflow**：你可以将常用的检查流程（如 `code-review.md`、`deploy-check.md`）封装成 Superpowers 的 Workflow。把"最佳实践"变成"可执行的代码"，直接调用命令，彻底告别手工作坊[citation:7]。通过这套流程，你不仅获得了一个不知疲倦的 AI 程序员，还同时配备了一个严谨的架构师和苛刻的 QA 测试员，真正实现了一人团队的极简、高质量开发[citation:3]。