Claude Code、OpenSpec、Superpowers三件套：刚需还是过度工程？

一句话总览：Claude Code负责“写”，OpenSpec负责“想清楚再写”，Superpowers负责“写得守规矩”——三件套各补一个坑：需求跑偏、跳过测试、决策归档丢失。但它们不是越多越好，30分钟的小脚本套全套就是过度工程。这篇讲清三者分别解决什么、怎么装起来跑通一条完整流水线，以及按任务工时该上几件，帮你既不裸奔也不过度。

用Claude Code写代码爽快，但用久了三种糟心事会反复出现：你心里想的功能和它交付的不是一回事；它图快直接写实现、跳过了测试；还有最隐蔽的——这次会话里讨论出的技术决策，关掉窗口就蒸发了，下次它读不到，又把同样的弯路走一遍。

OpenSpec和Superpowers这两个开源框架，正是冲着这三个坑来的。配上Claude Code，业内有人把这套组合叫“三件套”。带客户做独立站后端时实测下来的结论很明确：它确实能把AI编程的稳定性拉上一个台阶，可它也绝不是无脑全上——用错场景，三件套带来的流程开销比它省的还多。先把每件干什么讲透，再谈什么时候该上。

Claude Code、OpenSpec、Superpowers各自在补哪个坑？

三个工具对应三个具体的痛点，一一对上就好记：

• 坑一：AI做出来的不是你要的。根源是需求理解有偏差，你一句话带过的地方，它自行脑补。OpenSpec用一层规格文档把需求先对齐，治的是这个。
• 坑二：跳过测试直接写代码。根源是缺工程纪律，赶进度时测试是第一个被牺牲的。Superpowers用强制的TDD和代码审查纪律，治的是这个。
• 坑三：决策依据关掉聊天就没了。根源是没有版本化归档，这次为什么这么设计、否决了哪些方案，下次无从查起。OpenSpec的归档机制治的是这个。

这三个坑听着抽象，其实每个都在真实项目里反复咬人。坑一最常见的形态是：你说“做个登录”，它给你做了个只有用户名密码、没有任何限流和锁定的登录，因为你没说、它也没问。坑二的形态是：功能跑通了，你一问“测试呢”，它才回头补几个走过场的断言。坑三最让人崩溃——上周你们刚讨论清楚“为什么不用第三方登录”，这周它又自作主张接了个OAuth，因为那段对话的上下文早就不在了。三个坑单独看都不致命，叠在一起就是AI编程“看着很快、其实在原地打转”的根因。

看出来了吗？Claude Code本身是那个“执行者”，干活快但没约束；OpenSpec在它前面加了“规划层”，Superpowers在它身上加了“纪律层”。三层叠起来，才凑成“想清楚→守规矩地写→把决策存下来”的完整闭环。这不是堆工具，而是把人类团队里“产品对需求、架构定方案、测试卡质量、文档留决策”那套协作纪律，搬到了一个人带AI的场景里。

OpenSpec、Superpowers到底是什么？

OpenSpec是Fission AI团队做的开源框架，核心是规格驱动开发（Spec-Driven Development）。它把你的需求转化成几份结构化文档——提案（proposal.md）、规格（specs/）、设计（design.md）和任务清单（tasks.md），让人和AI在动手前就把“要做什么、做成什么样”白纸黑字定下来。它不绑定Claude，号称支持二十多种编程助手。

Superpowers则是Jesse Vincent（隶属Prime Radiant）做的开源技能框架，2025年10月发布后增长惊人——很多教程里写的“14万星”其实是旧数据，截至2026年中它已经冲到21万星以上，是当年最火的开源项目之一。它给Claude Code灌进一套工程纪律技能：测试驱动开发、代码审查、系统化调试、头脑风暴、并行子代理等等，许可证是宽松的MIT，商用无负担。

多说一句OpenSpec那四份文档的分工，因为这是它整套价值的地基。proposal.md是“为什么做、做什么”的提案；specs/目录里是“做成什么样才算对”的行为规格，用接近“在什么条件下、发生什么、得到什么结果”的方式写，刻意不碰实现细节；design.md记的是技术方案和关键决策——为什么选这个库、否决了哪种架构；tasks.md则是拆好的、可勾选的任务清单。四份各司其职，把一个模糊的需求层层落实成可执行、可验收、可追溯的东西。它还有意把单份规格控制在两三百行以内，就是怕内容太长AI读着读着丢了上下文。

