★ FEATURED ARTICLE 最近这两个月我几乎把 Codex CLI 当成了日常编码的半个搭档。生成单测、补文档、做小范围重构它确实能省不少事。可每次代码量一上来问题就暴露了生成的代码风格飘忽该写测试的地方不写提交信息全凭心情。我一度以为是模型能力不够直到在技术社区刷到一个叫 superpowers 的项目才意识到问题出在“工作方法”上——AI 需要一套技能包来约束它的行为而不是只靠一次性的提示词。这篇文章就围绕 superpowers 的安装、使用和我在 Java 项目里的落地过程来写适合已经在用 Codex CLI、Claude Code 这类编码智能体工具但对生成质量不满意的开发者。1. superpowers 是什么AI 编码时代的“技能包”体系1.1 我为什么觉得 AI 写代码“差口气”先交代一个背景。我在一个老旧的微服务仓库里做过一次跨模块改造当时把需求拆成十几个子任务全部交给 Codex CLI 去做。结果很有意思单个任务它完成得都很快可合到一起看代码就像三个人同时写的——有人喜欢构造函数注入有人喜欢字段注入有人给每个方法都写 JavaDoc有人一个注释都不留最要命的是涉及数据库变更的那几个任务它完全没想过先写一个可回滚的迁移脚本直接就在实体类上加字段。我当时的第一反应是模型不够聪明换了更大的模型加了更长的提示词情况有好转但不多。后来我意识到问题的本质不是模型能力而是它缺少一套稳定的“工作方法”。一个正常的资深工程师接到需求脑子里会有一套固定的流程先确认边界、再补测试、写最小实现、重构、最后按规范提交。但 Codex CLI 默认是没有这套流程的你给它一个需求它就按训练数据里“最可能的方式”直接生成代码而训练数据里充斥着大量平庸的开源代码。所以那次改造之后我开始认真找一种能“给 AI 注入方法”的方案superpowers 就在这时进入了我的视野。它的思路很直接把资深工程师的工作方法论拆成一个一个可复用的“技能包”AI 在收到任务时按需调用而不是每次都临时从提示词里猜。1.2 技能包、插件、提示词模板的区别很多读者一看到 superpowers 是干这个的马上会联想到两类东西IDE 插件和提示词模板。这确实是理解它的两个参照物但都有本质区别。先说提示词模板。提示词模板是一次性的你在某次对话里粘贴一段“请遵循 TDD 流程”AI 这次遵守了下个会话它又忘干净了。而且模板一长上下文窗口立刻紧张用户也懒得每次手敲。技能包则是一个常驻的行为约定它存在于固定的目录结构中AI 每次会话启动时都知道有这么一份“操作手册”不需要用户重复粘贴。再说插件。插件通常是在 IDE 层面扩展功能比如补全、跳转、代码生成按钮它跟语言服务器、编辑器 API 深度绑定。技能包则完全工作在对话协议的层面它不关心你在哪个编辑器里只要你用的编码智能体工具支持技能目录加载就能生效。我整理过一个粗浅的对比方便理解三者的边界类型粒度触发方式可维护性对上下文的影响一次性提示词单次任务手动复制粘贴差多处漂移每次全量占用IDE 插件功能级命令、快捷键、事件中跟随 IDE 更新基本不占用技能包方法论级会话启动时索引按需加载好可版本管理索引阶段轻量展开时按需读取用生活化的方式说提示词是“你临时教一个人这次该怎么做”插件是“你给他换了一把更顺手的工具”技能包则是“你给他签了一份工作流程规范他每次开工前先翻一翻”。1.3 superpowers 在主流编码智能体工具里扮演什么角色现在这个赛道里最活跃的两类工具一类是 Codex CLI 这样偏终端操作的一类是 Claude Code 这样偏对话协作的。它们底层能力都很强能读文件、能跑命令、能编辑代码但它们默认都缺一层“方法论”。superpowers 补的正是这层。它不是一个独立的代码生成器也不是模型而更像一个“行为准则层”。你可以理解为模型是发动机编码智能体工具是车身superpowers 是驾驶规范。没有驾驶规范发动机再猛也是瞎跑挂上规范之后AI 才知道什么时候该减速、什么时候该变道、什么时候该靠边检查。这也是为什么“codex superpowers”和“superpowers java”会同时出现在搜索热词里。它跟具体工具无关跟具体语言也无关。Codex CLI 用户可以用它规范结构化提交Java 用户可以用它规范重构流程前端用户可以用它规范组件测试策略。它的价值天花板取决于你能把多少工程经验沉淀成技能描述。2. 安装与初始化从零到第一个技能生效2.1 安装前的准备清单第一次装 superpowers 之前我建议你先确认下面几项别急着复制命令。第一Node.js 环境是必须的。Codex CLI 目前还是以 npm 包形式分发Node 版本最好在 v18 以上太老的版本会有兼容问题。你可以在终端里用node -v看一眼如果输出是 v14 这种先升级。第二Codex CLI 本身得先装好并且能正常登录使用。这个步骤不在 superpowers 的职责范围内但如果你的 Codex 还没跑通后面所有验证都无从谈起。安装方式很简单npm install -g openai/codex装上以后先随便让它干点小活确认对话、文件读写、命令执行都正常再进入下一步。第三想清楚一个观念问题。superpowers 不是模型也不是某种加密算法或者运行时环境它本质上就是一批文档、脚本和约定。理解这一点很重要因为它意味着你的投资收益完全取决于“你往里放了多少工程智慧”。装好只是开始真正让它发挥价值的是你后续对技能包的裁剪和定制。2.2 安装操作实录我以 macOS 环境为例完整跑一遍安装流程。不同系统的差异主要在于目录习惯核心逻辑是一样的。# 1. 为 superpowers 创建独立配置目录避免污染用户主目录 mkdir -p ~/.config/superpowers # 2. 把项目仓库克隆到该目录具体地址以官方 README 为准 git clone 官方仓库地址 ~/.config/superpowers # 3. 检查技能目录是否完整 ls -la ~/.config/superpowers/skills如果你所在网络环境访问 git 仓库不稳定也可以直接从项目的 Releases 页面下载压缩包解压到同一个目录效果是一样的。我个人推荐用 git clone因为后续拉取更新方便一条git pull就能同步最新技能包。克隆完之后还差最关键的一步注册。编码智能体工具不会自动扫描你磁盘上所有目录你需要在 Codex 的配置文件里或者启动命令的参数中把技能目录的路径告诉它。常规做法是在项目的AGENTS.md文件里引用技能索引或者在 Codex CLI 的配置项里指定 extra 目录。这一步做完AI 在会话启动时才能知道“哦这里有一份工作手册”。注册完成后建议先做一次冒烟测试。随便发起一个简单请求观察 AI 的输出风格有没有变化。如果它开始主动询问“需要我按测试驱动开发的流程来做吗”说明技能索引已经加载成功如果行为和之前一模一样大概率是路径配置没生效参考第五节第一个坑。2.3 初始化之后先检查这几个目录装好之后你会看到类似下面的目录结构。不同版本略有差异但核心部分基本一致~/.config/superpowers/ ├── skills/ │ ├── test-driven-development/ │ │ ├── SKILL.md │ │ ├── reference/ │ │ └── scripts/ │ ├── code-review/ │ ├── structured-commits/ │ └── ... ├── agents/ ├── lib/ └── superpowers.json这里几个目录要搞清楚skills是核心里面每个子文件夹代表一个技能。子文件夹里的SKILL.md是技能描述文件AI 判断“当前任务要不要用这个技能”时就看它。reference目录放详细资料比如设计文档、代码示例、常见问题列表AI 在使用技能过程中需要深入细节时会来查。scripts目录放可执行脚本技能流程里需要跑脚本化操作时用。agents目录是给不同角色准备的配置。比如你可能希望 Codex CLI 的编码 agent 多偏保守而审查 agent 多偏激进可以在 agents 下分别配置。superpowers.json是总开关哪个技能启用、哪个技能禁用全局参数都在这里调。我第一次装完其实没怎么看这几个目录直接就开始用结果后面调试自定义技能时一头雾水。现在回想初始化后花十分钟把目录结构过一遍是值得的尤其是打开两三个核心技能的 SKILL.md 看看它们是怎么写的后面就理解 AI 的很多行为是从哪来的了。3. 技能如何被 AI 发现和执行核心机制拆解3.1 一个技能的本质目录、描述文件、脚本我拆开 TDD 技能给你看看里面到底是什么。它的 SKILL.md 大概长这样--- name: test-driven-development description: 在需求开始前先编写失败测试再实现最小代码让测试通过最后重构。 when: 用户需要新增功能、修复 bug、重构代码时 --- # TDD 工作流程 1. 先编写一个失败的测试。 2. 运行测试确认它失败红灯阶段。 3. 编写最小实现代码让测试通过。 4. 运行测试确认通过绿灯阶段。 5. 重构保持测试通过。 6. 重复以上步骤直到需求完成。 ## 注意事项 - 不要跳过红灯阶段红灯是验证测试有效性的关键。 - 如果测试失败原因与预期不符先检查测试代码本身。 - 提交前务必运行全部测试集而不是只跑单个用例。AI 读到这份文件后会把它当作一套指挥自己行动的标准流程。你可能会问这跟提示词模板有什么本质区别表面看格式很像但关键差异在于“来源”。提示词模板是用户每次手动粘贴的一次性文本没有组织结构也没有配套维护SKILL.md 则是一个有明确语义、有固定路径、可被版本管理的文件实体AI 在会话开始时就知道“有一套这样的规范存在”而不是等你复制过来。引用块格式在这里有个很实用的点SKILL.md 里的“注意事项”通常对 AI 行为的约束力最强。我测试过把注意事項从三条加到五条生成结果里的测试覆盖率明显提高。所以我后来写技能时会把踩过的坑优先写进“注意事項”而不是写在正文里。3.2 自动加载与上下文裁剪它为什么比提示词高效superpowers 最让我觉得设计聪明的地方是它的“两级加载”机制。现在的编码智能体工具普遍有一个上下文窗口限制。如果把几十个技能的完整文档一次性全部塞进对话窗口会被秒占满真正给代码逻辑的空间就没了。所以 superpowers 的做法是会话启动时只加载技能的索引信息也就是每个技能的名称加一句话描述等到 AI 判断当前任务和某个技能相关时再去读取那个技能的完整 SKILL.md。这个过程很像你去图书馆查资料。你不会把整个图书馆的书全部扛到桌上看而是先翻目录卡片锁定哪几本书有用再一本一本地去架子上取。两级加载的价值在于索引阶段消耗的 token 极小即使挂了几十个技能也不怕而真正需要细节时AI 可以按需展开也完全来得及。我第一次自己调试技能时曾试着把一个 SKILL.md 写到三千字结果对话进行到第三轮就出现了“上下文长度不足模型只保留最近内容”的警告。把详细案例拆到reference目录之后主文件缩短到八百字问题立刻缓解。所以如果你用下来觉得 AI 经常“忘事”先别怪模型看看是不是技能文档写得太长了。3.3 技能的执行顺序与冲突技能多了以后就会遇到一个现实问题几个技能可能同时被触发。比如代码审查技能和结构化提交技能都涉及“检查代码质量”当用户说“帮我 review 一下这次改动”AI 可能同时加载两个技能然后按什么顺序执行目前主流的解决思路有两个。第一靠 description 的措辞做区分。如果你把 code-review 的 description 写成“审查代码逻辑、风格、安全性”把 structured-commits 的 description 写成“生成符合规范的提交信息”AI 就能比较准确地按职责分流。第二在用户请求里显式指定。比如直接说“请使用 code-review 技能不要用 structured-commits”AI 就会以用户指定为准。我在实际使用中发现一个规律技能描述越像“场景触发器”越容易被自动调用描述越抽象AI 越容易犹豫。这也提醒了我不要指望 AI 聪明到能处理所有模糊情况把技能的适用边界写清楚是使用者的责任。冲突问题还有一个更隐蔽的维度优先级。如果两个技能都对“代码风格”有要求一个要求 leaf style另一个要求以现有项目为准AI 就会无所适从。我的土办法是在 superpowers.json 里调整技能顺序让更权威的技能排在前面。虽然不一定每个版本都保证严格按顺序生效但至少降低了随机性。4. Java 项目实战让 TDD 技能真正落地4.1 场景设定一个 Spring Boot 服务的老需求为了验证 superpowers 不是花架子我用一个真实的 Java 需求做了实验。项目是一个 Spring Boot 用户服务需求是实现用户注册接口要求校验邮箱格式、用户名唯一性、密码强度并在入库前做加密。放在以前我会直接让 Codex CLI“写一个注册接口”它大概率会把 controller、service、repository、实体类一口气全倒出来然后我再去补测试。但这次我在请求里加了一句“请使用 test-driven-development 技能完成”完整请求是这样的请使用 test-driven-development 技能完成用户注册接口的开发。 需求细节 - 邮箱格式必须合法 - 用户名全局唯一 - 密码至少 8 位包含大小写字母和数字 - 入库前使用 BCrypt 加密这个请求本身没有任何魔法但加上技能调用后AI 的行为路径明显不一样了。4.2 技能介入后的开发流技能介入后AI 没有立刻写实现代码而是先做了三件事。第一它确认测试框架版本和现有测试目录结构第二检查实体类字段和数据库迁移脚本现状第三直接开始写RegisterServiceTest。这一步在以前的对话里几乎不会出现。过去它会等我把所有代码写完再问一句“需要我补充测试吗”而这次它把“先写失败测试”当作默认动作。测试写完它主动运行mvn test -DtestRegisterServiceTest看到测试预期失败后它才进入实现阶段。实现阶段写得很克制只写了让当前测试通过的最小代码没有顺手把 controller、状态码、异常处理器全加进来。一轮红灯一轮绿灯之后它开始补边界条件比如邮箱大小写、用户名包含特殊字符、密码恰好 8 位等场景的断言。整个过程里我最惊讶的是提交环节。任务结束时AI 生成了两个提交第一个写“test: add failing test for registration validation”第二个写“feat: implement register endpoint to pass validation tests”。这已经是标准的 TDD 节奏了而它只因为挂了 TDD 技能就主动做到了。4.3 实测效果与人工把关的边界最终统计下来这个接口一共产出了 14 个测试用例覆盖了主要成功路径和失败分支测试时间和手工写差不多但遗漏边界条件的概率确实明显降低了。不过我要强调技能包不是银弹它解决不了业务理解的问题。比如需求里“邮箱格式必须合法”AI 写了一个简单的Email注解校验就过了。但在我做的一个海外项目里业务要求只接收机构邮箱比如以公司域名为后缀这个规则 AI 是不知道的你必须显式写进请求或技能文档里。再比如 BCrypt 加密的 cost factor 到底设置多少这也属于业务决策技能不会替你判断。所以我对技能包的理解是它能把“可标准化的工程流程”标准化但把“需要业务判断的部分”留给用户。这反而是一个健康的分工——你不需要跟 AI 反复强调“先写测试”这些交给技能但你要把自己的领域知识注入进去让技能持续生长。5. 使用中的六个坑与排查思路5.1 技能目录路径配错AI 完全感知不到技能这个坑我踩得最深也最值得先说。第一次装完后我的技能索引一直没生效AI 行为跟之前没有任何区别。排查了半天最后发现是配置文件里的路径写成了~/.config/superpowers而工具在解析时没有展开~符号直接把它当成了相对路径。解决方法是使用绝对路径。在 Codex 的配置里写成/Users/你的用户名/.config/superpowers或者在命令里先export展开后的路径。如果你不确定当前解析到哪个目录可以在配置里加一个主动输出检查让 AI 读一下superpowers.json的内容看它认不认。5.2 技能版本不一致同样的请求队友的结果不同团队协作时每人本地一个 superpowers 目录很容易出现版本漂移。你在本地改了一个技能的描述同事没有同步结果同一段请求两个人得到的 AI 行为完全不同。我遇到过最夸张的一次是同事的 TDD 技能还是旧版AI 在红灯阶段前就先开始写实现完全违背了 TDD 原则。解决办法是把 superpowers 目录作为一个私有依赖纳入版本管理。我们团队的做法是在项目仓库里建一个vendor/superpowers目录固定版本号所有人都以这个目录为唯一事实源。CI 里跑代码生成相关任务时也引用同一个目录避免“本机行为”和“CI 行为”不一致。5.3 技能说明过长把上下文窗口占满前面提到过SKILL.md 不是写论文不是越长越好。我见过有人把整个公司编码规范塞进一个技能文件AI 加载它之后剩下的对话上下文几乎没了用户稍微问一句非相关的问题它就表现得像失忆了一样。经验值是单个 SKILL.md 控制在五百到一千字正文只放流程和关键禁忌详细代码示例和案例全部放reference目录。当你发现对话越来越“健忘”第一件事就是检查是不是技能索引阶段加载的文档太长了。5.4 自定义技能的脚本报错流程中断技能里如果依赖脚本脚本出错时 AI 会卡在一个很奇怪的状态——它可能反复重试也可能干脆放弃技能流程回到默认行为。我写的一个“数据库回滚检查”技能里面有个check_migration.sh因为路径写错导致执行失败AI 就把整个技能流程跳过了。现在我的做法是所有技能脚本先手动独立执行一次确认退出码正常技能文档里写清楚“如果脚本执行失败应当停止并明确报告原因而不是静默继续”。这个策略让 AI 在脚本出错时至少会停下来问人而不是自作主张往下走。5.5 多个技能同时触发行为漂移有一次我让 AI“重构一段代码并提交”结果它同时加载了重构技能和结构化提交技能做法本身没问题但它把重构过程拆成了五次小规模提交每两次提交之间都跑了一遍全量测试整个时间花了差不多十分钟。这个问题的解法我在前面提过要么在请求里手动指定技能把“重构”和“提交”拆成两个独立任务要么调整技能的 description让“重构提交”这类场景明确归属于某一个技能管理。我后来倾向于后者因为团队里的人未必每次都会手动指定。5.6 一个意外收获提交信息终于可读了最后说一个完全在计划之外的收获。structured-commits 技能被我挂上之后AI 生成的提交信息全部变成了统一的格式类型在前范围在中简短描述在后正文里还会带上关联的 issue 编号。以前我每周要花半小时改同事的提交信息现在这半小时彻底省下来了。这个技能其实特别简单SKILL.md 不到两百字但它的描述写得极精准AI 几乎每次提交都会自动命中。这让我意识到技能包的价值不取决于多复杂而取决于描述是否贴切。一个两段话的小技能如果能在真实工作流里稳定触发它比一个洋洋洒洒三千字但没人调用的“巨型技能”有用得多。最后再分享一个小习惯。我现在的新项目只挂了三个技能test-driven-development、code-review、structured-commits。先跑两个星期观察哪些流程被频繁触发、哪些技能几乎没人用然后再根据实际需要调整。一开始就把几十个技能全部挂上AI 光是决定“现在该用哪个技能”就要消耗不少上下文效果反而不如精挑细选。技能包这个东西精炼比丰富更重要。
阅读完成 · 觉得有帮助？
