我第一次听到superpowers这个词是在同事的终端里。他给 Codex CLI 配了一套东西AI 跑起来的节奏完全不一样先问清楚需求再拆任务写完代码先跑测试再提交全程像有个资深工程师在带新人。后来才知道他装的就是社区里那套叫 superpowers 的技能包。它既不是新模型也不是什么 IDE 插件而是一组用 Markdown 写成的 Agent 工作流规则专门解决 AI 编码助手什么都会一点、但干活不靠谱的老大难问题。这篇文章我会把它是什么、为什么需要、怎么安装、核心技能怎么拆、Java 项目里怎么落地以及我踩过的坑一次性讲清楚。适合两类人看一是已经在用 AI 编码工具但觉得生成代码质量不稳定、经常改坏项目的工程师二是想给自己团队建立一套标准化 AI 开发流程的技术管理者。1. superpowers的真实身份它不是模型也不是插件而是一套技能文档集1.1 它不是什么先破除三个误解很多人第一次看到 superpowers 这个名字会先入为主地觉得它是一个更聪明的 AI或者开箱即用的编码 Agent。我刚开始也这么想结果翻了源码才发现这个仓库里没有一行模型代码也没有一个可执行文件。它甚至没有一个传统意义上的安装程序。它只是几十个 Markdown 文件按使用场景分门别类地放在目录里。每个文件都描述了一个完整的工作流这个技能在什么场景下用、执行分几步、每一步应该产出什么、验收标准是什么、输出格式长什么样。打个比方如果你把一个刚入职的工程师当成 AI 模型那 superpowers 就是公司发给他的那本厚厚的 SOP 手册。第二个误解是装了 superpowers 就等于给 AI 装上了自动驾驶。实际完全不是。它不会改变模型本身的智力水平也不会让模型突然会写你没见过的框架。它改变的是模型在干活时的行为方式——从抓起键盘就写变成先问需求、先看代码、先写测试、小步确认。同一个模型有流程和没流程最终产出的代码质量能差出一大截。第三个误解是superpowers 只能配 Codex CLI 用。我实际用下来它的核心思路完全可以迁移到其他 AI 编码工具上。社区里也有人把它适配到其他终端工具。只不过 Codex CLI 和 AGENTS.md 这套加载机制是它最早跑通的主场所以市面上大部分教程都以 Codex 为例我的这篇也一样。1.2 它是什么一份可以复制到任意项目的技能库把项目仓库克隆下来你会看到类似这样的目录结构不同版本略有差异superpowers/ skills/ brainstorming/ SKILL.md reading_code/ SKILL.md incremental_change/ SKILL.md test_driven_development/ SKILL.md writing_plans/ SKILL.md ... AGENTS.md README.md每个技能目录里都有一个 SKILL.md这是核心。里面写的是给模型看的详细指令包括技能的目标和适用范围触发条件什么情况下模型应该调用这个技能分步执行流程第 1 步做什么、第 2 步做什么每一步的产出物要求完成标准模型怎么知道自己做完了常见错误和反面示例安装过程说白了就两件事把这些技能目录复制到 Codex CLI 能读到的位置然后在项目的 AGENTS.md 里声明这个项目要遵循哪些技能。之后你在会话里说按 TDD 流程给这个模块加测试模型就会自动去读对应技能文件照着里面的步骤执行。这种设计最妙的地方是技能和项目代码是完全解耦的。你换一个项目不需要重新写技能你升级模型版本技能文件也基本不用动。它沉淀的是做事的流程而不是某个具体项目的具体写法。1.3 为什么社区愿意叫它超能力作者命名superpowers我理解有两层意思。第一层模型本身的能力已经足够强就像一个人体素质很好、但从来没受过专业训练的新人。你让他直接上项目他全凭本能发挥时好时坏。而 superpowers 这组技能相当于是把资深工程师的职业习惯打包封装改代码前先读上下文写完功能先补测试大任务先拆小任务每次修改都能独立验证。这些习惯单看都很朴素组合在一起就是 AI 从会写代码进化成会做工程的那层 buff。第二层这套东西是开放的、可扩展的。你不需要全盘接受作者给的技能完全可以按自己团队的工作方式新增一个技能文件比如数据库迁移技能、前端组件验收技能、运维变更技能。它本质上是一套给 AI 写操作手册的框架框架本身就在教你怎么用框架。这个特性让它和普通的 prompt 工程模板一条写死的提示词拉开了差距。2. 为什么需要superpowersAI编码助手的三个翻车现场2.1 现象一改一个 bug引入三个新 bug这是我用 AI 编码工具最痛的经历。模型定位到了问题代码改了一行测试确实过了结果另一个功能挂了。原因不是模型蠢而是它只看到了你丢给它的那一段孤立的代码没有主动去查这个函数被谁调用、依赖了哪些状态、返回值在哪里被消费。没有流程约束的模型默认行为是最小努力满足 prompt。你说修复这个 bug它就会真的只去修复这个 bug——不去确认影响范围不去跑全量测试不考虑回归。superpowers 里的 incremental_change 技能就是为了治这个病。它要求模型在执行任何修改前先回答当前这段代码的上下游是谁本次改动的边界在哪里有哪些代码绝对不要碰改完之后怎么验证没有破坏其他行为这些步骤不是技术难点而是工程意识。代码能力靠模型工程意识靠技能文档。2.2 现象二AI 只写代码不写测试很多人在评测 AI 编码工具时会惊叹它生成功能的速度真快。但如果你细看它交付的东西十次里有八次是没有测试的。你要求它补测试它又会把测试写得流于形式——断言也跟着实现写变成假绿。问题出在哪模型的目标函数是生成一段符合自然语言描述的代码而不是交付一个经过验证的变更。你不告诉它没有测试就不能算完成它就不会把测试当成必要步骤。superpowers 里的 test_driven_development 技能本质是把开发顺序反过来先写一个会失败的测试跑一次确认它是红的然后才写实现代码让它变绿。这一套流程强制模型在没有测试的情况下不能宣称完成从机制上堵住了只写代码不写测试的毛病。后面我会用 Java 例子完整演示这条流程。2.3 现象三需求还没对齐代码已经开写这是最容易忽略、也最致命的一个翻车现场。你给 AI 一句话需求给用户模块加一个按邮箱查询的接口。它唰唰唰就给你生成好了但接口的参数、异常处理、返回结构、是否分页全是你没提过的。你拿回来一看和现有代码风格不搭还要自己大改。模型太听话了你给什么 prompt 它就执行什么甚至不会反问一句你确认要这样吗。superpowers 的 brainstorming 技能需求澄清会在模型动手写代码前强制插入一个环节列出它理解的需求、提出关键问题、给出可能的实现方案及权衡、等用户确认后再进入开发。一开始你会觉得这步骤很啰嗦但多试几次就知道它在帮你避免最贵的那一类返工——方向错了的返工。2.4 把经验规则化才是真正的杠杆上面说的情况我相信每个重度使用 AI 编程工具的人都遇到过。有人靠每次多写几句 prompt 来约束它这有用但不可复制。你今天写了一条很好的约束明天换台机器、换个同事就丢了。supepowers 的价值是把这些临时 prompt 固化成项目里可版本管理、可团队共享的资产。你在 AGENTS.md 里写所有功能开发必须先补测试再实现团队里每个人用 AI 干活时都会遵守这条规则。你在技能库里加一个数据库变更必须生成回滚脚本以后所有涉及数据库的改动都会自动带上回滚方案。这就是流程规则的杠杆效应一次沉淀处处复用。3. 手把手安装superpowers从零到跑通的最小配置3.1 前置环境准备在装 superpowers 之前你得先有一个能正常工作的 Codex CLI。注意我默认你已经完成 Codex CLI 的安装和账号认证这里不展开讲。建议版本是 Node.js 18 以上Git 当然也要有。Java 项目的同学后面章节会用到 JDK 和 Maven/Gradle到那一步再装也不迟。安装前可以用一条命令快速确认环境codex --version node --version git --version三条都能输出版本号说明环境没问题。如果你之前用过 Codex 但没有配置任何项目级的 AGENTS.md也不影响superpowers 的安装是独立动作。3.2 下载并安装技能包整个安装过程核心就是把技能文件放到 Codex 能读取的位置。# 1. 克隆 superpowers 仓库到本地 git clone https://github.com/obra/superpowers.git ~/superpowers # 2. 创建 Codex 的技能目录如果不存在 mkdir -p ~/.codex/skills # 3. 把仓库里的全部技能复制过去 cp -r ~/superpowers/skills/* ~/.codex/skills/ # 4. 验证目录结构 ls ~/.codex/skills/执行完第四步你应该能看到 brainstorming、reading_code、incremental_change、test_driven_development 等一堆目录。这一步就完成了全局安装。它的含义是这台机器上的所有 Codex 项目都能通过 AGENTS.md 来引用这些技能。3.3 项目级配置用 AGENTS.md 声明规则技能装好了不等于 AI 会自动用。你需要在你当前的项目根目录下创建一个 AGENTS.md 文件没有就新建告诉 Codex本项目遵守哪些技能规则。我的建议是刚开始别贪多先声明最核心的两三条后面用熟了再逐步加。下面是一个最小可用的 AGENTS.md# 项目级 AI 指令 ## 开发流程 - 所有功能实现必须遵循 test_driven_development 技能。 - 所有代码修改必须遵循 incremental_change 技能。 - 在动手修改前先阅读相关代码并输出影响范围分析。 ## 上下文检查 - 如果信息不足使用 brainstorming 技能向用户确认需求。 - 修改 Java 代码后必须运行 mvn test 验证不能只靠编译通过。把这些写进 AGENTS.md 后Codex CLI 在每次会话开始时都会读取模型等于一开场就被注入了这些岗位要求。3.4 验证安装是否真的生效装完不能直接信要验证。我推荐用一个很小的测试问题随便找一个现有的简单函数让 AI用 TDD 流程为这个函数补充测试。如果你观察到它先写了一个测试文件、然后跑了一次测试这一步通常会报失败、接着才实现功能代码、最后再跑一遍测试确认通过那就说明技能加载成功了。如果它直接开始写实现代码甚至反问什么是 TDD说明技能没被读进去回到上一步检查文档加载路径或 AGENTS.md 的拼写。这里有个小坑AGENTS.md 必须在项目根目录放在子目录里是不生效的。4. 五个核心技能逐个拆解superpowers到底加了哪些buff4.1 需求澄清让 AI 学会先问再做brainstorming 技能解决的是需求没对齐就开干的问题。它的执行流程不是让模型直接给方案而是先做三件事用自己的话复述一遍对需求的理解列出需求中模糊的点向用户提具体问题给出候选方案并对比每个方案的优劣势举个例子用户说优化用户列表接口性能。没有这个技能时模型可能会直接优化一条 SQL。有了这个技能它先会问这个接口现在平均耗时多少预期的耗时目标是什么是数据库查询慢还是序列化慢有没有现成的监控数据甚至还会提醒优化方案要不要考虑缓存一致性的问题。这套流程和你让一位高级工程师去做性能优化之前会先做沟通是完全一致的。我比较意外的收获是这个技能生成的候选方案对比经常能帮你发现一些没考虑过的选项。因为模型读过大量类似场景的解法它把这些候选列出来的时候等于给你做了一次低成本的技术调研。4.2 代码阅读先读懂再动手reading_code 技能是我接手老项目时候的救命稻草。它的核心流程是先定位代码入口沿着调用链往外走梳理核心的数据流转最后读完相关的测试来验证自己的理解。技能文件里会要求模型在执行修改前输出一份代码阅读报告包括这个模块的入口函数是哪个、主要分支逻辑有哪些、现有的测试覆盖了哪些场景、当前实现里有哪些可疑或矛盾的地方。在 Java 项目里这一步通常伴随着在对话里直接贴上关键类的方法签名和调用关系。我有一次让它改一个遗留的支付模块按照这个技能它先读完整个调用链发现那个看似 bug 的金额除以 100其实是因为入参单位是分根本不用改。如果没有 reading_code 这个前置步骤它大概率会修掉这个bug然后引发资损级的事故。这也是为什么我现在只要改动老代码都会明确要求 AI 先执行阅读技能。4.3 增量修改把改动锁在最小的笼子里incremental_change 技能管的是所有代码修改动作。它给模型定了几条铁律明确改动范围列出会受影响的所有文件和函数主动列出本次绝对不动的部分尽可能做最小修改不做无关重构每完成一个可独立验证的小步骤就停下来确认结果这个技能在重构时格外有用。模型天生有顺手重构的癖好你让它改个变量名它可能把整个类的格式化都给你动了diff 里塞满了无关变更review 的人想骂人。incremental_change 会在改动开始前让模型自己写下边界声明本次改动只涉及 UserService 的 findUserByEmail 方法不涉及 UserRepository 的接口签名变更不调整任何其他方法的格式化。这么一写它后面就不太会越界。4.4 TDD 工作流先看到失败才允许成功test_driven_development 是 superpowers 全套技能里含金量最高的一个也是我建议所有人第一个启用的技能。它的流程严格遵循红-绿-重构循环红先写一个测试描述期望行为运行它确认测试是失败的绿写最少的实现代码让测试通过运行它确认测试是绿的重构在不改变行为的前提下优化代码再运行测试确认仍然绿技能文档里会特别强调不要试图一次性写出完整实现不要跳过红这个阶段直接写实现每次循环只专注于一个行为。举个类比这就好比你修水管第一步应该是先打开水龙头看哪里漏红而不是直接拿胶带把整根管子缠上。先确认见到预期的失败你才知道你的测试真的在守护这段逻辑。这个流程最大的好处是防止假绿——那种因为断言写得宽松、或者测试根本没被执行而出现伪通过。技能会要求模型必须展示测试命令的实际输出而不是只说测试通过了。4.5 任务分解大目标拆成可验收的小任务writing_plans 技能本质上是给 AI 加了一层项目管理能力。面对一个大型功能时它不会一口气全实现而是先输出一份任务清单每个任务包含目标描述、涉及的文件、实现步骤、验证方式、完成定义DoD。以 Java 项目为例一个新增文章发布接口的需求会被拆成这样的计划任务涉及文件验证方式新增 DTO 和校验注解dto/ArticlePublishRequest.java编译通过Service 层实现发布逻辑ArticleServiceImpl.java单元测试Repository 层新增查询方法ArticleRepository.java单元测试Controller 暴露接口ArticleController.java集成测试补充异常处理和错误码GlobalExceptionHandler.java测试覆盖每个任务完成后模型都要停下来让用户验收而不是一口气做完十个任务。这个习惯在长期项目里特别重要你不需要在 review 时面对一个几百行的大 diff而是分批次、小步提交每一批都可控、可回滚、可审查。5. Java项目实战用superpowers改造一个Spring Boot模块5.1 为什么 Java 项目特别适合这套工作流装好 superpowers 后很多人的第一个疑问是它到底适不适合 Java我的回答是Java 可能是最适合的工作流。原因有三。第一Java 有标准化构建工具Maven/Gradle验证这个动作可以被脚本化。TDD 技能需要模型反复跑测试在 Java 里就是一条mvn test的事反馈既快又明确。换到某些脚本语言项目测试框架选择五花八门技能反而要花更多精力去适配。第二Java 的类型系统和接口契约比较严格。改动一个方法签名编译器会立刻报错这给增量修改技能的小步验证提供了天然保障。模型可以在不运行测试的情况下先靠编译错误发现自己改漏了哪里。第三Java 项目的静态结构清晰Service、Repository、Controller 分层约定明确。reading_code 技能在探索这种结构时效率很高模型很容易通过类名和方法签名推断职责边界。5.2 实战案例给用户模块加一个按邮箱查询接口我还是用 Spring Boot Maven 项目一步步演示这样最有参照性。假设现有项目里有 UserService、UserRepository 和 UserController我们要新增一个接口按邮箱查询用户不存在时返回 null。第一步先用 brainstorming 技能对齐需求。我在 Codex 会话里输入请用 brainstorming 技能协助我规划按邮箱查询用户接口的开发。模型会反问几个问题返回类型应该是什么邮箱不存在时是返回 null 还是抛异常需不需要同时查逻辑删除的用户这几个问题问完需求边界就清晰了。第二步执行 reading_code 技能。让模型先读 UserService、UserRepository、UserController 和已有的测试输出影响范围分析。它会发现 UserRepository 目前只有 findById 和 findByUsername 两个方法需要在 Repository 层新增一个方法。第三步进入 TDD 循环。先写失败测试在 UserServiceTest 里新增Test void shouldFindUserByEmail() { User user userService.findByEmail(aliceexample.com); assertNotNull(user); assertEquals(aliceexample.com, user.getEmail()); }然后跑mvn test确认这个测试是红的编译失败也是红的一种表现形式。模型会很诚实地把失败日志贴出来告诉你当前还没有 findByEmail 方法。第四步写最小实现。在 UserRepository 里加OptionalUser findByEmail(String email);在 UserServiceImpl 里加Override public User findByEmail(String email) { return userRepository.findByEmail(email).orElse(null); }再跑mvn test全绿。这时候模型没有急着提交而是执行重构检查方法命名是否一致、是否需要加Transactional(readOnly true)、返回 null 是否需要标注Nullable。第五步跑全量回归。mvn test全部通过后我让模型生成一份简要的变更说明列出改动文件、测试结果、影响范围。这一整套下来一个简单的接口开发模型全程保持着清晰的节奏先问、再读、红、绿、重构、回归。5.3 实际效果什么变了什么没变这套流程跑完后最直观的感受是代码质量和以前一把梭式的生成有明显区别。测试是真的在保护行为而不是凑数改动范围非常收敛review 起来很轻松模型的每一步都有中间产物随时可以对账。但也要泼盆冷水superpowers 不会让模型突然写出架构精美的代码。它管住的是流程不是品味。比如领域建模的合理性、事务边界的划分这些还是需要你作为工程师在关键节点上把关。技能文档能保证 AI 不闯红灯、不逆行但自动驾驶的路线规划仍然需要你握方向盘。6. 常见问题与排查实录技能不生效、跳步、上下文爆炸6.1 技能文件没生效AI 完全不按流程走这是我被问得最多的问题。排查思路按顺序来先确认安装位置。Codex CLI 读取技能的标准路径是~/.codex/skills/不要把技能目录放到别的位置。我在 Windows 上遇到过路径分隔符问题Git Bash 里复制出来的目录结构正常到 PowerShell 里就加载不出来最后发现是符号链接没被正确解析。再确认 AGENTS.md 的写法。Codex 只会读取项目根目录下的 AGENTS.md文件名必须一模一样大小写也不能错。还有一个很容易忽略的点Codex CLI 是在会话初始化时读取项目指令的。如果你在会话进行中修改了 AGENTS.md当前会话不会自动生效需要重启会话。6.2 模型跳步明明说了 TDD 还是直接写实现这个问题我踩过很多次。原因通常是prompt 里说了按 TDD 来但 AGENTS.md 里的规则不够强模型把它当成建议而不是强制。模型本质上是概率生成跳步是常态。我的解决办法是在 AGENTS.md 里把规则写得非常绝对- 禁止在写完失败的测试之前编写任何实现代码。 - 任何实现代码必须伴随对应的测试否则视为未完成任务。另外在会话 prompt 里也要指名道姓严格按照 test_driven_development 技能执行第一步先写测试并运行。技能文档给的是流程AGENTS.md 给的是强制力两者配合才稳。6.3 上下文太长模型开始恍惚skill 文档全部加载之后AGENTS.md 可能膨胀到几千行会话里又贴了大量代码模型的表现会明显变差开始遗忘早期约定、把 A 技能的规则混到 B 技能里。上下文就像人的短期记忆塞太满必然溢。我现在的做法是不把所有技能文件都放进全局目录只放当前团队最常用的三四个按项目单独维护 AGENTS.md每个技能文件本身控制在 200 行以内描述精简到场景 步骤 验收标准避免把长篇大论的示例代码都堆进去。6.4 团队如何沉淀自己的专属技能superpowers 真正的长期价值在于团队可以定制自己的技能。给你一个我验证过的模板照着写基本不会错场景描述这个技能解决什么问题什么条件下触发执行步骤序号 每个步骤的具体动作和产出物验收标准怎么判断这个技能被正确执行了负面示例模型最容易出现的错误行为明确写不要做写好后放在团队统一维护的 Git 仓库里通过脚本部署到每个人的~/.codex/skills/。技能和代码一样需要 review、迭代千万别让某个人的 local 版本成为事实标准。6.5 常见问题速查表问题可能原因解决建议AI 不读技能文件安装路径错误 / AGENTS.md 缺失检查~/.codex/skills/和项目根目录 AGENTS.md模型跳步规则写得太委婉使用禁止必须等强制措辞上下文爆炸技能文件过多 / 文档过长精简技能数量控制文档长度测试假绿断言写得太松让模型运行并贴出测试命令输出改动越界没有执行 incremental_change要求模型先输出改动范围和不动范围新旧技能冲突技能文件版本过期定期从上游仓库更新技能写在最后的一点个人体会我在实际项目里用 superpowers 大半年最大的体会是它真正改变的不是 AI而是我对 AI 的使用方式。以前我把 AI 当成一个超级加速器期望它一次生成一大段能跑的代码现在我把 AI 当成一个需要按流程办事的组员每次交互都会确认流程、确认边界、确认验收标准。看起来变慢了实际上返工少了总体速度反而更快。最后分享一个用的时候才发现的小技巧不要一上来就把仓库里所有技能全部启用先从 test_driven_development 和 incremental_change 这两个开始跑跑顺了再引入 brainstorming 和 writing_plans。技能是给模型加的约束也是给会话占用的成本。精简到真正有效的两三个效果远比全家桶式堆配置来得稳。