前阵子折腾了一个挺有意思的开源项目叫 superpowers。看名字就知道它想给你的开发环境加一组“超能力”。简单说它不是另一个IDE插件也不是一套框架而是一组可以插在AI编码助手比如Codex这类命令行工具里的“技能包”。装好之后原本只会答话的AI助手能直接上手干各种杂活查项目结构、改代码、补测试、做代码审查甚至按你的工程规范来办事。如果你平时已经在用AI写代码但总觉得它“只会说不会做”或者每次都要反复交代细节和背景那这篇东西就是写给你看的。我会从安装配置讲起拆开核心概念再拿一个真实场景走一遍流程最后把我在实际使用中踩过的坑和排查思路一并列出来。内容偏向实操属于“抄了就能用”的路子。1. 项目定位与整体设计思路先说清楚superpowers到底是什么以及它和普通AI辅助工具的区别。我第一次看到这名字时以为是个概念玩具实际用下来发现它是个很实的“工作流”工具给AI助手预装一系列“技能文件”。你可以把这些技能理解为一份份高质量的执行手册里面写清楚了具体任务的解法、步骤、边界条件和你这个团队偏好的代码规范。AI在跑任务前把这些手册读一遍干活的方式就会从“随缘发挥”变成“按套路出牌”。1.1 核心需求解析AI编码助手为什么需要“技能包”现在的AI编码助手底层模型能力已经很能打了但大家抱怨最多的不是它不懂技术而是它太不稳定。同一个问题换个说法结果就漂移让它改个函数它顺手把无关的格式也动了让它写测试它偏偏用了你项目里根本没引入的断言库。这些问题的根源不是模型笨而是它缺少“上下文约束”。superpowers的思路恰恰就是把你反复强调的这些约束固化成文件每次启动任务前自动让AI加载。拿生活里的例子打比方你请了个很聪明的新人来协助干活他什么都懂但不懂你们团队的规矩。是每件事都从头交代一遍效率高还是先给他一份《团队工作手册》效率高superpowers就是这份手册。它既规定了“遇到什么情况该怎么处理”也规定了“哪些事别碰”。1.2 设计取舍为什么选择“目录即技能”而不是“一条龙脚本”我特意去翻了它的设计文档和源码目录发现开发者刻意没有把技能写进一个大脚本而是拆成一个个独立的技能文件按模块组织在项目的.superpowers/目录里。这个设计细节很关键。每个技能文件只关心一件事比如refactor、test-generation、dependency-upgrade互不干扰。你可以在一个项目里只启用部分技能另一个项目启用另一部分团队之间还可以通过Git共享技能文件。由于技能文件是普通文本任何人都能打开看你能清楚知道AI即将使用哪套逻辑不存在“黑箱”。这个取舍让superpowers变得非常轻它没有常驻后台进程也不阻塞你的git操作只是在AI编码工具启动时作为系统提示词的一部分存在。只要你的工具支持自定义初始指令就能接入superpowers。1.3 适用人群与典型场景我梳理了一下下面这几类人用superpowers收益最明显重度使用命令行AI编码助手的开发者尤其是已经在用Codex CLI或类似工具的人。团队里想要统一AI辅助编程行为规范的队伍比如规定AI只能使用已有的测试框架、注释放中文、禁止修改锁文件等。做Java等大型工程的人因为项目结构复杂AI经常“迷路”技能文件能让它先看项目地图再动手。希望把AI从“问答机器人”升级为“任务执行者”的个人开发者。反过来如果你只是偶尔让AI解释一段代码或者只用图形界面里的聊天功能那superpowers对你就有点大材小用。它的价值集中在高频、重复、可标准化的编码任务上。2. 环境准备与安装配置这部分是新手最容易卡住的地方。我按自己实际安装的路径来写尽量把每个命令为什么这样用都说清楚。以下安装步骤以官方文档为准如果你看到时版本更新了以最新发布为准。2.1 前置环境要求superpowers本身是用Node.js写的安装器和CLI工具所以你的机器上得先有Node.js环境。我用的是Node.js 18.17版本实测可以正常跑低于16的话大概率会报语法错误尤其是新版用了不少ESM模块语法。除此之外你需要有一个命令行版的AI编码助手。以Codex CLI为例它负责实际调用模型、执行命令、修改文件而superpowers提供的是任务执行的“行为准则”。两者是互补关系不是替代关系。注意superpowers本身不内置任何AI模型。所有AI能力仍来自你配置的模型服务。它的作用是让这些能力被组织化地用在工程任务上。2.2 一步步安装superpowers安装流程并不复杂我拆成几步来说。第一步全局安装CLI工具npm install -g superpowers-cli如果你不想全局安装也可以直接用npx执行但这会在每次运行时重新解析包稍慢一点。全局安装的好处是后续命令在任何项目目录都能直接用。第二步在项目目录里初始化技能目录cd your-project superpowers init执行之后它会询问你要启用哪些技能模块。我没细看直接回车结果默认启用了全部核心模块。如果你只想用其中几个建议在交互界面里手动选择。第三步接入Codex CLI等工具。我这边是在项目根目录生成了一个.superpowers/AGENTS.md文件然后在Codex的配置里指定让它在每次会话开始时读取这个文件。如果你用的是别的工具凡是支持--system-prompt或系统提示词文件路径的都可以按类似思路接入。2.3 安装后的目录结构与关键文件安装完毕后项目目录里大概会多出类似这样的结构.superpowers/ config.json AGENTS.md skills/ refactor/ README.md prompt.md rules.json test-generation/ README.md prompt.md rules.json dependency-upgrade/ README.md prompt.md rules.json解释一下各文件的定位config.json全局配置。比如是否允许AI自动安装依赖、是否严格禁止修改指定路径、默认语言设置等。AGENTS.md给AI看的“总章程”相当于技能的入口索引。AI每次会话都会先读它。skills/目录每个子目录是一个技能包prompt.md是技能主提示词rules.json是约束规则。首次安装后我建议你打开AGENTS.md看一遍。因为它是直接拼进系统提示词的内容不合适会影响所有会话。我遇到过默认章程里要求AI“总是使用函数式风格”之类的描述和项目实际风格不搭手动改掉就好了。3. 核心能力拆解与使用技巧装好只是第一步。真正让superpowers发挥威力的地方在于理解和调整每个技能包。这一节我会展开讲几个我用得最多的核心技能并且说说它们背后的设计逻辑。3.1 技能包的核心工作机制每个技能包本质上是一份“条件-动作-约束”模板。以重构技能为例当你在命令里请求AI“帮忙重构这个模块”时AI会读取skills/refactor/prompt.md里面大概会包含这样一些执行逻辑先扫描模块的依赖关系再去定位具体函数然后按你配置的“保持公共API不变、内部实现重写、测试必须全绿”等规则去改代码。这种机制的聪明之处在于AI不用每次重新推断你的偏好它照着规则执行就行。你通过调整rules.json里的一两个布尔值就能改变整组行为的走向而不用重新写一大段Prompt。3.2 Codex集成技巧让AI先读章程再干活和Codex配合时一个容易被忽略的点是AI能接收的上下文长度有限如果不加区分地把所有技能内容塞进去很快就把上下文烧完了。我实际对比过两种接入方式。第一种把整个.superpowers/AGENTS.md作为系统提示词。这种方法简单粗暴效果也直接但如果你配置文件写得像小说一样长模型可用上下文会被吃掉一截影响后续代码分析。第二种在AGENTS.md里只写索引让AI按需读取具体技能文件。比如当它收到重构任务时自己决定去skills/refactor/prompt.md加载细节。我更推荐第二种。代价是你需要给AI加上“按需读取技能文件”的显式指令收益是每次会话的上下文占用大幅下降。我的实测体感是长会话的稳定性提升非常明显AI不会做到后半段就开始忘前面要求。3.3 Java场景下的实际效能热搜里看到有“superpowers java”这个词我特意在Spring Boot项目里测了一周说说我的感受。Java工程天生有个特点有效信息密度低。目录层级深、配置多、模板代码多AI经常一头扎进某个实现类里忘了全局。但superpowers里的技能包能改变这一点。我把.superpowers/skills/里加了一个自定义的java-project-map技能要求AI在接到任何修改请求时先读取pom.xml和模块目录结构生成一份“项目依赖摘要”再到目标代码里动手。这个习惯养成之后AI在Java项目上的表现有两个明显变化一是它不会轻易改动公共接口签名了因为技能规则里写了“先去搜调用方再决定”二是写测试时它会自动选择JUnit 5和AssertJ而不是随机选一个看起来像测试框架的库。你要是维护过Java老项目一定懂那种“AI一通操作猛如虎结果编译直接挂掉”的痛。一个强制先读构建文件的技能规则能挡掉大部分低级问题。3.4 技能包的编写与自定义superpowers真正让人上瘾的地方是你可以自己写技能包。我第二周就开始把团队内部的一些规范写成新技能了。写一个新技能包只需要三步在skills/下建一个新目录比如security-review。写一个prompt.md里面明确描述触发场景、执行步骤、输入输出格式。写一个rules.json把硬性约束填进去比如“禁止使用eval”“涉及鉴权的改动必须返回高优先级提醒”。一个容易踩的坑是给技能包起的名称太宽泛。比如叫database-reviewAI可能不知道它到底覆盖哪些方面。我后面改成database-migration-risk-reviewAI的套用准确率立刻上来了。技能包名称本质上决定了AI在什么场景下想起它名字一定要具体和你想让它承担的任务强对应。4. 实操过程与典型工作流光说概念容易飘走一遍真实流程更直观。下面是我这段时间用得最顺的一个完整流程让AI基于superpowers技能在一个Java服务里完成“新增加密配置项并补充单元测试”的任务。整个过程我全程记录你可以照着推演一遍。4.1 场景设定项目是一个基于Spring Boot的订单服务加密密钥原本写死在配置类里。需求是把密钥改为从环境变量读取并且在缺失时给出友好报错。任务不算难但涉及配置类、工具类、单元测试三个地方还要求改动不能破坏已有调用方。4.2 第一步让AI读取项目章程我在终端里启动Codex第一句指令就写请先查看 .superpowers/AGENTS.md然后介绍你要执行的任务。这一步很关键等于让AI先进入“工作状态”。它随后输出了一份简短的计划检查配置类、定位加密工具、查看既有测试风格、实施修改、补充测试、跑构建。看到这里我就放心了它没有一上来就改代码。4.3 第二步调用具体技能执行任务我的任务是加密配置改造我给它发指令时主动点名了技能使用 dependency-upgrade 和 test-generation 技能完成以下改动。AI按照技能文件里的顺序执行了这几件事读取最新pom.xml确认Spring Boot版本避免新代码用到旧版本不支持的特性。扫描配置类找到硬编码密钥替换为System.getenv(ORDER_SERVICE_SECRET)。在缺失环境变量的路径上抛出带操作提示的异常。按test-generation的规则使用JUnit 5写了两个测试用例正常取值和缺失变量场景。整个过程没有什么魔法它就是严格遵循了技能规则把该做的检查做完了。这恰恰是superpowers最大的价值它让AI的行为从“随机抽样模型知识”变成了“按项目现成规则执行”。4.4 第三步检查Diff与回归AI改完之后我让它用refactor技能里的“安全审查”子项做了一遍自检superpowers run review --diff这条命令会输出改动摘要并根据风险规则标出需要注意的位置。实测中它对“新增了环境变量读取”这个点给出了一条提示需要同步检查部署脚本和本地开发环境配置。这个提醒很实在如果是在CI流水线里部署光改代码不更新环境变量上线就会直接启动失败。4.5 执行结果与花费估算我记录了一下整轮任务消耗的token和我平时直接和AI对话写代码差不多但由于中途没有因为跑偏返工实际“有效产出/总token”的比值高了不少。换算成时间以前这类改动可能要来回调整三四轮现在一轮落地跑一次构建就过了。5. 常见问题与排查技巧实录最后这部分是我积累的排错经验。遇到问题不要慌大部分都和Node版本、权限、配置路径、上下文长度有关。我整理成速查表方便你直接对照。现象可能原因解决方案安装时报ERR_PNPM_RECURSIVE_EXEC_FATAL使用了很老的pnpm或npm版本升级npm至9以上或改用npx superpowers init初始化后AI没有读取技能文件未在Codex配置中指定系统提示词路径检查配置项--system-prompt或AGENTS.md路径是否正确长会话中AI开始忽略规则上下文被大量项目代码挤占把AGENTS.md改为索引模式让AI按需加载技能细节自动修改了不允许动的锁文件缺少规则约束在rules.json中加入forbiddenPaths: [package-lock.json, pnpm-lock.yaml]技能名称太泛导致不被触发技能名和任务关联度弱改成更具体的名称降低AI判断成本Windows PowerShell下运行异常命令路径分隔符和脚本不兼容在PowerShell中使用npx.cmd前缀或改用WSL提示词过长被模型截断技能文件写得太多太长精简每条技能到一屏以内把长篇背景放到单独参考文档5.1 连接不上模型服务时的排查思路这是个和superpowers无关但很容易误伤的问题。如果你用了CLI工具后发现AI完全不回话先别赖superpowers按三步排查第一步确认API Key和服务地址配置正确第二步用一条最简单的提示词测一下模型连通性第三步检查代理类环境变量是否拦截了连接。这里特别提醒一下国内网络环境下模型服务连接经常是最大变数但这不是本文范围你只需要记住排查顺序就行。5.2 关于多项目共用技能包的实践如果你和我一样同时维护好几个项目一定不要每个项目都跑一遍superpowers init然后把技能文件复制来复制去。更省心的做法是把公共技能目录单独放一个Git仓库然后在每个项目里用软链指过去。Linux和macOS上可以这样ln -s ~/workspace/team-superpowers .superpowersWindows上则可以使用目录联接junction。这样团队更新一次技能包所有项目自动生效。代价是某个项目需要特立独行时你得额外处理差异但这比维护多份拷贝轻松得多。5.3 断网离线环境下的兜底方案superpowers本身是纯文本技能包离线也能读但CLI初始化时需要联网拉取模板。如果你在隔离环境里可以找一台能联网的机器执行superpowers init生成.superpowers目录后把整个目录上传到内网仓库。后续内网项目直接拉取这个仓库即可完全不需要联网。6. 我的实操体会与扩展建议文章最后聊几句我自己的感受。用过一段时间后我最大的体会是superpowers解决的问题不是“AI不够聪明”而是“聪明没用在刀刃上”。它不能让你从80分AI变成120分AI但能让AI每次干活都稳定在80分水平而不是这次90分下次50分。对工程协作来说稳定性本身就值回票价。有个小技巧特别推荐每次执行完一类任务后花两分钟把本次新增的指令要求补进对应的技能文件里。比如我在做完上面那个加密配置改造后就在test-generation的规则里加了一条“涉及环境变量时必须同时生成缺失变量的测试用例”。这个小动作相当于让技能包随项目一起进化越用越顺手。再给两个可能的扩展方向。第一可以把superpowers和CI流程结合起来在提交PR前自动跑一轮技能包里的代码自检规则相当于给AI生成的代码加一道纪律闸门。第二如果你在做文档类工作可以考虑把“文档规范”也写成技能包让AI按团队模板生成接口文档或变更记录。它本质上就是一套可版本化、可评审、可演化的“行为规范系统”思想并不限于写代码。我现在的日常流程已经离不开它了。新项目克隆下来第一件事就是初始化.superpowers给AI立好规矩再放它进代码库。这套玩法的上限不取决于工具本身而取决于你愿不愿意花时间去打磨那几份规则文件。规则越贴近实际工程痛点AI给你的惊喜就越多。
前阵子折腾了一个挺有意思的开源项目叫 superpowers。看名字就知道它想给你的开发环境加一组“超能力”。简单说它不是另一个IDE插件也不是一套框架而是一组可以插在AI编码助手比如Codex这类命令行工具里的“技能包”。装好之后原本只会答话的AI助手能直接上手干各种杂活查项目结构、改代码、补测试、做代码审查甚至按你的工程规范来办事。如果你平时已经在用AI写代码但总觉得它“只会说不会做”或者每次都要反复交代细节和背景那这篇东西就是写给你看的。我会从安装配置讲起拆开核心概念再拿一个真实场景走一遍流程最后把我在实际使用中踩过的坑和排查思路一并列出来。内容偏向实操属于“抄了就能用”的路子。1. 项目定位与整体设计思路先说清楚superpowers到底是什么以及它和普通AI辅助工具的区别。我第一次看到这名字时以为是个概念玩具实际用下来发现它是个很实的“工作流”工具给AI助手预装一系列“技能文件”。你可以把这些技能理解为一份份高质量的执行手册里面写清楚了具体任务的解法、步骤、边界条件和你这个团队偏好的代码规范。AI在跑任务前把这些手册读一遍干活的方式就会从“随缘发挥”变成“按套路出牌”。1.1 核心需求解析AI编码助手为什么需要“技能包”现在的AI编码助手底层模型能力已经很能打了但大家抱怨最多的不是它不懂技术而是它太不稳定。同一个问题换个说法结果就漂移让它改个函数它顺手把无关的格式也动了让它写测试它偏偏用了你项目里根本没引入的断言库。这些问题的根源不是模型笨而是它缺少“上下文约束”。superpowers的思路恰恰就是把你反复强调的这些约束固化成文件每次启动任务前自动让AI加载。拿生活里的例子打比方你请了个很聪明的新人来协助干活他什么都懂但不懂你们团队的规矩。是每件事都从头交代一遍效率高还是先给他一份《团队工作手册》效率高superpowers就是这份手册。它既规定了“遇到什么情况该怎么处理”也规定了“哪些事别碰”。1.2 设计取舍为什么选择“目录即技能”而不是“一条龙脚本”我特意去翻了它的设计文档和源码目录发现开发者刻意没有把技能写进一个大脚本而是拆成一个个独立的技能文件按模块组织在项目的.superpowers/目录里。这个设计细节很关键。每个技能文件只关心一件事比如refactor、test-generation、dependency-upgrade互不干扰。你可以在一个项目里只启用部分技能另一个项目启用另一部分团队之间还可以通过Git共享技能文件。由于技能文件是普通文本任何人都能打开看你能清楚知道AI即将使用哪套逻辑不存在“黑箱”。这个取舍让superpowers变得非常轻它没有常驻后台进程也不阻塞你的git操作只是在AI编码工具启动时作为系统提示词的一部分存在。只要你的工具支持自定义初始指令就能接入superpowers。1.3 适用人群与典型场景我梳理了一下下面这几类人用superpowers收益最明显重度使用命令行AI编码助手的开发者尤其是已经在用Codex CLI或类似工具的人。团队里想要统一AI辅助编程行为规范的队伍比如规定AI只能使用已有的测试框架、注释放中文、禁止修改锁文件等。做Java等大型工程的人因为项目结构复杂AI经常“迷路”技能文件能让它先看项目地图再动手。希望把AI从“问答机器人”升级为“任务执行者”的个人开发者。反过来如果你只是偶尔让AI解释一段代码或者只用图形界面里的聊天功能那superpowers对你就有点大材小用。它的价值集中在高频、重复、可标准化的编码任务上。2. 环境准备与安装配置这部分是新手最容易卡住的地方。我按自己实际安装的路径来写尽量把每个命令为什么这样用都说清楚。以下安装步骤以官方文档为准如果你看到时版本更新了以最新发布为准。2.1 前置环境要求superpowers本身是用Node.js写的安装器和CLI工具所以你的机器上得先有Node.js环境。我用的是Node.js 18.17版本实测可以正常跑低于16的话大概率会报语法错误尤其是新版用了不少ESM模块语法。除此之外你需要有一个命令行版的AI编码助手。以Codex CLI为例它负责实际调用模型、执行命令、修改文件而superpowers提供的是任务执行的“行为准则”。两者是互补关系不是替代关系。注意superpowers本身不内置任何AI模型。所有AI能力仍来自你配置的模型服务。它的作用是让这些能力被组织化地用在工程任务上。2.2 一步步安装superpowers安装流程并不复杂我拆成几步来说。第一步全局安装CLI工具npm install -g superpowers-cli如果你不想全局安装也可以直接用npx执行但这会在每次运行时重新解析包稍慢一点。全局安装的好处是后续命令在任何项目目录都能直接用。第二步在项目目录里初始化技能目录cd your-project superpowers init执行之后它会询问你要启用哪些技能模块。我没细看直接回车结果默认启用了全部核心模块。如果你只想用其中几个建议在交互界面里手动选择。第三步接入Codex CLI等工具。我这边是在项目根目录生成了一个.superpowers/AGENTS.md文件然后在Codex的配置里指定让它在每次会话开始时读取这个文件。如果你用的是别的工具凡是支持--system-prompt或系统提示词文件路径的都可以按类似思路接入。2.3 安装后的目录结构与关键文件安装完毕后项目目录里大概会多出类似这样的结构.superpowers/ config.json AGENTS.md skills/ refactor/ README.md prompt.md rules.json test-generation/ README.md prompt.md rules.json dependency-upgrade/ README.md prompt.md rules.json解释一下各文件的定位config.json全局配置。比如是否允许AI自动安装依赖、是否严格禁止修改指定路径、默认语言设置等。AGENTS.md给AI看的“总章程”相当于技能的入口索引。AI每次会话都会先读它。skills/目录每个子目录是一个技能包prompt.md是技能主提示词rules.json是约束规则。首次安装后我建议你打开AGENTS.md看一遍。因为它是直接拼进系统提示词的内容不合适会影响所有会话。我遇到过默认章程里要求AI“总是使用函数式风格”之类的描述和项目实际风格不搭手动改掉就好了。3. 核心能力拆解与使用技巧装好只是第一步。真正让superpowers发挥威力的地方在于理解和调整每个技能包。这一节我会展开讲几个我用得最多的核心技能并且说说它们背后的设计逻辑。3.1 技能包的核心工作机制每个技能包本质上是一份“条件-动作-约束”模板。以重构技能为例当你在命令里请求AI“帮忙重构这个模块”时AI会读取skills/refactor/prompt.md里面大概会包含这样一些执行逻辑先扫描模块的依赖关系再去定位具体函数然后按你配置的“保持公共API不变、内部实现重写、测试必须全绿”等规则去改代码。这种机制的聪明之处在于AI不用每次重新推断你的偏好它照着规则执行就行。你通过调整rules.json里的一两个布尔值就能改变整组行为的走向而不用重新写一大段Prompt。3.2 Codex集成技巧让AI先读章程再干活和Codex配合时一个容易被忽略的点是AI能接收的上下文长度有限如果不加区分地把所有技能内容塞进去很快就把上下文烧完了。我实际对比过两种接入方式。第一种把整个.superpowers/AGENTS.md作为系统提示词。这种方法简单粗暴效果也直接但如果你配置文件写得像小说一样长模型可用上下文会被吃掉一截影响后续代码分析。第二种在AGENTS.md里只写索引让AI按需读取具体技能文件。比如当它收到重构任务时自己决定去skills/refactor/prompt.md加载细节。我更推荐第二种。代价是你需要给AI加上“按需读取技能文件”的显式指令收益是每次会话的上下文占用大幅下降。我的实测体感是长会话的稳定性提升非常明显AI不会做到后半段就开始忘前面要求。3.3 Java场景下的实际效能热搜里看到有“superpowers java”这个词我特意在Spring Boot项目里测了一周说说我的感受。Java工程天生有个特点有效信息密度低。目录层级深、配置多、模板代码多AI经常一头扎进某个实现类里忘了全局。但superpowers里的技能包能改变这一点。我把.superpowers/skills/里加了一个自定义的java-project-map技能要求AI在接到任何修改请求时先读取pom.xml和模块目录结构生成一份“项目依赖摘要”再到目标代码里动手。这个习惯养成之后AI在Java项目上的表现有两个明显变化一是它不会轻易改动公共接口签名了因为技能规则里写了“先去搜调用方再决定”二是写测试时它会自动选择JUnit 5和AssertJ而不是随机选一个看起来像测试框架的库。你要是维护过Java老项目一定懂那种“AI一通操作猛如虎结果编译直接挂掉”的痛。一个强制先读构建文件的技能规则能挡掉大部分低级问题。3.4 技能包的编写与自定义superpowers真正让人上瘾的地方是你可以自己写技能包。我第二周就开始把团队内部的一些规范写成新技能了。写一个新技能包只需要三步在skills/下建一个新目录比如security-review。写一个prompt.md里面明确描述触发场景、执行步骤、输入输出格式。写一个rules.json把硬性约束填进去比如“禁止使用eval”“涉及鉴权的改动必须返回高优先级提醒”。一个容易踩的坑是给技能包起的名称太宽泛。比如叫database-reviewAI可能不知道它到底覆盖哪些方面。我后面改成database-migration-risk-reviewAI的套用准确率立刻上来了。技能包名称本质上决定了AI在什么场景下想起它名字一定要具体和你想让它承担的任务强对应。4. 实操过程与典型工作流光说概念容易飘走一遍真实流程更直观。下面是我这段时间用得最顺的一个完整流程让AI基于superpowers技能在一个Java服务里完成“新增加密配置项并补充单元测试”的任务。整个过程我全程记录你可以照着推演一遍。4.1 场景设定项目是一个基于Spring Boot的订单服务加密密钥原本写死在配置类里。需求是把密钥改为从环境变量读取并且在缺失时给出友好报错。任务不算难但涉及配置类、工具类、单元测试三个地方还要求改动不能破坏已有调用方。4.2 第一步让AI读取项目章程我在终端里启动Codex第一句指令就写请先查看 .superpowers/AGENTS.md然后介绍你要执行的任务。这一步很关键等于让AI先进入“工作状态”。它随后输出了一份简短的计划检查配置类、定位加密工具、查看既有测试风格、实施修改、补充测试、跑构建。看到这里我就放心了它没有一上来就改代码。4.3 第二步调用具体技能执行任务我的任务是加密配置改造我给它发指令时主动点名了技能使用 dependency-upgrade 和 test-generation 技能完成以下改动。AI按照技能文件里的顺序执行了这几件事读取最新pom.xml确认Spring Boot版本避免新代码用到旧版本不支持的特性。扫描配置类找到硬编码密钥替换为System.getenv(ORDER_SERVICE_SECRET)。在缺失环境变量的路径上抛出带操作提示的异常。按test-generation的规则使用JUnit 5写了两个测试用例正常取值和缺失变量场景。整个过程没有什么魔法它就是严格遵循了技能规则把该做的检查做完了。这恰恰是superpowers最大的价值它让AI的行为从“随机抽样模型知识”变成了“按项目现成规则执行”。4.4 第三步检查Diff与回归AI改完之后我让它用refactor技能里的“安全审查”子项做了一遍自检superpowers run review --diff这条命令会输出改动摘要并根据风险规则标出需要注意的位置。实测中它对“新增了环境变量读取”这个点给出了一条提示需要同步检查部署脚本和本地开发环境配置。这个提醒很实在如果是在CI流水线里部署光改代码不更新环境变量上线就会直接启动失败。4.5 执行结果与花费估算我记录了一下整轮任务消耗的token和我平时直接和AI对话写代码差不多但由于中途没有因为跑偏返工实际“有效产出/总token”的比值高了不少。换算成时间以前这类改动可能要来回调整三四轮现在一轮落地跑一次构建就过了。5. 常见问题与排查技巧实录最后这部分是我积累的排错经验。遇到问题不要慌大部分都和Node版本、权限、配置路径、上下文长度有关。我整理成速查表方便你直接对照。现象可能原因解决方案安装时报ERR_PNPM_RECURSIVE_EXEC_FATAL使用了很老的pnpm或npm版本升级npm至9以上或改用npx superpowers init初始化后AI没有读取技能文件未在Codex配置中指定系统提示词路径检查配置项--system-prompt或AGENTS.md路径是否正确长会话中AI开始忽略规则上下文被大量项目代码挤占把AGENTS.md改为索引模式让AI按需加载技能细节自动修改了不允许动的锁文件缺少规则约束在rules.json中加入forbiddenPaths: [package-lock.json, pnpm-lock.yaml]技能名称太泛导致不被触发技能名和任务关联度弱改成更具体的名称降低AI判断成本Windows PowerShell下运行异常命令路径分隔符和脚本不兼容在PowerShell中使用npx.cmd前缀或改用WSL提示词过长被模型截断技能文件写得太多太长精简每条技能到一屏以内把长篇背景放到单独参考文档5.1 连接不上模型服务时的排查思路这是个和superpowers无关但很容易误伤的问题。如果你用了CLI工具后发现AI完全不回话先别赖superpowers按三步排查第一步确认API Key和服务地址配置正确第二步用一条最简单的提示词测一下模型连通性第三步检查代理类环境变量是否拦截了连接。这里特别提醒一下国内网络环境下模型服务连接经常是最大变数但这不是本文范围你只需要记住排查顺序就行。5.2 关于多项目共用技能包的实践如果你和我一样同时维护好几个项目一定不要每个项目都跑一遍superpowers init然后把技能文件复制来复制去。更省心的做法是把公共技能目录单独放一个Git仓库然后在每个项目里用软链指过去。Linux和macOS上可以这样ln -s ~/workspace/team-superpowers .superpowersWindows上则可以使用目录联接junction。这样团队更新一次技能包所有项目自动生效。代价是某个项目需要特立独行时你得额外处理差异但这比维护多份拷贝轻松得多。5.3 断网离线环境下的兜底方案superpowers本身是纯文本技能包离线也能读但CLI初始化时需要联网拉取模板。如果你在隔离环境里可以找一台能联网的机器执行superpowers init生成.superpowers目录后把整个目录上传到内网仓库。后续内网项目直接拉取这个仓库即可完全不需要联网。6. 我的实操体会与扩展建议文章最后聊几句我自己的感受。用过一段时间后我最大的体会是superpowers解决的问题不是“AI不够聪明”而是“聪明没用在刀刃上”。它不能让你从80分AI变成120分AI但能让AI每次干活都稳定在80分水平而不是这次90分下次50分。对工程协作来说稳定性本身就值回票价。有个小技巧特别推荐每次执行完一类任务后花两分钟把本次新增的指令要求补进对应的技能文件里。比如我在做完上面那个加密配置改造后就在test-generation的规则里加了一条“涉及环境变量时必须同时生成缺失变量的测试用例”。这个小动作相当于让技能包随项目一起进化越用越顺手。再给两个可能的扩展方向。第一可以把superpowers和CI流程结合起来在提交PR前自动跑一轮技能包里的代码自检规则相当于给AI生成的代码加一道纪律闸门。第二如果你在做文档类工作可以考虑把“文档规范”也写成技能包让AI按团队模板生成接口文档或变更记录。它本质上就是一套可版本化、可评审、可演化的“行为规范系统”思想并不限于写代码。我现在的日常流程已经离不开它了。新项目克隆下来第一件事就是初始化.superpowers给AI立好规矩再放它进代码库。这套玩法的上限不取决于工具本身而取决于你愿不愿意花时间去打磨那几份规则文件。规则越贴近实际工程痛点AI给你的惊喜就越多。
