我一直觉得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 会生成一个标准化的文档骨架。拆任务TaskOpenSpec 会把一份提案自动拆成多个明确的小任务每个任务都可以独立交给 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: testexample.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: testexample.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 CodeSuperpowers 的官方在 GitHub 上维护核心内容包括一整套按软件开发流程组织的 skills 目录涵盖分析需求、写 TDD 测试、分步实现、代码审查、提交规范化、生成练手数据等环节。安装我这里给两种方式方式一通过 Claude Code 插件市场安装/plugin marketplace add workswarm/claude-flow /plugin install superpowersworkswarm装完之后在 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 就叫 TDDcommit这个 skill 用于生成规范提交信息。3.2 几个我用下来价值最高的 skillTDDtest-driven-development这是 Superpowers 里含金量最高的技能。它对 Claude 的约束是写任何功能前先写一个失败的测试确认测试确实失败RED再写实现让它通过GREEN最后做重构REFACTOR。没有 TDD skill 时Claude 写代码是先写一堆实现然后我跑一下报错再改。有 TDD skill 时它每实现一小步就自动跑测试确认没有 break 已有功能才继续下一步。这个差异在项目中期开始指数级显现测试越多AI 后续改动越安全。create-branch这个 skill 要求 Claude 在开始做任何功能前先建一个独立分支而不是直接在主干上改。听起来很基础但 AI 默认不会这么做。没有分支隔离AI 改到一半你发现方案不行想回滚只能靠 CtrlZ 碰运气。有分支之后想退就退成本极低。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 装好后有很多 skillClaude 在某些情况下会同时触发多个。比如它可能在执行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 稳定交付全栈项目的完整打法。希望这份经验对你有用也欢迎在实践中多踩踩坑踩完了你会发现——这些坑恰恰是最好的老师。