我最近一直在折腾Claude Code做日常重构，说实话体验时好时坏。模型经常在"答应你"和"干得漂亮"之间反复横跳，最典型的情况就是：你说"先跑测试再动手"，它嘴上答应得很好，下一条消息就把代码改了，改完还不告诉你。这让我意识到，缺的其实不是模型能力，而是能把"工程纪律"固化成流程的东西。后来我找到了superpowers这个开源技能包，它以SKILL.md文档为核心，给Claude Code和Codex这类AI编码代理装上了一套完整的"技能工作流"。这篇文章会把我的安装过程、核心技能拆解、SKILL.md内部结构和实际使用心得完整写一遍，给想给AI编码代理加buff的人做个参考。
简单交代一下背景：superpowers由Jesse Vincent（GitHub上叫obra）发起，在GitHub上以开源项目形式维护。它的理念很直接——不要指望模型自己知道什么时候该脑暴、什么时候该写测试、什么时候该逐行review，而是把这些方法论的执行步骤写成模型能够加载和遵循的SKILL.md文档。你装上之后，模型在你需要时会主动加载对应技能，强制自己按照流程走。效果最直观的一句话就是：它让AI从一个"爱自由发挥的实习生"变成一个"按规章制度办事的工程师"。
1. superpowers到底是个什么东西：与其说是插件，不如说是一套"模型行为协议"
先说结论：superpowers不是库，不是框架，也不产生任何API调用。它本质上是几百份经过实战打磨的Markdown文档，每一份文档就是一个"技能"（Skill），里面写清楚了这个技能适用的场景、具体要执行的步骤、每一步的验收标准、以及遇到偏差时的处理方式。
举一个生活化的类比。平时我们给AI的提示词，相当于对着临时工口头交代一句"你去把这个桌子擦了"。而superpowers里的技能，相当于把一整套《客房清洁SOP手册》递给服务员，里面写着：先检查桌面物品，再用什么清洁剂，擦完后如何确认没有遗漏，如果遇到顽固污渍应该换什么方案。模型执行的底层能力没有变，变的是它读到的工作指令的详细程度和结构强度。
superpowers能解决一个我一直觉得特别别扭的问题：通用大模型的"讨好型人格"。你问"可以吗"，它说可以；你问"是不是该这样做"，它说对。但真要落地产出时，它倾向于选择最短路径、最少步骤，而不是最稳妥的路径。superpowers做的不是改变模型的权重，而是通过SKILL.md这套外部结构，把"选择权"从模型手里夺回来一部分。它让你在对话里随时可以喊一声@brainstorm，然后模型就必须先跟你对齐方案再动手，而不是直接甩一堆代码出来。
从项目结构上看，superpowers的核心目录就是skills/，下面按不同场景拆成若干技能。每个技能自带frontmatter（元信息），包括技能名称、适用场景描述、何时使用等。Claude Code在对话中会通过"何时使用"这个字段自动判断要不要加载技能，也可以由你手动通过@技能名按需唤醒。
我整理了它最核心的几个技能，方便直观理解覆盖面：
| 技能 | 解决的问题 | 使用场景 |
|---|---|---|
| brainstorm | 需求模糊时直接写代码导致返工 | 拿到新需求、改架构、设计方案 |
| test-driven development | 不做测试盲目改代码 | 修复bug、新增功能 |
| systematic-debugging | 凭感觉乱试，越改越糟 | 线上问题、复现困难bug |
| code-review | 审代码时顺手就改，引入新问题 | 团队协作、合并请求前 |
| root-cause-analyzer | 只修表面，不解决根因 | 反复出现的故障 |
| validate | 改完不验证就提交 | 每个功能合入前 |
很多人第一次打开这个项目会觉得，这不就是一堆提示词吗？我最初也是这么想的，但用下来就明白，提示词和技能之间存在决定性差异：提示词是一次性的、被淹没在上下文里的、容易丢失的；技能是持久化的、可索引的、带触发条件的。它构建的是模型的行为协议，而不是模型的语言修饰。
2. 安装和环境准备：最容易被目录层级坑到的步骤
安装本身不难，但我在装的时候被目录结构卡了将近一个小时，社群和热搜里也经常看到"superpowers安装以后@不出来"的提问，所以这块值得单独说一说。
先交代环境前提。我本地是macOS，装了最新版Claude Code，Node.js是20.x，git是标配。Windows和Linux也可以正常用，配置方式完全一致，只是路径换一下。
我走的安装路径是直接从GitHub克隆项目到本地的全局技能目录。命令大概是这样的：
# 进入Claude Code的全局技能目录 mkdir -p ~/.claude/skills cd ~/.claude/skills # 克隆superpowers仓库 git clone https://github.com/obra/superpowers.git # 确认目录结构 ls -la ~/.claude/skills/superpowers如果你用的是Codex，对应的目录会略有不同，一般是~/.codex/skills，逻辑完全一样。关键在于，Claude Code只会扫描技能目录下固定的层级结构。superpowers仓库本身是带skills/子目录的，所以装完以后你需要在技能根目录下能看到一层是技能名、再一层是具体技能文件。
我遇到的问题是：克隆完之后，技能目录里多了一层superpowers/skills/，导致Claude Code扫描不到技能。解决办法有两个，要么把superpowers/skills/里的所有文件往上一层拷出来，要么在配置里显式指定完整路径。我自己最后选择的是直接把skills/下的内容拷贝到~/.claude/skills/，这样最稳。
除了手动clone之外，如果你用的是Claude Code较新版本，可以通过插件市场直接添加：
/plugin marketplace add obra/superpowers然后进入市场选择安装即可。社区里有部分插件市场机制在老版本上不稳，如果执行报错，回退用clone的方式就行。
安装完怎么验证是否生效？很简单，新建一个会话，在输入框输入@，看联想列表里是否出现技能名。如果输入@brainstorm能正常弹出补全，说明加载成功了。如果提示"No skills available"或者什么补全都没有，基本都是目录结构问题，先检查路径。
还有一个很隐蔽但影响巨大的坑：Claude Code的自动摘要机制。技能文档往往很长，如果上下文比较拥挤，模型或者编译器会把技能内容摘要压缩，导致技能行为时灵时不灵。我建议在会话里主动关闭自动摘要，或者在配置里把摘要阈值调低，让SKILL.md的全文尽量保留在上下文中。这一点在官方文档里写得不显眼，但对使用体验的影响比目录结构还大。
3. 核心技能逐个拆解：它究竟是怎么"管住"AI的
安装只是第一步，真正有价值的是理解这些技能具体怎么约束模型。我挑几个感受最深的展开说，这些也是我日常用得最频繁的。
3.1 brainstorm：把"我有个想法你帮我实现"变成"先聊清楚再动手"
以前我跟Claude Code说"帮我实现一个xx功能"，它大概率会直接甩一段代码，然后我就得在一堆半成品上返工。brainstorm技能的逻辑是：任何需求，先进入讨论流程，不给出最终代码。
模型加载这个技能后，会按照文档里的步骤走：先询问背景和目标，然后自己提出2到3个候选方案，每个方案都要做fact check——也就是说，它要检查自己的假设是否合理、依赖是否真实存在、成本能否被接受。之后它会列出每个方案的权衡点，再要求你拍板选一个，最后才进入实施环节。
我实际用下来的体会是：这个技能最大的价值不是让你"多聊几句"，而是强迫模型暴露它自己的思考假设。有一次我要做一个离线缓存模块，模型本来打算直接用localStorage，但在brainstorm流程里它自己检查到数据量可能超过单条存储上限，主动换成了IndexedDB方案。如果按以前的方式，这个坑大概率要等联调阶段才暴露。
3.2 test-driven development：把"写完再补测试"倒过来
这个技能对模型行为的干预力度最大。加载之后，模型的默认工作方式变成：先读你项目的测试框架，然后为要写的功能定义测试用例，确认测试失败（红），再写最简实现让测试通过（绿），然后进入重构。每一步都很小，模型不允许一次改一个文件里的几十处。
有基础的读者可能觉得这就是TDD的常识，但真正难点在于让模型"遵守"这个节奏。普通的提示词说"先写测试"，模型真的会先写测试，但它写测试的同时也把实现一起写了，或者干脆等写完整段代码才补一个测试文件。在superpowers的TDD技能里，文档会明确告诉模型：在测试通过之前，不允许写出非测试代码；如果测试还没有变绿，就不能进入下一步。这种"状态机式"的约束，比语言层面的劝告有效得多。
3.3 systematic-debugging：一次只改一个变量
排错场景最能体现AI的短板——它特别容易"灵光一现"地猜原因，然后一次性改动多个位置，把问题搞得更加不可收拾。systematic-debugging技能规定了一套排查流程：先复现问题，再检查最新的代码变更，然后针对最可能的根因提出一个假设，只能改一个变量，验证一次，再决定是继续还是回滚。
有一次我遇到一个偶发的内存泄漏，让Claude Code带着这个技能排查。它在整个过程中只改一处、跑一次验证，最后锁定在一个没有正确释放的事件监听器上。如果用以前的模式，它可能一口气改三个文件，泄漏反而更严重了。
3.4 逐行code-review：只读，不许改
这个技能约束的是"review时不越界改代码"。它要求模型逐行阅读文件，以评论形式输出发现的问题，但禁止直接修改任何代码行。对团队开发来说，这点特别重要——你并不想让AI审完代码直接把分支改了，而是希望它给你一份有依据的问题清单，由你决定怎么处理。
3.5 root-cause-analyzer：不满足于"现象消失"
这个技能会要求模型把问题拆成现象、直接原因、根本原因、验证实验四层，并且对"为什么这个方案能解决问题"给出逻辑链。效果是减少那种"好了但不知道为什么好了"的悬案。
整体来说，这些技能的共同点就是：把工程方法论写成模型强制执行的步骤，把模型的概率性行为锚定在流程轨道上。模型不是变聪明了，而是变守规矩了。
4. 技能内部结构解析：看懂SKILL.md，你就能自己写"超能力"
如果你想从"用技能的人"进阶成"造技能的人"，就必须理解SKILL.md的解剖结构。本质上它就是一个带元信息的Markdown文档，但它对格式和逻辑分层有明确要求。
一个标准的技能文档大概是这样的：
--- name: refactor-with-impact-check description: 在修改公共接口之前先生成影响范围清单，并征求用户确认 when_to_use: 当需要重构函数签名、修改公共API、或者调整模块间依赖时 layers: - thinking - acting --- # 重构前的影响清单 ## 第一步：读取当前实现 - 找到目标函数/接口的定义 - 找到所有调用方（搜索项目内全部引用） - 列出调用方所在文件与调用方式 ## 第二步：整理影响范围 - 按"直接影响"和"间接影响"分层记录 - 评估每个调用方的风险等级 ## 第三步：输出清单并等待确认 - 在回复中展示完整的调用方列表 - 明确写出可能破坏的兼容性点 - 等待用户明确同意后再修改代码前端字段是最关键的部分。name是技能的唯一ID；description决定模型在什么语义环境下检索到它；when_to_use是模型判断要不要主动加载技能的触发器；layers用来声明这个技能的思考层级。superpowers的思路是把技能分两层：thinking层负责分析、推理、制定方案；acting层负责具体执行。这样分层的核心目的是防止模型跳步——它必须先完成思考层的动作，才能进入行动层。这也是我觉得superpowers设计中最精妙的地方。
再看process和component的拆分。process是流程，component是原子能力。还是拿brainstorm举例，它内部会复用一些通用组件，比如"fact check"、"利益权衡分析"、"风险列举"。这些组件本身是独立文档，可以被多个流程复用。写新技能的时候，不需要把所有细节都从零写一遍，直接声明引用哪些组件即可。这跟写代码时的函数抽取是一个思路：流程是主函数，组件是工具函数。
基于这套结构，我自己写了一个"公共接口变更前的影响评估"技能，挂在本地技能目录下。新会话里输入@refactor-with-impact-check就能唤醒，模型在修改一个被多个模块调用的函数签名前，会先把调用方全部列出来，等我说"确认"才动手。这个技能帮我省掉了无数个"改完A模块，炸了B模块，再回头救火"的循环。
还有一个容易被忽略的点：技能的description质量直接决定模型是否会在正确时刻主动唤醒它。如果你写得含糊，模型可能在该加载的时候想不起来。建议描述里带具体行为动词和明确触发条件，比如"当用户要求修改公共接口时"比"用于代码重构"强得多。
5. 实战使用体验：变"啰嗦"了，但返工率肉眼可见下降
聊完原理，说点真实的使用体感。装上superpowers之后最明显的变化是，对话变啰嗦了。以前我让Claude Code改一个接口，它直接给改动后的代码，干净利落。现在同样的需求，它会先来一段影响范围分析，列几个方案，问我要哪个，然后才开始动手。刚上手的时候我甚至一度想卸载，觉得太拖沓。
但对比返工率之后，我改变了看法。拿我最近做的一个项目举例：把一个单体服务里的用户模块和订单模块拆分出独立接口。这个改动涉及十几个文件，调用关系交叉得很复杂。老做法是让AI直接改，结果经常是它改好了用户模块，订单模块的引用全红了，然后我再花半小时让AI修复那些红。用superpowers的brainstorm加TDD技能走了一遍之后，整个过程多了大概20分钟的"废话时间"，但最终一次性通过编译和测试，联调阶段几乎没有返工。
再补充一组我记录的对比数据。以前平均每个改动需求，我要发5到7条消息才能收敛到一个稳定版本，其中至少一条是"你怎么把我的xx也改了"这样的纠错指令。用superpowers之后，同样的需求平均在3条消息内就能收敛，纠错指令出现的频率明显下降。代价是上下文长度变长，token消耗增加，我粗估在30%到60%之间，但考虑到一次全量调试排查的成本，这个开销是值回票价的。
关于Codex的适配问题，我也试了。superpowers官方是支持Codex的，安装路径换成~/.codex/skills即可。但因模型本身对长文档的遵从度存在差异，实测下来Claude Code上的执行最稳定，Codex偶尔会"读了文档但不照做"。这不是superpowers的问题，是模型能力边界。如果你的主力工具是Codex，建议装完先跑一次@systematic-debugging或@brainstorm这类流程性强的技能做验证，确认模型遵守度再决定是否长期使用。
再回答一个热搜里出现很多次的问题："superpowers java"。这个完全不用担心，技能体系与编程语言无关。SKILL.md里写的都是工程流程，比如"先写测试、再写实现""改一个变量验证一次"，Java项目、Python项目、Go项目都可以用。真正跟语言相关的是模型自身的代码能力，不是这套技能。
至于什么时候该开技能、什么时候不该开，我自己的判断标准是：探索期和原型阶段，我反而会关掉大部分技能。因为那个阶段要的是快速发散，模型给出一个思路、几段代码，我看了有灵感就行，不需要严谨的流程。一旦项目进入收尾、重构、上线排错这些"稳定性优先"的阶段，再把superpowers开上。一个会话内同时激活的技能数量建议控制在2到3个，太多技能会让模型检索和切换时出现混乱，影响响应速度和质量。
6. 失灵时的排查链路：从"技能没生效"到"技能救不了你"
最后这部分写给已经装上superpowers但遇到各种异常的人。技能不是装了就好，它会以各种姿势失灵，我把踩过的坑和排查方式按链路整理一遍。
先说最常见的问题：@补全里看不到技能。排查第一步不是重装，而是检查目录层级。打开技能根目录，看是不是出现了skills/skills/这种嵌套目录。如果是，把文件层级捋平，让技能名直接位于根目录下一层。第二步，确认你编辑的是正确的全局目录——有人把仓库clone进了项目本地.claude/skills，换了一个项目后技能全没了，这属于路径认知问题。第三步，重启Claude Code会话，因为技能列表是在会话启动时扫描加载的，新clone的目录不会自动刷新到已打开的会话里。
其次是"看了@brainstorm，但模型行为完全不像加载了技能"。这个情况大概率是技能被吃了，而不是没加载。排查时新建一个空白会话，只输入@brainstorm这一个技能，加上一句"请执行你的技能流程"，看它是否按照脑暴步骤走。如果空白会话里能正常执行，那就是旧会话上下文太长，技能文档被压缩或者被其他指令淹没了。处理办法是关掉自动摘要、缩短会话长度、或者切换到一个新会话。如果空白会话里也不按流程走，就要检查模型版本和遵守度，换一个能力更强的模型再试。
然后是"技能加载了，但只走了一半流程就跳步"。比如TDD技能要求先写测试，模型却直接连实现代码一起写了。这种跳步很难通过提示词修复，我比较推荐在系统提示词里增加一条"必须严格遵守已加载技能的步骤，每一步完成后再进入下一步"，然后继续观察。另外，降低模型温度也能减少跳步概率，实测有效，只是响应会变得更保守一些。
最后不得不泼一盆冷水：技能救不了能力不足的模型。如果你用的是参数量较小、执行能力较弱的模型，即使它逐字读完了SKILL.md，也可能在"落实"环节变形——比如让它找调用方，它只搜了当前目录；让它做fact check，它编造事实。superpowers能管住流程，但管不住模型本身的能力上限。这个边界心里要有数。
还有一个常见的误区：以为技能就是某种"万能模板"，输入一个句子就能自动补全所有工程能力。实际不是。superpowers更像一个"流程引擎"，它把方法论带上，把约束补上，但分析质量、代码质量、方案质量依然取决于底层模型的推理能力。工具和模型是乘法关系，不是加法。
颜色也比较容易出现的情况是，开了太多技能导致模型选择困难。比如一个会话里同时挂上brainstorm、TDD、code-review三个技能，模型会在对话中反复切换角色，反而显得分裂。我现在每类任务固定只开一两个最匹配的技能，效果稳定很多。
我的整体建议是：装上superpowers后，不要急着把每个技能都试一遍，先从@brainstorm和@test-driven-development这两个开始，用一周时间适应它带来的"变啰嗦"。等适应了这种节奏，再逐步引入排错和审查类技能。这套东西的核心价值不是某一项功能，而是让AI编码代理从"能回答"变成"有纪律地执行"——而后者在整个工程链路上的价值，远比多写几行代码要大。
如果你也在被AI编码助手"答非所问"、反复返工的问题折磨，我强烈建议从安装一个@brainstorm技能开始。它可能不会让你立刻觉得"超能力"附身，但会你第一次感受到：原来AI不是在敷衍你，只是从来没有人用结构化流程跟它认真打交道。
