superpowers技能包：为Codex 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 init

init命令会在当前用户目录下生成默认的~/.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.json

AGENTS.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.java

Order是实体类，包含订单号、金额和状态；OrderRepository负责存储；OrderService提供查询和创建订单的方法。初始代码非常简单：

public class Order { private String id; private BigDecimal amount; private String status; // getter / setter 省略 } public interface OrderRepository { Optional<Order> 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")); List<Order> 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：不止 Codex

5.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 hints，Java 项目用记录类型还是传统 POJO，都需要在技能库里写清楚。我建议你上手就把这些工程约定写进AGENTS.md，不要等踩坑之后再补。

6.4 安全与权限设置

超级技能包本质上是在给 AI 代理更大操作权限，因此安全这根弦不能松。

首先是命令执行权限。我希望你千万不要给代理任意执行终端命令的权限，尤其是rm -rf、git push --force这类高危操作。superpowers 的官方技能里默认没有这些操作，但万一你自己写了一个自定义技能，要格外小心。

其次是敏感信息的保护。不要把数据库密码、API Key 这些内容写进AGENTS.md或 skill 文件里。代理可能会在日志中输出这些内容，或者在你的团队之间被复制传播。如果确实需要连接数据库做验证，建议通过环境变量注入，并让代理不要输出具体值。

最后是人审。superpowers 不是一个“无人驾驶”系统，它优化的是执行效率，但代码评审和最终确认仍然必须由人类完成。我见过不少人完全信任 AI 生成的测试断言，结果断言本身写错了，功能也错了，测试照样绿。所以无论 AI 多厉害，代理在你自主可控的环境里跑就对了。

6.5 问题速查表

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 编程代理这条路上少踩几个坑，多省几根白头发。