写这篇东西的动机，得从一次让我有点烦躁的调试经历说起。我一直在用 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 或者其他终端编程助手，建议你也试一次，装好技能包，跑一个最小任务对比看看——大概率会有惊喜。
