最近在折腾Codex CLI的时候我发现一个特别明显的现象同一个模型、同一个项目有的人用起来跟装了外挂一样有的人却总觉得AI写的代码没法看改半天比自己写还累。区别往往不在模型的版本号而在于你给它搭的那套辅助配置。社区里管这个叫superpowers——严格说它不是一个标准开源项目名而是一套让编码智能体从能用变成好用的技能增强思路和配置方案。我这么说可能有点抽象换个说法默认状态下的Codex就像一个能力很强但完全没有入职培训的新人。你知道他能干活但每次都得把项目背景、代码规范、测试要求、输出格式逐条交代一遍交代不清楚他就给你自由发挥然后你就得收拾烂摊子。superpowers这套思路要解决的就是把这个入职培训固化下来让AI每次开工前自动读完你的规范、自动带上你的最佳实践变成一个懂规矩、有章法的熟练工。这篇文章我就把这段时间配置、踩坑、迭代skill包的过程完整梳理一遍适合正在用Codex CLI、或者打算把AI编程助手真正用进日常开发的朋友参考。1. 项目整体设计与思路拆解1.1 superpowers到底解决什么问题先说痛点。我刚开始用Codex的时候工作流是这样的新建一个会话粘贴一段代码说帮我看看有什么问题然后它给我回一段泛泛而谈的点评什么注意空指针建议增加日志——说了等于没说。后来我尝试把所有需求都写进提示词里结果提示词越来越长几百个token全浪费在重复背景上有时候还因为描述不清AI的理解反而跑偏。后来我意识到问题的本质不是模型变笨了而是每一次会话都是冷启动。Codex没有记忆它不知道我们项目的包结构、不知道团队约定用PostgreSQL还是MySQL、不知道接口返回格式统一是{code, msg, data}。每次你都得重新说说漏了它就按自己的默认习惯来而AI的默认习惯往往是教科书风格不是你团队的真实风格。superpowers这个思路的核心就是把需要重复交代的内容沉淀成一份份可以被自动加载的技能包。技能包里有背景说明、规范约束、示例输入输出、以及触发条件。会话开始的时候CLI先加载对应的技能包相当于给AI做了一次快速的入职培训。培训完了再干活输出质量完全是两个级别。我自己的体感是配置好技能包之后Codex在熟悉项目上的表现从偶尔惊艳偶尔离谱变成了稳定可用——大多数情况下第一次给出的代码已经符合团队规范我只需要做小范围修改而不是推倒重来。1.2 为什么是技能包而不是换模型有人可能会问既然模型默认行为不理想为什么不直接换一个更大的模型或者做微调这里有几个现实原因。第一换模型的成本很高。API调用成本、延迟、以及你本地环境的兼容性都是问题。更强的模型不保证更懂你的项目——它只是能力上限更高但如果没人告诉它你的代码规范它照样按通用套路来。第二微调更不现实。一个普通团队一年跑几十万行代码微调的语料怎么准备标注团队从哪来模型版本一更新微调成果可能就废了。这属于理论上可行、实际上劝退的路线。第三技能包是轻量、可维护、可版本管理的。它本质上是文本文件放在Git仓库里谁都可以改、可以review、可以回滚。新同学加入团队拉一份技能包就能让AI秒懂团队规范这比什么培训文档都直接。我用一个生活化的类比给AI配技能包就像给新人发一本《入职手册》手册里写了我们团队几点开会代码提交前必须跑哪些检查线上故障找谁。而每件事都靠提示词现交代就像每次让新人去干活前把手册重新念一遍——费时费力还容易念漏。1.3 这套方案适合谁、不适合谁先说不适合的情况。如果你只是偶尔用AI问几个技术问题比如Python里怎么反转字典那完全没必要搞技能包那是杀鸡用牛刀。如果你用的是Web版ChatGPT根本接触不到CLI层的技能加载机制也暂时用不上这套东西。反过来适合的情况非常明确你在代码里高频使用Codex CLI之类的智能体工具每天至少好几个会话。项目有一定规模团队有自己的代码规范、目录结构、常用技术栈。你希望AI的输出风格稳定比如接口注释必须写清楚入参出参数据库操作必须走mapper层不允许裸SQL。你想把个人AI使用经验沉淀成团队资产而不是留在自己脑子里。说白了这套思路适合真正的工程场景而不是尝鲜场景。如果你在一次会话里问完就走那技能包的价值体现不出来如果你希望AI成为团队里稳定输出的一员那它值得投入。2. 核心细节解析与实操要点2.1 技能包的基础构成既然要做技能包第一步是搞清楚一份技能包里有什么。我参考了社区里比较常见的做法结合自己的实践通常包含这几个部分元信息技能的名称、描述、适用场景用于决定什么时候加载这个技能。指令正文告诉AI应该怎么做的核心提示词。这部分要写得非常具体不能含糊。示例一个或几个输入输出对展示什么样的输入对应什么样的输出最好。约束与红线明确哪些事情绝对不能做比如不要修改公共接口签名不要自动执行测试。参考文件路径指向项目里的某个文件或目录让AI在需要的时候去读取细节。举个例子我团队里有个约定所有新增接口返回格式必须是{code: 0, msg: success, data: ...}。如果我仅仅在提示词里写返回格式要统一AI可能给你来个ResultT、ResponseEntity、ApiResponse每次都不一样。但在技能包里我可以写死所有Controller层方法返回类型固定为 RT R 的定义见 src/main/java/com/xxx/common/R.java。 成功时 code0失败时 code非0data 为 null 时不返回该字段。这样的指令很枯燥但对AI来说越枯燥、越具体的指令执行准确度越高。你写要符合规范它不知道你的规范是什么你把规范原文放进去它就能照着做。2.2 定义一条高质量技能的四要素我在迭代技能包的过程中总结了一条技能要写得好的四个要素缺一个都会导致效果打折。第一是触发条件要清晰。技能包不是越多越好每个技能都要有明确的适用边界。比如代码审查技能只在你说review一下这个改动的时候触发数据库迁移技能只在涉及Flyway脚本时触发。如果没有触发条件AI可能在写业务代码的时候突然给你套上代码审查的话术很割裂。第二是步骤要顺序化不要写成散文。同样是代码审查写成散文请你全面审查这段代码效果远不如给它明确的步骤第一步检查空指针和资源泄漏 第二步检查是否符合团队命名规范 第三步检查事务边界 第四步按严重程度输出问题清单。为什么步骤化有效因为AI在长任务里容易丢失目标给它一个checklist它就顺着清单一项项走不会自己发挥出新的审查维度。第三是必须有正反示例。AI很吃示例尤其吃反例。我写过一个技能里面特意放了一个错误写法某个接口直接把DAO层对象返回了出去变成了实体序列化泄漏。AI看过反例之后在审查类似代码时命中这个问题的概率明显提高。没有示例的技能就像只有理论没有实操的培训听懂了但不会用。第四是红线和边界必须单独强调。比如只审查不修改代码遇到不安全的原则可以指出但不输出完整替代代码。把红线和主指令分开AI执行起来才不会混在一起。2.3 上下文编排与token成本控制技能包不是越多越好这里有个很现实的成本问题上下文窗口有限token是钱。Codex这类工具每次请求都要把对话历史、系统提示、技能内容一起塞进上下文窗口。如果你给每个会话都加载20个技能每个技能800个token光技能就吃掉16000 token留给实际代码分析的空间就非常小。轻则速度变慢重则直接超限报错。我的做法是给技能分等级按需加载全局技能每个会话都要用到比如代码风格规范Git提交信息格式控制在3个以内。项目技能特定项目才加载比如XX项目数据模型说明通过项目目录下的配置关联。任务技能用到时再调用比如Redis迁移方案幂等设计模板这类技能不必全局加载。实际操作中我把技能的加载逻辑写成了一段规则放进项目配置文件里当识别到文件路径含xxx-mapper.xml时才加载数据库规范技能当识别到Dockerfile相关路径时才加载容器化构建技能。这样既保证需要时有又不会造成不必要的token消耗。我补充一点写技能的时候也要控制单个技能的体积。一份技能超过3000字AI的执行力就会明显下降因为核心指令被淹没在背景信息里了。如果确实信息量大可以拆成多个小技能或者把详细内容放在引用文件里技能只写去读哪个文件、关注哪些点。这是很多新手容易忽略的地方——以为塞得越多越好结果AI抓不住重点。3. 实操过程与核心环节实现3.1 环境准备先用起来先说明一下我这里说的环境准备是基于社区里最常见的用法具体到你本地的版本和配置最好以官方文档为准。但大体的套路是通用的。第一步安装Codex CLI。安装好之后确认命令行能跑通登录并验证基础会话正常。这一步没什么好说的装不上就去查官方文档一般就是环境变量和鉴权token的问题。第二步为技能包建一个目录。以我常用的方式为例我建了一个skills/目录放在项目根目录旁边或者在用户配置目录下建~/.codex/skills/。两种方式我都试过放项目里方便跟代码一起走、一起版本管理放用户目录里适合跨项目通用技能。我的建议是通用技能放用户目录项目特化技能放项目目录。这样拉一个新项目clone下来就自带项目技能不用再额外拷贝。第三步写第一份技能文件。不用急着写复杂的先写一个最简单的Git提交信息生成规则技能名称git-commit-style 触发条件当用户要求生成提交信息或写commit message时触发 指令 - 提交信息格式type(scope): subject - type 取值为 feat / fix / docs / refactor / test / chore - subject不超过50个字符祈使句开头首字母小写 - 正文必须说明为什么做这个改动而不是改了什么 约束 - 不生成任何除此之外的格式不写 Co-authored-by第四步在会话里试一下随便改一个文件然后让AI生成提交信息。如果它输出的格式跟你定义的一致说明技能被加载成功了如果还是按照通用格式输出那就需要检查配置路径和命名是否被正确识别。我遇到过一种情况技能目录建了、文件也写了但是AI完全没反应。后来发现是因为技能文件没有写触发条件CLI不知道什么时候该加载它。没有触发条件的技能就像没有预约的新员工根本不会出现在工位上。3.2 手写一个Java代码审查技能这部分我用一个完整的Java场景演示一遍这也是社区里问得比较多的话题——怎么样让AI的代码审查真正贴合团队规范而不是空泛地背八股。假设团队的技术栈是Spring Boot MyBatis数据库操作习惯走Mapper层不允许业务代码里直接用JDBC或SqlSessionTemplate裸查。基于这些前提我写一个代码审查技能技能名称java-code-review 触发条件当用户提到review审查看看这段代码且文件后缀为.java时触发 步骤 1. 先读取项目根目录下的 CODE_STYLE.md提取命名规范和分层规范 2. 按以下维度逐项审查 a. 空指针风险所有外部传入的参数、缓存查询结果、远程调用返回值 b. 事务边界检查Service层方法是否对多步数据库操作使用了Transactional c. 架构一致性确认Controller只做参数校验和路由Service只做业务逻辑DAO只做数据访问 d. 资源管理检查流、连接、锁是否正确关闭优先推荐try-with-resources e. 敏感信息不允许在日志中输出明文密码、token、手机号 3. 输出问题清单格式为级别严重/建议/可选 文件路径:行号 问题描述 修改建议 约束 - 如果代码不符合上述规范直接指出不要先夸一遍再委婉说可以考虑优化 - 只审查不修改输出问题清单不要输出完整重构代码 示例 输入 public User getUserById(String userId) { ResultSet rs stmt.executeQuery(select * from user where id userId); ... } 输出 - 严重 | UserService.java:12 | 存在SQL注入风险使用字符串拼接查询应改为PreparedStatement参数化查询这份技能写的不长但每条都是可执行的。我特别想说一下其中输出格式这一条。早期我的技能没规定输出格式AI审查完给我来一段长篇大论我得自己从中找重点。加了问题清单级别文件行号之后效率明显提升甚至可以配合脚本把输出导入到评论区或者工单里。写完技能之后还要实际测试。我拿一段故意埋了三个问题的老代码去触发它一个Service里直接new了一个SqlSessionTemplate做查询一个Controller里打印了用户手机号日志一个finally块里忘记关闭连接。三次测试下来前两类问题都精准命中连接关闭这个点偶尔漏。后来我又在技能里加了一句重点检查finally块和资源释放路径补齐了这个盲区。这也说明技能包是一个持续迭代的东西不是写完一遍就完事而是要在真实使用里不断校准。3.3 把技能接入团队工作流技能包在个人手里是一次性效率提升在团队里就能变成一件资产。我后续做的是把技能包放进Git仓库然后写了一个简短的README告诉团队成员怎么启用。接入流程大概是这样的新建一个ai-skills仓库目录结构按skills/技能名/skill.md组织在README里写清楚如何安装、如何更新、如何提交新技能通过git submodule或者直接复制的方式把通用技能部署到每个开发者的用户目录项目特化技能比如订单中心数据字典放在各自项目的.codex/skills/下随代码库走。这个流程跑起来之后效果很明显团队里不同成员让AI生成的代码风格趋同了因为大家的AI读的是同一份规范。代码review的时候因为AI已经按统一规范筛过一轮人工review的负担小了很多。有朋友问我说自己不是用Codex而是用其他AI编程工具或者是在某些封装平台里用问怎么套用superpowers。我的回答是思路一模一样。你只需要确认三件事——第一你的工具支不支持在会话开始时加载一些预设文本第二能不能按路径或关键词自动触发预设文本第三预设文本能不能版本管理。只要这三个回答都是可以那你就可以按上面这套技能包的思路去搭。工具只是加载器核心永远是技能的编写质量。还有一个容易踩的坑技能包一定要有人维护。我见过团队把技能仓库搭起来了但三个月没人更新后来连基本的构建工具版本都变了技能里还写着旧命令。AI照着旧命令生成代码CI直接挂掉。技能是活的东西项目演进技能也要跟着演进。我现在的习惯是每两个星期花半小时过一遍技能仓库把过期内容清掉把新踩坑经验补进去。4. 常见问题与排查技巧实录4.1 技能没生效AI还是答非所问这是刚上手时最常碰到的问题。你明明写了技能文件但AI好像完全不知道它的存在。我排查的顺序一般是这样的先确认触发条件是否明确。技能里如果没有写清楚什么场景下加载CLI可能不会把它带进上下文。解决方式是把触发条件写得非常直白比如当用户要求review Java代码时而不要写成该技能适用于质量保障场景——后者太模糊了。再确认路径是否正确。我遇到过在项目目录下建了skills/目录但CLI读取的是用户目录下的配置两边没关联导致技能根本没被索引。这种情况去翻一下工具的帮助文档确认技能目录的配置项指向的是哪里比直接改文件更实际。最后确认上下文是否可见。有些工具会把系统级的技能说明放在模型看不到的地方或者在某个版本里对技能文件的大小有限制。如果一个技能文件超过了模型的有效窗口它可能被静默截断。判断方法很简单在技能里故意加一句在每次输出前先说一句已加载技能包。如果AI没说就说明技能没被完整加载如果说了说明机制通了。4.2 多技能互相打架技能包一多就会出现指令冲突。比如我有一个SQL优化技能和一个数据库安全技能前者鼓励用复杂查询降低应用层内存消耗后者要求所有SQL必须经过预编译、能拆则拆。两个技能同时在会话里时AI就容易摇摆不定一会儿给出复杂SQL一会儿自己又提醒要注意注入风险。我的处理原则是定义优先级而且明确写出来。当技能之间的指令冲突时按以下顺序生效 1. 安全相关约束永远优先 2. 项目架构规范优先于通用风格规范 3. 冲突无法解决时输出两条选项让用户决定这相当于给AI一套价值观让它面对矛盾指令时有章可循。更重要的是在编写技能本身时尽量做好边界隔离别让一个技能管太宽。把SQL优化和数据库安全合成一个技能效果反而更好因为AI可以在同一个上下文里做权衡而不是让两套指令在上下文里自行打架。4.3 上下文超限与输出不稳定技能包过多、过大最直接的后果就是上下文超限。报错倒还好就怕AI开始丢失前文表现出的症状是前面讨论过的规范后面突然忘了重新开始泛泛而谈。这个问题的核心是上下文资源分配。我习惯在技能文件里给字数做预算全局技能控制在1800字以内项目技能控制在1500字以内任务技能控制在1200字以内超出就拆。这个数字不是硬性标准是提醒自己写技能时克制。真正有用的技能往往就是几条精准的规则加一两个精挑细选的示例而不是长篇小说。输出不稳定还有一个容易被忽略的原因示例太少或者太偏。AI很依赖示例给出输出分布。如果你的示例只展示了文件行号问题描述这种简短格式它就会倾向简短如果你给的示例是长篇分析它也会跟着写长篇。想要稳定的输出就给足够稳定的示例而且要覆盖正常情况和边界情况。4.4 快速排查速查表为了省事我把这段时间踩过的坑整理成一张表每次配置技能不生效的时候先过一遍能解决八成的怪问题。症状最可能的原因处理方式技能完全没反应触发条件没写或写得太模糊明确列出触发关键词或文件后缀技能加载了但行为怪异与其他技能冲突检查技能优先级定义合并重叠技能输出之前还记得规则后面忘了上下文过长模型丢失前文精简技能体积减少全局技能数量技能里的规则被无视规则写成了建议语气改成强约束指令例如必须禁止同一个技能两次输出差别很大示例不够或示例覆盖不全面增加正反示例明确输出格式更新技能后行为没变化工具启用了缓存或加载了旧路径重启会话确认技能文件路径这张表的核心逻辑其实是两点一是技能有没有被正确加载二是加载进去之后指令质量够不够硬。大部分跑偏问题追到根上就是这两个环节出了岔子。4.5 写在最后的一点经验按照惯例最后分享一条我自己的实操心得。技能包这个思路很多人当成一次性配置来做——配完了感觉AI变聪明了就丢在那里不管了。但我的体会是技能包更像一份你亲手维护的工程手册它的价值来自持续打磨。我每次debug到凌晨、从一次事故里复盘出某个坑都会顺手更新对应的技能包。慢慢地AI就不再只是帮我写代码的工具它变成了团队里那个最懂规范、最不会犯重复错误的虚拟成员。还有一个小技巧送给大家在技能包的目录里放一个CHANGELOG.md记录每个版本改了什么、为什么改。别小看这个文件过两个月你再回头看会发现它就是你跟AI协作方式进化的日志比任何AI使用教程都真实。这也是为什么我后来跟朋友聊起这套方案时总喜欢说一句话——所谓superpowers并不是某个神奇模型带来的而是你愿意花时间把经验喂给工具之后自然长出来的一种手感。