一句话区分：OpenSpec管“规格和归档”，是流程的骨架；Superpowers管“写代码时的职业素养”，是执行的肌肉。两者职能有重叠（都关心质量），但侧重不同，后面会讲为什么缺一个就断链。值得一提的是，这俩都不是Anthropic官方出品，而是社区里长出来的开源框架——Superpowers能在半年里冲到二十多万星，本身就说明“给AI编程套一层工程纪律”是真痛点，不是少数人的洁癖。

从机制上看，Superpowers本质就是一大包精心调教过的Skill——它没发明新东西，而是把TDD、代码审查、系统化调试这些工程实践，封装成Claude Code原生支持的技能包，靠描述自动命中、按需加载。所以你要是已经搞懂了Claude Code的扩展机制，理解它就很快。反过来，要是对Skill、MCP、Hook这几样还没分清，建议先补一下MCP、Skills、Hooks的区别，再来看这套三件套会顺很多——你会发现OpenSpec多半通过MCP接入、Superpowers跑在Skills上、而“强制TDD”这种硬约束最终还得靠Hook兜底，三件套其实是建立在那三大扩展机制之上的一层应用。

三件套怎么装起来才能跑通？

安装本身不复杂，关键是别抄错命令。三步走：

第一步，装Claude Code（前提是你有Claude的付费订阅）：

# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# 验证
claude --version

第二步，全局装OpenSpec并在项目里初始化（需要Node.js 20.19或更高）：

npm install -g @fission-ai/openspec@latest

cd your-project
openspec init

第三步，在Claude Code里装Superpowers插件：

claude
> /plugin install superpowers@claude-plugins-official

openspec init会在项目里铺好规格目录的骨架，并把一套/opsx:开头的斜杠命令注册进来。常用的就那么几条，对应规格生命周期的四个阶段：/opsx:explore先调研和发散问题，/opsx:propose把想法变成那四份规格文档，/opsx:apply按规格逐个任务实施，/opsx:archive把完成的变更合并归档；中间还能用/opsx:verify核对完成情况。记住这条主线——探索、提案、实施、验证、归档，整套流程的命令就齐了，剩下的continue、bulk-archive之类都是辅助。

如果想让Claude直接调OpenSpec的能力，还可以把OpenSpec作为一个MCP服务器接进来，再在权限里放行openspec、npm、git相关命令。这里要提醒一句：装是装上了，三者怎么协同、谁该在什么时候出手，得靠你在CLAUDE.md里写清楚路由规则，否则它们职能一重叠就会打架。关于CLAUDE.md的作用域和写法，保哥在CLAUDE.md记忆配置指南里讲过，这一步偷不得懒。

一个认证API从需求到归档怎么走完整流程？

光看命令没感觉，跑一遍才知道这套东西到底改变了什么。拿一个最常见的活——“做个用户认证API”——走一遍全流程：

第一步，把需求规格化。不是直接让它写代码，而是先提案：

> /opsx:propose 用户认证 API，Express + MongoDB + JWT。
  功能：注册、登录、获取用户信息。
  安全要求：bcrypt 加密，JWT 鉴权。

OpenSpec会据此生成那四份文档。注意这一步的价值不在“生成文档”，而在它会逼出你没想清楚的细节——令牌过期怎么处理？密码强度校验放哪？这些平时写到一半才发现的问题，被提前摆到了台面上。

第二步，复核计划。打开tasks.md，花五分钟通读任务顺序、有没有遗漏项、验收标准合不合理。这五分钟通常能省掉后面一两个小时的返工，是整套流程里性价比最高的一步。

第三步，启动执行。确认计划后让它开干。如果你在CLAUDE.md里要求了TDD，这时Superpowers的纪律就会接管，进入“红→绿→审查”的循环：先写一个会失败的测试（红），再写实现让它通过（绿），最后过一遍代码审查。这里有个让很多人意外的细节——Superpowers的TDD技能为了逼你真正测试驱动，会把你在写测试之前抢着写的实现代码删掉，强制“测试先行”。一开始会很不习惯，但它确保了测试反映的是需求、而不是反过来给已写好的代码补一张橡皮图章。

第四步，验证与归档。跑/opsx:verify看任务完成情况，确认无误后用/opsx:archive把这次变更的规格合并、版本化存档。这一步是坑三的解药：下次会话里，AI能读到“认证模块当初是怎么设计的、为什么选JWT而非session”，不会推倒重来。

整套跑下来，你会发现时间分配明显前移了：需求对齐和设计规划占掉两三成，真正写代码反而是水到渠成的部分。这跟“上来就让AI一把梭”的体感完全不同——慢在前面，快在后面，返工少了一大截。

