1. 从“会用AI”到“会用superpowers”先搞懂它解决什么问题这几年AI编程工具层出不穷今天换这个明天换那个但你会发现一个尴尬的事实同一个模型在不同人手里表现差距巨大。有人能用它半小时搞定一个模块有人折腾一上午还在跟上下文窗口搏斗。问题不在模型本身而在“你怎么跟它协作”。superpowers这个项目就是冲着这个痛点去的。1.1 痛点AI编程助手能力不稳定的根源先说一个我自己的经历。之前用某款AI编码工具写Java服务同一个需求我换了一种描述方式结果代码质量天差地别。第一次它规规矩矩按项目现有风格补全逻辑第二次它自作主张引入了一堆我根本没见过的依赖。你可能会说“提示词写清楚点不就行了”但真实项目里提示词根本覆盖不了所有规则。比如项目里有这么一条隐形约定所有对外接口的返回结构必须统一为ResultT异常不能直接往外抛。这种约定写在文档里、写在不显眼的Wiki里但AI读不到。你每次都要在对话里重新强调一遍累不累更麻烦的是团队里每个人强调的方式还不一样AI今天听张三的明天听李四的代码风格越来越乱。superpowers解决的就是这个问题把那些“应该让AI自动遵守的规则”固化成文件项目一加载AI天然就能读到。它不依赖你每次对话时临场发挥而是把规则前置、流程前置让AI从“凭感觉干活”变成“按规矩干活”。1.2 规则驱动给AI立规矩的正确姿势superpowers的核心不是某个神奇的算法也不是什么黑科技而是一套“规则驱动”的协作模式。它的设计思路其实特别朴素既然AI工具默认是“通用助理”那我们就给它灌入“项目专属的领域知识”和“团队专属的工作习惯”把它变成“懂这个项目的助理”。这个项目我琢磨了很久它最聪明的地方在于分层设计。最底层是规则文件用Markdown写成描述项目的技术栈、代码规范、目录结构、常见约束中间层是技能包把某类任务的完整流程固化成可复用的指令模板最上层是具体的执行工具比如Codex CLI、Claude Code这类命令行编码助手。规则定义“不能做什么、必须怎么做”技能包定义“这类任务应该按什么步骤做”工具负责真正动手写代码。用生活里的例子来类比superpowers就像是给AI一本“新员工入职手册”里面写了公司的考勤制度、代码规范、上线流程、常见坑位而不是每次开会时口头叮嘱一遍。这个手册随项目走谁接手项目谁就能获得同样的协作体验。2. 上手实操5分钟搭起superpowers工作区聊完原理直接上手。superpowers的安装和配置不需要你懂什么高深的东西只要你的开发环境里有Node.js和Git就能在几分钟内跑起来。我用的是macOS环境Windows和Linux的流程基本一致差别只在于路径写法。2.1 安装与目录结构.superpowers、规则、技能包安装方式很简单官方推荐用npm全局安装然后通过CLI初始化项目。我建议你在项目根目录执行初始化而不是全局初始化这样每个项目都能有自己的规则集。npm install -g superpowers cd your-project superpowers init执行完superpowers init之后项目根目录会多出一个.superpowers文件夹里面是默认的目录骨架。你还会看到一个AGENTS.md文件这个文件是整个规则体系的入口AI工具加载项目时会优先读取它。整个目录结构大致长这样your-project/ ├── .superpowers/ │ ├── rules/ # 细分规则比如 java.mdc、git.mdc │ ├── skills/ # 技能包比如 task.md、boomerang.md │ ├── commands/ # 命令注册供AI调用具体技能 │ └── templates/ # 任务模板标准化某类请求 ├── AGENTS.md # 规则声明入口 └── .superpowers.json # 配置文件可选第一次看到这么多文件不用慌真正需要你维护的核心只有两个AGENTS.md和.superpowers/rules/下的规则文件。技能包默认会带一批直接能用后面你想自定义再改。2.2 技能包拆解从task到pr-reviewsuperpowers默认内置了不少技能包我挑几个高频的讲一下方便你快速度过“不知道它能干嘛”的阶段。task技能包定义的是“接手一个任务”的标准流程先读取项目README和AGENTS.md再定位相关代码最后才动手修改。这看起来像是废话但AI默认并不这么做。很多AI上来就写代码写完才发现改了不该改的地方。boomerang技能包解决的是“AI进行到一半被打断”的场景。它会把当前进度、已完成部分、剩余工作、待验证项记录到一个状态文件里下次交互时自动恢复。这个对实际开发太重要了——尤其当AI跑了一个长任务中途你切出去开会回来想接着干没有状态记录的话上下文基本废了。pr-review技能包是代码审查的专属流程检查diff、检查提交信息格式、检查是否有调试残留、检查边界条件。它不依赖人肉提醒AI“请先看git diff”AI会自动按这个流程执行。每个技能包本质上都是一份精细的Markdown提示词里面包含了该场景下的步骤拆解和约束条件。你完全可以打开文件看它的实现这本身就是很好的学习材料。2.3 第一步验证让AI按你的节奏干活装好环境之后先别急着上复杂项目用一个最简单的场景验证superpowers是否生效。我在一个测试项目里写了一条规则所有方法必须写Javadoc注释然后让AI生成一个工具类。没配superpowers之前AI生成的代码经常只有稀疏的几行注释配好规则之后AI会老老实实每个public方法都补上Javadoc甚至还会在类头写上作者和版本信息。看到这个变化你就可以确定规则管道已经通了。有一个细节需要注意不同AI工具对规则文件的读取策略不同。Codex CLI和Claude Code都会读AGENTS.md但Claude Code还支持.claude目录下的.mdc规则文件。为了让superpowers在多个工具之间通用规则声明里不要写死某个特定工具专属的指令。我自己踩过这个坑在规则里写了“你是一个使用Claude Code的助手”结果切到Codex时行为就变得很奇怪。3. 核心细节解析规则文件与技能包的工作原理很多人以为superpowers只是“把提示词存成文件”这理解太浅了。它的价值在于设计了一个“规则通路”从仓库根目录的AGENTS.md出发层层引用到具体的规则文件和技能包让AI在处理不同任务时能自动加载对应的约束。这里面有几个关键机制值得展开讲。3.1 .mdc规则文件到底怎么写才生效规则文件的格式是Markdown但它的生效依赖“前置描述块”frontmatter。一个标准的.mdc文件长这样--- description: Java项目必须遵守的代码规范 globs: *.java, src/main/java/** alwaysApply: false --- # Java编码规范 1. 所有DTO类必须使用record或final class禁止使用可变POJO。 2. 所有对外接口返回统一ResultT结构。 3. 禁止catch异常后吞掉必须记录日志并抛出业务异常。frontmatter里的description很重要AI工具会用它来决定“什么情况下需要读取这个规则”。globs用于限定规则适用的文件范围。alwaysApply如果设为true表示这个规则在所有场景下都生效如果为falseAI会按照description的描述来判断“当前任务是否涉及该规则”。我建议你把高频的硬性约束比如不允许使用System.out.println、不允许引入未在pom.xml声明的依赖设为alwaysApply: true把低频但重要的规范比如“变更数据库表结构时必须先生成迁移脚本”设为alwaysApply: false这样AI不会被一堆规则压得喘不过气又能按需加载。这里面有个容易踩的坑规则文件不是越详细越好。我也曾试图把所有编码规范都塞进规则里结果AI在简单任务上反而更啰嗦了因为它要“遵守”太多约束而频繁中断操作。实际测试下来一份规则文件控制在一个主题、十个要点以内效果最好。3.2 结合Java开发superpowers在项目里的落地Java项目天然适合用superpowers因为Java项目的结构相对规整团队规范也多。我的一个Spring Boot项目里规则文件是这样组织的java.mdc负责基础编码规范包括命名风格、异常处理、Lombok使用边界。spring.mdc专门约束Spring的用法比如禁止在Controller里写业务逻辑、Service接口必须有实现类、依赖注入必须用构造器方式。db.mdc管理数据库相关规则比如所有SQL必须走Mapper接口、批量操作必须分批提交、禁止使用SELECT *。技能包方面我改了一个task技能包让它适配Java开发流程先用Maven编译并跑完单元测试确认当前基线是绿色的再进行功能开发开发完成后再次跑测试并检查是否有新增的编译警告。这套组合用下来AI生成的代码在“合规性”上明显提高。之前它经常在Controller里直接new一个Service被规则约束后它会乖乖走构造器注入。规则不只是在“输出端”限制AI还是在“行为端”引导AI它会让AI先检查现有代码再动手而不是凭空发挥。3.3 参数与配置控制AI行为的边界.superpowers.json这个配置文件可能被很多人忽略它其实是控制AI行为边界的“总闸”。我常用的几个配置项{ mode: strict, maxConsecutiveEdits: 5, requireCheckpoint: true, ignorePatterns: [target/, node_modules/] }mode字段可设为strict或normalstrict模式下AI必须遵循所有标记为“MUST”的规则maxConsecutiveEdits限制了AI连续编辑文件的次数防止它一口气改动十几个文件导致review困难requireCheckpoint要求AI在长任务执行途中主动汇报进度。我个人强烈建议打开requireCheckpoint尤其是在做跨多个文件的重构时。没有它AI可能埋头改了一大堆等你去review的时候已经不知道它动了什么。打开后AI每完成一个阶段就会输出当前状态和下一步计划相当于给了你一个“中途干预”的机会。4. 实战过程用superpowers完成一次Java代码审查理论说再多不如跑一遍流程。这一节我完整记录一次实际操作让大家看到superpowers在具体任务里是怎么运作的。4.1 需求定义与技能选择场景我负责的一个支付模块提交了一次MR改动涉及PaymentService、PaymentController和PaymentMapper三个文件。我让AI先做一个自审重点检查事务边界、异常处理和SQL注入风险。在superpowers框架下对应的交互方式是调用pr-review技能superpowers pr-review --focustransaction,exception,sql-injection这里的--focus参数会传递给技能包引导AI审查时把注意力集中在指定维度。其余维度的检查代码风格、命名规范也不会被跳过只是在汇报时会区分“重点问题”和“一般问题”。4.2 完整操作流程记录AI收到指令后的执行轨迹大致如下第一步读取规则。AI先加载AGENTS.md然后根据任务类型读取了rules/java.mdc和rules/spring.mdc确认了项目里“事务注解必须放在public方法上”“禁止捕获通用异常”“Mapper参数必须使用Param注解”三条硬性规则。第二步获取代码变更。AI调用git命令拿到MR的diff同时读取了PaymentService的完整文件内容因为它需要了解上下文而不仅仅是变更行。第三步逐项审查。AI按技能包里的检查清单逐项过先看类结构、方法签名是否符合项目风格再查事务边界——发现PaymentService.refund()方法上加了Transactional但方法内部调用了PaymentCallback.notify()这个远程接口调用这会导致事务长时间占用数据库连接。接着查异常处理——发现PaymentController里有一段catch块仅仅做了日志打印没有抛出业务异常违反“禁止吞异常”规则。第四步输出审查报告。AI生成的报告分三块问题列表、严重级别、修改建议。表述很明确没有模棱两可。4.3 效果对比有规则和没规则的差别同样的MR我在另一个未配置superpowers的仓库里让AI审查过差别非常明显。没有规则时AI只会泛泛地指出代码风格问题比如“方法命名不够清晰”其实问题不大有规则时它的审查能够触及项目特有的约定而不是“AI味”很重的内容。最关键的一点是配置规则后AI审查的注意力范围被重构了它不再海撒网似地扫描所有能看到的代码问题而是聚焦于团队真正关心的问题域。pr-review技能包把“审查”这个宽泛任务拆成了有优先级的清单AI按清单逐项执行不会因为上下文过长而遗漏关键检查项。这种体验让我觉得很踏实它意味着AI的能力不再依赖“这次对话里用户有没有把规则说全”而是取决于“团队是否把规范沉淀了下来”。规范沉淀得越精细AI输出越稳定。5. 常见问题与排查技巧实录用superpowers的过程中我踩过不少坑。下面挑几个典型问题按“现象—原因—解决”的方式整理出来供大家对照排查。5.1 规则不生效怎么办这是最常遇到的问题。你明明写了规则AI却视而不见。我遇到过的原因大致有三种。第一种AGENTS.md里没引用对应的规则文件。很多人在rules/目录下写了java.mdc但在AGENTS.md里没有加上“本仓库的Java代码规范见.superpowers/rules/java.mdc”这句话。AI工具默认只读AGENTS.md不扫描整个.superpowers目录。加上明确的引用后规则才进入AI的加载列表。第二种globs配置写得太宽或太窄。我吃过亏的配置是把globs写成*.java但项目实际在src/main/java下AI在读取特定文件时可能匹配不到规则。改成src/main/java/**/*.java后效果好多了。这个字段的匹配严格程度与工具的实现有关建议用**通配而不是*。第三种规则内容与任务无关。AI不会在每次对话中都把全部规则加载进来它只会加载与当前任务相关的规则。如果你给AI的任务是“写一个README”它不会主动去读Java编码规范。判断规则是否被加载可以在规则文件里加一行“如果有疑问请先向用户确认是否适用本规则”如果AI照做了说明规则已被读取。5.2 模型被规则“锁死”了规则设得过严AI确实会变“愣”。比如我在一个项目里设了“所有方法必须写Javadoc包括getter和setter”结果AI在生成批量代码时每个简单的getter都配了一大段注释代码行数膨胀了30%阅读起来反而更吃力。解决思路是给规则加“豁免条件”明确“简单POJO类中不强制要求注解但核心业务类和接口必须写”。或者利用alwaysApply: false把适用于大多数场景的规则设为默认加载把“重型”规范比如“每个类必须描述设计意图”设为按需加载。另外规则语言不要用“尽量”“最好”这种模糊表述。AI面对模糊指令时往往会重复确认或选择最保守的执行方式导致任务效率下降。要用“禁止”“必须”“允许”这类明确约束词。5.3 多语言项目中的规则冲突与复用一个仓库里同时有Java和Python代码的情况很常见。如果规则文件里写了“包名必须为com.xxx”Python代码也会被这个规则困扰。解决办法是按子目录拆分规则rules/ ├── java.mdc # globs: src/main/java/**/*.java └── python.mdc # globs: src/python/**/*.py但要注意AGENTS.md里不要写只在单一语言下成立的全局规则。例如“禁止使用System.out.println”只在Java规则里写“禁止使用print”只在Python规则里写不要写成“禁止使用控制台输出语句”这种笼统规则AI可能把它解读成禁止一切输出操作。关于复用我的习惯是把通用规则提交信息格式、分支命名、代码评审要求单独抽出来放到.superpowers/rules/common.mdc里被alwaysApply: true把语言专属规则放到对应语言的规则文件里。这样新项目初始化时只要复制整个.superpowers目录微调一下就行不用从头写。用superpowers这几个月下来我最大的感受是AI编程的下半场拼的不是谁的模型更强而是谁更会用规则约束模型。这个框架把团队经验、项目规范、工作流沉淀成了可复用的资产新人接手项目时AI助手直接就是“老员工”状态。如果你也觉得现在的AI编程助手总是“差那么点意思”不妨从规则文件入手给它立好规矩再放手干活。