写这篇东西的动机得从一次让我有点烦躁的调试经历说起。我一直在用 Codex CLI 这类终端里的编程助手处理日常开发尤其是维护几个老项目的时候它能帮我省不少敲代码的时间。但用久了你会发现一个尴尬的问题同一个模型同一套上下文你换个问法它给你的代码质量能差出一大截。有时候它一上来就大刀阔斧改结构有时候又只顾着补眼前的小漏洞完全没有通盘考虑。问题不在模型本身而在于我们缺少一套稳定的、可复用的工作方法来约束它。后来我接触到了 superpowers 这个技能包简单说它就是一套给 Codex CLI 这类编码代理准备的工作手册集合。它不给你写具体业务代码而是告诉你拿到任务后先干什么、再干什么、遇到报错怎么查、写测试要覆盖哪些场景。这篇文章我就围绕 superpowers 是什么、怎么装、日常怎么用、在 Java 项目里怎么落地这几个问题展开把我实际跑通的流程和踩过的坑都写出来。想解决AI 写代码时灵时不灵问题的朋友可以仔细看看后面的内容。1. superpowers 的核心价值与其调提示词不如定工作流程先说清楚一个很多人没意识到的事实让 AI 编程助手输出稳定高质量代码本质上不是一次性的提示词工程而是流程管理。你写再长的 prompt也只是一次性的约束但项目是多轮对话、多次修改、持续演进的过程。单次对话里模型表现得再聪明换个任务、换个文件、隔几天再回来它又失忆了。superpowers 解决的恰恰是这个痛点。1.1 为什么编码 AI 需要技能而不是话术我在早期使用 Codex CLI 时习惯在每次对话开头写一大段请扮演资深工程师注意代码规范务必写单元测试之类的提示。刚开始确实有效但很快就发现三件事。第一这段提示浪费 tokens。每次对话都要重复一遍长项目跑到后面上下文窗口被这些重复指令挤占真正留给代码和报错信息的空间就少了。第二模型对务必写单元测试这种模糊要求的执行力不稳定。你说务必它能给你写出一个叫test_开头的空壳函数就算交差。第三每个人写提示的风格不一样换个人接手项目整套约束就失效了。superpowers 的做法完全不同它把资深工程师的思考过程拆成一个个独立的技能文件每个文件用 Markdown 写清楚一个场景下的完整行动指南。你在项目里需要用哪个技能就明确引用哪个文件。这相当于给 AI 一份岗位操作手册而不是一句好好干。1.2 技能文件的工作原理以 Markdown 构建操作手册superpowers 的技能文件本质上是一组结构化的指令文档。每个文件通常包含几个固定模块技能的目标、适用场景、完整操作步骤、关键检查清单以及典型的输出格式。我举个具体的例子。一个典型的plan.md技能文件会告诉模型拿到需求后第一步先列出所有已知信息第二步标记不确定的问题不要急着写代码第三步输出一个包含文件改动清单、函数级修改描述、测试策略的完整计划最后一步才是询问用户是否批准这个计划。你看这些内容本来就是一个资深工程师拿到需求后脑子里过的流程superpowers 把它变成了显式的、模型每一步都必须遵守的规则。这样做的好处非常直接模型不再自由发挥了它的思考路径被限制在一个合理的框架内。就像你把一个天才棋手塞进一套固定的开局库他可能觉得受约束但至少不会在开局就走出昏招。1.3 它与普通提示的最大区别在哪里普通提示是一次性的技能包是结构化的、持久的、可组合的。我用一个表格来说明它们之间的差异。对比维度普通提示词superpowers 技能文件生效范围仅当前对话项目内跨会话持续引用是否结构化自由文本无固定步骤分步骤、带检查清单、有输出格式约束可复用性每个任务都要重新写给一次安装多个技能场景复用对模型的约束力弱靠措辞引导强模型会被要求按流程输出中间产物团队标准化依赖个人表达能力文件入库团队统一我实际用下来最大的感受是superpowers 不是让 AI 变得更聪明而是让 AI 的行为变得更可预测。它牺牲了一部分灵光一闪的可能性但换来了最少不犯错的底线。在做老项目维护、批量重构、跨模块调试这类脏活累活时可预测性比发挥更重要。2. 安装与第一个可用 Demo三十分钟跑起来光说不练假把式。这一节我直接讲怎么把 superpowers 装进你的工作流并用一个最小项目验证它生效了。2.1 环境准备与版本检查安装之前先确认三样东西你的终端里已经装好了 Codex CLI 并且能正常对话你的系统里有 Git你的项目目录结构是干净的。这里有个容易忽略的点Codex CLI 的版本不能太老。技能文件引用机制依赖它较新版本对自定义指令目录的支持。我自己就踩过这个坑起先用的一个几个月前装的老版本技能文件怎么配都不生效升级之后问题立刻消失。建议你先跑一下版本检查如果低于 v0.14这是我测试时的稳定版本先升级到最新版再继续。codex --version如果你还没装 Codex CLI安装其实就是一条命令的事。官方推荐的方式是直接通过 npm 全局安装npm install -g openai/codex装完后随便在终端里问它一句你好确认基础对话能通再回来继续。2.2 获取 superpowers 技能包并放进项目获取技能包的方式有很多最省事的是直接到 GitHub 上搜superpowers skills找到对应的仓库把它 clone 到本地。然后关键的一步来了在项目根目录创建一个.codex文件夹再把技能文件放进去。我建议的目录布局长这样your-project/ ├── .codex/ │ ├── skills/ │ │ ├── plan.md │ │ ├── code.md │ │ ├── debug.md │ │ └── test.md │ └── AGENTS.md ├── src/ └── tests/这里面的AGENTS.md是 Codex CLI 的项目级指令文件它会在每次会话开始前被自动加载。我会在AGENTS.md里写一行总规则告诉模型遇到复杂任务时必须先从 skills 目录选择对应的技能文件加载再开始动手。这样一来不需要每次对话都手动引用技能。还要提一个细节技能文件不用一股脑全塞进去。我一开始把仓库里几十个技能文件全复制进项目结果每次读上下文都要扫一遍这些文件既浪费 tokens 又容易让模型选择困难。后来我只保留了和自己工作流最相关的四五个效果反而更稳定。2.3 第一轮验证看 AI 是否按流程走配置完成后用一个简单任务验证技能是否生效。我当时的测试任务是让 AI 帮我重构一个 Python 工具脚本把里面一个 200 行的函数拆成几个小函数。关键要看模型的表现有没有发生三个变化第一它不再立刻甩出代码而是先输出一个简单的计划列出改动文件和步骤第二它在动手前先问了我几个问题比如这个函数有没有其他调用方期望的返回结构是不是要保持不变第三代码完成后它主动给了一段验证建议而不是丢下一堆代码就不管了。如果这三个变化都出现了说明技能文件已经被正确加载并且发挥了作用。如果模型还是老样子直接写代码不要急着怀疑是技能包的问题先检查AGENTS.md里的规则是不是写得太软了比如可以考虑使用这种语气肯定不行要用必须和在第一步这种强约束词。3. 从安装到上瘾我把 superpowers 的日常使用流程彻底重构了装好只是开始真正让效率上台阶的是把它嵌入日常开发流程。这一节我不讲理论直接给实操讲清楚我在计划、编程、调试三个环节分别引用了哪些技能以及它们如何改变了我的工作方式。3.1 计划技能动手之前先建立作战地图以前我用 AI 写代码基本都是需求扔过去代码扔回来遇到复杂功能经常要来回改四五轮甚至推翻重来。superpowers 的plan.md技能彻底改变了这个循环。它要求模型在收到一个复杂需求时先不要碰代码而是执行一系列规划动作列出所有已知的业务要求和约束条件明确列出需要向用户确认的模糊点优先级从高到低排好基于确认结果输出完整的实施计划包括待改动文件、每个文件里要动哪些函数、依赖关系是怎样的先让用户确认计划批准之后再进入编码阶段。我在实际项目中用下来这种先讨论再动手的模式至少省掉了一半的返工。特别是涉及跨模块改动的时候AI 先把它想动的文件列出来我一眼就能发现某些模块根本不该碰及时止损。如果你想跳过这一步结果大概率是它把无关模块的逻辑也给你优化了那才是真正的灾难。3.2 编程技能测试先行与一次只做一件事编程技能是我日常使用频率最高的一个。code.md技能文件里包含了几条对我帮助极大的约束。第一条是测试先行在写业务代码之前先写测试用例或至少描述清楚验证指标。这里不是让所有场景都严格遵守 TDD而是让模型在开工前对做完的标准有明确认知。模型写代码时如果没有测试概念经常是看起来逻辑通就交差了但一跑测试就露馅。先写测试等于给后续代码套上了缰绳。第二条是一次只做一件事技能文件要求模型在一次请求里只聚焦一个功能点不要顺手重构无关代码不要顺手改格式不要顺手升级依赖。这条看起来简单实际是 AI 编码中最难约束的行为。本来只是加一个字段它可能顺带把整个文件改成新语法、给每个函数加了注释、还调整了导入顺序导致 review 变得极其困难。技能文件用硬性规定把这种顺手行为关掉了。3.3 调试技能面对报错的系统性思维模式debug.md是我建议所有使用者第二个必须安装的技能它解决的是 AI 调试时拆东墙补西墙的通病。默认情况下AI 遇到报错会这样处理读一下报错信息猜测一个可能的原因直接改代码再跑一次。如果不行再猜再改。这种试错法在简单场景下有效但在复杂系统里就是灾难因为每个修复都可能引入新的隐性 Bug。调试技能给模型的约束是先复现再假设再验证假设最后才修改。完整的流程是第一步复现问题记录稳定的复现路径第二步提出至少两个以上可能的成因假设第三步用日志、断点或最小化测试去验证哪个假设成立第四步针对验证过的原因做最小修改第五步跑完整回归确认没有引入新问题。这套流程本质上就是专业开发者调试时的标准动作。把它交给模型后它不再猜答案而是像实习生一样按流程走虽然速度会慢一点但结果是可控的这比跑得快但经常跑偏实用得多。4. 在 Java 项目里实测从泛化能力到定制改造很多用 Java 做后端开发的读者可能已经不耐烦了前面讲的都是通用流程Java 项目到底能不能用答案是可以但它需要一些针对性调整。我专门拿一个 Spring Boot 微服务项目实测了一轮这节把我的操作和观察到的现象完整分享出来。4.1 Java 项目给 AI 编码带来的特殊挑战Java 项目和其他语言相比有几个对 AI 编码不太友好的特性不解决好技能包再强也白搭。第一个是项目结构复杂。标准的 Maven 或 Gradle 工程有src/main/java、src/test/java、src/main/resources等多级目录加上pom.xml或build.gradle里的依赖管理。技能文件里的通用步骤必须结合这个目录结构才有意义。第二个是类型系统带来的上下文负担。Java 的强类型意味着一个方法签名里可能牵扯到好几个自定义类型AI 在一个文件里改代码往往需要同时理解四五个关联类。这在泛化技能里并没有针对性处理需要在定制时补充。第三个是框架约定大于配置。Spring 项目里 Bean 的生命周期、依赖注入方式、AOP 切面、事务传播机制这些潜规则模型不一定能完全遵守。它可能会写出一个看起来没问题的 Controller但实际上没被 Spring 扫描到。第四个是构建工具的繁琐性。改完代码要重新编译、跑测试如果只是在终端里让 AI 改代码它往往不会自动处理 Maven 生命周期。这些流程需要被显式写进技能文件。4.2 我在一个 Spring Boot 服务里实际跑通的操作流我选的项目是一个订单服务里面有标准的 Controller、Service、Mapper 三层结构。我给它下了一个需求新增一个查询用户本月累计订单金额的接口。在未配置技能包的情况下AI 的第一版响应是直接在 Controller 里写了一个方法Service 里加了一个对应实现然后告诉我完成了。问题在于它没有查这个需求是否涉及表索引、没有考虑金额精度用BigDecimal、没有写测试甚至也没检查 Service 是否已经存在类似方法。这种回复看起来很快但离可上线的标准差得很远。用上 superpowers 之后整个流程明显不同。plan.md技能首先让它列出问题清单包括金额精度类型确认是否需要对空结果做兜底接口返回 DTO 是否需要兼容旧字段。这些都是我自己可能还没想到的细节。确认完计划后code.md技能让它先写了断言完整的单元测试用 Mockito 模拟 Mapper 层返回。测试写完才动手写实现代码最后还主动要求我提供pom.xml里的测试配置来跑 Maven 验证。整个过程下来代码质量对得起资深工程师的评价而且每一轮都有中间产物我能随时介入纠正方向。这就是定制技能与裸用模型最本质的区别。4.3 给 Java 项目定制技能文件的几个方向原版的通用技能文件偏重流程对 Java 生态的具体约束不足。我在实际使用中给项目加了一个java-spring.md技能文件专门补充 Java 项目相关的规则。这里分享几个我觉得最有价值的补充条目你可以直接抄进自己的技能文件里。首先是代码风格约束。Java 项目通常有既有代码风格比如 Lombok 的使用习惯、异常处理是抛自定义异常还是返回 Result 包装类、日志用 Slf4j 还是 Log4j2。这些必须在技能文件里写明因为模型默认倾向于每种风格都来一点。其次是依赖与构建约束。技能文件里我明确要求涉及新依赖时先检查pom.xml是否已存在修改pom.xml后必须同步检查mvn dependency:tree是否有冲突所有修改交付前必须至少跑一次mvn -q test。再就是 Spring 特有规则的强制化。比如所有Service类必须面向接口编程、Transactional不能直接加在 Controller 上、Controller 层不允许出现业务逻辑。最后是命名与包结构约束。Java 项目对命名规范很敏感技能文件里可以规定新增类的包路径必须以项目根包开头、工具方法必须放在util包、不得在entity包里写业务逻辑。定制技能文件看上去是在束缚 AI实际上是在把你的项目规范固化成机器可执行的规则。换个角度来看这比在新人入职时反复口头强调规范要高效得多。5. 不是银弹superpowers 的局限、故障排查与我的使用建议写到这里要泼一盆冷水了。superpowers 确实让我的 AI 编码体验有了质的变化但它不是银弹也有明显的适用范围和边界。这节把我在真实项目里踩过的坑和摸索出的经验完整摆出来省得你再走弯路。5.1 哪些场景下我不建议为了用而用第一类场景是纯探索型的代码任务。比如你想验证某个第三方库 API 怎么调用或者临时写个脚本处理一份数据这种任务本身没有复杂的业务约束也不需要多轮重构。套上技能流程反而显得笨重模型被要求先输出计划、再确认、再写测试等它走完流程你手写早就跑通了。第二类场景是大型老项目的全局性重构。技能文件里的步骤再详细也不可能覆盖一个几十万行老项目里隐含的历史包袱。这种场景下AI 做的每一步都需要频繁人工介入确认技能包并不能显著减少工作量反而会因为流程繁琐拖慢节奏。第三类场景是需求描述极度模糊的早期探索。如果产品需求连你自己都没想清楚工具里的计划确认环节就会变成AI 问你答的无限循环。技能包假设你有一个相对明确的目标它的作用是约束执行过程而不是帮你完成需求分析。5.2 常见故障排除技能文件不生效时排查链路如果你按我的步骤配置完后发现模型根本不按流程走不要急着怀疑 skill 格式不对大概率是下面这几个地方出了问题。我整理了一张排查表你可以按顺序逐个检查。现象优先排查项处理方式模型完全不提技能文件AGENTS.md规则语气太弱改成明确指令必须先加载对应技能再动手技能文件加载了但不执行步骤技能文件本身写得不够强约束检查文件里是否用了应该这类模糊词全部改成必须只有部分技能生效目录层级不对确认技能文件放在.codex/skills/下检查大小写技能生效但输出质量差上下文挤占精简技能文件数量只保留当前任务相关的升级 CLI 后行为变化版本兼容性查看更新日志确认自定义指令目录配置是否变了我在实际项目里最常遇到的是第一种也就是AGENTS.md写得太客气。比如我最初写的是可以考虑参考 skills 目录中的技能文件模型基本无视。改成在响应任何复杂任务前你必须阅读并遵循 skills 目录中的相关技能文件之后立刻生效。记住对模型提要求语气上的确定性非常关键。5.3 我的实际工作方式如何让技能包长期保持有效最后分享几条我长期使用后总结的经验这些属于常规文档里不会写的部分。第一技能文件要随项目演进定期迭代。我会在每个迭代结束后把当次项目中反复出现的问题写进技能文件。比如某次发现模型频繁忘记处理 DTO 字段转换我就在code.md里加了一条所有接口新增字段时必须同步检查对应 DTO 和 VO 的转换逻辑。经过几轮迭代技能文件会越来越贴近你的项目实际。第二给技能文件增加版本记录。我会在文件末尾用一个注释块记录2025-01-20 新增字段转换检查规则。这样做的好处是当模型输出行为发生变化时你能快速定位是哪个规则的修改导致的。第三不要把技能文件直接 fork 自官方仓库然后永远不动。仓库里的技能是通用标准你的项目才是特殊场景。至少要在通用技能之上叠加一个项目自己的技能文件把项目独有的规范固化进去。第四留意上下文长度。技能文件本身要控制篇幅单个技能文件最好限制在 100 行左右。超过这个长度模型在长对话后期容易忽略文件后半部分的内容。宁可拆成多个小技能文件也不要写一个又臭又长的大文件。第五和团队协作时把技能文件纳入代码审查范围。技能文件的每一行都直接影响 AI 的产出团队里任何人都可以提修改意见。这相当于是把团队的最佳实践沉淀到了机器可读的规则里价值不亚于任何一份设计文档。写到这里我想起刚配置完 superpowers 那天晚上我盯着 Codex CLI 输出的那份完整实施计划突然有一种很奇妙的体验原来让 AI 写代码这事儿关键真的不只是模型强不强而是你有没有给它一套像样的工作方法。模型还是那个模型但产出的稳定性和可维护性完全不一样了。我现在的习惯是每接一个新项目第一件事不是搭代码框架而是先把技能包配置好把项目规范写进技能文件。这套流程我已经用了挺长时间省下来的返工时间非常可观。如果你也在用 Codex CLI 或者其他终端编程助手建议你也试一次装好技能包跑一个最小任务对比看看——大概率会有惊喜。
superpowers技能包如何让Codex CLI输出稳定代码
写这篇东西的动机得从一次让我有点烦躁的调试经历说起。我一直在用 Codex CLI 这类终端里的编程助手处理日常开发尤其是维护几个老项目的时候它能帮我省不少敲代码的时间。但用久了你会发现一个尴尬的问题同一个模型同一套上下文你换个问法它给你的代码质量能差出一大截。有时候它一上来就大刀阔斧改结构有时候又只顾着补眼前的小漏洞完全没有通盘考虑。问题不在模型本身而在于我们缺少一套稳定的、可复用的工作方法来约束它。后来我接触到了 superpowers 这个技能包简单说它就是一套给 Codex CLI 这类编码代理准备的工作手册集合。它不给你写具体业务代码而是告诉你拿到任务后先干什么、再干什么、遇到报错怎么查、写测试要覆盖哪些场景。这篇文章我就围绕 superpowers 是什么、怎么装、日常怎么用、在 Java 项目里怎么落地这几个问题展开把我实际跑通的流程和踩过的坑都写出来。想解决AI 写代码时灵时不灵问题的朋友可以仔细看看后面的内容。1. superpowers 的核心价值与其调提示词不如定工作流程先说清楚一个很多人没意识到的事实让 AI 编程助手输出稳定高质量代码本质上不是一次性的提示词工程而是流程管理。你写再长的 prompt也只是一次性的约束但项目是多轮对话、多次修改、持续演进的过程。单次对话里模型表现得再聪明换个任务、换个文件、隔几天再回来它又失忆了。superpowers 解决的恰恰是这个痛点。1.1 为什么编码 AI 需要技能而不是话术我在早期使用 Codex CLI 时习惯在每次对话开头写一大段请扮演资深工程师注意代码规范务必写单元测试之类的提示。刚开始确实有效但很快就发现三件事。第一这段提示浪费 tokens。每次对话都要重复一遍长项目跑到后面上下文窗口被这些重复指令挤占真正留给代码和报错信息的空间就少了。第二模型对务必写单元测试这种模糊要求的执行力不稳定。你说务必它能给你写出一个叫test_开头的空壳函数就算交差。第三每个人写提示的风格不一样换个人接手项目整套约束就失效了。superpowers 的做法完全不同它把资深工程师的思考过程拆成一个个独立的技能文件每个文件用 Markdown 写清楚一个场景下的完整行动指南。你在项目里需要用哪个技能就明确引用哪个文件。这相当于给 AI 一份岗位操作手册而不是一句好好干。1.2 技能文件的工作原理以 Markdown 构建操作手册superpowers 的技能文件本质上是一组结构化的指令文档。每个文件通常包含几个固定模块技能的目标、适用场景、完整操作步骤、关键检查清单以及典型的输出格式。我举个具体的例子。一个典型的plan.md技能文件会告诉模型拿到需求后第一步先列出所有已知信息第二步标记不确定的问题不要急着写代码第三步输出一个包含文件改动清单、函数级修改描述、测试策略的完整计划最后一步才是询问用户是否批准这个计划。你看这些内容本来就是一个资深工程师拿到需求后脑子里过的流程superpowers 把它变成了显式的、模型每一步都必须遵守的规则。这样做的好处非常直接模型不再自由发挥了它的思考路径被限制在一个合理的框架内。就像你把一个天才棋手塞进一套固定的开局库他可能觉得受约束但至少不会在开局就走出昏招。1.3 它与普通提示的最大区别在哪里普通提示是一次性的技能包是结构化的、持久的、可组合的。我用一个表格来说明它们之间的差异。对比维度普通提示词superpowers 技能文件生效范围仅当前对话项目内跨会话持续引用是否结构化自由文本无固定步骤分步骤、带检查清单、有输出格式约束可复用性每个任务都要重新写给一次安装多个技能场景复用对模型的约束力弱靠措辞引导强模型会被要求按流程输出中间产物团队标准化依赖个人表达能力文件入库团队统一我实际用下来最大的感受是superpowers 不是让 AI 变得更聪明而是让 AI 的行为变得更可预测。它牺牲了一部分灵光一闪的可能性但换来了最少不犯错的底线。在做老项目维护、批量重构、跨模块调试这类脏活累活时可预测性比发挥更重要。2. 安装与第一个可用 Demo三十分钟跑起来光说不练假把式。这一节我直接讲怎么把 superpowers 装进你的工作流并用一个最小项目验证它生效了。2.1 环境准备与版本检查安装之前先确认三样东西你的终端里已经装好了 Codex CLI 并且能正常对话你的系统里有 Git你的项目目录结构是干净的。这里有个容易忽略的点Codex CLI 的版本不能太老。技能文件引用机制依赖它较新版本对自定义指令目录的支持。我自己就踩过这个坑起先用的一个几个月前装的老版本技能文件怎么配都不生效升级之后问题立刻消失。建议你先跑一下版本检查如果低于 v0.14这是我测试时的稳定版本先升级到最新版再继续。codex --version如果你还没装 Codex CLI安装其实就是一条命令的事。官方推荐的方式是直接通过 npm 全局安装npm install -g openai/codex装完后随便在终端里问它一句你好确认基础对话能通再回来继续。2.2 获取 superpowers 技能包并放进项目获取技能包的方式有很多最省事的是直接到 GitHub 上搜superpowers skills找到对应的仓库把它 clone 到本地。然后关键的一步来了在项目根目录创建一个.codex文件夹再把技能文件放进去。我建议的目录布局长这样your-project/ ├── .codex/ │ ├── skills/ │ │ ├── plan.md │ │ ├── code.md │ │ ├── debug.md │ │ └── test.md │ └── AGENTS.md ├── src/ └── tests/这里面的AGENTS.md是 Codex CLI 的项目级指令文件它会在每次会话开始前被自动加载。我会在AGENTS.md里写一行总规则告诉模型遇到复杂任务时必须先从 skills 目录选择对应的技能文件加载再开始动手。这样一来不需要每次对话都手动引用技能。还要提一个细节技能文件不用一股脑全塞进去。我一开始把仓库里几十个技能文件全复制进项目结果每次读上下文都要扫一遍这些文件既浪费 tokens 又容易让模型选择困难。后来我只保留了和自己工作流最相关的四五个效果反而更稳定。2.3 第一轮验证看 AI 是否按流程走配置完成后用一个简单任务验证技能是否生效。我当时的测试任务是让 AI 帮我重构一个 Python 工具脚本把里面一个 200 行的函数拆成几个小函数。关键要看模型的表现有没有发生三个变化第一它不再立刻甩出代码而是先输出一个简单的计划列出改动文件和步骤第二它在动手前先问了我几个问题比如这个函数有没有其他调用方期望的返回结构是不是要保持不变第三代码完成后它主动给了一段验证建议而不是丢下一堆代码就不管了。如果这三个变化都出现了说明技能文件已经被正确加载并且发挥了作用。如果模型还是老样子直接写代码不要急着怀疑是技能包的问题先检查AGENTS.md里的规则是不是写得太软了比如可以考虑使用这种语气肯定不行要用必须和在第一步这种强约束词。3. 从安装到上瘾我把 superpowers 的日常使用流程彻底重构了装好只是开始真正让效率上台阶的是把它嵌入日常开发流程。这一节我不讲理论直接给实操讲清楚我在计划、编程、调试三个环节分别引用了哪些技能以及它们如何改变了我的工作方式。3.1 计划技能动手之前先建立作战地图以前我用 AI 写代码基本都是需求扔过去代码扔回来遇到复杂功能经常要来回改四五轮甚至推翻重来。superpowers 的plan.md技能彻底改变了这个循环。它要求模型在收到一个复杂需求时先不要碰代码而是执行一系列规划动作列出所有已知的业务要求和约束条件明确列出需要向用户确认的模糊点优先级从高到低排好基于确认结果输出完整的实施计划包括待改动文件、每个文件里要动哪些函数、依赖关系是怎样的先让用户确认计划批准之后再进入编码阶段。我在实际项目中用下来这种先讨论再动手的模式至少省掉了一半的返工。特别是涉及跨模块改动的时候AI 先把它想动的文件列出来我一眼就能发现某些模块根本不该碰及时止损。如果你想跳过这一步结果大概率是它把无关模块的逻辑也给你优化了那才是真正的灾难。3.2 编程技能测试先行与一次只做一件事编程技能是我日常使用频率最高的一个。code.md技能文件里包含了几条对我帮助极大的约束。第一条是测试先行在写业务代码之前先写测试用例或至少描述清楚验证指标。这里不是让所有场景都严格遵守 TDD而是让模型在开工前对做完的标准有明确认知。模型写代码时如果没有测试概念经常是看起来逻辑通就交差了但一跑测试就露馅。先写测试等于给后续代码套上了缰绳。第二条是一次只做一件事技能文件要求模型在一次请求里只聚焦一个功能点不要顺手重构无关代码不要顺手改格式不要顺手升级依赖。这条看起来简单实际是 AI 编码中最难约束的行为。本来只是加一个字段它可能顺带把整个文件改成新语法、给每个函数加了注释、还调整了导入顺序导致 review 变得极其困难。技能文件用硬性规定把这种顺手行为关掉了。3.3 调试技能面对报错的系统性思维模式debug.md是我建议所有使用者第二个必须安装的技能它解决的是 AI 调试时拆东墙补西墙的通病。默认情况下AI 遇到报错会这样处理读一下报错信息猜测一个可能的原因直接改代码再跑一次。如果不行再猜再改。这种试错法在简单场景下有效但在复杂系统里就是灾难因为每个修复都可能引入新的隐性 Bug。调试技能给模型的约束是先复现再假设再验证假设最后才修改。完整的流程是第一步复现问题记录稳定的复现路径第二步提出至少两个以上可能的成因假设第三步用日志、断点或最小化测试去验证哪个假设成立第四步针对验证过的原因做最小修改第五步跑完整回归确认没有引入新问题。这套流程本质上就是专业开发者调试时的标准动作。把它交给模型后它不再猜答案而是像实习生一样按流程走虽然速度会慢一点但结果是可控的这比跑得快但经常跑偏实用得多。4. 在 Java 项目里实测从泛化能力到定制改造很多用 Java 做后端开发的读者可能已经不耐烦了前面讲的都是通用流程Java 项目到底能不能用答案是可以但它需要一些针对性调整。我专门拿一个 Spring Boot 微服务项目实测了一轮这节把我的操作和观察到的现象完整分享出来。4.1 Java 项目给 AI 编码带来的特殊挑战Java 项目和其他语言相比有几个对 AI 编码不太友好的特性不解决好技能包再强也白搭。第一个是项目结构复杂。标准的 Maven 或 Gradle 工程有src/main/java、src/test/java、src/main/resources等多级目录加上pom.xml或build.gradle里的依赖管理。技能文件里的通用步骤必须结合这个目录结构才有意义。第二个是类型系统带来的上下文负担。Java 的强类型意味着一个方法签名里可能牵扯到好几个自定义类型AI 在一个文件里改代码往往需要同时理解四五个关联类。这在泛化技能里并没有针对性处理需要在定制时补充。第三个是框架约定大于配置。Spring 项目里 Bean 的生命周期、依赖注入方式、AOP 切面、事务传播机制这些潜规则模型不一定能完全遵守。它可能会写出一个看起来没问题的 Controller但实际上没被 Spring 扫描到。第四个是构建工具的繁琐性。改完代码要重新编译、跑测试如果只是在终端里让 AI 改代码它往往不会自动处理 Maven 生命周期。这些流程需要被显式写进技能文件。4.2 我在一个 Spring Boot 服务里实际跑通的操作流我选的项目是一个订单服务里面有标准的 Controller、Service、Mapper 三层结构。我给它下了一个需求新增一个查询用户本月累计订单金额的接口。在未配置技能包的情况下AI 的第一版响应是直接在 Controller 里写了一个方法Service 里加了一个对应实现然后告诉我完成了。问题在于它没有查这个需求是否涉及表索引、没有考虑金额精度用BigDecimal、没有写测试甚至也没检查 Service 是否已经存在类似方法。这种回复看起来很快但离可上线的标准差得很远。用上 superpowers 之后整个流程明显不同。plan.md技能首先让它列出问题清单包括金额精度类型确认是否需要对空结果做兜底接口返回 DTO 是否需要兼容旧字段。这些都是我自己可能还没想到的细节。确认完计划后code.md技能让它先写了断言完整的单元测试用 Mockito 模拟 Mapper 层返回。测试写完才动手写实现代码最后还主动要求我提供pom.xml里的测试配置来跑 Maven 验证。整个过程下来代码质量对得起资深工程师的评价而且每一轮都有中间产物我能随时介入纠正方向。这就是定制技能与裸用模型最本质的区别。4.3 给 Java 项目定制技能文件的几个方向原版的通用技能文件偏重流程对 Java 生态的具体约束不足。我在实际使用中给项目加了一个java-spring.md技能文件专门补充 Java 项目相关的规则。这里分享几个我觉得最有价值的补充条目你可以直接抄进自己的技能文件里。首先是代码风格约束。Java 项目通常有既有代码风格比如 Lombok 的使用习惯、异常处理是抛自定义异常还是返回 Result 包装类、日志用 Slf4j 还是 Log4j2。这些必须在技能文件里写明因为模型默认倾向于每种风格都来一点。其次是依赖与构建约束。技能文件里我明确要求涉及新依赖时先检查pom.xml是否已存在修改pom.xml后必须同步检查mvn dependency:tree是否有冲突所有修改交付前必须至少跑一次mvn -q test。再就是 Spring 特有规则的强制化。比如所有Service类必须面向接口编程、Transactional不能直接加在 Controller 上、Controller 层不允许出现业务逻辑。最后是命名与包结构约束。Java 项目对命名规范很敏感技能文件里可以规定新增类的包路径必须以项目根包开头、工具方法必须放在util包、不得在entity包里写业务逻辑。定制技能文件看上去是在束缚 AI实际上是在把你的项目规范固化成机器可执行的规则。换个角度来看这比在新人入职时反复口头强调规范要高效得多。5. 不是银弹superpowers 的局限、故障排查与我的使用建议写到这里要泼一盆冷水了。superpowers 确实让我的 AI 编码体验有了质的变化但它不是银弹也有明显的适用范围和边界。这节把我在真实项目里踩过的坑和摸索出的经验完整摆出来省得你再走弯路。5.1 哪些场景下我不建议为了用而用第一类场景是纯探索型的代码任务。比如你想验证某个第三方库 API 怎么调用或者临时写个脚本处理一份数据这种任务本身没有复杂的业务约束也不需要多轮重构。套上技能流程反而显得笨重模型被要求先输出计划、再确认、再写测试等它走完流程你手写早就跑通了。第二类场景是大型老项目的全局性重构。技能文件里的步骤再详细也不可能覆盖一个几十万行老项目里隐含的历史包袱。这种场景下AI 做的每一步都需要频繁人工介入确认技能包并不能显著减少工作量反而会因为流程繁琐拖慢节奏。第三类场景是需求描述极度模糊的早期探索。如果产品需求连你自己都没想清楚工具里的计划确认环节就会变成AI 问你答的无限循环。技能包假设你有一个相对明确的目标它的作用是约束执行过程而不是帮你完成需求分析。5.2 常见故障排除技能文件不生效时排查链路如果你按我的步骤配置完后发现模型根本不按流程走不要急着怀疑 skill 格式不对大概率是下面这几个地方出了问题。我整理了一张排查表你可以按顺序逐个检查。现象优先排查项处理方式模型完全不提技能文件AGENTS.md规则语气太弱改成明确指令必须先加载对应技能再动手技能文件加载了但不执行步骤技能文件本身写得不够强约束检查文件里是否用了应该这类模糊词全部改成必须只有部分技能生效目录层级不对确认技能文件放在.codex/skills/下检查大小写技能生效但输出质量差上下文挤占精简技能文件数量只保留当前任务相关的升级 CLI 后行为变化版本兼容性查看更新日志确认自定义指令目录配置是否变了我在实际项目里最常遇到的是第一种也就是AGENTS.md写得太客气。比如我最初写的是可以考虑参考 skills 目录中的技能文件模型基本无视。改成在响应任何复杂任务前你必须阅读并遵循 skills 目录中的相关技能文件之后立刻生效。记住对模型提要求语气上的确定性非常关键。5.3 我的实际工作方式如何让技能包长期保持有效最后分享几条我长期使用后总结的经验这些属于常规文档里不会写的部分。第一技能文件要随项目演进定期迭代。我会在每个迭代结束后把当次项目中反复出现的问题写进技能文件。比如某次发现模型频繁忘记处理 DTO 字段转换我就在code.md里加了一条所有接口新增字段时必须同步检查对应 DTO 和 VO 的转换逻辑。经过几轮迭代技能文件会越来越贴近你的项目实际。第二给技能文件增加版本记录。我会在文件末尾用一个注释块记录2025-01-20 新增字段转换检查规则。这样做的好处是当模型输出行为发生变化时你能快速定位是哪个规则的修改导致的。第三不要把技能文件直接 fork 自官方仓库然后永远不动。仓库里的技能是通用标准你的项目才是特殊场景。至少要在通用技能之上叠加一个项目自己的技能文件把项目独有的规范固化进去。第四留意上下文长度。技能文件本身要控制篇幅单个技能文件最好限制在 100 行左右。超过这个长度模型在长对话后期容易忽略文件后半部分的内容。宁可拆成多个小技能文件也不要写一个又臭又长的大文件。第五和团队协作时把技能文件纳入代码审查范围。技能文件的每一行都直接影响 AI 的产出团队里任何人都可以提修改意见。这相当于是把团队的最佳实践沉淀到了机器可读的规则里价值不亚于任何一份设计文档。写到这里我想起刚配置完 superpowers 那天晚上我盯着 Codex CLI 输出的那份完整实施计划突然有一种很奇妙的体验原来让 AI 写代码这事儿关键真的不只是模型强不强而是你有没有给它一套像样的工作方法。模型还是那个模型但产出的稳定性和可维护性完全不一样了。我现在的习惯是每接一个新项目第一件事不是搭代码框架而是先把技能包配置好把项目规范写进技能文件。这套流程我已经用了挺长时间省下来的返工时间非常可观。如果你也在用 Codex CLI 或者其他终端编程助手建议你也试一次装好技能包跑一个最小任务对比看看——大概率会有惊喜。