这里值得停下来体会一个反直觉的点：很多人觉得“需求对齐占两三成时间”是浪费，毕竟那段时间一行代码都没产出。但真实的项目成本从来不在“敲键盘”这一段，而在“方向错了重来”和“上线后救火”这两段。propose把模糊地带提前照亮，apply阶段的TDD把边界提前钉死，archive把决策提前存档——这三下都是在拿“前期多花的确定时间”，去置换“后期不确定的巨额返工”。对一次性脚本这笔账不划算，但对要维护的系统，几乎稳赚。这也是规格驱动开发这套方法论的底层逻辑：把不确定性尽量往前赶，赶到改起来最便宜的阶段。

为什么说三个工具缺一个就断链？

有人会问：我只用其中两个行不行？拆开看就知道每一个都卡着别人替不了的位置。

只用Claude Code：速度最快，但完全裸奔。同一个团队里代码风格各写各的，安全漏洞拖到测试阶段才暴露，需求理解全靠模型这次的发挥。适合一次性脚本，扛不住正经项目。

OpenSpec + Claude Code，缺Superpowers：有了结构化蓝图，但执行阶段没有“监理”。规格写得再好，写代码时偷工减料、跳过测试，规范和实现照样会偏离。蓝图挂在墙上，工地上没人盯。

Superpowers + Claude Code，缺OpenSpec：TDD和代码审查保住了质量，设计文档也有（存在docs目录里）。但它有个致命短板——没有多轮版本化归档。下次你做头脑风暴时，新的设计文档会直接覆盖旧的，历史决策就此丢失。这正是OpenSpec的Delta / Archive机制独占的能力：每轮变更增量归档、自动把“唯一可信规格”注入上下文。

所以三者是真正的“正交互补”：OpenSpec管规划与归档，Superpowers管纪律与质量，Claude Code管执行。任意拿掉一个，闭环就缺一块。这也解释了为什么它们职能虽有重叠，却不会自动互相谦让——你得在CLAUDE.md里明确谁管哪段，否则两个都想管设计文档时就会冲突。

三件套实战，到底能稳到什么程度？

抽象的好处说再多，不如一个真实项目有说服力。保哥去年给一个宠物用品独立站做“订阅复购”功能，是个典型的“值得上全套”的活——要对接现有订单系统、要算复购周期和优惠、还要发提醒邮件，多人维护、上线后改不得。正好拿它当样本，看三件套实际改变了什么。

最让人意外的是propose阶段。还没写一行代码，光是把需求过成规格文档，就被逼出了七八个当初没想到的问题：订阅中途换地址怎么处理？优惠券和订阅价叠不叠加？用户取消订阅后历史数据留多久？这些放在“直接开写”的模式下，全都是写到一半甚至上线后才暴雷的坑。规格阶段提前把它们摆上桌，相当于把返工成本最高的那批问题，挪到了改动成本最低的时候解决。这一点的价值，怎么强调都不过分。

执行阶段Superpowers的TDD纪律也实打实兜了底。算复购周期那段逻辑有不少边界——月底下单、闰年、跨时区——按“测试先行”写，这些边界在写实现前就被测试钉死了，没出现“跑通了主流程、边界全是Bug”的经典翻车。最后这个功能的时间分配大致是：需求对齐和设计占了三成多，写代码占一半出头，验证修复一成多。账面上“写代码”的占比降下来了，但总耗时和返工反而更省——因为没有了那种“做完发现方向错了推倒重来”的大窟窿。上线之后那一版几乎没有回滚，这在以前“一把梭”的节奏里是不敢想的。

当然，这是个该上全套的活才有的回报。换成一个“给后台加个导出按钮”的半小时小活，同样的流程只会让你觉得处处是枷锁。所以下一节得认真聊聊：什么时候根本不该上。

哪些场景根本不该上全套？

讲了这么多好处，必须泼盆冷水：三件套不是默认配置，乱上就是过度工程。按任务体量给一张决策表：

判断的核心就一条：这件事值不值得为它写规格、留归档。一个跑完就扔的脚本，套上propose、apply、archive全流程，纯属给自己添堵。反过来，一个多人协作、要长期维护的功能，省掉规格对齐这一步，后面扯皮的成本会成倍奉还。工具是服务目标的，不是用来表演流程完整度的。Superpowers里那个并行worktree的玩法尤其值得单独研究，保哥在Claude Code worktree并行开发里专门拆过怎么让多条任务线互不打架。

