你有没有发现AI 写代码越来越像那么回事了但一上生产就各种翻车需求理解偏了、改 A 坏 B、代码风格混乱、测试补得乱七八糟——更气人的是你问它为什么这么写它还能振振有词地给你编一个理由。我自己从去年开始重度使用 AI 编码助手从 Cursor 到 Claude Code 再到 Codex CLI中间踩过的坑能写一本书。后来真正让我从AI 帮我写代码升级到AI 按规格写代码的是一套组合OpenSpec Superpowers也就是这几年越来越热的SDDSpec-Driven Development规格驱动开发。这篇文章不聊虚的直接把我从零落地这套流程的完整思路、安装步骤、可复制的 SOP 以及踩过的坑全部拆给你。先给结论SDD 的核心不是让 AI 少写代码而是让 AI 在动手前先把要做什么、怎么做、怎么验收想清楚、写下来再由人来审批这个计划书。OpenSpec 负责把规格文档变成可管理的工程资产Superpowers 则负责给 AI 装上先思考后行动的工作流。这套东西适合谁适合所有用 AI 写代码但总觉得失控的开发者尤其是团队协作场景里需要约束 AI 输出质量的工程负责人。哪怕你是个人开发者一个人维护多个项目这套流程也能让你少当很多次救火队员。1. 先弄清楚我们到底在解决什么问题1.1 AI 写代码失控的三个典型现场我在不同项目里反复遇到过同样的三类问题如果你也用过 AI 写代码估计能对号入座。第一类是需求漂移。你跟 AI 说帮我加一个用户注销功能它上下文里可能带着之前聊过的某个无关需求结果把注销做成了软删除匿名化通知管理员的全套方案。功能是完整但不是你要的改起来还特别费劲。第二类是上下文断裂。一个文件超过一定长度或者项目文件一多AI 就开始失忆。它可能重写了一个已经废弃的工具函数也可能在一个不应该出现的地方引入了新的依赖。最离谱的一次AI 在一个纯前端的项目里给我 import 了一个 Node.js 内置模块编译直接挂。第三类是验收缺失。让 AI 写完代码它自己说完成但根本没有对照原始需求做验证。测试是写了但测的是它自己理解的功能而不是你描述的需求。等 code review 的时候才发现一堆逻辑从一开始就错了方向返工成本极高。这三类问题的根子其实是一个AI 的默认行为是直接生成答案而不是先理解问题。而我们的常规开发流程恰恰需要后者。SDD 就是把这个先理解问题的过程强制放到流程里。1.2 从 TDD 到 SDD规格为何要先于代码很多人听说过 TDD测试驱动开发先写测试再写实现让测试用例成为需求的可执行表达。SDD 可以理解为 TDD 的上一级抽象——它先要求你把**行为规格Specification**写清楚再基于规格拆任务、写测试、写代码。为什么更偏好规格先行因为测试本质上也是一种代码它依然存在理解偏差的问题。你让 AI 根据需求文档写测试AI 可能写出和需求不一致的测试。规格则更接近自然语言和结构化描述是人可以直接审核的。而且规格是和实现无关的换技术栈、重构代码规格都不需要动但测试和代码都要跟着变。再直白一点TDD 解决的是代码对不对SDD 解决的是代码该不该这么写。先把该不该定了对不对才有意义。OpenSpec 和 Superpowers 的组合恰好把这两层都覆盖了。2. 组合拳拆解OpenSpec 负责管文档Superpowers 负责管行为2.1 OpenSpec给规格文档上版本管理OpenSpec 是一个开源工具核心目标就是把规格变成像代码一样可管理、可评审、可追溯的工程资产。它提供了一套 CLI 命令让你在项目里初始化一个openspec/目录里面按照约定组织所有的规格文档。它的工作模型是以Change Proposal变更提案为中心。每当你有一个新需求就创建一个提案提案里包含关于这个变更的完整描述背景、目标、具体规格、任务清单、验收标准。这样每次变更都是独立的、可审查的不会出现需求散落在聊天记录里的情况。从项目结构上看OpenSpec 初始化后会生成类似这样的目录openspec/ ├── project.md # 项目整体说明 ├── specs/ # 已批准并实施的规格 └── proposals/ # 待评审或正在实施的提案 └── user-account-deletion/ ├── proposal.json # 提案元数据状态、负责人、日期等 ├── spec.md # 规格描述做什么、怎么做、边界 ├── tasks.md # 任务拆解 └── acceptance-criteria.md # 验收标准这个目录结构本身就是一种约束AI 必须按照模板产出内容而不是自由发挥。同时因为所有内容都是文本文件天然支持 Git 评审、Diff 对比、版本回滚。你可以在 PR 里 review 规格就像 review 代码一样。2.2 Superpowers压制 AI 的答题冲动Superpowers 是一套 Skills 集合出自开源社区主要用在 Claude Code、Codex CLI 这类 AI 编码代理上。它的核心理念非常朴素让 AI 在写代码之前先完成一系列思维动作——头脑风暴、制定计划、写任务清单、排序执行。说白了就是给 AI 装了一个先思考后动手的工作流。它的实际形态是一组 skill 目录包含brainstorming/、writing-plans/、implementing-plans/、debugging/、test-driven-development/等。AI 在项目里初始化这些 skills 后会按照 skill 里的提示词逐步执行。比如它接收一个新需求会先调用 brainstorming 相关 skill 向你提一堆澄清问题而不是直接开写。这对解决我前面说的三类问题非常有效需求漂移被前置澄清挡掉上下文断裂被结构化的计划书补上验收缺失被测试必须先行的规则堵死。Superpowers 不是某个具体的插件而是一套行为规范包你可以在不同 AI 工具里复用它。2.3 两者的边界在哪里怎么配合简单说OpenSpec 管写什么Superpowers 管怎么写。OpenSpec 是纯文档层的工具它不关心你用哪个 AI、哪个编辑器只负责把规格文档组织好。Superpowers 是 AI 行为层的工具它管的是 AI 在执行任务时的思考流程和输出顺序。两者配合的方式是Superpowers 把 OpenSpec 生成的规格文档当作输入和权威依据AI 在写代码前先读取规格再按规格拆解任务最后实现时严格对照规格。我这里给出一个简洁的协作模型层级工具解决的问题需求层OpenSpec Proposal需求不明、范围不清规格层OpenSpec spec.md acceptance-criteria.md实现预期不一致、验收无标准任务层Superpowers writing-plansAI 跳过计划直接写代码执行层Superpowers implementing-plans TDD代码偏离规格、测试缺失两者不是竞争关系而是上下游关系。OpenSpec 是合同Superpowers 是按合同施工的流程。没有 SuperpowersOpenSpec 只是普通的文档管理工具没有 OpenSpecSuperpowers 能保证 AI 按计划干活但计划本身的质量没人把关。3. 环境搭建从零装好 OpenSpec 和 Superpowers3.1 初始化 OpenSpec 工作区安装 OpenSpec 最直接的方式是通过 Homebrew 或直接拉取源码编译。我习惯用 Homebrew干净且升级方便# 安装 OpenSpec CLI brew install openspec # 在项目根目录初始化 openspec init # 如果项目里还没有 Git先 git initopenspec init会创建一个openspec/目录同时生成project.md模板。这个文件用来描述项目整体信息AI 在阅读规格前会先读它了解上下文。你在project.md里至少要写清楚项目是干什么的、技术栈是什么、代码结构约定有哪些。提示openspec init也可以用openspec init --force重置已有配置但会覆盖你之前的改动慎用。3.2 安装并挂载 Superpowers SkillsSuperpowers 的安装方式取决于你用的 AI 工具。以目前社区里用得最多的 Claude Code 为例有两种方式。第一种是通过 Claude Code 的插件市场安装# 在 Claude Code 里执行 /plugin marketplace add obra/superpowers-marketplace /plugin install superpowerssuperpowers第二种也是更通用的方式是直接把 skills 克隆到项目的.claude/skills/目录# 在项目根目录执行 git clone https://github.com/obra/superpowers.git .claude/skills/superpowers这样项目里的 Claude Code 会自动识别这些 skills。如果你用的是 Cursor 或 Codex CLI逻辑也是类似的——把 skills 放到对应的配置目录下。以 Codex CLI 为例通常放在~/.codex/skills/或项目.codex/skills/下。3.3 验证环境是否就绪装完最怕的就是看似装好了实际没生效。我每次都会快速做一个冒烟测试。先验证 OpenSpecopenspec --version openspec validateopenspec validate会检查项目里的规格文档是否符合格式要求。如果没有任何输出且退出码为 0说明环境没问题。验证 Superpowers 是否被 AI 正确加载最直接的方式是问 AI 一句话你现在有哪些 skills 可用请列出来。如果它列出了 brainstorming、writing-plans、implementing-plans 等项目说明加载成功。如果它说我没有 skills多半是路径配置不对。这时候检查一下 skills 目录的层级注意不要把superpowers/superpowers/嵌套多了一层。3.4 配置建议给 AI 一个启动开关我建议在项目里加一个CLAUDE.md或者AGENTS.md文件取决于你用哪个 AI 工具写清楚工作规范。比如# 项目协作规范 1. 收到新需求时先读取 openspec/proposals/ 下相关提案理解规格后再动手。 2. 如果没有对应提案必须先创建提案并让用户确认再开始编码。 3. 编写代码时必须严格对照 acceptance-criteria 逐条实现。 4. 任何与规格不符的改动必须先修改规格文档再修改代码。这个文件相当于告诉 AI遇到需求先走流程是保证 SDD 落地的关键一环。没有它AI 还是会回到直接写代码的默认行为。4. 可复制的 SDD 落地 SOP七个步骤下面这套 SOP 是我个人项目中反复验证过的流程每一步我都标了目的和关键输出物。你可以直接抄走再按自己团队的工作习惯微调。4.1 第 0 步需求澄清AI 提问人类回答收到需求后第一件事不是写规格而是让 AI 通过 Superpowers 的 brainstorming skill 向你提问题。你需要回答清楚这个功能解决什么问题不做的代价是什么目标用户是谁有什么使用前提有哪些边界场景比如无权限、网络异常、数据为空等。性能、安全、合规有没有硬性要求需不需要兼容旧的流程和数据这一步的输出物是需求澄清记录可以是一段对话摘要最好直接粘贴进后续的 proposal 里作为背景。4.2 第 1 步创建 Change Proposal在需求理解一致后用 OpenSpec 创建提案openspec new user-account-deletion这会生成一个提案目录和模板文件。你别急着让 AI 写先自己在proposal.json里填好元信息提案名称、负责人、创建日期、状态draft/under-review/approved/implemented。4.3 第 2 步AI 根据澄清内容撰写规格这是整个流程的核心。把需求澄清记录交给 AI让它基于模板撰写spec.md和acceptance-criteria.md。有一个经验不要一次让 AI 写完所有内容而是分两个阶段。第一阶段只写spec.md第二阶段让 AI 对着spec.md写验收标准。这样验收标准才会真正和规格对齐而不是 AI 自己脑补一套。写完之后你作为人类必须通读一遍规格确认如果我是一个完全不了解项目的新人看到这份规格能不能直接实现。4.4 第 3 步人类评审规格锁定范围规格文档写好后走一次评审。评审时关注三个问题范围是否合理有没有过度设计或遗漏关键路径验收标准是否可测每一条都必须是可以明确判定通过/失败的。边界条件是否覆盖至少要考虑输入异常、权限不足、重复提交三种情况。评审通过后把 proposal 的状态改为approved。这一步务必用 Git 打一个 tag 或 commit锚定规格锁定的时间点。之后任何改动都必须先改规格再改代码。4.5 第 4 步AI 基于规格拆解任务并制定计划状态变成 approved 后让 AI 读取tasks.md模板根据spec.md拆解实施任务。这里 Superpowers 的 writing-plans skill 会起作用AI 会生成一个详细的实施计划包括每个任务的技术方案、涉及的文件、依赖关系、风险点。你需要在计划里重点检查两点任务拆解是否足够小每个任务最好控制在一次代码提交的量级。顺序是否合理一般来说先搭骨架再填血肉先做数据层再做接口层最后做 UI。4.6 第 5 步按计划逐项实施严格对照验收标准这一步进入 implementing-plans 和 TDD 流程。每个任务完成后AI 需要把对应的验收标准标为已通过并附上测试证据。这里有个很实用的技巧让 AI 每完成一个任务就暂停等你 review 再继续下一个。虽然 ChatGPT 和 Claude 都支持连续执行但连续执行意味着你失去了中途纠偏的机会。我自己的习惯是写完一个任务就 commit 一次commit message 里带上任务编号方便追溯。4.7 第 6 步整体验收与回归所有任务完成后做一次整体验收。让 AI 基于acceptance-criteria.md逐条跑一遍验证输出规格验收表列出每条标准的验证方法和结果。这一步能有效防止 AI 在实现过程中自以为完成了。如果验收发现问题回到 4.5 步修而不是绕过规格直接改代码。这是整个 SDD 流程纪律性的体现——规格是唯一事实来源。5. 实战记录一个真实功能的落地全程光讲框架不够我拿一个真实例子跑一遍完整流程。假设我们要给项目加一个用户注销账号的功能下面是我实际执行时留下的关键产物。5.1 需求澄清记录节选功能目标允许用户永久注销自己的账号注销后数据进入待删除队列30 天后物理删除。边界注销前必须二次确认如果用户有未完结的订单禁止注销并提示原因。安全要求注销接口需要登录态校验且需要图形验证码防止脚本批量操作。数据要求注销后用户无法登录但保留基本脱敏信息用于合规审计。5.2 规格文件的实际内容简化在openspec/proposals/user-account-deletion/spec.md中写## 概述 提供用户主动注销账号的能力注销后账户进入禁用状态数据进入延迟删除队列。 ## 详细规格 - 用户在「设置 - 账号安全」页面可发起注销申请。 - 发起注销前需通过图形验证码校验。 - 若用户存在未完结订单页面展示拦截提示不允许发起注销。 - 注销申请成功后账户立即标记为 DELETING禁止登录及一切写操作。 - 30 天后后台任务对标记为 DELETING 的账户执行物理数据清理。 - 清理完成后保留脱敏记录 180 天用于审计查询。 ## 边界条件 - 已注销账户的手机号/邮箱可以被重新注册。 - 注销操作不可逆需前端二次确认弹窗。5.3 验收标准节选在acceptance-criteria.md中写- [ ] AC1登录用户在设置页面可见「注销账号」入口。 - [ ] AC2点击注销后弹出二次确认框确认后展示验证码输入框。 - [ ] AC3验证码错误时接口返回 400 以及可读错误信息不产生注销申请。 - [ ] AC4用户存在未完结订单时注销接口返回 409前端展示具体拦截原因。 - [ ] AC5注销成功后用户使用原账号登录返回 401。 - [ ] AC6DELETING 状态的账户在 30 天后不再存在于业务表中。 - [ ] AC7审计表中保留脱敏记录 180 天。5.4 执行过程中的两个关键时刻第一个时刻是规格评审时我们发现 AC4 的定义有歧义——未完结订单都没有明确什么状态算未完结。后来补充了定义订单状态为 PAID、SHIPPING、REFUNDING 三种都算未完结。这个如果不提前定义清楚AI 大概率会自作主张。第二个时刻是任务拆解时AI 把物理数据清理和审计记录保留拆成了两个独立任务但没考虑数据库事务边界。我在 review 时追加了一个任务清理和审计记录写入必须在同一个事务里要么都成功要么都失败。这种细节在需求层面根本不会有人提但规格拆解到任务层的时候就会暴露出来。6. 常见问题与排查技巧实录6.1 OpenSpec CLI 找不到命令装了却提示 command not found多半是 PATH 没配好。用 Homebrew 安装后需要检查/opt/homebrew/bin是否在 PATH 里。另外注意 OpenSpec 需要 Node.js 运行时版本过低也可能导致启动失败。which node node --version # 建议 v18 及以上6.2 Superpowers Skills 不生效最常见的坑是目录层级放错了。我遇到过.claude/skills/superpowers/skills/xxx这种多套了一层的情况导致 AI 识别不到。检查你的技能目录正确的层级应该是.claude/skills/superpowers/skills/brainstorming/也就是superpowers下面直接是各个 skill 名字。6.3 AI 在实现时偏离了规格这是 SDD 落地最头疼的问题。我的排查顺序是先确认 AI 是否真正读取了规格文件。可以问它这份提案的验收标准是什么回答不出来就是没读。如果读取了还是偏检查CLAUDE.md/AGENTS.md里是否明确声明了规格是唯一事实来源。AI 默认会优先遵循系统提示和用户即时对话如果你没有写这句话它很容易被对话里的偶发信息带跑。如果还是偏建议重置会话再试。AI 的上下文窗口有限聊得越久越容易遗忘规格细节。6.4 任务拆解太粗或太细任务拆得太粗一个任务包含多个功能点review 时很难把关拆得太细又会让流程变得繁琐。我的经验是以一次 commit 能完成、且可以独立验证为粒度。比如实现注销接口可以算一个任务但实现注销接口 写接口测试 更新前端页面就该拆成三个。6.5 常见问题速查表现象可能原因排查与解决方案openspec 命令不存在PATH 未配置或安装失败重新安装检查 /opt/homebrew/binAI 不按规格执行上下文缺少规格指引在 AGENTS.md 里声明规则重置会话skills 列表为空目录层级错误或路径不对检查 .claude/skills/ 下目录结构验收标准写得太虚第一次生成时没有分阶段提示让 AI 单独针对 spec 重新生成 AC规格和代码不同步修改代码时没有同步更新规格建立改码必改规格的团队规则另一个独家技巧把规格文件的路径直接引用在任务描述里比如请阅读 openspec/proposals/user-account-deletion/spec.md 后开始实现。这比让 AI 自己翻目录找到规格要可靠得多减少一步就有少一步的出错概率。6.6 关于什么时候需要规格什么时候不需要的取舍不是每一个任务都要走完整的 SDD 流程。一个只有三行改动的 bug 修复你让它先写提案再写规格反而浪费时间。我在实践中形成的判断标准是需要新建文件、涉及多个模块、影响数据结构的 → 必须走完整流程。简单的文案调整、单行逻辑修复 → 不需要提案直接修复。介于两者之间的 → 至少写一个简单的 proposal哪怕只有 spec 和验收标准两个文件。流程是工具不是目的。过度流程化会让团队产生抵触心理适度取舍才能长期坚持。7. 一点个人心得SDD 的真正门槛不是工具是纪律整套 OpenSpec Superpowers 组合用下来我最大的感触是工具解决的是能不能的问题但真正决定 SDD 成败的是愿不愿意坚持流程。如果你没有养成先审规格再看代码的习惯再好的工具也拦不住你为了快点上线而跳步。我个人的体会是导入这套流程的前两个星期是最痛苦的尤其当你一个人开发时会怀疑写规格的时间都快够我写完功能了。但坚持过第一个月后返工率下降得非常明显。最直观的改动是以前我每周都要花一两个晚上处理 AI 留下的烂摊子现在这种情况几乎没有了。你花在规格上的时间会在代码审查、测试调试、上线运维三个环节加倍拿回来。最后分享一个小技巧把规格文档当作你和 AI 之间的共同语言。你在 AI 面前不用再费力气解释前因后果只要说阅读 openspec/proposals/xxx按验收标准实现。这一句话抵得上过去和 AI 来回扯皮十句话。如果你正被 AI 写代码的失控感困扰不妨挑一个小功能按本文的 SOP 完整跑一遍我相信你会回来感谢这个决定的。 
长河君 · 2026/9/15 0:42:05 · 阅读 1.2k AI写代码不靠谱？用OpenSpec+Superpowers落地SDD开发流程
你有没有发现AI 写代码越来越像那么回事了但一上生产就各种翻车需求理解偏了、改 A 坏 B、代码风格混乱、测试补得乱七八糟——更气人的是你问它为什么这么写它还能振振有词地给你编一个理由。我自己从去年开始重度使用 AI 编码助手从 Cursor 到 Claude Code 再到 Codex CLI中间踩过的坑能写一本书。后来真正让我从AI 帮我写代码升级到AI 按规格写代码的是一套组合OpenSpec Superpowers也就是这几年越来越热的SDDSpec-Driven Development规格驱动开发。这篇文章不聊虚的直接把我从零落地这套流程的完整思路、安装步骤、可复制的 SOP 以及踩过的坑全部拆给你。先给结论SDD 的核心不是让 AI 少写代码而是让 AI 在动手前先把要做什么、怎么做、怎么验收想清楚、写下来再由人来审批这个计划书。OpenSpec 负责把规格文档变成可管理的工程资产Superpowers 则负责给 AI 装上先思考后行动的工作流。这套东西适合谁适合所有用 AI 写代码但总觉得失控的开发者尤其是团队协作场景里需要约束 AI 输出质量的工程负责人。哪怕你是个人开发者一个人维护多个项目这套流程也能让你少当很多次救火队员。1. 先弄清楚我们到底在解决什么问题1.1 AI 写代码失控的三个典型现场我在不同项目里反复遇到过同样的三类问题如果你也用过 AI 写代码估计能对号入座。第一类是需求漂移。你跟 AI 说帮我加一个用户注销功能它上下文里可能带着之前聊过的某个无关需求结果把注销做成了软删除匿名化通知管理员的全套方案。功能是完整但不是你要的改起来还特别费劲。第二类是上下文断裂。一个文件超过一定长度或者项目文件一多AI 就开始失忆。它可能重写了一个已经废弃的工具函数也可能在一个不应该出现的地方引入了新的依赖。最离谱的一次AI 在一个纯前端的项目里给我 import 了一个 Node.js 内置模块编译直接挂。第三类是验收缺失。让 AI 写完代码它自己说完成但根本没有对照原始需求做验证。测试是写了但测的是它自己理解的功能而不是你描述的需求。等 code review 的时候才发现一堆逻辑从一开始就错了方向返工成本极高。这三类问题的根子其实是一个AI 的默认行为是直接生成答案而不是先理解问题。而我们的常规开发流程恰恰需要后者。SDD 就是把这个先理解问题的过程强制放到流程里。1.2 从 TDD 到 SDD规格为何要先于代码很多人听说过 TDD测试驱动开发先写测试再写实现让测试用例成为需求的可执行表达。SDD 可以理解为 TDD 的上一级抽象——它先要求你把**行为规格Specification**写清楚再基于规格拆任务、写测试、写代码。为什么更偏好规格先行因为测试本质上也是一种代码它依然存在理解偏差的问题。你让 AI 根据需求文档写测试AI 可能写出和需求不一致的测试。规格则更接近自然语言和结构化描述是人可以直接审核的。而且规格是和实现无关的换技术栈、重构代码规格都不需要动但测试和代码都要跟着变。再直白一点TDD 解决的是代码对不对SDD 解决的是代码该不该这么写。先把该不该定了对不对才有意义。OpenSpec 和 Superpowers 的组合恰好把这两层都覆盖了。2. 组合拳拆解OpenSpec 负责管文档Superpowers 负责管行为2.1 OpenSpec给规格文档上版本管理OpenSpec 是一个开源工具核心目标就是把规格变成像代码一样可管理、可评审、可追溯的工程资产。它提供了一套 CLI 命令让你在项目里初始化一个openspec/目录里面按照约定组织所有的规格文档。它的工作模型是以Change Proposal变更提案为中心。每当你有一个新需求就创建一个提案提案里包含关于这个变更的完整描述背景、目标、具体规格、任务清单、验收标准。这样每次变更都是独立的、可审查的不会出现需求散落在聊天记录里的情况。从项目结构上看OpenSpec 初始化后会生成类似这样的目录openspec/ ├── project.md # 项目整体说明 ├── specs/ # 已批准并实施的规格 └── proposals/ # 待评审或正在实施的提案 └── user-account-deletion/ ├── proposal.json # 提案元数据状态、负责人、日期等 ├── spec.md # 规格描述做什么、怎么做、边界 ├── tasks.md # 任务拆解 └── acceptance-criteria.md # 验收标准这个目录结构本身就是一种约束AI 必须按照模板产出内容而不是自由发挥。同时因为所有内容都是文本文件天然支持 Git 评审、Diff 对比、版本回滚。你可以在 PR 里 review 规格就像 review 代码一样。2.2 Superpowers压制 AI 的答题冲动Superpowers 是一套 Skills 集合出自开源社区主要用在 Claude Code、Codex CLI 这类 AI 编码代理上。它的核心理念非常朴素让 AI 在写代码之前先完成一系列思维动作——头脑风暴、制定计划、写任务清单、排序执行。说白了就是给 AI 装了一个先思考后动手的工作流。它的实际形态是一组 skill 目录包含brainstorming/、writing-plans/、implementing-plans/、debugging/、test-driven-development/等。AI 在项目里初始化这些 skills 后会按照 skill 里的提示词逐步执行。比如它接收一个新需求会先调用 brainstorming 相关 skill 向你提一堆澄清问题而不是直接开写。这对解决我前面说的三类问题非常有效需求漂移被前置澄清挡掉上下文断裂被结构化的计划书补上验收缺失被测试必须先行的规则堵死。Superpowers 不是某个具体的插件而是一套行为规范包你可以在不同 AI 工具里复用它。2.3 两者的边界在哪里怎么配合简单说OpenSpec 管写什么Superpowers 管怎么写。OpenSpec 是纯文档层的工具它不关心你用哪个 AI、哪个编辑器只负责把规格文档组织好。Superpowers 是 AI 行为层的工具它管的是 AI 在执行任务时的思考流程和输出顺序。两者配合的方式是Superpowers 把 OpenSpec 生成的规格文档当作输入和权威依据AI 在写代码前先读取规格再按规格拆解任务最后实现时严格对照规格。我这里给出一个简洁的协作模型层级工具解决的问题需求层OpenSpec Proposal需求不明、范围不清规格层OpenSpec spec.md acceptance-criteria.md实现预期不一致、验收无标准任务层Superpowers writing-plansAI 跳过计划直接写代码执行层Superpowers implementing-plans TDD代码偏离规格、测试缺失两者不是竞争关系而是上下游关系。OpenSpec 是合同Superpowers 是按合同施工的流程。没有 SuperpowersOpenSpec 只是普通的文档管理工具没有 OpenSpecSuperpowers 能保证 AI 按计划干活但计划本身的质量没人把关。3. 环境搭建从零装好 OpenSpec 和 Superpowers3.1 初始化 OpenSpec 工作区安装 OpenSpec 最直接的方式是通过 Homebrew 或直接拉取源码编译。我习惯用 Homebrew干净且升级方便# 安装 OpenSpec CLI brew install openspec # 在项目根目录初始化 openspec init # 如果项目里还没有 Git先 git initopenspec init会创建一个openspec/目录同时生成project.md模板。这个文件用来描述项目整体信息AI 在阅读规格前会先读它了解上下文。你在project.md里至少要写清楚项目是干什么的、技术栈是什么、代码结构约定有哪些。提示openspec init也可以用openspec init --force重置已有配置但会覆盖你之前的改动慎用。3.2 安装并挂载 Superpowers SkillsSuperpowers 的安装方式取决于你用的 AI 工具。以目前社区里用得最多的 Claude Code 为例有两种方式。第一种是通过 Claude Code 的插件市场安装# 在 Claude Code 里执行 /plugin marketplace add obra/superpowers-marketplace /plugin install superpowerssuperpowers第二种也是更通用的方式是直接把 skills 克隆到项目的.claude/skills/目录# 在项目根目录执行 git clone https://github.com/obra/superpowers.git .claude/skills/superpowers这样项目里的 Claude Code 会自动识别这些 skills。如果你用的是 Cursor 或 Codex CLI逻辑也是类似的——把 skills 放到对应的配置目录下。以 Codex CLI 为例通常放在~/.codex/skills/或项目.codex/skills/下。3.3 验证环境是否就绪装完最怕的就是看似装好了实际没生效。我每次都会快速做一个冒烟测试。先验证 OpenSpecopenspec --version openspec validateopenspec validate会检查项目里的规格文档是否符合格式要求。如果没有任何输出且退出码为 0说明环境没问题。验证 Superpowers 是否被 AI 正确加载最直接的方式是问 AI 一句话你现在有哪些 skills 可用请列出来。如果它列出了 brainstorming、writing-plans、implementing-plans 等项目说明加载成功。如果它说我没有 skills多半是路径配置不对。这时候检查一下 skills 目录的层级注意不要把superpowers/superpowers/嵌套多了一层。3.4 配置建议给 AI 一个启动开关我建议在项目里加一个CLAUDE.md或者AGENTS.md文件取决于你用哪个 AI 工具写清楚工作规范。比如# 项目协作规范 1. 收到新需求时先读取 openspec/proposals/ 下相关提案理解规格后再动手。 2. 如果没有对应提案必须先创建提案并让用户确认再开始编码。 3. 编写代码时必须严格对照 acceptance-criteria 逐条实现。 4. 任何与规格不符的改动必须先修改规格文档再修改代码。这个文件相当于告诉 AI遇到需求先走流程是保证 SDD 落地的关键一环。没有它AI 还是会回到直接写代码的默认行为。4. 可复制的 SDD 落地 SOP七个步骤下面这套 SOP 是我个人项目中反复验证过的流程每一步我都标了目的和关键输出物。你可以直接抄走再按自己团队的工作习惯微调。4.1 第 0 步需求澄清AI 提问人类回答收到需求后第一件事不是写规格而是让 AI 通过 Superpowers 的 brainstorming skill 向你提问题。你需要回答清楚这个功能解决什么问题不做的代价是什么目标用户是谁有什么使用前提有哪些边界场景比如无权限、网络异常、数据为空等。性能、安全、合规有没有硬性要求需不需要兼容旧的流程和数据这一步的输出物是需求澄清记录可以是一段对话摘要最好直接粘贴进后续的 proposal 里作为背景。4.2 第 1 步创建 Change Proposal在需求理解一致后用 OpenSpec 创建提案openspec new user-account-deletion这会生成一个提案目录和模板文件。你别急着让 AI 写先自己在proposal.json里填好元信息提案名称、负责人、创建日期、状态draft/under-review/approved/implemented。4.3 第 2 步AI 根据澄清内容撰写规格这是整个流程的核心。把需求澄清记录交给 AI让它基于模板撰写spec.md和acceptance-criteria.md。有一个经验不要一次让 AI 写完所有内容而是分两个阶段。第一阶段只写spec.md第二阶段让 AI 对着spec.md写验收标准。这样验收标准才会真正和规格对齐而不是 AI 自己脑补一套。写完之后你作为人类必须通读一遍规格确认如果我是一个完全不了解项目的新人看到这份规格能不能直接实现。4.4 第 3 步人类评审规格锁定范围规格文档写好后走一次评审。评审时关注三个问题范围是否合理有没有过度设计或遗漏关键路径验收标准是否可测每一条都必须是可以明确判定通过/失败的。边界条件是否覆盖至少要考虑输入异常、权限不足、重复提交三种情况。评审通过后把 proposal 的状态改为approved。这一步务必用 Git 打一个 tag 或 commit锚定规格锁定的时间点。之后任何改动都必须先改规格再改代码。4.5 第 4 步AI 基于规格拆解任务并制定计划状态变成 approved 后让 AI 读取tasks.md模板根据spec.md拆解实施任务。这里 Superpowers 的 writing-plans skill 会起作用AI 会生成一个详细的实施计划包括每个任务的技术方案、涉及的文件、依赖关系、风险点。你需要在计划里重点检查两点任务拆解是否足够小每个任务最好控制在一次代码提交的量级。顺序是否合理一般来说先搭骨架再填血肉先做数据层再做接口层最后做 UI。4.6 第 5 步按计划逐项实施严格对照验收标准这一步进入 implementing-plans 和 TDD 流程。每个任务完成后AI 需要把对应的验收标准标为已通过并附上测试证据。这里有个很实用的技巧让 AI 每完成一个任务就暂停等你 review 再继续下一个。虽然 ChatGPT 和 Claude 都支持连续执行但连续执行意味着你失去了中途纠偏的机会。我自己的习惯是写完一个任务就 commit 一次commit message 里带上任务编号方便追溯。4.7 第 6 步整体验收与回归所有任务完成后做一次整体验收。让 AI 基于acceptance-criteria.md逐条跑一遍验证输出规格验收表列出每条标准的验证方法和结果。这一步能有效防止 AI 在实现过程中自以为完成了。如果验收发现问题回到 4.5 步修而不是绕过规格直接改代码。这是整个 SDD 流程纪律性的体现——规格是唯一事实来源。5. 实战记录一个真实功能的落地全程光讲框架不够我拿一个真实例子跑一遍完整流程。假设我们要给项目加一个用户注销账号的功能下面是我实际执行时留下的关键产物。5.1 需求澄清记录节选功能目标允许用户永久注销自己的账号注销后数据进入待删除队列30 天后物理删除。边界注销前必须二次确认如果用户有未完结的订单禁止注销并提示原因。安全要求注销接口需要登录态校验且需要图形验证码防止脚本批量操作。数据要求注销后用户无法登录但保留基本脱敏信息用于合规审计。5.2 规格文件的实际内容简化在openspec/proposals/user-account-deletion/spec.md中写## 概述 提供用户主动注销账号的能力注销后账户进入禁用状态数据进入延迟删除队列。 ## 详细规格 - 用户在「设置 - 账号安全」页面可发起注销申请。 - 发起注销前需通过图形验证码校验。 - 若用户存在未完结订单页面展示拦截提示不允许发起注销。 - 注销申请成功后账户立即标记为 DELETING禁止登录及一切写操作。 - 30 天后后台任务对标记为 DELETING 的账户执行物理数据清理。 - 清理完成后保留脱敏记录 180 天用于审计查询。 ## 边界条件 - 已注销账户的手机号/邮箱可以被重新注册。 - 注销操作不可逆需前端二次确认弹窗。5.3 验收标准节选在acceptance-criteria.md中写- [ ] AC1登录用户在设置页面可见「注销账号」入口。 - [ ] AC2点击注销后弹出二次确认框确认后展示验证码输入框。 - [ ] AC3验证码错误时接口返回 400 以及可读错误信息不产生注销申请。 - [ ] AC4用户存在未完结订单时注销接口返回 409前端展示具体拦截原因。 - [ ] AC5注销成功后用户使用原账号登录返回 401。 - [ ] AC6DELETING 状态的账户在 30 天后不再存在于业务表中。 - [ ] AC7审计表中保留脱敏记录 180 天。5.4 执行过程中的两个关键时刻第一个时刻是规格评审时我们发现 AC4 的定义有歧义——未完结订单都没有明确什么状态算未完结。后来补充了定义订单状态为 PAID、SHIPPING、REFUNDING 三种都算未完结。这个如果不提前定义清楚AI 大概率会自作主张。第二个时刻是任务拆解时AI 把物理数据清理和审计记录保留拆成了两个独立任务但没考虑数据库事务边界。我在 review 时追加了一个任务清理和审计记录写入必须在同一个事务里要么都成功要么都失败。这种细节在需求层面根本不会有人提但规格拆解到任务层的时候就会暴露出来。6. 常见问题与排查技巧实录6.1 OpenSpec CLI 找不到命令装了却提示 command not found多半是 PATH 没配好。用 Homebrew 安装后需要检查/opt/homebrew/bin是否在 PATH 里。另外注意 OpenSpec 需要 Node.js 运行时版本过低也可能导致启动失败。which node node --version # 建议 v18 及以上6.2 Superpowers Skills 不生效最常见的坑是目录层级放错了。我遇到过.claude/skills/superpowers/skills/xxx这种多套了一层的情况导致 AI 识别不到。检查你的技能目录正确的层级应该是.claude/skills/superpowers/skills/brainstorming/也就是superpowers下面直接是各个 skill 名字。6.3 AI 在实现时偏离了规格这是 SDD 落地最头疼的问题。我的排查顺序是先确认 AI 是否真正读取了规格文件。可以问它这份提案的验收标准是什么回答不出来就是没读。如果读取了还是偏检查CLAUDE.md/AGENTS.md里是否明确声明了规格是唯一事实来源。AI 默认会优先遵循系统提示和用户即时对话如果你没有写这句话它很容易被对话里的偶发信息带跑。如果还是偏建议重置会话再试。AI 的上下文窗口有限聊得越久越容易遗忘规格细节。6.4 任务拆解太粗或太细任务拆得太粗一个任务包含多个功能点review 时很难把关拆得太细又会让流程变得繁琐。我的经验是以一次 commit 能完成、且可以独立验证为粒度。比如实现注销接口可以算一个任务但实现注销接口 写接口测试 更新前端页面就该拆成三个。6.5 常见问题速查表现象可能原因排查与解决方案openspec 命令不存在PATH 未配置或安装失败重新安装检查 /opt/homebrew/binAI 不按规格执行上下文缺少规格指引在 AGENTS.md 里声明规则重置会话skills 列表为空目录层级错误或路径不对检查 .claude/skills/ 下目录结构验收标准写得太虚第一次生成时没有分阶段提示让 AI 单独针对 spec 重新生成 AC规格和代码不同步修改代码时没有同步更新规格建立改码必改规格的团队规则另一个独家技巧把规格文件的路径直接引用在任务描述里比如请阅读 openspec/proposals/user-account-deletion/spec.md 后开始实现。这比让 AI 自己翻目录找到规格要可靠得多减少一步就有少一步的出错概率。6.6 关于什么时候需要规格什么时候不需要的取舍不是每一个任务都要走完整的 SDD 流程。一个只有三行改动的 bug 修复你让它先写提案再写规格反而浪费时间。我在实践中形成的判断标准是需要新建文件、涉及多个模块、影响数据结构的 → 必须走完整流程。简单的文案调整、单行逻辑修复 → 不需要提案直接修复。介于两者之间的 → 至少写一个简单的 proposal哪怕只有 spec 和验收标准两个文件。流程是工具不是目的。过度流程化会让团队产生抵触心理适度取舍才能长期坚持。7. 一点个人心得SDD 的真正门槛不是工具是纪律整套 OpenSpec Superpowers 组合用下来我最大的感触是工具解决的是能不能的问题但真正决定 SDD 成败的是愿不愿意坚持流程。如果你没有养成先审规格再看代码的习惯再好的工具也拦不住你为了快点上线而跳步。我个人的体会是导入这套流程的前两个星期是最痛苦的尤其当你一个人开发时会怀疑写规格的时间都快够我写完功能了。但坚持过第一个月后返工率下降得非常明显。最直观的改动是以前我每周都要花一两个晚上处理 AI 留下的烂摊子现在这种情况几乎没有了。你花在规格上的时间会在代码审查、测试调试、上线运维三个环节加倍拿回来。最后分享一个小技巧把规格文档当作你和 AI 之间的共同语言。你在 AI 面前不用再费力气解释前因后果只要说阅读 openspec/proposals/xxx按验收标准实现。这一句话抵得上过去和 AI 来回扯皮十句话。如果你正被 AI 写代码的失控感困扰不妨挑一个小功能按本文的 SOP 完整跑一遍我相信你会回来感谢这个决定的。