1. 先搞清楚Superpowers到底解决了什么问题前几天有个朋友问我说他照着网上的教程把Codex装好、配上模型兴冲冲地让它改一个遗留项目的Bug结果Codex改出来的代码风格和项目里其他代码完全不在一个频道上甚至还把一个接口的兼容性改坏了。他一脸困惑地问“这工具不是号称能顶一个初级工程师吗怎么连基本的项目规范都守不住”这个问题我太熟悉了。大部分AI编程工具刚装好的时候其实处于一种“裸奔”状态——它们模型很强但你项目里的隐性规则、团队约定、历史包袱、目录结构、依赖关系它一概不知道。你让它干活它就只能靠通用的编程常识硬猜。这就是为什么很多人用AI越用越累改十次、返工八次最后还得自己动手。Superpowers这套东西本质上就是专门解决这个“裸奔”问题的。它不是某个大厂出的官方插件而是社区里逐渐成型的一套增强方案核心思路非常朴素在AI编码工具真正干活之前先给它配齐“岗位说明书”“项目手册”和“技能训练包”让它带着项目常识去动代码。你可以在很多开源仓库里找到它的不同实现版本有的直接把技能写进仓库目录有的配了一套自动化引导脚本但它们解决的问题都是一样的就是那个朋友遇到的“AI很强但在我的项目里很蠢”的问题。如果你正在用Codex、Cline这类AI编程助手并且不满足于简单的问答式辅助而是想让AI真的参与到日常开发里、按团队标准产出代码——那这篇内容值得你花十分钟看完。下面我会从安装前的准备、核心机制、Java实战到避坑经验把Superpowers的完整用法拆开讲一遍。2. 安装前的准备工作环境与版本选择2.1 你需要的最小环境先说硬性前提。Superpowers类是直接跑在AI编程工具之上的增强层所以你至少需要一台能正常联网的开发机操作系统不限Windows、macOS、Linux都行但它依赖的命令行工具略有差异已经安装好一个AI编程CLI工具比如Codex CLI、Cline的CLI模式或Claude Code并且能正常对话本机装有Git因为大部分技能模板、规则文件都是通过Git仓库拉取的如果是Java项目还需要确认JDK和Maven/Gradle已经在PATH里否则后面运行验证会卡住。之前看到有人在Windows的PowerShell上安装时碰壁原因是脚本用了Linux风格的路径拼接。如果你也是Windows用户建议优先用Git Bash来跑安装脚本而不是直接怼在cmd里。这个细节很多教程不会提但实测下来能省不少事。2.2 安装方式与版本选择安装方式不算复杂整体思路就是“拉取一套模板到你的项目目录然后让AI工具读取它”。以目前社区里比较常见的方式为例# 拉取superpowers模板到当前项目按实际项目README调整仓库地址 git clone https://github.com/你的项目模板地址/superpowers.git .superpowers # 让AI工具启动时自动加载目录下的规则文件 codex exec 请阅读.superpowers目录下的所有文档然后回答这个项目采用了哪些约定这里稍微解释一下第一次安装时那个clone动作其实是次要的真正重要的是第二步的“让AI读一遍”动作。因为Superpowers的效果不取决于文件静静地躺在目录里而取决于AI的上下文里有没有真正吸收这些规则。我见过不少人clone完模板就以为大功告成结果AI该怎样还怎样就是漏了这个“激活”步骤。版本选择上我的建议是不要盲目追最新。Superpowers这类工具迭代速度很快但它强依赖上游AI工具的能力边界。比如某些新版本要求AI工具支持“多文件编辑”“技能调用”等能力如果你的Codex版本偏旧强行装新版模板很可能会遇到规则读不全的问题。“尽量跟你正在用的AI工具版本匹配”是个安全策略具体怎么找匹配版本看仓库的Release说明或README里的兼容性表格。2.3 验证安装是否成功装完之后怎么判断它真的生效了这里分享一个我自己常用的验证方式非常简单但很有效# 在项目根目录执行让AI描述它当前“知道”的项目规则 codex exec 不要写代码只告诉我1. 这个项目的代码风格要求是什么2. 测试文件的命名规范是什么3. 不允许使用的API有哪些如果Superpowers成功生效AI应该能准确答出这些信息甚至能说出项目里哪个目录是历史遗留模块、哪个服务不允许直接连数据库。如果AI支支吾吾、答非所问或者只给出通用编程建议那大概率是规则没有被正确加载。这时候不要急着重装先检查目录位置对不对、AI工具的上下文窗口够不够大、规则文件有没有被某行JSON注释给搞坏。我遇到的大部分安装失败最后查下来都是这三个原因。3. 核心机制拆解规则、技能和记忆是如何工作的这一节是整个Superpowers最值得理解的部分。很多人用不好它就是因为只把它当成一堆配置文件却没搞明白它背后的三个核心机制。3.1 AGENTS.md规则文件如何变成AI的“岗位手册”接触过AI编程工具的你应该对AGENTS.md不陌生它是很多AI工具的默认规则文件。Superpowers做的第一件事就是把原本一坨几十行的AGENTS.md拆分成一套结构化的“岗位手册”。打个比方你新招了一个程序员你肯定不会只丢给他一本《编程语言入门》而是会给他《团队代码规范》《业务领域说明》《基础设施注意事项》《常见坑位清单》。Superpowers里的规则文件就是按这个逻辑组织的典型结构大致长这样.superpowers/ ├── AGENTS.md # 总入口告诉AI先读哪些文件 ├── rules/ │ ├── code-style.md # 代码风格与格式化约定 │ ├── architecture.md # 架构约定与模块边界 │ └── anti-patterns.md # 禁止使用的API与反模式 ├── skills/ │ ├── refactor/ # 一个重构技能包 │ ├── review/ # 一个代码审查技能包 │ └── test/ # 一个测试编写技能包 └── memory/ ├── project-history.md # 项目历史与关键决策记录 └── user-preference.md # 开发者个人偏好为什么要拆这么碎因为AI的上下文窗口是有限的你把所有规则塞进一个文件里AI读到最后可能已经忘了开头写了什么。拆开之后AGENTS.md只充当“索引”AI按需去读具体文件这样既能保证关键规则不遗漏又不至于把上下文一下子灌爆。这点对大项目来说几乎是生死线——我之前试过把所有规则堆在一个文件里项目一大AI的注意力明显涣散经常犯“顾头不顾腚”的错误。3.2 技能Skills的组织方式规则文件解决的是“不能做什么、应该怎么做”的问题技能则解决“遇到特定任务时该按什么流程走”的问题。举个例子“重构一个微服务接口”这件事里面的门道其实很多要先找到接口的调用方、确认兼容性要求、改完还要跑哪些回归测试、上线顺序怎么安排。如果你不告诉AI它就只会机械地把方法签名改了调用方直接编译报错然后它再一个个去修又可能修出新问题。Superpowers里的技能包就是把这些复杂任务的执行流程写成了“操作手册”。一个重构技能包通常包含skills/refactor/ ├── SKILL.md # 技能说明书触发条件、执行步骤、注意事项 ├── prompts/ │ ├── analyze-callers.md # 分析调用方的提示词 │ └── plan-migration.md # 制定迁移计划的提示词 └── templates/ └── migration-checklist.md # 重构检查清单在SKILL.md里你会写清楚这个技能适用于什么场景、不能用于什么场景、第一步做什么、第二步做什么、最后必须检查什么。这样AI在接到任务时就不再是“凭感觉写代码”而是“按作业指导书施工”。说白了这就是把团队里资深工程师的执行力翻译成了AI能理解的流程文本。3.3 记忆与上下文管理Superpowers的第三个机制是记忆管理它解决的是AI“转头就忘”的问题。熟悉AI工具的人都懂上下文窗口一滚动前面的对话细节就没了。Superpowers会在工作过程中定期把关键决策、已完成步骤、遗留问题写入memory目录下次对话开始时AGENTS.md会提示AI先读取这些记忆文件。这相当于给AI配了一个“工作日志本”哪怕你隔了三天回来继续同一个任务它也能快速捡起上下文而不是让你重新解释一遍来龙去脉。这个功能在Java大项目里尤其好用。之前我做过一个多模块的订单系统模块之间循环依赖严重前期排查花了大半天。后来我把排查结论写进memory目录第二天让AI继续优化它直接就知道哪些模块不能碰、哪些依赖是历史债务省了不知道多少口水。4. Java项目中的Superpowers实战4.1 用Superpowers强化Maven多模块项目Java项目尤其是Maven多模块项目对AI来说一直不太友好。因为AI单次改动的代码可能只在一个Module里但它需要了解的依赖关系、parent POM配置、模块间的依赖方向却分散在好多个文件里。Superpowers在这种场景下的价值比其他语言项目更明显。我建议你在Java项目里至少配以下几个规则模块规则文件核心内容解决的问题rules/architecture.md模块依赖方向、禁止循环依赖、公共模块边界AI改代码时不会随手引入跨模块依赖rules/code-style.md命名规范、日志规范、异常处理规范、Lombok使用约定避免AI写出“看起来不像项目代码”的代码rules/testing.md单元测试命名、数据库集成测试隔离、JUnit 5使用方式防止AI产出脆弱的测试skills/refactor/跨模块重构流程、兼容性处理步骤降低AI重构大型方法/接口时的翻车率配置好之后你可以在AGENTS.md中写明# AGENTS.md 在修改代码前你必须依次阅读 1. rules/architecture.md — 确认模块边界与依赖方向 2. rules/code-style.md — 确保代码风格与现有代码一致 3. rules/testing.md — 明确测试规范 当任务涉及跨模块方法签名变更时必须参考 skills/refactor/SKILL.md 的流程执行。这里的价值不是告诉AI“你要优秀”而是给它一份具体的“施工边界图”。我实测过配了这些规则后AI在改一个Maven多模块项目时跨模块引用的踩坑次数明显下降。它能主动意识到“这个类在别的模块里改签名前要先查调用方”这就是规则文件起的作用。4.2 用技能模板固化团队规范团队规范这种东西平时存在文档里根本没人看但一旦AI开始写代码它反而成了最需要被严格执行的东西。Superpowers让我觉得最实用的一点就是它能把那些散落在Code Review评论里的“潜规则”沉淀成技能模板。比如你们的规范里有这么一条新增接口必须做参数校验错误信息格式必须是[模块名][错误码] 描述并且要写进接口文档。你可以把这个规范做进一个技能包里skills/add-api/ ├── SKILL.md └── templates/ └── api-response-template.javaSKILL.md写清楚步骤先检查是否存在类似的已有接口尽量复用其响应结构新增DTO时必须包含参数校验注解错误码需要在ErrorCodeEnum中登记不允许Magic Number完成后必须在接口类上补充注释与API说明。之后你让AI新增任何接口它都会自动按这套流程走。这相当于把你们团队最严格的那个技术负责人做成了AI的执行模板。对于团队里刚从学校毕业的新人来说看AI按这个流程写出来的代码其实也是一份不错的学习范本。4.3 实际效果一个重构任务的前后对比纸上谈兵没意思给你看一个我实际跑过的场景。项目是一个Java Spring Boot的订单服务里面有个OrderService类一个方法快400行了圈复杂度高得离谱还混合了权限校验、库存扣减、优惠计算、订单落库四件事。在配置Superpowers之前我试着让Codex拆分这个方法结果它拆完是拆完了但新的Service之间互相注入还引入了一个循环依赖编译都过不去。配置了Superpowers之后同样让它拆这个方法它的执行路径变成了主动阅读rules/architecture.md确认了当前模块不允许Service互相注入的约定找到skills/refactor/SKILL.md里的步骤先画出原始方法的逻辑分块再按领域职责拆出独立的Component拆完后自动跑了一遍mvn -q compile确认编译通过最后在改动的地方生成了提交信息草稿说明每个文件改动的原因。前后对比非常明显不是模型的智能提升了而是它干活之前拿到了一份“流程指引”。这个过程给我的感触是在很多工程类任务里AI的能力其实已经够了缺的是把“经验”和“流程”喂给它的通道。Superpowers就是干这个的。5. 我踩过的坑和调优经验这部分是日常使用中最容易出问题的地方希望你能少走点弯路。5.1 规则不是越多越好而是要分层第一次用Superpowers的时候我恨不得把所有团队规范全塞进去结果第一条就栽了规则文件太长AI在上下文里被大量规范信息填满真正关键的项目独有信息反而被稀释了。它在一次代码修改里频繁地在不同规则文件之间跳来跳去响应速度肉眼可见地变慢最终产出的代码虽然“合规”但完全没有针对问题本身进行设计。后来我调整策略把规则分成两层第一层是全局通用规则放在用户主目录的Superpowers模板里比如“不要改动未要求的代码”“不要移除现有注释”“提交前必须编译通过”第二层是项目级规则放在项目.superpowers/目录里只放和这个项目强相关的内容比如模块边界、接口兼容性约定、特殊业务逻辑。这样AI启动时默认只读取项目级规则全局规则只做兜底上下文压力小很多效果反而更好。这里有个经验项目级规则文件的篇幅尽量控制在100行以内超过这个限度建议用索引式写法在总入口里只列关键词和文件路径让AI按需去查。5.2 技能命名与触发词设计技能包的命名看起来是小事其实影响很大。AI判断什么时候该调用某个技能主要靠语义匹配所以要避免取那种“意义过宽”的名字。举个例子我一开始管重构技能包叫refactor结果AI只要遇到任何需要改代码结构的任务都会优先去套这个技能哪怕只是加个字段。后来我把它拆成了extract-method、split-large-service、api-compatible-refactor三个更具体的技能包AI的触发准确率反而提升了。命名之外SKILL.md里的“触发条件”一定要写明确。我会在技能说明书开头固定加一段## 什么时候使用这个技能 仅当任务满足以下条件时使用 - 任务描述中包含拆分、重构、提取方法等关键词 - 目标方法长度超过200行 - 或团队技术评审明确要求进行结构调整。 以下情况不要使用本技能 - 纯新增功能开发 - 仅修改文件头注释或格式化。这样AI就不容易把技能用错地方。这跟给Elasticsearch设计索引的讲究差不多索引范围越小、规则越明确匹配的精度越高。5.3 和现有CI/CD流程的冲突处理Superpowers本身不碰你的CI/CD但它产出的代码风格和检查规则很有可能跟现有流水线里的静态检查插件打架。比如有些项目开了Checkstyle或者SpotBugs规则阈值设得非常严格。Superpowers生成的技能里如果没考虑到这些AI写出来的代码很可能在提交阶段被mvn verify直接拦下来。而且问题在于AI并不会主动去读CI脚本里的配置除非你在规则文件里明确告诉它。我的解决办法是在项目级rules/里增加一个ci-checks.md把CI里跑的检查项、禁止的警告级别、执行命令都写进去# CI检查要求 - 项目使用SpotBugs禁止引入任何HIGH级别警告 - 方法行数不得超过100行如超过需要拆分 - 所有新代码必须通过 mvn clean verify 才能提交 - 禁止在测试代码中使用Thread.sleep()等待异步结果。然后要求AI在完成修改后主动执行指定的验证命令把结果贴出来。这样虽然多了几步操作但至少不会出现“AI觉得写完了CI却一片飘红”的尴尬局面。关于Superpowers还有一点值得记住——它仍然是辅助工具不是银弹。配置得再完善它也只能在你提供的规则和流程框架内发挥能力。如果你自己都没想清楚团队到底要什么规范那Superpowers能帮的也很有限。先用它逼自己把项目约定明确一遍反而可能是它最大的额外收益。