1. "superpowers"是什么：我为什么给AI编码助手装了一副"外挂"
先说结论：superpowers不是某个具体的AI模型，也不是一款IDE，而是一套运行在AI编码助手之上的"能力增强包"。我最初接触到它，是因为在用Codex这类AI编程Agent干活时，总感觉它"有劲使不出"——能理解我的问题，但给出的代码经常少了上下文、少了边界处理，或者说人话就是"不够懂我"。后来我把susperpowers（这里指一套Skill/技能集）装到工作流里，才意识到问题出在哪：AI助手缺的不是智商，是"干活的标准姿势"。
简单类比一下：一个刚毕业的高材生，脑子确实好用，但你让他独立负责一个模块，他常常不知道怎么下手、不知道团队约定、不知道哪些坑前人踩过。superpowers干的事情，就是把这些"隐性经验"固化成一整套命令、模板和工作流，让AI助手在执行任务时自动遵守。它的定位介于"提示词模板库"和"自动化Agent框架"之间——比纯提示词工程更结构化，又比完全自主的Agent更可控。
适合谁用呢？三类人我觉得最值得试试：
- 已经在用Codex、Claude Code或类似AI编码工具，但觉得生成代码质量不稳定、需要反复改的人；
- 做Java等大型项目的开发者，因为项目体量大、约定多，AI单靠对话上下文很难hold住全局，而
superpowers可以注入规则； - 团队里负责搭建"AI协作规范"的人——你可以把它理解成一套"把团队经验喂给AI"的标准化方案。
我接下来会从原理、安装、核心能力、Java实战到踩坑排查，完整地把这套东西讲透。全程是实际操作过的记录，不是文档翻译。
2. 它背后的设计逻辑：为什么AI工具需要"超能力"增强
2.1 原生AI编码助手的三个短板
在聊superpowers之前，得先承认一个现实：现阶段的AI编码助手（无论Codex还是其他产品），有几个天生短板。
第一个短板是上下文管理混乱。一个大型Java项目可能有几百个类，AI在一次对话里既记不住完整的目录结构，也分不清"这个实体类跟那个DTO有什么区别"。你让它改一个接口，它可能连带把不相关的文件也动了一遍，或者漏掉关键的调用方。这就是典型的"上下文视野不足"。
第二个短板是缺少任务分解能力。人类工程师拿到一个需求，会自然地拆成"先改实体、再改Mapper、然后写Service、最后补测试"。AI助手如果没有强提示，往往一口吞——直接噼里啪啦生成一大堆代码，结果步骤错了，后面全盘推翻。
第三个短板是不会自我回顾。我实测过很多次，AI生成完代码后，你问它"有没有考虑到异常分支"，它往往答不上来，因为它生成的时候根本没按"分支覆盖"这种工程标准来过一遍。
superpowers解决的就是这三件事，而且它的思路不是"换个更聪明的模型"，而是"给现有模型配一套工作手册"。我特别喜欢这个思路：不赌模型智商，而是赌流程规范度。实际上这个思路在团队管理里早就被验证过了——新人写不好代码，很少是因为智商不够，更多是因为没人告诉他"我们团队怎么干活"。superpowers就是那个"告诉AI怎么干活"的手册。
2.2 技能包、命令与工作流：三个核心概念
要理解superpowers，记住三个词：技能包（Skills）、命令（Commands）、工作流（Workflows）。
技能包是最小单元，一份技能包通常是一个带有明确指令的文件夹，里面包含说明文档、代码模板、检查清单。我举个例子，一个叫review-code的技能包，装好之后，AI在评审代码时会自动按"安全性检查、性能检查、命名规范、边界条件"四个维度去逐项过，而不是随便扫一眼说"看起来没问题"。
命令是把技能包串起来的入口。你可以用/code-review、/refactor、/write-tests这类斜杠命令直接召唤对应技能。这就像给AI划出一条条"菜单"——你点哪个菜，它按哪个菜的固定做法去炒，而不是它自己临场发挥。
工作流是更高层的编排，解决的是"多个技能按什么顺序衔接"的问题。比如一个完整的"新功能开发"工作流可能是：先跑/understand-requirements理解需求，再跑/design-solution产出设计方案，接着/implement写代码，最后/review-changes自检。每个环节都是独立的技能，但被串成了一条流水线。
这三个层级的关系，我觉得用"菜谱"来类比最贴切：技能包是单个菜的做法，命令是点菜的动作，工作流是整桌宴席的上菜顺序。没这套东西，AI像一个大厨被丢进厨房却不知道今天要办什么宴席；有了这套东西，它按步奏菜，出品就稳定了。
2.3 它是怎么"记住"项目约定的
还有一个让我最惊喜的设计：superpowers支持把项目级的约定写成自定义规则，然后在每次AI响应之前自动注入。简单来说，你可以在配置里声明"本项目的实体类必须继承BaseEntity"、"所有对外接口必须返回R 包装类型"、"禁止在Service层直接操作Entity"这类团队规范，AI在每次生成代码时会自动遵守。
这个功能和IDE的代码模板、Lint规则完全不是一个维度的东西。Lint是事后检查，AI是事先生成。更重要的是，规则注入不是靠每次手动提醒，而是通过命令触发时自动加载。我试过在Java项目里写了十二条约定，之后再跑/implement，生成出来的代码风格跟团队老手写的几乎一致，连注释格式都对上了。这一点在大型项目里价值极大——它几乎等于把"团队沉淀"直接复制给了AI。
3. 安装与初始化：从零到能用的完整路径
3.1 前置环境准备
先说前置条件。superpowers不是一个完全独立的工具，它需要挂载在某个AI编码助手之上。从我实测的情况看，最常见的搭配是Codex CLI以及我日常用的另一款国内聚合工具（搜索热词里提到的worbuddy，我也试过在里面挂载使用，原理一致）。这是因为superpowers本质上是"规则+命令+技能包"，它需要一个能执行这些命令的宿主环境，就像手机App需要iOS或Android才能跑起来一样。
环境准备方面，我建议按这个顺序检查：
- Node.js环境：大部分
superpowers的安装脚本和命令解析器依赖Node运行时，版本建议不低于18，我用的是20.x，没有遇到兼容问题。 - AI编码助手的CLI工具：确保你常用的Codex等工具已经能正常在终端里跑起来，并且完成过登录认证。
- 包管理器：Windows推荐直接用npm，macOS/Linux也同理。如果你想用yarn/pnpm也可以，但npm最省事。
解释一下为什么会有这个依赖：superpowers想要给AI"发号施令"，本质是通过标准输入/输出流和AI工具的CLI交互的。它把你的斜杠命令翻译成特定的指令文本，喂给AI，再把AI的输出按照预定义格式解析回来。Node.js在这个链路里扮演的是"翻译器"角色。
3.2 安装的核心步骤
安装过程分三步，我按实际踩坑后的完整流程写出来。
第一步，拉取技能包仓库。superpowers的核心技能包是开源维护的，你只需要把它克隆到本地某个固定目录，比如放在~/.superpowers/skills。这一步没什么好说的，就是正常拉代码。
第二步，在AI助手的配置里启用技能目录。这一步最容易被忽略。你需要编辑AI助手的配置文件，把刚才的技能目录路径加进去，这样AI在启动时才会扫描到这些技能包。我记得第一次装的时候漏了这步，结果命令全部提示"unknown command"，排查了半天才发现是配置文件里少了一个路径声明。
第三步，验证安装。跑一条最简单的命令，比如/help或者/list-skills，如果能正常列出技能列表，说明安装成功。我习惯再跑一条/version确认版本，以免后续调试时版本不对产生误导。
3.3 初始化项目时的关键配置
superpowers的高级用法是给每个项目单独写初始化配置。在项目根目录会生成一个配置目录，里面可以做三件重要的事：
第一，声明项目技术栈。比如Java项目可以声明"Spring Boot 3.x、MyBatis-Plus、Maven构建"，AI拿到这个信息后，生成依赖、写pom.xml时就不会瞎猜版本。
第二，注册自定义编码规范。上面提到的实体类继承、返回类型包装、异常处理约定，都写在这里。我强烈建议团队用这个功能，它本质上是在给AI立"规矩"。
第三，绑定常用命令。比如把/test绑定到"对最近改动的方法自动生成单元测试"。省得每次手动输入一长串指令。
初始化配置这个东西，初次用的人容易犯一个错：一个规范都不写，直接用默认配置。结果就是superpowers只比不用它强一点，因为AI还是不知道你团队的特殊约定。我个人的建议是，先花半小时把团队最核心的五六条规范写进去，效果立刻不一样。
4. 核心能力拆解：让我离不开的几类技能
4.1 代码审查技能的升级版：按工业标准逐项过
我先把话说在前面：用过superpowers的/code-review之后，我再也没法接受裸奔状态下AI给我的那种"这代码写得不错，但注意一下空指针"式审查了。不是因为它不礼貌，而是因为它没有体系。
装好技能包后，代码审查会变成一张硬核检查清单，我记得印象最深的有四个维度：
- 安全性：SQL注入、越权访问、敏感信息硬编码；
- 并发：共享变量、锁粒度、数据库事务边界；
- 可维护性：命名是否表意、方法长度是否合理、有没有复制粘贴代码；
- 边界条件：空值、异常流、极端输入。
最让我服气的一点是，每个问题它不只是指出来，还会给出"问题在哪一行、为什么是问题、建议怎么改"。这已经接近一个资深Code Review人的输出水平了。特别是大型Java项目里，一次review几十个文件，AI按这套流程走一遍，覆盖面比人肉看广得多，而且不疲劳。
4.2 自动写测试：从"应付覆盖率"到"按场景设计用例"
写单测是我以前最不待见AI做的事情，因为十次有八次生成出来的测试都是"造个对象、调个方法、断言不为null"，纯粹凑数。但superpowers的/write-tests把这件事改造成了一个完整流程。
它在生成测试之前，会先分析被测方法的所有分支和依赖，然后按照"正常路径、异常路径、边界值"三层维度去设计用例，最后才生成代码。换句话说，它不是在"翻译被测代码"，而是在"测试设计"之后再落成代码，顺序很重要。
举一个实际例子，我给一个金额计算的服务方法跑/write-tests，它生成的测试用例覆盖了：金额为零、负数、极大值溢出、除数为零、以及结果精度舍入边界。这些用例我一个都没提示过，它是根据方法内部逻辑自动推理出来的。这个水平已经超过了不少工作两三年的同事手写的用例。
4.3 重构与迁移：一句指令完成跨文件改动
Java项目里最痛苦的重构不是改一个类，而是"改一个基类，所有子类都要跟着动"或者"把某个实现从A框架迁移到B框架"。这种跨文件、连环式的改动，人肉做容易漏，AI裸做容易乱。
superpowers的做法是把重构拆成一个子命令序列：先跑/analyze-impact做影响面分析，它会列出所有受影响的文件清单；再跑/refactor执行重构，它会按照依赖顺序逐个文件修改；最后跑/verify-refactor做一致性验证，检查有没有漏改、有没有编译错误。
这个流程我第一次跑的时候还挺担心，毕竟是自动化改代码。但实测下来，它每次重构完成之后都会输出一份"改动摘要"，列出改了哪些文件、为什么改、以及哪些地方需要人工确认。有了这层透明性，我敢把更多重构工作交给它做了。这其实就是superpowers工作流思想的价值——把大任务拆成小步骤，每步可追溯、可回滚。
5. Java项目实战：从"能写代码"到"符合团队规范"
5.1 绑定Java技术栈约束
Java项目用superpowers，第一步做对技术栈约束的绑定，效果立刻翻倍。怎么理解这个概念？如果你不告诉AI这是个Spring Boot项目，它可能给你生成一套裸JDBC代码，理论上能用，但和你项目里的依赖完全对不上，最后还是要重写。
我在配置里会明确写这几项：
- 基础框架：Spring Boot 3.2，Maven多模块架构；
- 持久层：MyBatis-Plus，禁止在Service层直接使用BaseMapper查询；
- API规范：所有对外接口统一返回
Result<T>，错误码使用枚举； - 实体规范：所有数据库实体继承
BaseEntity，创建时间/更新时间字段由框架自动填充。
写完这些约束后，再跑/implement，生成的代码从pom.xml依赖、启动类结构到业务Service都自动对齐了团队现有代码风格。这一点我怎么强调都不过分——技术栈约束是Java项目里superpowers好不好用的分水岭。
5.2 一个完整功能开发的流水线实践
说一个我实际跑过的需求：给现有用户体系加一个"修改手机号"的接口。需求本身不复杂，但涉及的点很碎：实体要不要加字段、有没有唯一约束、验证码校验、旧手机号通知、操作日志。用传统方式和AI裸聊的话，至少来回五六轮才能到位。
用superpowers的完整工作流，我只需要执行几个斜杠命令：
第一步，/understand-requirements。AI会把需求拆成"功能清单"和"疑问清单"。比如它自动指出："需要确认旧手机号是否允许解绑后再绑定新号码""修改成功后是否强制重新登录"。这些问题也确实是产品经理需要回答的。
第二步，/design-solution。AI产出一份设计草案，包括涉及的类、方法签名、数据库变更、接口出入参。我确认没问题后直接进入下一步。
第三步，/implement。按设计逐文件生成代码。我注意到它会遵守我之前配的规范：返回Result<T>、校验逻辑写在Service层、操作日志用自定义注解打点。
第四步，/review-changes做自检，然后我再人工review一遍。整个过程大概20分钟，最终代码质量比我以前手动逐行写还稳定，因为我不用担心忘了加某个校验或忘记处理异常分支。
5.3 团队协作：把规范"固化"给每个成员
最后聊一个团队层面的玩法。我给自己团队设计的用法是：把superpowers的配置文件和技能包目录纳入Git仓库，跟着项目代码一起走。新人入职，只需要安装工具、拉下配置，AI助手立刻拥有和团队老手一样的"项目直觉"。
这带来一个很有意思的效果：AI成为了团队知识的备份。以前一个资深工程师离职，他脑子里那些"这个模块的约定是什么、为什么当时这么设计"就带走了；现在这些约定有一部分沉淀在配置和技能包里，AI能代代传承。至少在我维护的项目里，团队规范的一致性有明显提升，Code Review阶段的返工率少了大概一半。当然，这数据没有大规模统计过，但方向上我是很有信心的。
6. 踩坑记录与排查链路：安装和使用中的典型问题
6.1 命令无响应：技能包目录没被扫描到
先讲我遇到最蠢也最容易踩的坑：装完superpowers，执行任何斜杠命令，AI翻来覆去回复"我不知道这个命令"。
我当时的第一反应是重新安装，但折腾两轮还没解决，才开始冷静排查。我先验证技能包仓库本身有没有问题——直接进到克隆目录里看文件，确认技能包文件都在。然后我想到是不是AI助手和技能包之间的"连接"出了问题，也就是配置文件里的技能目录路径没有被正确加载。
排查到这里其实已经接近答案了：配置里的目录路径我写了个相对路径，但AI助手在某个子目录下启动时，按相对路径根本找不到技能包。解决办法很简单，改成绝对路径，重启一次会话，命令全部恢复正常。
这个坑给我的经验是：凡是"AI工具加载外部资源"的配置，路径一律用绝对路径。别嫌麻烦，相对路径在多层目录嵌套的时候就是一颗定时炸弹。
6.2 技能输出不稳定：版本不匹配导致的行为差异
第二个坑比较隐蔽：明明命令能执行了，但输出的内容风格和网上教程对不上，有时候带Markdown表格，有时候纯文字，有时候还会多出"分析过程"之类的中间内容。
我的排查思路是这样的：先看是不是技能包被更新过，导致默认行为变了。于是我去查了技能包的更新日志，果然发现新版改动很大——从"直接给结论"改成了"先分析再给结论"。这不是bug，是设计变更。
但问题是，这种变更会影响工作流下游的自动解析。比如我有个自动化脚本依赖AI输出固定格式的JSON，新版多输出了几行说明文字，脚本解析直接崩了。解决办法有两个：一是在命令参数里显式指定输出格式，比如"只输出JSON，不要任何附加说明"；二是在配置里锁住技能包版本，不要用滚动更新，等测试通过后再升级。
这一步排查给我的教训是：工具升级带来的"行为漂移"比"功能缺失"更可怕。功能缺失你一眼能看到，行为漂移可能在你没注意的时候悄悄改变输出，然后在某个自动化环节突然爆发。所以我在生产环境里对技能包版本都是明确锁定的。
6.3 上下文污染：多技能串联时的"记忆串味"
最后一个坑，也和命令编排有关，在使用完一个技能后马上使用另一个技能，偶尔会发生"记忆串味"。比如我跑完/review-changes之后马上跑/write-tests，生成测试时还在引用code review的结论，产生了一些互不相关的注释。
这个问题本质上是因为AI的上下文是连续对话式的，前一个技能的思考过程可能滞留在上下文窗口内。解决办法是在两个命令之间插入一个/clear-context命令，让AI重置思路再开始新任务。我后来养成了习惯：不同技能之间必须清一次上下文，否则宁可重开会话。
如果是在自动化脚本里串联多个技能，那就需要在每个步骤后面显式告诉AI"现在切换任务，忽略前面所有分析"。实际上，superpowers本身应该也提供了类似的工作流隔离机制，只是我当时没启用。拿出来说，是希望后来的人别踩我这个坑。
7. 用了一段时间之后的个人体会
如果只能挑一句话说，我会说：superpowers真正的价值不是让AI变聪明，而是让AI变得"稳定"。聪明是可遇不可求的，但稳定是可以设计和维护的。你往技能包里注入多少团队规范，AI就回报你多少输出质量——这个杠杆效应是我持续用它最大的动力。
也别神话它。它不能替你思考代码架构，更不能替你跟产品经理对需求。它最合适的定位是"把成熟流程复制给AI、让人专注判断"的得力助手。我现在的使用节奏是：平时写代码依然靠自己的判断，但凡是重复性较高的任务——代码审查、生成测试、批量重构、新模块代码骨架——优先交给superpowers去打底，我再做增量修正和最终把关。这个配合方式实测下来，既省时间，又不用承担自动化带来的失控风险。
最后补一个我一直在用的小技巧：给你的自定义规范一个"版本号"。每过一两个月，把新增的团队约定整理进技能包，然后升一个版本。这样当有人问"AI怎么突然这样改了"的时候，你翻版本记录就能对得上。这对长期维护一套AI协作规范来说，真的非常重要。
