1. superpowers并不是代码库而是一套让AI干活前先学会思考的方法论1.1 它到底增强了什么不是Agent框架而是一组技能包如果你和我一样在2025年高强度使用Codex、Claude Code这类AI编码助手大概率会遇到同一个尴尬局面模型写单段代码很利索但放到真实项目里就经常埋头就干。让它修一个报错它能顺手把周围几百行业务逻辑都重构了让它加一个功能它不问输入输出边界、不看现有代码约定直接开写。AI编程工具不缺代码生成能力缺的是工程师的职业习惯。我是在一次连续翻车之后才认真去研究superpowers的。这个项目在GitHub上以skill库的形式存在作者是资深开发者它不提供任何代码库、不绑定模型而是把编码助手的工作方法拆成一组组可加载的技能skills。每一个技能对应一个Markdown文件SKILL.md里面写的是遇到某类任务时AI应该按什么流程执行。比如规划技能教它怎么把模糊需求拆成可执行任务调试技能教它如何先复现再定位再修复代码审查技能教它按严重程度逐层检查。用生活化的类比模型能力相当于员工的智商和体力superpowers相当于新员工入职时拿到的那本《资深工程师工作手册》。手册不能改变员工的智商但能让他少做蠢事。1.2 为什么流程约束比模型能力更影响编码效果这个判断可能有点反直觉但确实是我连续用了几周之后得到的结论模型在单点任务上的能力已经很接近初级工程师但放进真实项目里效果仍然不稳定问题大多出在行事路径上。AI很喜欢跳步骤不改测试就改代码、不读日志就猜原因、不跑构建就说完成。这些问题的根源不是它笨而是它缺少执行约束。superpowers的价值就在这里。它把工程师日常工作中那些行之有效、但很少被写下来的流程变成显性规则。拿它的调试技能来说流程大概是第一步要求AI复现问题拿不到可复现路径就继续向用户提问第二步要求收集证据读取堆栈、日志、相关上下文明确禁止凭空猜测根因第三步要求针对每一个假设设计最小验证把实验结果记录下来第四步要求在修复前先写回归测试确保修改是可被验证的最后才是改代码并跑完整测试。这套流程单独拿出来看几乎像废话。但真正喂给编码模型之后效果立竿见影——因为它把先想清楚再动手从口号变成了强制动作。我后来在多个项目里测试过遵循这套流程时AI首次交付的代码通过测试的概率明显更高返工次数少了一半以上。1.3 它和上千行system prompt的本质差异按需加载可能有人会问我之前也写了很长的system prompt或者项目里有AGENTS.md效果为什么还是不行这里有一个关键差异传统的静态规则文件是一次性全量注入的AI从对话开始就要在上下文里维护一大堆指令而superpowers是按需加载的。它把技能拆成独立文件AI只有在面对对应场景时才会通过技能名称去读取对应的SKILL.md。这个设计和插拔式架构完全一致核心指令保持轻量具体能力按需挂载。好处有两点第一上下文不会被一堆无关流程占用模型能更集中地处理任务本身第二每个技能文件可以写得很厚、很细因为不是每次对话都会加载它不需要为省token而牺牲流程完整性。我对这个机制的理解是superpowers本质上是在模型和项目之间加了一层工作流路由由场景决定加载什么流程由流程决定模型做什么、怎么做。2. 装之前搞清楚的几件事运行环境、版本选择与三种接入链路2.1 运行环境其实没什么门槛装好Git、能跑CLI就够关于superpowers的安装网上很多教程上来就让你跑一堆命令实际上完全没有那么复杂。它的核心资产是文本文件本质上是把Git仓库里的技能目录放到你的AI编码助手能读到的地方。运行环境几乎没有任何特殊要求只要你的机器能跑Codex CLI或Claude Code这类工具并且装了Git就足够了。不需要Docker不需要额外的Python环境不需要Node服务常驻。我自己的主力环境是macOS同时也在一台Linux开发机上用过两边都没有遇到额外依赖问题。Windows的话如果你用的是WSL或者Git Bash同样能走通。整个安装过程最核心的动作就是把superpowers仓库clone到本地然后让编码助手能找到这个目录。仅此而已别把它想成部署一个服务它没有后台进程也没有守护脚本。2.2 三种接入方式对比与我的选择我研究了一圈之后发现社区里主流的接入方式可以归成三类各有取舍接入方式做法适用场景注意事项直接clone到工具技能目录把仓库clone到~/.claude/skills/或~/.codex/skills/对应目录只用一个AI编码助手切换工具时目录不共享项目内引用在项目根目录添加AGENTS.md/CLAUDE.md指向外部技能目录单项目内使用方便团队统一路径写死了换机器要调整软链共享clone到公共目录再用符号链接挂到各个工具目录多工具、多项目共用一套技能更新一次所有入口全部生效我最后选的是软链共享方案。原因很现实我日常会在Codex和Claude Code之间来回切换有时候同一个项目还会用两种工具对比结果。如果每换一个工具就重新clone一遍技能版本很容易不一致维护成本太高了。用软链之后我只需要维护一份技能库Codex和Claude Code读到的永远是最新内容。具体命令也很简单假设我把superpowers clone到了~/tools/superpowersgit clone https://github.com/obra/superpowers.git ~/tools/superpowers mkdir -p ~/.codex/skills ~/.claude/skills ln -s ~/tools/superpowers ~/.codex/skills/superpowers ln -s ~/tools/superpowers ~/.claude/skills/superpowers不同版本或不同工具的技能目录命名可能有差异我建议动手之前先看一眼官方仓库的README把路径名对齐再执行。我最初就是因为没看说明把目录名写错了折腾了半天才发现是读取路径不对。2.3 版本锁定与后续升级的正确姿势superpowers迭代速度非常快几乎隔几天就会新增技能或者调整流程措辞。我在前两周直接跟着主分支走结果遇到过一次昨天还能用的技能今天突然不触发了的情况。后来排查发现是上游改了技能目录的命名方式老名字失效了。从那以后我养成了一个习惯用git tag锁定版本不盲目跟最新。但更关键的一个教训是不要直接改上游仓库里的技能文件。我一开始觉得某个技能的流程太啰嗦直接在主仓库里改了SKILL.md后来想更新版本时发现和上游冲突得一塌糊涂。正确的做法是先fork一份到自己名下再在fork上做修改更新时用rebase把上游的新内容合进来。这样既能保留自己的定制又能吃到上游的新特性。如果你是团队使用我还建议把fork出来的技能库作为项目的一部分纳入git版本管理。新成员clone项目之后一条软链命令就能把整组技能挂上配合项目里的AGENTS.md新成员第一次用就能得到和老成员一致的AI行为规范这对团队提效帮助很大。3. 技能到底怎么被AI读进去SKILL.md、目录约定与执行流程解剖3.1 一个技能文件夹里的标准结构为了理解superpowers为什么管用我建议你实际打开它的目录看一眼。每一个技能都是一个独立文件夹文件夹里最核心的文件叫SKILL.md此外通常还有参考文档、示例代码或辅助脚本。文件夹名就是技能的名字也是AI检索时的索引关键词。比如planning、debugging、code-review、subagents一看名字就知道这个技能负责什么。SKILL.md内部的结构也有讲究不是随便写两句你应该谨慎一点就完事。它通常会包含几个固定部分技能的触发条件什么场景下应该激活这个技能、执行流程按顺序要做什么、输出要求最后交付时应该包含哪些内容、以及明确的禁忌什么情况下绝对不能做什么。这套结构让AI在读取文件之后能够把流程转化为具体的行动指令而不是停留在泛泛的你应该怎么做更好。我最早犯的一个错误是以为只要把SKILL.md文件放在那里AI就会自动用。后来发现没那么简单技能是需要被发现的。AI通过你的提问和上下文判断当前场景然后在技能目录里查找名称匹配的技能文件读取之后才开始执行。如果你项目里的AGENTS.md或CLAUDE.md没有做任何引导AI可能完全意识不到这些技能的存在。所以挂载技能的同时一定要在规则文件里留下索引提示。3.2 以debugging为例一次完整技能调用长什么样把概念落到具体场景里才能理解这套机制的实际价值。我以一个真实遇到过的bug为例某个Java后端服务在生产环境偶发空指针日志里只有一行堆栈信息指向OrderService.calculateTotal方法。在没有superpowers之前我让Codex直接分析它给我的回复是可能是order为空加个判空就行然后甩给我一段代码就结束了。这属于典型的猜原因不验证。挂载了superpowers的debugging技能之后同样一个问题AI的行为模式完全不同。它会先触发复现步骤要求我提供完整的堆栈、触发路径、以及是首次发生还是偶发然后检查代码上下文定位order对象的来源接着写一个最小复现测试构造一个order为null或内部字段为null的用例跑测试确认失败之后才提出修复方案并且在修复前就把回归测试加到测试集里。整个流程走下来我的感受是它不像一个生成代码的机器更像一个拿着检查清单工作的工程师。虽然每一步单独看都不难但组合起来就能有效防止AI最常见的那类拍脑袋修复。更重要的是这些步骤不是我盯着它做的是superpowers的SKILL.md替我做完了管理。它输出的结果里包含复现方式、根因分析、修复方案、验证结果四个部分一眼就能看出整个过程是可靠的。3.3 技能是按需读取的所以每个技能可以写得很厚前面说了superpowers采用按需加载机制这带来一个实际好处你不用小心翼翼控制上下文长度技能文件可以写得非常详细。我见过有些技能文件的SKILL.md超过几百行把各种边界情况和分支流程都覆盖了。这在传统一次性system prompt模式下是不可想象的——如果把这些内容全部注入还没开始干活上下文先被消耗大半模型的指令遵循度反而会下降。按需加载还带来一个行为上的改善AI不会因为规则文件太长而选择性忽略。我自己的体会是静态规则文件超过一定长度之后模型实际上只会参考前面一小部分后面的规则经常说了等于没说。但技能文件是在具体场景下被主动读取的模型读取时的注意力是聚焦的执行率明显更高。这也是为什么superpowers的模式比写一个超大规则文件更靠谱的核心原因。4. Codex与superpowers的集成实践AGENTS.md配置与行为差异实测4.1 Codex默认行为里最让我头疼的两件事先说结论Codex本身已经很强了但默认状态下它有几个让我不太放心的行为习惯。第一它倾向于直接动手。拿到一个任务之后它往往会直接开始编辑代码而不是先梳理需求、调整计划。在改动范围小的时候这没问题一旦任务牵扯到多个文件它就容易漏改或者改出边界问题。第二它不太主动跑测试。很多次它改完代码回复已完成但我一跑测试全是红的。这倒不是Codex特别傻而是它缺少一个强制验证的外部约束。我最初试图通过AGENTS.md来解决这个问题写了不少请先写计划请跑测试之类的提示但效果不稳定。原因我在前面也提过静态规则文件在长对话里的约束力会衰减。后来我意识到与其自己写规则不如把superpowers的技能流程通过AGENTS.md挂载进来让Codex在特定场景下按手册办事。4.2 在AGENTS.md里挂载技能的配置示例我用的Codex集成方式和Claude Code的技能目录自动发现不太一样因为Codex这边目前更通用的扩展机制就是AGENTS.md。所以我在项目根目录的AGENTS.md里加了一段技能索引说明把superpowers的技能目录告诉Codex并约定触发条件。下面是我改之后的一个精简示例# 技能索引 本项目的AI助手在开始编码任务前应检查 /Users/you/tools/superpowers 下的技能列表。 按场景启用对应技能并严格遵循其流程 - 当任务需求模糊、涉及多文件改动时先读取 planning/SKILL.md按其中的步骤澄清需求并输出实施计划 - 当出现异常、报错或测试失败时先读取 debugging/SKILL.md禁止在未复现和未分析根因前直接修改源码 - 当准备提交代码或完成一个迭代时先读取 code-review/SKILL.md按其中的检查项做一次自查 - 当需要编写提交信息时读取 commit-writing/SKILL.md按其规范生成提交说明。注意AGENTS.md里的路径要用绝对路径或者相对项目根的稳定路径不然换台机器就失效了。我在集成时踩过一个坑第一次写的是~/tools/superpowers但Codex启动时的工作目录不固定有时候解析不出来后来改成绝对路径才稳定。如果你在团队里共享这个文件建议把技能库路径约定成一个固定的公共目录比如/opt/superpowers之类团队统一遵守。配置完成之后还需要验证一下技能是否真的能被读到。我习惯的做法是开一个新会话故意抛一个简单的报错任务给它然后在对话里让它列出你读取了哪个技能文件。如果它回复里出现了debugging/SKILL.md的路径就说明路由生效了如果它完全没有提到技能那说明AGENTS.md的索引写法有问题需要调整措辞。4.3 集成前后的行为差异我实测的对照表为了确认集成不是心理安慰我特意在同一个项目里、用同样的任务做了几组对照测试。任务包括修复一个单元测试失败、给一个接口新增字段、做一个跨三个文件的代码重构。下面是集成前后的行为对照观察项集成前集成后动手前是否输出计划偶尔输出多数直接改几乎所有多文件任务都会先输出计划面对报错时的处理猜测原因并直接改源码先要求复现、再定位根因最后才动代码修改后是否主动跑测试经常不跑绝大多数情况会运行相关测试交付信息简单说已完成包含改动摘要、验证结果和影响范围返工次数同一问题平均要来回2-3次明显减少约一半任务一次通过说白了Codex还是那个Codex模型能力没有变但行为质量明显上了一个台阶。我后来还试过把superpowers同时挂到Claude Code里两个工具的表现比之前更接近了。这其实也印证了我前面的判断编码助手的上限由模型决定但下限很大程度由流程约束决定superpowers管的就是这个下限。5. 在Java项目里的实战走查从报错信息到测试通过的完整链路5.1 为什么拿Java举例构建工具、强类型与测试体系最考验流程我日常主要做Java后端所以对superpowers在Java项目里的表现体会最深。Java项目相比脚本类项目有一个特点流程必须走完才能交付。你要面对Maven或Gradle的构建、强类型编译检查、JUnit测试、以及Spring这类框架的复杂装配。在这个环境里AI跳过验证直接改代码的代价特别高——很多幻觉在编译期就会暴露但问题是如果AI不主动编译暴露的机会都没有。所以Java项目恰好是检验superpowers流程约束力的最佳场景只要AI严格执行复现-定位-验证-修复-回归这套流程Java的构建工具和测试框架就会自动帮它兜底而如果它想跳过流程Java的编译错误和测试失败会立刻打脸。它逼着AI必须按手册办事没有太多捷径可走。5.2 一次NullPointerException的完整推进记录说到具体案例我分享一个印象比较深的排错过程。当时线上日志频繁出现NPE堆栈指向OrderService.calculateTotal但本地启动又很难复现属于典型的偶发问题。以前我处理这种问题AI助手基本会给出加个判空之类的建议然后自己去改但很难确认根因。接入superpowers之后整个推进变成了下面这样第一步AI先按debugging技能的流程列出需要我补充的信息完整堆栈、方法入参、订单状态枚举、以及复现频率相关的数据。这一步看起来很基础但它把问题从猜变成了查。第二步AI读取了OrderService的源码和关联实体类检查calculateTotal方法里的每个字段引用路径。真正的问题很快暴露出来这个方法直接使用了order.getPayment().getAmount()而payment字段在已下单未支付的状态下是null。第三步AI没有直接改代码而是先写了一个复现测试模拟payment为null的订单Test void calculateTotal_shouldHandleNullPayment() { Order order new Order(); order.setStatus(OrderStatus.CREATED); order.setPayment(null); assertDoesNotThrow(() - orderService.calculateTotal(order)); }测试跑起来果然是红的这说明定位是准确的。第四步才是修复AI把直接取值改成先判空再返回默认值// 修复前 return order.getPayment().getAmount(); // 修复后 return order.getPayment() null ? BigDecimal.ZERO : order.getPayment().getAmount();第五步它跑了一遍完整的mvn test确认原有测试没被破坏然后才输出总结。整个过程中的每一步都有据可查我不用再像以前一样一个个追问你确定吗测试跑了吗。这套链路走完问题在当天就发布了修复之后没再复发。5.3 这套流程在Java项目里的真实收益与边界必须说明的是superpowers不是万能的。Java项目里真正复杂的场景比如多模块依赖之间的循环依赖、带有状态机的事务边界、以及需要跨服务排查的性能问题单靠技能流程并不能直接给出最优方案。技能保证的是过程可靠而不是结果最优。但即便如此它在Java项目里的收益依然非常明显最大变化是AI终于愿意把编译和测试纳入它的工作闭环了。另外还有一个容易被忽略的好处superpowers的code-review技能在高强度类型语言里特别有用。它会让AI在改完代码后自查几个关键点——有没有新增空指针风险、有没有破坏现有接口签名、有没有补测试、有没有引入未使用的依赖。这些检查项在Java里都对应实际代码异味。我后来在团队里推广时很多同事反馈最实用的一点不是AI变得多聪明而是它终于知道改完代码要跑一遍构建再说话了。6. 稳定用了两个月后的避坑清单与个性化调优6.1 坑一技能装全了AI反而陷入选择困难这是我第一个踩到的坑。一开始我把superpowers仓库里的所有技能全部挂上结果发现AI每次拿到任务都要先纠结一下该用哪个技能甚至会在一些简单任务上强行套流程。比如改个变量名它都要先输出一份计划效率反而下降了。后来我把技能目录里不需要的文件夹移走只保留核心几个planning、debugging、code-review、commit-writing以及偶尔用到的subagents。精简之后行为立刻变得干净利落。这个教训让我意识到技能库和依赖库一样不是越多越好。AI在上下文里可用的技能越多路由决策的负担就越重。保留每个阶段真正用得上的技能效果远好于全量加载。6.2 坑二两套规则文件同时生效时容易互相打架我的另一个真实经历项目里原本就有一份比较详细的CLAUDE.md里面写了一些Codex和Claude Code共用的规则比如代码风格请遵循Google Java Format不要使用System.out.println。接入superpowers之后某些技能的指令语气和原有规则冲突。比如技能里要求先写复现步骤再改代码而原有规则写着优先快速给出补丁。AI同时读到两套指令时行为会出现随机性有时候听技能的有时候听原规则的。解决方式很直接在一套规则文件里做整合而不是让多个规则文件并列存在。我只保留AGENTS.md作为唯一入口把原有规则里必要的项目约定合并进去然后通过它来索引superpowers技能。这样AI在面对任务时只有一条决策链路冲突问题没有再犯。6.3 坑三直接改上游技能一升级就冲突前面提到过一次但值得再强调永远不要直接修改clone下来的上游技能文件。我一开始觉得简单的改动不会影响升级结果上游一次目录调整我的本地修改全部变成了冲突块。正确做法是fork一份自己的仓库改动都提交到fork上上游更新后用rebase合并。这个流程对单人使用稍微麻烦一点但对长期维护来说非常值。6.4 几个提升日常使用体验的小技巧分享几个我用了两个月之后沉淀下来的小技巧。第一在AGENTS.md里给技能起明确的动作别名比如使用调试技能、先做代码审查比让AI自己猜测该调用什么技能要可靠得多。第二把技能库里SKILL.md里最关键的禁令句比如禁止在未复现前猜测根因单独摘录到AGENTS.md里。这样即使AI因为某些原因没有读取技能文件这些核心约束仍然留在上下文里。第三团队协作场景下建议把fork后的技能库版本固定下来而不是所有人都去跟上游主分支。我们在团队里直接锁了一个tag等验证稳定后再统一升版避免成员之间技能行为不一致。第四如果你经常用CI做自动审查可以让流水线在PR阶段调用code-review技能做一次AI自查它会自动检查改动里有没有明显缺测试或危险操作相当于给人工review加了一道前置过滤。最后说一个我个人的使用心得superpowers对我来说不是一个装上就变强的开关而是一面镜子。它让我重新审视自己交给AI的任务描述够不够清楚。技能流程触发得越多越说明我在任务拆解上偷了懒。现在我尽量在提问时就把验收标准、环境信息、约束条件写清楚很多情况下AI甚至不需要调用调试技能就能给出正确结果。工具是辅助人和工具配合的方式才决定上限。希望这篇分享对你有用。