我一直觉得，AI 编程最大的问题不是模型不够聪明，而是需求与实现之间的损耗太大了。你让 Claude 写一个功能，它写出来的东西跟你脑子里想的，往往是两回事。改来改去折腾半天，最后代码变成一坨谁都不敢动的线团。直到我把 OpenSpec 和 Superpowers 这两套工具叠进 Claude Code 的工作流里，用规格驱动的方式重新组织整个开发过程，这种情况才彻底改变。
这篇文章我不打算讲概念，就直接分享我现在怎么搭这套组合拳：OpenSpec 负责把需求变成机器可读、可评审的规格文档，Superpowers 负责给 Claude Code 装上专业开发工作流（TDD、分支管理、提交规范、生成测试数据等等）。两者一配合，AI 就能从"盲猜需求"变成"按图施工"。这篇内容适合已经被 AI 编程吊过胃口、也踩过坑，想让 AI 稳定交付完整项目的朋友。
1. 为什么"提示词驱动"撑不起全栈项目，规格驱动才行
先说一个真实场景。我之前让 Claude 帮我做一个带用户登录、文件上传、后台管理三个模块的全栈小系统。我自认为提示词写得足够详细了，功能列表、页面结构、接口风格全写清楚了。结果呢？它前 20 分钟写出来的东西确实像模像样，但越往后越不对劲：登录逻辑和用户表对不上，文件上传接口返回的字段跟文档里不一致，后台管理页面干脆用了另一套组件风格。我每发现一个问题就追加一句提示词，它修完 A 又弄坏 B。整个下午就在这种"打地鼠"里浪费掉了。
这个问题的根源不在模型能力，而在工作方式。对话式提示词天然是线性的、模糊的、易遗忘的。你很难在 50 轮对话里保持需求的一致性，更别说让模型理解"这个接口设计是为了配合另一个模块"这种隐性约束。上下文窗口再大，也扛不住需求本身的复杂度。
规格驱动做的事情很简单：把需求从"对话"里拿出来，变成一份独立的、结构化的、可被随时重新读取的文档。听起来好像只是"把需求写下来"，但实际效果完全不同。
我拿装修做个类比。提示词驱动等于你站在工地现场跟工人说"这里要个柜子、那里要个台面"，工人听一步做一步，做错了你再吼一嗓子。规格驱动等于你先找设计师出一整套施工图，每个房间多高、插座在哪、用什么材料全部画清楚，工人照着图纸施工，做完一项勾掉一项。前者依赖沟通双方的临场默契，后者把质量控制在流程里。
具体到 OpenSpec 这个工具，它把规格拆成一份份 Change Proposal（变更提案），每份提案只解决一个明确的问题。提案里有变更动机、具体改动范围、影响边界、验收场景。这些内容全部是 YAML 和 Markdown 结构化格式，AI 可以精确读取，不会像读对话历史那样"猜重点"。
而且规格驱动还有一个特别容易被忽略的好处：可评审、可回溯。你可以在让 AI 动手之前先审一遍规格，发现方向错了直接改文档，成本几乎为零。如果让 AI 直接写代码，发现方向错了，那改动成本高一个数量级。
所以我的结论很直接：如果你的项目只有一个文件、几百行代码，怎么驱动都无所谓；但只要是 "全栈""多模块""多步骤" 的项目，规格驱动几乎是唯一能让 AI 稳定交付的方式。
2. OpenSpec：把模糊需求变成机器可读的施工图
OpenSpec 不是让 AI 更聪明的咒语，它是一套需求格式化和流程管理工具。它通过命令行告诉你：先创建一个 proposal（提案），然后拆分任务，再一步步追踪实现进度。理解这一点非常重要，因为很多人以为装个工具就能让 AI 写出更好的代码——不是的，工具改变的是你组织需求的方式。
2.1 核心工作流：提案 -> 任务 -> 实现
OpenSpec 的官方命令我用几个核心的举例：
# 创建一个新的变更提案 openspec proposal create "add-user-authentication" # 查看当前所有提案状态 openspec proposal list # 将一个提案拆解为具体任务 openspec task create # 将已完成的变更提案标记为已实现 openspec proposal implement实际用下来，最核心的流程就是三步循环：
- 写提案（Proposal）：用自然语言描述你要做什么、为什么做、涉及哪些模块。OpenSpec 会生成一个标准化的文档骨架。
- 拆任务（Task）：OpenSpec 会把一份提案自动拆成多个明确的小任务，每个任务都可以独立交给 AI 执行。
- 实现并验证（Implement）：让 Claude Code 在 Superpowers 的 TDD skill 驱动下逐项实现，每完成一个任务回填状态。
这套流程的价值不在命令本身，而在于它强迫你在写代码之前先把"做什么"和"怎么做"分离开。人脑很容易把这两个问题混在一起，AI 更是如此。OpenSpec 用流程把这个模糊地带卡死了。
2.2 Change Proposal 的结构长什么样
我用一个实际例子来展示一份提案的核心结构（简化版）：
id: "add-user-authentication" title: "Add user authentication" status: "active" summary: | Add email/password authentication for all API endpoints. motivation: | Currently any API request is unauthenticated. We need identity verification before exposing paid features. change: - "Add User model and auth-related database migration" - "Add POST /api/auth/register endpoint" - "Add POST /api/auth/login endpoint returning JWT" - "Add auth middleware to protect all /api/private/* routes" impact: - "All frontend requests to protected routes must carry Authorization header" - "Database requires new users table" boundary: - "Password reset is out of scope" - "Third-party SSO login is out of scope" scenarios: - id: register_success desc: "User submits valid email and password" steps: - "POST /api/auth/register" - "with { email: 'test@example.com', password: 'secret123' }" expect: - "Response code 201" - "Response contains new user id" - id: login_wrong_password desc: "User submits incorrect password" steps: - "POST /api/auth/login" - "with { email: 'test@example.com', password: 'wrong' }" expect: - "Response code 401"这个格式最大的特点是：每一项都精确到可以验收。动机（motivation）告诉 AI 为什么要做，变更列表（change）告诉 AI 要做什么，范围（boundary）告诉 AI 什么不要做，场景（scenarios）告诉 AI 怎么验证做对了。
我把这四块分别类比成：为什么出发、往哪走、哪里不去、怎么知道到了。凡是这四块含糊的，AI 一定会自由发挥；凡是这四块写清楚的，AI 的自由发挥空间就被压缩到合理范围内。
2.3 写规格的三个关键技巧
技巧一：boundary 比 change 更重要。AI 默认会把需求往"做更多"的方向发挥。你如果不限定"邮件验证不做""多因素认证不做""用户角色不区分"，它可能顺手给你加上一堆你根本不需要的东西。边界写得越狠，实现越可控。
技巧二：scenarios 要写足，写细。这是 OpenSpec 里最容易被忽略、但价值最高的部分。一个合格的场景要包含"输入什么、做什么操作、期望什么结果"三个要素。这不仅是给 AI 看的验收标准，也是你后续做回归测试的素材。
技巧三：一份提案只做一件事。我见过有人把"用户认证 + 文件上传 + 支付回调"塞进一份提案里。OpenSpec 本身不限制，但 AI 执行时会混乱——它不知道该先做哪个，任务拆分也会互相纠缠。拆得足够细，每个提案控制在 200 行以内的规格描述，AI 的执行准确率会明显上升。
3. Superpowers：给 Claude Code 装上专业开发的工作套路
规格驱动解决了"做什么"的问题，但"怎么做"依然是个坑。Claude Code 本身是通用对话型编程助手，你让它"写一个用户登录功能"，它知道怎么写，但它不一定知道要先写测试、再写实现、再重构。如果没有流程约束，它会把所有代码一次性糊上来，然后你慢慢调试。
Superpowers 解决的就是这个问题。它本质上是一组 skills（技能包），由开源社区维护，专门给 Claude Code 等 AI 编程工具注入软件工程的最佳实践。
3.1 Superpowers 是什么，怎么装进 Claude Code
Superpowers 的官方在 GitHub 上维护，核心内容包括一整套按软件开发流程组织的 skills 目录，涵盖分析需求、写 TDD 测试、分步实现、代码审查、提交规范化、生成练手数据等环节。
安装我这里给两种方式：
方式一：通过 Claude Code 插件市场安装
/plugin marketplace add workswarm/claude-flow /plugin install superpowers@workswarm装完之后在 Claude Code 里输入/plugin能看到已安装的 skills 列表。
方式二：手动 clone 仓库放到指定目录
git clone https://github.com/workswarm/superpowers.git ~/.claude/skills然后把skills目录下的子文件夹（每个子文件夹按 Cloude 约定命名SKILL.md）放到 Claude Code 能扫描到的位置。命名约定很关键：文件夹名字就是触发词，比如test-driven-development这个 skill 就叫 TDD，commit这个 skill 用于生成规范提交信息。
3.2 几个我用下来价值最高的 skill
TDD（test-driven-development）
这是 Superpowers 里含金量最高的技能。它对 Claude 的约束是：写任何功能前，先写一个失败的测试，确认测试确实失败（RED），再写实现让它通过（GREEN），最后做重构（REFACTOR）。
没有 TDD skill 时，Claude 写代码是"先写一堆实现，然后我跑一下，报错再改"。有 TDD skill 时，它每实现一小步就自动跑测试，确认没有 break 已有功能才继续下一步。这个差异在项目中期开始指数级显现：测试越多，AI 后续改动越安全。
create-branch
这个 skill 要求 Claude 在开始做任何功能前先建一个独立分支，而不是直接在主干上改。听起来很基础，但 AI 默认不会这么做。没有分支隔离，AI 改到一半你发现方案不行想回滚，只能靠 Ctrl+Z 碰运气。有分支之后想退就退，成本极低。
commit
这个 skill 让 Claude 在完成一个阶段后生成符合 Conventional Commits 规范的提交信息。它不只是格式化消息，还会去读取 git diff、结合当前任务上下文，写出"这个人到底改了什么、为什么改"的提交说明。对多人协作或自己一周后回看代码，这个体验提升非常大。
generate-logs / generate-data
这两个是我后来才发现的宝藏。generate-logs 能在开发环境生成模拟日志数据，generate-data 能生成仿真测试数据。别小看这个，没有数据，AI 写的列表页和图表在你本地跑起来永远是空荡荡的，你根本没法判断页面是不是真的没写错。
3.3 Superpowers 的核心价值：把"套路"变成"技能"
我琢磨了很久为什么 Superpowers 管用，最后想明白一个词：套路。
人有套路，资深工程师拿到需求后不会直接写代码，而是先设计、再拆解、再写测试、再实现、再重构、再提交。这套流程是多年经验内化成的肌肉记忆。AI 没有肌肉记忆，它只会根据提示词做出最直接的反应。你想让它按工程师的套路走，就必须把套路显式地喂给它。
Superpowers 就是把这些工程师套路做成了 AI 能执行的标准化技能包。它不教 AI 怎么写某个函数，而是教 AI 用什么样的工作流程写出可靠代码。这正是和 OpenSpec 互补的地方：OpenSpec 控制需求的边界，Superpowers 控制实现的过程。
4. 三件套合体实战：一个全栈项目从需求到落地的完整链条
纸上谈兵到此为止，我拿一个实际跑过的项目讲讲完整链路。这个项目是一个团队任务管理系统，包含用户认证、任务 CRUD、任务状态流转、简单的操作日志。规模不大，但足够展示三件套怎么配合。
4.1 第一步：用 OpenSpec 定义两张"施工图"
我先创建两份提案：
openspec proposal create "user-auth-and-profile" openspec proposal create "task-crud-with-status-workflow"然后分别填充规格。我不追求一次把规格写完美，但motivation、change、boundary、scenarios 四块一定会写完整。比如第一份提案的 boundary 我明确写了"不做邮箱验证、不做找回密码、不做第三方登录"；第二份的 boundary 写了"不做子任务、不看板视图、不做任务评论"。
这些边界一开始就把"未来可能想要"和"这次要做"切开。等 AI 提"是否需要支持子任务"这类问题时，直接拿规格回它："不在本次范围。"
4.2 第二步：用 Superpowers 约束实现过程
接下来打开 Claude Code，让它加载 Superpowers 技能。我在对话里先给出明确指令：
先加载 test-driven-development skill，按 TDD 流程实现 OpenSpec 中 proposal id 为 user-auth-and-profile 的任务。每个任务完成后用 create-branch 建独立分支，提交信息用 commit skill 生成。注意几个关键点：
- 必须显式指名要用哪个 skill。Superpowers 装好后，Claude 不一定每次都会自动调用，尤其是多个 skill 存在时，你不点名它就挑一个"最像"的用。我实测下来，明确指名的执行效果远好于让它自己选。
- 必须把OpenSpec 的提案路径告诉它。我一般直接说 "读取 openspec/proposals/user-auth-and-profile/ 下的全部文件"，确保它加载的是结构化规格，而不是我对话里的转述。这步非常关键——一旦你口头转述，信息就开始失真，规格文档的意义就没了。
4.3 第三步：观察它怎么按规格施工
在实现"任务状态流转"时，我看到了这套组合拳最理想的状态。
Claude 先读取提案，了解到状态流转包含todo -> in_progress -> done三条路径，并且我指定了边界条件：blocked状态这次不做。然后 TDD skill 介入，它先写了一个针对状态合法流转的函数测试，用todo -> in_progress -> done的正向用例和done -> todo的非法流转反向用例。测试跑完确认红线存在，它才开始写实现。实现完成后，又把所有存量测试跑了一遍，确认没有破坏认证模块的接口。
整个过程它没有问我"状态流转要不要考虑驳回逻辑"，因为规格里写了"不允许从 done 回退到 todo"。这正是规格驱动的意义——AI 不需要猜，我也不需要解释。
4.4 第四步：验证落地结果
项目完成后我做了一件事：直接执行 OpenSpec 里的验收场景。
openspec proposal implement user-auth-and-profile它会遍历该提案下的场景，逐个检查是否满足预期。比如register_success场景要求注册接口返回 201 和用户 id，我手动 curl 了一下接口，确认符合。再比如login_wrong_password场景要求返回 401，也符合。
到这里，这个功能才真正算"交付完成"。规格里写的每一个字，都变成了可验证的承诺。
4.5 这条链路的意外收益：上下文管理
我还有一个额外发现：这套流程实际上缓解了 Claude Code 的上下文压力。
以前让 AI 做一个复杂项目，聊到第 30 轮之后它就开始忘事——忘了最初的表结构、忘了某个接口的字段命名、忘了业务规则。有了 OpenSpec 规格文档之后，我随时可以发一句："重新读取 openspec/proposals/task-crud-with-status-workflow/，确认你现在实现的是不是这个规格。"它就立刻回到正轨。规格文档变成了 AI 的长期记忆，不需要依赖对话历史。
这就像给 AI 配了一本可以随时翻的笔记本，而 OpenSpec 就是那个笔记本。对话轮次再多，它都能翻回去看原始需求。
5. 踩坑记录：这套组合拳最常翻车的 5 个地方
任何工具都有脾气。我用了小半年，踩了不少坑，挑 5 个最典型的讲讲，帮后来人省点时间。
5.1 坑一：规格文件写得太"理想"，实现时 AI 直接卡死
我一开始写规格特别详细，场景写了一大堆，每个场景都描得天花乱坠。结果 Claude 在实现时经常会陷入"过度实现"的状态——它想把规格里的每个字都变成代码，甚至包括那些根本无法通过函数实现的内容。
后来我学到一个原则：规格文档描述"要什么"，不描述"怎么做"。比如我原来会写"系统应采用 bcrypt 算法对密码进行加盐哈希"，这实际上是实现细节，留给 Claude 去决策反而更好。我改成"密码必须安全存储，不能以明文形式进数据库"，AI 自己会选方案。
5.2 坑二：一份提案拆出太多任务，AI 执行顺序错乱
OpenSpec 自动拆任务的能力确实有，但如果你一份提案里的 change 列表超过 8 条，AI 执行时容易出现依赖顺序问题——它可能先实现了需要另一个任务前置完成的改动，结果编译不过。
我的做法是严格控制提案粒度。一个提案的 change 不超过 5 条，超过就拆成多个提案。比如"任务系统"我拆成了"认证"和"CRUD"两个提案，各自独立，互不依赖。这样一来，任何一个提案内的任务顺序都比较线性，AI 不容易跳步。
5.3 坑三：多个 Superpowers skill 互相干扰
这是我踩得最深的一个坑。Superpowers 装好后有很多 skill，Claude 在某些情况下会同时触发多个。比如它可能在执行test-driven-development时又顺手触发了generate-logs，结果生成了一堆假数据塞到项目里。
解决方案是我在每次任务开始前明确限制：
只使用 test-driven-development 和 create-branch 这两个 skill，其他 skill 除非我要求，不要主动触发。给 AI 划完这个边界之后，它的"技能乱入"情况基本消失了。
5.4 坑四：规格和代码脱节了没人发现
OpenSpec 管得好好的，但如果你中途手动改了很多代码而没更新规格，一段时间后规格就变成了"历史文档"，和实际代码完全是两回事。AI 重新加载规格后按旧规格实现，反而会改坏你已经改好的代码。
我现在给自己定了个规矩：任何手动修改代码后，必须同步修改对应提案的 change 或 scenarios。如果是一次比较大的临时改动，我会直接新建一个 update 类型的提案来记录偏差。这样规格永远是"活在当下的文档"，AI 读取它做出来的东西才不会跑偏。
5.5 坑五：过度依赖规格，忽略了对话的实时反馈
规格驱动不等于"完全交给规格，不闻不问"。有些问题确实需要实时沟通才能解决，比如 UI 细节、用户交互方式、某些业务异常的处理策略。如果这些也非要写进规格，效率反而低。
我的用法是：架构和核心业务规则走规格，界面细节和交互体验走对话即时确认。两条线并行，既保证了大方向不偏，又不至于被流程拖死。
6. 这套打法能复制到哪些场景，以及最小起步建议
最后聊聊适用性和落地路径。
6.1 什么场景值得上规格驱动
我用下来，下面三类场景收益最大：
- 从零搭建的中大型项目：模块多、依赖复杂，规格驱动能让 AI 按顺序施工，避免到处挖坑。
- 多人协作的 AI 辅助开发：规格文档本身就是团队沟通的载体，你不需要口头解释需求，直接把提案甩给同事和 AI 看就行。
- 需要长期迭代的产品：每次新功能都变成一份新提案，产品演进历史一目了然。三个月后回看，你能清楚知道每个功能当初为什么做、边界在哪。
反过来，如果你只是写个一次性脚本、做个原型验证、或者代码总量在几百行以内，规格驱动纯属增加负担。这种情况直接对话式提示词反而最高效。
6.2 最小起步组合建议
如果你现在还在用"纯对话式提示词"跟 AI 合作，不建议一上来就全套上。这个组合的学习曲线还是有一点陡的，一次性引入容易顾此失彼。
我建议按这个顺序逐步加码：
第一阶段（入门）：先只用 OpenSpec。把需求写成结构化提案，让 Claude 按提案实现。你会发现同一段需求，用提案格式写清楚之后，AI 的输出质量明显高一个档次。这一步先跑通，建立"先写规格再写代码"的肌肉记忆。
第二阶段（进阶）：引入 Superpowers，至少先加test-driven-development和commit这两个 skill。TDD 会显著提高代码质量，commit 会规范你的提交记录。这一阶段你会感受到"AI 不只写代码，还在做工程"。
第三阶段（完整）：把create-branch、generate-logs、generate-data加进来，再配合 OpenSpec 的场景验收，形成完整闭环。走到这一步，你的 AI 协作体验会和提示词时代完全是两个世界。
我个人感受最深的一点是：AI 编程工具能力越强，越需要更好的流程来约束它。就像给一个力气很大但方向感很差的助手配上图纸和施工规范——图纸约束方向，规范约束动作，最后产出的东西才真正可靠。OpenSpec 是图纸，Superpowers 是规范，Claude Code 是那个力气很大的助手。
这三样东西单独拎出来都只是工具，但组合起来，就是我目前能找到的最接近"让 AI 稳定交付全栈项目"的完整打法。希望这份经验对你有用，也欢迎在实践中多踩踩坑，踩完了你会发现——这些坑恰恰是最好的老师。
