最近技术社区的热搜里“superpowers”出现的频率相当高。点进讨论帖一看有人把它说得神乎其神好像装上以后 AI 编码助手就真能“觉醒”但也有人装完以后毫无体感跑来问是不是自己姿势不对。两种声音我都理解因为这玩意儿压根不是传统意义上的独立软件而是一套通过技能文本改变 AI 工作方式的配置资产。我花了一个周末把社区里流行的 codex superpowers 方案完整跑了一遍又用自己手头的 Java 工程做了几组对比实测结论比较直接它确实能把 Codex CLI 这类工具从“写代码很快”变成“做事靠谱”但前提是你得先搞懂它怎么工作、在什么环节被触发而不是把技能包往目录里一丢就指望它自动发力。这篇文章就把我从安装、配置、运行机制到 Java 项目实战踩坑的完整经过写下来给正在观望的人一份可以照着操作的参考。1. superpowers 究竟解决的是谁的痛点1.1 AI 编码助手为什么“看着厉害、上手毛糙”先说一个不少人都有的体感Codex CLI、Cline、Aider 这类工具单看生成代码的能力确实比两年前强了太多。让它写一个“读取 Excel 并解析为对象列表”的函数它三秒钟给你一个可运行版本让它补单元测试它也能把边界条件列得头头是道。但一旦任务变成“给整个模块加一个导出接口还要考虑多模块依赖”问题就来了。典型的翻车模式是这样你刚说完需求它立刻动手写代码既不确认业务边界也不问已有接口风格甚至不在乎项目里现有的异常处理规范。代码是能跑但风格和团队其他代码完全不搭review 时还得返工。更深一层的毛病是它没有“过程记忆”——这次对话里你纠正过它不要用 Lombok下次它写 Service 层时又给你加上了。说白了AI 编码助手不缺代码生成能力缺的是工作方法先做什么、后做什么、哪些事情必须问、哪些事情要主动查。1.2 superpowers 的本质给 AI 补齐行为规范superpowers 的核心思路其实非常朴素把开发者日常工作里默认遵守的“规矩”变成一份份 Markdown 文本在每次对话开始时塞给 AI 模型。这些文本不是代码也不依赖某个特定模型而是一种“技能注入”。比如其中最常见的技能会告诉模型拿到需求后先拆任务、识别含糊点、向用户提问确认清楚以后再进入实现阶段实现过程中遇到可能影响面较大的改动要主动说明风险和替代方案。听起来很简单对吧但真正用过以后你会发现这套东西和普通的一两句 system prompt 有本质区别。普通 prompt 是“你要做一个负责任的工程师”属于道德呼吁模型听过就忘superpowers 的技能文件则更像“操作手册”每条指令都对应具体动作有的还带了推荐的命令行工具和输出格式。模型读到的是“用户提出需求后你应该输出包含以下三个部分的计划”而不是“你最好先做个计划”。另外这套方案对模型的选择也没有强绑定。社区里大部分人在 Codex CLI 上跑因为 Codex 对 AGENTS.md 和技能目录的加载机制比较完善但同一套技能文本放到支持自定义指令的工具里也能用。所以我在文章里聊到的很多细节你完全可以迁移到其他 AI 编程工具上。1.3 这套东西适合哪些项目、哪些人从我自己的实践看superpowers 最值得投入的场景是那种“任务链路长、上下文多、涉及既有约束”的工程类开发。比如把一堆散落的 Java Service 方法重构成符合分层架构的样子或者在一个 Maven 多模块工程里新增一个对外查询接口。任务越复杂AI 越需要一套稳定的行事准则技能注入的收益就越明显。反过来如果只是拿 AI 写一些一次性脚本、LeetCode 题解或简单 CRUD Demo那这套东西带来的更多是负 面体验——它会让你反复确认需求、输出冗长计划反而拖慢速度。我在踩坑后把技能包裁剪成了“Java 工程项目模式”和“轻量脚本模式”两套按目录分别启用这事我放到后文详细说。2. 落地安装从零到跑通第一轮技能识别2.1 准备一个干净的环境在动手之前先把环境理顺。我自己的机器是一台 macOS 笔记本日常用 zsh Node.js 20Codex CLI 是直接用 npm 全局安装的。Windows 用户建议走 WSL否则文件路径和终端行为会有一堆不必要的问题。需要准备的东西如下Codex CLI 0.2.0 以上版本旧版本对技能文件的加载支持不完整git用来拉取技能仓库Node.js 18 以上部分技能脚本会用到一个真实的项目目录建议先拿一个非生产的小工程做试验安装 Codex CLI 本身不是难点一条命令就能搞定npm install -g openai/codex真正容易出现波折的是它第一次登录认证需要用 ChatGPT 账号做设备授权这一步在企业网络环境下偶尔会被拦截所以建议先在本机跑通codex命令确认基本对话正常再开始折腾 superpowers 的安装。我在一开始就跳过了验证步骤结果排错时很难判断是 Codex 本身的问题还是技能包的问题白白浪费了一个晚上。2.2 拉取并放置技能包Codex CLI 读取技能的目录官方文档里推荐放在~/.codex/skills/下这个路径在 Windows WSL 环境里同样适用。社区里流行的 codex superpowers 仓库通常包含大量按场景分类的 Markdown 文件结构大致是~/.codex/ skills/ superpowers/ start-here.md read-me-first.md ask-user-questions-before-code.md ...拉取过程很简单把仓库 clone 到技能目录即可mkdir -p ~/.codex/skills cd ~/.codex/skills git clone 你找到的 codex-superpowers 仓库地址 superpowers注意一个关键点仓库地址最好以项目 README 里标注的为准因为这个仓库的更新速度非常快我最初拿的是一个旧版本的 fork里面很多技能文件的 front matter 格式和当前 Codex CLI 不兼容导致加载时被静默忽略。如果拉下来以后发现技能一直不生效第一件事不是去改文件内容而是检查仓库最近一次 commit 时间和 Codex CLI 的版本适配说明。2.3 把技能挂到 Codex 的读取路径技能文件放进目录只是第一步接下来要告诉 Codex CLI 在每次对话时去加载它们。这一步不同人的做法不太一样我目前用的是在项目里维护一个AGENTS.md文件的做法# 项目行为规范 在开始任何任务前请读取 ~/.codex/skills/superpowers/ 下的技能说明。 优先遵循技能目录中定义的流程再遵循本文件中的项目特化约束。然后在~/.codex/config.toml里把model设为你习惯的模型同时确认没有关闭自动上下文采集的相关开关。项目级AGENTS.md的好处是跟着仓库走团队其他人拉下来也能看到同样的规范坏处是如果你的技能目录路径不同这段配置就失效了。2.4 第一次验证让 AI 主动提到技能装完以后怎么验证有没有生效我的办法是打开 Codex 对话输入一句非常简单的需求测试帮我重构这个 utils 类让它更符合工程规范。在没有加载技能的情况下Codex 通常会直接给出修改方案甚至直接动手改而技能生效时它的回复会明显“啰嗦”起来先请你确认项目背景、输出当前代码结构、列出重构约束甚至会主动问“你希望保留哪些外部调用方不修改”。看到这种回复结构出现基本就说明技能注入已经起作用了。这里我要特别提醒一句如果你在验证时发现回复和没装技能时一模一样大概率不是技能包没用而是安装过程出了问题。最常见的两个原因一是技能文件的扩展名不是.md或者 front matter 格式缺字段二是config.toml里启用了某种“省 token”模式把自动读取上下文关掉了。逐个排查基本都能解决。3. 运行机制拆解技能文本是怎么改变 AI 行为的3.1 一份技能文件里到底有什么很多人第一次打开技能文件会有点失望因为里面没有一行业务代码全是“描述性文本”。但这恰恰是它能跨模型、跨项目生效的原因。一个标准的技能文件大概长这样--- name: ask-user-questions-before-code description: 在开始写代码之前如果需求中存在含糊的业务规则、技术选型或影响范围问题先向用户提问并获得明确答复。 --- 当用户请求实现某个功能或修改某段代码时你必须按以下步骤操作 1. 提取需求中已知的明确信息。 2. 列出需求中缺失或含糊的关键信息。 3. 用简洁列表向用户提出针对这些缺失信息的问题。 4. 在获得用户回答之前不要开始编写代码或给出具体实现方案。最核心的部分是文件开头的front matter特别是name和description。Codex CLI 在加载技能时并不会把每个技能文件全文都塞进上下文——那是巨大的 token 浪费。它会先读取这些元信息再结合用户当前输入的消息内容判断当前场景该激活哪个技能然后把匹配的技能的正文追加到上下文中。这就是为什么很多教程反复强调“description 要写得具体要说明触发条件”因为描述写得越准确技能的被激活概率越高。3.2 Codex CLI 在每次对话时如何“读档”我用一个生活化的类比来理解整个流程你把一个新人工程师招进团队不会让他第一天就记住所有规范而是丢给他一本员工手册。他接到任务时会先翻手册里和当前任务相关的章节照着执行手册没写的他才会自由发挥。Codex CLI 对技能目录的加载逻辑本质上就是这套“翻手册”动作。具体到我用的版本每轮对话的上下文构造顺序大概是系统级行为指令、项目AGENTS.md、自动扫描到的项目文件信息、当前用户消息然后在其中插入被命中的技能正文。技能并不排在用户消息“之后”作为补充而是作为模型回复前需要优先遵守的约束。这个顺序很重要它决定了技能文本即使只占总上下文很小比例也能产生很强的影响力——因为模型在决策“下一步该输出什么”时最先看到的就是这些规则。3.3 实测拉锯不加技能与加了技能的 Java 代码生成对比为了把机制讲明白我用一个具体任务做了组对比测试。任务描述是“给用户模块写一个导出用户列表的接口支持按状态过滤并返回 CSV。”这个需求乍一看很明确但里面有大量隐藏的未知数是否需要分页导出是同步还是异步用户列表是指全部用户还是当前租户下的用户状态过滤字段的枚举值是什么 CSV 需要包含哪些列不加技能时Codex 直接生成了一段 Spring Boot Controller Service 代码用了RequestMapping、HttpServletResponse逻辑能跑但边界条件基本靠猜。加了技能后它的第一屏回复变成了问题列表导出数量上限需要设置吗超过多少条应拒绝导出CSV 列顺序和表头文案是否有既定约定接口是否需要权限校验当前项目已有权限注解用的是什么同步导出还是异步生成文件后提供下载链接这个差异非常直观。前者的代码你拿去做 code review 至少要改三处后者只花 30 秒回答了 4 个问题生成的代码一次通过的可能性就高非常多。这 20 倍的 review 成本差距就是用技能包的核心收益。4. Java 项目实战我踩过的三个坑和最终工作流4.1 坑一技能里的“通用规范”压不住项目特例把 superpowers 直接套进 Java 项目后第一个大坑很快就暴露了通用技能认为“开始前必须先提问”但真实业务场景里很多需求根本不需要问。比如一个内部管理后台的字典类型接口业务方已经给了完整接口文档你还让 AI 先问三个问题纯属浪费时间。解决办法是在技能体系里加一个“项目豁免清单”。我在AGENTS.md里明确写了一条当用户提供了清晰接口文档或需求描述中已包含字段定义时直接进入实现阶段不再重复提问。有了这一条Codex 的行为就从“无脑提问”变成了“按信息完整度决定流程”这才是工程上真正需要的自适应能力。4.2 坑二技能过多导致回复又长又慢第二个坑在我把所有技能文件全部保留的一周内出现。技能包生效后Codex 的回复质量确实上来了但回复长度也水涨船高——哪怕只是把日志级别改一下这种小任务它也要先输出一大段“分析计划”然后再动手。更麻烦的是 token 消耗长对话跑到一半就撞上上下文窗口上限来回翻车。我后来做了个统计我实际高频命中的技能只有四五个其余几十个技能文件在绝大多数场景下都不会被触发但它们的元信息依然参与了每轮的任务匹配计算拉低了模型的判断效率。于是我把技能目录做了分类整理按“前端、后端 Java、DevOps、数据脚本”分到不同子目录只在AGENTS.md里声明当前项目所需的那个子集。技能越少每次加载越干净回复也就回到了该有的长度。4.3 坑三Maven 多模块项目里的路径错乱Java 项目里最让我头疼的还不是技能本身而是 AI 对 Maven 多模块结构的理解。不加技能时Codex 经常把一个子模块的pom.xml当成整个项目的依赖总览改代码时也经常忽略模块边界在 A 模块里直接调用 B 模块的类却忘了加依赖。这个坑靠通用技能解决不了必须自己写一个“Maven 多模块定位技能”。我把它放在技能目录的java-specific.md里内容也很直接要求 AI 在改动涉及跨模块调用时先执行mvn dependency:tree查看模块依赖关系再读取目标模块的pom.xml确认该模块是否已声明相关依赖最后才允许动代码。这个过程看起来只是多了一步命令执行但对结果质量的影响是决定性的。4.4 我现在的 Java 工作流经过调整我现在在 Java 项目里用 Codex superpowers 的流程固定为四步开局让 AI 读取README.md和根目录pom.xml建立项目整体认知。让 AI 输出本轮任务影响面分析列出涉及模块和潜在依赖变更。确认需求边界或拿到明确接口文档后允许进入编码。编码完成后让 AI 自己检查mvn compile和现有测试是否通过并列出修改过的公共接口签名。这套流程把人的介入点控制在“需求确认”和“代码审查”两个环节中间的具体编码交给 AI 执行。相比不使用技能包时“AI 一股脑写完代码、我来删改”的模式返工率降低得非常明显。5. 二次开发把 superpowers 调教成你自己的提示词资产5.1 按项目类型裁剪技能组合用熟了以后我不再把它当成一个别人写好的“插件”来用而是开始系统性地裁剪和组合。每个新项目克隆下来后我会先快速创建对应的AGENTS.md里面只引入与当前技术栈相关的技能子目录并加上项目自己的约束。比如一个 Spring Boot 单体项目我的AGENTS.md就只写技能目录指向skills/java-base/额外约束包括“异常统一使用BizException包装”“实体类不加 Lombok”“Controller 层不写业务逻辑”。这些约束对模型来说比任何通用技能都有效因为它们是针对当前代码库的“原子事实”。5.2 写一个自己的技能文件当你理解了技能文件的结构为自己团队定制技能就不是难事。我后来写了一个专门处理老项目重构的技能这里分享一个简化版--- name: legacy-code-refactor description: 在重构历史遗留 Java 代码时识别潜在行为变化并在改动公共方法前提示兼容性风险。 --- 当用户请求重构已有 Java 类时 1. 先列出该类的所有 public 方法签名。 2. 标记其中被外部项目引用的方法为“高风险变更点”。 3. 重构过程中不得改变这些 public 方法的语义。 4. 完成后输出一份兼容性说明列出原有调用方可能受到的影响。这个技能的效果非常显著以前让 AI 重构 Service 层它经常把所有方法都“顺手优化”一遍导致调用方坏掉有了这个技能它的行为就收敛到“只动内部实现、保留外部契约”的安全范围。5.3 团队共享与版本管理还有一个容易被忽略的实践是版本管理。技能文件和AGENTS.md本身就是文本资产完全值得放进 Git 仓库和项目代码一起维护。我们团队现在是这么做的技能文件和项目根目录的AGENTS.md一起提交任何人对 AI 行为规范的修改都要走 PR review。这样一来AI 在项目里的工作方式就像代码规范一样受版本控制不会因为谁改了本地配置就突然导致 AI 行为前后不一致。刚开始推动这件事时有同事嫌麻烦觉得“装个提示词还要走代码审查”。但后来发现这份文件里记录的是团队辛苦试错总结出来的工程约束比大多数 README 里的内容更有长期价值值得被认真对待。5.4 我的最后几条经验如果你准备在自己项目里尝试我最后想分享的体会是不要一上来就把仓库里的所有技能全部启用。先挑三五个和你日常场景最贴近的比如“先提问后编码”“多模块依赖检查”“测试驱动”运行一周观察 AI 的行为变化再逐步微调。技能这东西不是越多越好而是越贴合你的项目越有用它以普通文本的形态存在于你的配置里你可以随时增删改查这才是它最可贵的地方。我自己现在维护的技能库已经精简到了一个非常顺手的规模每次开新项目只要把配套的AGENTS.md复制过去AI 就能快速进入高强度可用状态。这种“花几天调教省几个月返工”的体验值得每个经常和 AI 结对写代码的人亲自试一次。