1. superpowers 是个什么东西别把它当成又一个 AI 插件先说个我观察到的现象很多人用了 Codex 一段时间之后感受都是一开始很惊艳用着用着就感觉它变笨了。不是说模型本身退化了而是它对你的项目一无所知每次对话都要从零开始理解上下文遇到多文件改动、跨模块重构、工程规范约束这类任务它就容易犯只改表面、不动根因的毛病。superpowers 这个项目解决的就是这个问题。它的定位不是给 Codex 加一个技能而是给 AI 编码助手装上一整套工作方法论。打个比方:如果把 Codex 比作一个聪明但缺乏经验的新程序员superpowers 就像是塞给他一本资深工程师的工作手册——遇到问题先怎么分析、代码怎么写符合规范、写完要怎么自检、哪些场景必须反问确认。有了这本手册新程序员的产出质量就会明显提升这就是超能力的来源。这个项目适合谁用如果你是个人开发者经常用 AI 写代码但觉得它只能写单点功能撑不起整个任务superpowers 值得试如果你在小团队里负责技术基建想让 AI 的产出更标准化它也很对路。说白了它做的是把人的经验和AI 的能力之间的鸿沟填上——这恰恰是当前 AI 编程工具最容易被人忽略的一层。1.1 它解决的痛点为什么 AI 写代码总是浅一层先说一个日常场景。你直接让 Codex帮我写个用户认证模块它能写出来吗能。但写出来的往往是模板化的、没有任何业务判断的代码——不会考虑你的项目里已有的日志框架、异常处理风格、数据库事务边界、接口约定的返回结构。为什么因为 Codex 根本不了解这些约束你也没有给它提供了解约束的路径。superpowers 的思路是与其每次都在对话里反复叮嘱 AI不如在项目里预置一套行为规范。这套规范包含项目背景、编码约定、常见任务的执行步骤、禁止事项、验收标准。AI 每次接手任务时先读取这份规范再动手相当于你给它做了一个入职培训。很多前期看似多花的配置后期节省的是大量来回改 prompt 和返工的时间。另一个痛点是上下文管理。Codex 的上下文窗口再大也有限聊到第三轮、第五轮的时候早期的重要约束可能已经被冲掉了。superpowers 通过把关键信息拆成结构化的技能文件Skill 文件让 AI 能在需要的时候按需加载对应知识而不是从头到尾把所有内容都塞进上下文。这个设计思路我深有体会——它不是增加信息量而是让信息在正确的时候出现在正确的位置。1.2 它的运作方式技能文件与工作流注入superpowers 的核心可以拆成两样东西技能文件Skills和工作流定义。技能文件是一个个 Markdown 文档每个文档对应一个特定领域或任务类型。比如你用 Java 做后端可以有一个Java 编码规范技能文件你在写 SQL 性能优化就有一个SQL 调优检查清单。这些文件不是给人看的说明书而是给 AI 读的操作手册。当任务涉及某个领域时AI 会主动加载对应技能文件然后按里面的规则执行。工作流则是一组固定流程的描述。比如面对新需求先拆解任务清单再写实现计划再逐模块实现最后自测这套流程被固化下来之后AI 不会一上来就闷头写代码而是先展现对问题的理解再动手。这其实就是资深工程师和普通程序员的最大差别后者急着动手前者先想清楚。两者的关系有点像做事先立规矩、再按规矩办事。superpowers 实际上是把规矩做成了 AI 可以直接读取、遵循、自我检查的内容结构。我最初用的时候觉得它像提示词模板用深了才发现它是体系——单个模板只能约束一次对话技能文件的组合可以覆盖一个项目整个生命周期里的大量重复场景。2. 从零到跑起来superpowers 的安装与初始配置安装这一步网上能找到的教程大多写得含糊要么只给 clone 地址要么直接跳过前置条件新手照做很容易卡在半路。我把完整过程捋一遍先说清楚我自己的环境macOS 最新版 Codex CLI Node.js 20。不同系统差异不大但有几步要注意。2.1 前置条件先确认你的基础环境superpowers 本质上是一套基于 Codex/Skills 生态的增强配置所以前提是你已经装了 Codex CLI 并且能正常跑通基本对话。另外它需要 Node.js 环境来做一些脚本化操作建议版本不低于 18我用的是 20目前没遇到兼容问题。安装之前先确认两件事第一你的 Codex CLI 能正常访问第二项目目录的读写权限没问题——因为 superpowers 会在你的项目里生成一份技能配置目录如果权限不对后面加载会很别扭。我用的是官方提供的 Node 版 Agent Skills 目录结构下载后直接解压到~/.codex/skills或者项目内.agents/skills目录都可以。提示如果你同时装了多个 AI 编码助手建议别把技能配置全局铺开以每个项目单独配为主避免不同工具的配置互相干扰。我一开始偷懒用了全局配置结果在另一个测试项目里出现了技能文件互相覆盖的怪问题。2.2 安装步骤别多走弯路整体装起来其实就三步但每一步都有容易忽略的细节。先把项目 clone 下来git clone https://github.com/clemlesne/superpowers.git cd superpowers这里有个容易踩的坑有些人会在这一步直接npm install npm run build但仓库的构建脚本可能在你的 Node 版本下有些兼容作业。我建议先跑一次node -v确认版本然后按 README 里的步骤来不要自己跳步。官方主要提供两种接入方式一种是直接把示例 skills 目录复制到你的 Codex 配置目录另一种是运行安装脚本自动生成配置。我个人更推荐手动复制的方式因为能看清每个文件有什么用后面排查也方便。cp -R skills/* ~/.codex/skills/复制完成后在 Codex CLI 里输入一个简单问题比如列出你能用的技能如果能看到 superpowers 相关技能出现在列表里就说明加载成功了。我建议此刻做一个最小功能验证比如让它按照某个技能文件里的规范生成一段符合 Google Java Style 的代码。能跑通才算真正装好了。2.3 首次启动校验确认技能真正被加载这一步经常被忽略但它恰恰是区分装好了和觉得装好了的关键。很多人 clone 完、复制完目录就以为自己搞定了结果 Codex 根本没有读取到那些技能文件对话里问它你有什么技能它一无所知。校验方式很简单。先在项目目录里放一份技能文件内容可以很简单比如定义所有类名必须使用 UpperCamelCase变量名使用 lowerCamelCase然后问 Codex 一句根据项目技能规范下面这段变量命名有什么问题如果它能准确指出问题说明技能真的生效了如果它答非所问或者干脆说我没有看到任何规范那就要回去检查配置文件路径。另一个更快的验证方式是看 Codex 的启动日志。通常终端里会打印加载了哪些技能文件只要你看到 superpowers 的字样就说明加载过程没有问题。这套校验逻辑在后面排查问题时会反复用到——先确认技能被加载再判断是内容写错还是路径不对能省下大量时间。3. 核心能力逐项拆解所谓超能力到底强在哪配置好之后接下来是我最想写的一部分superpowers 到底给了 Codex 哪些超能力这些能力不是玄学每一个都有对应的机制在背后支撑。我拆成三块来讲。3.1 任务规划与破题让 AI 先想明白再动手接任务不急着写代码这是 superpowers 给我带来的最明显变化。默认情况下AI 面对实现一个订单状态机这种任务时会直接开写代码可能是对的但没有体现你的业务规则比如状态流转里 A 状态能不能直接跳 C 状态、哪些操作需要记录审计日志。有了任务规划技能后Codex 会先做三件事列出它对本任务的理解和你确认是否准确拆解需求清单标出哪些是明确要求、哪些是隐含假设给你展示它的实现计划等你确认了才动代码。这个交互习惯一开始让我觉得多此一举但用多了就明白它的价值。AI 对需求的理解一旦有偏差你可以在它动手之前就纠正而不是等代码写完、测试跑崩了才回头改。这其实就是软件工程里先设计后编码的老原则只不过被迁移到了 AI 协作场景里。还有一个细节值得提当任务涉及多个文件时superpowers 会让学生先绘制一份文件影响图列出本次改动会碰到的文件、依赖关系以及测试范围。这极大地减少了 AI 的局部视野问题——它不再只盯着你让它改的那个文件而是把相关联的代码都纳入考量。3.2 技能库驱动的专业输出Java 规范也可以硬约束第二个核心能力是按项目规范写代码。你完全可以定义一份 Java 项目的编码规范技能文件里面写明包结构、命名规则、日志框架约定、事务处理风格等。之后无论 Codex 写什么代码都会自动套用这套规范。我举个例子。我的技能文件里写了这么一行规则所有对外 DTO 字段必须显式标注NotNull、Size等校验注解不允许直接使用基本类型承接外部入参。以前我靠 chat 时反复提醒效果时好时坏现在技能文件里写清楚Codex 生成的 DTO 基本不需要我人工补注解偶尔漏一两个它自检环节也能抓出来。这种硬约束的好处在于团队里每个成员用 AI 写代码都能保持同一水准。以前新人写的代码和老手写的代码一眼就能看出差距现在有了技能文件的约束差距被大幅缩小。当然前提是技能文件本身写得足够细这个我在后面避坑部分会展开讲。3.3 自检与反馈回路不光是写完还要查一遍superpowers 另一个让我觉得实用的点是它内置了自检清单。每次生成完代码AI 会根据技能文件里的自检项逐条过一遍比如是否正确处理了边界条件有没有严格的空指针保护是否遵循了项目里的异常处理规范。这个机制单独拿出来说好像很普通但配上反馈回路就很有价值了。以前 Codex 写代码是一锤子买卖你让它改它才改你自己不发现问题它就默认一切正常。superpowers 的自检机制相当于给 AI 加了一道编译期 lint让它在交付之前就发现自己的问题。有一次我让它写一个并发任务执行器它初版代码竟然自己发现了一个竞态条件还主动标注此处存在数据竞争风险建议加锁或改用并发安全的数据结构。这种事以前我从来没遇到过。那一刻我突然理解了项目名字的含义——它确实给 AI 加了一种自我审视的能力。4. Java 项目实战用 superpowers 重构一段真实代码光说机制有点空这里用一个实际场景把前面的概念串起来。这周同事让我帮忙重构一个订单模块里的状态机实现原来的代码是用一堆 if-else 堆的新增状态非常痛苦。整个过程我全程在 Codex superpowers 环境里完成这里记录一下实操链路。4.1 场景设定一段让同事头疼的 if-else原始代码大概是这样的逻辑已简化public String getNextStatus(String currentStatus, String action) { if (CREATED.equals(currentStatus) PAY.equals(action)) { return PAID; } else if (PAID.equals(currentStatus) SHIP.equals(action)) { return SHIPPED; } else if (SHIPPED.equals(currentStatus) CONFIRM.equals(action)) { return COMPLETED; } else { throw new IllegalStateException(Illegal transition: currentStatus - action); } }需求是新增一个退款状态并且CREATED和PAID状态都可以进入退款退款之后不允许再支付。这种改动放到 if-else 里也能做但状态一多就难以维护。我的目标是用状态机模式重写并且加一份清晰的流转配置。4.2 从需求到方案的完整链路superpowers 怎么介入我把需求描述给了 Codex它没有直接写代码而是先输出了一段任务分析明确现状当前用 if-else状态流转隐藏在各分支中新增状态需要修改核心方法提出方案引入枚举定义状态用MapState, ListTransition描述状态流转拆分任务清单定义状态枚举、定义流转配置、实现状态机执行器、补充业务异常、编写单元测试。这个顺序看起来平淡但对比直接生成代码它的执行路径完全不同——先有结构再有实现。接下来它按清单逐步执行每一步完成之后会显示完成 xx下一步执行 xx。这是我在之前的工作流里最认可的一点AI 不再是个代码生成器而是像结对编程的伙伴一样按你的项目背景一步步推进。整个重构过程大约 15 分钟其中我人工介入的部分只有两次一次是确认退款后禁止支付的业务规则另一次是选择抛出异常还是返回空状态的异常策略。4.3 生成代码的质量分析它到底做得怎么样重构完成后我习惯性地人工 review 了一遍代码。整体来说质量超出预期几个关键点状态枚举命名规范符合我技能文件里定的 UpperCamelCase 规则流转配置用了不可变 Map且每次访问做了防御性拷贝避免被外部修改异常信息里带了当前状态和动作参数方便排障单元测试覆盖了所有合法流转和两条例外路径。其中最让我满意的是它自检时发现了两个遗漏场景一个是CREATED状态直接退款的测试用例没有覆盖另一个是Collections.unmodifiableMap包装的流转表在并发环境下读取没问题但在生成时用了可变的 HashMap 做中间构建严格来说应该用Map.of之类的不可变构造。这些问题它都主动标注出来了我只需要确认修复方案即可。实际经验是superpowers 并不能保证生成代码零缺陷但它能帮你减少低级错误和常识性遗漏把 review 的精力集中在真正的业务逻辑上。5. 与 worbuddy 配合干活任务编排里的引导、反馈与冷却单独用 superpowers 已经很顺手了但如果你接触过 worbuddy 这个工具就会发现它们是天然的一对。worbuddy 在我理解里是一个任务协同/编排层——它主要负责管理多个 AI 任务之间的关系包括任务的依赖、排队、反馈收集、计划调整。我曾在一个多模块功能开发中尝试把两者串起来效果比单独用任何一个都好。5.1 worbuddy 的角色定位它和 superpowers 的分工简单来说superpowers 管的是单个任务做得好不好worbuddy 管的是一堆任务怎么排布、彼此怎么衔接。前者给 AI 提供能力和方法论后者负责任务的调度和组织。我用一个生活中的类比来理解superpowers 是给厨师的一本菜谱和烹饪技巧手册worbuddy 则是后厨的中控台负责管理出菜顺序、协调锅灶使用、处理顾客催单。没有菜谱厨师每个菜的口味不稳定没有中控台厨房再好的菜谱也会因为出菜次序混乱而崩溃。在这个组合里worbuddy 还能做一件事当某个任务的产出不符合预期时它会记录反馈并触发冷却机制让 AI 先停下来反思而不是继续往错误的方向推进。这就像敏捷里的迭代回顾——每轮结束先总结再做下一轮。5.2 配合工作流的典型模式在我项目里的一次完整配合我手头一个项目需要同时完成后端接口改造、前端联调辅助、数据库迁移脚本三个任务。这三个任务存在依赖关系数据库迁移要先行接口改造依赖新表结构前端联调依赖接口改造完成。如果一股脑丢给 Codex它很可能按顺序硬推前面任务未完成就推进后续任务导致返工。用 worbuddy 编排后的执行顺序是阶段一数据库迁移脚本生成并自动校验 SQL 语法阶段二后端接口改造根据迁移后的表结构调整 Mapper 层代码阶段三生成接口文档更新说明供前端联调参考阶段四集中执行一轮自检覆盖三个任务的交叉影响点。每个阶段之间有明确的完成定义只有当前阶段通过自检才会触发下一个阶段。这就避免了我最怕的前端代码和后端接口对不上的问题。这套配合方式如果只用 superpowers也能做但需要我手动在对话里不断补充现在做第二个任务记得刚才第一个任务的结论。有了 worbuddy 这一层任务边界和依赖关系是结构化管理的AI 不需要每次都靠上下文里的零散信息来判断现在该干嘛。两者结合的最大收益是从一个对话流里的单线程执行升级成了多条任务线的有向并行。注意worbuddy 这类工具每个版本的能力边界略有差异但配合逻辑是通用的——任务拆分、依赖编排、反馈收集、冷却反思这四件事只要做扎实了工具叫什么名字其实不太重要。6. 实测经验与避坑清单这些坑我替你踩过了最后这部分写给所有打算深入使用 superpowers 或类似技能系统的读者。项目本身设计得不错但设计得不错和用得顺手之间还有一段距离这段距离基本是靠踩坑填平的。6.1 上下文窗口的隐性杀手技能文件不是越多越好第一个坑也是最隐蔽的一个技能文件本身也会占用上下文窗口。你以为加载的技能文件是在后台给 AI 参考实际上它会进入 AI 的上下文计算范围。每个技能文件几十行还好如果你的技能库里有几十个技能文件每次对话 AI 都要把这些内容都读一遍上下文空间被大量蚕食对话轮数一长早期重要的信息就更容易被挤掉。我的教训是全局加载了十几个技能文件涉及 Java、SQL、前端、Shell 脚本等各类规范结果有一次 Codex 在项目里对要不要加载某个技能的选择变得很奇怪该用的没用上不该用的反而出现了。后来我改成每个项目只保留 3 - 5 个真正相关的技能文件效果明显改善。这个问题的解决方案不是多定义技能而是定义少量但精准的技能并且按项目维度隔离。6.2 技能文件过度膨胀写得越细越好是个错觉第二个坑和第一条相反很多人包括我一开始容易把技能文件写成百科全书每条规则恨不得细化到每一个标点符号。比如我在 Java 技能文件里写了六十多条规范覆盖到接口命名必须以 I 开头DTO 必须有 swagger 注解service 层必须捕获所有异常并包装等等。用过一段时间之后发现过度精细的规范反而限制了 AI 的灵活性。有些规则在特定场景下是合理的换个场景就成了过度设计。比如DTO 必须有 swagger 注解这个规范在处理内部模块间的方法调用时就不适用AI 会机械地给内部 DTO 也强加注解产生一堆无意义的代码噪音。我的改进方式是技能文件分两个层次——核心规范项目级严格遵循和场景约定任务级按需加载。核心规范控制在一页以内场景约定单独拆成文件只在对应任务类型下才被加载。这个调整之后AI 的产出质量和灵活性反而都提升了。6.3 版本兼容与降级策略升级前务必先看变更日志第三个坑关于版本升级。superpowers 迭代速度不算慢每隔几周就会有新版本。有一次我直接拉取了最新代码发现技能文件的目录结构和命名规则改了AI 加载技能的方式也跟着变了。结果是我的几个定制技能文件因为格式不兼容在升级后的一段时间里根本没生效我一度以为 Codex 出了问题。排查的过程其实不难但刚开始容易走弯路。我先检查配置路径发现目录结构变了再看技能文件格式发现新旧版对技能头部的元信息字段定义不同最后对照文档重新调整了文件格式才恢复。这个过程中最有用的一招是每次升级前先把当前技能文件目录备份一份然后只保留一个最小测试技能文件验证新版能正常加载再逐步把其他技能文件迁过去。这样出了问题你知道一定是某个文件格式的问题而不是整体配置的问题。6.4 一个关于使用心态的提醒最后想多说一句。AI 编码工具的能力边界一直在扩展superpowers 这类项目也确实让 AI 变得更懂事了但它毕竟不是万能钥匙。我见过一些人期望装完 superpowers 之后AI 就能自动把整个项目重构好、什么都不用管——这种期待注定会落空。在我实际使用中它更像一个放大器你本身对项目的理解越清晰它放大的效果越明显你对需求一团模糊它再多次任务规划也规划不出对的东西。所以工具要学项目本身的企业逻辑、架构约束、代码风格也要花心思维护。把这些基本功打牢了再让 superpowers 给你 100 倍速往前走才是这个项目真正想给你的超能力。