1. 先用我的真实经历回答为什么 AI 编程助手需要外挂如果你最近一直在用 Claude Code、Codex 这类 AI 编程助手一定体会过那种又爱又恨的感觉上午刚跟它说清这个项目用 Java 17、Maven 构建、不要字段注入下午它生成的代码里就全是 setter/getter 和 Autowired让它改一个跨模块功能它吭哧吭哧把整个仓库读了一遍最后还是漏了关键文件稍微复杂点的任务它永远一个文件一个文件串行处理改完 A 才发现 B 还在等 A 的接口又折返回去返工。我一度以为这是模型不够聪明、上下文窗口不够大造成的直到我把 Superpowers 加进工作流才发现问题其实出在工具链本身。Superpowers 不是一个新的 IDE也不是什么编程语言而是一层跑在 AI 编程助手之上的扩展框架。它的核心思想非常朴素让 AI 像人一样做事之前先翻操作手册做完事情之后记笔记。这里的手册就是一个个技能Skills笔记就是自动记忆系统再加上并行子代理基本上把 AI 编程助手最让人抓狂的三块短板都补上了。作者是 Perl 社区的老熟人 Jesse VincentGitHub 上叫 obra项目开源后在开发者圈子里传得很快尤其搭配 Codex 使用是最近的热搜方向。这篇文章把我这两周的折腾过程完整写出来怎么安装底层是怎么工作的怎么和 Codex 配合Java 老项目里怎么用以及我踩过的三个坑。如果你正在用或者准备用 AI 编程助手觉得AI 写代码目前还差点意思那这篇大概率对你有用。我默认你已经装好了 Claude Code 或 Codex 里的至少一个会基本的终端操作如果还没装先把对应工具装好再回来看。1.1 三个差点让我放弃 AI 编程助手的瞬间先说第一个失忆。AI 编程助手本身是有上下文窗口的但这个窗口是会滚动丢弃的。我试过在同一个会话里让 Claude Code 改一个 Web 服务的鉴权逻辑聊到第四五个文件的时候它突然开始用 GET 请求改数据完全忘了一开始定的所有写操作必须走 POST、必须带签名头。新开一个会话更夸张连项目用什么构建工具都要重新教一遍。这种每开一次会话就失忆一次的感觉用久了真的很心累尤其项目大了之后光是一遍遍重复背景信息就够浪费时间。第二个是上下文爆炸。让它改一个核心实体类它会把整个仓库的代码读一遍。项目小的时候无所谓项目大了之后每次任务都带着十几万 token 的背景知识进来响应变慢不说还容易捡了芝麻丢西瓜。我后来才意识到这是它缺少一个先规划、再按需读取的机制只能靠暴力填塞上下文来弥补。最离谱的一次我让它给一个支付模块加日志它读完一堆无关的订单历史代码后给我写了一个能编译但逻辑完全不对的日志切面。第三个是多文件串行。改一个稍微跨模块的特性它得先找到依赖链再一个一个文件改。问题是 AI 在改每个文件的时候未必记得前面文件里已经改了哪些名字。结果就是经常出现刚把 A 类改完B 类还在引用旧名字的尴尬局面不是我手动指出来它根本不知道。更磨人的是如果中间夹着一个编译报错它往往会从头再分析一遍把原本十分钟能做完的事拖到半小时。这三个瞬间的共同点是什么不是模型变笨了而是工具链没有给模型提供稳定的记忆和流程控制。人写代码为什么不会这样因为人会先看项目文档、会遵循团队规范、会开多个分支并行处理。Superpowers 做的就是把这些能力补到 AI 助手上。1.2 Superpowers 到底给 AI 加了什么原生行为和加上 Superpowers 之后的差别我用下面的表格总结一下场景原生 AI 助手加了 Superpowers 之后项目背景复用每次新会话都要重新描述从记忆文件自动读取项目约定和你的偏好新任务启动直接翻代码、靠猜先扫描技能目录匹配最合适的处理流程大型任务一股脑读完所有代码先规划再拆成子任务按依赖顺序执行多文件改动串行读写容易前后不一致并行子代理分头处理主代理最后合并团队规范靠模型悟通过技能文件固化稳定不跑偏说白了Superpowers 不是让模型本身变聪明而是给模型加了一套流程和记忆的外设。它让 AI 做事从凭感觉变成按手册来。这也是为什么很多人管它叫给 AI 助手开挂。我第一次用它的时候特别惊讶的一点是它会在开始干活之前自动把技能列表过一遍。像批量重命名生成单元测试整理 CHANGELOG这些技能它看到任务描述就能自动匹配。我当时让 AI帮我看看这次改动有什么问题它居然自动加载了代码审查技能按安全性、可读性、性能、边界情况四类输出了一份结构化的 review 报告——这在原生工具里只能靠手写 prompt 硬拗而且每次拗出来的格式还不一样。有了技能文件之后审查标准被固化下来了什么该查、按什么顺序查、输出格式长什么样全都稳定了。2. 安装与初始化从零到十分钟跑通2.1 环境准备先确认你满足这几个条件Superpowers 底层是 Node.js 生态的工具所以第一个前提是 Node 版本够新。我建议 18 及以上太老的版本在跑安装脚本时容易报语法错误。第二个前提是至少装了 Claude Code 或 Codex CLI 中的一个因为 Superpowers 本身不直接产出代码它是寄生在 AI 助手里的。第三操作系统方面macOS 和 Linux 体验最顺Windows 用户最好用 WSL别直接用 CMD 和 PowerShell 折腾目录权限会烦死人。装之前先跑三条命令确认环境node -v git --version claude --version # 或者 codex --version如果 claude 或 codex 还没装先去各自官方渠道装好初始化好登录状态再接 Superpowers。这一步很重要Superpowers 的配置过程会去扫描 AI 助手的配置文件如果助手本身没初始化过它找不到配置目录会装了个寂寞。我见过有朋友跳过这步直接装 Superpowers结果 init 的时候报无法找到 claude 配置目录又回头补装的。2.2 安装步骤命令就一条剩下全是验证官方 README 里给了一行安装脚本大致长这样不同版本命令会有变化如果 404 了直接去官方仓库复制最新的curl -sSL https://raw.githubusercontent.com/obra/superpowers/main/install.sh | bash跑完之后先验证命令是否进入 PATHsuperpowers --help能看到帮助信息就说明装上了。接着执行初始化superpowers init这条命令会干三件事创建技能目录、创建记忆目录、探测你本机装的是 Claude Code 还是 Codex。如果你两个都装了它会问你要不要同步技能到两边我推荐同步——这样以后不管开哪个工具行为标准是一致的。最后一步回到你的 AI 编程助手新开一个会话然后直接问它你现在有哪些技能正常的话它会列出一串技能名字包括代码审查、生成测试、整理提交信息等等。如果它一脸懵说明技能目录没有被加载重启终端或者重新初始化一次。2.3 第一次跑起来从失忆到会记笔记我第一次把 Superpowers 跑通后做的第一件事是跟 AI 说以后生成的代码都用 Java 17 语法不要用 var接口返回统一用 DTO禁止返回实体。你猜怎么着它当场就把这条记进了记忆文件。我特意找了一下文件就在 ~/.superpowers/ 下的 memory 目录里纯 Markdown 格式随手就能打开编辑。这个体验和原生 AI 是完全不同的——原生工具你这句话说完就过去了上下文一滚动就忘了现在它被落盘存储下次无论新旧会话AI 都会主动读取。这里我想多说一句很多人上来就问这玩意儿能让我不用写 prompt 吗我理解这个期待但它不是干这个的。Superpowers 解决的是说了不白说的问题——你的偏好、项目的约定、处理任务的流程都能被持久化并且自动在合适的时机被调用。这比任何玄学的 prompt 技巧都实在。2.4 安装失败最常见的两种原因我安装那会儿也遇到过问题身边朋友也问过我基本就两类。第一类是目录权限不够。安装脚本默认往 /usr/local/bin 写可执行文件macOS 和 Linux 对这个目录的权限管得比较严。报错如果是 permission denied别硬加 sudo直接用官方推荐的用户级安装方式把文件装到 ~/.local/bin 下然后把这个目录加到 PATH 里一劳永逸。第二类是 Node 版本太旧。如果你看到类似 Unexpected token ? 的语法错误基本就是 Node 太老。用 nvm 装个 LTS 版本重新打开终端再来一次。装完之后记得确认 nvm 默认版本已经切到新版否则新开终端还是旧版本。3. 拆开引擎看原理技能目录、记忆系统与子代理是怎么协作的3.1 技能不是插件是一本本操作手册一开始我总下意识地把技能理解成插件后来发现不对劲。插件是写死的代码逻辑技能更像是一份给 AI 看的操作手册。每个技能其实就是一个目录放在 ~/.claude/skills 或者 ~/.codex/skills 下面。目录里最核心的东西是一个 Markdown 文件通常是 SKILL.md里面有技能的描述、适用场景、具体执行步骤如果需要跑脚本目录里还可以挂脚本文件。重要的是 AI 如何发现技能它在接任务时会去扫描技能描述根据语义匹配不是简单的关键词匹配。所以技能描述一定要写什么时候用而不是这是什么。比如你写代码审查技能当用户要求检查代码、Review PR、评估改动是否有问题时使用AI 在遇到帮我看看这个 PR 靠不靠谱时就能匹配上你要是只写提升代码质量AI 一辈子都不会触发它。下面是一个简化的 SKILL.md 示例你能直观感受一下它的结构--- name: code-review description: 当用户要求检查代码、Review PR、评估改动是否有问题时使用。输出结构化审查报告。 --- ## 执行步骤 1. 获取当前改动的 git diff 2. 按四类问题分别检查 - 安全性注入、越权、敏感信息泄露 - 可读性命名、重复代码、复杂条件 - 性能不必要的循环、N1 查询、大对象拷贝 - 边界情况null、空集合、超时、并发 3. 输出 Markdown 报告每类问题给出文件路径、行号、问题和修复建议注意技能里并没有写死用什么模型、调用什么 API它只是一套步骤。AI 读到这套步骤后会结合自己的推理能力一步步执行。这就像给了实习生一份 checklist他按着做结果虽然不如资深工程师完美但至少不会漏掉关键环节。3.2 记忆系统AI 的长期笔记本记忆系统其实也藏在技能目录里但它的定位完全不同。它分为全局记忆和项目记忆两层。全局记忆存的是你个人的工作习惯比如生成代码默认 Java 17、提交信息用 Conventional Commits项目记忆存的是当前仓库的特殊约定比如模块间调用必须走 API 层不能直接 new Service。记忆类型存什么作用范围示例全局记忆个人偏好、通用习惯所有项目代码注释用中文版本管理用 GitFlow项目记忆当前仓库约定、架构决策当前仓库使用 Lombok禁止静态 mock接口返回 DTO临时 TODO当前任务相关的一次性信息当前会话这次需求只改订单模块不动支付模块什么时候会写入记忆我观察下来有三个触发点一是你明确说记住……二是 AI 发现某个指令在同一个项目里被反复提及它会主动提议写入三是你干活干到一半手动让它补充。写入之后AI 每次开始工作前会把相关记忆片段注入上下文这一步是自动的不需要你手动引用。记忆文件大了之后也有副作用它同样会占用上下文窗口。所以我会定期清理按主题拆文件把最高优先级约定放在文件开头。后面翻车章节我会详细说这个问题。3.3 子代理与任务编排AI 也能多线程Superpowers 比较亮眼的其实就是子代理机制。主 Agent 接到一个大任务后会先做任务规划拆出一系列相互独立的子任务然后启动多个子代理并行执行。每个子代理有独立的临时上下文只关心自己的子任务执行完把结果交回主 Agent 汇总。这套机制特别适合重构场景。比如我要重命名一个公共接口连带所有实现类和调用方都要改。传统方式是 AI 串行扫描一遍再一个个改容易漏。用子代理的话主 Agent 可以同时派一个子代理梳理调用链一个子代理生成改动清单一个子代理检查测试依赖最后再由主 Agent 统一执行修改。因为是并行跑整体耗时少很多遗漏也少。但是注意子代理适合读多写少的场景不适合两个子代理同时改同一个核心类。这个我踩过坑后面详细讲。4. 把 Codex 加进工作流我最常用的协作模式4.1 为什么单把 Codex 拎出来说最近搜 codex superpowers 的人特别多我自己也是从 Claude Code 玩到 Codex 的。原因很简单Codex 在某些场景下真的快尤其是快速生成一段独立逻辑或者根据注释补一个函数这种任务它又便宜又利索。但它的短板也是真明显——项目级约定把握得不如 Claude Code 那么稳经常写出能跑但对不上团队规范的代码。所以我就想了个笨办法把团队规范写成技能文件让 Codex 在开跑之前先读一遍。Superpowers 对 Codex 的支持虽然不像对 Claude Code 那么自动化但配置好之后效果是实打实的。而且如果你像我一样Claude Code 和 Codex 两个都在用技能同步机制能保证两边拿到的是同一套操作标准不会出现Claude 守规矩、Codex 乱来的分裂局面。4.2 Codex 集成步骤比你想象的简单首先装完 Superpowers 后跑一下superpowers doctor它会告诉你当前检测到了哪些 AI 助手。如果它没识别到 Codex一般是两种原因要么 Codex 还没登录初始化要么技能目录路径不对。手动做法也很直白在 Codex 的配置目录下建一个 skills 文件夹然后把 Claude Code 那边的技能内容复制过来。具体路径不同版本略有差异可以是 ~/.codex/skills也可以是 ~/.config/codex/skills自己用codex --help看一眼或者直接按 Superpowers init 时打印出来的提示路径来。配置完之后重启 Codex CLI新开一个会话问一句你现在会哪些技能。如果它列出来了那就说明加载成功。之后你让它用代码审查技能看看当前改动它就会按技能文件里的步骤走。有一个细节Codex 对技能目录的扫描时机不是每次对话都触发有时候你刚放进去的新技能它要新开会话才认。所以别急着怀疑配置错了先重启会话再说。4.3 三个我现在天天在用的协作模式第一个模式是Claude 主规划 Codex 跑小任务。我遇到复杂需求时先用 Claude Code 结合全局记忆和项目记忆把方案、改动清单、依赖关系理清楚然后把里面可以独立拆出来的小任务丢给 Codex 去并行执行。这样既享受了 Claude 的规划能力又享受了 Codex 的速度。第二个模式是提交信息生成。我写了一个 commit-message 技能描述里写当用户要求生成提交信息、整理 git log、写 CHANGELOG 时使用。技能文件里规定了格式type(scope): subject 结构正文里要写清为什么改、影响范围、如何验证。现在不管哪个工具给我生成提交信息格式都是一致的再也不用手改。第三个模式是代码审查流水线。我会在本地把改动整理成 patch然后让 Codex 跑审查技能输出报告。这个流程比直接在 IDE 里人工 review 要快而且审查技能里的标准是我自己定的AI 会严格按标准来挑问题。当然AI 挑出来的问题我还是一眼一眼看过的它负责找可疑点我负责判断真伪和优先级。5. Java 老项目实战重构、测试生成与长期记忆的价值5.1 批量重构类重命名与包迁移Java 老项目里最痛的事情之一就是一堆命名不规范的类和一个混乱的包结构。手工改的话几十个文件来回跳一不小心就漏改了一个引用让原生 AI 改它倒是勤快但经常改到一半忘记哪些文件已经动过。我的做法分三步。第一步先让 AI 扫描项目结构输出一张依赖清单标出哪些类是公共类、哪些被谁引用。第二步在提示里明确要求按依赖顺序从底层往上改先改实体类再改仓储、服务、控制器。第三步每改完一层立刻跑mvn -q compile验证。编译失败就把报错日志丢给 AI让它先回滚到上一个提交再重新执行。这套流程里 Superpowers 的价值在于它会先启动一个规划任务把改动清单整理好然后每个文件的修改都有前后对照即使改到一半我喊停它也能基于技能里的批量编辑规范把已改文件的状态整理成报告给我。我用它分批次重命名了一个包含 60 多个类的老模块全程只手动处理了三个因为同名类引起的冲突这个效率放在以前想都不敢想。5.2 自动生成单元测试别贪多先保覆盖率Java 项目的单元测试生成Superpowers 配合技能也能做得有模有样。我写了一个 generate-junit-test 技能规则写得很死默认输出 JUnit 5 Mockito 风格所有外部依赖用 Mock 注入每个测试方法只测一个行为命名用 should_when_ 的格式必须覆盖正常路径、边界值、异常分支三类场景。实际用下来生成的测试代码确实能跑但直接照单全收是不行的。它生成的测试有个典型毛病断言太弱。最夸张的一次它给一个订单计算服务生成的测试只断言了返回值不为 null完全没有验证核心的金额计算结果。我后来在技能里加了一条硬性规则所有涉及数值计算的方法必须用具体数值断言结果禁止使用 assertNotNull 糊弄过去。 加了这条之后输出质量明显提升。还有一个小技巧先让 AI 输出测试计划再写测试代码。这能逼着它在动笔前把被测类的依赖和边界条件想清楚。我实测下来写计划的阶段多用两分钟能省掉后面三轮返工。算是目前我在 Java 项目里收益最明显的用法之一。5.3 长期记忆在 Java 项目里的隐藏价值Java 项目最大的问题是约定分散pom.xml 里埋了依赖版本.editorconfig 里写了格式化风格README 里讲了分层架构团队 wiki 里还有各种潜规则。每次新开一个 AI 会话它都要重新读这些读漏了就开始跑偏。我在项目初始化好 Superpowers 记忆后做的第一件事是主动让 AI 把项目里的约定整理进项目记忆包括JDK 版本17使用 record 定义不可变数据类构建工具Maven依赖版本统一维护在 parent POM 中代码规范使用 Lombok禁止字段注入构造器注入优先分层规范Controller 只做参数校验Service 写业务逻辑Repository 只做数据访问测试规范JUnit 5禁止 mock static 方法数据库操作一律用集成测试覆盖之后我再让 AI 写新接口效果完全不一样。有一次我让它为一个分页查询写 Service它自动用了构造器注入、自定义分页结果类、日志里打了耗时的 warning——这些全是我没在本次 prompt 里写的但它都从记忆里翻出来了。这就是长期记忆的隐藏价值它不是让你的 prompt 变短而是让 AI 从一开始就站在熟悉项目的老同事的角度干活。6. 三类翻车现场与自定义技能入门6.1 翻车一并行子代理同时改同一个文件导致合并冲突子代理并行看起来很美好但我在一次重构里翻了个大车。那次任务是重构一个用户服务它包含 UserService、UserRepository、UserController 三个核心文件。主 Agent 把任务拆成了三个子代理一个改 Service一个改 Repository一个改 Controller理论上互不干扰。结果三个子代理都发现 UserRepository 里的 findByName 方法需要修改。于是三个进程同时往一个文件里写最后的合并结果直接把方法签名弄得乱七八糟编译都过不了。我当时的内心是崩溃的。事后复盘问题出在任务拆解没有以文件所有权为边界。正确的拆法应该是指定一个子代理负责核心模型的修改其他子代理只允许读取这个文件不允许写入所有写入需求统一提交给主 Agent由它决定谁拥有该文件的写权限。现在我的做法是任务拆解处加上一条规矩每个文件只能有一个写入方其他子代理需要修改该文件时必须先报告主 Agent。 翻车概率大大下降。错误拆法正确拆法子代理A改 Service子代理B改 Repository子代理C改 Controller主 Agent 持有核心文件写权限子代理只读并输出建议三个子代理都依赖 UserRepository各自修改同一个方法指定一个文件所有者其他子代理只能请求变更合并时出现方法名冲突编译失败统一由主 Agent 按顺序应用变更6.2 翻车二记忆越长 AI 越分心用了一周之后我项目记忆文件滚到了小五千字。我以为记忆越丰富越好结果发现 AI 开始变笨了——它会在无关紧要的细节上纠结反而忽略了最重要的约定。后来我打开记忆文件一看里面什么都有包括某天随口聊到的暂时用临时方案、某个一次性分支的处理方式、甚至还有一条已经过时的端口号信息。记忆这东西和上下文窗口一样不是越大越好关键信息被稀释了AI 的注意力就分散了。我现在维护记忆文件的原则有三条分主题拆文件最高优先级规则固定放在每个文件顶部每次会话结束花半分钟清理失效条目涉及临时决定的记录单独放一个临时 TODO区完成即删。我推荐每个项目记忆文件都长成这个骨架# 项目记忆 ## 最高优先级不可违反 - 禁止字段注入 - 所有公共方法必须写 Javadoc ## 项目结构 - 模块间调用必须走 API 层 ## 工具链 - Maven 构建JDK 17Lombok ## 临时 TODO完成即删 - [ ] 升级某组件的日志脱敏策略这样 AI 读到记忆时先接触的一定是最关键的那几条而不是被一堆历史细节带跑。6.3 翻车三技能描述写太泛AI 永远不触发我最早自己写过两个技能一个叫文档处理一个叫代码优化。听名字挺正常结果 AI 一次都没主动触发过。后来我盯着技能描述看了半天才明白问题描述里写的是处理各种文档优化代码质量这类话对 AI 来说信息量几乎为零——它根本不知道应该在什么时机、什么任务下调用你。正确的写法是穷举触发场景。描述要像设备说明书一样精确当用户要求检查代码风格、Review PR、评估改动是否有隐患时使用本技能当用户需要生成 Word 文档、整理文档格式、批量转换文件时使用本技能。技能命名也尽量用动词宾语。generate-junit-test 比 junit 好update-changelog 比 log 好。命名清晰、描述具体AI 的匹配率会明显提升。顺带提一句最近有人私信问我能不能用 Superpowers 增强某个具体的文档处理工具其实思路完全一样只要那个工具能走命令行或者你能把它的操作步骤写清楚它就能被封装成一个技能。门槛没有想象中那么高。6.4 从零写一个最简单的自定义技能动手写一个技能其实只需要三步建目录、写 SKILL.md、重启会话验证。下面我以代码审查技能为例展示一个完整的目录结构~/.codex/skills/code-review/ ├── SKILL.md └── scripts/review.jsSKILL.md 是灵魂前面已经给过示例这里补充两点。第一frontmatter 里的 name 和 description 是 AI 判断是否调用这个技能的依据要多花心思写第二正文里的执行步骤要拆到可执行的粒度最好每个步骤都写清楚输入输出。比如获取 git diff后面可以补一句如果没有未提交的改动使用 git diff HEAD~1 获取最近一次提交的改动这样 AI 就不需要猜。脚本不是必须的。AI 本身就是模型你给它清晰的步骤它就能照着执行脚本的作用是补足 AI 不擅长的确定性操作比如读取大文件、调用外部命令、处理结构化数据。我的 review.js 脚本做的事情很简单就是把 git diff 整理成带行号的标准输入AI 处理起来更快更准。如果你第一次写技能建议从纯 Markdown 开始后续确实有需要再加脚本别一上来就把复杂度拉满。6.5 最后几句大实话折腾了两周 Superpowers我的整体感受是它解决的不是AI 会不会写代码的问题而是AI 能不能稳定地按你的方式写代码的问题。如果你刚接触我的建议是别一上来就铺一大堆技能先跑通记忆系统把项目约定喂进去用一周再说技能这东西是慢慢长出来的用到哪个场景缺了再补而不是先造一堆永远触发不到的工具。另外还是要泼一盆冷水Superpowers 给的是流程和上下文的确定性不是结果的正确性。它生成的代码该 review 还是得 review该跑测试还是得跑测试。我自己见过太多人把 AI 工具当免费劳动力使结果上线出事故又回来骂工具不行。工具只是把翻车概率降下来不能直接变成零。最后分享一个保留项目我会在每个项目开头主动让 AI 生成一份项目约定速查表写进项目记忆里然后把这份速查表提交到仓库文档目录。这样一来团队同事用任何 AI 工具甚至新人入职都能迅速对齐这套约定。这套玩法我已经推给了几个朋友反馈都还不错。如果你也在折腾 AI 编程工作流不妨从今天这个项目约定速查表开始试起。