最近一个月我几乎把主力 IDE 里的 AI 助手当成实习生来带。不是它写不出代码而是它总能写出“能跑”的代码却写不出“像样”的代码不写测试、不看项目规范、提交信息乱成一团。后来朋友丢给我一个叫 superpowers 的开源项目说能把这些毛病一次性治好。我抱着试试看的心态折腾了一周发现它确实改变了我对 AI 编码工具的认知。这篇文章不是官方文档的翻译而是我从安装到实际跑项目踩完所有坑之后整理的一份可以照着用的经验记录。如果你在用 Codex、Claude Code 这类 Agent 工具或者正想让 AI 在 Java 项目里真正上手干活那这组技能层配置值得你花十分钟看完。1. Superpowers 解决的真正痛点Agent 不缺算力缺的是工程纪律先说一个很反直觉的结论现在的 AI 编码 Agent 并不是能力不够而是“职业素养”不够。你让它写一个登录接口它三秒钟就能给你吐出一段 Express 代码接口能调通、参数能校验、数据库也能连上。但如果你不额外嘱咐它大概率不会顺手补测试不会按你项目的目录结构放文件更不会在提交时写一条符合 Conventional Commits 规范的信息。原因很简单模型是在大量代码上训练的它知道“正确代码长什么样”但它不知道“你的团队怎么干活”。人为什么天然会做这些事因为公司有研发规范、有代码评审、有老同事带着这些都被内化成了习惯。Agent 没有这种习惯它的行为完全由当前上下文决定。你说“写一个登录功能”它的上下文里全是登录功能相关的内容没有“测试规范”“提交规范”“代码风格”。所以它给出的结果永远是“最直接的答案”而不是“最符合工程规范的答案”。Superpowers 的思路就是把这个问题从“靠人每次提示”变成“靠文件系统约束”。它不是一个单独的模型也不是一个传统的插件而是一套以 SKILL.md 为核心文件的技能层。每个技能就是一个文件夹里面有一份 Markdown 格式的使用说明告诉 Agent 在什么场景下、按什么步骤、用什么标准去完成特定工作。安装之后Agent 会在合适的时机主动读取这些文件相当于入职第一天就领到一本《团队研发手册》而不是每次开会都听你在口头强调。1.1 为什么是“文件”而不是“提示词”我最早的想法特别简单既然要约束 Agent 的行为直接在系统提示词里多写几句不就行了比如“你总是先写测试”“提交信息要用规范格式”。但试过之后就发现三个问题。第一提示词会膨胀。你要约束的行为一多提示词越长模型对关键信息的注意力反而被稀释。第二提示词会过时。长对话里聊了几十轮之后系统提示词的约束力会被后面的大量对话冲淡。第三提示词没法复用。你在这个项目里写的约束换一个项目又得重新组织语言。SKILL.md 完全绕开了这三个问题。文件存在磁盘上Agent 在执行相关任务时“按需读取”读完之后就按照里面的步骤执行。它是持久化的、结构化的、可以放进 Git 版本管理的。打个比方提示词像是开会时口头说一句“大家注意安全”技能文件则是贴在工位上的一张《安全操作手册》——前者说完就散后者随时能查、随时能改、每个人看到的都是同一版。1.2 它和普通 Prompt、MCP 到底有什么区别我经常看到有人把 Superpowers 和 MCPModel Context Protocol混在一起其实它们解决的不是一类问题。MCP 解决的是“Agent 外接能力”的问题比如让 Agent 能查数据库、能调内部 API、能操作浏览器。而 Superpowers 解决的是“Agent 行为和流程”的问题比如要不要先写测试、提交信息怎么写、代码评审要看哪些点。两者完全可以共存在同一个项目里。我用一个表格把区别列出来这样比较直观维度普通 PromptMCP 工具Superpowers 技能存在形态会话内文字远程/本地服务磁盘上的 Markdown 文件持久性会被对话冲淡独立于会话永久存在可版本管理解决对象告诉 AI 做什么给 AI 额外的工具规范 AI 怎么做触发方式每次重复写按需调用Agent 自动读取或 slash 命令触发复用性差一般强跨项目可移植理解到这层你就知道 Superpowers 为什么不是“锦上添花”的小工具了。它补的是 Agent 工具链里最缺的那一层工程行为层。2. 初次安装解锁技能目录前要准备好的三件事安装本身并不复杂但很多人在第一步就栽了跟头因为没有先理顺环境就开始 clone 仓库。我建议按下面三步走每一步都有明确的验证方式不用瞎猜。2.1 环境检查Node、Git、可用的 Agent 会话Superpowers 这类技能层本身不依赖某个具体版本但它要挂载到 AI 编码工具上才能生效所以环境准备要围绕“能不能跑起一个 Agent 会话”来检查。比较稳妥的基线是Node.js 18 以上多数 CLI 工具本身是 Node 写的、Gitclone 技能仓库用、一个能正常对话的 Codex CLI 或 Claude Code 会话。另外建议装好 GitHub CLI因为很多技能仓库涉及私有仓库更新和 PR 提交用 GitHub CLI 认证之后可以省掉配 SSH key 的麻烦。这一步最容易忽略的是先确认 Agent 工具能“自己执行命令”而不是只在一个聊天窗口里生成代码。如果你用的 Codex CLI 还在纯问答模式那技能层装了也只能看不能用。检查方法很简单直接让 Agent“读取当前目录下的 package.json 并告诉我项目名称”如果它能自己执行 ls 或 cat说明基础能力没问题。2.2 把技能仓库 clone 到统一目录别放项目里环境就绪之后下一步是获取技能仓库。以官方发布页为准拿到仓库地址后把它放到一个全局统一的目录比如~/.superpowers。这里有一条非常重要的经验不要把技能目录 clone 进某个具体项目里。我见过有人图省事直接把技能仓库丢进正在开发的项目目录结果换一个项目就要重新配置一遍而且在 Git 提交时还得写 ignore 规则才能避免把整个技能目录带进去。正确的做法是让它独立于项目存在这样所有项目都能共享同一套技能另一个项目想用的时候只需要在配置文件里指一下路径。# 以实际仓库地址为准 git clone https://github.com/your-user/superpowers.git ~/.superpowersclone 完成之后先不要急着配置做一次快速健康检查进入~/.superpowers目录确认里面有一个skills文件夹并且该文件夹下至少有若干个以技能命名的子目录每个子目录里能看到SKILL.md或同等作用的 Markdown 索引文件。如果看到的只有 README 和文档说明你可能 clone 错了分支。2.3 让 Agent 在启动时“知道”这些技能存在这是安装的核心一步把技能目录的路径告诉 Agent 工具。不同工具的配置入口不一样但思路是一致的。以 Codex CLI 为例它支持在项目根目录放AGENTS.md文件里面可以写全局规则。以 Claude Code 为例对应的入口是CLAUDE.md。我所使用的版本是把技能读取规则写在AGENTS.md里内容大致如下# AGENTS.md - 开始编码之前先浏览 ~/.superpowers/skills/ 目录下的技能清单 - 任务涉及测试编写时必须读取 tdd-cycle 技能 - 任务涉及代码提交时必须读取 commit-message 技能 - 任务涉及代码审查时必须读取 review-checklist 技能写完之后启动一个新的 Agent 会话直接输入技能列表命令比如/superpowers具体命令名以你所用工具的实际支持为准看它能否列出技能清单。如果命令没有响应也可以换一种粗暴但有效的验证方式直接问 Agent“你现在能看到哪些技能把它们的名字列出来”。能列出说明路径配置成功列不出来就回头检查刚才写的读取规则有没有拼错路径。2.4 安装期最容易踩的三个坑第一次装的时候我先后踩过三个坑可以说都是那种文档里不会特意提醒、但实际卡你半小时的事情。第一个是路径问题。Windows 下用户目录如果包含中文用户名Agent 在解析C:\Users\张三\.superpowers这类路径时容易出现解析失败表现为技能列表加载不全或直接读不到。解决方法是把技能目录放到D:\tools\superpowers这种纯 ASCII 短路径下然后在配置里使用绝对路径。第二个是 YAML frontmatter 格式问题。SKILL.md 通常以 YAML 元信息开头包括技能名称、描述、适用场景。如果你自己新建技能时写了多行描述却在缩进上不严谨Agent 解析时会把整个文件标记为无效技能在列表里直接消失。这个问题排查起来特别隐蔽因为文件内容看起来一点问题都没有。第三个是“改了不生效”问题。Agent 只在会话启动时扫描技能目录新增或修改技能之后不重启会话是不会被感知的。很多人改完文件之后发现行为没变以为是权限问题实际上只是没开新会话。3. 核心工作流拆解技能文件到底在约束什么安装完成只是第一步真正有价值的是理解技能文件的运行机制。我在实际使用中把技能分成了两类一类负责“流程”一类负责“标准”。流程类技能告诉 Agent 先做什么后做什么标准类技能告诉 Agent 什么样算做得好。两者经常组合出现。3.1 TDD 技能先写失败测试再写实现代码TDD测试驱动开发是最典型的一个流程类技能。它的核心要求是接到功能需求时Agent 不能直接开始写实现而是要先写一个会失败的测试然后写最小实现让测试通过最后重构。一份简化的tdd-cycleSKILL.md 大概长这样--- name: tdd-cycle description: 在实现功能之前先写测试遵循 red-green-refactor 循环 --- # TDD Cycle 当你接到一个功能实现任务时按以下步骤执行 1. 为预期行为编写一个失败测试确保测试正确地描述了需求 2. 运行测试确认它失败red证明测试确实能发现缺陷 3. 编写最小实现代码让测试通过green 4. 在不改变测试结果的前提下重构实现代码refactor 5. 运行完整测试套件确认没有回归为什么这件事对 Agent 特别有用因为 Agent 默认的策略永远是“最小努力满足当前请求”你先告诉它“写个登录接口”它就真的只写一个接口不会主动扩展测试。但当它读到tdd-cycle技能之后它的行为链条就变了先写测试、先确认测试失败、再写实现。我实际跑过一个小例子让 Codex 用 Node.js Express 写一个简单的 CRUD API。没有技能层时它直接生成了一堆路由代码和两个锦上添花的测试用例加载 TDD 技能之后它先花时间把接口行为拆成了几个测试场景包括正常创建、参数缺失、数据不存在三种情况然后才动手写实现。测试覆盖率从“象征性”直接变成“覆盖主流程”。这就是技能文件的作用它把“人认为理所当然的步骤”显式化。3.2 提交信息规范技能把最后一步也管起来第二个让我感触很深的是提交信息规范技能。没有约束时Agent 的提交信息经常是fix bug或者update file更夸张的是有时候直接把一整段代码变更塞进update两个字里完全无法追踪。技能文件可以这样定义--- name: commit-message description: 使用 Conventional Commits 规范生成提交信息 --- # Commit Message 提交信息必须遵循 Conventional Commits 格式 - feat: 新功能 - fix: 修复 Bug - docs: 文档变更 - refactor: 重构且不影响功能 - test: 新增或修改测试 正文需要说明变更动机每个提交只包含一个逻辑变更。加上这个技能之后Agent 在完成代码修改后会自动读取 Git diff 内容按照规范生成提交信息。我甚至能让它执行git add和git commit的完整流程前提是在技能文件里明确允许。对于有经验的开发者来说这条看着不起眼但它能让项目的 Git 历史从一片混沌变成按规范排列的脉络。3.3 自定义技能不要写“万金油”要写“触发条件”Superpowers 最有吸引力的地方是可以自己定义技能。新建一个技能非常简单在skills目录下建一个文件夹里面放一份SKILL.md写好 frontmatter 和正文规则即可。但我建议一个原则技能文件中的description字段要写清楚“什么时候用”而不是“这个技能多厉害”。Agent 会依据description来决定是否触发某个技能如果你写得太宽泛比如“指导你写出更好的代码”那它几乎在任何任务都会把这份文件读进来结果就是上下文被大量无关内容挤占Token 消耗飙升且决策变慢。我自己的做法是给每个技能定义非常具体的触发条件例如“当任务涉及数据库表结构变更时触发”“当任务涉及修改已存在的测试文件时触发”。这样 Agent 的读取行为就从“什么都要读”变成了“相关才读”效率和准确性都会明显提升。技能数量不是越多越好我最终稳定在五个左右覆盖计划、测试、实现、审查、提交五个环节其他零散的规范统一写进 AGENTS.md 里作为长期背景规则。4. 热门落地组合Codex 里的 Superpowers以及 Java 场景“codex superpowers”成为近期搜索热词并不意外。Codex CLI 本身是一个能自主执行命令的 Agent 工具大家期待它的不只是“在编辑器里给建议”而是能真正独立完成一个小型开发任务。Superpowers 恰好补上了它在“工程行为规范”上的缺口。4.1 在 Codex 里把 Superpowers 用起来接入逻辑和前面说的配置一样核心是让 Codex 在会话启动时读取技能目录。我在AGENTS.md里写了这样一段# AGENTS.md - 任何编码任务开始前先运行 /superpowers:plan 技能拆解需求 - 涉及多文件修改的任务必须先输出改动方案再动手 - 默认使用 TDD 技能测试先行 - 提交代码前使用 commit-message 技能生成提交信息实际体验下来Codex 这类能自主执行命令的工具在加载技能层之后行为模式变化很明显。一个典型的会话会变成这样先调用plan技能把需求拆成三到五个步骤接着读取tdd-cycle技能为每个步骤写测试然后实现、运行测试、重构最后生成一条规范的 commit message。整个过程你只需要在几个关键节点确认。有一个细节值得注意Codex 的会话上下文窗口虽然大但也不是无限大。技能文件中如果写了大量示例代码Agent 会在读取时把它们全部塞进上下文导致后续可用的窗口变小。我在使用中发现技能正文尽量写“步骤和判断标准”少贴大段完整代码把代码示例压缩成短小的示意片段能显著提升长任务的稳定性。4.2 从零搭一个 CRUD API实测对比为了验证效果我做了一个简单但完整的实测让 Codex 在一个空目录里从零搭建 Node.js Express Jest 的 CRUD API分别跑“无技能”和“有技能”两个回合。无技能回合的表现如下Agent 直接生成了一整套代码包括路由文件、控制器文件和数据模拟文件但测试只写了一小段“hello world”级别的冒烟测试。提交时它自作主张输出了update README and add api这样的信息实际上连 README 都没更新。有技能回合的表现是完全不同的轨道Agent 先通过plan技能列出了六个步骤包括设计接口、建目录结构、写测试、实现、运行测试、提交代码。它还真的一步一步执行先写了三个失败测试再写实现让测试转绿最后提交信息是feat: add CRUD endpoints for user resource with test coverage。两次用时相差不大但产出物的可用性完全是两个档次。4.3 Java 项目为什么特别关注 superpowers java另一个热搜点是 “superpowers java”。Java 项目相比 Node 项目更需要技能层的定制原因也很直接Java 工程的结构性强制约定太多了。比如项目结构必须符合 Maven 或 Gradle 的约定Spring Boot 的包扫描机制要求主类位置不能乱放JUnit 5 的测试类命名和生命周期方法有一定的使用范式Mockito 的使用又涉及一堆注解约定。通用 Agent 面对这些约定时经常做出“看起来对、跑起来崩”的判断。技能包的作用就是把 Java 项目里的这些“约定俗成”写成文件让 Agent 在接触这类项目时按规则办事。一个典型的 Java 技能包会覆盖几个方面项目结构规范比如src/main/java与src/test/java的职责划分构建系统指令比如 Maven 用什么命令跑测试、如何跳过 Checkstyle框架约束比如 Spring Boot 主类放置位置、Controller 层与 Service 层职责边界测试模板比如 JUnit 5 Mockito 的标准写法。我建议 Java 开发者接入时不要一开始就把所有技能全加载。先用最小集跑通一个任务比如只加载“Maven 命令封装”和“JUnit 测试模板”两个技能跑通一个完整的小需求再逐步加入其他约束。因为 Java 技能包的规则密度天然较高一次加载过多会让 Agent 在“读规则”上消耗太多上下文反而拖慢任务执行。5. 跑起来之后的真实心得Token 开销、权限边界与排查路径最后这部分是纯经验也是我认为比任何功能列表都重要的内容。Superpowers 用得好不好很大程度上取决于你如何处理三个问题Token 开销、权限边界、故障排查。5.1 Token 开销技能不是装得越多越好技能文件的读取并不是免费的。每读一份 SKILL.md里面的内容就要占用一部分上下文空间。如果技能数量太多或者每个技能文件写得过长Agent 每次任务都会背上一个“沉重的书包”。我做过对比测试安装约十五个技能时同样的任务比不装技能时 Token 消耗高出约百分之四十到六十但把技能精简到五个核心技能后Token 消耗只增加百分之十到二十而输出质量几乎没有下降。原因是核心技能的每次读取都能直接影响行为噪音技能的读取不仅浪费 Token还可能让 Agent 在多个规则之间纠结。所以我的建议是默认保持一个精简技能集特殊项目里需要额外技能时临时指定、用完即删。另外善用description字段实现“按需加载”让 Agent 只在相关场景下读取对应技能而不是每轮对话都把全部技能索引刷一遍。5.2 权限边界技能文件会让 Agent 更“自信”也更危险技能文件本质上是给 Agent 写了一堆“操作规程”Agent 读到规程后会更有底气去执行。这就有个副作用它可能把本应让你确认的操作也一并执行了。比如某个技能文件里写了“运行以下命令完成构建”Agent 就可能直接跑mvn clean install这还好但如果技能文件里写了“修改版本号并推送提交”Agent 就可能在未确认的情况下git push origin main。我的处理方式很朴素凡是不可逆操作在技能正文里明确写一句“执行前必须向用户展示命令并等待确认”。把这句话写进技能文件的“总则”部分能有效降低误操作风险。5.3 技能不生效时按这条路径排查技能层失效是最常见的问题但它几乎都能被定位。我自己形成了一套固定的排查思路按顺序做下来五分钟内能定位问题确认配置入口文件AGENTS.md/CLAUDE.md里写的技能目录路径是否存在且正确。在新会话中执行技能列表命令确认该技能是否出现在清单里。不在清单里说明文件解析有问题优先检查 frontmatter 的 YAML 语法。如果在清单里但行为没变化说明技能文件中的触发条件写得过于狭窄description没有覆盖到当前任务的场景调整描述用词。如果以上都没问题把会话关闭重启再试一次让 Agent 重新扫描技能目录。这套顺序的核心逻辑是“从路径到解析再到触发条件”层层递进跳过任何一层都会让人绕弯子。5.4 团队协作把技能仓库变成团队资产最后聊一下团队场景。Superpowers 很适合作为团队级的工程资产来维护因为它天然是文件、天然可以进 Git。我把团队的技能仓库单独建了一个 repo团队成员各自 clone 一份配置到自己的 Agent 工具里。谁觉得技能规则需要调整就提一个 PR其他人 review 合并之后拉取更新。这样团队里的编码规范从“文档里的 PPT”变成了 Agent 每天实际会读取的执行规则落地效果比我预想中好得多。对于刚接触团队协作的人我建议第一波只推两个技能一个是代码评审检查单一个是提交信息规范。这两个技能见效最快、最容易被团队成员接受。等大家习惯了“Agent 会遵守规则”这个设定之后再逐步把 TDD 技能和计划技能加进来。我在实际使用中最深的体会是Superpowers 并没有让 AI 多写代码它改变的是 AI 写代码之前的“决策过程”。当我用plan技能把需求拆成步骤时AI 会带着我做需求梳理这比直接让 AI 生成代码更能发现问题。如果你也想提升现有 Agent 工具的产出质量与其不断在提示词里打补丁不如把工作规范落成技能文件。这一套思路对 Codex 有效对 Claude Code 有效对任何基于文件上下文的 Agent 工具都有效。