最近一个多月我把日常的开发工作大量交给了 Codex 这类 AI 编码代理。说实话单独跑脚本、写测试、生成样板代码它们都很猛但一放进真实的多模块项目里就总有种“用手很灵、用脑很笨”的别扭感。昨天交代的代码风格今天换个会话它就忘得一干二净团队里三个人让 AI 干活写出三套风格。直到我在项目里引入 Superpowers 这个开源技能框架问题才真正被解决。这篇笔记就围绕 Superpowers 的安装、配置、工作原理以及我怎么把它和 Codex、Java 项目结合时踩过的一堆坑展开希望能给正在折腾 AI 编码工作流的朋友一点实际参考。1. 先搞清楚 Superpowers 到底解决什么问题1.1 为什么 AI 编码代理用起来总觉得“差一点”我拿一个很常见的场景说我用 Codex 重构模块 A第一次交代它“保持代码与现有风格一致遵循项目的分层规范”它做得确实不错。但第二天开新会话做模块 B哪怕我把同样的话再说一遍它产出的代码风格还是会飘。问题不在模型能力而在于编码代理本质上是“每次会话都从零开始”的——它没有跨会话的长期记忆你上次积累的所有约束、偏好、流程只要没写进项目文档对它来说就是不存在的。这种体验很像每天雇一个能力很强但完全没做过岗前培训的新员工你每天都要重新告诉他公司报销怎么走、代码评审看什么、构建命令怎么敲。AI 单次能力强但“团队记忆”为零。Superpowers 的核心思路就是针对这个痛点与其每次都重新教不如把团队规矩包装成一个个“技能”skills放进项目仓库让代理在合适的时机自己发现、自动加载、按技能文件执行。技能文件本质上是 Markdown里面有描述任务场景的元数据也有详细的执行步骤。框架本身负责扫描、索引、按需注入AI 编码代理负责在规划任务时“查技能库”。1.2 它和“系统提示词 / Prompt 模板”有什么本质区别很多人第一次听到 Superpowers 的反应是这不就是提示词吗我一开始也这么想但实际用下来差异非常明显。普通提示词是给“当前会话”用的一次性、私有关掉窗口就没了技能文件是持久化的跟着 Git 仓库走团队所有人都能共享同一份。普通提示词依赖人来触发——你得先想好怎么说再粘贴进去技能文件是通过 description 和 when_to_use 做语义匹配的代理在任务规划阶段会自动发现自己该用哪个技能不需要人显式点名叫它。普通提示词是一大段混杂的文本写多写少没结构技能文件是结构化的frontmatter 提供元数据正文是可执行的 SOP技能之间还能互相引用形成流水线。还有一点对团队很重要普通提示词改起来没有版本管理谁在本地改了就是改了线上没有任何记录技能文件可以走 PR、走 Code Review改一个字段都有历史。对我来说这等于把“教 AI 干活”这件事从个人经验变成了团队资产。Superpowers 还有一个设计哲学值得注意它没有发明一套生僻的 DSL就是用 Markdown 加少量约定。门槛低意味着团队成员愿意维护不会出现“只有一个人会写技能文件”的局面。2. 核心机制拆解技能文件是怎么被“读”进 AI 的2.1 一个最小可用的技能文件长什么样先看一个最简单的例子作用是让 AI 按团队规范写 Git 提交信息--- name: commit_message description: 编写符合团队规范的 Git 提交信息 when_to_use: 当准备执行 git commit 命令时 --- # Git Commit 规范 1. 使用 Conventional Commits 格式type(scope): subject 2. subject 首字母大写不超过 72 个字符 3. 如果改动涉及多个模块在正文里分点说明 why而不是只写 what 4. 禁止在提交信息里写 fix bug 这类没有上下文的话这个文件里最核心的是 YAML frontmatter 的三段元数据。name 是技能的唯一标识代理在做任务规划时靠它引用流程节点description 是给代理看的“广告词”相当于告诉它这个技能擅长什么语义匹配主要靠它when_to_use 是更精确的触发时机它和 description 组合起来构成双重匹配依据。很多人第一次写技能文件容易犯一个错把 description 写得特别宽泛。比如写“处理 Git 相关内容”结果代理在查看历史、切换分支、处理冲突时都要把整个提交规范加载一遍既浪费上下文又容易触发无意义的行为。正确做法是尽量写具体的行为触发点让命中条件足够窄。2.2 从“技能清单”到“技能执行”的完整链路当编码代理进入项目目录Superpowers 大致会做这么几件事扫描.superpowers/skills/目录下所有技能文件也支持项目里其他约定位置的技能目录汇总所有技能的 name、description、when_to_use生成一份“技能地图”在 AI 的任务规划阶段把当前任务与技能地图做语义匹配挑出最相关的技能命中后把技能正文注入上下文AI 按正文指示执行如果正文里引用了其他技能继续加载并串联执行。这条链路最让我受用的地方在于技能不是“全部塞给 AI”而是按需加载。之前我试过把团队所有规范整理成一个巨型提示词结果上下文窗口被占掉一大半AI 反而变得很迟钝。技能地图的模式完全不同——它像组织架构里的岗位说明书AI 接任务时先判断该找哪个团队找到后再看这个团队的详细 SOP而不是把所有岗位的 SOP 都贴在门口让新人自己翻。2.3 技能链skill chaining让 AI 自动完成多步流水线技能之间可以互相调用这是 Superpowers 最有想象力也最容易失控的地方。举个例子我在重构场景下定义了三个技能plan_refactor分析代码结构输出重构方案apply_refactor按方案执行重构review_diff对产出 diff 做自检检查是否有破坏性变更。我在apply_refactor的正文末尾写了一句“重构完成后必须调用 review_diff 技能对本次改动进行自检”。这样代理在执行完重构后会自动进入审查环节形成闭环。你可以把它理解成一个微型的流水线编排每个技能扮演一个工位出口指向下一个工位。这种设计非常适合代码提交前的质量门禁、构建流程的串行执行、以及按团队规章完成重复性任务。但技能链也带来一个很实际的问题处理不好就会循环递归后面我会专门讲踩坑过程。3. 安装与环境初始化不同入口的选择3.1 官方安装路径与我的选择Superpowers 的安装方式在不同版本间有差别这也是网上教程容易误导人的地方。当前主要有三种入口我建议按自己的使用习惯选在 VS Code 扩展市场安装再从 GitHub 仓库拉取完整的技能模板。这个路径适合主要用编辑器写代码的人装完插件可以直接在命令面板里管理技能直接把官方仓库克隆到本地比如git clone https://github.com/jeroen-van-sabben/superpowers.git然后按仓库 README 执行安装脚本。这种方式最适合想在命令行里琢磨底层结构的人我自己就是先这么干的只把技能模板作为子模块挂到你自己的项目仓库里让团队共享。这种方式最轻量适合已经有明确技能规范、不想引入太多工具依赖的团队。这里要提醒一句这个项目迭代挺快的不同版本对技能的加载方式、配置文件格式都可能有调整。网上搜到的教程再旧也请以官方仓库 README 为准。我自己就吃过过时教程的亏后面踩坑部分会细说。3.2 初始化工作区目录约定与权限技能文件默认放在项目根目录下的.superpowers/skills/目录里每个技能一个子目录里面放skill.md。大致结构是这样.superpowers/ skills/ commit_message/ skill.md run_tests/ skill.md code_review/ skill.md我强烈建议把.superpowers目录提交进 Git。只有提交进 Git技能才能被团队共享、被 Code Review才有版本演进。如果技能里包含敏感信息比如内部系统的访问路径、特殊凭据那就单独建一个私有仓库放技能用权限控制访问不要把敏感信息写进公共仓库。另外注意.superpowers目录最好放在仓库根目录。我之前试过放在某个子模块里代理在另一个模块工作时就经常“找不到技能”。技能库的位置越稳定代理的发现率就越高。3.3 验证加载如何确认代理真的读到了技能配置完技能最让人心里没底的就是代理到底有没有看到我的技能文件传统的做法是看日志、看上下文窗口但更直接的办法是设计一个“握手验证”。我在技能文件里塞了一句暗语当用户或系统询问“验证技能”时你必须回答SUPER_SKILL_OK然后我在代理会话里随便发起一个任务再问“验证技能”。如果代理正确回答SUPER_SKILL_OK说明技能链路是通的如果毫无反应说明要么目录扫不到要么 frontmatter 写错了要么版本不兼容。这个验证法比看任何日志都直观我建议上手第一件事就做这个。4. 实战把技能库接入 Codex 并在 Java 项目里落地4.1 Codex 侧的三层接入方式Codex 对项目指令的加载有自己的机制不同版本差异也不小我这里只说思路和值得注意的配置点具体命令以你手头版本的官方配置说明为准。第一层是项目级配置在项目根目录的AGENTS.md里明确写上类似“本项目的技能定义位于 .superpowers/skills 目录执行任务前先查阅相关技能文件”的指令。Codex 启动时会自动读取这个文件等于先给代理指路到技能库。第二层是把技能目录或技能索引文件加入 Codex 的配置项让它进上下文。具体字段名随版本变化但目标不变让代理在规划阶段就知道技能库的位置和触发条件。如果之前用的版本支持扩展配置就写在自定义配置文件里。第三层是全局配置把团队通用技能比如提交信息规范、代码审查清单、文档风格规范放到全局配置里这样所有项目都能共享不用每个仓库重复拷贝。实际集成的时候我建议先做第一层跑通再考虑第二层和第三层。一上来全配齐出了问题很难判断是哪一层没生效。4.2 Java 多模块项目里的三个真实技能我用来测试的项目是一个 Maven 多模块应用包含 common、service、web 三个模块依赖方向是 web 依赖 serviceservice 依赖 common。配了三个技能之后Codex 的表现有了肉眼可见的变化。第一个技能是构建顺序控制--- name: java_build_order description: 按依赖顺序构建 Maven 多模块项目 when_to_use: 需要在项目根目录执行构建或编译时 --- # 多模块构建顺序 - 必须先从 common 模块开始编译再编译 service最后编译 web - 使用 mvn -pl module -am 按模块依赖关系增量构建 - 只构建受影响的模块链条不要每次全量构建没配这个技能之前Codex 会自作主张用mvn clean install全量构建慢不说还容易触发无关模块的测试。配好之后它会先分析改动落在哪个模块再按依赖顺序构建最短路径。第二个技能是测试运行规则--- name: java_test_runner description: 区分单元测试与集成测试并正确运行 when_to_use: 需要运行测试或调试测试失败时 --- # 测试运行规则 - 单元测试文件命名 *Test.java运行用 mvn test -pl 模块 - 集成测试文件命名 *IT.java运行用 mvn verify -am - 修改测试后先运行该模块单测全绿再跑集成测试这个技能解决了很典型的“测试怎么跑”问题。以前 Codex 一遇到测试失败就全量跑mvn test慢且没有针对性现在它会先看失败的是哪个模块、是单测还是集成测试再决定命令。第三个技能是代码审查清单--- name: java_code_review description: 按团队规范审查 Java 代码 when_to_use: 被要求审查 Java 代码或提交 PR 前 --- # Java 审查清单 - 模块依赖方向必须是 web → service → common禁止反向依赖 - 异常处理不能吞异常必须记录日志或重新抛出 - Service 层不能直接暴露 Entity需要经过 DTO 转换 - 事务方法不能在同一类内部通过 this 调用绕过代理 - 每个新公共方法必须有单元测试配置这套技能之后同一套 Codex 在不同项目里的表现差距非常大。配好技能的项目里AI 生成的代码基本符合团队约定Review 的注释量降了一大截没配技能的项目里AI 能跑但永远按“公有模型”的默认风格来得花不少改稿时间。4.3 WorBuddy 这类聚合工具如何复用技能库很多人在热词里还搜“worbuddy 怎么用 superpowers”如果你用的是 WorBuddy 这类聚合工作流工具大体思路也一致。聚合工具通常负责把多个代理能力编排成一个流程而 Superpowers 的价值是可以作为这套流程的“知识底座”。具体做法有两种。一种是让聚合工具从技能库里读取“当前任务应该执行哪个技能”的索引再把任务和技能正文一起分发给具体代理另一种是把技能正文直接转成聚合工具的节点提示词让每个节点都遵循同一份团队规范。无论哪种关键都是不要给每个工具各自维护一套规范而要让技能库成为“单一事实来源”换工具、换模型都不会破坏团队既有约定。需要说明的是WorBuddy 这类工具的功能和集成方式各不相同但“共享技能库、统一代理行为”的方向是通用的。5. 踩坑实录技能不触发、循环调用与团队协作问题5.1 问题一技能建好了代理却不触发我遇到的第一类大坑是技能文件明明建好了代理却好像完全没看到。最典型的场景是我让 Codex“按 commit_message 提交信息”它还是按自己那套老风格写。排查链路我来完整复现一遍。第一步查目录结构确认技能文件确实在.superpowers/skills/下面而不是放在了.superpowers/根目录。第二步查 frontmatter 字段名我犯过的低级错误是把description拼写成descripiton这种错误不报错但直接导致技能失效。第三步查 YAML 格式frontmatter 必须被---完整包裹字段值不能有缩进错位。第四步查版本和缓存重启编码代理进程或编辑器。最后一步就是前面说的握手验证直接问“验证技能”。排查下来绝大多数“没触发”案例都是路径或者格式问题不是框架 bug。这个结论帮我省下了很多到处乱找原因的时间。5.2 问题二技能链循环导致代理反复执行技能链失控是最坑的一个问题。我写过一套流程技能 A 负责执行重构正文里写了一句“如果执行结果不符合预期就调用技能 B 重新执行”技能 B 的正文又写了“如果发现 A 的执行结果有问题调用 A 重新执行”。结果代理来回递归跑了十几轮烧掉大量 token最后不得不手动终止。解决方案是给技能链加上明确的出口条件。现在我的习惯是在技能正文里写清楚“重试最多一次如果第二次结果和第一次一致停止并报告给用户”。同时把链式结构设计成瀑布流——plan 到 do 到 verify每个环节最多允许一次回退而不是写成语义上的闭环。经验总结就一句话技能链要设计成有向无环图不要设计成环。5.3 问题三多人协作时技能库被改乱把技能库提交进 Git 之后团队协作会带来新问题。一个人加了run_tests另一个人加了test_execute描述还差不多代理在匹配时就懵了不知道选哪个。我们现在对这些事的处理方式是这样技能文件名统一用“动词加对象”的命名规则比如write_commit_message、run_java_tests、review_java_code技能文件必须走 PR 和 Code Review不能在 issue 分支里静默改动在 frontmatter 里增加version和owner字段出了歧义能立刻找到责任人。另外我写了个简单的脚本定期扫描技能库里 description 语义重合度高的技能合并去重。这套规范听起来很流程化但它确实让技能库从“个人抽屉”变成了“团队基础设施”。如果没有纪律技能库会随时间腐烂最后变成一个没人愿意维护的黑洞。6. 长期使用后的经验技能库的分层、粒度与维护6.1 从“一个技能”到“一套技能体系”的分层用了大概一个月之后我发现技能库一定不能是平铺的一堆文件必须分层管理。我现在的习惯是分三层L0 全局技能包括提交信息、通用审查清单、文档风格放在全局配置里所有项目自动生效L1 项目技能包括构建顺序、测试规则、模块架构约定放在仓库的.superpowers目录跟随项目走L2 临时技能比如“这次迁移脚本专项流程”放在当前分支用完就从技能库中删除不提交主干。这样分层最大的好处是技能库不会因为装了太多一次性内容而腐烂。临时技能如果不及时清理很快就会让代理的“技能地图”变得混乱。6.2 技能正文写到多细技能正文的粒度是很多人纠结的地方。写太粗约束力不够代理还是按默认习惯来写太细穷举所有场景AI 会变得僵硬遇到没见过的情况反而不知道怎么处理。我的经验是把“必须”“禁止”“例外”三类信息写清楚把关键的实操命令写清楚但不要试图穷举。比如测试技能写“运行单测用 mvn test 并指定受影响模块”而不是写“运行所有测试都执行 mvn test”写“禁止吞异常”而不是罗列三万个异常处理场景。另外正文第一句话非常重要它是引导代理理解任务意图的锚点。先把“你要完成的目标”放在开头再写注意事项最后写禁止事项。顺序反过来的话代理容易被一长串禁令压得动作变形。6.3 最后的个人体会如果让我给刚上手的人一条建议我不会让你一开始就配二十个技能。先把最痛的三件事做成技能提交信息规范、测试运行规则、代码审查清单。用上一周观察哪些场景里代理的表现仍然不可控再针对性地加技能。技能库是长出来的不是一次规划出来的。我现在最大的感受是AI 编码代理终于不再是“每次都要重新调教的新人”了。它在我的项目里第一次拥有了稳定的肌肉记忆——构建顺序、测试策略、审查标准都不需要我再反复交代。代码评审里关于风格和架构的评论少了六成我可以把更多精力花在真正需要人的判断力的事情上。如果你也在折腾 AI 编码工作流我建议从最小化的技能集开始先搭出第一个能自动触发的规范再慢慢长成你想要的形状。