我一开始接触 superpowers 这个项目的时候以为是某个营销号又造了个概念。真正花了一个下午把它装进我日常用的 Codex 环境里跑完一个 Java 项目的重写之后我承认这东西确实有点东西。它不是什么藏在深处的黑科技也不是替代 AI 助手的另一个工具而是一套给 AI 编程助手装上“工作方法”的技能包。简单说它让 AI 从“能写出代码片段”进步到“知道怎么把一个任务从头到尾做完”。这个项目特别适合已经在用 Codex、Claude Code 这类 AI 编码工具、但又总觉得 AI 只管生代码不管后果的人。也适合团队想统一 AI 协作方式、把内部规范固化到工具里的场景。如果你只会把需求丢给 AI 然后祈祷它别乱写那 superpowers 能帮你把这条路走扎实。我下面会从核心思路、安装步骤、具体用法到一个完整的 Java 项目实操过程全部摊开来讲。1. 先搞清楚 superpowers 到底改变了什么1.1 它解决的不是“不会写代码”而是“不会干活”很多人用 AI 写代码第一感受是这东西“单点能力很强”。你让它写一个二分查找、解析一段日志、生成一个 DTO它通常几秒钟就能给你像样的结果。可一旦任务变成“从零搭一个订单服务需要带数据库、接口文档、测试、异常处理”AI 就很容易拉胯——不是代码报错而是思考方式不对它会忽略边界条件不做任务拆解甚至跳过测试直接上生产。说白了它缺少一个工程师的骨架。superpowers 这个项目解决的就是这个问题。它把“干活流程”封装成一组可复用的“技能skills”。每个技能包含明确的触发条件、执行步骤、输入输出要求和检查清单。比如“规划技能”会让 AI 先拆解需求、列出任务清单“测试驱动开发技能”会强制 AI 先写失败测试再写实现。它本质上不是在教 AI 更多语法而是把资深工程师的工作习惯变成一套 AI 可以执行的协议。我第一次跑完这套东西的感受是原本需要我反复纠正 AI“你漏了测试”“你先想清楚再动手”的对话变成了项目自己按流程走。AI 在每次动手前都会主动输出当前步骤的计划然后逐步推进。这个体验和平时聊天式写代码完全不同。1.2 为什么叫 superpowers技能复用与组合项目取名 superpowers 不夸张它用到的核心机制是“技能的组合与复用”。你可以把每个技能理解成一个乐高模块——它本身解决一个特定问题但组合起来能完成复杂任务。今天你在 Java 项目里用到“规划 测试驱动 代码审查”明天在 Python 脚本里还能复用同一套“测试驱动”只是具体实现变化而已。这种设计最直接的好处是你不需要为每个项目重复调教 AI。以前换一个技术栈可能要重新写一大段提示词把团队规范、输出格式、代码风格全塞进去。在 superpowers 的框架下你只需加载对应的技能文件AI 自动就知道该怎么走。技能文件通常就是结构化的 Markdown 或 YAML里面有描述、触发词、步骤清单、例子AI 读取之后就能照着执行。我实际用下来觉得它最厉害的地方不是某个技能多聪明而是“显式化”。工作流一旦写成技能每一步都看得见、可以改、可以被审查。团队里任何人都能往技能库里加东西也能发现 AI 为什么在某一步跑偏。这种透明性是普通提示词完全不具备的。2. 安装 superpowers从零开始的三步走2.1 环境准备与版本选择如果你平时已经在用 Codex那环境基本不缺什么。核心需要三样东西Git、Node.js推荐 18 LTS 或更高、以及一个能用的 AI 编程助手环境。我这里主要针对 Codex 讲但 superpowers 的设计思路同样可以沿用到其他支持自定义技能或命令的 AI 工具上。版本选择上我踩过一个坑一开始用的 Node 16跑初始化脚本时报了一堆语法错误后来换成 Node 20 就好了。如果你遇到类似问题不用怀疑是脚本坏了先看看 Node 版本是不是太老。另外git 需要支持普通 HTTPS 克隆国内网络有时候会比较慢但通常不影响使用。2.2 安装与加载到 Codex安装流程不复杂但有几个地方容易出错。我把完整命令放在下面你按顺序执行即可# 1. 克隆项目到本地工作目录 git clone https://github.com/your-user/superpowers.git ~/superpowers # 2. 进入项目目录 cd ~/superpowers # 3. 安装依赖 npm install # 4. 运行初始化脚本生成配置文件 npm run init初始化脚本会问你几个问题比如 Codex 配置文件路径、要不要启用内置技能包等。如果拿不准直接一路回车用默认值就行。之后脚本会在你的 Codex 配置目录里生成一个新的配置文件或者往现有配置里追加一段加载指令。你需要做的就是重启 Codex 会话让它重新读取配置。我自己的习惯是不把 superpowers 装在系统全局而是装在每个项目根目录旁边。这样不同项目可以用不同的技能组合不会互相干扰。具体做法进入项目目录后把~/superpowers里的skills文件夹复制一份到项目根目录再在 Codex 配置里指向这个相对路径。这样团队成员拉下代码后也能共享技能定义。2.3 安装后必须做的第一个检查装完之后别急着写业务代码先做一个“冒烟测试”。打开一个新的 Codex 会话直接输入/list-skills如果看到类似以下输出说明技能加载成功了Planning TestDrivenDevelopment CodeReview Refactoring如果提示找不到命令八成是配置文件的路径写错了或者 Codex 没有重启。还有一种情况有些版本的要求是技能命令必须以斜杠开头你直接输入“list skills”是无效的得用/list-skills这种格式。另外可以检查日志目录一般会生成一个superpowers.log里面记录了技能文件加载的详细过程。如果某个技能文件有语法错误日志里会明确标出是哪一行。这个日志是我排查问题时的第一求助对象比翻配置文件快多了。3. 核心用法怎么才能让 AI 真正“有超能力”3.1 调用方式slash 命令与自然语言触发superpowers 的调用方式主要分两种。一种是显式调用在对话里直接输入斜杠命令比如/plan、/tdd。另一种是隐式触发当 AI 识别到任务特征时自动启动对应技能。实际使用中我更推荐显式调用因为可控性更强。你让 AI 先执行计划技能它就会按步骤输出需求理解和任务清单你直接输入/review它就会对当前代码做一轮审查。有一点需要特别注意斜杠命令是精确匹配的不是模糊匹配。也就是说输入/plan有效但输入/plan now please很可能会被当成普通自然语言处理。社区里有人喜欢把所有触发词都写成自然语言结果 AI 总是忽略技能体验很不好。我自己的做法是在项目里建立一个固定的“操作手册”把所有命令列成表格每次新会话先让 AI 读一遍。3.2 内置技能地图规划、重构、审查、测试内置技能包里最常见的四个技能值得你花时间研究。下面这张表格总结了我的实际使用经验技能名称触发命令主要作用适用场景Planning/plan需求拆解、任务列表、验收条件输出新项目启动、大功能开发前TestDrivenDevelopment/tdd先写失败测试再实现通过任何需要稳定逻辑的功能开发CodeReview/review对照规范审查代码列出风险和修改建议提交 MR 前、代码合并前Refactoring/refactor在不改变外部行为的前提下优化结构老代码整理、消除重复逻辑我强烈建议先尝试Planning和TestDrivenDevelopment这对组合。原因很简单日常开发中“想清楚再动手”和“让测试拉着实现走”是最能提升代码质量的两件事。以前需要人肉盯着的流程现在 AI 会在技能文件约束下自动完成产出质量和稳定性都有明显提升。3.3 自定义技能把团队规范变成 AI 的肌肉记忆内置技能只是开始superpowers 真正值钱的地方是自定义技能。打个比方你所在团队要求接口必须带统一的响应包装、异常必须走全局处理器、日志必须打业务流水号。这些规范即使写在 README 里AI 也经常“选择性失明”。但如果你把这些要求写成技能每次调用都强制 AI 按清单执行效果就完全不同。一个最基本的技能文件结构大概是这样的name: JavaApiStandard description: 生成符合团队规范的 Java REST API triggers: - create api - 写接口 steps: 1. 确认 Controller、Service、Mapper 三层结构 2. 返回统一 ResponseWrapper 3. 异常统一由 GlobalExceptionHandler 接管 4. 打印包含 traceId 的出入参日志 5. 补充单元测试覆盖正常和异常路径 examples: - prompt: 创建一个查询用户的接口 response: | UserController - UserService - UserMapper 返回 ResponseWrapperUserVO 测试包含用户不存在场景写完保存到skills目录之后重新加载或重启会话即可。技能文件不用写得太长关键是让 AI 有据可循。这个机制对团队协作特别友好——技能文件本身就是规范文档放在 git 仓库里人人都能 review有问题直接改文件就行不用反复口头跟 AI 强调。4. 实操记录用 superpowers 从零跑通一个 Java 项目4.1 任务定义与技能选型为了把这套东西讲透我专门用一个最小 Java REST API 项目做实验。任务背景很简单提供一个/users接口支持获取用户列表和按 ID 查询数据存内存要求包含异常处理和单元测试。项目用 Maven 管理JDK 17。技术栈不复杂复杂的是“过程”。我选了三组技能Planning做需求拆解TestDrivenDevelopment保证实现有测试覆盖CodeReview在收尾时兜底检查。这三个技能正好覆盖“事前、事中、事后”。开局先输入/planAI 会在几秒钟内输出需求理解、接口定义、异常场景和任务清单。这里有一个细节规划阶段不要让 AI 直接写代码它如果“手痒”写了你可以明确说“停先把计划列完整”。superpowers 的规划技能会强制它输出验收条件这些条件后来会变成测试用例的雏形非常有用。4.2 实战过程规划 → 环境搭建 → 编码 → 测试规划输出之后我接着让 AI 用 Maven 初始化项目结构。因为前面有明确的清单AI 不再乱七八糟地生成十几个无关文件而是精准地创建了pom.xml、启动类、Controller、Service 和异常处理类。下一步是进入/tdd。这一步很有意思AI 会先写一个失败的测试比如断言调用/users/1能返回用户数据然后才写实现代码。如果你以前遇到过“AI 写完代码测试一跑就挂”的情况这个流程会非常舒服。因为它默认把测试当作验证标准没有测试通过它不会宣布任务完成。实际运行命令大概是这样的mvn test在我记录的这个案例里第一次测试确实跑出了失败——实现类还没写完整。然后 AI 根据测试结果补全了逻辑再次运行测试就通过了。整个过程没有出现中途干别的事、突然改接口签名的问题。因为技能的每一步都在检查当前状态是否符合预期。4.3 踩坑AI 跑偏时怎么拉回来再好的流程也架不住意外。我在实操中遇到了一个典型的“AI 自作主张”案例在实现用户列表接口时AI 发现内存里没有数据就自动加了一个DataInitializer类往里面塞了几条测试数据。从功能上说这没错但它没有在测试里覆盖这个行为而且计划阶段也没提过要加这个类。发现这个问题后我没有直接叫停它而是输入/review代码审查技能立刻把这次“计划外改动”标了出来并建议要么在计划里补充这个设计要么移除该类。这里我学到一个经验不要用自然语言跟 AI 争论“你为什么不按计划做”而是直接启动一个带检查清单的技能让流程来纠正流程。效果更好也更容易复现。收尾阶段我又跑了一次/review它对照 Common 规范查了一遍命名、异常处理、日志、测试覆盖。结果还真发现一个问题——Controller 里直接返回了内部实体对象而不是 VO。这是我之前故意不提醒它想看看 review 能不能抓到。结果它确实抓到了。这个能力在团队协作里非常实用相当于每次提交前多了一个不知疲倦的代码审查员。5. 常见问题与排查技巧实录5.1 典型故障速查表用了一段时间之后我遇到的绝大多数问题都集中在配置、命令和上下文三块。下面这张表是我自己的排障记录基本覆盖了你可能碰到的九成问题。问题现象可能原因解决办法输入/plan没反应Codex 没有重启或技能未加载重启会话确认配置路径正确技能加载列表为空skills 目录位置不对检查配置文件里的路径使用绝对路径Node 脚本运行报错Node 版本过老升级 Node 到 18 LTS 以上日志里有 YAML 解析错误技能文件缩进有问题用在线 YAML 校验工具检查文件AI 不按技能步骤走触发词没被识别改用精确斜杠命令或在开头加一句“按当前技能流程执行”Java 项目测试跑不起来JDK 版本与 pom 不一致统一JAVA_HOME和 Maven compiler 版本技能多了之后上下文膨胀每次回话都加载全部技能按项目按需加载只保留需要的技能目录如果你遇到“AI 不按技能走”的问题我这里有个独家排查方法临时关闭所有技能用最小化提示词测试 AI 是不是本身就没听指令。如果这时它能听问题多半出在技能描述写得太模糊如果它还是不听那可能是你对 AI 的顶层指令配置不对得先回去看 Codex 的系统配置。5.2 三个能救命的小技巧第一个技巧每次新会话开始先加载技能。你可以在项目根目录放一个AGENTS.md或者类似说明文件内容写上“本项目使用 superpowers 工作流请先执行 /list-skills 并默认为我加载 Planning、TDD、Review 技能”。这样即使忘了手动敲命令AI 也会主动读取并遵循。第二个技巧把技能文件纳入版本库。很多人忽略这一点。技能文件不是个人配置它应该是团队规范的一部分。放在 git 仓库里以后每次规范更新都会有记录新人拉完代码就能获得相同的 AI 行为而不是靠口口相传。第三个技巧善用--dry-run或者“仅输出计划”模式。在需要处理大任务时先让 AI 在不改动文件的情况下完整输出它准备执行的步骤你确认没问题再让它真正动手。这个习惯能帮你避免 AI 做出一堆破坏性改动才发现方向错了。superpowers 本身就强调显式化步骤但你仍然可以在技能之外给 AI 加一道“先看摘要再动手”的约束。5.3 如何维护自己的技能库技能库和代码库一样需要持续维护。我建议每完成一个重要项目就回顾一下哪些流程 AI 跑得顺、哪些地方总是别扭。顺的流程固化到技能文件里别扭的地方不是去写更多提示词而是去修改技能文件里的步骤顺序或检查清单。比如我最初写的 Java 技能文件里漏了“输出参数日志”这一条导致 AI 生成的接口日志不完整。后来我在检查清单里加了这一步之后生成的新接口就再也没漏过日志。这种“经验沉淀”的感觉比任何提示词优化都让人上瘾。你维护的技能越多你的 AI 助手就越像团队里那个从业十年的老工程师。我个人在实际操作中的体会是superpowers 没有改变 AI 写代码的原理它改变的是我们使用 AI 的方式。从“一次性问答”变成“定义流程、显式执行、持续修正”这个过程其实也是在逼我自己把工程经验梳理清楚。很多你以为自己很熟悉的工作步骤真要写成技能文件的时候才发现原来漏了不少关键环节。最后再分享一个小技巧不要一开始就追求大而全的技能包。先挑最常用的三四个技能跑熟之后再慢慢加。技能文件贵在精不在多。一个团队只需要几个真正贴合业务习惯的技能就能让 AI 助手的产出稳定一大截。等你积累出自己的技能库再回头用真的会有种“这才是 AI 编程该有的样子”的感觉。