我最早接触 AI 编程就是拿 Claude Code 直接甩需求让它帮我写接口、写页面、修 bug。前两周还挺爽后面就开始不对劲功能越堆越多代码库存越来越多但每次加需求AI 都基于一套早就不对的前提在改代码。你说不出哪里坏了但项目就是越来越不可控。那个阶段我一直在想一个问题——AI 写代码最大的问题不是写不快而是“不知道自己在往哪写”。直到我把 OpenSpec 和 Superpowers 加进来用规格驱动的方式重新组织整个 AI 编程流程项目的可控性才真正回来了。这篇文章就把我目前这套打法完整拆开讲清楚三个工具各自解决什么问题、怎么配合、有哪些坑。这篇东西适合谁看如果你已经在用 Claude Code、Codex、OpenCode 这类 AI 编程工具做真实项目但总觉得交付质量不稳定或者你听说过 OpenSpec 和 Superpowers但不知道怎么组合落地这篇文章应该能帮你省掉不少试错时间。1. 为什么“聊天式编程”会越写越乱问题出在缺少契约层先聊个扎心的现象。很多人包括一开始的我用 AI 编程是把它当成一个“超级实习生”你给它一段话它给你一段能跑的代码。单个功能看起来没问题但放在整个项目里你会发现 AI 的维护成本其实是递增的。1.1 缺乏验收标准的开发循环普通聊天式开发的循环是这样的你提出需求 → AI 猜测需求 → 生成代码 → 你肉眼检查 → 提修改意见 → AI 再改。这个循环最大的问题是AI 的“猜测”不是基于文档或规格而是基于上下文联想。比如你说“给订单列表加一个筛选状态”AI 可能猜是前端加个下拉框你说“用户登录后跳转到首页”AI 可能会在路由里硬编码一个/home完全不管你项目里实际的首页路径是什么。第一次没问题但十次、二十次之后代码里到处是“当年猜对了”的痕迹后面再让 AI 重构它会被这些历史猜测带偏改出很不自然的实现。问题的根源不是什么模型能力不行而是这个工作流里缺少一个东西契约层。人和 AI 之间没有一个明确的、可校验的“我到底要做成什么样”的中间产物。规范不明AI 就只能在概率上接近你的想法。1.2 规格驱动到底改变了什么协作关系规格驱动的思路是把“需求描述 → 代码实现”这个一步到位的操作拆成两段先描述“系统应该长什么样、什么行为可接受”再让 AI 基于这份描述去实现。这一步拆完AI 的瞎猜空间被压缩到很小。它不再需要从零推断产品意图而是在既定边界内选择实现路径。这也是OpenSpec这类工具存在的原因把规格本身做成一等公民用文件和格式来承载而不是散落在聊天记录里。Superpowers 的角色则是“流程约束”。它管的不再是结果而是 AI 怎么一步步达成结果先想清楚方案、再写计划、再测试驱动开发、最后提交。让 AI 的行为方式更像一个有经验、有纪律的程序员而不是一个“你问一句它答一句”的答题机。所以你看到的三件套本质是一次分工Claude Code提供执行力和原子能力OpenSpec提供“做什么”的契约Superpowers提供“怎么做”的纪律。这三者缺一个另外两个都会变形。没有规格Superpowers 只会让 AI 在一个错误的计划里走得特别认真没有流程纪律OpenSpec 产出的文档就是死文档代码该飘还是飘。2. OpenSpec 在管什么把需求固化成可验收的规格文件OpenSpec 不是一个重型的软件工程框架它的设计思路很朴素用一套目录结构和 Markdown 文件把“项目当前应该是什么样”和“接下来要变成什么样”沉淀下来让 AI 在任何一次会话开始之前都能快速建立对项目的“正式认知”。2.1 OpenSpec 的目录结构与工作流按我目前的实践来看一个接入了 OpenSpec 的项目通常长这样project-root/ ├── openspec/ │ ├── project.md # 项目总览描述系统的核心目标与边界 │ ├── changes/ # 存放待审阅、未应用的变更提案 │ │ ├── 2025-06-10-add-user-profile.md │ │ └── 2025-06-12-refactor-auth-flow.md │ └── specs/ # 已确认并应用的规格 │ ├── authentication.md │ └── user-profile.mdchanges/目录里放的是“变更提案”也就是你接下来想让 AI 做的事。每份提案都是一个 Markdown 文件核心内容包含变更背景、行为描述、验收标准。specs/目录放的是“已生效规格”。一个变更提案被评审通过后经过整理就会合并进 specs成为项目的一部分后续所有开发都以它为准。工作流的顺序是这样的先给 AI 看openspec/下的已有规格让它在正确的前置认知下工作然后新建或修改变更提案写清楚要做什么、做到什么程度最后让 AI 在提案约束下实现代码实现完再回到规格层确认是否真的完成。2.2 一份变更提案的书写要点很多人第一次写变更提案会犯一个通病写得像 PRD全是“用户希望”“系统需要”。但在规格驱动模式里变更提案要更接近“行为契约”。我最常用的提案结构是这样Change Description变更描述解释为什么做这件事解决什么问题Acceptance Criteria验收标准用“当……时系统应该……”句式描述具体行为Implementation Notes实现提示给 AI 的可选实施线索包括涉及模块、数据表、调用链。举一个实际例子。我在做一个内部报表系统时要加“按部门导出月度汇总”功能。验收标准部分我不是写“导出功能要正常”而是写当用户在报表页选择“部门维度”并点击“导出”时系统应生成一个 CSV 文件CSV 第一行必须包含“部门名称、月度收入、月度支出、净额”四个列如果当月无数据CSV 仍应包含表头且第二行显示“暂无数据”。这种写法AI 想发挥也很难跑偏因为它有了“对不对”的判断依据。验收标准越具体后面测试用例的生成就越轻松最终代码和需求的偏差就越小。提示验收标准不是功能清单而是可观测行为的集合。不要写“性能要好”要写“接口应在 200ms 内返回”不要写“界面要美观”要写“页面在移动端宽度小于 375px 时不应出现横向滚动条”。2.3 为什么规格层能成为“项目记忆”我在不止一个项目里发现AI 编程最大的浪费不是写代码慢而是它每次都像“失忆”一样重新理解项目。给它一个很长的项目背景它读不完不给它就瞎猜。OpenSpec 的价值恰恰是把“项目当前状态”沉淀成一个人机都能读懂的文件。当规格文件存在且被持续维护Claude Code 每次启动时只要读几个 Markdown 文件就能知道这个项目目前有哪些模块、哪些约定、哪些决策是已经定下来的。这比在聊天里反复粘贴上下文高效太多。而且规格文件的另一层价值是可追溯。每次变更提案从changes/合并到specs/都对应一次 git 提交。几个月后回看你能清楚地知道某个功能为什么存在、设计约束是什么。这种“项目记忆”以前只能靠人肉维护文档现在规格驱动把它变成了 AI 工作流中的固定环节。3. Superpowers 在管什么让 AI 拥有“工程纪律”OpenSpec 解决的是“目标定义”的问题Superpowers 解决的是“过程控制”的问题。它不是 IDE 插件也不是独立的 AI 引擎而是一套让 Claude Code 具备特定工作技能的提示词体系。3.1 Superpowers 技能集与普通提示词的本质区别你可以把 Superpowers 理解为一套“内置工程方法论”的技能包。通过一些特定指令Claude Code 会从默认的“助手模式”切换到一个更接近“资深工程师”的行为模式。Superpowers 最关键的几个技能模块按我的使用频率排一下计划制定动手写代码前先产出一份分步骤的实施计划尤其适合做全栈项目的大改动测试驱动开发坚持“先写失败测试再实现再重构”的节奏系统化调试遇到 bug 不瞎试先建立假设再验证假设代码评审完成后按文化标准审视自己的代码头脑风暴在不确定最优方案时先发散列出可能方案再收敛。这跟普通提示词最大的区别在于Superpowers 不是“你让我更像工程师我就更像工程师”的即兴表演而是一整套经过设计的指令链。它会强制 Claude Code 在特定阶段输出特定格式的内容比如先写测试、再跑测试、看到失败、才开始实现。3.2 从“先想后做”到“红绿重构”的链路我以前让 Claude Code 干活它的本能是“尽快产出代码”。给一个需求它恨不得一口气把所有文件都生成完。结果常常是逻辑看着对一跑就崩而且崩在哪一步都很难定位。Superpowers 给我最大的改变是它让 Claude Code 进入了一种类 TDD 的节奏。在“测试驱动开发”技能模式下工作链路变成明确待实现的行为这里刚好接规格文件里的验收标准先为这个行为写一个会失败的测试运行测试确认它确实失败写最少的实现代码让它通过运行全部测试确认没有破坏其他功能。这个节奏单看没什么特别但关键在于当 AI 被强制走这条路时它的“完成定义”不再是自己觉得写完了而是“测试真的通过了”。这个转变是决定性的。我之前用普通方式让 Claude Code 加一个导出接口它告诉我“写好了”我一看代码函数存在、路由也挂了但实际调接口时一直报 500因为有个数据库字段它写错了却没被任何测试捕获。切到 Superpowers 的 TDD 流程后第一步的红绿测试就会迫使它先把失败的用例暴露出来。出现的错误都是真错误而不是隐患。3.3 规格驱动和技能流程如何衔接Superpowers 和 OpenSpec 如果各干各的价值会大打折扣。真正的用法是让两者形成上下游OpenSpec 的输出变更提案、验收标准是 Superpowers 制定计划和编写测试的输入Superpowers 的执行结果实现完毕、测试全绿反过来验证 OpenSpec 的验收标准是否达成。我在实际中会让 AI 先读 OpenSpec 的变更提案再调用 Superpowers 的“计划制定”技能生成实施步骤接着进入 TDD 技能完成编码。这样 AI 的每一步都有据可依目标来自规格层节奏由技能层控制具体动作则由 Claude Code 自己完成。提示不要让 AI 跳过“阅读规格”这一步直接进入编码。哪怕你觉得这个功能很小也值得让它先读一遍相关规格。成本极低收益很稳。4. 三件套联动实战跑通一个全栈小项目理论讲再多不如把一次完整流程走一遍。这里我拿一个我最近做过的内部工具项目举例项目不大但完整经历了“新项目启动 → 需求迭代 → 中途变更”三个关键阶段正好能展示三件套的配合逻辑。4.1 场景设定与项目初始化需求背景给团队做一个简单的“周报提交与汇总”工具后端只提供接口前端是一个基础页面数据存在 SQLite 里。核心功能有三个用户提交周报、周报列表查询、按周汇总展示。项目最开始没有用 OpenSpec 和 Superpowers我就是裸 Claude Code 在写结果写到一半我自己都快忘了当初定过哪些规则比如周报字段到底叫content还是description提交时间是服务端生成还是客户端传。这类细节在会话里反复横跳严重拖慢进度。后来我把项目重建到 OpenSpec 框架下。第一件事是初始化openspec/目录写project.md把项目的核心目标、模块边界、关键约定全部写清楚。这个文件不需要很长但必须是准确的因为它是 AI 后续所有操作的“认知起点”。4.2 编写第一份变更提案接着我在openspec/changes/下新建了一份提案主题是“实现周报提交接口”。验收标准我写了四条用户提交 POST /api/reports 时请求体应包含user_name字符串和content字符串长度不超过 2000 字服务端应记录submitted_at字段值为服务器当前时间校验失败时返回 400并给出明确错误信息成功后返回 201 和生成的 report id。写完提案后我把 Claude Code 的会话指向这个文件然后调用 Superpowers 的“计划制定”技能。它在 specs 和提案的基础上给出了一个包含 5 个步骤的实施计划建表、写模型、写路由、写请求校验、补测试。然后我切到 TDD 技能模式它先根据验收标准写出了测试用例包括“正常提交”“content 超长”“缺少 user_name”三个场景。测试跑起来是失败的——这是预期的红。接着它才开始写实现代码。大概过了十几分钟全部测试转绿。这一步给我最大的体感是整个过程我没怎么对话。我不需要一遍遍解释“这个字段应该在服务端生成”因为规格已经写死了我也不需要强调“你写之前先想清楚”因为 Superpowers 已经强制它按流程走了。4.3 运行整个链路看测试如何反向验证规格第一个功能做完后我紧接着用同样的方式加了“按周汇总”接口。到这一步OpenSpec 的架构优势开始体现新提案直接引用现有 specs 里的数据表结构AI 不需要重新理解整个项目只需要关注新功能的增量变化。而且由于每次变更都留下了规格层和测试层的记录后续 Claude Code 在生成代码时会倾向于复用已有实现而不是另起炉灶。这一点对全栈项目的稳定性非常关键。4.4 中途需求变更从规格层而不是代码层入手项目做了一个多月后产品其实就是我老板提了新需求周报里要增加“本周完成事项”和“下周计划”两个字段而不是一段长文本。如果是以前的裸开发模式我大概率会直接跟 Claude Code 说“把 content 字段拆成两个字段”然后它就开始改代码改到哪儿算哪儿最后留下一堆没清理的兼容逻辑。规格驱动下我的处理方式完全不一样。我先在openspec/changes/新建一个“重构周报内容结构”的提案写明表结构变更content字段拆为completed_items和next_plans均为 TEXT 类型接口变更POST /api/reports 请求体不再接受content改为接受上述两个新字段兼容策略v1 接口保留 30 天但新项目停用。然后我把这个提案拿给 Claude Code让它基于规格先调整测试再改实现。由于验收标准够清楚AI 没有问我“那 content 还要不要兼容”“前端老数据怎么办”这类问题全部按规格执行完毕。这次经历让我彻底理解了规格驱动的意义它不是让你多写文档而是让每次变更都有明确的边界和验收方式AI 不会越界你也不会失控。5. 工具链搭建与团队协作安装配置的几个关键细节聊完工作流再说点落地的。很多同学拿到 OpenSpec 和 Superpowers 后第一步就卡在配置上。其实安装本身不复杂但有几个细节容易踩坑。5.1 基础环境的准备思路我目前的主力组合是 Claude Code OpenSpec CLI Superpowers 技能包。安装上OpenSpec 有官方命令行工具按文档装好即可Superpowers 则是通过安装脚本或手动方式把技能集放进去然后 Claude Code 在启动时会自动读取相关指令。如果你用的是 Claude CodeSuperpowers 的接入通常依赖CLAUDE.md或类似的项目级指令文件。这个文件会被 Claude Code 在每次会话启动时自动加载Superpowers 会在里面登记可用的技能目录相当于给 Claude Code 一个“工具箱清单”。配置完成后你可以做一个最简单的验证在 Claude Code 里输入一个触发 Superpowers 技能的命令词或斜杠命令看它是否按技能流程响应而不是普通对话。能触发说明技能包路径没配错。5.2 项目级与个人级的配置边界这里有个非常容易被忽略的问题Superpowers 是装在你个人环境里的但规格是项目级的。如果团队每个人都装了各自的 Superpowers 配置同一个项目的specs/却只有一份很容易出现“规格一致、流程不一”的乱象。我的习惯是项目级只放 OpenSpec 的openspec/目录和CLAUDE.md里面写明项目约定和常用命令个人级把 Superpowers 作为自己的“工作风格”配置不强制团队所有人使用同一版本。这样即使有人不用 Superpowers只用 Claude Code 和 OpenSpec他也至少能读懂规格、遵循验收标准而用了 Superpowers 的人则能获得额外的流程纪律加成。5.3 规格变更的代码评审习惯规格文件本身也是代码需要走评审。我经历过一个惨痛教训有一次我为了赶进度直接让 Claude Code 根据一份没评审过的变更提案写了大量代码结果三四天后发现提案里某个验收标准跟业务实际不符所有相关代码都要返工。后来我给自己定了一条规则**任何变更提案先在代码之外评审再让 AI 动代码。**评审时重点看验收标准是否可测试、是否覆盖了边界情况、是否与已有规格冲突。确认无误后再把提案交给 Claude Code 执行。这个过程看起来多了一步实际上省掉的是大量返工的成本。6. 踩坑记录规格漂移、技能滥用与反面案例最后这部分是我最想分享的。工具再好用错了方向照样翻车。我在三件套的实践过程中踩过不少坑有些已经解决有些还在摸索但都值得拿出来说。6.1 规格文件写得太虚AI 只能“表演式遵守”规格驱动最大的风险不是没写规格而是写了“看起来很对但本质是空话”的规格。我最开始写验收标准时很喜欢用“系统应保证数据安全”“模块划分应清晰合理”这类话。这种描述有一个共同问题无法被测试验证。AI 看到这种标准只能假装它达到了因为你根本没有一个可以运行的检查方式。后来我给自己定了一个验收标准“三不写”不写无法观测的目标如“体验更好”不写没有标准的限定量如“性能要有保障”不写依赖主观判断的描述如“结构要优雅”。每一条验收标准都要能对应到一个具体的测试用例或可观察行为。宁可啰嗦不能空洞。6.2 Superpowers 流程冗长小改动也被拖慢Superpowers 的 TDD 和计划制定流程在大功能上非常好用但不代表每个小改动都需要走完整套流程。有一次我让 Claude Code 改一个按钮文案它愣是给我写了两个测试用例、跑了三遍测试最后还生成了一份完整的变更记录。效率低不说关键是这种小改动根本不值得消耗这么多 token。后来我学会按照改动的影响范围来决定流程强度改动类型建议流程文案调整、样式微调直接修改不需要完整规格和 TDD新增接口、数据模型变更必须有 OpenSpec 变更提案作为前置契约核心模块重构、架构调整提案 计划 TDD 代码评审全流程规格驱动的目标不是把每个操作都变沉重而是该重的时候重、该轻的时候轻。6.3 团队里“只有你会用”等于没落地还有一点很现实如果这套工作流只有你一个人会用它就只能服务你一个人的项目。一旦团队协作别人不知道 OpenSpec 的目录结构代表什么也不会调用 Superpowers 技能整个流程就会出现断层。所以我现在的做法是在项目 README 里写一段“AI 协作说明”告诉团队新成员——这个项目里有openspec/目录AI 改代码前先读它涉及新功能时先提变更提案测试跑挂时不要直接让 AI 修先看是规格问题还是实现问题。让规格驱动成为团队默认的工作语言而不是某个人的个人技巧这套打法才真正有价值。回头再看我这段时间的实践最大的感受是AI 编程能力本身早就够了缺的是让这种能力稳定输出的一套“工作框架”。Claude Code 负责干活OpenSpec 负责定义“什么是对的”Superpowers 负责保证“怎么走到对”。三件套组合在一起我得到的不只是更高的代码产出率而是一种对项目走向的掌控感。如果你也在被 AI 编程的随机性折磨不妨从一份变更提案开始慢慢把规格驱动的循环建立起来。
我最早接触 AI 编程就是拿 Claude Code 直接甩需求让它帮我写接口、写页面、修 bug。前两周还挺爽后面就开始不对劲功能越堆越多代码库存越来越多但每次加需求AI 都基于一套早就不对的前提在改代码。你说不出哪里坏了但项目就是越来越不可控。那个阶段我一直在想一个问题——AI 写代码最大的问题不是写不快而是“不知道自己在往哪写”。直到我把 OpenSpec 和 Superpowers 加进来用规格驱动的方式重新组织整个 AI 编程流程项目的可控性才真正回来了。这篇文章就把我目前这套打法完整拆开讲清楚三个工具各自解决什么问题、怎么配合、有哪些坑。这篇东西适合谁看如果你已经在用 Claude Code、Codex、OpenCode 这类 AI 编程工具做真实项目但总觉得交付质量不稳定或者你听说过 OpenSpec 和 Superpowers但不知道怎么组合落地这篇文章应该能帮你省掉不少试错时间。1. 为什么“聊天式编程”会越写越乱问题出在缺少契约层先聊个扎心的现象。很多人包括一开始的我用 AI 编程是把它当成一个“超级实习生”你给它一段话它给你一段能跑的代码。单个功能看起来没问题但放在整个项目里你会发现 AI 的维护成本其实是递增的。1.1 缺乏验收标准的开发循环普通聊天式开发的循环是这样的你提出需求 → AI 猜测需求 → 生成代码 → 你肉眼检查 → 提修改意见 → AI 再改。这个循环最大的问题是AI 的“猜测”不是基于文档或规格而是基于上下文联想。比如你说“给订单列表加一个筛选状态”AI 可能猜是前端加个下拉框你说“用户登录后跳转到首页”AI 可能会在路由里硬编码一个/home完全不管你项目里实际的首页路径是什么。第一次没问题但十次、二十次之后代码里到处是“当年猜对了”的痕迹后面再让 AI 重构它会被这些历史猜测带偏改出很不自然的实现。问题的根源不是什么模型能力不行而是这个工作流里缺少一个东西契约层。人和 AI 之间没有一个明确的、可校验的“我到底要做成什么样”的中间产物。规范不明AI 就只能在概率上接近你的想法。1.2 规格驱动到底改变了什么协作关系规格驱动的思路是把“需求描述 → 代码实现”这个一步到位的操作拆成两段先描述“系统应该长什么样、什么行为可接受”再让 AI 基于这份描述去实现。这一步拆完AI 的瞎猜空间被压缩到很小。它不再需要从零推断产品意图而是在既定边界内选择实现路径。这也是OpenSpec这类工具存在的原因把规格本身做成一等公民用文件和格式来承载而不是散落在聊天记录里。Superpowers 的角色则是“流程约束”。它管的不再是结果而是 AI 怎么一步步达成结果先想清楚方案、再写计划、再测试驱动开发、最后提交。让 AI 的行为方式更像一个有经验、有纪律的程序员而不是一个“你问一句它答一句”的答题机。所以你看到的三件套本质是一次分工Claude Code提供执行力和原子能力OpenSpec提供“做什么”的契约Superpowers提供“怎么做”的纪律。这三者缺一个另外两个都会变形。没有规格Superpowers 只会让 AI 在一个错误的计划里走得特别认真没有流程纪律OpenSpec 产出的文档就是死文档代码该飘还是飘。2. OpenSpec 在管什么把需求固化成可验收的规格文件OpenSpec 不是一个重型的软件工程框架它的设计思路很朴素用一套目录结构和 Markdown 文件把“项目当前应该是什么样”和“接下来要变成什么样”沉淀下来让 AI 在任何一次会话开始之前都能快速建立对项目的“正式认知”。2.1 OpenSpec 的目录结构与工作流按我目前的实践来看一个接入了 OpenSpec 的项目通常长这样project-root/ ├── openspec/ │ ├── project.md # 项目总览描述系统的核心目标与边界 │ ├── changes/ # 存放待审阅、未应用的变更提案 │ │ ├── 2025-06-10-add-user-profile.md │ │ └── 2025-06-12-refactor-auth-flow.md │ └── specs/ # 已确认并应用的规格 │ ├── authentication.md │ └── user-profile.mdchanges/目录里放的是“变更提案”也就是你接下来想让 AI 做的事。每份提案都是一个 Markdown 文件核心内容包含变更背景、行为描述、验收标准。specs/目录放的是“已生效规格”。一个变更提案被评审通过后经过整理就会合并进 specs成为项目的一部分后续所有开发都以它为准。工作流的顺序是这样的先给 AI 看openspec/下的已有规格让它在正确的前置认知下工作然后新建或修改变更提案写清楚要做什么、做到什么程度最后让 AI 在提案约束下实现代码实现完再回到规格层确认是否真的完成。2.2 一份变更提案的书写要点很多人第一次写变更提案会犯一个通病写得像 PRD全是“用户希望”“系统需要”。但在规格驱动模式里变更提案要更接近“行为契约”。我最常用的提案结构是这样Change Description变更描述解释为什么做这件事解决什么问题Acceptance Criteria验收标准用“当……时系统应该……”句式描述具体行为Implementation Notes实现提示给 AI 的可选实施线索包括涉及模块、数据表、调用链。举一个实际例子。我在做一个内部报表系统时要加“按部门导出月度汇总”功能。验收标准部分我不是写“导出功能要正常”而是写当用户在报表页选择“部门维度”并点击“导出”时系统应生成一个 CSV 文件CSV 第一行必须包含“部门名称、月度收入、月度支出、净额”四个列如果当月无数据CSV 仍应包含表头且第二行显示“暂无数据”。这种写法AI 想发挥也很难跑偏因为它有了“对不对”的判断依据。验收标准越具体后面测试用例的生成就越轻松最终代码和需求的偏差就越小。提示验收标准不是功能清单而是可观测行为的集合。不要写“性能要好”要写“接口应在 200ms 内返回”不要写“界面要美观”要写“页面在移动端宽度小于 375px 时不应出现横向滚动条”。2.3 为什么规格层能成为“项目记忆”我在不止一个项目里发现AI 编程最大的浪费不是写代码慢而是它每次都像“失忆”一样重新理解项目。给它一个很长的项目背景它读不完不给它就瞎猜。OpenSpec 的价值恰恰是把“项目当前状态”沉淀成一个人机都能读懂的文件。当规格文件存在且被持续维护Claude Code 每次启动时只要读几个 Markdown 文件就能知道这个项目目前有哪些模块、哪些约定、哪些决策是已经定下来的。这比在聊天里反复粘贴上下文高效太多。而且规格文件的另一层价值是可追溯。每次变更提案从changes/合并到specs/都对应一次 git 提交。几个月后回看你能清楚地知道某个功能为什么存在、设计约束是什么。这种“项目记忆”以前只能靠人肉维护文档现在规格驱动把它变成了 AI 工作流中的固定环节。3. Superpowers 在管什么让 AI 拥有“工程纪律”OpenSpec 解决的是“目标定义”的问题Superpowers 解决的是“过程控制”的问题。它不是 IDE 插件也不是独立的 AI 引擎而是一套让 Claude Code 具备特定工作技能的提示词体系。3.1 Superpowers 技能集与普通提示词的本质区别你可以把 Superpowers 理解为一套“内置工程方法论”的技能包。通过一些特定指令Claude Code 会从默认的“助手模式”切换到一个更接近“资深工程师”的行为模式。Superpowers 最关键的几个技能模块按我的使用频率排一下计划制定动手写代码前先产出一份分步骤的实施计划尤其适合做全栈项目的大改动测试驱动开发坚持“先写失败测试再实现再重构”的节奏系统化调试遇到 bug 不瞎试先建立假设再验证假设代码评审完成后按文化标准审视自己的代码头脑风暴在不确定最优方案时先发散列出可能方案再收敛。这跟普通提示词最大的区别在于Superpowers 不是“你让我更像工程师我就更像工程师”的即兴表演而是一整套经过设计的指令链。它会强制 Claude Code 在特定阶段输出特定格式的内容比如先写测试、再跑测试、看到失败、才开始实现。3.2 从“先想后做”到“红绿重构”的链路我以前让 Claude Code 干活它的本能是“尽快产出代码”。给一个需求它恨不得一口气把所有文件都生成完。结果常常是逻辑看着对一跑就崩而且崩在哪一步都很难定位。Superpowers 给我最大的改变是它让 Claude Code 进入了一种类 TDD 的节奏。在“测试驱动开发”技能模式下工作链路变成明确待实现的行为这里刚好接规格文件里的验收标准先为这个行为写一个会失败的测试运行测试确认它确实失败写最少的实现代码让它通过运行全部测试确认没有破坏其他功能。这个节奏单看没什么特别但关键在于当 AI 被强制走这条路时它的“完成定义”不再是自己觉得写完了而是“测试真的通过了”。这个转变是决定性的。我之前用普通方式让 Claude Code 加一个导出接口它告诉我“写好了”我一看代码函数存在、路由也挂了但实际调接口时一直报 500因为有个数据库字段它写错了却没被任何测试捕获。切到 Superpowers 的 TDD 流程后第一步的红绿测试就会迫使它先把失败的用例暴露出来。出现的错误都是真错误而不是隐患。3.3 规格驱动和技能流程如何衔接Superpowers 和 OpenSpec 如果各干各的价值会大打折扣。真正的用法是让两者形成上下游OpenSpec 的输出变更提案、验收标准是 Superpowers 制定计划和编写测试的输入Superpowers 的执行结果实现完毕、测试全绿反过来验证 OpenSpec 的验收标准是否达成。我在实际中会让 AI 先读 OpenSpec 的变更提案再调用 Superpowers 的“计划制定”技能生成实施步骤接着进入 TDD 技能完成编码。这样 AI 的每一步都有据可依目标来自规格层节奏由技能层控制具体动作则由 Claude Code 自己完成。提示不要让 AI 跳过“阅读规格”这一步直接进入编码。哪怕你觉得这个功能很小也值得让它先读一遍相关规格。成本极低收益很稳。4. 三件套联动实战跑通一个全栈小项目理论讲再多不如把一次完整流程走一遍。这里我拿一个我最近做过的内部工具项目举例项目不大但完整经历了“新项目启动 → 需求迭代 → 中途变更”三个关键阶段正好能展示三件套的配合逻辑。4.1 场景设定与项目初始化需求背景给团队做一个简单的“周报提交与汇总”工具后端只提供接口前端是一个基础页面数据存在 SQLite 里。核心功能有三个用户提交周报、周报列表查询、按周汇总展示。项目最开始没有用 OpenSpec 和 Superpowers我就是裸 Claude Code 在写结果写到一半我自己都快忘了当初定过哪些规则比如周报字段到底叫content还是description提交时间是服务端生成还是客户端传。这类细节在会话里反复横跳严重拖慢进度。后来我把项目重建到 OpenSpec 框架下。第一件事是初始化openspec/目录写project.md把项目的核心目标、模块边界、关键约定全部写清楚。这个文件不需要很长但必须是准确的因为它是 AI 后续所有操作的“认知起点”。4.2 编写第一份变更提案接着我在openspec/changes/下新建了一份提案主题是“实现周报提交接口”。验收标准我写了四条用户提交 POST /api/reports 时请求体应包含user_name字符串和content字符串长度不超过 2000 字服务端应记录submitted_at字段值为服务器当前时间校验失败时返回 400并给出明确错误信息成功后返回 201 和生成的 report id。写完提案后我把 Claude Code 的会话指向这个文件然后调用 Superpowers 的“计划制定”技能。它在 specs 和提案的基础上给出了一个包含 5 个步骤的实施计划建表、写模型、写路由、写请求校验、补测试。然后我切到 TDD 技能模式它先根据验收标准写出了测试用例包括“正常提交”“content 超长”“缺少 user_name”三个场景。测试跑起来是失败的——这是预期的红。接着它才开始写实现代码。大概过了十几分钟全部测试转绿。这一步给我最大的体感是整个过程我没怎么对话。我不需要一遍遍解释“这个字段应该在服务端生成”因为规格已经写死了我也不需要强调“你写之前先想清楚”因为 Superpowers 已经强制它按流程走了。4.3 运行整个链路看测试如何反向验证规格第一个功能做完后我紧接着用同样的方式加了“按周汇总”接口。到这一步OpenSpec 的架构优势开始体现新提案直接引用现有 specs 里的数据表结构AI 不需要重新理解整个项目只需要关注新功能的增量变化。而且由于每次变更都留下了规格层和测试层的记录后续 Claude Code 在生成代码时会倾向于复用已有实现而不是另起炉灶。这一点对全栈项目的稳定性非常关键。4.4 中途需求变更从规格层而不是代码层入手项目做了一个多月后产品其实就是我老板提了新需求周报里要增加“本周完成事项”和“下周计划”两个字段而不是一段长文本。如果是以前的裸开发模式我大概率会直接跟 Claude Code 说“把 content 字段拆成两个字段”然后它就开始改代码改到哪儿算哪儿最后留下一堆没清理的兼容逻辑。规格驱动下我的处理方式完全不一样。我先在openspec/changes/新建一个“重构周报内容结构”的提案写明表结构变更content字段拆为completed_items和next_plans均为 TEXT 类型接口变更POST /api/reports 请求体不再接受content改为接受上述两个新字段兼容策略v1 接口保留 30 天但新项目停用。然后我把这个提案拿给 Claude Code让它基于规格先调整测试再改实现。由于验收标准够清楚AI 没有问我“那 content 还要不要兼容”“前端老数据怎么办”这类问题全部按规格执行完毕。这次经历让我彻底理解了规格驱动的意义它不是让你多写文档而是让每次变更都有明确的边界和验收方式AI 不会越界你也不会失控。5. 工具链搭建与团队协作安装配置的几个关键细节聊完工作流再说点落地的。很多同学拿到 OpenSpec 和 Superpowers 后第一步就卡在配置上。其实安装本身不复杂但有几个细节容易踩坑。5.1 基础环境的准备思路我目前的主力组合是 Claude Code OpenSpec CLI Superpowers 技能包。安装上OpenSpec 有官方命令行工具按文档装好即可Superpowers 则是通过安装脚本或手动方式把技能集放进去然后 Claude Code 在启动时会自动读取相关指令。如果你用的是 Claude CodeSuperpowers 的接入通常依赖CLAUDE.md或类似的项目级指令文件。这个文件会被 Claude Code 在每次会话启动时自动加载Superpowers 会在里面登记可用的技能目录相当于给 Claude Code 一个“工具箱清单”。配置完成后你可以做一个最简单的验证在 Claude Code 里输入一个触发 Superpowers 技能的命令词或斜杠命令看它是否按技能流程响应而不是普通对话。能触发说明技能包路径没配错。5.2 项目级与个人级的配置边界这里有个非常容易被忽略的问题Superpowers 是装在你个人环境里的但规格是项目级的。如果团队每个人都装了各自的 Superpowers 配置同一个项目的specs/却只有一份很容易出现“规格一致、流程不一”的乱象。我的习惯是项目级只放 OpenSpec 的openspec/目录和CLAUDE.md里面写明项目约定和常用命令个人级把 Superpowers 作为自己的“工作风格”配置不强制团队所有人使用同一版本。这样即使有人不用 Superpowers只用 Claude Code 和 OpenSpec他也至少能读懂规格、遵循验收标准而用了 Superpowers 的人则能获得额外的流程纪律加成。5.3 规格变更的代码评审习惯规格文件本身也是代码需要走评审。我经历过一个惨痛教训有一次我为了赶进度直接让 Claude Code 根据一份没评审过的变更提案写了大量代码结果三四天后发现提案里某个验收标准跟业务实际不符所有相关代码都要返工。后来我给自己定了一条规则**任何变更提案先在代码之外评审再让 AI 动代码。**评审时重点看验收标准是否可测试、是否覆盖了边界情况、是否与已有规格冲突。确认无误后再把提案交给 Claude Code 执行。这个过程看起来多了一步实际上省掉的是大量返工的成本。6. 踩坑记录规格漂移、技能滥用与反面案例最后这部分是我最想分享的。工具再好用错了方向照样翻车。我在三件套的实践过程中踩过不少坑有些已经解决有些还在摸索但都值得拿出来说。6.1 规格文件写得太虚AI 只能“表演式遵守”规格驱动最大的风险不是没写规格而是写了“看起来很对但本质是空话”的规格。我最开始写验收标准时很喜欢用“系统应保证数据安全”“模块划分应清晰合理”这类话。这种描述有一个共同问题无法被测试验证。AI 看到这种标准只能假装它达到了因为你根本没有一个可以运行的检查方式。后来我给自己定了一个验收标准“三不写”不写无法观测的目标如“体验更好”不写没有标准的限定量如“性能要有保障”不写依赖主观判断的描述如“结构要优雅”。每一条验收标准都要能对应到一个具体的测试用例或可观察行为。宁可啰嗦不能空洞。6.2 Superpowers 流程冗长小改动也被拖慢Superpowers 的 TDD 和计划制定流程在大功能上非常好用但不代表每个小改动都需要走完整套流程。有一次我让 Claude Code 改一个按钮文案它愣是给我写了两个测试用例、跑了三遍测试最后还生成了一份完整的变更记录。效率低不说关键是这种小改动根本不值得消耗这么多 token。后来我学会按照改动的影响范围来决定流程强度改动类型建议流程文案调整、样式微调直接修改不需要完整规格和 TDD新增接口、数据模型变更必须有 OpenSpec 变更提案作为前置契约核心模块重构、架构调整提案 计划 TDD 代码评审全流程规格驱动的目标不是把每个操作都变沉重而是该重的时候重、该轻的时候轻。6.3 团队里“只有你会用”等于没落地还有一点很现实如果这套工作流只有你一个人会用它就只能服务你一个人的项目。一旦团队协作别人不知道 OpenSpec 的目录结构代表什么也不会调用 Superpowers 技能整个流程就会出现断层。所以我现在的做法是在项目 README 里写一段“AI 协作说明”告诉团队新成员——这个项目里有openspec/目录AI 改代码前先读它涉及新功能时先提变更提案测试跑挂时不要直接让 AI 修先看是规格问题还是实现问题。让规格驱动成为团队默认的工作语言而不是某个人的个人技巧这套打法才真正有价值。回头再看我这段时间的实践最大的感受是AI 编程能力本身早就够了缺的是让这种能力稳定输出的一套“工作框架”。Claude Code 负责干活OpenSpec 负责定义“什么是对的”Superpowers 负责保证“怎么走到对”。三件套组合在一起我得到的不只是更高的代码产出率而是一种对项目走向的掌控感。如果你也在被 AI 编程的随机性折磨不妨从一份变更提案开始慢慢把规格驱动的循环建立起来。
