别再让 AI 瞎写了OpenSpec Superpowers 落地 SDD 规格驱动开发附可复制 SOP这段时间 AI 编程工具越来越猛Claude Code、Cursor 这些 Agent 类工具写代码的速度确实快但等代码量堆起来问题就来了AI 写的代码经常跑着跑着就变味儿了。要么是需求理解偏了写了一堆用不上的功能要么是这个文件改一下、那个接口动一下前后的设计对不上更头疼的是你问它某个模块当初为什么这么写它自己也说不清楚。这不是模型能力不行而是工作方式出了问题。天天让 AI 直接从零开写它没有上下文、没有边界、没有验收标准全靠“猜”跟“编”那结果自然就是“瞎写”。今天要聊的这套组合拳我自己在几个中大型项目里实打实跑了一段时间效果非常直观OpenSpec 负责让 AI 读懂需求Superpowers 负责规范 AI 的执行动作两者一配合SDDSpec-Driven Development规格驱动开发就能真正落地。这篇会把整套思路、具体配置、操作流程全部拆开最后给一份可以直接复制去用的 SOP。无论你是独立开发者、小团队技术负责人还是刚刚接触 AI 编程的爱好者只要受够了 AI 无限返工、代码失控这篇内容值得从头到尾看一遍。尤其后面附的 SOP是我踩过不少坑之后整理出来的收藏起来下次开新项目直接照着搬。1. 先搞明白为什么 AI 写代码失控根子在哪很多人的第一反应是“AI 不够聪明”。但说实话Claude 4、GPT-4o、DeepSeek 这些模型的编码能力已经很强了单看函数级代码生成很多时候比初级工程师写得更规范。问题根本不在“写代码”这个动作而在于写代码之前的所有环节都没人管。1.1 直接裸写代码的三大失控场景场景一需求边界模糊。你告诉 AI“写一个用户登录功能”它默认就给你做手机号密码验证码第三方登录记住我忘记密码中间再夹一个 token 刷新。但实际上你只需要一个简单的邮箱验证码登录。多出来的部分不只是浪费时间还会引入大量不必要的依赖和潜在安全风险。场景二上下文失忆。一个文件里没写完的逻辑换到另一个文件里它可能就“忘了”前面定好的数据格式。你手动改完了这个接口的返回值下一次让它改相邻功能时它又按旧格式生成了一遍改完这个漏那个。场景三改动无痕。人类程序员改代码会同步更新文档、注释、测试用例AI 不会。除非你每轮都明确要求否则它只会专注在你指定的那几行代码上改了 A 模块的接口却不知道 B 模块的调用逻辑已经坏了。这三个场景的共同点是什么缺少一个“规格层”。没人提前告诉 AI你要做的是什么、边界在哪里、验收标准是什么、哪些东西不能动。代码只是需求的最终投影需求本身一团乱麻代码自然不可能工整。1.2 SDD 规格驱动开发的核心思路所谓 SDDSpec-Driven Development换个直白的说法就是先把“做什么、不做什么、做成什么样算好”这三件事固定下来再让 AI 动手写代码。这跟传统开发里的“设计文档先行”有些相似但又不完全一样。传统方式里需求文档是给人看的写得再长也能靠人脑去理解上下文而 SDD 里的规格主要是给 AI 看的。它要求文档结构足够明确、内容足够原子化让 AI 能精确定位某条规则、某个约束、某份验收标准并且能跨会话地追踪这些内容。规格驱动开发的顺序大致是这样用自然语言或结构化模版定义需求验证需求描述的一致性、完整性和可测性基于规格生成任务清单逐步、可验证地实现每一步都对照规格回归校验实现结果与规格是否一一对应。正常情况下可想得挺好但手动去写这么一套流程麻烦程度不亚于自己多写一遍代码。所以就需要工具来把流程固化下来。这就是 OpenSpec 和 Superpowers 要干的事。2. 工具认知OpenSpec 和 Superpowers 到底各管哪一块这两个工具名字听起来都挺“超级英雄”但定位截然不同。理解它们的分工是后面所有操作的前提。2.1 OpenSpec把需求变成 AI 能读懂的“蓝图”OpenSpec 本质上是一个面向 AI 的规格管理框架。它定义了一组目录规范、文件格式和校验规则让需求描述可以像代码一样被结构化组织、版本化管理和自动化校验。我第一次接触 OpenSpec 的时候下意识想到的是以前用过的 Swagger/OpenAPI。确实OpenSpec 借鉴了类似于 OpenAPI 的思维方式——用一套标准化的格式去描述“系统应该有什么行为”这样工具和 AI 才能准确理解。但它不是只描述接口而是覆盖了功能需求、数据模型、变更影响、验收测试等多个维度。一个典型的 OpenSpec 项目目录长这样结构非常清晰openspec/ ├── project.md # 项目整体说明全局上下文 ├── specs/ │ ├── auth/ │ │ ├── login.md # 登录功能规格 │ │ └── register.md # 注册功能规格 │ ├── billing/ │ │ └── checkout.md # 结算功能规格 │ └── ... ├── changes/ │ ├── 2025-06-01_add-login.md │ └── ... └── requirements/ └── ...每个 spec 文件都遵循固定的前页frontmatter和内容模版。这样做的最大好处是AI 扫描一遍 openspec 目录就能对项目全局建立共识。你不需要把几千字的背景塞到对话里只要让它读这个目录即可。2.2 Superpowers给 AI 装上“项目管理方法论”Superpowers 这个名字听起来有点中二但实际作用非常实际它是一套基于规则的 AI 工作流增强工具本质上是给 Claude Code 这类 Agent 增加了一整套结构化的行为约束和流程引导。简单说OpenSpec 管的是“需求文件长什么样”Superpowers 管的是“AI 的工作过程怎么走”。它通过一套精心设计的规则文件让 AI 遵守类似 Scrum 的节奏先规划再拆任务逐步实现每步都验证出了问题先回溯再修。具体到实现层面Superpowers 会要求 AI 在开工之前先创建一份工作计划拆分成小步骤每一步完成之后AI 必须停下来报告进展并提供验证方法而不是一股脑把代码全生成完。而且 Superpowers 不只针对编码场景它还能管理 AI 的工具调用行为。例如该读哪些文件、不该乱创建文件、测试失败之后不能直接反复试错而是要回退分析。相当于给 AI 装上了一个“项目经理脑子”。2.3 两者叠加的效果让 AI 从“打字员”变成“工程师”有朋友问只用 OpenSpec 行不行说实话行但效果会打折扣。因为 OpenSpec 解决的是“需求管理”它本身并不强制 AI 按流程执行。假如你只导入 OpenSpec 的规格文件然后直接说“按照这些规格完成功能”AI 很可能会一次性把所有代码写完——又快又全但遇到中途想调整需求你又要重新解释、重新改。反过来只装 Superpowers 也不行。Superpowers 能管 AI 的干活节奏但 AI 干活时的“依据”是什么如果缺少规格文件它还是会靠猜只是猜得更谨慎了而已。两个工具叠加相当于给 AI 编程流程同时加了内容保障和过程保障维度没有工具只用 OpenSpecOpenSpec Superpowers需求是否有统一格式否是是AI 是否先计划再动手否不一定强制变更是否能追踪困难较好好交付质量是否可验证靠人肉检查部分验证每步验证这就是为什么我强烈建议两个一起用。它们不是竞争关系而是天然的互补搭档。3. 环境准备从零装好 OpenSpec 和 Superpowers工欲善其事必先利其器。这套方案本身的安装并不复杂但在实际落地之前有几个关键决策点值得单独拿出来讲讲。3.1 前置工具Claude Code 是首选运行环境目前这套组合最成熟的运行环境是Claude Code。我试过在 Cursor 里手动配置类似流程也能跑但有两点差距比较明显OpenSpec 和 Superpowers 对 Claude Code 的命令行接口做了适配可以直接通过指令触发完整流程Claude Code 对长上下文的理解和遵循长指令的能力更强而 Superpowers 的规则文件本身就是一个很长的系统提示如果模型遵循能力不够强规则很容易被忽略。所以我的建议是没有特殊理由的话直接装 Claude Code。安装方式非常简单在终端执行npm install -g anthropic-ai/claude-code装完在项目目录里运行claude就能启动交互界面。关于这个部分GitHub 上是这套组合的常见搭配相关讨论也比较多像“claude code openspec superpowers 三件套”就是社区里一个很热的话题组合大家可以直接参考。提示如果你用的是其他 Agent 工具也没关系后面提到的 SOP 思路照样可以参考只是命令和触发方式需要自己手动适配。3.2 OpenSpec 安装与项目初始化OpenSpec 目前提供了 CLI 工具安装和初始化流程很顺直接照着执行就行# 全局安装 npm install -g openspec/cli # 在项目目录中初始化 cd your-project openspec init初始化之后OpenSpec 会在项目中自动生成 openspec 目录及对应的模版文件。这里有一个小细节需要注意如果你想让 AI比如 Claude Code在每轮对话中都默认遵守 OpenSpec 的规矩最好把 OpenSpec 的加载指令写进项目的 CLAUDE.md 文件里例如## 工作约定 - 在修改任何代码之前必须检查 openspec/ 目录下的规格文件确保当前实现符合规格要求。 - 新增功能必须先在 openspec/changes/ 下创建对应的变更提案。 - 规格文件与代码实现不一致时优先修改代码使之一致除非规格本身已经确认变更。这么做的目的很好理解AI 工具的上下文窗口虽然大但如果你每次不主动提醒它去看规格文件它很可能会“选择性忽略”。写进 CLAUDE.md 里相当于默认规则每次对话都会自动加载省心得多。3.3 Superpowers 安装与规则生效机制Superpowers 的安装方式同样很直接它是一个基于 Claude Code 的 Skill 规则包。官方推荐的做法是把规则文件克隆到 Claude Code 的配置目录下确保每次启动时自动加载# 克隆规则库 git clone https://github.com/your-repo/superpowers.git # 复制到 Claude Code 配置目录 cp -r superpowers/skills ~/.claude/skills/ cp -r superpowers/commands ~/.claude/commands/装完之后你可以在 Claude Code 中使用一些特殊命令来唤起对应的工作流。最常用的是/superpowers:init这个命令会引导 AI 为当前项目建立一套工作计划流程。初次运行时会检查项目背景、技术栈、现有代码结构然后生成一份项目级的执行规则。后续每次写代码之前AI 都会被这些规则约束先出规划再动手。我在实操里的额外一步是把 OpenSpec 的规格文件名、关键路径也写进 Superpowers 的项目规则里这样两个工具之间就形成了一个闭环——Superpowers 管流程流程引用 OpenSpec 的规格内容规格内容约束代码行为。4. 完整落地 SOP六步实践指南照着抄就行前面讲了原理和安装这部分是重点中的重点。我把实际项目中验证过没问题的整套 SOP 流程整理成六步每一步的命令、操作要点、验证方法都写到可以直接照做的程度。4.1 第一步写清目标防止 AI 自嗨式发散很多人启动一个 AI 项目时第一句话是“帮我做一个待办事项应用”。这句话信息量太小了。给人类同事说这句话对方可以追问你给 AI 说这句话它就大概率按自己想象的“标准待办应用”去做了。所以第一步不是直接让 AI 写代码而是先写项目目标。目标是整个规格体系的最小单元必须包含要解决什么问题、面向什么用户、核心使用场景、非目标明确不做什么。例如# 项目极简番茄钟 - 目标帮助自由职业者通过番茄工作法提升单任务专注时长。 - 用户画像30-45 岁的远程办公者不喜欢复杂操作。 - 核心场景用户点击开始25 分钟后提醒休息可手动暂停/继续。 - 非目标不做任务列表、不做数据统计、不集成第三方登录。搭建 OpenSpec 可以先从 project.md 写起把上面的信息放进去。你现在可能觉得有点啰嗦但后面 AI 不跑偏时就知道这份啰嗦有多值钱了。4.2 第二步功能拆解让每个规格原子化第二步是在 openspec/specs/ 下为每个核心功能建立独立的规格文件。这里有一个非常关键的原则一个文件只讲一件事。文件越小、边界越清晰AI 越容易准确引用和修改。以番茄钟为例可以拆成两个规格文件timer.md专注计时器的启动、暂停、重置行为notification.md提醒通知的触发条件和展示方式。每个规格文件内部建议遵循这样的结构--- name: 专注计时器 status: approved --- ## 功能概述 提供 25 分钟专注倒计时支持暂停/继续/重置。 ## 详细行为 - 启动点击“开始”后倒计时从 25:00 开始。 - 暂停点击“暂停”后倒计时冻结按钮变为“继续”。 - 重置点击“重置”后倒计时恢复为 25:00状态变为空闲。 - 结束倒计时归零时触发结束状态播放提示音。 ## 验收标准 - [x] 倒计时误差不超过 1 秒。 - [ ] 暂停后时间不会继续减少。 - [ ] 重置之后状态恢复初始。 - [ ] 归零时有通知触发。注意验收标准里不用全部打钩。你可以先把期望写出来后面的实现过程中AI 每完成一项会更新一项。打钩这个动作本身就是一种进度追踪。4.3 第三步变更提案先行建立需求追踪的“审计线索”这一步是最容易被忽略、但价值最大的。OpenSpec 的工程化思想体现在 changes 目录里任何功能开发先以变更提案Change Proposal的形式建立记录。为什么要加这一步因为没有变更记录的话你和一个 AI 对话几小时后你根本想不起哪一轮会话里做了哪些决定。当下一次开启新会话AI 又“失忆”了。变更提案文件本质上是一份“跨会话的审计线索”让 AI 不管多少次重新启动都能通过读取 changes 目录恢复上下文。实际操作中我会先手动创建变更提案文件--- id: 2025-06-12-timer-function status: proposed --- ## 变更内容 实现番茄钟核心计时逻辑。 ## 影响模块 - src/components/Timer.vue - src/hooks/useTimer.ts ## 规格引用 - openspec/specs/timer.md ## 完成定义DoD - [ ] 计时功能通过全部验收标准 - [ ] 相关测试用例通过 - [ ] 变更说明已更新创建完文件之后再让 AI 基于这份变更提案去实现。每一步的修改都对应到一个提案这样的话将来想回滚某个功能直接按提案回溯即可。4.4 第四步让 Superpowers 把任务拆成可验证的小步规格和变更都准备好了接下来就是让 AI 动手。这一步里Superpowers 的作用就显现出来了。当你输入类似这样的指令请根据 openspec/changes/2025-06-12-timer-function.md 实现功能。Superpowers 规则会把这句话转化成一套标准工作流。AI 不会直接扔给你一坨代码而是先给出工作计划例如执行计划 1. 读取 openspec/specs/timer.md提取验收标准。 2. 检查现有项目结构确认技术栈。 3. 设计 useTimer 的接口签名和状态机。 4. 实现 Timer.vue 组件 UI。 5. 对验收标准逐项自测。 6. 更新变更提案的完成列表。这个计划生成之后AI 会逐项执行并在每步之间暂停让你确认。此时你需要注意如果 AI 在第一步之后就直接跳到了第五步说明 Superpowers 的规则没生效或者模型遵循能力不够需要检查规则文件是否加载成功。正常情况下的节奏应该是一步一确认的这并不拖沓后面你就知道这个“慢”换来了多少返工时间。4.5 第五步每步验证 AI 自动测试减少低级错误很多人的另一个错误做法是把所有代码写完再统一测试。在传统开发模式下这个流程倒也常见但对于 AI 编程的场景这样做风险很大——AI 上下文一旦过长前面的决策很容易被遗忘。在 Superpowers 的工作流里每实现一个小步骤AI 必须停下来运行相关测试或者进行自我校验。具体来说如果有测试框架AI 需要跑通新功能相关的单测如果没有测试框架AI 需要执行一次静态检查或至少调用一次功能入口确认能正常运行校验通过后再进入下一步。这个环节还有一个附加好处AI 在每步验证时能及时发现规格本身的问题。比如规格里写了“倒计时归零后播放提示音”但项目技术栈里没有音频库AI 会在验证时提出这一点而不是硬编码或者直接跳过。这种反馈对规格的完善非常重要。4.6 第六步回归审查验收标准逐项打钩最后一步是我个人最喜欢的一环也是整套流程的临门一脚对照验收标准逐项确认。在这步我会让 AI 打开规格文件逐个检查验收标准请对照 openspec/specs/timer.md 的验收标准逐项检查当前实现状态并更新检查标记。AI 会一项一项地核对把已完成的标准标记为[x]未完成的标记为[ ]同时说明原因。如果某一条验收标准无法满足它必须说明是代码问题还是规格本身不合理。这个时候你就能看到整套流程的威力了它不会遗留“我以为做了但实际上没做”的功能验收标准的打钩记录本身就是项目文档后续任何人或者任何 AI接手项目只要一眼扫过 openspec/specs 目录就能知道项目实际进度。5. 避坑实录我在实际使用中踩过的几个大坑工具虽好但第一次使用时会有一堆意料之外的问题。有些坑我在社区里也看到很多人踩整理出来帮你们省点时间。5.1 坑一规格文件写得太粗AI 还是靠猜一开始我为了省事规格文件写得比较简比如“支持用户登录”这样一句话就是一条规格。结果 AI 实现出来的登录功能跟我想要的完全不是一回事。后来我学乖了每条验收标准都尽量拆到可测试的粒度。不能写成“登录体验良好”要写成“登录失败时错误信息显示在表单下方”。规格粒度越细AI 的发散空间越小实现越可控。这里我给自己定了一条红线如果一条验收标准没法在三分钟内设计出对应的测试用例那就是写得太粗了需要继续拆。5.2 坑二变更记录不及时新对话里 AI 又“失忆”了用 Claude Code 这类工具一个常见场景是开了一个新终端窗口想让 AI 接着上一个会话的进度继续做。但如果你没有把变更提案文件做好新会话里的 AI 完全不知道项目现在进行到什么状态。后来我把“每次结束会话之前必须更新 changes 目录”作为强制纪律才解决这个问题。具体动作是在对话结束时告诉 AI“请把我们本次完成的全部变更更新到 openspec/changes/ 对应文件中并更新验收标准状态。” 这条明确写进了 CLAUDE.md确保每次都会执行。5.3 坑三Superpowers 和已有项目规则冲突如果你之前的项目里已经设置了比较具体的 .claude/commands 或者 CLAUDE.md 规则新装 Superpowers 后可能会出现“双重人格”的情况一会儿听 Superpowers 的一会儿听旧规则的。解决办法很简单把旧规则里跟开发流程相关的内容合并进 Superpowers 的项目规则里把旧文件清理掉。在项目里只保留一份规则源避免冲突。5.4 问题速查表现象可能原因解决办法AI 不按规格写代码规格文件路径未在 CLAUDE.md 中声明在 CLAUDE.md 中增加规格检查指令AI 一次性写完所有代码Superpowers 未生效或规则未加载执行 /superpowers:init确认规则安装新会话里 AI 不知道项目进度changes 目录未及时更新每次会话结束时强制更新变更提案验收标准全部打钩但功能有问题验收标准写得太粗未覆盖细节拆细验收粒度补充边界场景两个工具的命令冲突旧规则文件残存清理旧规则只保留一套流程定义6. 这套组合还能怎么玩除了基本的 SDD 落地我在几个方向上尝试了扩展分享两个比较实用的思路。6.1 把人工 Code Review 变成 AI 规格审查当规格文件和代码混在一个目录后你可以让 AI 以“审查官”的身份来工作——不直接改代码而是只检查代码是否与规格一致。我把这个指令做成了一个自定义命令每次只需要一句话请按照 openspec/specs/ 下所有的规格文件逐一检查 src/ 目录的代码实现输出差异清单只报告不修改。这个检查可以在开发中随时执行也可以在提交之前执行。输出的差异清单我会直接转给代码生成会话做修复。相当于团队里多了一个不知疲倦的 code reviewer而且它的审查依据是统一的规格不是个人口味。6.2 用规格文件自动生成测试用例规格文件里的“验收标准”写清楚了功能的行为边界这些标准天然就是测试用例的雏形。有一次我试了让 AI 只读规格文件来生成 pytest 测试套件不告诉它代码怎么写结果生成的测试覆盖到了很多我本来想手动补的边界场景。这个思路特别适合用来补测试债——先把规范整理好测试生成是水到渠成的事。你甚至可以把“基于 openspec/specs/timer.md 生成测试计划”这一步直接写进开发流程里让每次规格变更都自动伴随测试更新。7. 写在最后的几点感受OpenSpec Superpowers 这套组合看起来只是两套工具的叠加本质上其实是一次工作方式的改造。我以前用 AI 写代码总是抱着“让它先写有问题我再改”的心态结果越改越乱最后气的不是 AI而是自己为什么不把需求想清楚再动手。现在我的习惯变了先用 OpenSpec 把规格写明白再用 Superpowers 让 AI 按工程化节奏执行。虽然前期会多花一点时间写规格但这部分成本在后期的返工率、上下文记忆和交接效率上全部省了回来性价比极高。几个我实际使用中的小心得分享一下规格文件尽量用中文写。因为团队内部交流天然是中文用中文书写减少二次翻译造成的信息损耗AI 理解起来也很准确两者成本几乎没差别。不要贪多求全一个规格文件控制在 200 行以内。超过 200 行就该考虑拆分子功能否则 AI 引用时也会出现上下文截断。每完成一个里程碑把 openspec 目录整体做一次 git commit并附上“Spec Update”这类标记。将来回溯版本时你可以清楚地看到需求演进路径并且可以随时和实现代码一起回滚。这套流程可能不是最好的但它是目前在 AI 编程浪潮下我试用过多种方案后最可靠、最接近“可复制工程化”的一套。真心建议大家先在个人小项目上跑一遍用不了一下午就能感受到差别。
OpenSpec + Superpowers：落地SDD规格驱动开发的完整SOP
别再让 AI 瞎写了OpenSpec Superpowers 落地 SDD 规格驱动开发附可复制 SOP这段时间 AI 编程工具越来越猛Claude Code、Cursor 这些 Agent 类工具写代码的速度确实快但等代码量堆起来问题就来了AI 写的代码经常跑着跑着就变味儿了。要么是需求理解偏了写了一堆用不上的功能要么是这个文件改一下、那个接口动一下前后的设计对不上更头疼的是你问它某个模块当初为什么这么写它自己也说不清楚。这不是模型能力不行而是工作方式出了问题。天天让 AI 直接从零开写它没有上下文、没有边界、没有验收标准全靠“猜”跟“编”那结果自然就是“瞎写”。今天要聊的这套组合拳我自己在几个中大型项目里实打实跑了一段时间效果非常直观OpenSpec 负责让 AI 读懂需求Superpowers 负责规范 AI 的执行动作两者一配合SDDSpec-Driven Development规格驱动开发就能真正落地。这篇会把整套思路、具体配置、操作流程全部拆开最后给一份可以直接复制去用的 SOP。无论你是独立开发者、小团队技术负责人还是刚刚接触 AI 编程的爱好者只要受够了 AI 无限返工、代码失控这篇内容值得从头到尾看一遍。尤其后面附的 SOP是我踩过不少坑之后整理出来的收藏起来下次开新项目直接照着搬。1. 先搞明白为什么 AI 写代码失控根子在哪很多人的第一反应是“AI 不够聪明”。但说实话Claude 4、GPT-4o、DeepSeek 这些模型的编码能力已经很强了单看函数级代码生成很多时候比初级工程师写得更规范。问题根本不在“写代码”这个动作而在于写代码之前的所有环节都没人管。1.1 直接裸写代码的三大失控场景场景一需求边界模糊。你告诉 AI“写一个用户登录功能”它默认就给你做手机号密码验证码第三方登录记住我忘记密码中间再夹一个 token 刷新。但实际上你只需要一个简单的邮箱验证码登录。多出来的部分不只是浪费时间还会引入大量不必要的依赖和潜在安全风险。场景二上下文失忆。一个文件里没写完的逻辑换到另一个文件里它可能就“忘了”前面定好的数据格式。你手动改完了这个接口的返回值下一次让它改相邻功能时它又按旧格式生成了一遍改完这个漏那个。场景三改动无痕。人类程序员改代码会同步更新文档、注释、测试用例AI 不会。除非你每轮都明确要求否则它只会专注在你指定的那几行代码上改了 A 模块的接口却不知道 B 模块的调用逻辑已经坏了。这三个场景的共同点是什么缺少一个“规格层”。没人提前告诉 AI你要做的是什么、边界在哪里、验收标准是什么、哪些东西不能动。代码只是需求的最终投影需求本身一团乱麻代码自然不可能工整。1.2 SDD 规格驱动开发的核心思路所谓 SDDSpec-Driven Development换个直白的说法就是先把“做什么、不做什么、做成什么样算好”这三件事固定下来再让 AI 动手写代码。这跟传统开发里的“设计文档先行”有些相似但又不完全一样。传统方式里需求文档是给人看的写得再长也能靠人脑去理解上下文而 SDD 里的规格主要是给 AI 看的。它要求文档结构足够明确、内容足够原子化让 AI 能精确定位某条规则、某个约束、某份验收标准并且能跨会话地追踪这些内容。规格驱动开发的顺序大致是这样用自然语言或结构化模版定义需求验证需求描述的一致性、完整性和可测性基于规格生成任务清单逐步、可验证地实现每一步都对照规格回归校验实现结果与规格是否一一对应。正常情况下可想得挺好但手动去写这么一套流程麻烦程度不亚于自己多写一遍代码。所以就需要工具来把流程固化下来。这就是 OpenSpec 和 Superpowers 要干的事。2. 工具认知OpenSpec 和 Superpowers 到底各管哪一块这两个工具名字听起来都挺“超级英雄”但定位截然不同。理解它们的分工是后面所有操作的前提。2.1 OpenSpec把需求变成 AI 能读懂的“蓝图”OpenSpec 本质上是一个面向 AI 的规格管理框架。它定义了一组目录规范、文件格式和校验规则让需求描述可以像代码一样被结构化组织、版本化管理和自动化校验。我第一次接触 OpenSpec 的时候下意识想到的是以前用过的 Swagger/OpenAPI。确实OpenSpec 借鉴了类似于 OpenAPI 的思维方式——用一套标准化的格式去描述“系统应该有什么行为”这样工具和 AI 才能准确理解。但它不是只描述接口而是覆盖了功能需求、数据模型、变更影响、验收测试等多个维度。一个典型的 OpenSpec 项目目录长这样结构非常清晰openspec/ ├── project.md # 项目整体说明全局上下文 ├── specs/ │ ├── auth/ │ │ ├── login.md # 登录功能规格 │ │ └── register.md # 注册功能规格 │ ├── billing/ │ │ └── checkout.md # 结算功能规格 │ └── ... ├── changes/ │ ├── 2025-06-01_add-login.md │ └── ... └── requirements/ └── ...每个 spec 文件都遵循固定的前页frontmatter和内容模版。这样做的最大好处是AI 扫描一遍 openspec 目录就能对项目全局建立共识。你不需要把几千字的背景塞到对话里只要让它读这个目录即可。2.2 Superpowers给 AI 装上“项目管理方法论”Superpowers 这个名字听起来有点中二但实际作用非常实际它是一套基于规则的 AI 工作流增强工具本质上是给 Claude Code 这类 Agent 增加了一整套结构化的行为约束和流程引导。简单说OpenSpec 管的是“需求文件长什么样”Superpowers 管的是“AI 的工作过程怎么走”。它通过一套精心设计的规则文件让 AI 遵守类似 Scrum 的节奏先规划再拆任务逐步实现每步都验证出了问题先回溯再修。具体到实现层面Superpowers 会要求 AI 在开工之前先创建一份工作计划拆分成小步骤每一步完成之后AI 必须停下来报告进展并提供验证方法而不是一股脑把代码全生成完。而且 Superpowers 不只针对编码场景它还能管理 AI 的工具调用行为。例如该读哪些文件、不该乱创建文件、测试失败之后不能直接反复试错而是要回退分析。相当于给 AI 装上了一个“项目经理脑子”。2.3 两者叠加的效果让 AI 从“打字员”变成“工程师”有朋友问只用 OpenSpec 行不行说实话行但效果会打折扣。因为 OpenSpec 解决的是“需求管理”它本身并不强制 AI 按流程执行。假如你只导入 OpenSpec 的规格文件然后直接说“按照这些规格完成功能”AI 很可能会一次性把所有代码写完——又快又全但遇到中途想调整需求你又要重新解释、重新改。反过来只装 Superpowers 也不行。Superpowers 能管 AI 的干活节奏但 AI 干活时的“依据”是什么如果缺少规格文件它还是会靠猜只是猜得更谨慎了而已。两个工具叠加相当于给 AI 编程流程同时加了内容保障和过程保障维度没有工具只用 OpenSpecOpenSpec Superpowers需求是否有统一格式否是是AI 是否先计划再动手否不一定强制变更是否能追踪困难较好好交付质量是否可验证靠人肉检查部分验证每步验证这就是为什么我强烈建议两个一起用。它们不是竞争关系而是天然的互补搭档。3. 环境准备从零装好 OpenSpec 和 Superpowers工欲善其事必先利其器。这套方案本身的安装并不复杂但在实际落地之前有几个关键决策点值得单独拿出来讲讲。3.1 前置工具Claude Code 是首选运行环境目前这套组合最成熟的运行环境是Claude Code。我试过在 Cursor 里手动配置类似流程也能跑但有两点差距比较明显OpenSpec 和 Superpowers 对 Claude Code 的命令行接口做了适配可以直接通过指令触发完整流程Claude Code 对长上下文的理解和遵循长指令的能力更强而 Superpowers 的规则文件本身就是一个很长的系统提示如果模型遵循能力不够强规则很容易被忽略。所以我的建议是没有特殊理由的话直接装 Claude Code。安装方式非常简单在终端执行npm install -g anthropic-ai/claude-code装完在项目目录里运行claude就能启动交互界面。关于这个部分GitHub 上是这套组合的常见搭配相关讨论也比较多像“claude code openspec superpowers 三件套”就是社区里一个很热的话题组合大家可以直接参考。提示如果你用的是其他 Agent 工具也没关系后面提到的 SOP 思路照样可以参考只是命令和触发方式需要自己手动适配。3.2 OpenSpec 安装与项目初始化OpenSpec 目前提供了 CLI 工具安装和初始化流程很顺直接照着执行就行# 全局安装 npm install -g openspec/cli # 在项目目录中初始化 cd your-project openspec init初始化之后OpenSpec 会在项目中自动生成 openspec 目录及对应的模版文件。这里有一个小细节需要注意如果你想让 AI比如 Claude Code在每轮对话中都默认遵守 OpenSpec 的规矩最好把 OpenSpec 的加载指令写进项目的 CLAUDE.md 文件里例如## 工作约定 - 在修改任何代码之前必须检查 openspec/ 目录下的规格文件确保当前实现符合规格要求。 - 新增功能必须先在 openspec/changes/ 下创建对应的变更提案。 - 规格文件与代码实现不一致时优先修改代码使之一致除非规格本身已经确认变更。这么做的目的很好理解AI 工具的上下文窗口虽然大但如果你每次不主动提醒它去看规格文件它很可能会“选择性忽略”。写进 CLAUDE.md 里相当于默认规则每次对话都会自动加载省心得多。3.3 Superpowers 安装与规则生效机制Superpowers 的安装方式同样很直接它是一个基于 Claude Code 的 Skill 规则包。官方推荐的做法是把规则文件克隆到 Claude Code 的配置目录下确保每次启动时自动加载# 克隆规则库 git clone https://github.com/your-repo/superpowers.git # 复制到 Claude Code 配置目录 cp -r superpowers/skills ~/.claude/skills/ cp -r superpowers/commands ~/.claude/commands/装完之后你可以在 Claude Code 中使用一些特殊命令来唤起对应的工作流。最常用的是/superpowers:init这个命令会引导 AI 为当前项目建立一套工作计划流程。初次运行时会检查项目背景、技术栈、现有代码结构然后生成一份项目级的执行规则。后续每次写代码之前AI 都会被这些规则约束先出规划再动手。我在实操里的额外一步是把 OpenSpec 的规格文件名、关键路径也写进 Superpowers 的项目规则里这样两个工具之间就形成了一个闭环——Superpowers 管流程流程引用 OpenSpec 的规格内容规格内容约束代码行为。4. 完整落地 SOP六步实践指南照着抄就行前面讲了原理和安装这部分是重点中的重点。我把实际项目中验证过没问题的整套 SOP 流程整理成六步每一步的命令、操作要点、验证方法都写到可以直接照做的程度。4.1 第一步写清目标防止 AI 自嗨式发散很多人启动一个 AI 项目时第一句话是“帮我做一个待办事项应用”。这句话信息量太小了。给人类同事说这句话对方可以追问你给 AI 说这句话它就大概率按自己想象的“标准待办应用”去做了。所以第一步不是直接让 AI 写代码而是先写项目目标。目标是整个规格体系的最小单元必须包含要解决什么问题、面向什么用户、核心使用场景、非目标明确不做什么。例如# 项目极简番茄钟 - 目标帮助自由职业者通过番茄工作法提升单任务专注时长。 - 用户画像30-45 岁的远程办公者不喜欢复杂操作。 - 核心场景用户点击开始25 分钟后提醒休息可手动暂停/继续。 - 非目标不做任务列表、不做数据统计、不集成第三方登录。搭建 OpenSpec 可以先从 project.md 写起把上面的信息放进去。你现在可能觉得有点啰嗦但后面 AI 不跑偏时就知道这份啰嗦有多值钱了。4.2 第二步功能拆解让每个规格原子化第二步是在 openspec/specs/ 下为每个核心功能建立独立的规格文件。这里有一个非常关键的原则一个文件只讲一件事。文件越小、边界越清晰AI 越容易准确引用和修改。以番茄钟为例可以拆成两个规格文件timer.md专注计时器的启动、暂停、重置行为notification.md提醒通知的触发条件和展示方式。每个规格文件内部建议遵循这样的结构--- name: 专注计时器 status: approved --- ## 功能概述 提供 25 分钟专注倒计时支持暂停/继续/重置。 ## 详细行为 - 启动点击“开始”后倒计时从 25:00 开始。 - 暂停点击“暂停”后倒计时冻结按钮变为“继续”。 - 重置点击“重置”后倒计时恢复为 25:00状态变为空闲。 - 结束倒计时归零时触发结束状态播放提示音。 ## 验收标准 - [x] 倒计时误差不超过 1 秒。 - [ ] 暂停后时间不会继续减少。 - [ ] 重置之后状态恢复初始。 - [ ] 归零时有通知触发。注意验收标准里不用全部打钩。你可以先把期望写出来后面的实现过程中AI 每完成一项会更新一项。打钩这个动作本身就是一种进度追踪。4.3 第三步变更提案先行建立需求追踪的“审计线索”这一步是最容易被忽略、但价值最大的。OpenSpec 的工程化思想体现在 changes 目录里任何功能开发先以变更提案Change Proposal的形式建立记录。为什么要加这一步因为没有变更记录的话你和一个 AI 对话几小时后你根本想不起哪一轮会话里做了哪些决定。当下一次开启新会话AI 又“失忆”了。变更提案文件本质上是一份“跨会话的审计线索”让 AI 不管多少次重新启动都能通过读取 changes 目录恢复上下文。实际操作中我会先手动创建变更提案文件--- id: 2025-06-12-timer-function status: proposed --- ## 变更内容 实现番茄钟核心计时逻辑。 ## 影响模块 - src/components/Timer.vue - src/hooks/useTimer.ts ## 规格引用 - openspec/specs/timer.md ## 完成定义DoD - [ ] 计时功能通过全部验收标准 - [ ] 相关测试用例通过 - [ ] 变更说明已更新创建完文件之后再让 AI 基于这份变更提案去实现。每一步的修改都对应到一个提案这样的话将来想回滚某个功能直接按提案回溯即可。4.4 第四步让 Superpowers 把任务拆成可验证的小步规格和变更都准备好了接下来就是让 AI 动手。这一步里Superpowers 的作用就显现出来了。当你输入类似这样的指令请根据 openspec/changes/2025-06-12-timer-function.md 实现功能。Superpowers 规则会把这句话转化成一套标准工作流。AI 不会直接扔给你一坨代码而是先给出工作计划例如执行计划 1. 读取 openspec/specs/timer.md提取验收标准。 2. 检查现有项目结构确认技术栈。 3. 设计 useTimer 的接口签名和状态机。 4. 实现 Timer.vue 组件 UI。 5. 对验收标准逐项自测。 6. 更新变更提案的完成列表。这个计划生成之后AI 会逐项执行并在每步之间暂停让你确认。此时你需要注意如果 AI 在第一步之后就直接跳到了第五步说明 Superpowers 的规则没生效或者模型遵循能力不够需要检查规则文件是否加载成功。正常情况下的节奏应该是一步一确认的这并不拖沓后面你就知道这个“慢”换来了多少返工时间。4.5 第五步每步验证 AI 自动测试减少低级错误很多人的另一个错误做法是把所有代码写完再统一测试。在传统开发模式下这个流程倒也常见但对于 AI 编程的场景这样做风险很大——AI 上下文一旦过长前面的决策很容易被遗忘。在 Superpowers 的工作流里每实现一个小步骤AI 必须停下来运行相关测试或者进行自我校验。具体来说如果有测试框架AI 需要跑通新功能相关的单测如果没有测试框架AI 需要执行一次静态检查或至少调用一次功能入口确认能正常运行校验通过后再进入下一步。这个环节还有一个附加好处AI 在每步验证时能及时发现规格本身的问题。比如规格里写了“倒计时归零后播放提示音”但项目技术栈里没有音频库AI 会在验证时提出这一点而不是硬编码或者直接跳过。这种反馈对规格的完善非常重要。4.6 第六步回归审查验收标准逐项打钩最后一步是我个人最喜欢的一环也是整套流程的临门一脚对照验收标准逐项确认。在这步我会让 AI 打开规格文件逐个检查验收标准请对照 openspec/specs/timer.md 的验收标准逐项检查当前实现状态并更新检查标记。AI 会一项一项地核对把已完成的标准标记为[x]未完成的标记为[ ]同时说明原因。如果某一条验收标准无法满足它必须说明是代码问题还是规格本身不合理。这个时候你就能看到整套流程的威力了它不会遗留“我以为做了但实际上没做”的功能验收标准的打钩记录本身就是项目文档后续任何人或者任何 AI接手项目只要一眼扫过 openspec/specs 目录就能知道项目实际进度。5. 避坑实录我在实际使用中踩过的几个大坑工具虽好但第一次使用时会有一堆意料之外的问题。有些坑我在社区里也看到很多人踩整理出来帮你们省点时间。5.1 坑一规格文件写得太粗AI 还是靠猜一开始我为了省事规格文件写得比较简比如“支持用户登录”这样一句话就是一条规格。结果 AI 实现出来的登录功能跟我想要的完全不是一回事。后来我学乖了每条验收标准都尽量拆到可测试的粒度。不能写成“登录体验良好”要写成“登录失败时错误信息显示在表单下方”。规格粒度越细AI 的发散空间越小实现越可控。这里我给自己定了一条红线如果一条验收标准没法在三分钟内设计出对应的测试用例那就是写得太粗了需要继续拆。5.2 坑二变更记录不及时新对话里 AI 又“失忆”了用 Claude Code 这类工具一个常见场景是开了一个新终端窗口想让 AI 接着上一个会话的进度继续做。但如果你没有把变更提案文件做好新会话里的 AI 完全不知道项目现在进行到什么状态。后来我把“每次结束会话之前必须更新 changes 目录”作为强制纪律才解决这个问题。具体动作是在对话结束时告诉 AI“请把我们本次完成的全部变更更新到 openspec/changes/ 对应文件中并更新验收标准状态。” 这条明确写进了 CLAUDE.md确保每次都会执行。5.3 坑三Superpowers 和已有项目规则冲突如果你之前的项目里已经设置了比较具体的 .claude/commands 或者 CLAUDE.md 规则新装 Superpowers 后可能会出现“双重人格”的情况一会儿听 Superpowers 的一会儿听旧规则的。解决办法很简单把旧规则里跟开发流程相关的内容合并进 Superpowers 的项目规则里把旧文件清理掉。在项目里只保留一份规则源避免冲突。5.4 问题速查表现象可能原因解决办法AI 不按规格写代码规格文件路径未在 CLAUDE.md 中声明在 CLAUDE.md 中增加规格检查指令AI 一次性写完所有代码Superpowers 未生效或规则未加载执行 /superpowers:init确认规则安装新会话里 AI 不知道项目进度changes 目录未及时更新每次会话结束时强制更新变更提案验收标准全部打钩但功能有问题验收标准写得太粗未覆盖细节拆细验收粒度补充边界场景两个工具的命令冲突旧规则文件残存清理旧规则只保留一套流程定义6. 这套组合还能怎么玩除了基本的 SDD 落地我在几个方向上尝试了扩展分享两个比较实用的思路。6.1 把人工 Code Review 变成 AI 规格审查当规格文件和代码混在一个目录后你可以让 AI 以“审查官”的身份来工作——不直接改代码而是只检查代码是否与规格一致。我把这个指令做成了一个自定义命令每次只需要一句话请按照 openspec/specs/ 下所有的规格文件逐一检查 src/ 目录的代码实现输出差异清单只报告不修改。这个检查可以在开发中随时执行也可以在提交之前执行。输出的差异清单我会直接转给代码生成会话做修复。相当于团队里多了一个不知疲倦的 code reviewer而且它的审查依据是统一的规格不是个人口味。6.2 用规格文件自动生成测试用例规格文件里的“验收标准”写清楚了功能的行为边界这些标准天然就是测试用例的雏形。有一次我试了让 AI 只读规格文件来生成 pytest 测试套件不告诉它代码怎么写结果生成的测试覆盖到了很多我本来想手动补的边界场景。这个思路特别适合用来补测试债——先把规范整理好测试生成是水到渠成的事。你甚至可以把“基于 openspec/specs/timer.md 生成测试计划”这一步直接写进开发流程里让每次规格变更都自动伴随测试更新。7. 写在最后的几点感受OpenSpec Superpowers 这套组合看起来只是两套工具的叠加本质上其实是一次工作方式的改造。我以前用 AI 写代码总是抱着“让它先写有问题我再改”的心态结果越改越乱最后气的不是 AI而是自己为什么不把需求想清楚再动手。现在我的习惯变了先用 OpenSpec 把规格写明白再用 Superpowers 让 AI 按工程化节奏执行。虽然前期会多花一点时间写规格但这部分成本在后期的返工率、上下文记忆和交接效率上全部省了回来性价比极高。几个我实际使用中的小心得分享一下规格文件尽量用中文写。因为团队内部交流天然是中文用中文书写减少二次翻译造成的信息损耗AI 理解起来也很准确两者成本几乎没差别。不要贪多求全一个规格文件控制在 200 行以内。超过 200 行就该考虑拆分子功能否则 AI 引用时也会出现上下文截断。每完成一个里程碑把 openspec 目录整体做一次 git commit并附上“Spec Update”这类标记。将来回溯版本时你可以清楚地看到需求演进路径并且可以随时和实现代码一起回滚。这套流程可能不是最好的但它是目前在 AI 编程浪潮下我试用过多种方案后最可靠、最接近“可复制工程化”的一套。真心建议大家先在个人小项目上跑一遍用不了一下午就能感受到差别。