最近几周我一直在折腾 Codex CLI也就是 OpenAI 那个跑在终端里的 AI 编程助手。用了一段时间后我的感受特别矛盾它确实能写代码但如果你直接丢一个大需求过去它经常给你来一套自认为很对的流程——没有拆解、没有检查、没有编译验证写出来的代码看着像模像样一跑全是低级错误。后来同事给我推荐了一个叫superpowers的开源项目说这东西能直接给 Codex 这类终端 Agent 装上一套技能系统让 AI 先想清楚再动手干完活还会自己复查。我试了两周效果非常明显。这篇文章就是把我的安装过程、核心玩法、实际改造 Java 项目的经验以及踩过的坑一次性整理出来给准备入手的你做个参考。如果你已经在用代码类 AI 助手但觉得生成代码质量不稳定每次都要反复纠正细节团队规范没法落实到 AI 产出里那这个项目值得你好好研究一下。1. superpowers 到底是什么以及它想解决的问题1.1 先说背景Codex CLI 这类工具的尴尬Codex CLI 是一个命令行编程工具它会读取你本地仓库的文件基于自然语言指令生成代码还能直接执行命令、运行测试、查看报错信息属于比较典型的AI Agent路线。它的能力上限很高但问题在于它默认没有一套稳定的工作习惯。什么叫没有工作习惯举个我实际遇到过的例子。我让它给项目里所有的 REST 接口加上统一异常处理它直接把一个工具类生成出来了代码本身没什么问题但它忘了先看看项目里现在有没有类似的类结果出现两个功能重叠的ExceptionHandler它也没跑测试就宣布任务完成等我手动编译才发现有个类名拼写错误。这不是 Codex 一家的问题而是所有 Agent 类工具的共性问题——大模型本身是自由发挥型的给它一个目标它倾向于直接跳到最终答案而不愿意做过程管理。superpowers 这个项目核心就是把**过程**这个缺失的部分补回来。1.2 superpowers 的解决思路技能包 工作流superpowers 本质上是一个开源框架它的做法非常像游戏里的技能树把 AI 编程过程中常用的能力拆成一个个独立的、可复用的Skill技能包。每个技能包都是一个包含指令、脚本、参考文档的目录当 AI 判断当前任务命中某个技能时就会加载这个技能按照里面定义的步骤去执行。举个例子社区里常见的技能包有这些方向plan-mode先做需求分析、拆任务不急着写代码test-first先写测试再写实现code-review写完代码后按检查清单逐项自审bug-hunting通过二分法、日志定位和最小复现来修问题refactoring做代码重构前先画依赖关系、定安全边界你可能会说这不就是把一些提示词整理好吗对也不对。提示词只是一段文本而 superpowers 里的技能包是一个完整的目录结构可以包含可执行的脚本、外部参考文档、子技能依赖甚至能决定 AI 在某个阶段能调用哪些命令。它把经验从人脑里搬到了项目的文件系统里是结构化的不是靠 AI 运气发挥的。1.3 它和裸用 Codex 的本质区别我画了一个对比能直观看出两者差异维度裸用 Codex CLI使用 superpowers任务启动方式直接生成代码先按技能加载对应流程比如先规划再动手代码检查依赖 AI 自觉有专门的自检技能明确要求编译、测试、逐项过检查单团队规范落地每次重复口头要求做成技能包AI 自动遵守错误的可追溯性低AI 自己说完成了高有任务拆解记录和阶段输出上下文管理容易越聊越乱技能包引导 AI 拆阶段避免一个对话干所有事我在实际使用里感受最深的是它把 AI 从答题者变成了执行者。直接问 Codex帮我把这个模块重构成支持扩展的插件体系它可能会给一版方案然后问你行不行但在 superpowers 的流程里AI 会先加载设计技能产出方案评估、影响面分析再进入实施阶段最后还有一次自检。这个差距非常大。1.4 适合什么样的人折腾我先说清楚superpowers 不是那种开箱即用的普通软件它使用过程中需要你具备基础的命令行能力和一点结构化思维。但它也远没有想象中那么难我判断可以从这个项目里获得价值的人包括主力语言是 Java、Python、Go 这类中大型项目开发AI 写代码容易只见树木不见森林需要一定的过程控制。已经在用 Codex CLI、Claude Code 这类终端 Agent但对产出质量不满意想提升稳定性。团队里有明确编码规范、提交规范、测试要求想把这些规范固化成 AI 的行为准则。对 AI 编程有兴趣想探索提示工程之上形态的开发者superpowers 的 Skill 机制其实已经接近AI 时代的 IDE 插件生态。如果你是纯前端切图的日常或者只是想让 AI 帮你写点一次性脚本那这个项目带来的收益有限不一定值得投入时间。2. 安装与初始化从零到让 AI 第一次带技能干活2.1 环境准备我的安装环境是 macOS Node.js 20项目要求 Node.js 18 以上这个应该绝大多数人都满足。另外你需要先把 Codex CLI 装好并完成登录因为 superpowers 在初始化时会扫描你本机的 Codex 配置识别它的位置。如果你的核心工具不是 Codex而是 Claude Code 或者其他 Agent后面我也会提到怎么迁移思路但第一步还是建议按它默认支持的 Codex 来体验。在开始之前我建议先看一眼自己有没有装好基础命令行工具node -v npm -v codex --version codex login如果你已经能正常在终端里调用codex并且登录过那环境就准备好了。国内网络环境访问 OpenAI 的接口需要一些额外配置这里就不展开了重点说这个项目本身的安装。2.2 克隆与安装我安装的版本是从 GitHub 上直接 clone 下来的。具体的仓库地址不同镜像和版本会有差异建议你在 GitHub 上搜索 superpowers codex 找到官方仓库留意一下仓库的描述里是否包含 skills for coding agents 之类的关键词避免装错同名项目。安装流程是这样的# 1. 克隆仓库到本地 git clone https://github.com/你的仓库地址/superpowers.git cd superpowers # 2. 安装依赖 npm install # 3. 以非交互方式初始化生成配置文件 npm run powerup这里重点说一下powerup这一步。它会做几件事在你的用户目录下创建.codex相关的配置目录把 superpowers 默认推荐的技能包模板放进去同时生成一个用于 Codex 的AGENTS.md文件——这个文件就是告诉 AI你有哪些技能可用、遇到什么场景应该加载哪个技能的关键配置文件。如果你是第一次跑它可能还会问你要不要自动下载社区推荐的默认技能集我建议选 Yes先体验自带技能的效果后面再删减。我不太建议一开始就完全从零手写技能那样你既不知道格式也没有对比基准后面排错会很痛苦。2.3 验证安装是否成功初始化完成后你可以检查这样几个东西是否到位~/.codex/skills/目录下是否出现了多个以技能名命名的文件夹比如plan-model、code-review-o之类的。如果出现了说明技能包本体已经就位。Codex 项目目录下是否有AGENTS.md文件文件里是否列出了可用技能的名单和触发说明。在任意一个 Git 项目里运行codex然后输入一句话请加载 plan 技能帮我分析一下这个项目的模块结构——如果它输出的内容里有任务拆解阶段划分而不是直接开始写代码说明初始化成功了。我第一次初始化完成后看到~/.codex/skills下多了一堆技能目录第一反应是这不就是个放 Markdown 文件的文件夹吗。但实际用起来才发现AI 是真的会去读这些 Markdown 文件并且严格按照里面的流程执行。不要把技能目录和普通的文档目录混为一谈它的核心在于文件结构决定了 AI 的思维路径。2.4 跑通第一个带技能的示例项目为了快速验证我做了一个最小实验新建一个空目录初始化 Git然后在里面写了三行AGENTS.md# 项目技能说明 当需要新增功能时使用 plan 技能先输出任务拆解。 所有代码必须通过测试后才能标记完成。随后我打开 Codex让它用 Python 写一个 Todo List 的命令行工具支持增删改查数据保存在本地 JSON 文件。它给出的响应和裸用 Codex 时完全不同最开始它没有写代码而是先给出了实现方案包括文件结构、命令设计、数据存储方式。然后它自己把任务拆成了创建项目结构 - 实现数据层 - 实现命令层 - 编写测试 - 手动执行验证五个步骤。中间每完成一步它会打印已完成 XX下一步执行 YY。最后它真的跑了一次python -m pytest把测试结果贴了出来才宣布任务完成。这个初次体验给我留下的印象很深。因为它已经不是你问我答的交互模式而是一个有流程、有验证、有输出记录的完整执行过程。3. 核心玩法拆解Skill 技能包的结构与自定义思路3.1 一个 Skill 到底长什么样技能包本质是一个目录以我常用的code-review技能为例它的目录结构大致是这样的code-review/ ├── SKILL.md # 技能主描述文件 ├── scripts/ │ └── extract_diff.py # 可选辅助脚本 └── references/ ├── checklist.md # 审查清单 └── common_bugs.md # 常见问题参考SKILL.md是整个技能包的核心它决定了 AI 会不会加载这个技能、加载后会按什么顺序做哪些事。一个典型的SKILL.md包含两部分内容第一部分是 frontmatter 元信息负责匹配--- name: code-review description: 在代码提交前或代码合并前执行审查时使用识别潜在缺陷、安全问题和可维护性风险。 when_to_use: 当用户要求 review 代码、检查 PR、或说帮我看看这段代码有没有问题 ---第二部分是正文指令负责执行# Code Review 流程 1. 查看变更范围获取 diff 或改动文件列表。 2. 使用 references/checklist.md 中的清单逐项检查。 3. 对发现的问题按严重程度标记Critical / Warning / Suggestion。 4. 输出审查报告包含问题位置、原因说明、修改建议。 5. 禁止直接修改代码除非用户明确要求。这份文件和平时给 ChatGPT 用的提示词最大的区别在于它明确告诉 AI什么时候该用我、要怎么用、边界在哪里。我后来把团队里 Java 项目的一些常见规范也写进了references/里比如Controller 层不能直接操作 Entity日志必须带 traceId然后让 AI 按这个技能做 code review效果确实比口头要求省心很多。3.2 写一个自己的技能包Java 代码审查实战很多人看教程看到这里可能还是不知道我自己怎么写一个技能。我拿一个最适合大部分人复刻的java-code-review来演示整个过程只要十分钟。先创建目录mkdir -p ~/.codex/skills/java-code-review/references然后写SKILL.md。我的写法参考了官方模板同时增加了一些自己的细节规则。这里分享一个技巧不要把 SKILL.md 写得像长篇小说AI 的上下文窗口是有限的技能文件越简洁、越结构化越容易被完整加载。我见过有人往技能里塞了上千行的规范文档结果 AI 经常漏读后半部分效果反而大打折扣。我的SKILL.md精简版如下--- name: java-code-review description: 针对 Java 项目代码进行审查重点检查异常处理、空指针、并发安全和 MyBatis 使用规范。 when_to_use: 当用户要求对 Java 代码进行审查、找 bug、评估代码质量时使用。 --- # Java Code Review 流程 1. 获取待审查代码列表优先审查 Controller、Service、Mapper 层。 2. 逐项检查以下要点 - 异常处理是否捕获了过宽的异常是否吞掉了异常 - 空指针方法入参和查询结果是否有判空Optional 是否使用正确 - 并发安全是否有共享可变状态SimpleDateFormat 是否被多线程共用 - 资源释放IO 流、数据库连接是否正确关闭是否使用 try-with-resources 3. 参考 references/checklist.md 中的详细清单逐条对照。 4. 输出报告按影响程度排序每条包含文件名、行号、问题描述、修改建议。 5. 修改必须经过用户同意禁止自行改动代码。再在references/checklist.md里补充详细清单比如Controller 层不要直接返回 MyBatis 的 Entity避免序列化字段暴露、批量插入必须使用 batch 方式而不是 for 循环单条插入、日志必须包含租户 ID 和操作人。这些内容完全来自你们团队的编码规范每个团队都能沉淀出这么一份清单。最后在项目的AGENTS.md里加入这个技能的声明当用户提出代码审查相关需求时默认加载 java-code-review 技能。我把这套技能用了两个星期过程中最大的感受是AI 作为审查者并不是真的在理解代码质量它是在对照清单逐条找违规点。所以清单的质量直接决定了审查质量。如果你的团队规范本身很模糊建议先自己总结哪怕一开始只有十条也比没有强。3.3 技能的全局配置与项目隔离superpowers 的技能可以放在两个层级这一点很重要很多新手会在这里搞混全局级别放在~/.codex/skills/下所有项目都能用。项目级别放在当前项目的.codex/skills/下只对当前项目生效。我建议把所有通用技能放在全局把和具体业务相关的规范放在项目级。比如java-code-review这种通用技能放全局而支付模块必须走统一对账接口这种业务约束放项目里避免 A 项目的技能干扰 B 项目。还有一点需要注意全局技能太多会导致 AI 在启动时阅读大量技能描述浪费上下文。我一开始把社区里二三十个技能全部启用了结果发现 AI 经常在多个技能之间跳跃甚至出现既想用重构技能又想用审查技能最后哪个都没执行完整的情况。后来我只保留四五个高频技能其余按需动态启用混乱问题基本消失。4. 实战记录用 superpowers 驱动一次 Java 项目改造4.1 场景设定为了验证 superpowers 在真实项目里的效果我选了一个自己维护的旧 Java 项目做实验。这个项目是一个内部工具系统原来用的是比较古老的 Servlet JSP 架构最近要做一次技术改造把接口层迁移到 Spring Boot并且引入统一的异常处理和参数校验。这个需求如果丢给裸 Codex 去做我的预期是它会把web.xml里的映射删掉新建几个RestController类然后告诉我迁移完成。但它大概率不会关注旧的 filter 是否兼容、登录拦截器是否还能生效、前端调用的接口路径是否保持一致。这些都是改造里最容易出问题的地方。所以我先做了准备在项目里写了两个技能spring-boot-migration和test-first。配置大致如下# spring-boot-migration 技能要点 - 迁移过程中必须保持原有 URL 路径不变除非用户明确要求修改。 - 旧 Filter 的职责必须在新拦截器或 Spring 机制中找到对应实现。 - 每个接口迁移后必须同步调整对应的前端调用文档。 - 启动项目并使用 curl 对迁移后的接口做冒烟验证。 # test-first 技能要点 - 每个迁移动手前先基于原接口行为编写集成测试。 - 测试必须覆盖成功路径、参数校验失败路径、异常处理路径。 - 代码实现后执行 mvn test保证测试全部通过才能标记任务完成。可以看到这些内容其实不是提示词技巧而是一条条项目级的改造约束。把约束写进技能文件AI 执行时就会带着这些约束做决策。我把这些技能放在项目的.codex/skills/目录下并确保AGENTS.md里声明了它们。4.2 任务拆解AI 如何把大任务拆成子任务一切就绪后我给 Codex 输入了这样一句话使用 spring-boot-migration 和 test-first 技能完成接口层从 Servlet 到 Spring Boot 的迁移。它的处理过程让我印象很深。它并没有直接从第一个接口开始改而是先输出了一个拆解计划阶段 1摸底。扫描 web.xml、所有 Servlet 类、Filter、Listener整理接口清单。 阶段 2搭建骨架。创建 Spring Boot 入口类、基础配置类、统一返回体。 阶段 3按模块迁移。先迁移用户模块接口再迁移订单模块接口。 阶段 4补充测试。为已迁移接口补充集成测试覆盖正常、异常、参数错误场景。 阶段 5整体验证。启动项目使用 curl 验证核心路径输出迁移报告。这个拆解质量和我手写的开发计划几乎没有差别。尤其是摸底阶段它真的先去看这些 Servlet 类在项目里哪些地方被转发、被 include避免迁移后出现调用链断裂的问题。这里我要特别说一句拆解能力不是 superpowers 自带的而是它让 AI 在执行前先调用 plan 类技能强制它先输出计划再动手。大模型本身是具备拆解能力的只是默认情况下它不太会主动这么做。superpowers 最大的贡献就是靠流程设计把这个能力稳定地激发出来。4.3 执行过程中的自检与修复在迁移第一个用户接口时我盯着 AI 输出注意到它做完代码修改之后自动执行了这样几个操作mvn compile确认没有编译错误。读取原 Servlet 里的WebServlet(/user/detail)注解和web.xml里的映射确认新接口路径仍然是/user/detail。运行了已有的测试类发现一个测试的期望状态码是 500但新代码返回了 400。它分析了原逻辑后发现旧代码在参数缺失时确实抛异常返回 500而新代码因为加了校验注解提前抛MethodArgumentNotValidException所以变成 400。这是一个非常好的例子。这种情况如果没人管AI 大概率会在测试报错后反复改测试来匹配新行为而不是反过来审视代码是否符合原有 API 的语义。但因为在 skill 里写了保持 URL 和基本行为不变并且要求自测时必须检查失败原因它最终选择了保留旧行为把新增的校验注解去掉只保留对请求体基本字段的非空判断。这一步之后的测试全部通过而我的参与只是在最开始给了它一个任务描述。整个过程它从拆解、编码、编译、测试到问题归因几乎不需要人干预。我在旁边做的只是偶尔看一下执行日志防止它误删文件。4.4 改造后的收益复盘整个过程耗时大约 40 分钟迁移了四个模块的接口补充了 12 个集成测试。如果我自己手动改同样的工作量差不多需要一到两天而且大概率还会漏掉一两个前端调用路径的同步调整。对比裸用 Codex带技能使用的差异体现在几个方面明确的自测行为。不带技能时Codex 也可能会跑测试但概率不稳定带技能后只要 skill 里有必须运行测试这条它就会稳定执行。对既有语义的尊重。我总是在 skill 里写保持旧行为不变这让 AI 在遇到测试与预期不符时会优先怀疑自己的代码而不是怀疑测试这个方向的改错概率大幅降低。阶段输出的可读性好。整个改造过程像在看一个开发者的工作日志它每完成一个阶段就输出小结我可以随时叫停或调整方向而不是等它一口气写完所有代码再去 review那种模式一旦方向错了返工成本极高。当然它不是万能的。改造过程中我也遇到了一次 AI 把web.xml里一个 filter 误删的情况原因是我给的技能描述里写了旧 Filter 的职责必须在新机制中找到对应实现但并没有明确列出哪些 Filter 是核心的于是 AI 把一个日志记录 filter 判断为非必要直接删掉了。后来我在 skill 里补充了一条删除任何 Filter 前必须先向用户确认这类问题就再没出现过。5. 常见问题与排查技巧实录5.1 装完后技能不被触发AI 完全无视技能这是我被问得最多的问题。很多人配置完技能后发现 AI 依然我行我素像没看到AGENTS.md一样怎么排查我的排查路径是打开AGENTS.md检查技能描述里有没有明确的触发词。如果你的技能写的是当合适的场景出现时使用那大概率不会触发因为合适对大模型来说太模糊了我建议改成当用户提到代码审查、review、找 bug 这些关键词时使用。检查技能是否放在了正确的目录。全局技能放在~/.codex/skills/项目技能放在当前项目的.codex/skills/不要放混。如果目录没问题那就直接显式输入技能名请使用 java-code-review 技能审查这段代码。大部分情况下 AI 都能正确加载。如果显式输入都不生效那大概率是工具本身对技能目录的支持有问题可以检查版本或重新powerup初始化。5.2 技能开着但 AI 执行到一半跑偏了这种情况也挺常见。比如我让 AI 用 plan 技能先输出任务拆解它写了三行计划就直接跳进代码实现了完全没有按技能文件里的完整流程走。我的经验是技能文件里的步骤太抽象是跑偏的第一个原因。比如分析项目结构这种描述AI 理解完可能觉得看一眼目录就够了但你的本意是让它梳理清楚模块依赖关系。所以就别写分析项目结构直接写1. 列出 src/main/java 下所有包名。 2. 读取每个模块的入口类。 3. 输出模块之间的调用关系图。步骤越具体AI 越不容易自由发挥。另外一个办法是在技能正文末尾加一句如果遇到无法继续的情况停下来向用户提问不要自己假设这能有效避免 AI 在一个分支上越走越远。5.3 全局技能太多上下文被严重占用superpowers 技能体系是基于 Markdown 文件加载的理论上每个技能都会消耗上下文。如果你把社区里所有技能都塞进去Codex 每次启动都要读一遍所有技能描述还没开始写代码上下文就已经耗掉一大截实际代码生成质量会明显下降。我的做法是在~/.codex/skills/下建一个_disabled目录把不常用的技能全部移进去。需要用时再移出来或者直接用绝对路径指定。我实际保留在启用状态的技能不超过六个plantest-firstcode-reviewdebug-buggit-commit-helper其他的基本都是按项目临时启用。5.4 不是 Codex CLI 用户这个思路能迁移吗能而且我强烈建议你迁移。superpowers 最核心的资产不是代码而是那套技能包 触发条件 执行清单的组织方式。我自己就用这种方式在别的 AI 工具里也实现了类似效果。比如有些团队用的是偏向提示词管理与工作流编排的辅助工具像 Worbuddy 这类思路完全可以借鉴把 SKILL.md 的 frontmatter 当作工具里的场景配置把正文章节当作任务模板。你在工具里新建一个Java 代码审查的工作流把步骤填进去触发关键词写上审查 / review / 找 bug实际效果几乎等同于在 superpowers 里创建了一个技能。另外像 Cursor 这类编辑器里的 rules 文件本质上也是干这个的只是表达能力弱一些。但思路是通用的凡是你能给 AI 定义固定流程的地方都值得用技能包的方式去沉淀。5.5 多项目技能互相干扰怎么处理最后讲一个项目管理上的坑。我一开始把所有技能都放在全局目录结果在 A 项目写的支付模块规范技能在 B 项目做代码审查时也被加载了AI 开始用 A 项目的规范去审查 B 项目的代码输出了一堆无效建议。处理办法就是我前面说的项目级隔离。所有和业务绑定的规范类技能一律放在当前项目的.codex/skills/下绝不放进全局目录。全局目录只放与语言、框架无关的通用能力比如 code-review、git-commit-helper。这样即使你还管理着五六个项目每个项目的 AI 行为也能保持相对独立。我在实际使用中的体会是superpowers 这类技能框架真正的价值不在于它让 AI 生成了更好的代码而在于它让 AI 的工作习惯变成了可以沉淀、可以复用、可以交给团队成员的项目资产。以前带新人我得反复强调代码规范、测试要求、审查流程现在把这些写进技能包新人用 AI 干活时AI 会先把这些问题挡下来。这套东西的后续想象空间也很大比如把团队所有历史变更记录做成 references 参考文档让 AI 在做设计决策前先检索旧方案避免重复踩坑。我觉得这才是 AI 编程工具最终该有的形态——不是让它替你做决定而是把这些年踩过坑沉淀下来的判断标准原原本本地教给它。