如果你用 Claude Code 或 Cursor 写过超过 500 行的功能大概率遇到过一种很迷惑的场景AI 写得飞快需求聊两句就开始生成代码看起来每一步都对可等到真正跑起来不是漏了边界条件就是把上一版好不容易稳定的逻辑改坏了。更难受的是你根本说不清它是在哪一步开始偏的。我最近小半年一直在折腾怎么让 AI 编程从“碰运气”变成“可预期”最后沉淀下来的一套打法就是标题里这组组合OpenSpec 负责“规格驱动”Superpowers 负责“执行纪律”。一个管需求契约一个管施工流程两者合在一起基本覆盖了从业务想法到可验证交付的完整链路。这篇文章不聊空概念全部是我在真实项目里跑过的安装步骤、工作流设计和踩坑记录适合正在用 Claude Code、Cursor、opencode或者任何兼容 Claude Skills 机制的 AI 编程工具的人参考。1. 为什么 AI 编程必须走向“规格驱动”先说个结论现在的 Agent 编程能力已经不是瓶颈真正的不稳定因素在于“任务边界”。你让 AI 做一件事它确实会做但“会做”不等于“只做该做的、不做不该做的”。模型本质上是在预测下一个 token它没有长期记忆也没有业务常识。只要上下文稍微长一点或者需求里有几个模糊词它就很容易用“最常见的实现”去填你的“特殊业务逻辑”。这就像你请了一个能力很强但不看任务书的实习生你让他改报表他顺手把数据库字段也改了还觉得自己干得挺全面。1.1 先还原几个失控现场我在项目里反复遇到过这几类问题如果你也在用 AI 编程应该不会陌生。第一类是“需求没写清楚AI 自己脑补”。比如你要“文章列表支持标签筛选”AI 默认标签只是文章表里的一个逗号分隔字符串于是写出来一个只能精确匹配单个标签的接口。等运营真的想用“标签 A 标签 B 组合筛选”时整个查询逻辑都要推翻。第二类是“改动像滚雪球”。你让 AI 顺手改一个按钮的颜色它却因为要“保证类型安全”重构成了组件库还顺手升级了依赖。代码评审时你根本看不出哪些是必要改动哪些是它自作主张。这种问题在小范围任务里不明显一旦 Agent 连续执行十几个工具调用失控概率会指数上升。第三类是“测试变成了安慰剂”。AI 很擅长写测试但它写的测试经常只覆盖自己刚生成的 happy path。你问它“测过了吗”它会说“测过了”实际上边界条件、异常分支、空数据状态全都没碰到。这也是我后来坚持先把验收标准写清楚再让它写业务代码的根本原因。1.2 失控的根因需求到代码之间隔了一个“翻译黑洞”把上面这些现场拆开看会发现共同点不是模型笨而是工作流缺失了一个关键环节规格化。以前手工编程时代需求分析师、产品经理、架构师会一层一层把“业务语言”翻译成“技术语言”。AI 编程时代很多人把这个过程压缩了直接对着聊天窗口说一句话就让 Agent 出代码。中间那层翻译全靠模型临场发挥。一次两次没问题但只要你需要维护、扩展、协作这种“临场发挥”就会变成技术债。规格驱动开发Spec-Driven Development做的就是把这个“翻译黑洞”重新补上。你先别让 AI 写代码而是先让它和你一起把需求写成一段可读、可评审、可验证的规格文本。规格里写清楚目标、非目标、输入输出、验收条件然后代码阶段只是把这份规格翻译成实现。代码可以重构规格不能随便变这样 AI 的每一步执行都有锚点不至于中途跑偏。1.3 规格驱动不是文档驱动是“契约驱动”有人会觉得“这不就是写文档吗我让 AI 写需求文档它也能写”。这话对了一半。普通文档强调的是“记录”写完之后没人看规格文件强调的是“契约”AI 每次动代码之前必须读每完成一个验收条件必须能跑测试证明。区别在于文档是给人看的规格是人和 AI 共同遵守的执行协议。具体到工具上OpenSpec 帮我把规格文件、变更提案、状态流转管理起来Superpowers 则帮我把规格拆成 AI 能执行的任务流。两者配合核心逻辑就一句话先定义什么是对的再讨论怎么实现最后才让 AI 动手。这个顺序一旦反了后面全是救火。2. OpenSpec 与 Superpowers 各自解决什么问题很多人第一次看到 OpenSpec × Superpowers 会觉得抽象我把它们拆开讲清楚。你可以把 OpenSpec 理解成“需求管理后台”Superpowers 理解成“施工规范手册”。它们不在一个层级恰好互补。2.1 OpenSpec把需求“结构化”成可验证的变更提案OpenSpec 的核心工作方式是每一次需求变更都先进入一个提案阶段而不是直接改代码。提案里包含背景、目标、非目标、验收标准必要时还要写清楚影响面和数据变化。我实际用下来OpenSpec 最有价值的一点是让“非目标”显性化。以前我和 AI 对话时通常只告诉它“要什么”很少告诉它“不要什么”。结果 AI 经常顺手做一堆额外优化。OpenSpec 会让每次变更都显式列出非目标比如“本次不改动权限逻辑”“本次不做多语言”AI 一旦在计划里越界你能立刻发现。另外OpenSpec 是文件优先的工具所有状态都沉淀在项目目录里不会锁在某个聊天窗口里。这意味着你可以把一份规格文件发给任何人评审可以进 Git 做 diff甚至可以让 CI 在 AI 动代码之前检查“当前分支是否有未评审的规格变更”。这一点非常契合团队协作AI 编程容易产生的“黑箱感”被文件系统彻底打破了。2.2 Superpowers给执行过程装上“流程保险”如果说 OpenSpec 是“做什么、做到什么程度”Superpowers 就是“按什么顺序做”。Superpowers 本质上是一组 Skill它把优秀工程师的工作习惯封装成了 AI 可以调用的流程。比如先头脑风暴收集信息再写执行计划再按计划小步实现每一步都配合测试和调试。它不是简单的提示词而是一套有状态的技能目录AI 会在合适的节点主动调用对应的技能而不是靠用户一句一句去催。我体会最深的是 TDD 相关技能。以前让 AI 写代码它喜欢先写实现再补测试甚至先写实现再“编”测试。Superpowers 的执行流程会强制它先考虑测试用例先写一个会失败的测试再写实现让测试通过。整个过程像给 AI 上了轨道不是不能自由发挥而是自由发挥被限制在合理的施工顺序里出问题的概率自然就低了。2.3 两者组合后的完整闭环单独用 OpenSpec容易停留在“规格写得很规范但 AI 执行时不一定按步骤来”单独用 Superpowers容易陷入“计划很精彩但计划内容可能建立在一堆错误假设上”。组合之后链路就闭环了OpenSpec 先生成经得起推敲的规格Superpowers 再把规格转成执行计划并监督落地。规格负责“防止做错”流程负责“防止做乱”。这两件事缺一个AI 编程都很难稳定交付全栈项目。我用一个表格总结一下分工方便后面实操时对照维度OpenSpecSuperpowers核心问题做什么、不做什么、怎么验收按什么顺序、用什么方法做产出物规格文件、变更提案、验收清单头脑风暴结果、执行计划、测试序列控制对象需求边界实施步骤典型失败模式规格模糊导致 AI 乱做计划缺失导致 AI 乱序执行适合的阶段动工之前、需求变更时动工之后、任务拆解、调试阶段可替代性不能替代需求分析不能替代验收标准3. 落地安装与初始配置理论说再多不上手都是白搭。下面是我在一台干净设备上的实操记录。 OpenSpec 和 Superpowers 的安装命令更新很快建议以官方 README 为准我这里记录的是当前完全可用的方式也包含一套通用的验证思路。3.1 环境准备与安装 OpenSpec我建议准备一个“干净”的工作目录专门用来跑实验不要一上来就塞进公司老项目。原因很简单规格驱动的流程需要 AI 在每次动代码前读取目录结构如果项目本身很乱spec 里写的路径和实际路径对不上排查起来会非常痛苦。我的环境是 macOS Node.js 20。如果你还没装 Node.js先装一个 LTS 版本就行。OpenSpec 官方提供了安装脚本和 npm 包两种方式我更推荐用 npm 全局安装卸载和升级都会简单一些。npm install -g fission-ai/openspec openspec --version如果你安装遇到权限问题不要直接加 sudo 硬刚先在用户目录下配好 npm 全局路径再装。装完以后进入项目目录执行初始化cd ~/workspace/demo-project openspec init初始化会在当前项目生成.openspec开头的工作目录里面包含规格模板和项目状态配置。我见过不少人只装 CLI 忘了 init结果 AI 始终找不到规格文件所以初始化这步一定别省。3.2 安装 Superpowers skillsSuperpowers 的安装逻辑和普通 npm 包不太一样它是把一个 skill 目录暴露给 AI 编程工具。以 Claude Code 为例技能会被加载到全局或项目级目录里。git clone https://github.com/obra/superpowers.git /tmp/superpowers mkdir -p ~/.claude/skills cp -r /tmp/superpowers/skills/* ~/.claude/skills/如果你用的是 Cursor并且在项目里使用 Agent 功能可以把技能复制到当前项目的.cursor/skills目录mkdir -p .cursor/skills cp -r /tmp/superpowers/skills/* .cursor/skills/这里有个关键点不同版本的 Claude Code / Cursor / opencode 对 skill 目录的识别规则不完全一样。上面这条路径是我验证过的但如果你用的是其他客户端或者比较新的版本最好在各自的设置界面里看一遍帮助文档确认一下技能目录路径。安装完成后打开 AI 对话界面问一句“你现在能使用哪些技能”如果它列出的技能里包含 brainstorming、planning、test-driven-development 这一类说明已经加载成功。3.3 配置项目级 AGENTS.md让 AI 开局读规格安装好工具只是第一步真正让 AI “先读规格再动代码”需要靠 AGENTS.md 这类项目指令文件。很多模型在启动新对话时不会主动扫描整个目录它会优先读根目录的 AGENTS.md 或 CLAUDE.md。所以我在项目根目录创建了一个精简的指令文件## 工作原则 - 动代码之前必须阅读 .openspec 目录下所有相关提案和规格文件。 - 没有对应规格时不得直接实现先向用户确认需求。 - 实现前使用 Superpowers 规划技能拆解任务先列计划再动手。 - 执行过程中保持测试通过不跳过失败测试不隐瞒测试结果。 ## 输出要求 - 完成每个子任务时简要说明你改了哪些文件、对应哪条验收标准。 - 如果规格与实际代码冲突优先认为规格是权威。把这段内容写进 AGENTS.md 之后AI 每次开工都会先看到“先读规格”的指令这比你在对话里反复强调“你先别写代码”要稳定得多。因为对话上下文会被新消息冲掉而 AGENTS.md 通常会作为系统上下文的一部分加载。3.4 验证安装是否生效的快速方式装完之后我习惯做一个“空跑验证”故意让 AI 执行一个还没写规格的小需求看它是什么反应。我测试时用的一句话是 “帮我在首页加一个公告横幅需求还没写进规范文件你先处理一下。”如果它真的直接去改代码说明 AGENTS.md 没有生效或者上下文没读进去。如果它回复“当前没有对应规格请先创建变更提案”说明整个链路已经通了。这一步很重要。没有这个验证你可能在真正开发时才发现 AI 根本不读规格到时候返工成本就高了。4. 完整打法从业务想法到可验证交付下面用我最近在做一个内容管理后台时的一个真实小需求来演示完整流程。需求只有一句话“文章列表页增加标签筛选方便运营按标签找文章。”这句话如果直接丢给 AI十有八九会翻车不是漏了标签组合逻辑就是漏了空结果状态。我把它按完整打法拉了一遍。4.1 Step 1用“逆向验收”写规格而不是写功能清单我拿到模糊需求后不会立刻整理功能清单而是先带着 AI 做头脑风暴把“可验收的行为”问出来。这个环节可以手动进行也可以让 AI 以提问的方式帮你排查但提问方向是固定的数据从哪来标签是文章内置字段还是多对多关系多个标签筛选时是只要包含其中一个还是必须同时包含没有结果时页面显示什么标签需要按热度排序还是按名称排序这次是否涉及标签管理功能我会把所有问题的答案整理成一份规格文件。下面是我写在这个项目里的一个核心片段## 目标 文章列表支持按标签组合筛选多个标签之间取交集。 ## 非目标 - 不新增标签管理界面。 - 不处理标签别名、同义词。 - 不改动现有分类筛选逻辑。 ## 验收条件 1. 用户选择一个标签后列表只显示包含该标签的文章按发布时间倒序。 2. 用户选择多个标签时结果取交集。 3. 标签选择器显示每个标签对应的文章数量数量小于等于 0 的标签置灰。 4. 组合筛选结果为空时展示空状态组件而不是空白页面。 5. 清空筛选条件后列表恢复为全量文章。注意这份规格里没有任何一行 SQL也没有提组件名但每个条件都可以直接映射到测试用例。这就是规格驱动的精髓让验收标准先于实现存在。4.2 Step 2先做计划拆解把规格切成可执行任务规格文件写好后我会让 AI 进入 Superpowers 的规划流程大致提示语是“基于规格文件帮我生成一份实施计划先不要写业务代码。”这一步它会输出类似这样的计划任务 1为文章标签关联关系准备迁移和测试夹具。 任务 2实现文章列表接口的多标签筛选参数并补充接口测试。 任务 3修改列表前端的筛选组件支持多选标签和数量展示。 任务 4补充空状态组件并接入筛选结果为空的场景。 任务 5运行全量测试更新 API 文档。我拿到计划后不会直接让它开工而是先检查一件事计划里的每个任务是否能对应到规格里的至少一条验收条件。如果某些任务找不到对应验收条件那就是典型的“计划外动作”我会让它删掉或说明理由。如果某条验收条件没有被任何任务覆盖说明计划漏了需求我会让它补上。这个检查是我认为整套打法里最能体现工程价值的一步AI 生成的计划再漂亮也需要人来判断它和规格是否对齐。格式化的规格文件让这种对齐检查变得非常快而不是靠人脑凭感觉猜。4.3 Step 3让 AI 按任务执行测试驱动进场计划对齐之后我会把第一个任务交给 AI同时要求它严格按 TDD 流程执行先写失败测试再写实现最后做重构。比如实现“文章列表接口支持多标签筛选”这条AI 通常会先创建接口测试it(多标签筛选时返回交集结果, async () { const postA await createPost({ tags: [前端, 工程化] }); const postB await createPost({ tags: [前端] }); const res await request(app) .get(/api/posts) .query({ tags: [前端, 工程化] }) .expect(200); expect(res.body.items.map((item: any) item.id)).toEqual([postA.id]); });写这个测试的时候AI 甚至还没有实现接口的筛选逻辑。按照正常流程这个测试应该跑红。看到跑红之后它才会去实现数据查询再跑绿这条测试。这个过程能逼着 AI 把“预期行为”想清楚再动手而不是先写一堆代码再回头补测试。这里有一个非常容易被忽略的细节不要让 AI 一次性执行多个任务。Superpowers 的理想用法是一个任务一个任务地跑每完成一个都看测试结果。如果你让它在一次对话里把任务 1 到任务 5 全做完中间一旦出错定位问题的范围就会被放大好几倍。我自己吃过这个亏后来强制自己拆细。4.4 Step 4变更进入闭环而不是直接改代码任务全部完成之后我还会让 AI 做一次“规格回溯”把最终代码行为与规格里的验收条件逐条对照并输出一个验证表。例如它可能会返回验收条件 1 已通过接口测试 verify_single_tag_filter 覆盖。 验收条件 2 已通过接口测试 verify_multi_tag_intersection 覆盖。 验收条件 3 已通过前端组件测试 verify_tag_count_disable 覆盖。 验收条件 4 已通过组件测试 verify_empty_state 覆盖。 验收条件 5 已通过接口测试 verify_clear_filter 覆盖。如果某一条验收条件没有对应测试就说明实现不完整如果测试存在但没有跑就说明测试被跳过了。这两类问题我都会让 AI 当场处理绝不带到下一次需求里。此外每次需求结束OpenSpec 的变更提案会进入一个已完成状态。下次再提新需求时新规格会和旧规格形成对比AI 能很清楚地区分哪些是本次变更引入的哪些是原本就有的行为。这个历史追踪能力是做大型项目时特别刚需的。5. 实际项目中踩过的坑与排查建议再顺的工具落地过程中也难免踩坑。我把自己遇到的典型问题和排查思路整理成速查表方便你直接在团队内部排查。5.1 技能不生效、规格不读、计划乱飞排查速查表现象大概率原因解决办法AI 说不知道 Superpowersskill 路径没放对或客户端缓存了旧的技能列表重启会话运行“列出可用技能”检查 skills 目录完全忽略 AGENTS.md上下文过长时指令被截断或指令放在子目录把核心规则写在根目录 AGENTS.md尽量精简读了规格但计划仍不合理计划没有和验收条件对齐要求它逐条映射验收条件不接受无来源的任务测试老是不通过可能不是代码问题是测试夹具和规格不一致禁止改测试绕过先检查夹具数据和规格假设AI 频繁越界改无关文件规格里的非目标写得不够清楚在规格里增加“非目标”章节明确禁止动作规格文件越来越长AI 读不进去规格粒度失控拆分变更提案一次只解决一组相关需求其中最坑的是第一条和第二条。因为很多工具对 skill 目录的加载是会话开始时做的你中途把新技能复制进目录它不会热加载。遇到“没生效”的情况先重启会话再问技能列表都比在对话里反复追问“你明白了吗”有效。5.2 规格粒度怎么控制才不会过度设计有人会把规格写成 200 行的大文档反而把 AI 限制死了任何一点小改动都要花大量时间去更新规格。我的经验是一份规格文件控制在 30~60 行聚焦在“行为契约”上。什么意思就是多写“用户看到什么、接口返回什么、边界情况怎么处理”少写“你调用某个函数、用某个设计模式”。前者是规格后者是实现计划。如果 AI 在执行时发现实现细节有问题它应该有空间调整但如果它调整了接口行为就必须回来改规格和测试。这个边界不守住规格就会变成流水账最后没人愿意维护。我一般这样判断粒度如果一段内容删掉之后代码行为不会发生任何变化那它就不该出现在规格里。反之如果一段内容删掉之后AI 可能做出两种不同的实现那它就该保留。5.3 什么时候不该用这套组合规格驱动不是银弹。我最近写一些一次性脚本、临时爬虫、原型验证代码时已经完全不用这套流程了。因为那些任务本身生命周期极短写完跑一次就扔花时间写规格反而拖慢节奏。另外纯探索性质的聊天也不适合引入 OpenSpec。比如你在跟 AI 讨论“某个方案是否可行”这属于发散讨论不该强制进入“提案-验收-执行”的僵硬流程。我自己的经验是先用普通对话做技术预研一旦判断这个功能需要进入项目、要持续迭代再切换到规格驱动。还有一点如果你的 AI 编程工具只支持普通的聊天补全不支持 Skills 和项目上下文指令那 Superpowers 的价值会大打折扣。这套组合最适合已经具备 Agent 能力、能自主调用工具、能读取多文件上下文的编程工具。工具不对上面的流程很难完整跑起来。6. 关于这套打法我最想说的三句话如果你只打算记住这篇里的几件事我建议记这三句。第一句规格文件是给 AI 看的“任务书”不是给老板看的“汇报材料”。写规格时不要堆形容词要写能在测试里断言的行为。第二句OpenSpec 负责守住需求边界Superpowers 负责守住执行顺序两者分开用威力减半。第三句再完美的流程也需要人做终审AI 生成的计划不是用来直接执行的而是用来被检查的。我在实际项目中跑了大概三周之后最大的变化不是代码写得快了而是“返工”明显少了。以前每个需求做完我都会担心 AI 有没有悄悄改坏别的地方现在有了规格和测试双保险每次收尾我只需要看那份验收条件对照表心里踏实很多。最后再分享一个小技巧我会把 AGENTS.md 里“先读规格再动代码”这句话放在指令的最前面后面才是各种技术栈说明。你别说就这么一个小调整AI 不按规格走的情况直接少了一大半。很多人喜欢在 AGENTS.md 里堆技术细节结果核心指令被挤到后面反而成了摆设。这个顺序问题值得你回去检查一遍。