1. superpowers 是个什么东西：别把它当成又一个 AI 插件
先说个我观察到的现象：很多人用了 Codex 一段时间之后，感受都是"一开始很惊艳，用着用着就感觉它变笨了"。不是说模型本身退化了，而是它对你的项目一无所知，每次对话都要从零开始理解上下文，遇到多文件改动、跨模块重构、工程规范约束这类任务，它就容易犯"只改表面、不动根因"的毛病。
superpowers 这个项目解决的就是这个问题。它的定位不是给 Codex 加一个技能，而是给 AI 编码助手装上一整套"工作方法论"。打个比方:如果把 Codex 比作一个聪明但缺乏经验的新程序员，superpowers 就像是塞给他一本资深工程师的工作手册——遇到问题先怎么分析、代码怎么写符合规范、写完要怎么自检、哪些场景必须反问确认。有了这本手册，新程序员的产出质量就会明显提升，这就是"超能力"的来源。
这个项目适合谁用？如果你是个人开发者，经常用 AI 写代码但觉得它"只能写单点功能，撑不起整个任务"，superpowers 值得试；如果你在小团队里负责技术基建，想让 AI 的产出更标准化，它也很对路。说白了，它做的是把"人的经验"和"AI 的能力"之间的鸿沟填上——这恰恰是当前 AI 编程工具最容易被人忽略的一层。
1.1 它解决的痛点：为什么 AI 写代码总是"浅"一层
先说一个日常场景。你直接让 Codex"帮我写个用户认证模块"，它能写出来吗？能。但写出来的往往是模板化的、没有任何业务判断的代码——不会考虑你的项目里已有的日志框架、异常处理风格、数据库事务边界、接口约定的返回结构。为什么？因为 Codex 根本不了解这些约束，你也没有给它提供"了解约束的路径"。
superpowers 的思路是：与其每次都在对话里反复叮嘱 AI，不如在项目里预置一套"行为规范"。这套规范包含项目背景、编码约定、常见任务的执行步骤、禁止事项、验收标准。AI 每次接手任务时，先读取这份规范再动手，相当于你给它做了一个入职培训。很多前期看似"多花"的配置，后期节省的是大量来回改 prompt 和返工的时间。
另一个痛点是上下文管理。Codex 的上下文窗口再大也有限，聊到第三轮、第五轮的时候，早期的重要约束可能已经被冲掉了。superpowers 通过把关键信息拆成结构化的技能文件（Skill 文件），让 AI 能在需要的时候按需加载对应知识，而不是从头到尾把所有内容都塞进上下文。这个设计思路我深有体会——它不是增加信息量，而是让信息"在正确的时候出现在正确的位置"。
1.2 它的运作方式：技能文件与工作流注入
superpowers 的核心可以拆成两样东西：技能文件（Skills）和工作流定义。
技能文件是一个个 Markdown 文档，每个文档对应一个特定领域或任务类型。比如你用 Java 做后端，可以有一个"Java 编码规范"技能文件；你在写 SQL 性能优化，就有一个"SQL 调优检查清单"。这些文件不是给人看的说明书，而是给 AI 读的"操作手册"。当任务涉及某个领域时，AI 会主动加载对应技能文件，然后按里面的规则执行。
工作流则是一组固定流程的描述。比如"面对新需求先拆解任务清单，再写实现计划，再逐模块实现，最后自测"，这套流程被固化下来之后，AI 不会一上来就闷头写代码，而是先展现对问题的理解，再动手。这其实就是资深工程师和普通程序员的最大差别：后者急着动手，前者先想清楚。
两者的关系有点像做事先立规矩、再按规矩办事。superpowers 实际上是把"规矩"做成了 AI 可以直接读取、遵循、自我检查的内容结构。我最初用的时候觉得它像提示词模板，用深了才发现它是体系——单个模板只能约束一次对话，技能文件的组合可以覆盖一个项目整个生命周期里的大量重复场景。
2. 从零到跑起来：superpowers 的安装与初始配置
安装这一步，网上能找到的教程大多写得含糊，要么只给 clone 地址，要么直接跳过前置条件，新手照做很容易卡在半路。我把完整过程捋一遍，先说清楚我自己的环境：macOS + 最新版 Codex CLI + Node.js 20。不同系统差异不大，但有几步要注意。
2.1 前置条件：先确认你的基础环境
superpowers 本质上是一套基于 Codex/Skills 生态的增强配置，所以前提是你已经装了 Codex CLI 并且能正常跑通基本对话。另外它需要 Node.js 环境来做一些脚本化操作，建议版本不低于 18，我用的是 20，目前没遇到兼容问题。
安装之前先确认两件事：第一，你的 Codex CLI 能正常访问；第二，项目目录的读写权限没问题——因为 superpowers 会在你的项目里生成一份技能配置目录，如果权限不对，后面加载会很别扭。我用的是官方提供的 Node 版 Agent Skills 目录结构，下载后直接解压到~/.codex/skills或者项目内.agents/skills目录都可以。
提示：如果你同时装了多个 AI 编码助手，建议别把技能配置全局铺开，以每个项目单独配为主，避免不同工具的配置互相干扰。我一开始偷懒用了全局配置，结果在另一个测试项目里出现了技能文件互相覆盖的怪问题。
2.2 安装步骤：别多走弯路
整体装起来其实就三步，但每一步都有容易忽略的细节。先把项目 clone 下来：
git clone https://github.com/clemlesne/superpowers.git cd superpowers这里有个容易踩的坑：有些人会在这一步直接npm install && npm run build，但仓库的构建脚本可能在你的 Node 版本下有些兼容作业。我建议先跑一次node -v确认版本，然后按 README 里的步骤来，不要自己跳步。官方主要提供两种接入方式：一种是直接把示例 skills 目录复制到你的 Codex 配置目录，另一种是运行安装脚本自动生成配置。我个人更推荐手动复制的方式，因为能看清每个文件有什么用，后面排查也方便。
cp -R skills/* ~/.codex/skills/复制完成后，在 Codex CLI 里输入一个简单问题，比如"列出你能用的技能"，如果能看到 superpowers 相关技能出现在列表里，就说明加载成功了。我建议此刻做一个"最小功能验证"，比如让它按照某个技能文件里的规范，生成一段符合 Google Java Style 的代码。能跑通，才算真正装好了。
2.3 首次启动校验：确认技能真正被加载
这一步经常被忽略，但它恰恰是区分"装好了"和"觉得装好了"的关键。很多人 clone 完、复制完目录，就以为自己搞定了，结果 Codex 根本没有读取到那些技能文件，对话里问它"你有什么技能"它一无所知。
校验方式很简单。先在项目目录里放一份技能文件，内容可以很简单，比如定义"所有类名必须使用 UpperCamelCase，变量名使用 lowerCamelCase"，然后问 Codex 一句："根据项目技能规范，下面这段变量命名有什么问题？"如果它能准确指出问题，说明技能真的生效了；如果它答非所问或者干脆说"我没有看到任何规范"，那就要回去检查配置文件路径。
另一个更快的验证方式是看 Codex 的启动日志。通常终端里会打印加载了哪些技能文件，只要你看到 superpowers 的字样，就说明加载过程没有问题。这套校验逻辑在后面排查问题时会反复用到——先确认技能被加载，再判断是内容写错还是路径不对，能省下大量时间。
3. 核心能力逐项拆解：所谓"超能力"到底强在哪
配置好之后，接下来是我最想写的一部分：superpowers 到底给了 Codex 哪些"超能力"？这些能力不是玄学，每一个都有对应的机制在背后支撑。我拆成三块来讲。
3.1 任务规划与破题：让 AI 先想明白再动手
接任务不急着写代码，这是 superpowers 给我带来的最明显变化。默认情况下，AI 面对"实现一个订单状态机"这种任务时会直接开写，代码可能是对的，但没有体现你的业务规则，比如状态流转里 A 状态能不能直接跳 C 状态、哪些操作需要记录审计日志。
有了任务规划技能后，Codex 会先做三件事：
- 列出它对本任务的理解，和你确认是否准确；
- 拆解需求清单，标出哪些是明确要求、哪些是隐含假设；
- 给你展示它的实现计划，等你确认了才动代码。
这个交互习惯一开始让我觉得"多此一举"，但用多了就明白它的价值。AI 对需求的理解一旦有偏差，你可以在它动手之前就纠正，而不是等代码写完、测试跑崩了才回头改。这其实就是软件工程里"先设计后编码"的老原则，只不过被迁移到了 AI 协作场景里。
还有一个细节值得提：当任务涉及多个文件时，superpowers 会让学生先绘制一份"文件影响图"，列出本次改动会碰到的文件、依赖关系以及测试范围。这极大地减少了 AI 的"局部视野"问题——它不再只盯着你让它改的那个文件，而是把相关联的代码都纳入考量。
3.2 技能库驱动的专业输出：Java 规范也可以硬约束
第二个核心能力是"按项目规范写代码"。你完全可以定义一份 Java 项目的编码规范技能文件，里面写明包结构、命名规则、日志框架约定、事务处理风格等。之后无论 Codex 写什么代码，都会自动套用这套规范。
我举个例子。我的技能文件里写了这么一行规则："所有对外 DTO 字段必须显式标注@NotNull、@Size等校验注解，不允许直接使用基本类型承接外部入参。"以前我靠 chat 时反复提醒，效果时好时坏；现在技能文件里写清楚，Codex 生成的 DTO 基本不需要我人工补注解，偶尔漏一两个，它自检环节也能抓出来。
这种"硬约束"的好处在于：团队里每个成员用 AI 写代码都能保持同一水准。以前新人写的代码和老手写的代码一眼就能看出差距，现在有了技能文件的约束，差距被大幅缩小。当然前提是技能文件本身写得足够细，这个我在后面避坑部分会展开讲。
3.3 自检与反馈回路：不光是写完，还要查一遍
superpowers 另一个让我觉得实用的点，是它内置了自检清单。每次生成完代码，AI 会根据技能文件里的"自检项"逐条过一遍，比如"是否正确处理了边界条件""有没有严格的空指针保护""是否遵循了项目里的异常处理规范"。
这个机制单独拿出来说好像很普通，但配上"反馈回路"就很有价值了。以前 Codex 写代码是一锤子买卖，你让它改它才改，你自己不发现问题它就默认一切正常。superpowers 的自检机制相当于给 AI 加了一道"编译期 lint"，让它在交付之前就发现自己的问题。
有一次我让它写一个并发任务执行器，它初版代码竟然自己发现了一个竞态条件，还主动标注"此处存在数据竞争风险，建议加锁或改用并发安全的数据结构"。这种事以前我从来没遇到过。那一刻我突然理解了项目名字的含义——它确实给 AI 加了一种"自我审视"的能力。
4. Java 项目实战：用 superpowers 重构一段真实代码
光说机制有点空，这里用一个实际场景把前面的概念串起来。这周同事让我帮忙重构一个订单模块里的状态机实现，原来的代码是用一堆 if-else 堆的，新增状态非常痛苦。整个过程我全程在 Codex + superpowers 环境里完成，这里记录一下实操链路。
4.1 场景设定：一段让同事头疼的 if-else
原始代码大概是这样的逻辑（已简化）：
public String getNextStatus(String currentStatus, String action) { if ("CREATED".equals(currentStatus) && "PAY".equals(action)) { return "PAID"; } else if ("PAID".equals(currentStatus) && "SHIP".equals(action)) { return "SHIPPED"; } else if ("SHIPPED".equals(currentStatus) && "CONFIRM".equals(action)) { return "COMPLETED"; } else { throw new IllegalStateException("Illegal transition: " + currentStatus + " -> " + action); } }需求是：新增一个"退款"状态，并且"CREATED"和"PAID"状态都可以进入退款；退款之后不允许再支付。这种改动放到 if-else 里也能做，但状态一多就难以维护。我的目标是用状态机模式重写，并且加一份清晰的流转配置。
4.2 从需求到方案的完整链路：superpowers 怎么介入
我把需求描述给了 Codex，它没有直接写代码，而是先输出了一段任务分析：
- 明确现状：当前用 if-else，状态流转隐藏在各分支中，新增状态需要修改核心方法；
- 提出方案：引入枚举定义状态，用
Map<State, List<Transition>>描述状态流转； - 拆分任务清单：定义状态枚举、定义流转配置、实现状态机执行器、补充业务异常、编写单元测试。
这个顺序看起来平淡，但对比直接生成代码，它的执行路径完全不同——先有结构，再有实现。接下来它按清单逐步执行，每一步完成之后会显示"完成 xx，下一步执行 xx"。
这是我在之前的工作流里最认可的一点：AI 不再是个"代码生成器"，而是像结对编程的伙伴一样，按你的项目背景一步步推进。整个重构过程大约 15 分钟，其中我人工介入的部分只有两次：一次是确认退款后禁止支付的业务规则，另一次是选择"抛出异常还是返回空状态"的异常策略。
4.3 生成代码的质量分析：它到底做得怎么样
重构完成后，我习惯性地人工 review 了一遍代码。整体来说质量超出预期，几个关键点：
- 状态枚举命名规范，符合我技能文件里定的 UpperCamelCase 规则；
- 流转配置用了不可变 Map，且每次访问做了防御性拷贝，避免被外部修改；
- 异常信息里带了当前状态和动作参数，方便排障；
- 单元测试覆盖了所有合法流转和两条例外路径。
其中最让我满意的是它自检时发现了两个遗漏场景：一个是"CREATED"状态直接退款的测试用例没有覆盖，另一个是Collections.unmodifiableMap包装的流转表在并发环境下读取没问题，但在生成时用了可变的 HashMap 做中间构建，严格来说应该用Map.of之类的不可变构造。这些问题它都主动标注出来了，我只需要确认修复方案即可。
实际经验是：superpowers 并不能保证生成代码零缺陷，但它能帮你减少"低级错误"和"常识性遗漏"，把 review 的精力集中在真正的业务逻辑上。
5. 与 worbuddy 配合干活：任务编排里的引导、反馈与冷却
单独用 superpowers 已经很顺手了，但如果你接触过 worbuddy 这个工具，就会发现它们是天然的一对。worbuddy 在我理解里是一个任务协同/编排层——它主要负责管理"多个 AI 任务之间的关系"，包括任务的依赖、排队、反馈收集、计划调整。我曾在一个多模块功能开发中尝试把两者串起来，效果比单独用任何一个都好。
5.1 worbuddy 的角色定位：它和 superpowers 的分工
简单来说，superpowers 管的是"单个任务做得好不好"，worbuddy 管的是"一堆任务怎么排布、彼此怎么衔接"。前者给 AI 提供能力和方法论，后者负责任务的调度和组织。
我用一个生活中的类比来理解：superpowers 是给厨师的一本菜谱和烹饪技巧手册，worbuddy 则是后厨的中控台，负责管理出菜顺序、协调锅灶使用、处理顾客催单。没有菜谱，厨师每个菜的口味不稳定；没有中控台，厨房再好的菜谱也会因为出菜次序混乱而崩溃。
在这个组合里，worbuddy 还能做一件事：当某个任务的产出不符合预期时，它会记录反馈并触发"冷却机制"，让 AI 先停下来反思，而不是继续往错误的方向推进。这就像敏捷里的迭代回顾——每轮结束先总结，再做下一轮。
5.2 配合工作流的典型模式：在我项目里的一次完整配合
我手头一个项目需要同时完成后端接口改造、前端联调辅助、数据库迁移脚本三个任务。这三个任务存在依赖关系：数据库迁移要先行，接口改造依赖新表结构，前端联调依赖接口改造完成。如果一股脑丢给 Codex，它很可能按顺序硬推，前面任务未完成就推进后续任务，导致返工。
用 worbuddy 编排后的执行顺序是：
- 阶段一：数据库迁移脚本生成，并自动校验 SQL 语法；
- 阶段二：后端接口改造，根据迁移后的表结构调整 Mapper 层代码；
- 阶段三：生成接口文档更新说明，供前端联调参考；
- 阶段四：集中执行一轮自检，覆盖三个任务的交叉影响点。
每个阶段之间有明确的完成定义，只有当前阶段通过自检，才会触发下一个阶段。这就避免了我最怕的"前端代码和后端接口对不上"的问题。
这套配合方式，如果只用 superpowers，也能做，但需要我手动在对话里不断补充"现在做第二个任务，记得刚才第一个任务的结论"。有了 worbuddy 这一层，任务边界和依赖关系是结构化管理的，AI 不需要每次都靠上下文里的零散信息来判断"现在该干嘛"。两者结合的最大收益是：从"一个对话流里的单线程执行"升级成了"多条任务线的有向并行"。
注意：worbuddy 这类工具每个版本的能力边界略有差异，但配合逻辑是通用的——任务拆分、依赖编排、反馈收集、冷却反思，这四件事只要做扎实了，工具叫什么名字其实不太重要。
6. 实测经验与避坑清单：这些坑我替你踩过了
最后这部分写给所有打算深入使用 superpowers 或类似技能系统的读者。项目本身设计得不错，但"设计得不错"和"用得顺手"之间还有一段距离，这段距离基本是靠踩坑填平的。
6.1 上下文窗口的隐性杀手：技能文件不是越多越好
第一个坑，也是最隐蔽的一个：技能文件本身也会占用上下文窗口。你以为加载的技能文件是在"后台给 AI 参考"，实际上它会进入 AI 的上下文计算范围。每个技能文件几十行还好，如果你的技能库里有几十个技能文件，每次对话 AI 都要把这些内容都读一遍，上下文空间被大量蚕食，对话轮数一长，早期重要的信息就更容易被挤掉。
我的教训是：全局加载了十几个技能文件，涉及 Java、SQL、前端、Shell 脚本等各类规范，结果有一次 Codex 在项目里对"要不要加载某个技能"的选择变得很奇怪，该用的没用上，不该用的反而出现了。后来我改成每个项目只保留 3 - 5 个真正相关的技能文件，效果明显改善。
这个问题的解决方案不是"多定义技能"，而是"定义少量但精准的技能，并且按项目维度隔离"。
6.2 技能文件过度膨胀：写得越细越好是个错觉
第二个坑和第一条相反，很多人（包括我）一开始容易把技能文件写成"百科全书"，每条规则恨不得细化到每一个标点符号。比如我在 Java 技能文件里写了六十多条规范，覆盖到"接口命名必须以 I 开头""DTO 必须有 swagger 注解""service 层必须捕获所有异常并包装"等等。
用过一段时间之后发现，过度精细的规范反而限制了 AI 的灵活性。有些规则在特定场景下是合理的，换个场景就成了过度设计。比如"DTO 必须有 swagger 注解"这个规范，在处理内部模块间的方法调用时就不适用，AI 会机械地给内部 DTO 也强加注解，产生一堆无意义的代码噪音。
我的改进方式是：技能文件分两个层次——核心规范（项目级，严格遵循）和场景约定（任务级，按需加载）。核心规范控制在一页以内，场景约定单独拆成文件，只在对应任务类型下才被加载。这个调整之后，AI 的产出质量和灵活性反而都提升了。
6.3 版本兼容与降级策略：升级前务必先看变更日志
第三个坑关于版本升级。superpowers 迭代速度不算慢，每隔几周就会有新版本。有一次我直接拉取了最新代码，发现技能文件的目录结构和命名规则改了，AI 加载技能的方式也跟着变了。结果是我的几个定制技能文件因为格式不兼容，在升级后的一段时间里根本没生效，我一度以为 Codex 出了问题。
排查的过程其实不难，但刚开始容易走弯路。我先检查配置路径，发现目录结构变了；再看技能文件格式，发现新旧版对技能头部的元信息字段定义不同；最后对照文档重新调整了文件格式才恢复。这个过程中最有用的一招是：每次升级前，先把当前技能文件目录备份一份，然后只保留一个最小测试技能文件，验证新版能正常加载，再逐步把其他技能文件迁过去。这样出了问题，你知道一定是某个文件格式的问题，而不是整体配置的问题。
6.4 一个关于使用心态的提醒
最后想多说一句。AI 编码工具的能力边界一直在扩展，superpowers 这类项目也确实让 AI 变得更"懂事"了，但它毕竟不是万能钥匙。我见过一些人期望装完 superpowers 之后，AI 就能自动把整个项目重构好、什么都不用管——这种期待注定会落空。
在我实际使用中，它更像一个"放大器"：你本身对项目的理解越清晰，它放大的效果越明显；你对需求一团模糊，它再多次任务规划也规划不出对的东西。所以工具要学，项目本身的企业逻辑、架构约束、代码风格也要花心思维护。把这些基本功打牢了，再让 superpowers 给你 100 倍速往前走，才是这个项目真正想给你的"超能力"。
