1. 先聊聊 AI 编程“失控”的那一刻：为什么无数 Agent 都败给了“自由发挥”
说个我印象很深的场景。那次我用 Claude Code 让 Agent 帮我改一个支付模块，需求就一句话：“把超时重试的逻辑加上”。结果它特别兴奋地给我加了三层重试、一个指数退避算法，还顺手改了我另一个文件的函数签名——因为它觉得那样“更优雅”。业务逻辑没坏，但我的 review 成本比我自己写一遍还高，更不用说它中途还自作主张引入了一个新的依赖库。
这件事让我意识到一个核心问题：AI 编程最大的瓶颈，早就不是“模型能不能写代码”，而是“Agent 靠不靠谱、守不守规矩”。你给它一个模糊目标，它能在几分钟内产出结果，但产出的过程完全没有工程纪律可言——不写测试、不按已有架构来、不遵循项目规范，甚至会把需求理解成它自己脑补的“升级版”。
Superpowers 这个技能框架，解决的就是后面这件事。它是一套跑在 Claude Code 这类 AI Agent 上的“纪律引擎”，通过结构化的 Skill（技能）和流程约束，强制 Agent 从接到需求开始，到写代码、跑测试、做评审，每一步都按工程规范来，而不是想到哪儿写到哪儿。
坦白说，我第一次接触它的时候也没太当回事，毕竟“给 AI 加提示词约束”这事儿我干过太多次，效果都不持久。但用了几周之后，我是真的把工作流全面切过来了。这篇文章就把我对 Superpowers 整个机制的理解、实际配置过程、踩过的坑，以及它和 OpenSpec、CLAUDE.md 配合起来形成完整闭环的用法，一次性讲清楚。如果你也是那个在 AI 编程里反复“救火”的人，这篇文章应该能帮你省下不少力气。
1.1 一个典型的“AI 自由发挥”事故现场
要理解 Superpowers 的价值，得先从反面看。拿我自己一个外包项目举例。
当时我让 Agent 实现一个用户积分过期提醒的功能。需求其实很简单：每天扫描一次积分表，把过期前 7 天的用户筛出来，给推送通知。我给了它项目路径，顺便说了一句“按项目现有风格写就行”。
结果呢？Agent 直接创建了一个scheduler.py，自己引入了一个定时任务库，还给整个项目的配置改成了支持多环境变量。我 review 的时候人都傻了。测试呢？没写。日志规范？它自己定了一套。数据库连接方式？它觉得原来的db.py写得不好，给绕过去了。功能确实实现了，但整个代码和项目的其余部分完全是两个世界的人写的。
后来我复盘，问题不在于模型能力，而在于 Agent 的“价值取向”。它天然倾向于把任务完成得“漂亮”，而不是“合规”。没有外部强约束时，它会默认自己那套优雅方案就是最好的，根本不会先去看项目已有的模式。工程规范里所谓的“一致性”“最小变更”“测试先行”，对 Agent 来说是隐形的空气。这就是自由发挥的本质：不是恶意，是无序。
1.2 为什么你写一百遍“请遵守规范”都没用
很多人面对这个问题，第一反应是加强提示词，比如在系统提示里写“你是一个资深工程师，请务必遵循 TDD，写干净整洁的代码”。我也这么干过。刚开始有点用，但效果衰减得特别快。原因有三个。
第一是上下文衰减。Claude 这类模型的注意力是有限的，你塞给它的指令越多，它在具体任务执行时就越容易“忘记”那些优先级没那么高的约束。尤其当一个会话拉到几万 token，早期提到的“规范”早就被淹没在海量上下文里了。
第二是隐式约束没法落地。你跟它说“按工程规范来”，但工程规范是几十条不同粒度的规则：文件命名用小写加横线、单元测试文件要靠近源码、不要修改与你无关的模块……这种隐式知识你得拆成显式步骤，它才知道从哪个动作开始执行。
第三是缺少流程闸门。提示词只能影响 Agent 的“意愿”，影响不了它的“流程”。你想要的是它先写计划、你审批、再写测试、看测试失败、再写实现。但模型不会自动这么跑，它倾向于一口气把活干完——因为这样最符合它的训练习惯，也最省事。
这三座大山决定了，光靠“说话”管不住 Agent。只有把规则变成程序上的步骤，把约束变成触发执行的条件，Autonomy 才会被关进笼子里。Superpowers 的核心思路，正是把“工程规范”翻译成一连串 Agent 无法跳过的操作节点。
2. Superpowers 的底层逻辑：Skills 不是提示词，是一套可强制执行的工程流程
Superpowers 最容易被误解的点，是大家觉得它就是一个“更高级的提示词集合”。不是的。它的本质是把“做事方法”封装成了结构化的工作流，再让 Agent 按工作流一步步执行。提示词只是它用来沟通的最小单位，真正的约束力来自流程本身。
你可以把它想成给 Agent 装了一套“施工手册”：不是告诉它“你要盖好楼”，而是告诉它“先勘察地基、再支模板、再浇筑混凝土、再养护”，每一步都有产出物和验收标准。只要流程被严格执行，结果自然就不会跑偏到哪儿去。
2.1 它到底往 Claude Code 里塞了什么
Superpowers 的项目本体是一个 GitHub 仓库，你 clone 下来之后，里面是一堆按功能划分的 Skill 文件和配套的说明文档。它的核心组成部分是以 CLAUDE.md 为入口，把skills/目录下各个 skill 的能力暴露给 Agent。
举个例子，它里面我会用到的主要 skill 有这几个：brainstorming（头脑风暴，用来澄清需求）、writing-plans（把需求拆成可执行的计划）、executing-plans（按计划实施）、TDD（测试驱动开发）、code-review（代码评审”。每个 skill 里都有一个 SKILL.md 文件，里面详细描述了“这个技能用来干什么、在什么情况下触发、执行时需要遵循哪些步骤、产出物是什么”。
这跟普通提示词的关键区别在于：Skill 是带“触发条件”和“完成检查”的。如果某个 Skill 要求 Agent 先输出计划再动手，那它就不会在没写计划的情况下直接跳去写代码——因为这套流程已经把“输出计划”设置成了它继续执行的前提条件。换句话说，这种约束不再是语言层面的“请求”，而是执行层面的“门槛”。
2.2 从 brainstorming 到 plan 到 execute：一次规范的“思考漏斗”
Superpowers 的整个流程可以看作一个漏斗：从抽象需求开始，逐步收敛到具体任务，再进入执行。
这个漏斗的第一层是 brainstorming。它的作用是逼 Agent 在动手前先确认需求。你在 Claude Code 里敲#调用 brainstorming skill，Agent 不会立刻给方案，而是反过来问你一系列问题：你到底要解决什么问题？现有的系统边界在哪？你期待的结果是什么状态？这块体验非常像跟一个较真的同事过需求，而不是面对一个急于交作业的执行者。
需求澄清之后，进入第二层 writing-plans。这个 skill 会把目标拆成一份 Markdown 格式的计划文档，里面有步骤、有依赖关系、有验收标准。我在实际用的时候，它生成的计划往往会分阶段，并且会在计划里标记哪些地方需要我人工确认。这个文档不是摆设，后续的 executing-plans 会严格按照这份计划来执行，Agent 每做完一步都会检查自己“是不是还在计划轨道上”。
最后才是真正写代码的阶段。这个阶段也会套上 TDD skill，先让它根据计划写测试，再跑测试看到失败，然后写实现代码让它通过，最后做重构。整套漏斗走下来，Agent 每一步都有明确的上下文和目标，而不是握着整个代码库自由发挥。
2.3 TDD 为什么是 Superpowers 的“纪律核心”
前面说的计划流程负责管方向，TDD 这个 skill 负责管质量。技术上，TDD 本身只是“红-绿-重构”三个循环：先写一个会失败的测试，再写让测试通过的最简实现，最后在安全网的保护下重构。听起来很简单，但让 Agent 执行起来却非常难。
难在哪？因为模型本质上是“结果导向”的。你让它实现一个功能，它的本能是先写实现，测试只是附带品。但 TDD skill 会把顺序彻底倒过来：在 Agent 看到任何实现代码之前，它必须先根据需求写出一批测试用例。这些测试的内容，实际上就是把需求文本翻译成了可验证的行为契约。
这一步的价值体现在两个地方。一方面，它逼 Agent 在写码之前想清楚“这个功能的行为边界到底是什么”，很多需求歧义在这一步就会暴露，而不是等到功能上线才发现理解错了。另一方面，测试代码是天然的“质量标准”，Agent 后续的实现有没有跑偏，跑一下测试就知道了，不用靠人肉 review 猜。
我在实际项目中感受最深的是：有了 TDD 约束之后，Agent 的“自作聪明”行为大幅减少。因为它一旦开始重构别人的函数或者改接口，测试会直接报警。纪律不是靠自觉，是靠“违规就会被抓住”的机制。
3. 从安装到跑通：我把 Superpowers 接进工作流的关键细节
概念说完了，进入实操环节。Superpowers 的安装本身不复杂，但有几个坑要提前避，不然会被各种“目录找不到”“Agent 不识别 skill”的问题卡半天。
以我目前使用的方式为例，我的目标环境是：macOS 本机 + Claude Code 已安装 + Node.js 环境可用。Superpowers 本质上依赖 Node.js 来跑一些辅助脚本，所以 Node 版本不能太低，建议 18 以上。
3.1 克隆仓库前，先想清楚三件事
第一件事是“装到哪里”。Superpowers 官方推荐的做法是 clone 到~/.claude/skills/里，这样对当前用户下所有项目生效。但我个人的建议是：如果你在多个项目里实验，先放进全局目录感受一下；一旦决定在某个正式项目里固化使用，就复制到项目自身的.claude/skills/里。理由很简单，全局生效意味着 Agent 在每一个会话里都会把这一堆技能加载进来，上下文被占用的代价是你想象不到的。
第二件事是“版本锁定”。Superpowers 目前迭代特别快，master 分支随时可能变。第一次 clone 成功之后，建议记录一下 commit hash，后续更新时做一次对比再升。我之前有一次直接git pull，结果某个 skill 的目录结构变了，旧项目的 CLAUDE.md 引用路径全部失效，Agent 完全找不到技能，折腾了一天。
第三件事是“盘点你要哪些 skill”。不是仓库里所有 skill 都适合你的项目。如果项目本身没有测试体系，硬上 TDD 会让你先补一大堆测试基建。我现在的用法是：核心的 brainstorming、writing-plans、executing-plans 一定保留；TDD 和 code-review 看项目成熟度决定要不要启用。
3.2 一步步配置，让 Claude Code 主动认识这些技能
整个配置我给你拆成几个动作，你跟着做就行。
第一步，clone 仓库。我把指令放在下面，如果你已经有~/.claude目录就直接用，没有就先建一个。
mkdir -p ~/.claude git clone https://github.com/obra/superpowers.git ~/.claude/skills/superpowers注意这里有个最容易踩的坑：很多教程会让你 clone 到~/.claude/skills根目录下，直接把一堆 skill 文件散在skills/里。这会导致 Claude Code 在扫描技能时目录结构对不上，加载失败。正确做法是 clone 成一个子目录superpowers，让它的内部结构和仓库保持一致。
第二步，告诉 Claude Code 去读技能说明。你需要在项目根目录或全局的 CLAUDE.md 里加上一段引用，我习惯这样写：
在开始任何复杂任务前，先阅读 ~/.claude/skills/superpowers/SKILL.md 了解可用技能，并按其中描述的流程执行。这一步的作用是给 Agent 一个“入口索引”。因为 Agent 不会自己去翻你的文件系统，你得明确告诉它技能说明书在哪儿。如果你把 Superpowers 装到了项目目录，那路径就改成.claude/skills/superpowers/SKILL.md这种项目相对路径。
第三步，重启会话。CLAUDE.md 的改动只在新的会话里生效。改完配置之后一定要/clear开一个新会话，然后随便敲一句“你有哪些技能”，看它能不能正确罗列出来。如果这一步失败了，优先检查路径和目录层级。
3.3 第一次触发 Skill 时的交互体验
配置完成之后，你不需要做什么特别的操作。正常描述你的需求，比如“我想给订单模块加一个取消功能”，Superpowers 的入口会判断这个问题是否足够复杂、是否需要启动 brainstorming。如果它判定需要，就会在回复里引导你进入技能流程。
实际操作中，我会看到类似这样的交互：Agent 先回复一段“这个问题有几个关键点需要先确认”，然后列出三四个问题，等我的反馈。这种“不急着干活”的状态，就是 skill 被触发的信号。
这里我要特别说一点：你会觉得 Agent 变“啰嗦”了。以前你一个需求丢过去，它闷头写半天给你一坨代码；现在它会先问需求、再给计划、再等审批，节奏明显变慢。但你要理解，这个“慢”本身就是纪律的一部分。它把大量返工成本提前到了计划和设计阶段，实际上总耗时往往是下降的。第一周你会不习惯，但坚持下来你会发现这种“慢”才是真的快。
4. 实测两周后，Agent 的行为发生了哪些肉眼可见的变化
光讲理论没意思，我直接说实测结果。我把 Superpowers 接入到一个真实的中型项目里跑了大概两周，这个项目是 Vue 3 + FastAPI 的全栈应用，有测试基线但覆盖不全，团队成员对代码规范有要求但没有自动化检查。以下是几个让我印象深刻的实际变化。
4.1 同一个任务的前后对比：从“直接开写”到“先出计划”
我特意做了一个对照实验。同一个需求：“把用户列表接口加上分页参数”，我分别用普通 Claude Code 会话和接入了 Superpowers 的会话来处理。
普通会话的行为：直接搜索用户列表接口的位置，然后改代码，返回一段修改摘要，告诉我“已经加上了 page 和 page_size 参数”，没有任何测试和计划。
Superpowers 会话的行为：先触发 brainstorming，问了我“分页默认值是什么？前端传参格式是 page=1&size=20 还是 limit=20？接口返回格式要不要包一层 metadata？”等问题。确认之后生成了一份计划，明确写着“在现有 ListUsers API 上增加 query 参数，同时保证原有调用不受影响；新增 2 个测试用例验证分页边界”。最后才进入 TDD 流程，先写测试跑红，再改实现跑绿。
我把两份产出都提交到分支里，差异是巨大的。前者代码能用，但没有任何安全保障；后者从一开始就有测试兜底，后续重构也不心虚。这就是工程规范和自由发挥最直观的区别。
4.2 测试先行真能压住“无意义返工”吗
我本来有点怀疑 TDD 在 AI 编程里是不是形式主义，但两周里发生的两次事情说服了我。
一次是 Agent 在实现“优惠券叠加”功能时，TDD 流程让它先写了“同一订单不能叠加两张同类优惠券”的测试。写实现的时候，它试图直接修改优惠券计算的公共函数，结果跑测试立刻失败，因为公共函数变更影响到了其他已经通过的用例。于是它被强制停下来，重新评估最小变更方案，最后选择在调用层做判断，而不是大改底层。
另一次是“积分过期提醒”那个任务。因为测试先定义了“只在过期前 7 天发送提醒”的边界，Agent 实现时想改成“10 天内都提醒”，测试直接红，迫使它重新读需求确认。如果按自由发挥模式，它可能就自作主张改了业务规则，我们 review 时还不一定看得出来。
这个机制的厉害之处在于：它不是靠 prompt 求 Agent 别乱来，而是用测试结果作为“行为是否符合预期”的裁判。一旦越界，立刻暴露，返工成本被压到最低。这种效果是任何文字约束都达不到的。
4.3 code-review 模式揪出的典型问题
Superpowers 的 code-review skill 我一开始以为就是拿来看一遍代码有没有 bug，用了几次发现它的价值远不止此。
它会在审查时按几个维度检查：变更是否超出任务范围？是否有重复造轮子？是否有明显的安全或性能隐患？是否遵循了项目现有的命名和分层？最让我吃惊的是，它能在 diff 里识别出“Agent 顺手做的无关改动”，类似之前那样改掉函数签名这种——它会明确标记“此变更与当前任务无关，建议撤销”。
我特意统计了一下两周内 review 报告里频率最高的三类问题：排名第一是“改变了现有 API 的响应格式但未更新调用方”，第二是“在公共模块添加了只为一个调用点服务的参数”，第三是“新增了不必要的依赖”。这些问题放在人工 review 里，要花不少时间才能发现，而 skill 基本能在几分钟内列出来。作为人在环路的最终把关者，我只需要确认这些告警是不是真的需要修，省掉大量从 diff 里找问题的精力。
5. 和 OpenSpec、CLAUDE.md 配合：把“纪律”从代码层面扩展到项目层面
Superpowers 管的是“Agent 接到任务之后怎么执行”，但落到真实项目里，光有执行纪律还不够。需求本身是模糊的，项目约束是散落的，这两块如果不兜住，Superpowers 在中间环节再怎么规范，源头一个错误理解也会传递到最终代码。这也是圈子里经常把 Claude Code + OpenSpec + Superpowers 称为“三件套”的原因。
5.1 OpenSpec：把需求从“一句话”变成“可验证规范”
OpenSpec 是一个规范驱动开发的开源工具，它解决的是“需求到底说了什么”的问题。它用结构化的 Markdown 文件来描述系统行为，每个功能点对应一个spec.md，里面写清楚背景、需求细节、验收标准。
我现在的流程是：接到需求后，先让 Agent 用 OpenSpec 生成一份规范草案，我审核并修订后才进入正式开发。这样做有一个非常大的好处：需求和实现之间不再是“一连串聊天消息”，而是一份可持续追踪的文档。后续如果 Agent 对某些行为不确定，它可以回去翻 spec，而不是靠猜。
举个例子，有一次客户提了个需求：“用户可以在会员中心看到积分明细”。这听起来足够清晰了吧？但 OpenSpec 的流程会让 Agent 细化出“积分明细包含哪些字段”“排序规则是什么”“是否分页”“统计口径是入账时间还是出账时间”。这些细节全都沉淀进 spec 文档，写代码时 Agent 只需要翻译文档，不需要二创。
5.2 CLAUDE.md：项目级规则应该写什么
CLAUDE.md 是 Claude Code 的项目记忆文件，它就是 Agent 每次进入项目时必读的“员工手册”。Superpowers 的 Skill 说明书放在这，但项目自身的约束也放在这。
我建议 CLAUDE.md 至少包含这几块：项目技术栈和技术选型理由、目录结构说明、代码风格约定（命名、注释语言、接口设计风格）、测试要求（哪些目录必须有单测、怎么跑测试）、禁止事项（比如不允许修改哪些目录、不允许引入哪些依赖）。你写得越具体，Agent 的自由发挥空间就越小。
这里我说一个实战体会。以前我总想写“代码要高质量”，这句空话对 Agent 一点用没有。后来我改成“所有 API 层的输入必须用 Pydantic 做校验，不允许在 View 函数里直接操作原始 request 对象”。这种规则是 Agent 能直接执行的，而且它一旦违反，你在 review 时一眼就能看出来。规范的价值不在于写得漂亮，在于能够被执行和验证。
5.3 三件套怎么分工，才不会功能重叠
很多人觉得 OpenSpec、CLAUDE.md、Superpowers 都在“约束 Agent”，会不会功能重复？我一开始也迷糊，用了一段时间才理清楚它们的分工。
合理的分工是：OpenSpec 管“做什么（What）”，负责从模糊需求里提炼出可验证的行为规范；CLAUDE.md 管“在什么约束下做（Constraints）”，描述项目固有的技术栈和规则；Superpowers 管“一步步怎么做（How）”，定义任务从接单到交付的方法流程。
这三者的配合可以画成一条流水线：需求进来，OpenSpec 把它变成规范文档；规范确定后，Superpowers 的 brainstorming/writing-plans 把文档变成可执行计划；Agent 写代码的过程中，CLAUDE.md 里的项目规则兜底；写完代码再通过 TDD 验证和 code-review skill 收尾。每层各管一段，既有独立性又能串成闭环。我从接入这套体系之后，AI 产出的代码基本只需要做业务确认，不用再为“代码规范”给他返工。
6. 绕不开的边界：哪些场景下 Superpowers 反而会帮倒忙
任何工具都有局限，Superpowers 也不是银弹。我用了这段时间，踩了一些坑，有些场景下这套“纪律引擎”不但没提效，反而让简单事变得复杂。这些边界如果你不提前知道，很容易被劝退。
6.1 Skill 目录塞太满，Agent 会“选择困难”
Superpowers 的技能体系本身就不少，再加上社区里还有一堆第三方 skill。如果你一股脑全装进去，Agent 每次任务前都要在几十个技能里做选择，反而容易选错。
有一次我装了一个“图片优化”的 skill，结果在我做前端页面调整时，Agent 自己触发了一次图片压缩流程，等了几分钟，其实我根本不需要这个操作。所以我的建议是“最小化技能集”：只保留你项目真正高频使用的技能，其他的一律不装。少即是多。
6.2 计划写得再细，也要留人工审批闸门
Superpowers 的 plan 流程确实能把需求拆得很细，但它生成的计划不等于你确认过的事实。有一次它针对“导出数据”的功能写了八步计划，里面有一步是“新增一个后台任务队列来异步处理导出”。这个方案在技术上没错，但对我们那个小项目来说纯属过度设计。
好在整套流程里计划会等我来确认，我直接删掉那一步，调整了思路，Agent 就沿着修正后的计划执行下去了。这个教训是：不要让“它的计划”成为“你的计划”。你得把它生成的计划当作一份草案，保持否决权。人工闸门一旦放开，前面所有纪律都会失去意义。
6.3 资源消耗和时间成本比想象中大
这一点很多人不会跟你说：TDD 和严格的流程会让单次任务耗时明显变长，同时 token 消耗也会上升。毕竟它要先写测试、跑测试、看失败、写实现、再跑测试，每一步都要读文件和上下文，这比直接生成一段代码贵得多。
在我们团队，一个中型需求的 token 消耗大概比普通会话高出 40% 到 60%。如果项目本身预算敏感，或者你只是做一次性脚本，那这套重流程就没必要上。按需启用才是理性的做法，像我自己的小项目就没有全程开 TDD，只开 brainstorming 和 writing-plans。
6.4 不适合的场景：原型探索和一次性任务
最后说说场景边界。Superpowers 适合的是“要长期维护、多人协作、对稳定性有要求”的工程化项目。但如果你是在快速验证一个方案、做一个 hackathon demo、或者临时写个脚本处理数据，那这套纪律引擎反而会拖你后腿。
我上次想快速实验一个数据清洗思路，Agent 还在那按流程跟我确认需求和写测试，我直接把它打断了。这种场景需要的是“自由发挥”的模糊探索，让模型快速给出各种可能性，而不是一板一眼地按工程规范交付。判断标准其实就一句话：这件事做完之后还要不要长期维护？要，就上纪律；不要，就让它随便跑。
7. 我最后想说的，是关于“可控性”的一点个人体会
用 Superpowers 这段时间，让我重新想明白了一个问题：AI 编程的未来方向不在于把模型变得更强，而在于让模型在既定规则内稳定发挥。能力强但没有纪律的 Agent，相当于一个技术很牛但完全不听指挥的同事——你宁可不要他。而 Superpowers 的意义，就是给 Agent 建立了一套可执行、可验证、可干预的行为规范，让它从“自由发挥”变成“按章办事”。
当然，它不是万能的。它不能代替架构师，不能代替产品经理把需求想清楚，更不能取代你作为工程师的判断力。它真正的价值是把那些繁琐但必须遵守的工程规范，从你的口头叮嘱变成 Agent 的执行本能。
如果你现在也被 AI 的“自由发挥”折磨得头疼，我的建议是别一上来就全套照搬。先只装 brainstorming 和 writing-plans，跑一个迭代感受一下流程变化；觉得能接受，再逐步加上 TDD 和 code-review。让 Agent 从一个“莽撞的实习生”变成一个“有章法的高级工程师”，这中间需要的不是更强的模型，而是一套你真正愿意坚持的纪律。