这套流程最容易踩哪几个坑？

把高频翻车点集中列一下，每条都有人栽过：

• 把Spec写成了伪代码。规格该描述“行为”（在什么条件下、发生什么、得到什么结果），不是描述实现细节。一上来就写函数怎么实现，规格就失去了对齐需求的意义。
• 干完忘了archive。这是最常见的。不归档，下次会话AI读的还是旧规格，可能把已经做过的功能又实现一遍。/opsx:archive要养成肌肉记忆。
• 跳过头脑风暴直接干。省掉前期对齐，等于把技术决策的机会全压到事后，改动成本反而更高。
• 不看Plan就执行。tasks.md通读五分钟能省一两小时返工，这笔账太划算，别嫌麻烦。
• 30分钟的任务跑全套。前面反复说的过度工程，工具应该服务于目标，而不是反过来。

这五条里，前两条和归档有关、中间两条和“别图快跳步”有关、最后一条是总原则。说白了，三件套的价值全在“慢工出细活”，你要是处处想抄近道，那还不如不上，省得流程开销白白浪费。

新手该按什么路线把三件套用熟？

一次全上手，多半被流程劝退。给一条循序渐进的路线：

第一周，只用Claude Code。先把“在终端里跟AI结对编程”这件事本身玩熟——怎么给上下文、怎么纠偏、怎么验证结果。基础不牢，加再多框架都是空中楼阁。

第二周，加Superpowers。这时候你大概率已经被“AI跳过测试”坑过一两次了，正好亲身体会TDD和代码审查纪律的价值。从一两个核心技能用起，感受“被强制写测试”从别扭到真香的转变。

第三周以后，按需加OpenSpec。当你开始做需要决策追溯、或者要多人协作的功能时，再引入规格和归档。带着真实的“我需要把决策存下来”的痛点去用，比一开始就背着全套流程跑顺畅得多。

这个顺序的逻辑是“先练手感、再加纪律、最后上规格”。它和把三件套当成“安装清单”一次性装完的思路正相反——工具的价值是在你撞到对应的痛点时才显现的，没痛点硬上，只会觉得处处是枷锁。想系统了解Claude Code本身怎么用得更顺，可以先读保哥的Claude Code最佳实践打底，再来上这套流程框架。

说到底，三件套是“刚需还是过度工程”这个问题，根本没有统一答案——它取决于你手上这个活值不值得被认真对待。一次性脚本上全套是过度工程，多人维护的核心系统裸奔则是埋雷。把这套工具想成一个“可调档位”的流程：小活松、大活紧，按任务体量自由组合，而不是非黑即白地全上或全不上。真正的高手，不是流程跑得最全的那个，而是每次都把档位调到刚好够用的那个。

常见问题解答

OpenSpec和Superpowers能单独用吗，必须一起上？

能单独用，但各有短板。只上OpenSpec缺执行纪律，规格和实现易偏离；只上Superpowers缺多轮版本化归档，新设计会覆盖旧决策。两者互补，正经项目建议一起，小活按体量取舍即可。

Superpowers真的会删掉我写的实现代码吗？

它的TDD技能确实会在“测试先行”时，把你抢在测试之前写的实现删掉，逼你真正测试驱动。目的是让测试反映需求而非给已有代码补章。觉得太激进，可以在CLAUDE.md里调整对该技能的触发要求。

OpenSpec只能配Claude Code用吗？

不是。OpenSpec不绑定具体助手，官方称支持二十多种编程助手。它本质是一层独立的规格文档框架，Claude Code只是其中配合得最顺的执行端之一，你换别的AI助手也能用。

装了三件套，开发会不会变慢？

前期会慢——需求对齐和设计规划要占两三成时间。但写代码和返工的时间大幅下降，整体往往更快、更稳。它牺牲的是“立刻开写”的爽感，换来的是少踩坑、少推倒重来，适合要维护的正经项目。

怎么避免OpenSpec和Superpowers职能打架？

关键在CLAUDE.md里写清路由规则：谁负责设计文档、谁负责测试纪律、归档归谁管。两者都关心质量、职能有重叠，但不会自动互让，必须由你显式划清边界，否则容易在设计文档归属上冲突。

什么任务根本不值得上这套流程？

两小时内的原型和一次性脚本。它们没有长期维护和决策追溯的需求，写规格、走归档纯属增加开销。这类活直接用Claude Code一把梭最划算，把三件套留给要协作、要维护的功能。

权威参考资料