最近在折腾 Codex CLI 的时候我挖到了一个叫 superpowers 的项目最初以为只是又一个给 AI 编程工具打补丁的小插件结果花了一晚上读完文档、配好环境、跑了两个真实项目之后我发现它改变的是我使用 AI 编程代理的整套方式。如果你手里也在用 Codex 这类终端里的 AI 编程工具并且经常觉得 AI 写出来的代码“单看没问题、放进项目就变味”那这篇东西大概率能帮你把工具真正盘活。我会从 superpowers 是什么、为什么值得装、怎么装、怎么写自己的技能包、再到 Java 项目里的实战一条线讲清楚最后附上我踩过的坑和排查思路。先说结论superpowers 不是某个编程语言框架也不是代码生成器它是给 AI 编程代理比如 Codex CLI加装“可复用技能”的增强层。打个比方原版 Codex 像一个专业扎实但没带项目经验的新人你把需求丢给它它能把代码写出来但不知道你们组的代码规范、不知道测试怎么组织、遇到编译错误只会盯着日志发呆。而 superpowers 做的事情就是把一个“资深工程师的干活习惯”沉淀成 Markdown 格式的技能手册让 AI 按着手册走流程。这不是给它多装点上下文而是给它一套完整的工作方法论。如果你是 AI 编程工具的日常用户、团队的 AI 工程效率负责人或者单纯对“怎么让 AI 写代码更可控”这件事感兴趣这篇文章应该能给你一套可以直接抄作业的方案。下面我从设计原理开始拆。1. 核心设计拆解superpowers 解决的是“流程缺失”而非“能力缺失”1.1 为什么 AI 编程代理总在“局部正确、全局翻车”用 Codex CLI 写过几次真实需求的人应该都有同感单看它生成的函数命名规范、注释齐全、边界处理到位但一旦把它放进整个项目里问题就来了——它不知道你们的目录规范、不理解现有模块的依赖关系、也不会主动去跑测试给自己“验货”。这不是模型能力不够而是交互方式有问题。你给它的是一次性提示词它回你一段一次性代码两个人之间根本没有“重复使用的合作流程”。superpowers 的设计出发点就是补上这一环把 AI 编程代理从一个“问答工具”改造成一个“按流程办事的执行者”。它的核心机制是技能包Skills每个技能包是一组 Markdown 文件以SKILL.md为入口里面写清楚“什么时候该用这个技能”“使用前要收集哪些信息”“处理流程分几步”“每一步的验收标准是什么”。AI 在运行时会读取这些文件把自己“代入”到一套标准工作流里。我在实际使用中的体会是这相当于给 AI 配了一本“操作手册”。新人入职时你给他讲一遍业务、丢给他几个需求文档他能干但经常干得歪歪扭扭可你要是把团队规范、典型任务的执行步骤都写成文档他照着做质量立刻稳定一个档次。superpowers 就是把这种“文档化团队经验”的做法搬到了 AI 代理身上。1.2 为什么用 Markdown 而不是写死在代码里我第一次看到技能包全是.md文件时也愣了一下不该是 JSON 配置或者 Python 脚本吗后来细想才发现这是最合理的设计。第一Markdown 是人类可读、AI 也读得最稳的格式。模型对自然语言的指令理解远好于对复杂 JSON 结构的关系推断与其让 AI 去“解析配置”不如直接让它“读手册”。第二修改技能不需要改代码、不需要重新构建、更不需要升级主程序编辑一个文本文件就能让 AI 的行为发生改变迭代成本极低。第三技能包天然适合 Git 管理团队的技能沉淀可以像代码一样评审、分支、回滚这点对企业落地太重要了。另外superpowers 把技能包组织成了三层结构skills/存放通用小型技能比如“写提交信息”“做代码审查”agents/存放完整的代理角色定义每个 agent 可以带一组技能面向完整任务commands/存放斜杠命令Slash Commands让你在 Codex CLI 里直接通过/skill-name触发特定流程。这个分层本质上是把“经验”按粒度拆开小技能是积木agent 是组装好的机器人命令是遥控器。1.3 渐进式披露避免“一口气碾压上下文”superpowers 还有一个很关键的机制叫渐进式披露Progressive Disclosure。简单说AI 一开始不会把整本手册全部塞进上下文而是先读取SKILL.md这个入口文件了解技能概览需要执行具体步骤时再去读对应章节的详细文件。这样做的好处有两个一是节省 Token二是不让 AI 被海量信息干扰保持对核心任务的专注度。这个设计思路我特别认可。在我的使用经验里一次性给 Codex 几千行项目文档它反而会“看花了眼”——重点信息被淹没指令权重被稀释。渐进式披露相当于给 AI 一个“先看目录、再看正文”的阅读路径信息是按需加载的不是一锅端。2. 安装与基础配置从零把 superpowers 跑起来2.1 环境准备先确认你的底子在动手安装之前先确认你的机器满足这几个条件缺一个后面都会卡住。系统macOS、Linux、Windows通过 WSL都行我是在 macOS 13 上跑的流程最顺。Codex CLIsuperpowers 主要面向 Codex CLI 这类 AI 编程代理确保你已经装好并能正常使用。安装命令一般是npm install -g openai/codex装完先跑一次codex确认能正常对话。Node.js 18Codex CLI 依赖 Node 环境版本太低会被拒。Git拉取技能包仓库要用到。提示如果你日常用的是其他支持技能包机制的 AI 编程工具部分开源代理也兼容类似格式思路完全一样只是配置文件位置略有差异。本文以 Codex CLI 为主。2.2 拉取技能包仓库官方技能包集合是直接以 Git 仓库形式分发的。我用的典型流程是# 找个干净目录存放技能包 mkdir -p ~/.codex/skills cd ~/.codex/skills # 克隆官方技能包仓库 git clone https://github.com/worksolutions/superpowers.git仓库克隆下来之后你会看到里面有skills/、agents/、commands/三个主要目录。先别急着改东西进去把结构浏览一遍心里有个数。装好之后还需要让 Codex CLI 知道“去哪里找技能包”。这一步以 Codex 的配置文件为准通常是在~/.codex/config.toml里添加技能包路径或者在 Codex CLI 的启动参数里指定。如果你用的是默认配置可以在config.toml中加入[experimental] skills_path /Users/你的用户名/.codex/skills/superpowers注意这里的路径一定要写成绝对路径用~有时候解析不到。配置完重启 Codex CLI技能包机制就会加载。2.3 验证是否生效怎么确认技能包被成功加载了最简单的方式是在 Codex CLI 里输入斜杠命令比如/superpowers如果能看到技能列表输出就说明加载成功。此时让它做一个简单任务比如用 /delegate 技能帮我列出当前目录的 git 状态观察它是否先输出“正在读取技能包…”之类的中间过程如果是说明它已经进入“按技能干活”的模式。我在这一步遇到过一个问题技能列表能看到但实际调用不生效。后来排查发现是路径写错了——我复制文档时带了一个尾随空格解析直接失败。所以配置路径时务必检查空格和大小写。3. 核心实操编写你自己的技能包3.1 SKILL.md 的结构YAML 头 Markdown 正文学习 superpowers 的最好方式不是读教程而是拆一个现成的技能包看结构。我拆解了仓库里的code-review技能它的SKILL.md长这样--- name: code-review description: 对代码变更进行系统性审查发现逻辑错误、安全隐患和风格问题。适用于 merge request 或 push 前。 --- # Code Review 技能 ## 触发场景 - 用户要求“审查代码”“看看这次改动有没有问题” - 提交前需要自我检查 ## 前置信息 - 需要审查的代码范围diff 或文件列表 ## 执行步骤 1. 获取变更文件列表 2. 逐个文件阅读差异记录疑点 3. 分类汇总逻辑错误 / 安全隐患 / 风格问题 4. 输出结构化审查报告这个结构是最小可用的模板。YAML 头里的name是技能的唯一标识description是给 AI 看的“何时该用这个技能”的说明——description 写得好不好直接决定 AI 会不会在恰当的时候主动调用它。我后来在写技能时常犯的毛病是 description 写得太泛比如“这个技能用于代码审查”AI 判断不了什么场景该触发使用率就很低。改成“适用于 merge request 前或 push 前”之后调用率明显提升。3.2 技能的设计原则小而专、可验证我自己写技能包踩过几个坑总结出三条经验。第一技能粒度要小。一个技能只做一件事。比如“生成提交信息”是一个技能“完成整个功能开发”就不应该是一个技能而应该是一个 agent 编排多个技能。技能太大AI 的注意力会被拆散执行效果反而差。第二步骤必须可验证。每步最好都有明确的产出或检查动作比如“运行构建命令并确认返回码为 0”“查看日志确认无 ERROR 级别输出”。AI 代理和真人一样没有验收标准的步骤它会敷衍过去。第三使用前置信息显式列出。在 SKILL.md 里写清楚“开始前需要知道什么”这能避免 AI 在信息不足时强行开干。比如写“升级依赖”技能前置信息必须包括“当前依赖版本”“目标版本”“是否有锁文件”AI 就会先去收集齐这些再动手。3.3 用 Agents 组合多技能完成复杂任务单个技能解决的是单点问题真实开发里你需要的往往是“一个完整功能的交付”设计技术方案、写代码、补测试、跑构建、写提交信息、更新文档。superpowers 的 agent 机制就是干这个的。我自建了一个feature-developeragent它绑定了 6 个技能analyze-existing-code理解现有代码、design-approach设计方案、implement-changes实现、run-tests跑测试、write-commit-message生成提交信息、update-docs更新文档。我还给它配了一个专门的AGENTS.md里面写了这个 agent 的“人设”比如“每一步必须跑测试不通过不能进行下一步”“变更范围超过 5 个文件时必须先跟你确认”。在我实际跑一个“给项目加缓存层”的任务时这个 agent 的行为和默认 Codex 完全不同它先分析了现有数据访问层然后主动给出了缓存方案让我确认确认后才动代码写完自动跑了原有测试来验证不破坏功能最后生成的提交信息把改动原因写得清清楚楚。整个过程我只参与了三次确认这在以前不可能——默认的 Codex 会直接上手改代码改完也不测试等你自己发现。注意agent 不是用得越多越好。任务简单时直接交互反而更快。agent 适合那些流程固定、需要多步骤协作的重复性任务。判断标准很简单如果一件事你每次都要跟 AI 说同样的步骤那就应该做成 agent。4. Java 项目实战用 superpowers 做“分析—改进—验证”闭环4.1 定义目标让 AI 对遗留代码做结构性改进看到热搜里有人问 superpowers 在 Java 场景怎么用我专门拿一个遗留 Spring Boot 项目试了一轮。场景是这样项目里有一个老旧的OrderService核心业务逻辑全堆在一个 800 行的方法里测试覆盖几乎没有。我的目标是让 AI 帮我梳理逻辑、拆出独立方法并提出改进建议——注意我没让它直接改先让它分析和建议。我预先准备了一个java-refactor技能包包含三类技能analyze-java-structure、design-refactor-plan、apply-refactor。每个技能的SKILL.md都写了详细的执行步骤和验收标准。实际操作时我在 Codex CLI 里启动该 agent让它执行analyze-java-structure它先是读取了pom.xml确认项目依赖然后用find定位相关源码再用grep找出方法内的关键业务分支。最让我意外的是它不止分析了单个类还自动追踪了调用方和依赖服务输出的分析报告里画出了方法调用的依赖链用文字描述这比我手动梳理还仔细。4.2 Java 技能包的编写要点编译器和测试就是最好的验收标准Java 项目相比前端项目有个天然优势有编译器兜底、有成熟的测试框架。所以在编写 Java 相关技能时我把“跑编译”和“跑测试”作为硬性验收门槛。比如apply-refactor技能的执行步骤里我明确要求每完成一步重构必须立刻运行mvn -q compile有编译错误就必须回退到上一个状态重新思考所有重构结束后必须跑一遍完整的mvn test保证原有功能不回退。这里有个值得分享的细节让 AI 分步执行编译验证而不是全部改完再编译。AI 改完一个方法后立刻编译错误定位准确、修复成本低如果让它一口气重构五个方法再编译报错时它要面对的是“哪个改动引入了问题”的定位难题很容易陷入反复试错。实际效果如何AI 最后把那个 800 行的方法拆成了 7 个私有方法每个都有清晰的单一职责并且生成了 4 个针对核心分支的单元测试。中间我唯一一次人工介入是它设计的分拆方案里把两个原本共享局部变量的逻辑段拆得太碎破坏了原有的事务边界——这种业务语义层面的判断AI 在没有充分领域知识时确实容易想当然。所以 Java 场景里尤其建议先让它出方案你确认边界再放它改。4.3 复合技能把常规流程固化成可复用资产做完这次实战之后我把整套流程固化成了一个java-feature-deliveryagent分析现有代码 → 输出设计方案 → 确认 → 实现 → 编译 → 补测试 → 全量验证 → 生成提交信息。现在但凡要在这个项目里加新功能我直接调用它它自己就按这个流程走不需要我重复交代。这里建议你把团队常用的开发流程也做成技能包沉淀到 Git 仓库里。比如“接入新的第三方 API”的流程、“修复线上 Bug”的排查路径、“数据库迁移脚本的编写规范”——每一类重复劳动都值得固化成技能。技能不是一次性的提示词模板它是会随着项目经验迭代的资产越用越值钱。5. 常见问题与排查技巧实录5.1 常见问题速查表问题现象可能原因排查方案技能包加载了但 AI 不按技能执行SKILL.md 的 description 写得过于笼统AI 判断不了触发时机重写 description加入触发场景关键词和具体示例技能执行到一半中断上下文过长AI 丢失了早期步骤信息在 SKILL.md 里给关键步骤加上“需显式确认的信息”栏目避免 AI 过度收集信息AI 修改范围超出预定边界技能前置信息里没有限定变更范围在 SKILL.md 开头加一句“只处理 XXX不得改动 XXX”的硬约束编译/测试失败后 AI 反复试错缺少回退机制在步骤中明确写“若编译失败回退到最近一次可用状态并输出原因而不是继续修改”Windows 下技能路径失效路径分隔符或权限问题使用 WSL 运行 Codex技能包放在 Linux 文件系统内避免/mnt/c路径的权限坑代理输出的提交信息不符合规范缺少提交信息模板在技能里把模板直接写进去并附上正例与反例5.2 我认为最值得记住的排查思路遇到 AI 行为不符合预期时先别急着改代码或者重装工具第一件事是打开它实际读到的技能内容看一眼——你可以让它直接输出“你当前的技能包内容是什么”通常能立刻发现它读错文件、路径拼接错误、或者读到了缓存的旧版本技能。另外我给所有技能目录都加了CHANGELOG.md每次修改技能都会记录日期和改动原因。听起来麻烦但对排查特别有用——当项目行为突然变化时回看技能变更记录经常能一秒定位问题。如果你和团队成员共享技能包仓库这个习惯还能避免“有人偷偷改了技能导致全员行为变化”的混乱。提示技能包是活的随项目演进要持续维护。一个半年没更新过的技能包很可能已经在拖 AI 的后腿了。每个迭代周期花一点时间审查技能是否还符合当前项目状态收益远超成本。6. 从工具到方法论让 AI 编程代理真正“懂规矩”我在实际使用 superpowers 这段时间最大的感触是它没有给 AI 增加任何“新能力”但让 AI 的每一次输出都变得更可控、更可预期。技术原理拆开讲并不复杂——把人的经验结构化、文档化然后让模型像读操作手册一样去执行。这套思路价值很大因为技能包一旦沉淀下来就是团队集体智慧的结晶不依赖某一个工程师的记忆也不会在人员流动时流失。如果你现在正用着 Codex CLI 或者类似的 AI 编程代理我强烈建议你从克隆官方技能包开始先跑通一遍然后试着把你自己最常做的一件事写成技能。不用一开始就搞复杂的 agent一个简单的SKILL.md就能让你体会到“AI 按规矩办事”和“AI 自由发挥”之间的区别。最后再分享一个小技巧给你的技能包写README.md里面记录这个技能包解决的问题、使用场景和常见误区。这不是写给别人看的是写给三个月后的自己看的。技能包数量一多没有导航文档的情况下连你自己都会忘记里面装了些什么。 superpowers：为Codex CLI打造可复用技能包，让AI编程代理更可控
最近在折腾 Codex CLI 的时候我挖到了一个叫 superpowers 的项目最初以为只是又一个给 AI 编程工具打补丁的小插件结果花了一晚上读完文档、配好环境、跑了两个真实项目之后我发现它改变的是我使用 AI 编程代理的整套方式。如果你手里也在用 Codex 这类终端里的 AI 编程工具并且经常觉得 AI 写出来的代码“单看没问题、放进项目就变味”那这篇东西大概率能帮你把工具真正盘活。我会从 superpowers 是什么、为什么值得装、怎么装、怎么写自己的技能包、再到 Java 项目里的实战一条线讲清楚最后附上我踩过的坑和排查思路。先说结论superpowers 不是某个编程语言框架也不是代码生成器它是给 AI 编程代理比如 Codex CLI加装“可复用技能”的增强层。打个比方原版 Codex 像一个专业扎实但没带项目经验的新人你把需求丢给它它能把代码写出来但不知道你们组的代码规范、不知道测试怎么组织、遇到编译错误只会盯着日志发呆。而 superpowers 做的事情就是把一个“资深工程师的干活习惯”沉淀成 Markdown 格式的技能手册让 AI 按着手册走流程。这不是给它多装点上下文而是给它一套完整的工作方法论。如果你是 AI 编程工具的日常用户、团队的 AI 工程效率负责人或者单纯对“怎么让 AI 写代码更可控”这件事感兴趣这篇文章应该能给你一套可以直接抄作业的方案。下面我从设计原理开始拆。1. 核心设计拆解superpowers 解决的是“流程缺失”而非“能力缺失”1.1 为什么 AI 编程代理总在“局部正确、全局翻车”用 Codex CLI 写过几次真实需求的人应该都有同感单看它生成的函数命名规范、注释齐全、边界处理到位但一旦把它放进整个项目里问题就来了——它不知道你们的目录规范、不理解现有模块的依赖关系、也不会主动去跑测试给自己“验货”。这不是模型能力不够而是交互方式有问题。你给它的是一次性提示词它回你一段一次性代码两个人之间根本没有“重复使用的合作流程”。superpowers 的设计出发点就是补上这一环把 AI 编程代理从一个“问答工具”改造成一个“按流程办事的执行者”。它的核心机制是技能包Skills每个技能包是一组 Markdown 文件以SKILL.md为入口里面写清楚“什么时候该用这个技能”“使用前要收集哪些信息”“处理流程分几步”“每一步的验收标准是什么”。AI 在运行时会读取这些文件把自己“代入”到一套标准工作流里。我在实际使用中的体会是这相当于给 AI 配了一本“操作手册”。新人入职时你给他讲一遍业务、丢给他几个需求文档他能干但经常干得歪歪扭扭可你要是把团队规范、典型任务的执行步骤都写成文档他照着做质量立刻稳定一个档次。superpowers 就是把这种“文档化团队经验”的做法搬到了 AI 代理身上。1.2 为什么用 Markdown 而不是写死在代码里我第一次看到技能包全是.md文件时也愣了一下不该是 JSON 配置或者 Python 脚本吗后来细想才发现这是最合理的设计。第一Markdown 是人类可读、AI 也读得最稳的格式。模型对自然语言的指令理解远好于对复杂 JSON 结构的关系推断与其让 AI 去“解析配置”不如直接让它“读手册”。第二修改技能不需要改代码、不需要重新构建、更不需要升级主程序编辑一个文本文件就能让 AI 的行为发生改变迭代成本极低。第三技能包天然适合 Git 管理团队的技能沉淀可以像代码一样评审、分支、回滚这点对企业落地太重要了。另外superpowers 把技能包组织成了三层结构skills/存放通用小型技能比如“写提交信息”“做代码审查”agents/存放完整的代理角色定义每个 agent 可以带一组技能面向完整任务commands/存放斜杠命令Slash Commands让你在 Codex CLI 里直接通过/skill-name触发特定流程。这个分层本质上是把“经验”按粒度拆开小技能是积木agent 是组装好的机器人命令是遥控器。1.3 渐进式披露避免“一口气碾压上下文”superpowers 还有一个很关键的机制叫渐进式披露Progressive Disclosure。简单说AI 一开始不会把整本手册全部塞进上下文而是先读取SKILL.md这个入口文件了解技能概览需要执行具体步骤时再去读对应章节的详细文件。这样做的好处有两个一是节省 Token二是不让 AI 被海量信息干扰保持对核心任务的专注度。这个设计思路我特别认可。在我的使用经验里一次性给 Codex 几千行项目文档它反而会“看花了眼”——重点信息被淹没指令权重被稀释。渐进式披露相当于给 AI 一个“先看目录、再看正文”的阅读路径信息是按需加载的不是一锅端。2. 安装与基础配置从零把 superpowers 跑起来2.1 环境准备先确认你的底子在动手安装之前先确认你的机器满足这几个条件缺一个后面都会卡住。系统macOS、Linux、Windows通过 WSL都行我是在 macOS 13 上跑的流程最顺。Codex CLIsuperpowers 主要面向 Codex CLI 这类 AI 编程代理确保你已经装好并能正常使用。安装命令一般是npm install -g openai/codex装完先跑一次codex确认能正常对话。Node.js 18Codex CLI 依赖 Node 环境版本太低会被拒。Git拉取技能包仓库要用到。提示如果你日常用的是其他支持技能包机制的 AI 编程工具部分开源代理也兼容类似格式思路完全一样只是配置文件位置略有差异。本文以 Codex CLI 为主。2.2 拉取技能包仓库官方技能包集合是直接以 Git 仓库形式分发的。我用的典型流程是# 找个干净目录存放技能包 mkdir -p ~/.codex/skills cd ~/.codex/skills # 克隆官方技能包仓库 git clone https://github.com/worksolutions/superpowers.git仓库克隆下来之后你会看到里面有skills/、agents/、commands/三个主要目录。先别急着改东西进去把结构浏览一遍心里有个数。装好之后还需要让 Codex CLI 知道“去哪里找技能包”。这一步以 Codex 的配置文件为准通常是在~/.codex/config.toml里添加技能包路径或者在 Codex CLI 的启动参数里指定。如果你用的是默认配置可以在config.toml中加入[experimental] skills_path /Users/你的用户名/.codex/skills/superpowers注意这里的路径一定要写成绝对路径用~有时候解析不到。配置完重启 Codex CLI技能包机制就会加载。2.3 验证是否生效怎么确认技能包被成功加载了最简单的方式是在 Codex CLI 里输入斜杠命令比如/superpowers如果能看到技能列表输出就说明加载成功。此时让它做一个简单任务比如用 /delegate 技能帮我列出当前目录的 git 状态观察它是否先输出“正在读取技能包…”之类的中间过程如果是说明它已经进入“按技能干活”的模式。我在这一步遇到过一个问题技能列表能看到但实际调用不生效。后来排查发现是路径写错了——我复制文档时带了一个尾随空格解析直接失败。所以配置路径时务必检查空格和大小写。3. 核心实操编写你自己的技能包3.1 SKILL.md 的结构YAML 头 Markdown 正文学习 superpowers 的最好方式不是读教程而是拆一个现成的技能包看结构。我拆解了仓库里的code-review技能它的SKILL.md长这样--- name: code-review description: 对代码变更进行系统性审查发现逻辑错误、安全隐患和风格问题。适用于 merge request 或 push 前。 --- # Code Review 技能 ## 触发场景 - 用户要求“审查代码”“看看这次改动有没有问题” - 提交前需要自我检查 ## 前置信息 - 需要审查的代码范围diff 或文件列表 ## 执行步骤 1. 获取变更文件列表 2. 逐个文件阅读差异记录疑点 3. 分类汇总逻辑错误 / 安全隐患 / 风格问题 4. 输出结构化审查报告这个结构是最小可用的模板。YAML 头里的name是技能的唯一标识description是给 AI 看的“何时该用这个技能”的说明——description 写得好不好直接决定 AI 会不会在恰当的时候主动调用它。我后来在写技能时常犯的毛病是 description 写得太泛比如“这个技能用于代码审查”AI 判断不了什么场景该触发使用率就很低。改成“适用于 merge request 前或 push 前”之后调用率明显提升。3.2 技能的设计原则小而专、可验证我自己写技能包踩过几个坑总结出三条经验。第一技能粒度要小。一个技能只做一件事。比如“生成提交信息”是一个技能“完成整个功能开发”就不应该是一个技能而应该是一个 agent 编排多个技能。技能太大AI 的注意力会被拆散执行效果反而差。第二步骤必须可验证。每步最好都有明确的产出或检查动作比如“运行构建命令并确认返回码为 0”“查看日志确认无 ERROR 级别输出”。AI 代理和真人一样没有验收标准的步骤它会敷衍过去。第三使用前置信息显式列出。在 SKILL.md 里写清楚“开始前需要知道什么”这能避免 AI 在信息不足时强行开干。比如写“升级依赖”技能前置信息必须包括“当前依赖版本”“目标版本”“是否有锁文件”AI 就会先去收集齐这些再动手。3.3 用 Agents 组合多技能完成复杂任务单个技能解决的是单点问题真实开发里你需要的往往是“一个完整功能的交付”设计技术方案、写代码、补测试、跑构建、写提交信息、更新文档。superpowers 的 agent 机制就是干这个的。我自建了一个feature-developeragent它绑定了 6 个技能analyze-existing-code理解现有代码、design-approach设计方案、implement-changes实现、run-tests跑测试、write-commit-message生成提交信息、update-docs更新文档。我还给它配了一个专门的AGENTS.md里面写了这个 agent 的“人设”比如“每一步必须跑测试不通过不能进行下一步”“变更范围超过 5 个文件时必须先跟你确认”。在我实际跑一个“给项目加缓存层”的任务时这个 agent 的行为和默认 Codex 完全不同它先分析了现有数据访问层然后主动给出了缓存方案让我确认确认后才动代码写完自动跑了原有测试来验证不破坏功能最后生成的提交信息把改动原因写得清清楚楚。整个过程我只参与了三次确认这在以前不可能——默认的 Codex 会直接上手改代码改完也不测试等你自己发现。注意agent 不是用得越多越好。任务简单时直接交互反而更快。agent 适合那些流程固定、需要多步骤协作的重复性任务。判断标准很简单如果一件事你每次都要跟 AI 说同样的步骤那就应该做成 agent。4. Java 项目实战用 superpowers 做“分析—改进—验证”闭环4.1 定义目标让 AI 对遗留代码做结构性改进看到热搜里有人问 superpowers 在 Java 场景怎么用我专门拿一个遗留 Spring Boot 项目试了一轮。场景是这样项目里有一个老旧的OrderService核心业务逻辑全堆在一个 800 行的方法里测试覆盖几乎没有。我的目标是让 AI 帮我梳理逻辑、拆出独立方法并提出改进建议——注意我没让它直接改先让它分析和建议。我预先准备了一个java-refactor技能包包含三类技能analyze-java-structure、design-refactor-plan、apply-refactor。每个技能的SKILL.md都写了详细的执行步骤和验收标准。实际操作时我在 Codex CLI 里启动该 agent让它执行analyze-java-structure它先是读取了pom.xml确认项目依赖然后用find定位相关源码再用grep找出方法内的关键业务分支。最让我意外的是它不止分析了单个类还自动追踪了调用方和依赖服务输出的分析报告里画出了方法调用的依赖链用文字描述这比我手动梳理还仔细。4.2 Java 技能包的编写要点编译器和测试就是最好的验收标准Java 项目相比前端项目有个天然优势有编译器兜底、有成熟的测试框架。所以在编写 Java 相关技能时我把“跑编译”和“跑测试”作为硬性验收门槛。比如apply-refactor技能的执行步骤里我明确要求每完成一步重构必须立刻运行mvn -q compile有编译错误就必须回退到上一个状态重新思考所有重构结束后必须跑一遍完整的mvn test保证原有功能不回退。这里有个值得分享的细节让 AI 分步执行编译验证而不是全部改完再编译。AI 改完一个方法后立刻编译错误定位准确、修复成本低如果让它一口气重构五个方法再编译报错时它要面对的是“哪个改动引入了问题”的定位难题很容易陷入反复试错。实际效果如何AI 最后把那个 800 行的方法拆成了 7 个私有方法每个都有清晰的单一职责并且生成了 4 个针对核心分支的单元测试。中间我唯一一次人工介入是它设计的分拆方案里把两个原本共享局部变量的逻辑段拆得太碎破坏了原有的事务边界——这种业务语义层面的判断AI 在没有充分领域知识时确实容易想当然。所以 Java 场景里尤其建议先让它出方案你确认边界再放它改。4.3 复合技能把常规流程固化成可复用资产做完这次实战之后我把整套流程固化成了一个java-feature-deliveryagent分析现有代码 → 输出设计方案 → 确认 → 实现 → 编译 → 补测试 → 全量验证 → 生成提交信息。现在但凡要在这个项目里加新功能我直接调用它它自己就按这个流程走不需要我重复交代。这里建议你把团队常用的开发流程也做成技能包沉淀到 Git 仓库里。比如“接入新的第三方 API”的流程、“修复线上 Bug”的排查路径、“数据库迁移脚本的编写规范”——每一类重复劳动都值得固化成技能。技能不是一次性的提示词模板它是会随着项目经验迭代的资产越用越值钱。5. 常见问题与排查技巧实录5.1 常见问题速查表问题现象可能原因排查方案技能包加载了但 AI 不按技能执行SKILL.md 的 description 写得过于笼统AI 判断不了触发时机重写 description加入触发场景关键词和具体示例技能执行到一半中断上下文过长AI 丢失了早期步骤信息在 SKILL.md 里给关键步骤加上“需显式确认的信息”栏目避免 AI 过度收集信息AI 修改范围超出预定边界技能前置信息里没有限定变更范围在 SKILL.md 开头加一句“只处理 XXX不得改动 XXX”的硬约束编译/测试失败后 AI 反复试错缺少回退机制在步骤中明确写“若编译失败回退到最近一次可用状态并输出原因而不是继续修改”Windows 下技能路径失效路径分隔符或权限问题使用 WSL 运行 Codex技能包放在 Linux 文件系统内避免/mnt/c路径的权限坑代理输出的提交信息不符合规范缺少提交信息模板在技能里把模板直接写进去并附上正例与反例5.2 我认为最值得记住的排查思路遇到 AI 行为不符合预期时先别急着改代码或者重装工具第一件事是打开它实际读到的技能内容看一眼——你可以让它直接输出“你当前的技能包内容是什么”通常能立刻发现它读错文件、路径拼接错误、或者读到了缓存的旧版本技能。另外我给所有技能目录都加了CHANGELOG.md每次修改技能都会记录日期和改动原因。听起来麻烦但对排查特别有用——当项目行为突然变化时回看技能变更记录经常能一秒定位问题。如果你和团队成员共享技能包仓库这个习惯还能避免“有人偷偷改了技能导致全员行为变化”的混乱。提示技能包是活的随项目演进要持续维护。一个半年没更新过的技能包很可能已经在拖 AI 的后腿了。每个迭代周期花一点时间审查技能是否还符合当前项目状态收益远超成本。6. 从工具到方法论让 AI 编程代理真正“懂规矩”我在实际使用 superpowers 这段时间最大的感触是它没有给 AI 增加任何“新能力”但让 AI 的每一次输出都变得更可控、更可预期。技术原理拆开讲并不复杂——把人的经验结构化、文档化然后让模型像读操作手册一样去执行。这套思路价值很大因为技能包一旦沉淀下来就是团队集体智慧的结晶不依赖某一个工程师的记忆也不会在人员流动时流失。如果你现在正用着 Codex CLI 或者类似的 AI 编程代理我强烈建议你从克隆官方技能包开始先跑通一遍然后试着把你自己最常做的一件事写成技能。不用一开始就搞复杂的 agent一个简单的SKILL.md就能让你体会到“AI 按规矩办事”和“AI 自由发挥”之间的区别。最后再分享一个小技巧给你的技能包写README.md里面记录这个技能包解决的问题、使用场景和常见误区。这不是写给别人看的是写给三个月后的自己看的。技能包数量一多没有导航文档的情况下连你自己都会忘记里面装了些什么。