说实话我一开始看到 superpowers 这个词以为是某个超级英雄题材的开源项目直到我在 GitHub 上翻到它才意识到这是给 AI 编码助手用的一套提示词配置集合。事情是这样的同样是打开 Codex CLI别人家的 AI 写代码像吃了兴奋剂一次生成就能跑改需求也跟得上我自己的 Codex 写出来的东西要么是教科书式样板要么爱自作主张乱改我原有逻辑。后来我把 superpowers 接进项目里才明白问题不在 Codex 本身而在于我从来没告诉它我到底要怎么干活。superpowers 这套配置最早就是面向 Codex CLI 设计的核心思路非常朴素与其在每次对话里重复强调编码规范、测试要求、提交信息格式不如把这些话写进项目根目录的 AGENTS.md 或 CLAUDE.md让 AI 每次启动都先读到一份团队新人手册。这篇文章不打算讲什么高深原理就聊聊 superpowers 是什么、怎么装、每个提示词文件到底改变了 AI 哪些行为以及我在 Java 项目里的实测体验和踩过的坑。适合正在用 Codex、Claude Code 这类工具的开发者也适合那些觉得AI 写代码总差一口气的人。1. 先搞清楚 superpowers 到底是什么1.1 它解决的问题AI 编码助手有能力但没规矩很多人对 AI 编码助手的期待是给它一个需求它就能写出符合项目规范的代码。但实际用下来你会发现模型本身的能力很强问题出在规矩上。它不知道你项目的包名规则、不知道你的测试框架是 JUnit 5 还是 TestNG、不知道提交信息该用 Conventional Commits 还是随便写、也不知道你希望每个公共方法都补 Javadoc。这些细节你可以在每次对话里手打但效率太低而且一旦换了会话就得重新说。superpowers 做的事情就是把规矩固化成提示词文件。它不是某个具体的库也不是需要引用的 SDK而是一组 Markdown 文档。Codex CLI、Claude Code 这类工具在启动时会自动读取项目里的 AGENTS.md 或 CLAUDE.md把这些文档里的内容作为上下文的一部分交给模型。模型读到这些规则之后在接下来的整个会话里就会照着执行相当于给你雇来的 AI 新人做了一次入职培训。1.2 工作机制AGENTS.md 是 AI 的入职手册如果你用过 Anthropic 的 Claude Code应该对 CLAUDE.md 不陌生OpenAI 这边的 Codex CLI 则优先读 AGENTS.md。有些工具两个都认有些只认其中一个但底层逻辑是一样的它们都是Agent 环境文件描述了这个项目里 AI 应该遵守的约定、可用的命令、架构特点和常见陷阱。superpowers 项目把这些文件组织成一套体系。以我实际拉下来的仓库为例核心文件包括总原则、代码风格、TDD、提交信息规范、CHANGELOG 生成、文档编写、调试技巧、安全清单等几个模块。你可以整体使用也可以只挑需要的模块拿进自己的项目。它的设计思路是模块化的每个文件独立成篇方便裁剪和组合而不是塞给你一大堆互相矛盾的规则。1.3 为什么这套配置敢叫 superpowers项目名字起得确实有点狂但用过之后你会发现它强调的不是让 AI 变得更强而是让 AI 的能力能被项目真正用起来。默认状态下Codex 的编码能力像一把好刀但没有磨刀石也没有使用说明superpowers 提供的提示词文件就是磨刀石和说明书。它不改变模型的参数也不调用特殊 API纯粹靠上下文引导。换个说法它不是给你加超能力而是把你本来就有的超能力从偶尔触发变成稳定触发。这一点很重要因为很多人一听到提示词工程就觉得是玄学。其实在 AI 编码助手这个场景里提示词文件的效果非常可预测AI 每次都会读到、每次都会遵守比你在对话里偶然想起要可靠得多。2. 安装与接入把 superpowers 塞给你的 Codex2.1 全局接入让所有项目都能用我最早用的是全局接入方式。Codex CLI 支持读取~/.codex/AGENTS.md这种用户级配置文件把这个文件放到用户目录下相当于给你机器上的所有 Codex 会话都装上默认的 superpowers。对于个人开发者来说这种方式最省事不用每个项目都复制一遍。具体的做法是先把仓库克隆下来git clone https://github.com/simonw/codex-superpowers cd codex-superpowers然后把里面的核心提示词文件复制到 Codex 的用户配置目录mkdir -p ~/.codex cp *.md ~/.codex/如果 Codex CLI 已经在运行需要重启会话才能生效。之后你在任何一个项目目录里打开 Codex它都会先读取这份用户级 AGENTS.md再把项目里可能存在的项目级 AGENTS.md 叠加进来。全局配置适合放通用规则比如代码风格、提交信息格式、TDD 习惯这些跟具体业务无关所有项目都适用。2.2 项目级接入按仓库隔离能力全局接入适合个人机器但如果你参与多个项目不同项目有不同的技术栈和约定全局配置就有点不够用了。比如你的 A 项目是 Java MavenB 项目是 Node TypeScript两个项目对格式、测试、构建工具的要求完全不一样。这时候项目级接入是更好的选择。把对应的提示词文件放到项目根目录比如说AGENTS.md然后只对当前仓库生效。Codex 在项目目录里启动时会按优先级读取项目根目录的 AGENTS.md 优先于全局的~/.codex/AGENTS.md子目录的 AGENTS.md 又优先于根目录。这给我们提供了很灵活的隔离粒度后面我讲 Java 定制时会细说。2.3 目录级接入只给某个模块加 buff还有一种更精细的玩法目录级接入。在一个大型 monorepo 里你没必要让整个仓库的所有 AI 会话都遵守同一套规则。比如backend/是 Javafrontend/是 TypeScript你可以在各自目录下放单独的 AGENTS.md覆盖根目录的通用规则实现模块级别的超能力分发。这个机制跟 lint 配置很像全局 ESLint 管所有文件但某个目录下可以有自己的覆盖配置。AI 编码助手的 AGENTS.md 粒度跟这个是同样的思路。我在一个多模块项目里就是这么用的效果很明显AI 在 backend 目录里能正确使用 Maven 和 JUnit 5切到 frontend 目录就知道该用 pnpm 和 Vitest不需要我来回提醒。2.4 验证是否生效的方法接入之后怎么确定真的生效了我个人的习惯是直接问 AI:你当前读到了哪些项目规则如果它列出了 superpowers 里的关键条款比如代码风格、TDD、提交信息格式说明配置生效了。如果它一脸茫然那就要检查文件路径是否正确、是不是装到了用户目录而不是项目目录、或者有没有被其他 AGENTS.md 覆盖。另一个验证技巧是故意写一个反规范的请求比如让它给一个 Java 类生成单元测试注意观察它是否自动用了 JUnit 5 的注解而不是 JUnit 4 的。规范生效时AI 会在没有要求的情况下主动遵守约定如果它还是按默认风格来说明规则没读进去。3. 核心提示词文件逐一拆解这些超能力到底改了什么3.1 总原则文件AI 的价值观设置superpowers 里最核心的不是具体技巧而是一个总原则文件相当于给 AI 设定了价值观。这份文件会告诉模型要先理解需求再动手、不要盲目生成大段代码、优先考虑简单方案、不要破坏现有功能、保持代码可读性。听起来是很虚的东西但对 AI 编码助手的实际行为影响非常大。因为 Codex 这类工具在默认状态下倾向于你让我写我就写写得多就行。你让它实现一个功能它能给你造出一堆类、接口、抽象工厂把简单问题复杂化。总原则文件的核心作用就是拉回这种倾向强迫模型在动手前先复述需求、列出可选方案、然后给出最小可行实现。我用下来的体会是这部分对代码质量的提升是最明显的AI 生成的代码从能跑变成了看得出为什么这样写。3.2 代码风格与 TDD最立竿见影的两个文件代码风格文件解决的是格式符合项目习惯问题。它会约束缩进、命名、Javadoc、常量定义、异常处理方式等。尤其对于 Java 项目风格文件里如果写了使用 Lombok 的 Slf4j 而不是手动声明 LoggerAI 就会一直遵守。这个文件是唯一不用看效果就能立刻感觉到变化的因为生成代码的观感完全不一样。TDD 文件的作用更偏向流程。它要求 AI 在面对一个新功能时先写测试、再写实现、运行测试确认通过、最后重构。如果你用的是 Codex CLI 并且配置了 bash 工具权限它甚至真的会去跑 Maven 测试失败了就自己修而不是把责任推给你。这一步是AI 结对编程和AI 生成代码的分水岭前者是完整的工作流后者只是打字机。3.3 提交信息与 CHANGELOG顺手把规范也做了这组文件看起来跟写代码关系不大但实际用的时候很加分。Conventional Commits 规范文件会告诉 AI 如何写提交信息feat:加功能、fix:修 bug、docs:改文档还规定了正文格式和关联 issue 的写法。以前我手动写提交信息总是偷懒现在 AI 改完代码之后会顺便把提交信息也生成好格式规范省了很多事。CHANGELOG 文件也很实用。它定义了如何基于 Conventional Commits 生成 changelog区分新功能、破坏性变更、修复和性能优化。放到 CI 里配合自动发布流程比手动维护 changelog 可靠得多。这里我补充一个自己的使用场景项目里如果用了 semantic-release 之类的工具这些提示词文件能确保 AI 生成的提交信息严格匹配触发条件避免发布流程卡住。3.4 调试与安全平时用不上出事能救命调试类提示词是我一开始想砍掉的因为总觉得没什么用直到有次 Codex 连续三次修不好一个空指针异常。默认状态下AI 遇到 bug 时会凭感觉改代码改完让你重新跑再失败再改效率很低。调试提示词会强制它先看堆栈、定位异常发生位置、理解数据流、然后才动手改并且每改一步就运行一次验证。安全类提示词也值得留着尤其是 Web 项目。它会让 AI 意识到 SQL 注入、XSS、权限绕过、依赖漏洞这些基础安全问题而不是只管功能实现。我不是说这套配置能让项目变安全但它至少能挡住 AI 自己制造的隐患。有一次 AI 自然生成的代码里出现了一个字符串拼接 SQL 的操作被安全文件拦住了这个功劳我是认的。4. Java 场景实战把 superpowers 调成你的结对搭档4.1 Java 项目需要的定制增量superpowers 默认配置偏通用直接用在 Java 项目里效果一般因为 Java 项目的痛点太具体了。比如构建工具选型是 Maven 还是 GradleJava 版本是 17 还是 21测试框架是 JUnit 5 还是 TestNGORM 用 MyBatis 还是 Spring Data JPA是不是强制使用 Lombok包结构按业务分层还是按技术分层。这些约定如果不在提示词里写清楚AI 就会随机发挥有时生成 Maven 风格的项目结构有时用 Gradle 的写法让人很头疼。所以我把 superpowers 当底座然后针对 Java 项目写一个追加的 AGENTS.md。做法很简单在项目根目录创建一个自己的 AGENTS.md让它保留 superpowers 中跟语言无关的部分再补充 Java 特定约束。经过几轮迭代我的 Java 定制配置基本稳定下来下面直接给参考模板。4.2 一份适合 Maven Spring Boot 的 AGENTS.md 模板以下是我实际在用的精简版配置适合 Maven Spring Boot 3 Java 17 JUnit 5 的项目。解释放在注释里方便大家按需调整# AGENTS.md - Java 项目约定 ## 技术栈 - Java 17Maven 3.9Spring Boot 3.x - Lombok 优先使用 Slf4j 声明日志RequiredArgsConstructor 注入依赖 - 测试框架JUnit 5 AssertJ Mockito ## 项目结构 - 遵循 maven-standard-layoutsrc/main/java、src/test/java - 按业务模块分包禁止在 controller 里写业务逻辑 - Service 层必须面向接口编程但只在实际需要多实现时建接口 ## 代码规范 - 每个公共方法必须写 Javadoc说明参数、返回值、异常 - 禁止 System.out.println统一使用 Lombok Slf4j - 异常处理优先使用业务异常禁止catch后吞掉 - 使用 var 仅在局部变量返回值类型必须显式声明 ## 测试要求 - 新增业务代码必须同时新增或更新单元测试 - Controller 测试用 WebMvcTestService 测试用纯 Mockito不用 Spring Context - 断言使用 AssertJ禁止使用 JUnit 4 的断言风格 ## 构建与验证 - 修改代码后必须运行mvn test - 涉及数据库变更时需要运行 mvn -DskipTests package 验证编译这段配置的关键点是具体。不要写代码要规范而要写禁止 System.out.println。AI 对模糊要求的执行力很差但只要你给出可检查的条件它就能稳定执行。模板里的每一项我都验证过尤其是 Lombok 和 JUnit 5 的约束几乎每次都能减少一些手工修改。4.3 有和没有 superpowersCodex 的表现差多少我拿一个用户注册接口做过对比。没配 superpowers 时Codex 生成的是一个 UserController、一个 UserService、一个 UserRepository、一个 User 实体代码能跑但有很多细节让人皱眉。比如使用 Spring Data JPA 时忘了给实体加EntityListeners单元测试用了SpringBootTest而不是更快的WebMvcTest日志直接用System.out.println提交信息写的是add user registration而不是 Conventional Commits 格式。配上定制后的 superpowers同样一个需求Codex 的生成结果变成了按包结构放到对应目录、Controller 里只有参数校验和调用、Service 层用RequiredArgsConstructor注入依赖、日志统一用Slf4j、测试自动写了三层Controller、Service、Repository提交信息是标准的feat: add user registration endpoint with validation。功能上两者都能用但后者几乎不需要 review 时改结构只需要关注业务逻辑本身。这不是玄学是上下文的作用。默认模型会因为缺少项目约束而采取最容易的通用方案而 superpowers 把约束提前暴露给模型它自然就避开了那些通用但不符合本项目习惯的写法。对我这种每周要 review 大量 PR 的人而言省下的时间非常可观。5. 实测三个月我踩过的坑和总结的调参经验5.1 上下文被撑爆配置不是越多越好我第一次用 superpowers 时把仓库里所有提示词文件一股脑全装上了心想超能力当然是越多越好。结果 Codex 每次会话光读取这些提示词文件就占掉大量上下文窗口可用 token 变少回答速度明显变慢而且生成的代码反而变得很规矩但很冗余每条规则都要表现出来。这里要理解一个底层机制AGENTS.md 不是无限免费空间它占的是模型的上下文配额。你塞两千行提示词进去模型在生成代码时能用的思考空间就少了两千行对应的影响。而且提示词之间有优先级冲突时模型会试图同时满足所有规则导致生成结果变得奇怪。我的建议是全局配置只保留 5-8 个核心文件项目级配置只保留本项目真正需要的规则。superpowers 的模块化设计就是为了干这个的别学我一股脑全装。每加一个文件之前问自己一个问题如果 AI 不遵守这一条会发生什么答案不够严重就删掉。5.2 规则互相打架优先级和去重superpowers 的默认规则跟项目里的自定义规则有时会冲突。比如默认规则要求所有公共方法都写 Javadoc但你的项目里 Controller 方法约定不写只写 Service 层。这种冲突会让模型困惑它可能选择两者之一也可能两者都写结果就是输出不稳定。解决办法是在项目级 AGENTS.md 里用明确覆盖的语言比如直接写覆盖总原则文件第 X 条Controller 层公共方法不需要 Javadoc。模型读到这里时会明确知道后写的规则优先就不会再摇摆了。另外不要重复描述同一条规则比如全局配置和项目配置里都写了使用 Slf4j这不仅浪费 token还可能因为语气不同导致模型执行不到位。5.3 别当一次性文件它应该进 git 维护我最初把 AGENTS.md 当成本地临时文件没有提交到 git结果配置坏了都不知道是什么时候改的也回不去上一个状态。后来痛定思痛把所有的提示词文件纳入版本管理每次调整都走 commit这样既有历史记录也能在团队里共享。AGENTS.md 本身就是项目文档的一部分和 README、CONTRIBUTING 同级。把它提交进 git 还有个额外好处新同事 clone 项目之后AI 编码助手开箱就带全套项目规范不需要他们自己去读几万行文档。我现在的习惯是把所有提示词文件放成一个docs/ai/目录然后在根目录的 AGENTS.md 里用相对路径引用既保持根目录清爽又不影响读取。5.4 团队里的额外收益新人比我先看懂了项目最后分享一个意外收获。我把定制后的 AGENTS.md 发到团队之后一个刚入职的同事说他在 IDE 里装了支持 AGENTS.md 的 AI 插件写需求时 AI 自动帮他按照项目规范生成代码他靠着这些文件快速了解了项目的技术栈、代码结构和测试套路。从一个受益者的角度看这其实就是 superpowers 真正的超能力——它把资深开发者脑子里的隐性知识显式地写给了每个人和每个人的 AI 助手。我自己后来的习惯是每完成一个中型需求就把 review 时发现的共性问题追加到 AGENTS.md 里。比如新建的 Repository 必须加Repository注解这条就是某次 AI 漏加之后我手动补上然后写进规则里的。从那时起AI 再也没漏过。这类规则积累得越多你的 AI 结对伙伴就越了解你的项目代码返工率就越低。配置这套东西的前期成本是有的但三个月用下来这点成本早就在每次生成即用的代码里赚回来了。