这两年做 AI 编程的人几乎都经历过同一种崩溃AI 写码速度是真的快但跑偏起来也是真的快。你给它一句话需求它还给你一个能跑、结构完整、但完全不是你想要的“看起来对”的东西。问题从来不在 AI 本身而在于我们怎么给它下需求。后来我把工作流切换到 OpenSpec Superpowers 这套“规格驱动”的打法之后项目交付的稳定性实打实上了一个台阶。今天不聊虚的把整套思路、工具选型、以及我在真实项目里踩过的坑完整盘一遍。这篇文章适合谁一种是已经被 AI 编程“惊艳过”也开始“惊吓过”的人你想把 AI 的输出从“随缘”变成“可控”另一种是刚开始接触 AI 编程、想一步到位建立正确工作流的新手。无论哪种这套方法论都能给你一个可以直接落地复制的框架。1. 先理清楚为什么“规格驱动”能解决 AI 编程的核心痛点1.1 聊天式编程的幻觉AI 最擅长“一本正经地跑偏”先讲一个我自己的经历。早期我用 AI 编程助手干活方式很原始——把需求打字发过去AI 哗啦啦生成一整包代码我一看结构漂亮、注释齐全心里暗爽。结果合入项目三天后问题开始浮出水面需求里的边界条件一个没处理业务规则连蒙带猜验收标准对不上号。后来我意识到问题不在 AI 的代码能力而在“需求传递”这个环节。人和 AI 最大的差异是我们脑子里有一套默认的上下文很多东西不用说出口但 AI 没有那套上下文它只能从你的只言片语里“猜”。猜对了是运气猜错了是常态。这就是聊天式编程的致命伤你给了 AI 一道填空题AI 却以为自己做的是阅读理解。所以它输出的东西代码层面可能是对的需求层面可能就是错的。这种“一本正经地跑偏”比 AI 直接报错更可怕——报错你一眼就能看到跑偏你得等到测试甚至上线之后才能发现。1.2 规格驱动到底是什么先画图纸再让 AI 施工规格驱动的核心逻辑用一句话概括就是别让 AI 替你思考需求只让它替你实现需求。我经常用一个装修的类比来解释这件事。聊天式编程是什么感觉你请了个施工队然后你站在毛坯房里说“这里整个客厅那里搞个厨房风格要高级一点”然后就走了。三天后回来一看客厅有了厨房也有了但厨房在客厅里面风格是“高级的混乱”。你气得不行施工队也委屈——你说高级我觉得这就挺高级。规格驱动就是反过来施工之前先出一套完整的图纸。哪里放什么、用什么材料、尺寸多少、验收标准是什么全都白纸黑字写清楚。施工队AI只负责照图施工你有意见改图纸而不是改工地。这样改出来的东西哪怕不是一个惊世骇俗的设计但至少不会离谱。放到 AI 编程语境下规格驱动就是三个步骤先写规格文档 → 再让 AI 按规格实现 → 最后用规格里的验收标准做测试。每一步都有据可查AI 的自由度被约束在“实现层”而不是“决策层”。1.3 从“提示词工程”到“规格工程”一次思维升级过去两三年大家都在聊“提示词工程”研究怎么把需求写得让 AI 更懂。但提示词工程有个天花板提示词是对话级的今天写好了一条提示词明天新对话就忘了。而且提示词本质上是面向“单次交互”的优化它优化的是“AI 听懂你这句话”的概率而不是“项目按预期交付”的概率。规格驱动本质上是一次升级——从提示词工程升级到规格工程。规格不再是一次性输入而是项目里的一组持久化文档跟代码放在一起跟测试绑定在一起跟验收流程串在一起。AI 每次开工之前先读规格每次改完代码用规格里的验收测试来验证。规格成了人和 AI 之间的“共同语言”而不是聊完就作废的对话记录。把这两套流行工具放在一起看就很有意思OpenSpec 管的是“规格怎么写、怎么存、怎么验收”Superpowers 管的是“AI 怎么思考、怎么规划、怎么执行”。一个约束产出一个优化过程正好补上了聊天式编程最缺的两块短板。2. OpenSpec 到底在解决什么一套可落地的规格化工作流2.1 OpenSpec 是什么不只是文档是 AI 编程的“需求锚点”顺着上面的思路我们需要一个工具帮我们把“写规格”这件事变成习惯最好还能跟 AI 编程流程无缝衔接。OpenSpec 就是干这个的。OpenSpec 的官方定位是一套开源的、规格驱动的工作流规范它定义了一种目录结构、一套文档格式、以及一个从需求到验收的闭环流程。你不需要从零发明写规格的方法OpenSpec 已经把骨架给你搭好了你往里面填内容就行。具体来说OpenSpec 把项目里的需求变更组织成一个个“Change”变更单元。一个 Change 就是一个小的、自包含的规格单元里面包含三样东西问题背景为什么要做、规格定义怎么做、以及验收标准怎么算做完。项目里的所有代码改动都能对应到一个或多个 Change 上。这样AI 每次动手改代码之前必须先读对应 Change 的规格改完之后跑一遍验收标准。有了这个“需求锚点”AI 就不再是收到一句话就开干而是始终围绕规格展开工作。代码可能改了好几版规格不变主线就不会乱。2.2 OpenSpec 的目录结构与文件规范规格就该有规格OpenSpec 定义了一套目录规范核心结构大致是这样的openspec/ ├── changes/ │ ├── add-payment-upgrade/ │ │ ├── proposal.md # 变更提案背景、目标、方案 │ │ └── spec.md # 规格详情具体规则、边界、验收标准 │ └── fix-invoice-bug/ │ ├── proposal.md │ └── spec.md └── project.md # 项目级说明整体架构、技术栈、通用约定这里project.md是全局的描述项目的整体情况相当于给 AI 的“项目背景说明书”changes/目录下每个子目录对应一个需求变更里面至少包含proposal.md提案和spec.md规格两份文档。提案负责回答“为什么做”规格负责回答“怎么做、做到什么程度算完”。我实际用下来这个结构最大的价值是强迫你把需求拆小。传统开发里你很容易写出一个“实现用户系统”这样的大需求AI 一看这种需求就得发挥创造力。但 OpenSpec 要求你拆成一个一个 Change——“支持邮箱登录”、“支持忘记密码”、“支持第三方 OAuth 登录”——每一块都是可独立交付、独立验收的小单元。需求一旦拆小AI 的实现准确率会高一大截。2.3 OpenSpec 如何约束 AI规格即验收验收即测试OpenSpec 里最有价值的设计是它把验收标准写进了规格里而且明确要求验收标准必须是可测试的。什么意思很多人在需求文档里写“系统要稳定”这句话 AI 没法验证因为它不可测试。但如果你写“用户提交包含非法字符的邮箱时系统返回 400 错误码且不会创建任何数据库记录”这就是一个可测试的验收标准AI 可以把它翻译成测试用例然后在代码里逐条验证。实际操作中我会在spec.md里把验收标准写成一个一个带编号的条目每个条目尽量用“当 X 条件发生时系统执行 Y 操作返回 Z 结果”这种可测句式。AI 拿到规格后我会明确要求它先写测试用例、再写实现代码最后跑测试确认全部通过。这样一来AI 的“做完”不再靠它的自我感觉而是靠测试结果说话。这套逻辑把“验收”从人的主观判断变成了客观测试结果自由度交给了实现确定性留给了流程。3. Superpowers 在 AI 编程里的角色给 AI 装上“方法论大脑”3.1 Skills 机制给 AI 预装“专业技能包”OpenSpec 管的是规格和流程但还有一个问题它没解决AI 拿到规格之后怎么保证它能高效、高质量地实现就像你给了施工队一套精细图纸但施工队没学过怎么砌墙照样白搭。这里就要聊到 Superpowers 了。Superpowers 是一套基于 Claude Code Skills 机制开发的技能包集合你可以把它理解成给 AI 预装的“专业技能包”。Skills 是 Anthropic 在 Claude 系模型里引入的一种扩展机制允许你把特定的专业方法论、工作流程、决策框架打包成文件让 AI 在需要时自动加载并遵循。用过 AI 编程工具的朋友应该知道默认状态下 AI 就像一个聪明的“通才”什么都懂一点但遇到特定类型的任务时不一定按照最佳实践来。而 Skills 机制解决了这个问题——相当于给这个通才配备了一本“专业操作手册”做代码审查的时候就翻代码审查的章节做重构的时候就翻重构的章节。3.2 Superpowers 的核心工作流规划 → 编码 → 验证Superpowers 这个技能包最核心的价值是它给 AI 编码过程装了一套标准工作流。如果用一句话概括就是先想明白再动手改最后证明没改坏。具体展开是三个阶段第一阶段是“规划”。AI 拿到任务后不是立刻开写代码而是先停下来分析需求、列计划、设计技术方案。这个阶段会强制 AI 检查自己“有没有完全理解需求”、“有没有遗漏边界条件”。如果你把 Superpowers 和 OpenSpec 结合这个阶段 AI 会先读规格文档然后产出自己的实现计划。第二阶段是“编码”。AI 按计划实现功能但实现过程中不是无脑堆代码而是遵循测试驱动的节奏——先写测试再写实现然后小步迭代。这样每一段代码都有对应的测试守护改起来不怕出错。第三阶段是“验证”。代码写完之后AI 会主动做自查和验证包括跑测试、检查代码质量、对比规格验收标准。没通过就继续修通过了才算完成。整个流程相当于给 AI 装了个“内部质检员”不再写完就交差。3.3 为什么聪明如 AI也需要“方法论约束”有人可能会问Claude、GPT 这些模型已经很强了为什么还要额外给它们装方法论我的体验是模型聪明是聪明但它本质上是一个“超级预测器”你问它一个问题它在预测“最可能的下一段内容”是什么。这就导致一个问题如果你不约束它它会倾向于输出“最典型的方案”而“最典型的方案”不一定是“最适合你当前项目的方案”。比如你让它重构一个组件它可能直接给你一个标准的三层架构但你的项目可能只需要一个几十行的工具函数。AI 不是不会写简单的而是默认模式会导向“标准答案”。Superpowers 这类方法论约束就是不断提醒 AI——“停一下想清楚需求再动手”、“按测试驱动节奏来”、“完成之前先自检”。这看起来像是给 AI 加了限制实际上是在减少它跑偏的概率。4. 两者结合实战一套完整的规格驱动 AI 交付流程4.1 环境准备安装配置两件套下面进入实操环节。我先说环境准备因为这块坑不少。我目前的常用组合是 Claude Code 作为 AI 编程主环境然后安装 OpenSpec 和 Superpowers。Claude Code 是 Anthropic 官方出的终端编程工具Skill 机制和工具链的兼容性最好。你如果用的是其他 AI 编程工具原理可以参考但具体命令会有差异。先装 OpenSpec官方提供了自动安装脚本curl -fsSL https://openspec.dev/install.sh | bash装完后在项目根目录初始化工作区openspec init接着装 Superpowers。Superpowers 是以 Skills 集合的形式分发的需要安装到 Claude Code 的 skills 目录里。克隆项目后把关键 skill 文件复制到对应目录git clone https://github.com/workswarm/superpowers.git # 查看安装文档通常是将 skills 同步到 Claude Code 的配置目录注意不同版本的 Claude CodeSkills 目录位置可能不一样。安装前务必确认你当前版本的 skill 加载路径否则装完 AI 根本不加载白折腾一场。装完可以快速验证一下在 Claude Code 里输入类似“/skills”的命令查看已加载的技能列表能看见 Superpowers 的各个技能模块就说明安装成功。4.2 需求阶段用 Superpowers 把模糊想法磨成规格环境准备好之后整个实战流程分五个阶段我按顺序走一遍。我以一个实际做过的项目举例给一个内部工具加一个“批量导入用户”的功能。第一阶段是需求澄清。传统做法是你直接告诉 AI“加一个批量导入用户的功能”然后听天由命。但有了这套工作流我第一件事是打开 Superpowers 里的 brainstorming 相关工作流让 AI 引导我把需求问清楚导入文件的格式是什么最大支持多少行导入过程中出现部分失败怎么处理重复的用户名是跳过还是覆盖需不需要生成导入结果报告你会发现这些问题如果没有流程引导你自己根本想不到要回答就算想到了也不会认为该提前告诉 AI。但正是这些细节决定了 AI 输出质量的百分之八十。模糊的需求给 AI它就靠猜猜对了是运气但这些细节问清楚了AI 的实现就不存在猜的成分了。4.3 规格阶段用 OpenSpec 把需求固化成文档第二阶段是规格编写。需求澄清做完之后我会在 OpenSpec 里新建一个 Changeopenspec create add-batch-user-import这个命令会创建openspec/changes/add-batch-user-import/目录生成proposal.md和spec.md两份模板。proposal.md里写背景和目标重点是让 AI 理解“为什么做这件事”比如“当前用户新增依赖管理员逐条录入效率低且易错需要支持通过 CSV 文件批量导入提高运营效率”。真正的重头戏在spec.md我把需求澄清阶段得到的答案逐条转化为规格条目和验收标准### 功能规格 - 支持上传 CSV 文件文件需包含 username, email, display_name 三列 - 单次导入最多支持 5000 行超过则拒绝导入并提示错误 - 导入前进行全量校验若存在用户名重复或邮箱格式非法则整批失败并返回错误报告 - 导入成功后系统向操作人发送包含导入成功/失败行数的站内通知 ### 验收标准 - ACA-001: 上传含 5001 行的 CSV系统返回 400 错误提示“单次导入不能超过 5000 行” - ACA-002: 上传含非法邮箱格式的 CSV系统返回 422 错误数据库无任何新增记录 - ACA-003: 上传 100 行合法 CSV系统返回 200 成功数据库新增 100 条记录操作人收到通知写完规格这一步我一般会先让另一个 AI或者同一个 AI 的另一个会话来扮演“需求挑刺官”专门找规格里的漏洞。这一步很管用因为写规格的人容易陷入“我以为我写清楚了”的错觉。4.4 实施阶段AI 照图施工测试先行兜底第三阶段就是实施。这时候把规格交给 AI让它开始实现。但注意不要让 AI 直接读 specs 就开写我会明确要求它执行 Superpowers 的测试驱动开发工作流顺序是先列出实现计划 → 针对每条验收标准写测试用例 → 写实现代码 → 跑测试确认验收标准全部通过。这里重点说一下为什么“先写测试”这件事如此重要。直接写实现代码AI 很容易陷入“自我感觉良好”的陷阱——代码写完、编译通过就觉得搞定了。但编译通过不等于需求实现测试通过才算。先写测试本质上是在逼 AI 把验收标准变成可执行的断言这样它后面写的每一行代码都是奔着“让测试通过”去的而不是奔着“写完交差”去的。实际操作中我会给 AI 一套很明确的指令模板大致长这样请完成 openspec/changes/add-batch-user-import/spec.md 中定义的功能。 要求 1. 先阅读规格文档理解全部功能规格和验收标准 2. 按照测试驱动开发流程执行先为每条验收标准编写测试用例 3. 实现功能代码确保测试通过 4. 测试全部通过后运行全量回归测试确认没有破坏其他功能 5. 完成后汇报测试结果矩阵这个指令模板本身没什么高深的关键是把它跟 OpenSpec 的规格、Superpowers 的方法论串在一起让 AI 既知道“做什么”也知道“怎么做”。4.5 验收阶段规格、测试、代码三方对齐第四阶段是验收。AI 说自己做完了你不能直接信跑一遍验证流程。OpenSpec 本身不跑测试但它提供了一种方式把验收标准和实际测试关联起来。实际操作中我让 AI 在汇报结果时把每个验收标准的测试结果整理成一张对照表验收标准测试用例测试结果ACA-001: 5001 行 CSV 返回 400test_import_rejects_over_limit通过ACA-002: 非法邮箱返回 422 且无新增test_import_rejects_invalid_email通过ACA-003: 100 行合法 CSV 导入成功test_import_success_with_100_rows通过这一步的价值在于验收不再是你和 AI 之间的“信任游戏”而是规格、测试、代码三方的客观对齐。每一条验收标准都对应一个测试用例每个测试用例都有明确的通过结果你只需要人工抽验部分关键逻辑而不是重新审查所有代码。4.6 迭代阶段变更走流程不再靠口头沟通最后是迭代阶段。需求变更是软件开发里的常态最怕的是“口头改需求”——今天 AI 对话里改一下明天新对话里 AI 不知道有这回事代码就乱了。OpenSpec 的方案是把变更也纳入流程开一个新 Change写新提案更新对应的规格和验收标准然后让 AI 按新规格实现。比如用户用了两周后提需求“批量导入时如果用户名重复不要整批失败改成跳过重复行并生成报告”。这时候我新建一个update-batch-user-import的 Change修改规格条目为“若存在用户名重复跳过重复行其他行正常导入并在报告中列出跳过的行号”同时新增验收标准 ACA-004: “CSV 中含 3 行重复用户名和 2 行正常数据导入成功 2 条、跳过 3 条报告包含跳过明细”。由于规格文档存在AI 可以精准知道旧行为和新行为的差异测试也不会漏掉旧逻辑。规格驱动最大的红利在这里显现变更可追溯、行为可预期、回归可验证。5. 常见问题与避坑清单这套打法落地时最容易翻车的几个地方任何方法论放到真实项目里都会遇到意外我把这套流程落地过程中踩过的坑和排查经验整理成一份速查表按出现频率排个序。现象根本原因解决方案AI 不读规格直接开写指令里没明确要求先读规格AI 默认走快捷路径指令模板里必须写死“先阅读 openspec/ 下对应 Change 的 spec.md再开始编码”验收标准太模糊AI 说“无法测试”规格里写了“系统要稳定”这类不可测标准重写为“当 X 发生时系统执行 Y返回 Z”的可测句式测试写完了但没覆盖验收标准让 AI “自由发挥”写测试没有逐条对应要求测试用例必须标注对应的验收标准编号ACA-XXX需求变更后 AI 保留旧逻辑直接在原对话里改需求没有更新规格文档所有变更走 OpenSpec 新 Change 流程改完规格再动代码AI 装完 Superpowers 后完全不生效Skills 目录放错了位置仔细看文档确认当前版本 Claude Code 的 skills 加载路径装完验证技能列表AI 实现过程中偏离规格但代码能跑缺少中间检查点在实施阶段要求 AI 先输出实现计划确认方案符合规格后再写代码再说几个没写进表格、但同样重要的个人经验。第一件规格别追求一次写到完美。很多人第一次接触规格驱动容易走极端想把所有东西都写全结果规格写了两天还没动代码。规格的价值是“够了就行”不是“完美才行”。我一般的原则是能把模糊的需求变成可测试的行为就够了剩下的边界条件可以在测试阶段补。规格也应该像代码一样迭代而不是一锤定音。第二件AI 的“自我验证”能力有边界。即使你要求 AI 先写测试再写实现它也有可能写出“为了通过而通过”的测试——比如测试代码本身写得不对或者断言写得太弱。所以关键的验收标准尤其是涉及金额、权限、数据一致性这类高危逻辑我仍然会人工过一遍测试代码确信断言的严格性到位。不要因为流程对了就放弃人工审查流程降低的是风险不是清零风险。第三件这套方法论有一个适用边界。像“写一个 hello world”这种小任务规格驱动纯属杀鸡用牛刀但只要是需要多轮迭代、需求会变化、失败了有成本的任务这套流程的性价比就很高。我给团队的建议是小任务直接对话式完成中等以上任务走规格驱动形成习惯后你就分得清什么任务该走哪条路。最后再分享一个很实用的技巧让 AI 在每次完成一个阶段的规格实现之后用一句话总结“这个 Change 的核心变更点和验收结论”然后把这个总结放在规格文档的末尾。这样过几周再回头看项目AI 能快速定位当时做了什么、为什么这么做你也能少花很多时间重新理解旧代码。把项目的历史演进记录下来这本身就是规格驱动模式长期收益里最容易被低估的一环。 
长河君 · 2026/9/8 11:49:00 · 阅读 1.2k OpenSpec+Superpowers：规格驱动AI编程，告别AI写码跑偏
这两年做 AI 编程的人几乎都经历过同一种崩溃AI 写码速度是真的快但跑偏起来也是真的快。你给它一句话需求它还给你一个能跑、结构完整、但完全不是你想要的“看起来对”的东西。问题从来不在 AI 本身而在于我们怎么给它下需求。后来我把工作流切换到 OpenSpec Superpowers 这套“规格驱动”的打法之后项目交付的稳定性实打实上了一个台阶。今天不聊虚的把整套思路、工具选型、以及我在真实项目里踩过的坑完整盘一遍。这篇文章适合谁一种是已经被 AI 编程“惊艳过”也开始“惊吓过”的人你想把 AI 的输出从“随缘”变成“可控”另一种是刚开始接触 AI 编程、想一步到位建立正确工作流的新手。无论哪种这套方法论都能给你一个可以直接落地复制的框架。1. 先理清楚为什么“规格驱动”能解决 AI 编程的核心痛点1.1 聊天式编程的幻觉AI 最擅长“一本正经地跑偏”先讲一个我自己的经历。早期我用 AI 编程助手干活方式很原始——把需求打字发过去AI 哗啦啦生成一整包代码我一看结构漂亮、注释齐全心里暗爽。结果合入项目三天后问题开始浮出水面需求里的边界条件一个没处理业务规则连蒙带猜验收标准对不上号。后来我意识到问题不在 AI 的代码能力而在“需求传递”这个环节。人和 AI 最大的差异是我们脑子里有一套默认的上下文很多东西不用说出口但 AI 没有那套上下文它只能从你的只言片语里“猜”。猜对了是运气猜错了是常态。这就是聊天式编程的致命伤你给了 AI 一道填空题AI 却以为自己做的是阅读理解。所以它输出的东西代码层面可能是对的需求层面可能就是错的。这种“一本正经地跑偏”比 AI 直接报错更可怕——报错你一眼就能看到跑偏你得等到测试甚至上线之后才能发现。1.2 规格驱动到底是什么先画图纸再让 AI 施工规格驱动的核心逻辑用一句话概括就是别让 AI 替你思考需求只让它替你实现需求。我经常用一个装修的类比来解释这件事。聊天式编程是什么感觉你请了个施工队然后你站在毛坯房里说“这里整个客厅那里搞个厨房风格要高级一点”然后就走了。三天后回来一看客厅有了厨房也有了但厨房在客厅里面风格是“高级的混乱”。你气得不行施工队也委屈——你说高级我觉得这就挺高级。规格驱动就是反过来施工之前先出一套完整的图纸。哪里放什么、用什么材料、尺寸多少、验收标准是什么全都白纸黑字写清楚。施工队AI只负责照图施工你有意见改图纸而不是改工地。这样改出来的东西哪怕不是一个惊世骇俗的设计但至少不会离谱。放到 AI 编程语境下规格驱动就是三个步骤先写规格文档 → 再让 AI 按规格实现 → 最后用规格里的验收标准做测试。每一步都有据可查AI 的自由度被约束在“实现层”而不是“决策层”。1.3 从“提示词工程”到“规格工程”一次思维升级过去两三年大家都在聊“提示词工程”研究怎么把需求写得让 AI 更懂。但提示词工程有个天花板提示词是对话级的今天写好了一条提示词明天新对话就忘了。而且提示词本质上是面向“单次交互”的优化它优化的是“AI 听懂你这句话”的概率而不是“项目按预期交付”的概率。规格驱动本质上是一次升级——从提示词工程升级到规格工程。规格不再是一次性输入而是项目里的一组持久化文档跟代码放在一起跟测试绑定在一起跟验收流程串在一起。AI 每次开工之前先读规格每次改完代码用规格里的验收测试来验证。规格成了人和 AI 之间的“共同语言”而不是聊完就作废的对话记录。把这两套流行工具放在一起看就很有意思OpenSpec 管的是“规格怎么写、怎么存、怎么验收”Superpowers 管的是“AI 怎么思考、怎么规划、怎么执行”。一个约束产出一个优化过程正好补上了聊天式编程最缺的两块短板。2. OpenSpec 到底在解决什么一套可落地的规格化工作流2.1 OpenSpec 是什么不只是文档是 AI 编程的“需求锚点”顺着上面的思路我们需要一个工具帮我们把“写规格”这件事变成习惯最好还能跟 AI 编程流程无缝衔接。OpenSpec 就是干这个的。OpenSpec 的官方定位是一套开源的、规格驱动的工作流规范它定义了一种目录结构、一套文档格式、以及一个从需求到验收的闭环流程。你不需要从零发明写规格的方法OpenSpec 已经把骨架给你搭好了你往里面填内容就行。具体来说OpenSpec 把项目里的需求变更组织成一个个“Change”变更单元。一个 Change 就是一个小的、自包含的规格单元里面包含三样东西问题背景为什么要做、规格定义怎么做、以及验收标准怎么算做完。项目里的所有代码改动都能对应到一个或多个 Change 上。这样AI 每次动手改代码之前必须先读对应 Change 的规格改完之后跑一遍验收标准。有了这个“需求锚点”AI 就不再是收到一句话就开干而是始终围绕规格展开工作。代码可能改了好几版规格不变主线就不会乱。2.2 OpenSpec 的目录结构与文件规范规格就该有规格OpenSpec 定义了一套目录规范核心结构大致是这样的openspec/ ├── changes/ │ ├── add-payment-upgrade/ │ │ ├── proposal.md # 变更提案背景、目标、方案 │ │ └── spec.md # 规格详情具体规则、边界、验收标准 │ └── fix-invoice-bug/ │ ├── proposal.md │ └── spec.md └── project.md # 项目级说明整体架构、技术栈、通用约定这里project.md是全局的描述项目的整体情况相当于给 AI 的“项目背景说明书”changes/目录下每个子目录对应一个需求变更里面至少包含proposal.md提案和spec.md规格两份文档。提案负责回答“为什么做”规格负责回答“怎么做、做到什么程度算完”。我实际用下来这个结构最大的价值是强迫你把需求拆小。传统开发里你很容易写出一个“实现用户系统”这样的大需求AI 一看这种需求就得发挥创造力。但 OpenSpec 要求你拆成一个一个 Change——“支持邮箱登录”、“支持忘记密码”、“支持第三方 OAuth 登录”——每一块都是可独立交付、独立验收的小单元。需求一旦拆小AI 的实现准确率会高一大截。2.3 OpenSpec 如何约束 AI规格即验收验收即测试OpenSpec 里最有价值的设计是它把验收标准写进了规格里而且明确要求验收标准必须是可测试的。什么意思很多人在需求文档里写“系统要稳定”这句话 AI 没法验证因为它不可测试。但如果你写“用户提交包含非法字符的邮箱时系统返回 400 错误码且不会创建任何数据库记录”这就是一个可测试的验收标准AI 可以把它翻译成测试用例然后在代码里逐条验证。实际操作中我会在spec.md里把验收标准写成一个一个带编号的条目每个条目尽量用“当 X 条件发生时系统执行 Y 操作返回 Z 结果”这种可测句式。AI 拿到规格后我会明确要求它先写测试用例、再写实现代码最后跑测试确认全部通过。这样一来AI 的“做完”不再靠它的自我感觉而是靠测试结果说话。这套逻辑把“验收”从人的主观判断变成了客观测试结果自由度交给了实现确定性留给了流程。3. Superpowers 在 AI 编程里的角色给 AI 装上“方法论大脑”3.1 Skills 机制给 AI 预装“专业技能包”OpenSpec 管的是规格和流程但还有一个问题它没解决AI 拿到规格之后怎么保证它能高效、高质量地实现就像你给了施工队一套精细图纸但施工队没学过怎么砌墙照样白搭。这里就要聊到 Superpowers 了。Superpowers 是一套基于 Claude Code Skills 机制开发的技能包集合你可以把它理解成给 AI 预装的“专业技能包”。Skills 是 Anthropic 在 Claude 系模型里引入的一种扩展机制允许你把特定的专业方法论、工作流程、决策框架打包成文件让 AI 在需要时自动加载并遵循。用过 AI 编程工具的朋友应该知道默认状态下 AI 就像一个聪明的“通才”什么都懂一点但遇到特定类型的任务时不一定按照最佳实践来。而 Skills 机制解决了这个问题——相当于给这个通才配备了一本“专业操作手册”做代码审查的时候就翻代码审查的章节做重构的时候就翻重构的章节。3.2 Superpowers 的核心工作流规划 → 编码 → 验证Superpowers 这个技能包最核心的价值是它给 AI 编码过程装了一套标准工作流。如果用一句话概括就是先想明白再动手改最后证明没改坏。具体展开是三个阶段第一阶段是“规划”。AI 拿到任务后不是立刻开写代码而是先停下来分析需求、列计划、设计技术方案。这个阶段会强制 AI 检查自己“有没有完全理解需求”、“有没有遗漏边界条件”。如果你把 Superpowers 和 OpenSpec 结合这个阶段 AI 会先读规格文档然后产出自己的实现计划。第二阶段是“编码”。AI 按计划实现功能但实现过程中不是无脑堆代码而是遵循测试驱动的节奏——先写测试再写实现然后小步迭代。这样每一段代码都有对应的测试守护改起来不怕出错。第三阶段是“验证”。代码写完之后AI 会主动做自查和验证包括跑测试、检查代码质量、对比规格验收标准。没通过就继续修通过了才算完成。整个流程相当于给 AI 装了个“内部质检员”不再写完就交差。3.3 为什么聪明如 AI也需要“方法论约束”有人可能会问Claude、GPT 这些模型已经很强了为什么还要额外给它们装方法论我的体验是模型聪明是聪明但它本质上是一个“超级预测器”你问它一个问题它在预测“最可能的下一段内容”是什么。这就导致一个问题如果你不约束它它会倾向于输出“最典型的方案”而“最典型的方案”不一定是“最适合你当前项目的方案”。比如你让它重构一个组件它可能直接给你一个标准的三层架构但你的项目可能只需要一个几十行的工具函数。AI 不是不会写简单的而是默认模式会导向“标准答案”。Superpowers 这类方法论约束就是不断提醒 AI——“停一下想清楚需求再动手”、“按测试驱动节奏来”、“完成之前先自检”。这看起来像是给 AI 加了限制实际上是在减少它跑偏的概率。4. 两者结合实战一套完整的规格驱动 AI 交付流程4.1 环境准备安装配置两件套下面进入实操环节。我先说环境准备因为这块坑不少。我目前的常用组合是 Claude Code 作为 AI 编程主环境然后安装 OpenSpec 和 Superpowers。Claude Code 是 Anthropic 官方出的终端编程工具Skill 机制和工具链的兼容性最好。你如果用的是其他 AI 编程工具原理可以参考但具体命令会有差异。先装 OpenSpec官方提供了自动安装脚本curl -fsSL https://openspec.dev/install.sh | bash装完后在项目根目录初始化工作区openspec init接着装 Superpowers。Superpowers 是以 Skills 集合的形式分发的需要安装到 Claude Code 的 skills 目录里。克隆项目后把关键 skill 文件复制到对应目录git clone https://github.com/workswarm/superpowers.git # 查看安装文档通常是将 skills 同步到 Claude Code 的配置目录注意不同版本的 Claude CodeSkills 目录位置可能不一样。安装前务必确认你当前版本的 skill 加载路径否则装完 AI 根本不加载白折腾一场。装完可以快速验证一下在 Claude Code 里输入类似“/skills”的命令查看已加载的技能列表能看见 Superpowers 的各个技能模块就说明安装成功。4.2 需求阶段用 Superpowers 把模糊想法磨成规格环境准备好之后整个实战流程分五个阶段我按顺序走一遍。我以一个实际做过的项目举例给一个内部工具加一个“批量导入用户”的功能。第一阶段是需求澄清。传统做法是你直接告诉 AI“加一个批量导入用户的功能”然后听天由命。但有了这套工作流我第一件事是打开 Superpowers 里的 brainstorming 相关工作流让 AI 引导我把需求问清楚导入文件的格式是什么最大支持多少行导入过程中出现部分失败怎么处理重复的用户名是跳过还是覆盖需不需要生成导入结果报告你会发现这些问题如果没有流程引导你自己根本想不到要回答就算想到了也不会认为该提前告诉 AI。但正是这些细节决定了 AI 输出质量的百分之八十。模糊的需求给 AI它就靠猜猜对了是运气但这些细节问清楚了AI 的实现就不存在猜的成分了。4.3 规格阶段用 OpenSpec 把需求固化成文档第二阶段是规格编写。需求澄清做完之后我会在 OpenSpec 里新建一个 Changeopenspec create add-batch-user-import这个命令会创建openspec/changes/add-batch-user-import/目录生成proposal.md和spec.md两份模板。proposal.md里写背景和目标重点是让 AI 理解“为什么做这件事”比如“当前用户新增依赖管理员逐条录入效率低且易错需要支持通过 CSV 文件批量导入提高运营效率”。真正的重头戏在spec.md我把需求澄清阶段得到的答案逐条转化为规格条目和验收标准### 功能规格 - 支持上传 CSV 文件文件需包含 username, email, display_name 三列 - 单次导入最多支持 5000 行超过则拒绝导入并提示错误 - 导入前进行全量校验若存在用户名重复或邮箱格式非法则整批失败并返回错误报告 - 导入成功后系统向操作人发送包含导入成功/失败行数的站内通知 ### 验收标准 - ACA-001: 上传含 5001 行的 CSV系统返回 400 错误提示“单次导入不能超过 5000 行” - ACA-002: 上传含非法邮箱格式的 CSV系统返回 422 错误数据库无任何新增记录 - ACA-003: 上传 100 行合法 CSV系统返回 200 成功数据库新增 100 条记录操作人收到通知写完规格这一步我一般会先让另一个 AI或者同一个 AI 的另一个会话来扮演“需求挑刺官”专门找规格里的漏洞。这一步很管用因为写规格的人容易陷入“我以为我写清楚了”的错觉。4.4 实施阶段AI 照图施工测试先行兜底第三阶段就是实施。这时候把规格交给 AI让它开始实现。但注意不要让 AI 直接读 specs 就开写我会明确要求它执行 Superpowers 的测试驱动开发工作流顺序是先列出实现计划 → 针对每条验收标准写测试用例 → 写实现代码 → 跑测试确认验收标准全部通过。这里重点说一下为什么“先写测试”这件事如此重要。直接写实现代码AI 很容易陷入“自我感觉良好”的陷阱——代码写完、编译通过就觉得搞定了。但编译通过不等于需求实现测试通过才算。先写测试本质上是在逼 AI 把验收标准变成可执行的断言这样它后面写的每一行代码都是奔着“让测试通过”去的而不是奔着“写完交差”去的。实际操作中我会给 AI 一套很明确的指令模板大致长这样请完成 openspec/changes/add-batch-user-import/spec.md 中定义的功能。 要求 1. 先阅读规格文档理解全部功能规格和验收标准 2. 按照测试驱动开发流程执行先为每条验收标准编写测试用例 3. 实现功能代码确保测试通过 4. 测试全部通过后运行全量回归测试确认没有破坏其他功能 5. 完成后汇报测试结果矩阵这个指令模板本身没什么高深的关键是把它跟 OpenSpec 的规格、Superpowers 的方法论串在一起让 AI 既知道“做什么”也知道“怎么做”。4.5 验收阶段规格、测试、代码三方对齐第四阶段是验收。AI 说自己做完了你不能直接信跑一遍验证流程。OpenSpec 本身不跑测试但它提供了一种方式把验收标准和实际测试关联起来。实际操作中我让 AI 在汇报结果时把每个验收标准的测试结果整理成一张对照表验收标准测试用例测试结果ACA-001: 5001 行 CSV 返回 400test_import_rejects_over_limit通过ACA-002: 非法邮箱返回 422 且无新增test_import_rejects_invalid_email通过ACA-003: 100 行合法 CSV 导入成功test_import_success_with_100_rows通过这一步的价值在于验收不再是你和 AI 之间的“信任游戏”而是规格、测试、代码三方的客观对齐。每一条验收标准都对应一个测试用例每个测试用例都有明确的通过结果你只需要人工抽验部分关键逻辑而不是重新审查所有代码。4.6 迭代阶段变更走流程不再靠口头沟通最后是迭代阶段。需求变更是软件开发里的常态最怕的是“口头改需求”——今天 AI 对话里改一下明天新对话里 AI 不知道有这回事代码就乱了。OpenSpec 的方案是把变更也纳入流程开一个新 Change写新提案更新对应的规格和验收标准然后让 AI 按新规格实现。比如用户用了两周后提需求“批量导入时如果用户名重复不要整批失败改成跳过重复行并生成报告”。这时候我新建一个update-batch-user-import的 Change修改规格条目为“若存在用户名重复跳过重复行其他行正常导入并在报告中列出跳过的行号”同时新增验收标准 ACA-004: “CSV 中含 3 行重复用户名和 2 行正常数据导入成功 2 条、跳过 3 条报告包含跳过明细”。由于规格文档存在AI 可以精准知道旧行为和新行为的差异测试也不会漏掉旧逻辑。规格驱动最大的红利在这里显现变更可追溯、行为可预期、回归可验证。5. 常见问题与避坑清单这套打法落地时最容易翻车的几个地方任何方法论放到真实项目里都会遇到意外我把这套流程落地过程中踩过的坑和排查经验整理成一份速查表按出现频率排个序。现象根本原因解决方案AI 不读规格直接开写指令里没明确要求先读规格AI 默认走快捷路径指令模板里必须写死“先阅读 openspec/ 下对应 Change 的 spec.md再开始编码”验收标准太模糊AI 说“无法测试”规格里写了“系统要稳定”这类不可测标准重写为“当 X 发生时系统执行 Y返回 Z”的可测句式测试写完了但没覆盖验收标准让 AI “自由发挥”写测试没有逐条对应要求测试用例必须标注对应的验收标准编号ACA-XXX需求变更后 AI 保留旧逻辑直接在原对话里改需求没有更新规格文档所有变更走 OpenSpec 新 Change 流程改完规格再动代码AI 装完 Superpowers 后完全不生效Skills 目录放错了位置仔细看文档确认当前版本 Claude Code 的 skills 加载路径装完验证技能列表AI 实现过程中偏离规格但代码能跑缺少中间检查点在实施阶段要求 AI 先输出实现计划确认方案符合规格后再写代码再说几个没写进表格、但同样重要的个人经验。第一件规格别追求一次写到完美。很多人第一次接触规格驱动容易走极端想把所有东西都写全结果规格写了两天还没动代码。规格的价值是“够了就行”不是“完美才行”。我一般的原则是能把模糊的需求变成可测试的行为就够了剩下的边界条件可以在测试阶段补。规格也应该像代码一样迭代而不是一锤定音。第二件AI 的“自我验证”能力有边界。即使你要求 AI 先写测试再写实现它也有可能写出“为了通过而通过”的测试——比如测试代码本身写得不对或者断言写得太弱。所以关键的验收标准尤其是涉及金额、权限、数据一致性这类高危逻辑我仍然会人工过一遍测试代码确信断言的严格性到位。不要因为流程对了就放弃人工审查流程降低的是风险不是清零风险。第三件这套方法论有一个适用边界。像“写一个 hello world”这种小任务规格驱动纯属杀鸡用牛刀但只要是需要多轮迭代、需求会变化、失败了有成本的任务这套流程的性价比就很高。我给团队的建议是小任务直接对话式完成中等以上任务走规格驱动形成习惯后你就分得清什么任务该走哪条路。最后再分享一个很实用的技巧让 AI 在每次完成一个阶段的规格实现之后用一句话总结“这个 Change 的核心变更点和验收结论”然后把这个总结放在规格文档的末尾。这样过几周再回头看项目AI 能快速定位当时做了什么、为什么这么做你也能少花很多时间重新理解旧代码。把项目的历史演进记录下来这本身就是规格驱动模式长期收益里最容易被低估的一环。