如果你也在用 Codex CLI或者习惯把 AI 编程代理当成结对程序员大概率会有一种感受默认的代理确实能写代码但总像隔着一层窗户纸——让它改一个跨文件逻辑它只会在当前文件里打转让它跑测试它跑完就完事不懂得根据失败信息往回改让它规划任务它列出的步骤又大又空根本没法执行。superpowers 就是来捅破这层窗户纸的它不是一个新的 IDE也不是某个大模型而是一套专门给 Codex 这类 AI 编程代理准备的“技能增强包”。装上之后代理会拥有更结构化的思考方式、更完整的工具调用链以及一套可复用的高质量工作流。这篇文章我会从安装开始把原理、配置、Java 项目实战、WorBuddy 接入和排坑经验一次讲透适合所有想让 AI 真正“多干活、少返工”的开发者。1. superpowers 到底是什么给 AI 编程代理装上“超能力”1.1 我为什么开始折腾 superpowers我最早接触 superpowers是因为一次相当痛苦的 Codex 使用经历。当时我接手一个中型 Spring Boot 项目业务逻辑散落在十几个 Service 和 Repository 里我让 Codex 帮忙把订单查询逻辑改成分页加条件组合。它第一轮很顺畅地改了OrderService里的一个方法但跑测试后报错 — 因为OrderRepository里根本没有对应的查询接口而它完全没有意识到需要去改 Repository。我把报错信息贴回去它才开始“反思”然后东一榔头西一棒子地改用了七八轮才把整个链路打通。后来我在社区看到有人提到 “codex superpowers”一开始以为又是一个噱头满满的 prompt 合集。但真正安装完之后我才发现它和普通提示词不一样它不是让 AI“变得聪明”而是围绕 AI 代理的执行流程做了一套标准化约束。比如它要求代理在动手前先输出计划要求每个变更都必须有测试承载要求跨文件修改前先梳理依赖关系。这些约束听起来简单但恰恰是日常使用中 AI 最容易偷懒的地方。我把这套东西在本地跑了两周最直观的感受是返工率下降。以前让 Codex 改一个功能我需要在旁边盯着每一步都要确认现在它可以按一个相对固定的节奏自己往前走遇到测试失败会主动回退或修复而不是反复生成看似正确、实则跑不通的代码。这让我开始认真研究它的内部结构也有了后面这篇文章里的大量实操记录。1.2 它解决的三个核心痛点第一个痛点是“跨文件修改能力弱”。大模型本身没有项目全局视角它只能通过读取多个文件的内容来拼凑上下文。默认状态下Codex 更倾向于在当前打开的上下文里做局部修改很少主动去翻阅其他相关文件。superpowers 通过工作流规则强制要求代理在改动前建立“影响面清单”哪些文件会被改、哪些依赖会被破坏、哪些调用方需要同步调整全部列出来之后再动手。这就像给代理加了一张项目地图而不是让它闭着眼钻胡同。第二个痛点是“测试驱动无法闭环”。很多开发者让 AI 写代码其实只是让 AI“写完代码后顺便跑一下测试”但一旦测试失败AI 经常不知道下一步该做什么。superpowers 的核心技能之一就是把测试当成第一等公民先写失败测试再写实现代码再重构测试不通过实现代码就不算完成。它把这条 TDD 流程固化成代理的内部步骤大幅度降低了“AI 以为写完了实际上根本没跑通”的情况。第三个痛点是“计划与执行脱节”。默认 Codex 给出的任务计划往往是“增加一个接口、实现一个服务、测试一下”这种粒度根本没法执行。superpowers 要求计划必须包含具体的文件路径、方法签名、数据流向和预期结果并且每完成一步就做一次验证。这个变化看着小实际用起来差别巨大计划能落地代理的执行效率至少翻一倍。1.3 适用人群与适用场景如果你属于下面这几类人我比较推荐你花一晚上把 superpowers 装起来试试。第一类是个人开发者或独立接单者你需要一个能在你睡觉时继续捣鼓代码的“数字员工”但又不希望它把项目拆得七零八落。superpowers 的结构化工作流能让它在有限权限内按部就班地干活。第二类是中小型技术团队的负责人你希望 AI 能自动处理重复性较高的需求比如接口字段调整、单元测试补齐、报错日志分析节省团队时间。第三类是刚接触 AI 编程代理的新手你需要一条清晰的路径来理解“提示词、技能、代理”之间的关系superpowers 本身就是一个很好的学习样本。场景上它特别适合有明确验收标准、有测试环境、需要多文件协作的工程任务。比如“给支付模块增加一个新的优惠码类型”、“把某个工具类从 A 包迁移到 B 包”、“所有列表接口统一返回分页结构”这类任务只要喂给 superpowers它往往比手动写提示词稳定很多。反而是一些纯创意型、探索型需求比如“帮我想想这个架构要不要改成微服务”它帮不上什么忙也不适合让它跑这跑那。提示不要把 superpowers 当成“万能 AI”。它的价值在于约束执行路径而不是提升模型智能。模型本身的能力上限决定最终质量superpowers 能确保你现有的模型能力被用到八分以上而不是三分。2. 安装与初始化一份可以直接抄的配置清单2.1 安装前的环境准备安装 superpowers 之前你需要先把基础环境准备好。最核心的是 Codex CLI——不管你是用 npm 全局安装的 codex还是本地编译的二进制版本都需要确认版本不要太老。我建议至少使用最近半年内更新的版本因为太老的版本对AGENTS.md和工具调用的支持不完整。其次需要 Node.js 运行时。superpowers 本身很多技能脚本是用 Node 写的通过本地命令或 npx 调用所以 Node 版本建议在 18 以上。另外还需要 Git 用来拉取技能库以及能正常访问 npm registry 和 GitHub 的网络环境。这里有一点要提前说明国内网络访问这些资源有时候会比较慢你可以在终端里先设置好镜像源或者直接配置好代理反正只要能拉取到代码就行。最后建议准备一个干净的测试项目。不要在正式项目里第一次使用 superpowers因为你还没熟悉它的工作方式它可能会给你生成一堆预料之外的文件。我就是先在一个只有几个类的 Demo 项目里跑通流程才敢拿到真实项目里用的。2.2 安装 superpowers 的具体步骤安装过程并不复杂。不同版本和分支的安装方式有些差异我这里以社区里最常见的 npm 全局安装方式为准再补充一种 git 源码方式。如果你只想快速体验直接执行npm install -g superpowers superpowers initinit命令会在当前用户目录下生成默认的~/.superpowers配置目录并把 Codex 的全局配置指向这里。执行完之后你可以用superpowers doctor检查一下环境是否就绪它会逐项检查 Node 版本、Codex 版本、目录权限和 AGENTS.md 是否能被正确读取。如果你想手动控制版本建议用 Git 克隆方式git clone https://github.com/yourname/superpowers.git ~/.superpowers然后把你的 Codex 配置里加上一行指定代理在启动时读取这个目录下的指令文件{ instructions: ~/.superpowers/AGENTS.md, skills: ~/.superpowers/skills }这里需要注意instructions指向的是全局指令也就是 Codex 每次会话开始都会自动加载的内容skills指向的是技能包目录代理在执行过程中可以按需读取里面的文件。两行配置缺一不可少了instructions代理不知道有技能包这回事少了skills代理就算读了指令也找不到对应的流程细节。2.3 初始化配置与目录结构跑完superpowers init之后你会得到一个类似下面的目录结构~/.superpowers/ ├── AGENTS.md ├── skills/ │ ├── plan.md │ ├── research.md │ ├── test-driven.md │ ├── refactor.md │ ├── commit.md │ └── review.md ├── scripts/ │ ├── run-tests.js │ ├── find-deps.js │ └── summarize.js └── config.jsonAGENTS.md是整个体系的入口。它类似于 Codex 的“人设 工作准则”告诉代理遇到任何需求先进入plan流程计划通过后再进入test-driven流程涉及跨文件修改时必须调用find-deps.js生成依赖清单。所有技能文件都是 Markdown 格式里面除了文字说明还包括少量示例代码和给代理的“触发条件”。config.json用来控制行为开关比如是否强制跳过测试、是否允许自动提交、最大单轮读取文件数等。我建议把autoCommit先设为false等熟悉之后再打开。自动提交听着省事但如果你没时间看提交信息很容易留下一堆“chore: fix”之类的无效提交记录。初始化完成之后你要做的第一件事不是直接上真实需求而是跑一次自检。你可以随便打开一个项目目录启动 Codex输入“请帮我分析当前项目的结构”看它是否会自动读取AGENTS.md并输出规划步骤。如果它依然像以前一样直接回答说明配置的读取路径有问题需要回到 2.2 节检查路径。2.4 安装过程中的常见坑安装过程中最典型的问题有三个。第一superpowers命令找不到。这种情况绝大多数是 npm 全局目录没有加入 PATH。运行npm config get prefix看全局安装路径然后把bin目录加进.zshrc或.bashrc即可。不要为了省事直接sudo npm install -g权限问题会贯穿整个使用过程非常烦人。第二Codex 启动时不读取AGENTS.md。这可能是因为你使用的 Codex 版本还不支持instructions字段或者配置文件格式不正确。建议先在 Codex 里输入AGENTS这个词看它的返回里有没有出现你写入的规则。如果完全没有多半是配置键名拼错了或者~没有展开成绝对路径。第三技能脚本无法执行。有些技能需要依赖node子进程调用外部命令如果项目里有特殊权限设置或者 npm 包缺失会报Permission denied。这时需要给对应脚本加上执行权限chmod x ~/.superpowers/scripts/*.js。如果你用的是 Windows注意别用 PowerShell 直接跑 bash 脚本最好通过 Codex 内置的 Node 环境执行。3. 核心机制拆解superpowers 是如何增强 Codex 的3.1 技能包与 AGENTS.md 的关系很多第一次接触 superpowers 的人会问这跟往系统提示词里塞一大堆“你要怎么做”有什么区别区别非常大。普通提示词是“一次性指令”代理读取之后就丢在上下文里很容易被后续对话冲淡而 superpowers 采用的是“主指令 按需读取子技能”的组合模式。AGENTS.md只负责“路由”当代理面对一个需求时它先判断这是计划类、实现类、重构类还是调试类任务然后打开对应的技能文件读取里面的详细步骤。技能文件里甚至可以包含代码示例、命令行参数、失败处理策略这些东西如果全部塞进主提示词上下文早就爆了。所以超级技能包的真正设计精髓是“分层加载”只有当前任务需要的指令才会被代理读取。比如你让它加一个新接口它会先读plan.md花几分钟把接口路径、参数、返回结构、影响模块都列清楚等你确认计划后它再读test-driven.md开始写测试一实现一重构的循环。如果任务里需要跨文件搜索它还会调用scripts/find-deps.js来定位依赖。这种机制让每次对话的有效上下文利用率更高也减少了无关指令对模型判断的干扰。3.2 关键技能模块逐个解读我反复用的几个核心技能模块值得单独说说。plan.md是第一个会被调用的技能。它的核心要求是任何任务开始前必须输出一个包含具体文件路径和验收条件的执行计划。它甚至会规定计划的最小粒度比如“不得出现‘优化相关代码’这种模糊描述必须写明是哪个目录、哪个方法、为什么改”。有了这个约束Codex 就不再空谈方案而是直接给出可执行任务表。test-driven.md是最能提升代码质量的一个模块。它要求代理严格遵循“红-绿-重构”循环先写一个会失败的测试再写让测试通过的最小实现代码最后清理重复逻辑。执行过程中如果测试失败代理不是直接改代码而是先分析失败原因并记录然后才动手。这听起来很像人类的 TDD 习惯但在 AI 编程代理里能做到这么严谨主要靠的是流程强制。refactor.md负责代码重构。它和普通“让 AI 改代码”最大的区别在于代理必须先跑一遍现有测试确认基线是绿的然后给每个重构步骤设置一个验证点。比如“把OrderService中的calculateTotal方法提取为PriceCalculator”这个过程不是一步到位而是每移动一个方法就运行一次测试。这种慎重的操作方式极大地减少了“重构完整个项目就崩了”的情况。commit.md负责提交信息规范化。我一开始觉得这功能很鸡肋后来发现它其实是在为整个工作流收尾。代理在完成功能后会按照约定格式生成提交信息并附上行数变化摘要和测试结果。这让 Git 历史变得非常好读尤其在回顾 AI 做了什么改动的时候作用特别大。3.3 提示词与工作流设计逻辑superpowers 的底层逻辑其实可以总结成一句大白话把“让 AI 自由发挥”改成“让 AI 按工程工序干活”。它背后是标准的软件工程方法只是被转换成了代理能执行的步骤。这种设计有一个很明显的好处出现问题时你能快速定位是“哪一步”出的问题而不是像以前那样盯着模型生成的代码猜心思。比如代理生成的代码跑不过测试你可以让它输出“当前执行到 TDD 的哪一步失败输入是什么”它自然会按照技能包里的模板回答而不会东拉西扯。另一个逻辑是“小步快跑”。AI 代理最容易被长流程带节奏做着做着就忘了最初的目标。superpowers 把任务拆成多个短周期每个周期结束都要有可见产物。这种设计思路和敏捷开发里的迭代非常像我发现它对长任务的效果尤其明显。如果一个需求预计要改 20 个文件不要让代理一口气改完而是让它分批改、分批验证往往更稳妥。3.4 它是怎么做到跨文件重构的跨文件重构是很多 AI 编程代理的软肋superpowers 在这里下了不少功夫。它会在重构开始前调用依赖分析脚本扫描整个项目里的 import、方法调用和继承关系生成一张依赖清单。这张清单会告诉代理A.java里的OrderService被B.java、C.java引用如果我把OrderService的方法签名改掉这两个调用方必须同步更新。有了这个清单代理就不会只改一个文件然后问你“其他地方要不要改”。在实际执行时superpowers 会按照“依赖倒置”的顺序来改先改底层被依赖的文件再改上层调用方。每改一层就编译或者跑一次相关测试。如果某个文件改动引发编译错误代理会立即回滚这个文件的改动重新分析差异而不是继续往下改。这正是它能实现“稳定重构”的关键也是我在 Java 项目里最看重的能力。4. 实战用 superpowers 完成一个 Java 项目的功能迭代4.1 准备一个最小 Java 项目为了演示我准备了一个非常小的 Maven 项目只有一个订单模块。项目结构大致是这样order-service/ ├── pom.xml └── src/ ├── main/java/com/example/order/ │ ├── Order.java │ ├── OrderRepository.java │ └── OrderService.java └── test/java/com/example/order/ └── OrderServiceTest.javaOrder是实体类包含订单号、金额和状态OrderRepository负责存储OrderService提供查询和创建订单的方法。初始代码非常简单public class Order { private String id; private BigDecimal amount; private String status; // getter / setter 省略 } public interface OrderRepository { OptionalOrder findById(String id); void save(Order order); }我故意让OrderService里有一段不太规范的手写分页逻辑用来测试 superpowers 的跨文件重构能力。在启动 Codex 之前我先确认项目能够通过mvn test确保基线是绿色的。这个动作很重要否则后面没法判断问题是 superpowers 造成的还是原本就存在的。4.2 让 superpowers 读需求并拆分任务我输入的需求是请为订单模块增加一个按状态查询的能力要求支持分页 并按金额从高到低排序。请走完整计划流程。superpowers 读完需求后没有直接写任何代码而是先输出了一个计划。计划里包含这些内容修改Order实体类增加状态字段的查询条件修改OrderRepository新增一个findByStatus方法返回列表而不是单条修改OrderService引入分页参数并做倒序在测试类里增加三个场景包括空列表、正常分页、金额倒序验证。它还特意标注了哪些文件会被新建哪些是修改哪些调用方需要同步检查。我看到计划简洁到可以直接用就回复了一个“按计划执行”。这一步是我使用 superpowers 后变化最大的一点以前我总要在 AI 开工前花十分钟手动解释需求边界现在它自己会把边界理清楚我只负责判断计划对不对。如果计划有偏我会直接改计划里的某一项而不是重新描述整个需求。4.3 从失败测试开始TDD 流程跑通按照超级技能包里的test-driven.md代理开始写测试。它先写了一个失败的测试Test void shouldReturnOrdersFilteredByStatusAndSortedByAmountDesc() { OrderRepository repo new InMemoryOrderRepository(); OrderService service new OrderService(repo); repo.save(new Order(1, new BigDecimal(100.00), PAID)); repo.save(new Order(2, new BigDecimal(200.00), PAID)); repo.save(new Order(3, new BigDecimal(50.00), CREATED)); ListOrder result service.findByStatus(PAID, 0, 10); assertEquals(2, result.size()); assertEquals(2, result.get(0).getId()); assertEquals(1, result.get(1).getId()); }运行测试预期结果是失败的因为findByStatus还不存在。接着代理开始实现OrderRepository的新方法把OrderService里的逻辑接上再跑测试。测试变绿后它又停下来做了一次小重构把分页参数封装成一个PageRequest对象。整个过程没有跳出 TDD 的圈子我几乎没有插嘴。这里我想特别说一下如果你希望 AI 代理帮你写代码最忌讳的是一上来就让它“先实现再补测试”。superpowers 为什么强调先写测试因为测试是代码行为的锚点。先有了锚点AI 后续做任何重构都不容易跑偏。也正是因为这个流程我对 AI 生成代码的信任度提高了很多。4.4 代码审查与自动修复功能实现之后superpowers 没有立刻结束而是进入了review.md流程。它会重新读一遍刚才改过的文件检查是否有明显的代码异味、边界条件漏判、重复逻辑。我观察到它检查出两个问题第一金额倒序排序时没有处理null金额第二分页参数没有做负数校验。针对这两个问题它给出了修复建议并询问我是否直接修改。我同意后它又走了一遍测试确认没有回归。这种“完成功能后再审自己一遍”的行为在默认 Codex 里很少出现。默认代理写完就停跟人写完代码不自查一样superpowers 则把代码审查也变成了标准流程的一部分。如果你愿意还可以让 superpowers 生成一份代码审查报告内容包括改动文件列表、主要风险点、测试覆盖率变化以及建议人工关注的逻辑。这个报告直接贴在 PR 描述里能省不少沟通成本。4.5 Java 项目里的注意事项Java 项目跟脚本语言项目不太一样有几个地方特别值得注意。第一Maven 或 Gradle 的构建速度会影响代理的反馈循环。如果每改一次代码都要等 30 秒编译TDD 流程就会很慢。我建议在本地配置好增量编译或者干脆用mvn -o离线模式让依赖解析不反复走网络。第二Lombok 这类注解处理器可能会让代理困惑。因为 getter 和 setter 在源码里不存在代理容易误判字段不可访问。如果你的项目用了 Lombok最好在AGENTS.md里加一行说明“项目使用 Lombok所有 DTO 和实体类的 getter/setter 由编译期生成”。否则你会看到代理试图自己补 getter 的尴尬场面。第三包结构要清晰。superpowers 的跨文件分析脚本高度依赖 import 关系如果包结构混乱、类之间循环依赖分析结果会很难看。如果你有一个历史包袱很重的模块建议先让代理执行一次依赖梳理再开始实际改动。第四Java 的泛型和检查异常比较啰嗦代理容易生成过度设计。比如一个简单查询方法它可能会给你套上CompletableFuture加Optional加 Builder 模式。遇到这种情况不用死磕直接让它“保持当前项目风格”它会参考现有代码的结构重新生成。5. 在 WorBuddy 等工具中使用 superpowers不止 Codex5.1 WorBuddy 是什么为什么也要接 superpowers除了 Codex 之外我现在也会在 WorBuddy 里用 superpowers。WorBuddy 是一款集成多种 AI 代理和本地脚本的工作台工具你可以把它理解成“AI 技能的管理器”它能加载不同的技能目录把提示词、脚本、执行路径组合成一套可复用的工作流。它的界面比终端友好很多适合不想整天敲命令行的人。在 WorBuddy 里接入 superpowers 的理由很简单项目里积累的技能包不应该只属于某一个命令行工具。团队里有人用 Codex有人用其他代理冗余的技能定义会导致行为不一致。把 superpowers 作为统一的技能库所有工具都按同一套标准执行团队协作会顺畅很多。5.2 接入方法与配置差异接入方法并不复杂。WorBuddy 通常支持在设置里指定“skills 目录”和“AGENTS 文件”。你只需要把~/.superpowers的路径填进去或者把技能目录软链到 WorBuddy 的配置目录下ln -s ~/.superpowers/skills ~/worbuddy/skills/superpowers然后在 WorBuddy 里新建一个项目设置默认指令文件为~/.superpowers/AGENTS.md。这里有一个配置差异要留意Codex 是“每轮对话动态读取技能文件”WorBuddy 可能是“启动时加载全部技能索引”。这意味着如果你在 superpowers 的技能包里新增了一个模块在 WorBuddy 里可能需要重启会话或者刷新索引才能生效。别问我是怎么知道的——我改完技能没刷新在那边干等了半小时一度以为接错了。另外WorBuddy 的权限模型跟 Codex 不一样。它允许你给每个技能单独设置“可执行命令白名单”。我建议给 superpowers 里的脚本只开放必要的 Node 执行权限不要让它默认能调用任意 bash 命令。安全边界还是要把握好。5.3 统一技能库的管理建议如果你打算在团队里推广 superpowers建议用 Git 仓库统一管理技能库。把AGENTS.md和整个skills/目录放进一个私有仓库然后让每位开发者通过 Git 拉取到本地。更新技能时直接git pull就能同步。技能库的文件命名和版本管理也很重要。我自己的习惯是每个技能文件开头都写明适用版本、维护人和触发条件变更比较大的技能增加v2、v3后缀避免代理读取到冲突定义。你可能觉得这有点过度规范但一旦技能数量超过 10 个没有版本控制一定会乱。最后建议团队里指定一个人负责“技能评审”。不是所有 AI 生成的技能都能进库要有一个能判断流程是否合理的人把关。不然你会在仓库里看到各种互相矛盾的“超能力”没人知道哪个是对的。6. 常见问题与排查技巧实录6.1 技能没生效先看这几处我踩过最多次的坑是 superpowers 装好了结果 Codex 完全不按技能库流程走。遇到这种情况先别卸载重建按下面顺序排查。第一确认AGENTS.md真的被加载了。在 Codex 会话里输入“请列出你当前需要遵守的核心规则”看看它输出的内容是否包含超级技能包里的条目。如果它输出的是“我是一只好用的编程助手”说明配置路径没生效。第二检查当前工作目录。Codex 会优先读取项目根目录下的AGENTS.md如果项目里恰好有一个同名文件覆盖了全局配置superpowers 的规则就不会被加载。解决办法是让全局配置优先级更高或者在项目文件里显式引入 superpowers 的规则。第三检查技能文件的命名是否正确。Codex 触发技能的机制常常是按文件名匹配的。比如要求“计划”时代理会找plan.md如果你的文件名写成planning.md它可能压根找不到。用默认模板初始化技能库是最稳妥的不要为了“更好看”随便改文件名。6.2 上下文太长、响应变慢怎么办superpowers 会提升上下文利用率但不可能把上下文无限变大。如果你做的是一个超大项目代理每轮都要读十几份文件很快上下文就会被塞满响应速度也会明显变慢。第一个解决办法是拆分任务。不要在一轮对话里让代理“分析全项目”又“实现新功能”。先用计划技能生成一份任务清单然后一个任务一个任务地执行。每个任务结束后你可以开一个新会话把当前完成进度和下一步目标贴进去。这种做法的效率往往比硬撑一个长会话高得多。第二个办法是善用脚本里的summarize.js。当你觉得上下文要爆的时候让代理先跑这个脚本把已经读过的文件内容压缩成摘要再继续后面的步骤。它会丢弃一些不重要的细节但保留关键接口和依赖关系。第三个办法是给代理“断点续传”能力。每个技能文件末尾加上一句话“如果会话上下文即将耗尽请输出一条简洁进度报告包含已完成任务、待完成任务和风险点然后建议用户开启新会话。”这听起来很土但确实管用。6.3 多语言项目的适配技巧superpowers 虽然对 JavaScript/TypeScript 和 Java 支持得比较好但也能用到 Python、Go、Rust 等项目里。关键在于你需要在AGENTS.md里声明项目的语言和构建工具。比如 Python 项目里代理跑测试用的是pytest不是mvn test如果你不告诉它它可能会尝试运行一个根本不存在的 Maven 命令。你可以这样写规则- 测试命令: pytest tests/ - 代码风格: black isort - 禁止在未通过 lint 的情况下提交代码Go 项目则可以声明go test ./...和gofmt风格。你甚至可以为一个仓库里同时存在的多个子项目各自定义测试命令skill 包会按照当前目录识别应该使用哪条规则。这里面容易忽略的一点是语言版本也会影响代理的判断。比如 Python 项目用 type hintsJava 项目用记录类型还是传统 POJO都需要在技能库里写清楚。我建议你上手就把这些工程约定写进AGENTS.md不要等踩坑之后再补。6.4 安全与权限设置超级技能包本质上是在给 AI 代理更大操作权限因此安全这根弦不能松。首先是命令执行权限。我希望你千万不要给代理任意执行终端命令的权限尤其是rm -rf、git push --force这类高危操作。superpowers 的官方技能里默认没有这些操作但万一你自己写了一个自定义技能要格外小心。其次是敏感信息的保护。不要把数据库密码、API Key 这些内容写进AGENTS.md或 skill 文件里。代理可能会在日志中输出这些内容或者在你的团队之间被复制传播。如果确实需要连接数据库做验证建议通过环境变量注入并让代理不要输出具体值。最后是人审。superpowers 不是一个“无人驾驶”系统它优化的是执行效率但代码评审和最终确认仍然必须由人类完成。我见过不少人完全信任 AI 生成的测试断言结果断言本身写错了功能也错了测试照样绿。所以无论 AI 多厉害代理在你自主可控的环境里跑就对了。6.5 问题速查表现象可能原因解决方法代理完全不按技能流程走AGENTS.md 路径未生效检查 Codexinstructions配置输入提示词验证技能文件读到了但不触发文件名与代理预期不匹配使用默认技能文件名避免改名跨文件改动时漏改调用方依赖分析脚本未运行手动执行find-deps.js并核对依赖清单测试失败后代理死循环缺少失败处理策略在 skill 文件中增加“重试上限和回退规则”响应明显变慢上下文过长用 summarize 脚本压缩或拆分新会话在 WorBuddy 中看不到新技能索引未刷新重启 WorBuddy 会话或手动刷新技能索引Java 项目构建失败Maven 依赖不全或离线模式先跑一次mvn dependency:resolve再执行任务7. 我的实操心得与后续扩展7.1 启用前后效率对比说实话我刚开始用 superpowers 那两天并没有觉得效率提升多少因为光是理解它的工作流和调目录权限就花了不少时间。但用了一周以后我明显感觉到“顺手”了。以前一个“给列表接口加分页”的小需求用 Codex 默认模式从改代码到修完测试大概要浪费十到二十分钟现在同样的需求直接在计划里拆好代理一次写完测试我只需要花几分钟做代码审查。返工率低了沟通成本也低了。有一个数字我记得特别清楚有一次我给一个老项目增加批量导入功能涉及 6 个文件、两处外部 API 调用和一套新的校验逻辑。按照我以前的经验让 AI 自己做至少需要我盯三四个小时。这次我让 superpowers 执行它的标准流程最后只用了大约四十分钟。最关键的是我中间只做了三次打断一次是确认优先级一次是指定日志格式还有一次是让它改用现有的枚举而不是新建枚举。这种体验确实刷新了我对“AI 写代码”这件事的预期。7.2 值得自定义的技能方向内置技能只是起点用好 superpowers 的诀窍是慢慢长出属于你自己的技能库。我这里给你几个我觉得特别值得自定义的方向。第一个是“代码评审技能”。你可以把团队的代码规范写进一个team-review.md要求代理在每次改动后逐项检查是否有硬编码、异常处理是否完整、SQL 是否能走索引、日志是否需要脱敏。这比自己口头强调一百遍管用。第二个是“错误日志分析技能”。让你的代理在 NPE 或者连接超时出现的时候不只是报告错误而是主动读取堆栈上下文、检查相关配置、对比最近改动最后给出可疑根因列表。我试过在一个 Spring Boot 项目里用它排查偶发 500 错误它把代码里一个空指针隐患给揪出来了省了我半天时间。第三个是“文档同步技能”。很多项目代码和文档脱节严重你可以让 superpowers 在功能变更后自动更新对应的 README 或接口文档。要把握好度不要让它在不能确定准确性的时候随意生成文档但给一个清晰的“变更后同步更新”规则还是靠谱的。7.3 最后一点建议如果你问我 superpowers 到底值不值得花一晚上去折腾我会说非常值得但要带着一颗平常心去用它。它不是魔法不会让你的 AI 从 GPT-4 变成“超级智能体”它的价值在于把 AI 编程代理的随机性变成工程效率的可预期性。你需要先接受一个前提AI 生成的代码依然需要人来负责但它能替你完成大量重复、繁琐、需要多文件联动的体力活。我个人在最开始安装的时候建议大家先从一个小项目入手先跑通计划、TDD、重构这三个核心流程再考虑接入 WorBuddy 这类工具。等你熟悉了它的工作方式你会发现真正的“超能力”不是它替你做了多少事而是它让你把精力从“盯着 AI 改 bug”中解放出来留给了真正需要判断力和创造力的部分。希望这篇分享能帮你在 AI 编程代理这条路上少踩几个坑多省几根白头发。
如果你也在用 Codex CLI或者习惯把 AI 编程代理当成结对程序员大概率会有一种感受默认的代理确实能写代码但总像隔着一层窗户纸——让它改一个跨文件逻辑它只会在当前文件里打转让它跑测试它跑完就完事不懂得根据失败信息往回改让它规划任务它列出的步骤又大又空根本没法执行。superpowers 就是来捅破这层窗户纸的它不是一个新的 IDE也不是某个大模型而是一套专门给 Codex 这类 AI 编程代理准备的“技能增强包”。装上之后代理会拥有更结构化的思考方式、更完整的工具调用链以及一套可复用的高质量工作流。这篇文章我会从安装开始把原理、配置、Java 项目实战、WorBuddy 接入和排坑经验一次讲透适合所有想让 AI 真正“多干活、少返工”的开发者。1. superpowers 到底是什么给 AI 编程代理装上“超能力”1.1 我为什么开始折腾 superpowers我最早接触 superpowers是因为一次相当痛苦的 Codex 使用经历。当时我接手一个中型 Spring Boot 项目业务逻辑散落在十几个 Service 和 Repository 里我让 Codex 帮忙把订单查询逻辑改成分页加条件组合。它第一轮很顺畅地改了OrderService里的一个方法但跑测试后报错 — 因为OrderRepository里根本没有对应的查询接口而它完全没有意识到需要去改 Repository。我把报错信息贴回去它才开始“反思”然后东一榔头西一棒子地改用了七八轮才把整个链路打通。后来我在社区看到有人提到 “codex superpowers”一开始以为又是一个噱头满满的 prompt 合集。但真正安装完之后我才发现它和普通提示词不一样它不是让 AI“变得聪明”而是围绕 AI 代理的执行流程做了一套标准化约束。比如它要求代理在动手前先输出计划要求每个变更都必须有测试承载要求跨文件修改前先梳理依赖关系。这些约束听起来简单但恰恰是日常使用中 AI 最容易偷懒的地方。我把这套东西在本地跑了两周最直观的感受是返工率下降。以前让 Codex 改一个功能我需要在旁边盯着每一步都要确认现在它可以按一个相对固定的节奏自己往前走遇到测试失败会主动回退或修复而不是反复生成看似正确、实则跑不通的代码。这让我开始认真研究它的内部结构也有了后面这篇文章里的大量实操记录。1.2 它解决的三个核心痛点第一个痛点是“跨文件修改能力弱”。大模型本身没有项目全局视角它只能通过读取多个文件的内容来拼凑上下文。默认状态下Codex 更倾向于在当前打开的上下文里做局部修改很少主动去翻阅其他相关文件。superpowers 通过工作流规则强制要求代理在改动前建立“影响面清单”哪些文件会被改、哪些依赖会被破坏、哪些调用方需要同步调整全部列出来之后再动手。这就像给代理加了一张项目地图而不是让它闭着眼钻胡同。第二个痛点是“测试驱动无法闭环”。很多开发者让 AI 写代码其实只是让 AI“写完代码后顺便跑一下测试”但一旦测试失败AI 经常不知道下一步该做什么。superpowers 的核心技能之一就是把测试当成第一等公民先写失败测试再写实现代码再重构测试不通过实现代码就不算完成。它把这条 TDD 流程固化成代理的内部步骤大幅度降低了“AI 以为写完了实际上根本没跑通”的情况。第三个痛点是“计划与执行脱节”。默认 Codex 给出的任务计划往往是“增加一个接口、实现一个服务、测试一下”这种粒度根本没法执行。superpowers 要求计划必须包含具体的文件路径、方法签名、数据流向和预期结果并且每完成一步就做一次验证。这个变化看着小实际用起来差别巨大计划能落地代理的执行效率至少翻一倍。1.3 适用人群与适用场景如果你属于下面这几类人我比较推荐你花一晚上把 superpowers 装起来试试。第一类是个人开发者或独立接单者你需要一个能在你睡觉时继续捣鼓代码的“数字员工”但又不希望它把项目拆得七零八落。superpowers 的结构化工作流能让它在有限权限内按部就班地干活。第二类是中小型技术团队的负责人你希望 AI 能自动处理重复性较高的需求比如接口字段调整、单元测试补齐、报错日志分析节省团队时间。第三类是刚接触 AI 编程代理的新手你需要一条清晰的路径来理解“提示词、技能、代理”之间的关系superpowers 本身就是一个很好的学习样本。场景上它特别适合有明确验收标准、有测试环境、需要多文件协作的工程任务。比如“给支付模块增加一个新的优惠码类型”、“把某个工具类从 A 包迁移到 B 包”、“所有列表接口统一返回分页结构”这类任务只要喂给 superpowers它往往比手动写提示词稳定很多。反而是一些纯创意型、探索型需求比如“帮我想想这个架构要不要改成微服务”它帮不上什么忙也不适合让它跑这跑那。提示不要把 superpowers 当成“万能 AI”。它的价值在于约束执行路径而不是提升模型智能。模型本身的能力上限决定最终质量superpowers 能确保你现有的模型能力被用到八分以上而不是三分。2. 安装与初始化一份可以直接抄的配置清单2.1 安装前的环境准备安装 superpowers 之前你需要先把基础环境准备好。最核心的是 Codex CLI——不管你是用 npm 全局安装的 codex还是本地编译的二进制版本都需要确认版本不要太老。我建议至少使用最近半年内更新的版本因为太老的版本对AGENTS.md和工具调用的支持不完整。其次需要 Node.js 运行时。superpowers 本身很多技能脚本是用 Node 写的通过本地命令或 npx 调用所以 Node 版本建议在 18 以上。另外还需要 Git 用来拉取技能库以及能正常访问 npm registry 和 GitHub 的网络环境。这里有一点要提前说明国内网络访问这些资源有时候会比较慢你可以在终端里先设置好镜像源或者直接配置好代理反正只要能拉取到代码就行。最后建议准备一个干净的测试项目。不要在正式项目里第一次使用 superpowers因为你还没熟悉它的工作方式它可能会给你生成一堆预料之外的文件。我就是先在一个只有几个类的 Demo 项目里跑通流程才敢拿到真实项目里用的。2.2 安装 superpowers 的具体步骤安装过程并不复杂。不同版本和分支的安装方式有些差异我这里以社区里最常见的 npm 全局安装方式为准再补充一种 git 源码方式。如果你只想快速体验直接执行npm install -g superpowers superpowers initinit命令会在当前用户目录下生成默认的~/.superpowers配置目录并把 Codex 的全局配置指向这里。执行完之后你可以用superpowers doctor检查一下环境是否就绪它会逐项检查 Node 版本、Codex 版本、目录权限和 AGENTS.md 是否能被正确读取。如果你想手动控制版本建议用 Git 克隆方式git clone https://github.com/yourname/superpowers.git ~/.superpowers然后把你的 Codex 配置里加上一行指定代理在启动时读取这个目录下的指令文件{ instructions: ~/.superpowers/AGENTS.md, skills: ~/.superpowers/skills }这里需要注意instructions指向的是全局指令也就是 Codex 每次会话开始都会自动加载的内容skills指向的是技能包目录代理在执行过程中可以按需读取里面的文件。两行配置缺一不可少了instructions代理不知道有技能包这回事少了skills代理就算读了指令也找不到对应的流程细节。2.3 初始化配置与目录结构跑完superpowers init之后你会得到一个类似下面的目录结构~/.superpowers/ ├── AGENTS.md ├── skills/ │ ├── plan.md │ ├── research.md │ ├── test-driven.md │ ├── refactor.md │ ├── commit.md │ └── review.md ├── scripts/ │ ├── run-tests.js │ ├── find-deps.js │ └── summarize.js └── config.jsonAGENTS.md是整个体系的入口。它类似于 Codex 的“人设 工作准则”告诉代理遇到任何需求先进入plan流程计划通过后再进入test-driven流程涉及跨文件修改时必须调用find-deps.js生成依赖清单。所有技能文件都是 Markdown 格式里面除了文字说明还包括少量示例代码和给代理的“触发条件”。config.json用来控制行为开关比如是否强制跳过测试、是否允许自动提交、最大单轮读取文件数等。我建议把autoCommit先设为false等熟悉之后再打开。自动提交听着省事但如果你没时间看提交信息很容易留下一堆“chore: fix”之类的无效提交记录。初始化完成之后你要做的第一件事不是直接上真实需求而是跑一次自检。你可以随便打开一个项目目录启动 Codex输入“请帮我分析当前项目的结构”看它是否会自动读取AGENTS.md并输出规划步骤。如果它依然像以前一样直接回答说明配置的读取路径有问题需要回到 2.2 节检查路径。2.4 安装过程中的常见坑安装过程中最典型的问题有三个。第一superpowers命令找不到。这种情况绝大多数是 npm 全局目录没有加入 PATH。运行npm config get prefix看全局安装路径然后把bin目录加进.zshrc或.bashrc即可。不要为了省事直接sudo npm install -g权限问题会贯穿整个使用过程非常烦人。第二Codex 启动时不读取AGENTS.md。这可能是因为你使用的 Codex 版本还不支持instructions字段或者配置文件格式不正确。建议先在 Codex 里输入AGENTS这个词看它的返回里有没有出现你写入的规则。如果完全没有多半是配置键名拼错了或者~没有展开成绝对路径。第三技能脚本无法执行。有些技能需要依赖node子进程调用外部命令如果项目里有特殊权限设置或者 npm 包缺失会报Permission denied。这时需要给对应脚本加上执行权限chmod x ~/.superpowers/scripts/*.js。如果你用的是 Windows注意别用 PowerShell 直接跑 bash 脚本最好通过 Codex 内置的 Node 环境执行。3. 核心机制拆解superpowers 是如何增强 Codex 的3.1 技能包与 AGENTS.md 的关系很多第一次接触 superpowers 的人会问这跟往系统提示词里塞一大堆“你要怎么做”有什么区别区别非常大。普通提示词是“一次性指令”代理读取之后就丢在上下文里很容易被后续对话冲淡而 superpowers 采用的是“主指令 按需读取子技能”的组合模式。AGENTS.md只负责“路由”当代理面对一个需求时它先判断这是计划类、实现类、重构类还是调试类任务然后打开对应的技能文件读取里面的详细步骤。技能文件里甚至可以包含代码示例、命令行参数、失败处理策略这些东西如果全部塞进主提示词上下文早就爆了。所以超级技能包的真正设计精髓是“分层加载”只有当前任务需要的指令才会被代理读取。比如你让它加一个新接口它会先读plan.md花几分钟把接口路径、参数、返回结构、影响模块都列清楚等你确认计划后它再读test-driven.md开始写测试一实现一重构的循环。如果任务里需要跨文件搜索它还会调用scripts/find-deps.js来定位依赖。这种机制让每次对话的有效上下文利用率更高也减少了无关指令对模型判断的干扰。3.2 关键技能模块逐个解读我反复用的几个核心技能模块值得单独说说。plan.md是第一个会被调用的技能。它的核心要求是任何任务开始前必须输出一个包含具体文件路径和验收条件的执行计划。它甚至会规定计划的最小粒度比如“不得出现‘优化相关代码’这种模糊描述必须写明是哪个目录、哪个方法、为什么改”。有了这个约束Codex 就不再空谈方案而是直接给出可执行任务表。test-driven.md是最能提升代码质量的一个模块。它要求代理严格遵循“红-绿-重构”循环先写一个会失败的测试再写让测试通过的最小实现代码最后清理重复逻辑。执行过程中如果测试失败代理不是直接改代码而是先分析失败原因并记录然后才动手。这听起来很像人类的 TDD 习惯但在 AI 编程代理里能做到这么严谨主要靠的是流程强制。refactor.md负责代码重构。它和普通“让 AI 改代码”最大的区别在于代理必须先跑一遍现有测试确认基线是绿的然后给每个重构步骤设置一个验证点。比如“把OrderService中的calculateTotal方法提取为PriceCalculator”这个过程不是一步到位而是每移动一个方法就运行一次测试。这种慎重的操作方式极大地减少了“重构完整个项目就崩了”的情况。commit.md负责提交信息规范化。我一开始觉得这功能很鸡肋后来发现它其实是在为整个工作流收尾。代理在完成功能后会按照约定格式生成提交信息并附上行数变化摘要和测试结果。这让 Git 历史变得非常好读尤其在回顾 AI 做了什么改动的时候作用特别大。3.3 提示词与工作流设计逻辑superpowers 的底层逻辑其实可以总结成一句大白话把“让 AI 自由发挥”改成“让 AI 按工程工序干活”。它背后是标准的软件工程方法只是被转换成了代理能执行的步骤。这种设计有一个很明显的好处出现问题时你能快速定位是“哪一步”出的问题而不是像以前那样盯着模型生成的代码猜心思。比如代理生成的代码跑不过测试你可以让它输出“当前执行到 TDD 的哪一步失败输入是什么”它自然会按照技能包里的模板回答而不会东拉西扯。另一个逻辑是“小步快跑”。AI 代理最容易被长流程带节奏做着做着就忘了最初的目标。superpowers 把任务拆成多个短周期每个周期结束都要有可见产物。这种设计思路和敏捷开发里的迭代非常像我发现它对长任务的效果尤其明显。如果一个需求预计要改 20 个文件不要让代理一口气改完而是让它分批改、分批验证往往更稳妥。3.4 它是怎么做到跨文件重构的跨文件重构是很多 AI 编程代理的软肋superpowers 在这里下了不少功夫。它会在重构开始前调用依赖分析脚本扫描整个项目里的 import、方法调用和继承关系生成一张依赖清单。这张清单会告诉代理A.java里的OrderService被B.java、C.java引用如果我把OrderService的方法签名改掉这两个调用方必须同步更新。有了这个清单代理就不会只改一个文件然后问你“其他地方要不要改”。在实际执行时superpowers 会按照“依赖倒置”的顺序来改先改底层被依赖的文件再改上层调用方。每改一层就编译或者跑一次相关测试。如果某个文件改动引发编译错误代理会立即回滚这个文件的改动重新分析差异而不是继续往下改。这正是它能实现“稳定重构”的关键也是我在 Java 项目里最看重的能力。4. 实战用 superpowers 完成一个 Java 项目的功能迭代4.1 准备一个最小 Java 项目为了演示我准备了一个非常小的 Maven 项目只有一个订单模块。项目结构大致是这样order-service/ ├── pom.xml └── src/ ├── main/java/com/example/order/ │ ├── Order.java │ ├── OrderRepository.java │ └── OrderService.java └── test/java/com/example/order/ └── OrderServiceTest.javaOrder是实体类包含订单号、金额和状态OrderRepository负责存储OrderService提供查询和创建订单的方法。初始代码非常简单public class Order { private String id; private BigDecimal amount; private String status; // getter / setter 省略 } public interface OrderRepository { OptionalOrder findById(String id); void save(Order order); }我故意让OrderService里有一段不太规范的手写分页逻辑用来测试 superpowers 的跨文件重构能力。在启动 Codex 之前我先确认项目能够通过mvn test确保基线是绿色的。这个动作很重要否则后面没法判断问题是 superpowers 造成的还是原本就存在的。4.2 让 superpowers 读需求并拆分任务我输入的需求是请为订单模块增加一个按状态查询的能力要求支持分页 并按金额从高到低排序。请走完整计划流程。superpowers 读完需求后没有直接写任何代码而是先输出了一个计划。计划里包含这些内容修改Order实体类增加状态字段的查询条件修改OrderRepository新增一个findByStatus方法返回列表而不是单条修改OrderService引入分页参数并做倒序在测试类里增加三个场景包括空列表、正常分页、金额倒序验证。它还特意标注了哪些文件会被新建哪些是修改哪些调用方需要同步检查。我看到计划简洁到可以直接用就回复了一个“按计划执行”。这一步是我使用 superpowers 后变化最大的一点以前我总要在 AI 开工前花十分钟手动解释需求边界现在它自己会把边界理清楚我只负责判断计划对不对。如果计划有偏我会直接改计划里的某一项而不是重新描述整个需求。4.3 从失败测试开始TDD 流程跑通按照超级技能包里的test-driven.md代理开始写测试。它先写了一个失败的测试Test void shouldReturnOrdersFilteredByStatusAndSortedByAmountDesc() { OrderRepository repo new InMemoryOrderRepository(); OrderService service new OrderService(repo); repo.save(new Order(1, new BigDecimal(100.00), PAID)); repo.save(new Order(2, new BigDecimal(200.00), PAID)); repo.save(new Order(3, new BigDecimal(50.00), CREATED)); ListOrder result service.findByStatus(PAID, 0, 10); assertEquals(2, result.size()); assertEquals(2, result.get(0).getId()); assertEquals(1, result.get(1).getId()); }运行测试预期结果是失败的因为findByStatus还不存在。接着代理开始实现OrderRepository的新方法把OrderService里的逻辑接上再跑测试。测试变绿后它又停下来做了一次小重构把分页参数封装成一个PageRequest对象。整个过程没有跳出 TDD 的圈子我几乎没有插嘴。这里我想特别说一下如果你希望 AI 代理帮你写代码最忌讳的是一上来就让它“先实现再补测试”。superpowers 为什么强调先写测试因为测试是代码行为的锚点。先有了锚点AI 后续做任何重构都不容易跑偏。也正是因为这个流程我对 AI 生成代码的信任度提高了很多。4.4 代码审查与自动修复功能实现之后superpowers 没有立刻结束而是进入了review.md流程。它会重新读一遍刚才改过的文件检查是否有明显的代码异味、边界条件漏判、重复逻辑。我观察到它检查出两个问题第一金额倒序排序时没有处理null金额第二分页参数没有做负数校验。针对这两个问题它给出了修复建议并询问我是否直接修改。我同意后它又走了一遍测试确认没有回归。这种“完成功能后再审自己一遍”的行为在默认 Codex 里很少出现。默认代理写完就停跟人写完代码不自查一样superpowers 则把代码审查也变成了标准流程的一部分。如果你愿意还可以让 superpowers 生成一份代码审查报告内容包括改动文件列表、主要风险点、测试覆盖率变化以及建议人工关注的逻辑。这个报告直接贴在 PR 描述里能省不少沟通成本。4.5 Java 项目里的注意事项Java 项目跟脚本语言项目不太一样有几个地方特别值得注意。第一Maven 或 Gradle 的构建速度会影响代理的反馈循环。如果每改一次代码都要等 30 秒编译TDD 流程就会很慢。我建议在本地配置好增量编译或者干脆用mvn -o离线模式让依赖解析不反复走网络。第二Lombok 这类注解处理器可能会让代理困惑。因为 getter 和 setter 在源码里不存在代理容易误判字段不可访问。如果你的项目用了 Lombok最好在AGENTS.md里加一行说明“项目使用 Lombok所有 DTO 和实体类的 getter/setter 由编译期生成”。否则你会看到代理试图自己补 getter 的尴尬场面。第三包结构要清晰。superpowers 的跨文件分析脚本高度依赖 import 关系如果包结构混乱、类之间循环依赖分析结果会很难看。如果你有一个历史包袱很重的模块建议先让代理执行一次依赖梳理再开始实际改动。第四Java 的泛型和检查异常比较啰嗦代理容易生成过度设计。比如一个简单查询方法它可能会给你套上CompletableFuture加Optional加 Builder 模式。遇到这种情况不用死磕直接让它“保持当前项目风格”它会参考现有代码的结构重新生成。5. 在 WorBuddy 等工具中使用 superpowers不止 Codex5.1 WorBuddy 是什么为什么也要接 superpowers除了 Codex 之外我现在也会在 WorBuddy 里用 superpowers。WorBuddy 是一款集成多种 AI 代理和本地脚本的工作台工具你可以把它理解成“AI 技能的管理器”它能加载不同的技能目录把提示词、脚本、执行路径组合成一套可复用的工作流。它的界面比终端友好很多适合不想整天敲命令行的人。在 WorBuddy 里接入 superpowers 的理由很简单项目里积累的技能包不应该只属于某一个命令行工具。团队里有人用 Codex有人用其他代理冗余的技能定义会导致行为不一致。把 superpowers 作为统一的技能库所有工具都按同一套标准执行团队协作会顺畅很多。5.2 接入方法与配置差异接入方法并不复杂。WorBuddy 通常支持在设置里指定“skills 目录”和“AGENTS 文件”。你只需要把~/.superpowers的路径填进去或者把技能目录软链到 WorBuddy 的配置目录下ln -s ~/.superpowers/skills ~/worbuddy/skills/superpowers然后在 WorBuddy 里新建一个项目设置默认指令文件为~/.superpowers/AGENTS.md。这里有一个配置差异要留意Codex 是“每轮对话动态读取技能文件”WorBuddy 可能是“启动时加载全部技能索引”。这意味着如果你在 superpowers 的技能包里新增了一个模块在 WorBuddy 里可能需要重启会话或者刷新索引才能生效。别问我是怎么知道的——我改完技能没刷新在那边干等了半小时一度以为接错了。另外WorBuddy 的权限模型跟 Codex 不一样。它允许你给每个技能单独设置“可执行命令白名单”。我建议给 superpowers 里的脚本只开放必要的 Node 执行权限不要让它默认能调用任意 bash 命令。安全边界还是要把握好。5.3 统一技能库的管理建议如果你打算在团队里推广 superpowers建议用 Git 仓库统一管理技能库。把AGENTS.md和整个skills/目录放进一个私有仓库然后让每位开发者通过 Git 拉取到本地。更新技能时直接git pull就能同步。技能库的文件命名和版本管理也很重要。我自己的习惯是每个技能文件开头都写明适用版本、维护人和触发条件变更比较大的技能增加v2、v3后缀避免代理读取到冲突定义。你可能觉得这有点过度规范但一旦技能数量超过 10 个没有版本控制一定会乱。最后建议团队里指定一个人负责“技能评审”。不是所有 AI 生成的技能都能进库要有一个能判断流程是否合理的人把关。不然你会在仓库里看到各种互相矛盾的“超能力”没人知道哪个是对的。6. 常见问题与排查技巧实录6.1 技能没生效先看这几处我踩过最多次的坑是 superpowers 装好了结果 Codex 完全不按技能库流程走。遇到这种情况先别卸载重建按下面顺序排查。第一确认AGENTS.md真的被加载了。在 Codex 会话里输入“请列出你当前需要遵守的核心规则”看看它输出的内容是否包含超级技能包里的条目。如果它输出的是“我是一只好用的编程助手”说明配置路径没生效。第二检查当前工作目录。Codex 会优先读取项目根目录下的AGENTS.md如果项目里恰好有一个同名文件覆盖了全局配置superpowers 的规则就不会被加载。解决办法是让全局配置优先级更高或者在项目文件里显式引入 superpowers 的规则。第三检查技能文件的命名是否正确。Codex 触发技能的机制常常是按文件名匹配的。比如要求“计划”时代理会找plan.md如果你的文件名写成planning.md它可能压根找不到。用默认模板初始化技能库是最稳妥的不要为了“更好看”随便改文件名。6.2 上下文太长、响应变慢怎么办superpowers 会提升上下文利用率但不可能把上下文无限变大。如果你做的是一个超大项目代理每轮都要读十几份文件很快上下文就会被塞满响应速度也会明显变慢。第一个解决办法是拆分任务。不要在一轮对话里让代理“分析全项目”又“实现新功能”。先用计划技能生成一份任务清单然后一个任务一个任务地执行。每个任务结束后你可以开一个新会话把当前完成进度和下一步目标贴进去。这种做法的效率往往比硬撑一个长会话高得多。第二个办法是善用脚本里的summarize.js。当你觉得上下文要爆的时候让代理先跑这个脚本把已经读过的文件内容压缩成摘要再继续后面的步骤。它会丢弃一些不重要的细节但保留关键接口和依赖关系。第三个办法是给代理“断点续传”能力。每个技能文件末尾加上一句话“如果会话上下文即将耗尽请输出一条简洁进度报告包含已完成任务、待完成任务和风险点然后建议用户开启新会话。”这听起来很土但确实管用。6.3 多语言项目的适配技巧superpowers 虽然对 JavaScript/TypeScript 和 Java 支持得比较好但也能用到 Python、Go、Rust 等项目里。关键在于你需要在AGENTS.md里声明项目的语言和构建工具。比如 Python 项目里代理跑测试用的是pytest不是mvn test如果你不告诉它它可能会尝试运行一个根本不存在的 Maven 命令。你可以这样写规则- 测试命令: pytest tests/ - 代码风格: black isort - 禁止在未通过 lint 的情况下提交代码Go 项目则可以声明go test ./...和gofmt风格。你甚至可以为一个仓库里同时存在的多个子项目各自定义测试命令skill 包会按照当前目录识别应该使用哪条规则。这里面容易忽略的一点是语言版本也会影响代理的判断。比如 Python 项目用 type hintsJava 项目用记录类型还是传统 POJO都需要在技能库里写清楚。我建议你上手就把这些工程约定写进AGENTS.md不要等踩坑之后再补。6.4 安全与权限设置超级技能包本质上是在给 AI 代理更大操作权限因此安全这根弦不能松。首先是命令执行权限。我希望你千万不要给代理任意执行终端命令的权限尤其是rm -rf、git push --force这类高危操作。superpowers 的官方技能里默认没有这些操作但万一你自己写了一个自定义技能要格外小心。其次是敏感信息的保护。不要把数据库密码、API Key 这些内容写进AGENTS.md或 skill 文件里。代理可能会在日志中输出这些内容或者在你的团队之间被复制传播。如果确实需要连接数据库做验证建议通过环境变量注入并让代理不要输出具体值。最后是人审。superpowers 不是一个“无人驾驶”系统它优化的是执行效率但代码评审和最终确认仍然必须由人类完成。我见过不少人完全信任 AI 生成的测试断言结果断言本身写错了功能也错了测试照样绿。所以无论 AI 多厉害代理在你自主可控的环境里跑就对了。6.5 问题速查表现象可能原因解决方法代理完全不按技能流程走AGENTS.md 路径未生效检查 Codexinstructions配置输入提示词验证技能文件读到了但不触发文件名与代理预期不匹配使用默认技能文件名避免改名跨文件改动时漏改调用方依赖分析脚本未运行手动执行find-deps.js并核对依赖清单测试失败后代理死循环缺少失败处理策略在 skill 文件中增加“重试上限和回退规则”响应明显变慢上下文过长用 summarize 脚本压缩或拆分新会话在 WorBuddy 中看不到新技能索引未刷新重启 WorBuddy 会话或手动刷新技能索引Java 项目构建失败Maven 依赖不全或离线模式先跑一次mvn dependency:resolve再执行任务7. 我的实操心得与后续扩展7.1 启用前后效率对比说实话我刚开始用 superpowers 那两天并没有觉得效率提升多少因为光是理解它的工作流和调目录权限就花了不少时间。但用了一周以后我明显感觉到“顺手”了。以前一个“给列表接口加分页”的小需求用 Codex 默认模式从改代码到修完测试大概要浪费十到二十分钟现在同样的需求直接在计划里拆好代理一次写完测试我只需要花几分钟做代码审查。返工率低了沟通成本也低了。有一个数字我记得特别清楚有一次我给一个老项目增加批量导入功能涉及 6 个文件、两处外部 API 调用和一套新的校验逻辑。按照我以前的经验让 AI 自己做至少需要我盯三四个小时。这次我让 superpowers 执行它的标准流程最后只用了大约四十分钟。最关键的是我中间只做了三次打断一次是确认优先级一次是指定日志格式还有一次是让它改用现有的枚举而不是新建枚举。这种体验确实刷新了我对“AI 写代码”这件事的预期。7.2 值得自定义的技能方向内置技能只是起点用好 superpowers 的诀窍是慢慢长出属于你自己的技能库。我这里给你几个我觉得特别值得自定义的方向。第一个是“代码评审技能”。你可以把团队的代码规范写进一个team-review.md要求代理在每次改动后逐项检查是否有硬编码、异常处理是否完整、SQL 是否能走索引、日志是否需要脱敏。这比自己口头强调一百遍管用。第二个是“错误日志分析技能”。让你的代理在 NPE 或者连接超时出现的时候不只是报告错误而是主动读取堆栈上下文、检查相关配置、对比最近改动最后给出可疑根因列表。我试过在一个 Spring Boot 项目里用它排查偶发 500 错误它把代码里一个空指针隐患给揪出来了省了我半天时间。第三个是“文档同步技能”。很多项目代码和文档脱节严重你可以让 superpowers 在功能变更后自动更新对应的 README 或接口文档。要把握好度不要让它在不能确定准确性的时候随意生成文档但给一个清晰的“变更后同步更新”规则还是靠谱的。7.3 最后一点建议如果你问我 superpowers 到底值不值得花一晚上去折腾我会说非常值得但要带着一颗平常心去用它。它不是魔法不会让你的 AI 从 GPT-4 变成“超级智能体”它的价值在于把 AI 编程代理的随机性变成工程效率的可预期性。你需要先接受一个前提AI 生成的代码依然需要人来负责但它能替你完成大量重复、繁琐、需要多文件联动的体力活。我个人在最开始安装的时候建议大家先从一个小项目入手先跑通计划、TDD、重构这三个核心流程再考虑接入 WorBuddy 这类工具。等你熟悉了它的工作方式你会发现真正的“超能力”不是它替你做了多少事而是它让你把精力从“盯着 AI 改 bug”中解放出来留给了真正需要判断力和创造力的部分。希望这篇分享能帮你在 AI 编程代理这条路上少踩几个坑多省几根白头发。
