最近在折腾 AI 编程辅助工具的时候我接触到了 superpowers 这套技能增强方案。它解决的问题特别实在AI 写代码很猛但让它按规范、按步骤、按团队约定来干活往往得靠临时写一长串 prompt。superpowers 就是把这类高质量指令沉淀成可复用的技能文件让 Codex CLI 这类编码代理在需要的时候自动加载对应技能完成从“一句话生成代码”到“按工程标准落地任务”的转变。这篇文章不是官方文档的复述而是我把自己的安装、配置、使用过程完整记录下来的结果包含了我实际踩过的坑和调优经验适合正在评估它、或者已经装上但还没玩明白的开发者参考。1. 追根溯源superpowers 到底解决什么问题1.1 一个让很多开发者挠头的场景先还原一个我经常遇到的场景项目里有个UserService1200 行里面混着订单查询、权限校验、邮件模板拼接、甚至几段复制粘贴过来的支付回调逻辑。直接在 Codex CLI 里敲一句“帮我重构一下 UserService”它大概率会给你一个看似合理、实则把业务逻辑打乱的重构方案。更常见的是模型改到一半就忘了你在开头提的约束——比如“不要动对外接口的签名”这条红线它可能为了代码整洁把整个类的公开方法全改了。问题的根源不在于模型能力而在于你没有给它一本“怎么干活的手册”。通用对话模型不掌握你们项目的编码规范、测试习惯、验收标准。这就是 superpowers 这类技能框架存在的价值把团队里“隐形但重要”的工程知识显性化成模型可以直接加载和执行的技能文件。1.2 superpowers 的核心理念技能即代码superpowers 最重要的设计理念可以概括成一句话技能即代码。它把“如何完成某一类任务”的定义从临时对话里的自由发挥变成了结构化的目录和文件。每个技能skill通常包含三部分技能说明这个技能在什么场景下使用、能解决什么问题、边界在哪里。执行步骤模型需要按顺序完成的子任务列表每一步都有明确的产出物。质量检查清单任务结束前必须逐项确认的验收标准比如“是否补充了测试”“是否保持接口兼容”“是否更新了文档”。我用一个生活类比来说明以前你让 AI 干活像你在电话里临时给新员工口述工作流程讲多少算多少效果取决于他当时的理解能力。而 superpowers 的玩法是给这个新员工发一本 SOP 手册每个任务对应一套可翻查的操作规程。模型要做的就是从技能库里找出那本手册照着执行。这样做的好处一是输出质量稳定二是这套手册本身就是团队经验的可维护资产。1.3 它的适用边界和人群我在实际使用中感受到superpowers 的甜区非常明确适合那些已经依赖 AI 编码助手、但又对代码质量有专业要求的开发者。尤其是做历史遗留系统重构、跨模块接口调整、框架版本升级这类复杂任务时技能文件能把模型的“即兴发挥”收束到可控轨道上。反过来如果你只是偶尔让 AI 写个正则、补个工具函数装这套东西属于过度设计。它带来的目录结构和配置成本对轻量用户是负担。我建议你在进入下一节安装步骤之前先想清楚自己的使用强度每周至少会发起 5 次以上多步骤编码任务的开发者这个投入非常值得。2. 环境准备与 5 分钟快速安装2.1 前置依赖与版本检查安装 superpowers 之前首先要确认本机环境是干净的。它依赖 Node.js 运行环境建议使用 18 LTS 或更高版本主要原因是技能引擎的异步任务调度用到了较新的 Node 特性老版本会直接报语法错误。Git 也是刚需因为技能的更新和团队共享依赖 Git 协作流程。打开终端按顺序执行下面的检查命令node -v npm -v git --version我这边实测的输出大致是v20.11.1 10.2.4 git version 2.39.3如果你在 Windows 上开发建议直接使用 Windows Terminal并且把 Git 的usr/bin目录加入 PATH否则后续执行技能脚本时可能出现sh命令找不到的情况。这些前置依赖不复杂但值得一条条确认我之前见过太多人卡在“明明装好了却跑不起来”的尴尬阶段最后发现是 Node 版本太低。2.2 安装 superpowers 的两种方式确认环境没问题之后接着安装 superpowers 本体。目前社区里主流的做法有两种我分别说一下各自的适用场景。第一种是使用 npm 全局安装这也是我最推荐的标准方式npm install -g superpowers-cli安装完成后你要确认一下是否成功进入 PATHsuperpowers --version如果终端提示找不到命令多半是 npm 的全局 bin 目录没有配置到 PATH这个我在后面常见问题部分会展开讲。第二种方式是从源码仓库克隆安装适合需要二次开发或者想贡献技能的玩家git clone https://github.com/superpowers-lab/superpowers.git cd superpowers npm install npm run build npm link两种方式的对比我用表格列在这里对比维度全局安装方式源码克隆方式安装速度快一条命令搞定慢需要编译构建升级方式npm update -g即可需要 pull 最新代码再构建二次开发不推荐文件分散自由修改随时调试适合人群大多数使用者需要定制技能的进阶用户如果你是刚开始接触先走全局安装的路线把核心流程跑通。等真正理解了技能系统的结构再决定是否需要自己维护一套源码版。这个顺序能帮你降低初期认知负担。2.3 初始化与自检安装完成后进入你要应用 superpowers 的项目根目录执行初始化命令superpowers init执行完之后你会看到项目里多出了一个superpowers/目录。它的初始结构长这样superpowers/ ├── skills/ │ ├── refactor/ │ │ ├── SKILL.md │ │ ├── examples/ │ │ └── scripts/ │ ├── code-review/ │ ├── test-driven/ │ └── repo-health/ ├── templates/ └── config.yaml这里我解释一下各个文件的作用skills/目录存放技能定义每个技能一个子目录SKILL.md是技能的核心描述文件模型在执行任务时主要读取它examples/目录存放参考样例这是让模型理解“长什么样算合格的输出”的关键材料scripts/目录可以放一些辅助脚本比如编译检查、测试执行等。初始化完成之后强烈建议先跑一遍自检命令确认所有依赖和配置都没问题superpowers doctordoctor命令会检查 Node 版本、npm 配置、技能目录结构、以及 Codex CLI 是否正常安装。我见过不少安装问题其实在doctor这一步就暴露了。看到如下输出说明一切正常✔ Node.js version check passed ✔ Superpowers CLI version 1.2.3 ✔ Skills directory found ✔ Codex CLI integration ready千万别跳过这一步自检它能帮你把后续排查时间大幅缩短。3. 核心能力深挖安装之后你能得到什么3.1 内置技能工坊开箱即用的模板库初始化完成后superpowers 会自带的技能模板已经能覆盖不少日常开发场景。我把最常用的几个整理成了表格方便你对照自己的需求技能名称适用场景关键产物典型任务refactor代码结构重组重构方案文档、前后对比抽取公共类、消除重复逻辑test-driven测试优先开发测试用例、覆盖率报告为遗留代码补测试code-review代码审查问题清单、修订建议列出潜在缺陷和优化点repo-health仓库体检健康度报告检查依赖漏洞、大文件、死代码api-design接口设计API 文档草案设计 RESTful 接口契约migration框架/依赖升级迁移步骤清单Spring Boot 版本升级你可能会问这些技能模板和直接在对话里说“帮我做代码审查”有什么区别区别在于执行深度。直接说“帮我审查代码”模型可能只会扫一眼泛泛地给几条意见。而加载code-review技能后模型会严格遵循技能文件里的步骤先定位变更范围再检查边界条件再逐一对照质量清单最后给出带严重级别标注的问题列表。模型还是那个模型但行为约束强了很多。3.2 与 Codex CLI 的配合模式superpowers 的一个核心使用场景就是和 Codex CLI 搭配工作。Codex CLI 支持通过项目根目录的AGENTS.md文件来加载指令superpowers 正是利用这个机制把技能目录交给 Codex 自动发现。具体来说你要在项目根目录创建一个AGENTS.md文件内容大致如下# 项目指令 本仓库使用 superpowers 技能系统来规范 AI 编码任务。 ## 技能加载 当执行与代码重构相关的任务时必须读取 superpowers/skills/refactor/SKILL.md 并严格按其步骤执行。 当执行与测试相关的任务时必须读取 superpowers/skills/test-driven/SKILL.md 并严格按其步骤执行。这样做的好处是Codex CLI 在启动时会自动读取AGENTS.md文件相当于一进场就拿到了“仓库工作手册”。当任务需求涉及到某个领域它就会按照文本里的指引去加载对应技能不依赖你每次在对话中重新唠叨规范。我在团队里测试过这个机制效果确实不一样。以前用 Codex 直接干重构任务它的第一次输出经常需要我来回纠正接入了 superpowers 技能加载机制后模型的第一版方案就能做到“按既定步骤走”返工次数明显减少。这个过程本质上是把团队纪律注入到了 AI 的执行流程里。3.3 Java 场景为什么值得重点关注在各种语言场景中Java 是表现最明显的一个。原因是 Java 项目有几个特点强类型约束、依赖体系重、模块边界多、测试体系复杂。这些特点让 AI 容易在“看似改对了”的表面下引入编译错误或隐藏的行为变化。我举一个实际例子。在 Spring Boot 项目中做一次接口拆分模型如果不知道你的模块边界和依赖约定很可能会把UserService里的方法直接搬到一个新建的MemberService里然后留下一堆循环依赖和注入失败的隐患。Java 场景下的 AI 辅助最缺的就是一套“约束清单”。superpowers 在 Java 场景的价值就在这里。它可以通过技能文件里预设的检查脚本比如mvn -q compile mvn -q test让模型在任务收尾阶段强制跑一遍编译和测试而不是只顾着“生成漂亮的代码”。下面是一个常见的 Java 技能片段## 质量检查清单必须全部满足 - [ ] 项目通过 mvn -q compile 编译无新增错误 - [ ] 所有修改的模块通过 mvn -q test原有测试不回归 - [ ] 未改变对外公开方法的签名 - [ ] 新增代码符合团队 Checkstyle 规则 - [ ] 更新了必要的 Javadoc 注释有了这份清单模型的“自由创作欲望”会被有效约束所有输出都要对这份验收标准负责。这不光让输出结果更稳定也让后续的人工审查工作量显著降低。4. 实操演示让 superpowers 跑通一个真实任务4.1 场景设计对一个遗留模块做重构理论讲再多不如完整走一遍流程。我设计了一个真实的演练场景假设当前项目里有个PaymentService.java里面既处理支付核心逻辑又混杂了营销优惠计算和用户通知发送属于典型的需要拆分的遗留模块。在这个场景下任务目标清晰把营销优惠计算逻辑抽到独立的PromotionCalculator.java同时保持PaymentService对外接口不变。这种任务如果没有明确的步骤约束AI 很容易把接口签名也改了导致调用方大量出错。4.2 逐步执行实录首先在项目根目录的AGENTS.md中指定了任务域对应的技能。然后我在 Codex CLI 中发起任务codex 按项目规范对 PaymentService 执行重构拆分详见 AGENTS.md 中的技能指引因为 AGENTS.md 已经写了“重构任务需要加载 refactor 技能”Codex 会自动去读取superpowers/skills/refactor/SKILL.md。技能文件里定义的标准流程是这样的# Refactor 技能 ## 适用条件 - 需要调整类结构、拆分模块、消除重复代码时使用本技能。 ## 执行步骤 1. **收集现状**列出目标类的所有公开方法和依赖关系。 2. **制定方案**基于现有方法调用链推算拆分边界明确新类的职责清单。 3. **模拟改动**先给出改动后的类结构不直接修改代码。 4. **编码实施**按照方案逐步修改代码保持每个中间状态可编译。 5. **质量验证**运行编译、测试、静态检查逐项确认清单。 6. **输出报告**列出改动文件清单、影响范围、后续建议。这个流程最大的特点是把“先给方案再动代码”固化成强制步骤。模型在第 3 步就会停下来输出重构方案等你确认后再继续。这比让模型直接改代码安全得多也是我觉得 superpowers 最有价值的机制之一。为了把业务上下文给足我把任务描述写在了仓库的superpowers/templates/task-card.md里。这类任务卡片可以辅助模型对齐目标内容可以按需扩展# 任务卡片拆分 PaymentService ## 背景 PaymentService 同时负责支付处理、优惠计算和用户通知产生职责过载问题。 ## 目标 将优惠计算逻辑私有方法提取到独立的 PromotionCalculator 公共服务类。 ## 约束 - 保持 PaymentService 对外公开方法签名完全不变。 - 优惠计算相关的业务规则不得有任何变化。 - 新类需要有单元测试覆盖核心算法。 - 不得修改支付流程的调用顺序。 ## 验收条件 - [ ] 编译通过 - [ ] 新类单测通过 - [ ] PaymentService 对外签名不变 - [ ] 代码审查无阻断项4.3 质量校验环节模型按技能流程执行完编码后走到了第 5 步质量验证。这里技能文件中的脚本会自动触发 Maven 编译和指定测试mvn -q compile mvn -q test -DtestPromotionCalculatorTest我实测跑完后编译一次通过但单测暴露了两个边界问题一个倒计时优惠场景的精度表现不对一个金额取整逻辑与旧实现不一致。这个结果很有代表性——如果没让模型严格执行测试环节它大概率会自信地把代码交上来留下隐患。因为技能文件里的检查清单强制它“必须验证测试结果并修正”模型会回头读取失败日志自行修复边界问题再重新跑测试直到清单全部勾完。最后技能流程会强制要求模型输出重构报告包含改动文件、影响范围、测试结果。我截个关关键结构## 改动清单 - PaymentService.java移除优惠计算相关私有方法新增 PromotionCalculator 注入。 - PromotionCalculator.java新增承载所有优惠计算逻辑。 - PromotionCalculatorTest.java新增覆盖 6 个核心场景。 ## 影响范围 - 支付流程调用链不变对外接口签名保持兼容。 - 依赖注入配置需在 ApplicationContext 中注册新 Bean。 ## 测试结果 - mvn compile: PASS - PromotionCalculatorTest: 6/6 PASS - 全量回归测试: 待 CI 执行这个报告直接可以作为 PR 描述的基础省了我不少整理时间。5. 参数调优与团队落地配置5.1 核心配置项解读superpowers 使用superpowers/config.yaml作为主配置。我把自己调过的核心参数整理成一张表配置项默认值说明我的推荐context_budget8000对话上下文预算 token 数大型仓库开 12000max_rounds8单任务最大执行轮次复杂重构开 12skill_autoloadtrue是否根据任务自动识别技能保持开启checklist_stricttrue清单未完成时是否阻止提交保持开启model_profilebalanced模型调用策略档位看预算调整script_timeout60技能脚本执行超时秒数大型项目调 120context_budget是影响最明显的参数。如果预算太小模型在处理多文件任务时容易“失忆”前面定下的拆分规则后面就不遵守了如果预算太大速度会明显变慢交互体验也很卡。我建议你先从默认值出发观察模型在任务后半段是否频繁忘记前面的约束再做微调。5.2 根据项目规模调整策略不同体量的仓库参数策略完全不一样。我踩过几次坑之后总结出了一个相对靠谱的推荐组合小型项目少于 1 万行代码context_budget保持 8000max_rounds设为 6 足够不需要额外扩展技能中型项目1 万到 20 万行context_budget提升至 10000 到 12000max_rounds调到 10建议为仓库特有代码规范写一份定制技能大型仓库20 万行以上context_budget12000 以上但不要无限扩大max_rounds12 或更高需要把任务拆成更细的技能避免单次任务承载过多内容一个重要心得是与其盲目调高上下文预算不如把任务拆得更细。比如一个大模块重构拆成“抽取优惠计算组件”“调整依赖注入方式”“补充单元测试”三个任务分别执行每个任务的上下文都足够集中效果比一次全做完要好得多。5.3 团队统一落地的建议如果你想把 superpowers 推广到整个团队有几个配置层面的建议值得参考。第一个建议把superpowers/目录纳入 Git 版本控制。技能文件本质上是一套工程资产它记录了团队希望 AI 遵循的规则后续任何人修改都需要走代码评审流程。第二个建议使用.superpowersrc文件统一锁定团队级配置。比如你可以约定所有成员必须开启checklist_strict这个参数写在个人配置里很容易被关掉写进仓库级的强制配置里就不会出现行为分叉。第三个建议定期更新技能库。我建议每两个迭代周期团队聚一次把这段时间在代码评审中暴露出来的新规则沉淀进技能文件。比如如果发现模型经常在 MongoDB 查询条件上写错索引提示就完善相关技能示例。这样技能库会像团队知识库一样持续生长。6. 常见问题与排查技巧实录6.1 安装时报错的 3 个典型场景我在安装和帮同事排查时遇到过几个高频问题整理成一个速查表症状可能原因解决方案Error: EACCES permission deniednpm 全局目录无写权限检查 npm 全局路径权限或使用 nvm 管理 Node 版本SyntaxError: Unexpected tokenNode 版本过低升级到 Node 18 LTS 以上superpowers: command not foundnpm 全局 bin 目录不在 PATH将 npm 全局 bin 路径加入系统 PATH安装过程卡死不动网络不稳定或镜像源问题更换 npm 镜像源后重试Node 权限的问题是 Windows 和 Linux 双平台的重灾区。我个人的建议是尽量使用 nvm 这类版本管理工具而不是直接以管理员身份去改全局目录权限后者虽然能解决一时问题但会把本机环境搞得很乱。6.2 明明安装了技能却不生效有一种非常让人头大的情况superpowers 装好了技能目录也生成了但 Codex CLI 执行任务时就像没看见一样完全按自己的路子走。碰到这种情况按下面的顺序排查第一步检查AGENTS.md文件是否真的被 Codex 读取。可以在启动 Codex 时观察开场信息里是否出现了你写的指令摘要。第二步检查技能加载语句里的路径是否和实际目录完全一致。一个很小的疏忽是写了superpowers/skills/refactor/但实际目录是superpowers/skills/refactor.lite/路径对不上加载就会失败。第三步确认技能文件本身格式没问题。SKILL.md里的---分隔线、标题层级、列表格式都必须规范任何 Markdown 结构错误都可能导致解析中断。这里有个独家技巧在技能文件的执行步骤里加一条“第 0 步确认已加载本技能并在输出开头声明技能版本”。如果模型按步骤执行你就能从它的输出第一行确认技能加载成功。如果它在第一步就违反了这条输出声明你立刻知道指令没有生效不用等整个任务跑完才发现。6.3 模型输出质量还是不稳定怎么办这个问题我一开始也遇到过。后来我意识到技能文件只是给模型提供了“做事的框架”但框架的材质和精度直接决定输出质量。如果你的技能描述写得太空洞比如只写了一句“尽可能保持代码整洁”那模型输出的质量依然不可控。真正管用的做法是在技能文件里给出正反例。我在refactor技能里补充了一段参考示例让模型区分“合格的重构”和“危险的重构”## 参考示例 good 把类似格式的重复逻辑抽取为工具方法调用方保持逻辑语义不变。 /good bad 为了消除重复改变原有方法的参数顺序或返回值类型。 /bad经验表明给模型看具体的正反例比抽象描述一百遍“要兼容”都管用。这就像教新人写代码光讲原则没用得让他看到好代码和坏代码长什么样他才能真正建立判断标准。技能文件不是写完就完事的。我建议每两周回顾一次看看最近模型输出里反复出现的质量问题觉得哪个模式不对劲就往技能文件里加一个反例。这样持续迭代模型的输出会越来越符合团队口味。7. 我的使用体会与后续扩展从第一次接上 superpowers 到现在它确实改变了我的 AI 编码工作流。最直观的收益有三个一是历史遗留项目的重构终于敢交给 AI 了因为技能里的分步确认机制让过程可控二是团队的编码规范可以通过技能文件沉淀下来不用每个任务都在对话里重复交代三是代码审查阶段的沟通成本降低了模型输出的结果更贴近团队预期审查者可以把精力放在真正的业务逻辑上。当然也不是没踩过坑。最典型的一次是我把一个技能文件写得特别“全面”步骤、说明、示例恨不得面面俱到结果整个技能描述超过了上下文预算模型读取时被截断反而导致执行结果残缺。后来我学会了给技能瘦身只保留核心流程、关键清单和一组正反例其余内容放到examples/目录按需加载。技能是指导框架不是百科文档写得太满反而影响效果。最后再分享一个值得尝试的扩展方向把技能文件本身纳入团队的知识库管理比如绑定到文档平台的某个空间让非技术人员也能阅读和反馈。开发者和业务协作时经常需要解释“AI 重构了什么、为什么这么改”superpowers 生成的报告正好可以作为沟通素材。后续我还计划把技能模板和 CI 流程打通让模型在提交代码之前自动触发技能检查这一步做完之后AI 辅助编码的质量把控就真正进入了自动化时代。