最近一直在折腾如何把 AI 编程代理真正用进日常开发，尤其是把 Codex 接进我那堆老旧的 Java 项目里。一开始裸跑 Codex 的效果说实话挺尴尬，它在小项目上很惊艳，一旦面对多模块工程就频频失控，改一个方法能顺便把不相关的代码也动了。后来朋友给我推荐了 superpowers，说是能给 Codex 装上“超能力”。我用了两周之后，终于明白这个名字不是在吹牛。这篇文章就把我对 superpowers 的理解、安装配置、实际用法和踩过的坑完整记录下来，希望能给正打算在 Codex 上做深度定制的朋友省点弯路。
先说清楚这个东西能解决什么问题：如果你觉得 AI 编程助手“给的代码像样但没灵魂”、动不动就自作主张重构、看不懂项目里真正影响全局的那几个核心类，那么 superpowers 就是拿来治这些毛病的。它适合已经用过 Codex、Cursor 这类 AI 编程工具但感觉上限锁死的开发者，也适合想在团队里统一一套 AI 协作工作流的人。这套工具本身不复杂，但一旦配好，它能让你用一套可控、可复现、可迁移的“技能包”去驱动 Codex，而不是每次全靠自然语言临场发挥。
1. superpowers到底是个什么东西
1.1 它不是另一个IDE，而是一套“能力增强层”
很多人第一次听到 superpowers 会误以为它是一个新的编程 IDE，或者某种代码生成引擎。我在安装之前也是这么想的，所以第一次跑完初始化脚本之后愣了半天——它没有炫酷的界面，没有快捷键面板，只是在你的项目目录里生成了一堆配置文件和技能脚本。具体来说，superpowers 是一套运行在 Codex CLI 之上的工作流增强层，本质上是把你在开发中的“隐式经验”显式化为规则、模板和指令集。它通过预设的技能包（skills）、上下文扫描器（scanner）和任务调度脚本，让 Codex 在动手前先理解项目的边界、约束和优先级。
用生活里的例子来理解：裸 Codex 就像一位业务能力强但完全不懂公司潜规则的新员工，你告诉它“写一个订单状态机”，它能写出来，但很可能写出一个完全不符合现有架构风格的状态机，因为它没有读过你们的历史代码、不知道哪些目录是不能动的、也不知道团队约定里的异常处理规范。superpowers 相当于给这位新员工做了三天入职培训，把公司红线、代码风格、常用模式、需要避开的雷区全部整理成手册，之后它再干活就会聪明得多。
这套工具的核心设计哲学是“控制权仍在开发者手里”。superpowers 不会替你决策，而是提供一套结构化的方式来告诉 Codex 什么能碰、什么不能碰、应该怎么碰。它把日常开发中那些散落在人脑里的经验——比如“不要修改 DbUtils 这个类”“所有对外接口必须做参数校验”“缓存相关的代码优先查 Redis 模块”等等——变成可加载的指令模块。这是它跟简单 prompt 模板最大的区别：prompt 是一次性的，而技能包是可以长期维护、复用、给团队共享的资产。
1.2 为什么需要它：裸Codex的痛点
在用上 superpowers 之前，我在一个中等规模的 Java 项目上对裸 Codex 做了将近一个月的观察，总结出几个反复出现的痛点，也是后来我判断 superpowers 是否有价值的核心对照标准。
第一个痛点是上下文管理失控。Codex 的上下文窗口有限，而真实业务项目里需要了解的东西远比窗口容量大。你让它修一个 bug，它为了理解整个调用链，可能把一堆无关的历史代码塞进上下文，结果要么截断真正重要的部分，要么因为信息过载而“答非所问”。我遇到过一次最离谱的：让它优化一个报表查询接口，它给我重构了整个数据访问层，原因是它把 mapper XML 里的一个嵌套查询误判成全局隐患。这种问题光靠调 prompt 很难根治，因为每次提问时你不知道它会把注意力放在哪里。
第二个痛点是项目隐式规则的丢失。任何在业务线里活了三年以上的项目，都有大量“文档里没有但大家默认遵守”的规则。比如某个 service 层的所有方法必须打 operation log、某些枚举类禁止新增字段、对外接口的返回结构必须包装成统一的 Result 对象。裸 Codex 对这些一无所知，你也不可能每次都在 prompt 里写一遍。而 superpowers 把这类规则固化成了项目级的 policy 文件，Codex 每次执行任务前都会自动加载，相当于把它从“天才临时工”调教成“懂行老同事”。
第三个痛点是多语言/多模块项目里的迷航。当你跟 Codex 说“帮我在 payment 模块里加一个退款接口”，它经常搞不清楚 payment 模块的边界在哪里，依赖哪些内部工具类，是否应该复用现有的 transaction 服务。superpowers 里有专门的项目拓扑扫描器，能生成模块依赖地图并注入到 Codex 的上下文里，让它先认路再动手。我后面会具体演示这个部分的操作，因为这是整个工具链里我觉得最值钱的一个功能。
2. 安装与初始化：从零开始配置
2.1 环境准备与前置依赖
superpowers 的安装不算难，但有几项前置依赖必须提前备好，否则会在后续初始化时栽跟头。我的环境是 macOS 13.6 + zsh，Node.js 20.10 和 Python 3.11 并存，Codex CLI 已经能正常跑通基础对话。你不需要把整个环境完全照搬，但下面这几个版本要求建议不要低于我标注的数值。
首先是 Node.js，superpowers 的配置引擎和技能调度器都是基于 Node 写的，实测 Node 18 以下会报语法错误，建议直接上 Node 20 LTS 或更高。其次是 Codex CLI 本身，你需要确保已经完成登录认证，并且能通过命令行执行codex "hello"这种最简单的对话。如果之前没用过 Codex CLI，建议先花半小时跑通它的官方 quickstart，把~/.codex/config.toml里的模型参数确认好再继续。最后是 git，因为 superpowers 的很多技能包会从远程仓库拉取，而且它本身支持通过 git 来管理你们的技能配置变更。
这里我额外补充一个容易被忽略的点：如果你所在项目里有大量的 Maven 或 Gradle 构建脚本，最好确认本机已经配置好对应构建工具的全局命令。superpowers 里的“项目扫描器”会尝试解析构建文件来推断模块结构，扫描器本身并不执行构建，但它会读取pom.xml和build.gradle里声明的依赖关系。如果构建工具本身不在 PATH 里，扫描器偶尔会跳过部分模块的拓扑分析，导致后续 Codex 对某些模块的上下文理解不够完整。这个坑我在用 Windows 台式机时踩过，后面在排查部分会详细说。
2.2 三步安装：一键脚本、手动验证、初始化配置
第一步是安装 superpowers 本体。官方推荐的安装方式是下载一键安装脚本，原因是它需要同时处理节点模块、bash 补全和 Codex 配置文件的注册，分开手搓比较容易遗漏。我这里直接用命令安装（拿到的版本是 0.10.x，后续小版本可能有更新，逻辑不变）：
curl -fsSL https://get.superpowers.dev/install.sh | bash脚本运行结束后，终端会提示你执行source ~/.zshrc或source ~/.bashrc来刷新环境变量。刷新后验证一下：
superpowers --version这个命令能正常输出版本号，说明本体已经装好。注意这里不要把curl | bash当成可以闭眼执行的命令去跑，我建议是先curl -O把脚本下载到本地，打开看一眼确认没有奇怪的重定向逻辑，再决定是否执行。不是什么不信任开源社区的问题，而是安装到本机的工具，花三十秒审一遍脚本内容，是对自己环境负责任的做法。
第二步是初始化 superpowers 的全局配置目录。执行：
superpowers init它会在~/.superpowers/底下创建三个子目录：config/存放全局设置文件，skills/存放你可以跨项目使用的通用技能包，logs/存放运行时日志。初始化完成之后，superpowers doctor命令可以检查当前环境是否满足所有要求，它会逐项检测 Node 版本、Codex CLI 配置、git 用户信息、以及可选的 Java/Python 工具链。我第一次跑 doctor 时它提示 Codex 配置里的 model 字段还是旧版本格式，让我去~/.codex/config.toml看一眼，这种检查做得比较细致，能省掉不少后续调试时间。
第三步是给具体项目创建项目级配置。进入你的目标项目目录后运行：
superpowers project init这一步会在项目根目录生成.superpowers/文件夹，里面包含project.yaml和skills/两个核心部分。project.yaml是项目级策略描述文件，用来声明项目类型、模块结构、关键路径、代码规范、禁止触碰的区域等信息。它的格式是 YAML，设计得比较扁平，可读性很好。我自己常用的一个最小化配置长这样：
project: name: payment-platform languages: [java, xml, sql] modules: core: path: ./core description: 公共领域模型与核心接口 payment: path: ./payment description: 支付业务实现，依赖 core guard: protected_paths: - "core/src/main/java/com/company/model/**" - "payment/src/main/resources/mapper/**" rules: - "对外的接口方法必须使用 Result 包装返回" - "数据库操作必须通过 mapper 层，禁止裸写 JDBC"这段配置的意图很清晰：告诉 Codex 这个项目有两个模块，core是公共核心模型，payment依赖core；两个模块下的某些路径受保护，不可擅自修改；还有两条项目铁律。当 superpowers 激活 Codex 会话时，它会把这些信息自动拼装成一段系统级指令，让 Codex 在每一次响应之前都先“背”一遍这些约束。实测这个措施能大幅降低 AI 乱动无关文件的概率。
2.3 配置项解析：workspace、profiles、skills
superpowers全局配置里还有三个相对高级但非常实用的概念：workspace、profiles 和 skills。理解他们之间的关系，你才算真正掌握了这套工具的灵活性。
workspace 对应一个你日常开发的工作区，可以理解为“一个业务线项目集合”。如果你像我一样同时维护两三个相关但又独立的服务，你会希望有些配置是跨服务共享的，比如团队统一的异常处理规范、日志格式要求。你可以在全局配置里创建一个名为fintech的 workspace，然后把这三个服务各自的.superpowers/project.yaml都注册到该 workspace 之下。之后激活 Codex 时，superpowers 会自动合并 workspace 级别的公共规则和项目级别的私有规则，规则的优先级是：项目规则 > workspace 规则 > 全局默认规则。这个设计特别适合微服务拆分比较细的团队，否则你就要在每个项目里重复维护同一份规范，迟早会改出分歧。
profiles 则是一组预设的“工作模式”，面向的是同一套代码库在不同任务类型下的差异。比如你正在给老项目加新功能时，你希望 Codex 保持克制，尽量沿用现有风格；但你做技术债清理/重构时，你又希望它更大胆地移除死代码、统一命名。superpowers 内置了几个官方 profile：conservative、refactor、feature、bugfix，你可以在~/.superpowers/config/profiles/里看到它们的定义，也可以自定义。profile 里主要配置的是 Codex 的温度参数、允许执行的 shell 命令白名单、以及技能包加载的优先级。我建议每个团队至少建立一个自己常用的team-default配置，把这些年沉淀的代码评审意见都抽象成几条规则放进去，效果比写十几页开发规范文档好得多——因为 Codex 是真正会去读并执行的。
skills 是 superpowers 的灵魂，它本质上是一个“可复用的操作指令包”，由一组 markdown 文件、模板片段和脚本组成。官方仓库自带一些通用技能，比如“从 Jira 描述生成代码更改”“写单元测试并确保覆盖率”“分析性能瓶颈”。我到现在已经积累了 20 多个自定义技能，都是按实际项目需求做的。后面我会拿一个 Java 重构的场景来演示怎么编写一个团队可复用的技能包。
3. 在Codex中激活superpowers：常用操作与实战
3.1 基础指令：/power、/scan、/delegate
配置完成后，在实际开发里要怎么把 superpowers 的能力“注入”到 Codex 对话中？它并不是后台常驻服务，而是提供了一个插件式的接入方式。当你需要让某个 Codex 会话带上 superpowers 的项目上下文时，只需要在会话中发送：
/power on这条指令会触发 superpowers 的上下文组装器，把 project.yaml 里的规则、已启用的 profile 指定、以及当前 git 分支和最近变更文件列表注入到 Codex 的 system prompt 中。我实测在codexCLI 里输入这条指令后，Codex 会短暂输出一段“加载中”的提示，之后对话历史里会多出一条类似“[superpowers] 已加载项目规则”的记录。接下来的对话，Codex 的行为会在很大程度上受这些规则约束。
/scan是另一个我高频使用的指令，它用来触发项目拓扑扫描。执行方式：
/scansuperpowers 会读取当前的构建文件、目录结构、以及 git 管理的源文件清单，生成一张模块依赖图谱，并把关键路径注解嵌入其中。扫描结果会以文本摘要的形式进入 Codex 上下文。对于大型旧项目来说，这是最实用的一条指令，因为 Codex 终于能分清哪个模块是给 APP 端用的、哪个模块是给后端管理台用的，不会再把两个结构相似但语义完全不同的实体类搞混。
/delegate则是把某个子任务“分包”给 Codex 并附带完整的边界描述。它的作用更像是给 AI 下达一份“合同”：任务目标、输入、输出、允许修改的文件列表、禁止修改的文件列表、以及验收标准。我用得最多的是让 Codex 去修一组单测失败的用例。以前裸跑 Codex 时，它修着修着就把被测代码也给改了，还美其名曰“优化”。用了/delegate之后，我在 contract 里明确写了“仅允许修改src/test/**目录下的文件”，它就成了一个非常守规矩的工具人。
这几条指令都不复杂，但组合起来能产生质变。我现在的工作流通常是：早上一到工位，先跑一次/scan更新项目认知，然后根据当天要做的任务选择对应 profile，再决定要不要用/delegate分包处理。Codex 不再是那个“时灵时不灵”的自动补全放大器，而变成了一个带边界感的高级实习生。
3.2 让Codex读懂大型项目的上下文策略
很多人在大型项目里用 AI 编程工具觉得不灵，根本原因不是模型不够强，而是它连“这个项目到底长什么样”都没搞清楚就开脑洞了。superpowers 解决这个问题的方法可以总结成三层：目录策略、依赖策略、变更策略。
目录策略是第一步。在 project.yaml 里，你把项目的顶层目录按照“可以动”“只读”“绝对保护”三级做标注。以我手上的支付平台为例：
paths: - path: payment/src/main/java/com/company/payment/controller access: read-write - path: payment/src/main/java/com/company/payment/service access: read-write - path: payment/src/main/java/com/company/payment/model access: read-only - path: core/src/main/java/com/company/core/** access: protected这样做的好处是，Codex 在规划修改时会先检查目标文件是否落在自己的读写作区内。模型层永远是只读的，核心公共模块是保护状态，只有 controller 和 service 层可以随便改。这看起来像个没什么技术含量的路径白名单，但在实际协作里它挽救了无数次“发现模型类少个字段顺手补上”的连锁事故。
依赖策略则依赖/scan的产物。superpowers 会用 AST 解析项目里的 import 引用关系，构建出模块间的依赖矩阵。比如它能得出“payment service 层依赖于 core model 但不应直接依赖 core repository”这类结论。这些关系会被自动生成成规则片段，在 Codex 每一次回应之前注入 prompt。你想象一下，Codex 每次被要求写代码时，脑子里都先是“我要遵守依赖方向约束，不能打破分层架构”，这就极大减少了那种“直接在 controller 里写了三千行 SQL 逻辑”的代码出现。
变更策略是我最看重的一层，它指的是通过 git diff 信息来限制 AI 的注意力范围。superpowers 在注入上下文时会自动获取当前分支相对主分支的变更文件列表，并且提示 Codex：“本次会话涉及的文件优先考虑这些已变更的文件。”如果你正在修复“支付回调超时”的 bug，Codex 就不会满仓库找突破口，而是优先从你手头已经改过的那些文件入手。这跟人类开发者的工作习惯是一致的——先在被修改过的代码附近排查，而不是从别处引一条新路径进来。
这三层策略叠在一起，效果非常明显。我统计过一个小样本，用相同的重构任务分别让裸 Codex 和 superpowers 加持的 Codex 去完成，裸 Codex 平均需要 7 轮对话来确认边界，且最后经常会出现 1-2 处无关代码被改动；加持后的 Codex 平均 2-3 轮就能产出符合预期的 diff，并且没有一次触碰保护路径。这个差异不只是效率问题，更重要的是把“AI 写了我不想要的代码”这种心智负担降了下来，让我更敢让它实际干活。
3.3 Java项目实战：重构老代码的完整流程
理论讲了不少，这里走一遍真实场景。我的支付平台里有个历史遗留的类PaymentRouter，两千多行，承担了渠道路由、费率计算、对账标记三件事，各种 if-else 嵌套得有七八层。我打算让 Codex 先把这个类里的“费率计算”逻辑抽出来，变成一个独立的FeeCalculator类，且不能改变任何对外方法签名。
第一步，初始化项目上下文。确保在项目根目录，先执行/power on把项目规则加载起来，再执行/scan更新模块拓扑。之后我给 Codex 下达的第一个任务指令是“分析PaymentRouter中费率计算相关代码的范围和耦合度”。这一步很关键，我不是直接让它“重构”，而是让它先输出一份影响分析。裸 Codex 往往愿意干这种分析活，但分析完之后就急着动手。为了让它在动手时牢记约束，我把一段分析结果反馈成一条项目规则：
rules: - "PaymentRouter 中的费率计算逻辑属于可独立抽取范畴，重构时保持公开方法签名不变"之后才下达重构指令：“将费率计算相关的私有方法、字段和常量抽离到新的com.company.payment.fee.FeeCalculator类，PaymentRouter 通过委托方式调用。”同时使用/delegate限定工作范围，只允许修改payment/src/main/java/com/company/payment/router/PaymentRouter.java，并新建上述 FeeCalculator.java。运行结果是 Codex 分三步完成了迁移：先把费率计算的方法体原样搬到新类，再把 Router 里相关调用替换为新类实例方法，最后构造了一个粗略的单测覆盖主要费率分支。
过程中我注意到一个小问题：Codex 在搬迁移时顺手把原来一个用于“金额毛差处理”的私有方法的可见性从 protected 改成了 private，而另一个类LegacyFeeHook还在用 protected 访问它。这在编译时会暴露出来。我最初的合同里忘了说明“原有可见性不得变更”。加了这条规则后，重新跑一遍，问题就消失了。这个细节值得每个用 AI 重构的人记住：可见性、注解、异常声明这类“语义边缘”属性是模型最容易在重构时弄丢的，务必要把它们写进委托合同里。
重构完成后，我还让 superpowers 把这次过程中总结出来的规则写回技能包，以后任何涉及PaymentRouter的改动都会自动带上“保持方法签名”“保留 protected 可见性”“费率逻辑已迁移至 FeeCalculator”这几条提醒。这就是技能包“越用越聪明”的实际意义——项目认知会随着每一次 AI 协作沉淀下来，而不是每次开会讨论完就消失。
3.4 自定义技能包：给团队复制你的工作流
superpowers 最有吸引力的地方，是它允许把“你的工作流”变成“团队的工作流”。我花了一个下午做了一个叫payment-code-review的技能包，里面集成了我们团队代码评审时最看重的五个维度：事务边界、资金计算精度、幂等性、日志完备性、异常处理。完成之后的技能包结构如下：
skills/ payment-code-review/ SKILL.md rules/ 001-transaction-boundary.md 002-money-rounding.md 003-idempotency.md 004-logging.md 005-exception-handling.md templates/ review-comment.md change-plan.mdSKILL.md是入口文件，里面用一段简短的描述说明这个技能包适用于什么场景：“针对支付相关代码变更的评审检查清单，适用于 Merge Request 审查和 Codex 辅助评审。”rules/目录下每个 markdown 文件描述一条具体的评审规则，templates/提供评审意见的输出格式。superpowers 会把这个技能包的所有规则拼进 Codex 的上下文。比如我给 Codex 下达“用 payment-code-review 技能审查本周的改动”，它就会按照五个维度依次检查并输出一份带严重级别的评审报告。
这里有个操作细节要强调：技能包不是写一次就能完美的，实际用起来需要定期回刷。我第一个版本的001-transaction-boundary.md只写了“所有跨库操作必须使用分布式事务”，结果 Codex 把很多不需要跨库的普通方法调用也标成了严重问题。后来我在规则里补了一句“仅在单个请求内同时修改两个及以上业务库的写操作才需要关注”，误报率立刻降了下来。这说明技能包里的规则必须写得像优秀的 code review 评论一样，有明确的适用范围和判断标准，而不能是大而化之的口号。
做团队共享的方法也很简单：把~/.superpowers/skills/或项目里的.superpowers/skills/放进 git 仓库。这样只要团队每个人 pull 下来并执行一次superpowers project sync，就都能同步到同一套技能包。我们的代码评审效率在这套流程跑顺之后有了肉眼可见的提升，至少“是否加了事务”“金额计算有没有用 BigDecimal”这类低级遗漏在 MR 里再也看不到了，因为 Codex 在第一道关卡就会先查一遍。
4. 常见问题排查与避坑实录
4.1 安装失败/权限问题的处理
安装过程最常见的坑，出现在superpowers init之后。如果你用的是 zsh，但脚本只是往~/.bashrc里写环境变量，那你新开的终端可能还是找不到superpowers命令。排查思路是按顺序执行which superpowers和echo $PATH，看是否包含~/.superpowers/bin。如果没包含，手动加一下或者重新执行source即可。更隐蔽一种情况是 Node 版本太旧导致的安装脚本本身报错，它通常会提示node: internal/modules/cjs/loader之类的堆栈。这时候不要盲目去改脚本，直接升级 Node 到 LTS 版本，重跑安装脚本，大概率就过了。
权限方面，如果你是在公司内网环境跑 install 脚本，可能会被网络代理拦截。此时可以去官方 GitHub Releases 页面手动下载对应平台的压缩包，解压后放到~/.superpowers/，再手动把~/.superpowers/bin加到 PATH。我因为公司网络策略限制，最后就是走的手动安装路线。整体耗时比自动脚本多了大概十分钟，但好处是你能清楚看到每个文件被放在哪里，后续排查也更方便。
启动时如果遇到codex command not found但 Codex CLI 明明装好的情况，检查一下 superpowers 配置里记录的 codex 执行路径是否和实际的which codex一致。尤其用 Homebrew 安装的 Codex，路径可能是/opt/homebrew/bin/codex，而 superpowers 初始化时探测到的可能是/usr/local/bin/codex，就会对不上。在~/.superpowers/config/config.yaml里显式指定一下codex_bin_path就行。
4.2 Codex上下文被“撑爆”怎么办
用了/scan之后，项目上下文的体积会变大，特别是在一个上千个类的微服务项目里。Codex 的 token 窗口有限，如果注入的扫描摘要过长，会导致模型“记住后面忘了前面”，甚至报出上下文超限错误。我的经验是不要试图把整个项目都塞进去，而是学会做减法。在 project.yaml 里明确scan.exclude目录，把generated/、target/、node_modules/、build/这些无关目录全部排除，同时把scan.depth设置成 2 或者 3，只让扫描器深入到你真正关心的业务模块层级。
另外，/scan生成的结果不是必须要全量注入。你可以用superpowers context show命令先查看它打算注入的内容列表，然后用superpowers context filter --module payment只保留 payment 模块的拓扑信息。这个习惯非常有用，我从一开始的无脑全量扫描，到后来只注入跟当前任务相关的两个模块，Codex 的响应质量和稳定性都提高了一截。上下文管理这件事，本质上是“与其让 AI 知道太多但每样都只懂一点，不如让它对你正在做的事建立一个极清晰且深入的局部模型”。
还有一个坑是扫描结果里的中文描述编码问题。在 Windows 终端下，如果项目路径包含了中文，扫描器生成的 JSON 摘要偶尔会出现乱码，进而影响 Codex 对文件路径的识别。我最后的解决办法是把项目路径统一改成纯英文，或者保持一个不含中文的工作根目录。这在绝大多数技术团队工程环境里其实是常规要求，如果你的是老项目已经带了中文目录名，那就只能手动在project.yaml里把路径映射写清楚，匹配规则尽量用通配符。
4.3 多语言项目中被“误解”的场景
我有个边缘项目同时包含 Kotlin 和 Java 代码，superpowers 的扫描器默认按语言统计文件，但在生成模块描述时，偶尔会把 Kotlin 的 data class 当成 Java POJO 来理解，导致 Codex 给出一些在 Kotlin 中根本不成立的写法，比如让我“手动编写 getter/setter”。解决方式是在project.yaml的languages字段里明确列出，并且额外声明每个语言对应的代码风格文件：
languages: java: style_guide: .superpowers/style-guides/java-style.md kotlin: style_guide: .superpowers/style-guides/kotlin-style.md我给每个语言写了一个极简的 style guide 文件，不需要长，五到十条关键约定就够，比如“Kotlin data class 使用 val 声明不可变属性”“Java 实体类使用 Lombok @Data，不需要手写 getter/setter”。这样 Codex 在生成不同语言代码时就会套用对应的规范。实际用下来，Kotlin 文件里出现冗余 getter/setter 的概率从之前的 20% 降到了不到 2%，说明这个方法是有效的。
另外，如果你的项目里有 SQL 文件或 XML mapper，建议单独建一个.superpowers/skills/db-aware/SKILL.md，里面写上“所有 SQL 必须走 MyBatis mapper，禁止在 Java 代码里拼接 SQL”之类的规则。因为 LLM 对“SQL 应该放在哪一层”的默认理解偏向于灵活的 JPA/Hibernate 风格，这跟你项目里已经固化的 MyBatis 范式很可能冲突。不显式告诉它，它就会按自己熟知的套路来。
4.4 我的几个使用心得
踩了这么多坑之后，我逐渐形成了一套自己用起来最顺的 superpowers 实践方式，写下来算是个人的经验沉淀。
第一，不要一开始就追求“大而全”的配置。我见过有人花三天时间把所有规则、技能、profile 全部配好，结果跑一次 Codex 会话，上下文被塞得满满当当，效果反而不如裸 Codex。我现在的原则是“最少可用配置”，只加那些能解决真实问题的规则。每加一条规则之前，先自问：这条规则是否会在至少 20% 的 AI 交互场景里被触发且产生明显价值？如果不满足，就先不加。等真遇到因此出问题的场景，再把规则补上。这种渐进式维护让配置文件始终处于可理解、可解释的状态。
第二，技能包里的规则一定要带“正反例”。只写“保持方法可见性不变”，模型其实理解得不够具体；但如果你在规则里同时给出“不要将 protected 改成 private；例如 LegacyFeeHook 仍依赖该方法的 protected 访问”，模型就能建立更精准的模式。我现在写的每一条规则几乎都包含bad和good两个示例段，虽然写的时候费点时间，但之后几乎不会再出现同类误判。
第三，用 git 管理好.superpowers/目录。因为它承载的是项目级的知识资产，跟代码一样需要版本管理和评审流程。我们自己团队的约定是：任何对 project.yaml 或技能包的修改，都必须走 Merge Request，由另一名熟悉业务的人进行复核。否则容易出现某人为了“让 Codex 闭嘴”而加入过于严苛的规则，导致 AI 在正常任务上也变得畏手畏脚。每一次规则变更都应像代码变更一样被审视，这才是让工具沉淀成为团队资产而不是某个人私有习惯的关键。
最后再分享一个小细节：superpowers 初始化时会自动生成一个CHANGELOG.md用于记录配置文件的变化历史，但你也可以在每次迭代之后手动写一点“这次为什么加这条规则”的背景说明。几个月之后再回头看，你会发现这些记录比代码注释更珍贵，因为它们记录的是你与 AI 协作模式逐渐演进的过程。我现在每次技术分享、团队 onboarding，都会直接拿这套配置当作教材来讲解，新同事在半天内就能对项目架构和协作约定建立起一个相当具体的认知，这一单收益就已经值回所有折腾成本了。
