最近 GitHub 上最让我上头的项目就是 superpowers准确说是给 Codex 这类终端 AI 编程助手打技能补丁的那套框架。很多人在搜 superpowers 使用指南、superpowers 安装、codex superpowers其实就是想解决同一个问题Codex 确实能干活但让它独立负责一个完整任务时经常表现得像个“有体力没章法”的新人——上来就改代码不先列计划测试跑挂了它随手打补丁而不是追根因。superpowers 就是在这一层给你兜底的它不直接写代码而是给 AI 一整套可复用的工作技能让它在动手前知道该按什么流程来。适合谁来用如果你在用 Codex CLI、Claude Code 这类 agentic 编程工具做真实项目并且受够了“AI 一跑就偏、一大改就崩”的体验这篇文章就是给你写的。我会把 superpowers 是什么、怎么装、日常怎么用、Java 项目里怎么落地以及我踩过的坑全部捋一遍。1. superpowers 到底是什么给 AI 编程助手挂上技能包1.1 从“聊天窗口”到“技能驱动”的转变先放下工具本身想一个问题为什么同样的 Codex有时候给你惊为天人的代码有时候却能在一个空指针上来回折腾半小时差别不在模型能力而在“流程”。默认状态下AI 拿到一个任务是凭它在训练数据里学到的“平均经验”去发挥——它不会主动规划不会先写测试也不会在重构前确认行为不变。这些工程方法它不是不懂而是没人提醒它、它就不做。superpowers 的做法很简单把这些工程方法论写成结构化的 SKILL.md 文件放到项目里让 AI 在需要的时候“按需加载”。每个技能文件都有元信息和正文AI 会先读 description判断这个技能适不适合当前任务适合才加载完整指令。这个设计很像人脑里的“方法库”——不是所有时候都要掏出 TDD 那套但当你决定要写一个新功能时你确实需要一套固定的动作顺序。我从第一次手动让 Codex “先写个测试用例”开始到后来发现它可以自己主动提出“我应该先使用 tdd 技能”这个体验变化是非常明显的。不是模型变聪明了而是它的行为被技能约束住了。1.2 核心价值与适用场景superpowers 到底解决了什么总结下来是三件事稳定、省上下文、可积累。先说稳定。没有技能约束的时候AI 的每一次行为都取决于你这次对话里碰巧写了什么。今天你记得让它“先写测试再写实现”它表现得挺靠谱明天你忘了写它就又放飞了。技能是把这份靠谱沉淀成固定流程每次任务都有兜底的动作顺序不依赖临场发挥。再说省上下文。有一种土办法是把几千字的工程规范全塞进 system prompt 里效果当然有但非常浪费 token而且 prompt 越长模型越容易忽略尾部指令。superpowers 是懒加载的平时只读一个技能清单等到真正要写测试了才把 tdd 的完整指令拉进来。这个设计对长期使用影响很大。最后是可积累。你可以把团队自己的代码规范、发版流程、代码审查清单都写成技能。这样 AI 也能“按团队规矩办事”而不是按训练数据里的“通用最佳实践”随机发挥。适用场景很宽。个人项目、小团队协作、甚至给公司的 Java 老项目做维护都能用上。相对地如果你只是偶尔让 AI 生成一个脚本、问个 API 用法那确实没太大必要搞这套因为技能框架本身也是要花时间维护的。下面是几个核心技能和它们的触发场景技能名触发场景核心作用planning开始一个多步骤任务前产出分步计划排优先级标注风险tdd写新功能、修 bug强制先写失败测试再写实现最后重构debugging报错、测试挂掉先复现并定位根因再改代码refactoring调整旧代码结构保持行为不变小步重构随时验证code-review提交前检查 diff按检查清单逐项审查自己的改动2. 安装与初始化把技能包装进你的终端工作流2.1 前置条件与环境准备先看环境。superpowers 依赖的是你本机已经有一个能跑 agentic 任务的 CLI 工具最常见的两个是 Codex CLI 和 Claude Code。这篇文章我会以 Codex 为主线来讲Claude Code 的用法大同小异区别会在后面标注。确认条件Node.js 18 以上因为 CLI 工具本身基于 Node 生态。Git 已装好安装技能包要走 git。终端里codex --version能正常输出版本号。装好 CLI 之后你需要在本地某个项目里开始试验不建议直接在系统根目录折腾。新建一个测试项目或者挑一个你熟悉的小项目后面所有操作都在这个项目里做。为什么要这么做因为技能是跟项目走的尤其是代码里的 AGENTS.md 引导文件它会告诉 Codex 这个仓库里有哪些特殊规则。如果你在根目录做实验这个引导文件的影响范围会失控Codex 会在所有项目里都尝试加载技能反而有问题。2.2 安装 superpowers 的两种方式第一种是当作插件装到 CLI 里。如果你用的是支持插件机制的版本可以直接进 CLI 的插件目录把仓库 clone 进去。以 Claude Code 的目录结构为例一般是~/.claude/plugins/在里面执行git clone https://github.com/obra/superpowers之后 CLI 启动时会自动发现技能目录。第二种是项目级安装我更推荐这种方式因为它把技能和项目绑定在一起团队成员 clone 下来就能用不用每个人都配一遍全局插件。做法是在项目根目录建一个.superpowers/目录把仓库里的 skills 子目录拷进去或者直接把整个仓库作为一个 submodule 挂到.superpowers下。结构大概是这样.superpowers/ SKILL.md skills/ planning/SKILL.md tdd/SKILL.md debugging/SKILL.md refactoring/SKILL.md这一步做完还没结束。技能目录只是原材料你得让 Codex 知道“这个项目里有技能可以用”。最稳妥的办法是在项目根目录的 AGENTS.mdCodex 的项目说明文件里写上一段本仓库启用了 superpowers 技能框架。处理任务前先读取 .superpowers/SKILL.md 和 .superpowers/skills/ 目录下的技能列表根据任务类型选择合适的技能并在执行过程中严格遵循技能内定义的步骤。这段提示是连线AGENTS.md 是 Codex 每次启动都会读的项目上下文你在这里告诉它技能的存在它才会在后续任务里主动去翻技能库。如果这一步漏了技能文件装得再多AI 也只会当一个普通的隐藏目录完全不会主动去碰。2.3 验证安装是否生效装完别急着写业务代码先做一个验证。打开终端进到项目目录启动 Codex让它做一件简单的事“请读取项目里的技能清单告诉我你可以使用哪些技能以及每个技能大概会在什么场景下使用。”如果安装成功它会列出 planning、tdd、debugging 这些技能并且能简单描述各自的适用场景。如果它说“没找到相关文件”优先检查.superpowers目录是不是被放到了项目根目录注意别放进src或子目录里。AGENTS.md 里的那段话是不是真的被 Codex 读到了。你可以故意在项目里留一个 TODO 注释然后问它项目上下文里有什么。我第一次装的时候就是放错了目录把技能库 clone 到了~/.codex下结果 Codex 在项目里完全感知不到排查半天才发现是路径问题。这类问题很典型不是工具没装而是它没有被放在“AI 能看到的位置”。所以验证这一步别省五分钟能省下后面一整天的困惑。3. 核心用法让技能在真实项目中跑起来3.1 从“帮你写代码”到“先给你一份作战计划”装好之后我第一次真正“被震撼”到是让 Codex 实现一个稍微复杂一点的需求给现有的博客系统加一个标签聚合页面。放在以前它会直接撸起袖子开始改模板、加路由、写查询语句一气呵成然后大概率在某一步改坏。但那次它在读取了 planning 技能之后回复的开头变成这样“我先用 planning 技能整理一下这个任务涉及入口路由、数据库查询、模板渲染、缓存清理步骤排序为……第一步建路由和查询接口第二步写模板第三步补测试风险点是标签数据量变大之后的索引问题我会在查询里先做优化并加一个覆盖测试。”这不是我 prompt 里写的是 planning 技能教会它的。它先拆解问题、列出步骤、排优先级、标注风险然后才开始动手。整个过程我可以随时叫停、调整步骤顺序而不是等它写完几百行代码之后才发现方向错了。这个变化对“AI 写代码”这个场景是质变我不是在检查一个结果而是在审查一个过程。后面我养成了一个习惯只要任务稍微复杂一点我都会先跟 Codex 说一句“先按 planning 流程走”。它会严格地输出一个 Plan我再把 Plan 确认一遍它才开始执行。这一来一回比让它直接改代码慢个两三分钟但省下的返工时间往往是几倍。尤其是涉及多个文件联动的功能没有计划直接动手几乎是必出事。3.2 TDD 技能测试先行怎么落地如果说 planning 解决的是“先想清楚再做”tdd 技能解决的是“做的时候每一步都稳”。这个技能的核心逻辑就是我们熟知的 red-green-refactor但它要求 AI 严格遵守顺序先写一个会失败的测试确认测试失败是因为“功能还没实现”而不是因为“测试本身写得有问题”然后再写最少量的实现代码让测试变绿最后才做重构。我实际跑下来的体会是AI 对“先写测试”这个要求执行得比人还严格。有次我让它给一个日期工具类加一个“判断是否工作日”的方法它居然先写了几个边界用例周一返回 true、周末返回 false、法定节假日怎么办、空参数怎么处理。它在测试用例里把异常分支都列出来了然后才去写实现。这个习惯很重要尤其当项目里测试覆盖率一直提不上来的时候。让 AI 先写测试覆盖率会随着功能代码一起补上来而不是写完功能之后靠人去追着补测试。如果你项目里的规矩就是“必须有测试才能合入代码”这个技能能直接帮你把流程规范化。我还有另一个感受一旦 AI 养成了“测试先行”的习惯它自己写出的代码会明显更内聚因为它需要让每个小行为都能被测试捕获自然就会减少藏着掖着的隐含逻辑。3.3 调试与重构技能调试和重构是我最开始没太在意的两个技能用多了之后发现它们才是“防止 AI 把项目改烂”的关键。调试技能的执行方法是反直觉的它不允许 AI 一上来就改代码而是要求它先复现问题、收集证据、定位根因再把问题变成一个新的失败测试修复之后用这个测试来防回归。听起来像是人肉 debug 的标准流程但 AI 默认不会这么做。它更倾向于“看到报错直接改”运气好改对了运气不好打了一堆补丁代码越来越乱。debugging 技能就是来治这个毛病的。refactoring 技能则更像一道保险它要求 AI 在重构过程中始终保持行为不变并且每一步都允许运行测试来验证。我拿它重构过一个老项目的核心工具类AI 在重构完一个方法之后主动跑了一遍测试并且停下来告诉我“这一步重构后有一个测试依赖了旧方法名我需要先改调用方再继续”。这个细致程度在没有技能约束的时候是很少见的。我第一次用 refactoring 技能重构一段耗时很长的 SQL 拼接代码时AI 没有一次性把所有逻辑重写而是先提取了一个常量再抽了一个方法最后才调整了拼接顺序。每一步之间都保持可编译、可测试。当时的感受是它不像在“写代码”更像一个谨慎的老工程师在小心翼翼地动别人的代码。4. Java 场景superpowers 在 Java 项目里的实战4.1 为什么 Java 项目更需要技能约束很多人搜 superpowers java是因为 Java 项目用 AI 编程助手的时候痛点格外明显。原因不难理解Java 项目通常结构重、构建链路长一个需求要动 Controller、Service、Repository、实体类、Mapper XML、pom 依赖AI 很容易中途迷失再加上 Maven/Gradle 编译和测试跑得慢AI 一旦在不该动的地方改出问题发现成本很高。更现实的一点是Java 老项目普遍有历史包袱命名不统一、测试缺失、模块依赖混乱。AI 在这种项目里默认发挥会很拉胯因为它学到的“一般 Java 写法”和项目里的“实际 Java 写法”经常对不上。而技能框架正好能把项目的特殊规矩写进去让 AI 按你的规矩来而不是按训练数据里的“通用最佳实践”来。举个小例子很多 Java 项目的单元测试约定是Service 层用 Mockito mock 掉 Repository不碰数据库集成测试才走真实数据库。默认状态下的 AI 经常会顺手写一个带 SpringBootTest 的测试把整个上下文都拉起来。如果你在技能里写清楚“单元测试不许启动 Spring 上下文”它就会老老实实写 mock 型测试跑测试的速度直接快一个数量级。4.2 在 Java 项目中安装和启用技能Java 项目里启用 superpowers 的步骤和前面讲的通用安装基本一样但有几个细节要注意。第一技能目录建议放进项目根目录并且提交到 Git。对于团队协作来说每个成员 clone 之后天然就带上了技能不需要各自配置。如果你不想让技能文件污染仓库用 submodule 或者直接拷进.superpowers也是可行的看团队习惯。我个人建议提交到仓库里因为技能文件本质上是文档它记录了团队的工作流跟 README 是一样的性质。第二AGENTS.md 里的引导语要写得跟 Java 技术栈相关。比如这样本仓库为 Maven 多模块 Java 项目。启用 superpowers 技能框架。任务开始前先读取 .superpowers/SKILL.md若任务涉及新功能开发必须使用 tdd 技能先编写 JUnit 5 测试涉及依赖调整时先修改对应模块的 pom.xml并在最终跑完mvn -q test后再结束任务。这段描述比通用提示更有用因为它把 Java 项目特有的动作改 pom、跑 Maven 测试也并入了 AI 的流程里。实际效果是AI 改完代码不会直接说“完成了”而是真的去跑一遍mvn test并且把失败信息贴回来。这相当于把“最后跑一次全量测试”的验收动作固化进了 AI 的交付标准。第三Java 技能可以自己定制。比如把 Mockito 的使用规范写进一个技能的 SKILL.mdAI 在写单元测试时就会优先用 given-when-then 结构而不是随机发挥。这个定制成本很低但收益很高适合团队逐步沉淀。我见过有团队把 Lombok 的使用限制、MapStruct 的生成路径、甚至 Git commit 消息格式都写进了技能AI 的产出风格会越来越贴近团队既有代码。4.3 实战体验一个 Spring Boot 小功能拿我自己做过的一个例子来讲。项目是一个 Spring Boot 的订单服务需求是给订单查询接口加一个“按用户 ID 和时间范围过滤”的能力。如果按老套路让 Codex 直接干它大概率会先找到 Controller然后顺着往下改 Service、Mapper最后补几个测试就算完事。启用技能之后它的流程变成了这样先读取 planning 技能列出改动路径再调用 tdd 技能在动手改代码前先写了 OrderQueryServiceTest设计了“空的用户 ID 抛异常”“时间范围跨月查询返回正确结果”“无条件查询时不分页”这几个用例然后才去改 Service 实现和 SQL 映射最后跑 Maven 测试等全部通过之后又调用了 code-review 技能对照检查清单看了一遍自己的 diff提了一个“分页参数建议放到请求参数里而不是写死在 SQL 里”的优化点。整个过程我基本只在旁边看着偶尔对它的 Plan 说“这块没必要做”。代码量虽然和以前差不多但质量明显更可控了测试先行意味着每个改动都有验证计划先行意味着没有“写着写着发现需要回滚”的情况。这里面最让我满意的是它主动提的那个分页优化建议——不是让我去改而是它识别出这个改动会越出任务边界于是明确标出来提醒我决策。这种“知道自己能做什么、不该做什么”的边界感正是技能约束带来的。5. 常见问题与排查技巧实录5.1 技能没被加载怎么办这是最多人踩的坑。症状一般是明明装好了技能库但 Codex 回答问题时完全不提技能、不按流程走。我之前讲过的路径问题是一类原因另一类更隐蔽的原因是AGENTS.md 的引导语写得不够明确AI 读了但没理解“这是一个可以按需加载技能的项目”。我的排查顺序是先直接问 AI“你能读取项目里的 .superpowers 目录吗里面有哪些技能”这一步能确认它有没有感知到技能文件的存在。如果它说没找到检查目录位置确保.superpowers在项目根目录。如果它找到了但没有使用回去把 AGENTS.md 的引导语改得更“硬”直接写明“处理任务前必须检查技能清单严禁跳过”。还不行就在当前会话里手动让它加载把 SKILL.md 的路径贴给它并让它读完再开始任务。不要觉得这个流程麻烦。技能框架本身是“懒加载”的AI 默认不会主动翻文件引导语写得越明确它的主动性越高。实测下来“必须”“严禁”这类强约束词汇比“可以”“建议”有效得多因为 AGENTS.md 里的措辞会被模型当成规范而非候选方案。5.2 技能和项目现有规范冲突怎么办有时候不是技能没用而是技能和项目现实矛盾。比如团队习惯先写实现后补测试而 tdd 技能要求测试先行项目根本没有测试基础设施让 AI 先写测试等于先搭一套框架成本很高又比如规划流程里要求的多步审批在个人项目里完全是浪费。遇到这种情况我的建议是不要硬套。技能库的目录结构允许你按需启用用不到的技能可以直接不放进项目或者写一个项目级的覆盖技能把团队自己的流程写进去。它不是宗教仪式而是一套“流程的知识库”你的团队怎么干活就应该怎么配置。我自己到了新项目第一件事永远是删掉用不上的技能只留 planning、tdd、debugging 这几个核心项。如果你发现技能本身没问题但和 AGENTS.md 里的其他规则产生了冲突以 AGENTS.md 为准。我在一个项目里同时定义了“新功能必须走 tdd”和“紧急修复可跳过测试”两条规则结果 AI 每次都要纠结一下到底该走哪条。后来我把规则改成“紧急修复必须注明原因且事后补测试”冲突就消失了。技能文件的描述语言尽量一致可以减少模型的误解。5.3 实测性能与上下文开销最后说一个比较实际的问题技能文件会不会吃太多上下文我自己的经验是单个 SKILL.md 文件控制在 300 到 600 行为宜技能清单文件只放 name 和 description不放正文。这样 AI 每次启动只需要读一个清单不会把几百行技能正文全部加载进来。清单可能只占 1 到 2 千 token完全在可接受范围内。真正用到某个技能时才会加载它的完整正文这个开销也只在执行特定任务时出现。还有一个小建议不要把技能库当成“万能 prompt 收藏夹”。我曾经往里面堆各种规范从代码风格到 Git 提交信息格式都写进去结果技能越大AI 对核心流程的执行率反而越低。技能就像一个储物间塞太满真正要用的时候反而翻不到东西。精简到几条核心技能效果最好。我现在每个项目的技能库里通常只有 4 到 5 个技能每个文件聚焦一件事。另外实测时我发现技能的正文结构也有讲究。最有效的是“场景判断 执行步骤 禁止事项”三段式先写什么情况下用再写具体步骤最后写不能做什么。AI 对“禁止”的理解比“应该”更到位因为负样本在指令遵循场景里往往更明确。技能正文里如果只有空泛的原则AI 执行起来会大打折扣。最后再分享一个小技巧技能里可以写“完成后向用户汇报时必须附带测试结果”这一句话能省你很多确认时间。我以前每次都要追问“测试跑了吗”加了这条之后Codex 会主动在回复里带上测试输出。整个使用体验一下子就从“监督 AI 干活”变成了“验收 AI 的交付物”。 
长河君 · 2026/11/4 10:31:43 · 阅读 1.2k superpowers 技能框架：让 Codex 从会写代码到会干工程
最近 GitHub 上最让我上头的项目就是 superpowers准确说是给 Codex 这类终端 AI 编程助手打技能补丁的那套框架。很多人在搜 superpowers 使用指南、superpowers 安装、codex superpowers其实就是想解决同一个问题Codex 确实能干活但让它独立负责一个完整任务时经常表现得像个“有体力没章法”的新人——上来就改代码不先列计划测试跑挂了它随手打补丁而不是追根因。superpowers 就是在这一层给你兜底的它不直接写代码而是给 AI 一整套可复用的工作技能让它在动手前知道该按什么流程来。适合谁来用如果你在用 Codex CLI、Claude Code 这类 agentic 编程工具做真实项目并且受够了“AI 一跑就偏、一大改就崩”的体验这篇文章就是给你写的。我会把 superpowers 是什么、怎么装、日常怎么用、Java 项目里怎么落地以及我踩过的坑全部捋一遍。1. superpowers 到底是什么给 AI 编程助手挂上技能包1.1 从“聊天窗口”到“技能驱动”的转变先放下工具本身想一个问题为什么同样的 Codex有时候给你惊为天人的代码有时候却能在一个空指针上来回折腾半小时差别不在模型能力而在“流程”。默认状态下AI 拿到一个任务是凭它在训练数据里学到的“平均经验”去发挥——它不会主动规划不会先写测试也不会在重构前确认行为不变。这些工程方法它不是不懂而是没人提醒它、它就不做。superpowers 的做法很简单把这些工程方法论写成结构化的 SKILL.md 文件放到项目里让 AI 在需要的时候“按需加载”。每个技能文件都有元信息和正文AI 会先读 description判断这个技能适不适合当前任务适合才加载完整指令。这个设计很像人脑里的“方法库”——不是所有时候都要掏出 TDD 那套但当你决定要写一个新功能时你确实需要一套固定的动作顺序。我从第一次手动让 Codex “先写个测试用例”开始到后来发现它可以自己主动提出“我应该先使用 tdd 技能”这个体验变化是非常明显的。不是模型变聪明了而是它的行为被技能约束住了。1.2 核心价值与适用场景superpowers 到底解决了什么总结下来是三件事稳定、省上下文、可积累。先说稳定。没有技能约束的时候AI 的每一次行为都取决于你这次对话里碰巧写了什么。今天你记得让它“先写测试再写实现”它表现得挺靠谱明天你忘了写它就又放飞了。技能是把这份靠谱沉淀成固定流程每次任务都有兜底的动作顺序不依赖临场发挥。再说省上下文。有一种土办法是把几千字的工程规范全塞进 system prompt 里效果当然有但非常浪费 token而且 prompt 越长模型越容易忽略尾部指令。superpowers 是懒加载的平时只读一个技能清单等到真正要写测试了才把 tdd 的完整指令拉进来。这个设计对长期使用影响很大。最后是可积累。你可以把团队自己的代码规范、发版流程、代码审查清单都写成技能。这样 AI 也能“按团队规矩办事”而不是按训练数据里的“通用最佳实践”随机发挥。适用场景很宽。个人项目、小团队协作、甚至给公司的 Java 老项目做维护都能用上。相对地如果你只是偶尔让 AI 生成一个脚本、问个 API 用法那确实没太大必要搞这套因为技能框架本身也是要花时间维护的。下面是几个核心技能和它们的触发场景技能名触发场景核心作用planning开始一个多步骤任务前产出分步计划排优先级标注风险tdd写新功能、修 bug强制先写失败测试再写实现最后重构debugging报错、测试挂掉先复现并定位根因再改代码refactoring调整旧代码结构保持行为不变小步重构随时验证code-review提交前检查 diff按检查清单逐项审查自己的改动2. 安装与初始化把技能包装进你的终端工作流2.1 前置条件与环境准备先看环境。superpowers 依赖的是你本机已经有一个能跑 agentic 任务的 CLI 工具最常见的两个是 Codex CLI 和 Claude Code。这篇文章我会以 Codex 为主线来讲Claude Code 的用法大同小异区别会在后面标注。确认条件Node.js 18 以上因为 CLI 工具本身基于 Node 生态。Git 已装好安装技能包要走 git。终端里codex --version能正常输出版本号。装好 CLI 之后你需要在本地某个项目里开始试验不建议直接在系统根目录折腾。新建一个测试项目或者挑一个你熟悉的小项目后面所有操作都在这个项目里做。为什么要这么做因为技能是跟项目走的尤其是代码里的 AGENTS.md 引导文件它会告诉 Codex 这个仓库里有哪些特殊规则。如果你在根目录做实验这个引导文件的影响范围会失控Codex 会在所有项目里都尝试加载技能反而有问题。2.2 安装 superpowers 的两种方式第一种是当作插件装到 CLI 里。如果你用的是支持插件机制的版本可以直接进 CLI 的插件目录把仓库 clone 进去。以 Claude Code 的目录结构为例一般是~/.claude/plugins/在里面执行git clone https://github.com/obra/superpowers之后 CLI 启动时会自动发现技能目录。第二种是项目级安装我更推荐这种方式因为它把技能和项目绑定在一起团队成员 clone 下来就能用不用每个人都配一遍全局插件。做法是在项目根目录建一个.superpowers/目录把仓库里的 skills 子目录拷进去或者直接把整个仓库作为一个 submodule 挂到.superpowers下。结构大概是这样.superpowers/ SKILL.md skills/ planning/SKILL.md tdd/SKILL.md debugging/SKILL.md refactoring/SKILL.md这一步做完还没结束。技能目录只是原材料你得让 Codex 知道“这个项目里有技能可以用”。最稳妥的办法是在项目根目录的 AGENTS.mdCodex 的项目说明文件里写上一段本仓库启用了 superpowers 技能框架。处理任务前先读取 .superpowers/SKILL.md 和 .superpowers/skills/ 目录下的技能列表根据任务类型选择合适的技能并在执行过程中严格遵循技能内定义的步骤。这段提示是连线AGENTS.md 是 Codex 每次启动都会读的项目上下文你在这里告诉它技能的存在它才会在后续任务里主动去翻技能库。如果这一步漏了技能文件装得再多AI 也只会当一个普通的隐藏目录完全不会主动去碰。2.3 验证安装是否生效装完别急着写业务代码先做一个验证。打开终端进到项目目录启动 Codex让它做一件简单的事“请读取项目里的技能清单告诉我你可以使用哪些技能以及每个技能大概会在什么场景下使用。”如果安装成功它会列出 planning、tdd、debugging 这些技能并且能简单描述各自的适用场景。如果它说“没找到相关文件”优先检查.superpowers目录是不是被放到了项目根目录注意别放进src或子目录里。AGENTS.md 里的那段话是不是真的被 Codex 读到了。你可以故意在项目里留一个 TODO 注释然后问它项目上下文里有什么。我第一次装的时候就是放错了目录把技能库 clone 到了~/.codex下结果 Codex 在项目里完全感知不到排查半天才发现是路径问题。这类问题很典型不是工具没装而是它没有被放在“AI 能看到的位置”。所以验证这一步别省五分钟能省下后面一整天的困惑。3. 核心用法让技能在真实项目中跑起来3.1 从“帮你写代码”到“先给你一份作战计划”装好之后我第一次真正“被震撼”到是让 Codex 实现一个稍微复杂一点的需求给现有的博客系统加一个标签聚合页面。放在以前它会直接撸起袖子开始改模板、加路由、写查询语句一气呵成然后大概率在某一步改坏。但那次它在读取了 planning 技能之后回复的开头变成这样“我先用 planning 技能整理一下这个任务涉及入口路由、数据库查询、模板渲染、缓存清理步骤排序为……第一步建路由和查询接口第二步写模板第三步补测试风险点是标签数据量变大之后的索引问题我会在查询里先做优化并加一个覆盖测试。”这不是我 prompt 里写的是 planning 技能教会它的。它先拆解问题、列出步骤、排优先级、标注风险然后才开始动手。整个过程我可以随时叫停、调整步骤顺序而不是等它写完几百行代码之后才发现方向错了。这个变化对“AI 写代码”这个场景是质变我不是在检查一个结果而是在审查一个过程。后面我养成了一个习惯只要任务稍微复杂一点我都会先跟 Codex 说一句“先按 planning 流程走”。它会严格地输出一个 Plan我再把 Plan 确认一遍它才开始执行。这一来一回比让它直接改代码慢个两三分钟但省下的返工时间往往是几倍。尤其是涉及多个文件联动的功能没有计划直接动手几乎是必出事。3.2 TDD 技能测试先行怎么落地如果说 planning 解决的是“先想清楚再做”tdd 技能解决的是“做的时候每一步都稳”。这个技能的核心逻辑就是我们熟知的 red-green-refactor但它要求 AI 严格遵守顺序先写一个会失败的测试确认测试失败是因为“功能还没实现”而不是因为“测试本身写得有问题”然后再写最少量的实现代码让测试变绿最后才做重构。我实际跑下来的体会是AI 对“先写测试”这个要求执行得比人还严格。有次我让它给一个日期工具类加一个“判断是否工作日”的方法它居然先写了几个边界用例周一返回 true、周末返回 false、法定节假日怎么办、空参数怎么处理。它在测试用例里把异常分支都列出来了然后才去写实现。这个习惯很重要尤其当项目里测试覆盖率一直提不上来的时候。让 AI 先写测试覆盖率会随着功能代码一起补上来而不是写完功能之后靠人去追着补测试。如果你项目里的规矩就是“必须有测试才能合入代码”这个技能能直接帮你把流程规范化。我还有另一个感受一旦 AI 养成了“测试先行”的习惯它自己写出的代码会明显更内聚因为它需要让每个小行为都能被测试捕获自然就会减少藏着掖着的隐含逻辑。3.3 调试与重构技能调试和重构是我最开始没太在意的两个技能用多了之后发现它们才是“防止 AI 把项目改烂”的关键。调试技能的执行方法是反直觉的它不允许 AI 一上来就改代码而是要求它先复现问题、收集证据、定位根因再把问题变成一个新的失败测试修复之后用这个测试来防回归。听起来像是人肉 debug 的标准流程但 AI 默认不会这么做。它更倾向于“看到报错直接改”运气好改对了运气不好打了一堆补丁代码越来越乱。debugging 技能就是来治这个毛病的。refactoring 技能则更像一道保险它要求 AI 在重构过程中始终保持行为不变并且每一步都允许运行测试来验证。我拿它重构过一个老项目的核心工具类AI 在重构完一个方法之后主动跑了一遍测试并且停下来告诉我“这一步重构后有一个测试依赖了旧方法名我需要先改调用方再继续”。这个细致程度在没有技能约束的时候是很少见的。我第一次用 refactoring 技能重构一段耗时很长的 SQL 拼接代码时AI 没有一次性把所有逻辑重写而是先提取了一个常量再抽了一个方法最后才调整了拼接顺序。每一步之间都保持可编译、可测试。当时的感受是它不像在“写代码”更像一个谨慎的老工程师在小心翼翼地动别人的代码。4. Java 场景superpowers 在 Java 项目里的实战4.1 为什么 Java 项目更需要技能约束很多人搜 superpowers java是因为 Java 项目用 AI 编程助手的时候痛点格外明显。原因不难理解Java 项目通常结构重、构建链路长一个需求要动 Controller、Service、Repository、实体类、Mapper XML、pom 依赖AI 很容易中途迷失再加上 Maven/Gradle 编译和测试跑得慢AI 一旦在不该动的地方改出问题发现成本很高。更现实的一点是Java 老项目普遍有历史包袱命名不统一、测试缺失、模块依赖混乱。AI 在这种项目里默认发挥会很拉胯因为它学到的“一般 Java 写法”和项目里的“实际 Java 写法”经常对不上。而技能框架正好能把项目的特殊规矩写进去让 AI 按你的规矩来而不是按训练数据里的“通用最佳实践”来。举个小例子很多 Java 项目的单元测试约定是Service 层用 Mockito mock 掉 Repository不碰数据库集成测试才走真实数据库。默认状态下的 AI 经常会顺手写一个带 SpringBootTest 的测试把整个上下文都拉起来。如果你在技能里写清楚“单元测试不许启动 Spring 上下文”它就会老老实实写 mock 型测试跑测试的速度直接快一个数量级。4.2 在 Java 项目中安装和启用技能Java 项目里启用 superpowers 的步骤和前面讲的通用安装基本一样但有几个细节要注意。第一技能目录建议放进项目根目录并且提交到 Git。对于团队协作来说每个成员 clone 之后天然就带上了技能不需要各自配置。如果你不想让技能文件污染仓库用 submodule 或者直接拷进.superpowers也是可行的看团队习惯。我个人建议提交到仓库里因为技能文件本质上是文档它记录了团队的工作流跟 README 是一样的性质。第二AGENTS.md 里的引导语要写得跟 Java 技术栈相关。比如这样本仓库为 Maven 多模块 Java 项目。启用 superpowers 技能框架。任务开始前先读取 .superpowers/SKILL.md若任务涉及新功能开发必须使用 tdd 技能先编写 JUnit 5 测试涉及依赖调整时先修改对应模块的 pom.xml并在最终跑完mvn -q test后再结束任务。这段描述比通用提示更有用因为它把 Java 项目特有的动作改 pom、跑 Maven 测试也并入了 AI 的流程里。实际效果是AI 改完代码不会直接说“完成了”而是真的去跑一遍mvn test并且把失败信息贴回来。这相当于把“最后跑一次全量测试”的验收动作固化进了 AI 的交付标准。第三Java 技能可以自己定制。比如把 Mockito 的使用规范写进一个技能的 SKILL.mdAI 在写单元测试时就会优先用 given-when-then 结构而不是随机发挥。这个定制成本很低但收益很高适合团队逐步沉淀。我见过有团队把 Lombok 的使用限制、MapStruct 的生成路径、甚至 Git commit 消息格式都写进了技能AI 的产出风格会越来越贴近团队既有代码。4.3 实战体验一个 Spring Boot 小功能拿我自己做过的一个例子来讲。项目是一个 Spring Boot 的订单服务需求是给订单查询接口加一个“按用户 ID 和时间范围过滤”的能力。如果按老套路让 Codex 直接干它大概率会先找到 Controller然后顺着往下改 Service、Mapper最后补几个测试就算完事。启用技能之后它的流程变成了这样先读取 planning 技能列出改动路径再调用 tdd 技能在动手改代码前先写了 OrderQueryServiceTest设计了“空的用户 ID 抛异常”“时间范围跨月查询返回正确结果”“无条件查询时不分页”这几个用例然后才去改 Service 实现和 SQL 映射最后跑 Maven 测试等全部通过之后又调用了 code-review 技能对照检查清单看了一遍自己的 diff提了一个“分页参数建议放到请求参数里而不是写死在 SQL 里”的优化点。整个过程我基本只在旁边看着偶尔对它的 Plan 说“这块没必要做”。代码量虽然和以前差不多但质量明显更可控了测试先行意味着每个改动都有验证计划先行意味着没有“写着写着发现需要回滚”的情况。这里面最让我满意的是它主动提的那个分页优化建议——不是让我去改而是它识别出这个改动会越出任务边界于是明确标出来提醒我决策。这种“知道自己能做什么、不该做什么”的边界感正是技能约束带来的。5. 常见问题与排查技巧实录5.1 技能没被加载怎么办这是最多人踩的坑。症状一般是明明装好了技能库但 Codex 回答问题时完全不提技能、不按流程走。我之前讲过的路径问题是一类原因另一类更隐蔽的原因是AGENTS.md 的引导语写得不够明确AI 读了但没理解“这是一个可以按需加载技能的项目”。我的排查顺序是先直接问 AI“你能读取项目里的 .superpowers 目录吗里面有哪些技能”这一步能确认它有没有感知到技能文件的存在。如果它说没找到检查目录位置确保.superpowers在项目根目录。如果它找到了但没有使用回去把 AGENTS.md 的引导语改得更“硬”直接写明“处理任务前必须检查技能清单严禁跳过”。还不行就在当前会话里手动让它加载把 SKILL.md 的路径贴给它并让它读完再开始任务。不要觉得这个流程麻烦。技能框架本身是“懒加载”的AI 默认不会主动翻文件引导语写得越明确它的主动性越高。实测下来“必须”“严禁”这类强约束词汇比“可以”“建议”有效得多因为 AGENTS.md 里的措辞会被模型当成规范而非候选方案。5.2 技能和项目现有规范冲突怎么办有时候不是技能没用而是技能和项目现实矛盾。比如团队习惯先写实现后补测试而 tdd 技能要求测试先行项目根本没有测试基础设施让 AI 先写测试等于先搭一套框架成本很高又比如规划流程里要求的多步审批在个人项目里完全是浪费。遇到这种情况我的建议是不要硬套。技能库的目录结构允许你按需启用用不到的技能可以直接不放进项目或者写一个项目级的覆盖技能把团队自己的流程写进去。它不是宗教仪式而是一套“流程的知识库”你的团队怎么干活就应该怎么配置。我自己到了新项目第一件事永远是删掉用不上的技能只留 planning、tdd、debugging 这几个核心项。如果你发现技能本身没问题但和 AGENTS.md 里的其他规则产生了冲突以 AGENTS.md 为准。我在一个项目里同时定义了“新功能必须走 tdd”和“紧急修复可跳过测试”两条规则结果 AI 每次都要纠结一下到底该走哪条。后来我把规则改成“紧急修复必须注明原因且事后补测试”冲突就消失了。技能文件的描述语言尽量一致可以减少模型的误解。5.3 实测性能与上下文开销最后说一个比较实际的问题技能文件会不会吃太多上下文我自己的经验是单个 SKILL.md 文件控制在 300 到 600 行为宜技能清单文件只放 name 和 description不放正文。这样 AI 每次启动只需要读一个清单不会把几百行技能正文全部加载进来。清单可能只占 1 到 2 千 token完全在可接受范围内。真正用到某个技能时才会加载它的完整正文这个开销也只在执行特定任务时出现。还有一个小建议不要把技能库当成“万能 prompt 收藏夹”。我曾经往里面堆各种规范从代码风格到 Git 提交信息格式都写进去结果技能越大AI 对核心流程的执行率反而越低。技能就像一个储物间塞太满真正要用的时候反而翻不到东西。精简到几条核心技能效果最好。我现在每个项目的技能库里通常只有 4 到 5 个技能每个文件聚焦一件事。另外实测时我发现技能的正文结构也有讲究。最有效的是“场景判断 执行步骤 禁止事项”三段式先写什么情况下用再写具体步骤最后写不能做什么。AI 对“禁止”的理解比“应该”更到位因为负样本在指令遵循场景里往往更明确。技能正文里如果只有空泛的原则AI 执行起来会大打折扣。最后再分享一个小技巧技能里可以写“完成后向用户汇报时必须附带测试结果”这一句话能省你很多确认时间。我以前每次都要追问“测试跑了吗”加了这条之后Codex 会主动在回复里带上测试输出。整个使用体验一下子就从“监督 AI 干活”变成了“验收 AI 的交付物”。