1. 从“superpowers”这个热词说起它到底是什么第一次看到“superpowers”这个词挂在热词榜上的时候我下意识以为是某部超级英雄电影又出了续集。点进去翻了半天才发现这波热度其实来自开发者圈子里一个叫Superpowers的开源项目——一套给 AI 编程助手“加装能力模块”的技能框架。说白了它做的事情就是让原本只会聊天、写代码片段的 AI 助手真正具备一整套可复用、可组合、可落地的工程能力。我接触这套东西的契机很偶然。去年年底我在做一个 Java 后端项目代码量不算大但模块特别碎每次让 AI 帮我改一个接口它都要重新理解一遍项目结构改完 A 文件忘了 B 文件来回折腾得我血压升高。后来一个做前端的朋友甩给我一句“你去看看 Superpowers给 AI 装上技能包试试。”我抱着试试看的心态折腾了一个周末结果确实改变了我对“AI 辅助编程”这件事的认知。所以这篇内容我想聊的不是那种“三分钟教你装个插件”的浅层教程而是把我从零开始接触 Superpowers、踩过的坑、想明白的原理、以及最终怎么把它用顺手的完整过程摊开来讲。Superpowers 本质上是一套“技能Skill驱动”的扩展机制它把常见的开发任务——比如代码审查、测试生成、重构、文档撰写——封装成一个个独立的技能模块AI 助手在需要的时候自动调用对应的技能而不是每次都从零开始“即兴发挥”。这篇文章适合几类人看一是已经在用 AI 编程助手、但觉得它“不够聪明”的开发者二是想给自己的 AI 工作流做系统化改造的技术负责人三是单纯被“superpowers”这个词刷屏、想知道它到底值不值得花时间学的人。不管你是 Java、Python 还是前端方向这套思路都是通用的我会尽量把原理讲透把操作步骤写细让你看完能直接上手。2. Superpowers 的核心机制技能包是怎么“长”在 AI 身上的2.1 为什么普通 AI 助手总是“记不住事”要理解 Superpowers 的价值得先搞清楚普通 AI 编程助手的问题出在哪。我用下来的感受是三个字没记性。你跟它说“这个项目用 Spring BootController 层不要写业务逻辑”它当时答应得好好的下一轮对话又忘了。这不是模型笨而是它的工作方式决定的——每次对话都是独立的上下文它没有一个“持久化的能力层”来承载你的项目规范和历史经验。打个比方普通 AI 助手就像一个临时雇来的外包每次来都要重新给他讲一遍项目背景、代码规范、目录结构。而 Superpowers 想做的是给这个外包配一本随时可查的操作手册手册里写满了“遇到 X 情况就按 Y 流程做”的技能条目。AI 在干活的时候会主动翻这本手册而不是凭记忆瞎猜。这个“手册”在技术上的实现就是一组结构化的技能定义文件。每个技能包含触发条件什么情况下用这个技能、执行步骤具体怎么做、输出规范结果长什么样。AI 助手在接到任务时先匹配技能再按技能里定义的流程执行。这就把“即兴发挥”变成了“按流程办事”稳定性提升非常明显。2.2 技能Skill的组成结构拆解我拆过几个官方和社区贡献的技能包结构其实不复杂核心就是几个部分。理解了这个结构你自己也能写技能。组成部分作用实际例子技能名称与描述让 AI 快速判断“这个技能是干嘛的”“Java 接口重构将冗长方法拆分为职责单一的小方法”触发条件定义什么场景下激活该技能检测到方法超过 50 行、圈复杂度过高执行步骤分步骤的操作指令1. 识别方法职责 2. 提取独立逻辑 3. 生成新方法签名约束与规范防止 AI 跑偏的硬性规则不改变原有对外接口、保持异常处理逻辑输出模板规定结果的格式输出 diff 格式的代码变更 变更说明这个结构看起来简单但真正让它好用的关键在于触发条件的精准度。触发条件写得太宽AI 会到处乱用技能写得太窄该用的时候又用不上。我自己的经验是触发条件最好绑定到具体的代码特征或任务关键词上而不是模糊的语义描述。2.3 技能之间如何组合与编排单个技能解决单点问题但真实开发任务往往是复合的。比如“给一个老接口加新功能”这件事其实包含了理解现有代码、设计新逻辑、写实现、补测试、更新文档。Superpowers 允许把这些技能串成流水线前一个技能的输出作为后一个技能的输入。我实测下来这种编排能力是它区别于普通“提示词模板”的核心。提示词模板是静态的你复制粘贴一次就完了而技能编排是动态的AI 会根据当前任务自动决定调用哪几个技能、以什么顺序调用。这背后其实是一套任务分解与调度逻辑也是我觉得这套框架最有技术含量的地方。提示技能编排不要贪多。我一开始恨不得把十个技能串在一起结果 AI 在中途就“迷路”了输出质量反而下降。后来改成“单次任务最多串三个技能”稳定性好了很多。3. 安装与环境准备那些文档里不会写的细节3.1 安装前的环境自查清单网上搜“superpowers 安装”大部分教程都是直接甩命令但我要说的是环境没准备好装了也是白装。我在第一次安装时就是因为 Node 版本不对折腾了两个小时才找到原因。下面这份清单是我踩坑之后总结的建议装之前逐条核对。运行时版本Superpowers 的技能加载器对 Node.js 版本有要求我实测 18.x 和 20.x 都稳定16.x 会出现技能解析失败的问题。用node -v先确认。包管理器npm 和 pnpm 都行但如果你项目里混用了两者容易出现依赖树冲突。建议统一用一个。AI 助手的接入方式这是最容易被忽略的一点。Superpowers 本身不绑定特定的 AI 助手它通过标准接口对接。你需要先确认自己用的助手支持哪种接入协议。磁盘权限技能文件默认会写入用户目录下的配置文件夹如果你在公司电脑上有权限限制提前确认能不能写入。网络环境首次安装需要拉取技能仓库确保能正常访问包源。3.2 安装步骤的逐条拆解环境确认没问题之后安装本身其实很快。但我还是把每一步的意图讲清楚这样你遇到报错时知道该往哪个方向查。第一步是初始化项目配置。在项目根目录执行初始化命令它会生成一个配置文件记录你这个项目要用哪些技能、技能仓库地址在哪。这一步的关键是选对项目类型因为不同类型的项目默认加载的技能集不一样。Java 项目会默认带上接口设计、单元测试相关的技能前端项目则会带上组件拆分、样式规范相关的技能。第二步是拉取技能仓库。Superpowers 的技能是集中托管在仓库里的安装时会根据你的配置拉取对应技能。这里有个坑如果你的网络拉取大仓库比较慢可以只拉取你需要的技能子集而不是全量拉取。全量仓库有几百个技能大部分你根本用不上还拖慢加载速度。第三步是验证安装。执行验证命令后它会列出当前已加载的技能清单。如果清单是空的说明技能仓库没拉下来或者路径配错了。这时候别急着重装先去看配置文件和日志八成是路径问题。# 初始化项目配置示意 superpowers init --type java-backend # 拉取技能仓库可指定子集 superpowers pull --skills code-review,test-gen,refactor # 验证安装列出已加载技能 superpowers list3.3 安装后必做的三项验证装完不代表能用。我养成的习惯是装完立刻做三个验证确认这套东西真的“活”了。第一个验证是技能加载验证。用list命令看技能清单确认你需要的技能都在。如果某个技能显示为“未激活”通常是它的依赖没满足比如某个技能依赖代码解析器而你没装。第二个验证是触发验证。随便找一段代码让 AI 助手执行一个应该触发技能的任务看它有没有按技能流程走。比如你让 AI 审查一段有明显坏味道的代码如果它调用了代码审查技能输出里会带上技能定义的检查项清单而不是泛泛而谈。第三个验证是输出格式验证。技能定义的输出模板是否被正确应用直接决定了结果能不能直接用。我见过有人装完技能后AI 输出还是一团乱原因就是输出模板没生效这时候要检查技能文件里的模板配置有没有被正确解析。注意三个验证里触发验证最重要。技能加载了但触发不了等于没装。触发不了通常是触发条件写得太死或者 AI 助手的意图识别没匹配上可以手动调整触发条件的关键词。4. 上手实操用 Superpowers 改造一个真实的 Java 项目4.1 场景设定一个典型的“祖传代码”困境光讲原理没意思我拿一个真实场景来演示。我手上有个 Java 项目是几年前别人写的典型的“祖传代码”一个OrderService类塞了两千多行里面什么逻辑都有——下单、改价、退款、发通知、写日志全挤在一起。每次改一个功能都要在这个巨型类里翻半天改完还容易碰坏别的地方。我的目标很明确在不改变对外接口的前提下把这个类拆开让职责清晰起来。这种重构任务如果纯手工做保守估计要两三天而且容易出错。用 Superpowers 的技能来做我的预期是半天内搞定主体重构剩下的时间用来验证。4.2 第一步让 AI 先“读懂”项目结构重构最怕的就是 AI 没读懂代码就动手。所以我第一步不是让它改而是让它分析。Superpowers 里有个“代码结构分析”技能触发之后AI 会扫描指定目录输出一份结构报告有哪些类、类之间怎么调用、哪些方法是“热点”被调用次数多、哪些方法是“孤岛”没人调用。这一步的价值在于它把“重构决策”建立在数据上而不是凭感觉。报告出来之后我发现那个两千行的类里真正核心的下单逻辑只占三百行剩下的大部分是各种辅助逻辑和重复代码。这就给了我拆分的方向核心逻辑保留辅助逻辑抽成独立服务重复代码合并。我特别想强调这一步的必要性。很多人用 AI 重构上来就说“帮我把这个类拆了”结果 AI 拆出来的结构完全不符合项目实际还得推倒重来。先分析、再动手这个顺序不能反。4.3 第二步用重构技能做方法级拆分分析报告出来后进入实际拆分阶段。我用的重构技能触发条件是“检测到方法行数超过阈值或职责不单一”。它会做几件事识别方法的实际职责、找出可以独立出去的逻辑块、生成新的方法签名、保持原有调用关系不变。这里有个细节值得说技能执行时会先生成一份“变更预览”而不是直接改代码。预览里会列出“准备把哪段逻辑移到哪个新方法”我确认没问题之后才让它真正执行。这个“预览-确认-执行”的流程是我觉得 Superpowers 比直接让 AI 改代码靠谱的地方——它给了你一个刹车。拆分过程中我遇到一个典型问题有些逻辑块之间有隐式的状态依赖比如 A 方法改了某个成员变量B 方法依赖这个变量。技能在拆分时会检测这种依赖如果检测到它会提示“该逻辑块存在状态耦合建议先解耦再拆分”。这个提示帮我避免了好几个潜在的 bug。4.4 第三步补测试锁住重构后的行为重构最怕的是“改完看着没问题一跑就崩”。所以拆完之后我立刻用测试生成技能给拆分出来的新方法补单元测试。这个技能的触发条件是“新增或修改了方法且缺少对应测试”。它生成的测试不是那种“为了覆盖率而写”的空测试而是会针对方法的边界条件、异常路径、正常路径分别生成用例。比如一个计算订单金额的方法它会生成正常金额计算、金额为零、金额为负、金额超上限这几类用例。我跑了一遍还真发现了一个拆分时引入的边界 bug——某个方法在金额为零时返回了 null 而不是 0。这一步让我彻底改变了对“AI 写测试”的看法。以前我觉得 AI 写的测试都是摆设但配合技能框架之后它生成的测试是有针对性的能真正起到“行为锁定”的作用。4.5 第四步生成重构说明文档重构做完还有一件容易被忽略但很重要的事留下变更记录。我用的文档生成技能会根据本次重构的 diff 自动生成一份说明包括改了哪些类、每个类的新职责是什么、对外接口有没有变化、有哪些需要注意的兼容性问题。这份文档的价值在团队协作里特别明显。你重构完同事 review 的时候不用逐行看代码先看这份说明就能抓住重点。而且过几个月你自己回头看也能快速回忆起当时为什么这么改。5. 技能选型与自定义别被“官方技能”绑死5.1 官方技能和社区技能的取舍Superpowers 的技能来源有两类官方维护的核心技能和社区贡献的扩展技能。我的建议是核心技能必装社区技能按需装。官方核心技能覆盖的是通用场景代码审查、测试生成、重构、文档。这些技能经过较多验证稳定性好触发条件也调得比较准。社区技能则五花八门有做特定框架适配的有做特定语言优化的质量参差不齐。我装过几个社区技能有的确实好用有的触发条件写得一塌糊涂动不动就误触发最后只能卸掉。判断一个社区技能值不值得装我的标准是三条看它的触发条件是否具体、看它的输出模板是否规范、看它的最近更新时间。三条里有一条不满足我就先不装观望一阵再说。5.2 什么情况下该自己写技能用了一段时间之后我发现有些项目特有的规范官方和社区技能都覆盖不到。比如我们团队有个约定所有对外接口的返回值必须包一层统一的结果对象不能直接返回实体。这种团队规范通用技能是不管的。这时候就得自己写技能。写技能没想象中那么难本质就是把“你平时口头交代给 AI 的话”结构化下来。我写第一个技能花了大概一个小时内容包括触发条件检测到新增或修改了 Controller 方法、执行步骤检查返回值类型、如果不是统一结果对象则包装、约束不改变方法名和参数、输出变更后的代码 说明。自己写技能最大的好处是把团队规范固化下来。以前新人来了要口头讲半天现在技能一装AI 自动按规范执行省了大量沟通成本。5.3 自定义技能的调试与迭代自己写的技能第一版几乎不可能完美。我的经验是先小范围试再逐步放开。第一版技能写好后先在一个小模块上试看触发是否准确、输出是否符合预期。有问题就改触发条件或执行步骤改完再试。调试技能有个技巧把技能的触发日志打开。Superpowers 可以记录每次技能触发的详细信息包括“为什么触发”“匹配了哪个条件”“执行了哪几步”。看日志能快速定位问题——是触发条件太宽导致误触发还是执行步骤有歧义导致 AI 理解偏了。我迭代一个技能通常要改三到五版才能稳定。第一版解决“能不能用”第二版解决“准不准”第三版解决“快不快”。别指望一次写好把它当成一个需要持续打磨的小工具。6. 常见问题排查我踩过的那些坑6.1 技能不触发或误触发这是最高频的问题。技能该触发的时候不触发不该触发的时候乱触发都会让人抓狂。不触发的常见原因有三个触发条件的关键词和实际任务描述对不上、技能依赖的解析器没装、AI 助手的意图识别没匹配上。排查顺序是先看触发日志确认是“没匹配到条件”还是“匹配到了但没执行”。如果是前者调整触发条件的关键词如果是后者检查技能依赖。误触发的原因通常是触发条件写得太宽泛。我写过一个“代码优化”技能触发条件只写了“检测到代码”结果 AI 看到任何代码都想优化连正常的代码也要改。后来把条件收窄到“检测到重复代码块或明显的性能反模式”误触发就少多了。6.2 技能执行结果不符合预期技能触发了但输出不是你想要的这种情况也常见。原因可能是执行步骤描述有歧义AI 理解成了另一个意思也可能是约束条件不够硬AI 中途“自由发挥”了。我的处理办法是先看输出和预期的差距在哪然后回到技能定义里找对应的步骤或约束把它写得更具体。比如“保持代码风格一致”这种模糊的约束AI 根本不知道你指的是什么风格得改成“缩进用 4 空格、方法名用驼峰、常量全大写”这种可执行的规则。6.3 多个技能冲突怎么办当你装了很多技能可能会出现两个技能同时想处理同一个任务的情况。比如“重构技能”和“优化技能”都检测到了同一段代码都想动手结果互相打架。解决办法是给技能设置优先级。Superpowers 允许在技能定义里指定优先级优先级高的先执行执行完的任务不会再被低优先级技能重复处理。我一般把“分析类”技能设高优先级“修改类”技能设中优先级“格式化类”技能设低优先级这样流程就顺了。问题类型典型表现排查方向解决手段不触发任务执行了但没走技能流程看触发日志调整触发关键词误触发不该用技能的地方用了看触发条件宽度收窄触发条件输出不符走了技能但结果不对看执行步骤和约束细化步骤描述技能冲突多个技能抢同一任务看技能优先级设置优先级顺序6.4 性能问题技能多了会不会变慢会。技能加载和匹配都是要耗资源的装了几百个技能之后AI 助手的响应速度会明显下降。我的做法是按项目配置技能集而不是全局装一堆。这个项目用 Java就只装 Java 相关的技能那个项目用前端就只装前端技能。这样每个项目的技能集都很精简速度快也不容易冲突。另外定期清理不用的技能也很重要。我每个月会 review 一次技能清单把三个月没用过的技能卸掉。技能不是越多越好够用就行。7. 把 Superpowers 用出“超能力”的几个心得7.1 从“让 AI 干活”到“让 AI 按流程干活”用 Superpowers 最大的思维转变是从“让 AI 干活”变成“让 AI 按流程干活”。以前我用 AI是丢一个任务过去等它给我一个结果结果好不好全看运气。现在我是先想清楚“这件事应该分几步做、每步的输入输出是什么”然后把这些流程固化成技能让 AI 按流程执行。这个转变带来的最大好处是结果可预期。流程固定了输出质量就稳定了不会今天好明天坏。而且流程本身是可以优化的你觉得哪一步效果不好改那一步的技能定义就行不用推倒重来。7.2 技能库是需要“养”的技能库不是装完就完事它需要持续维护。我的做法是每次遇到 AI 做得不好的地方就想想能不能用一个技能来固化正确的做法。比如我发现 AI 老是忘记给新方法加日志就写了个“日志检查”技能触发条件是“新增了方法且方法体超过十行”执行步骤是“检查是否有日志输出没有则补充”。这样日积月累技能库就越来越贴合你的实际需求。半年下来我攒了二十多个自定义技能覆盖了从代码规范到部署检查的各个环节。现在新项目一启动把这套技能库挂上去AI 助手立刻就有了“我们团队的做事风格”。7.3 别把技能当“银弹”最后说点泼冷水的话。Superpowers 是个好工具但它不是银弹。它解决的是“AI 执行任务时的稳定性和规范性”问题解决不了“AI 根本不会做某件事”的问题。如果某个任务本身超出了 AI 的能力边界装再多技能也没用。我的判断标准是如果一件事你自己都说不清楚步骤那就别指望技能能帮你做好。技能的本质是把“清晰的流程”固化下来流程本身不清晰固化出来的也是垃圾。所以用 Superpowers 之前先花时间把你要解决的问题想清楚把步骤理明白这比装什么技能都重要。我在实际使用中最大的体会是这套东西的价值不在于它自带的技能有多强而在于它提供了一种把个人经验结构化的方法。你把自己的经验写成技能AI 就能按你的经验干活团队把规范写成技能AI 就能按团队规范干活。这种“经验的可复用化”才是它真正有意思的地方。