1. superpowers 到底是什么它给 Codex 补上了三块短板我在终端里用 Codex CLI 写代码有大半年了一开始觉得它确实聪明但用久了就发现一个很别扭的地方它每次都很热情但每次都没长性。今天让它写的函数明天换个会话它就全忘了让它改一个 bug它上来就大范围改动连测试都不跑。后来我装了一个叫 superpowers 的开源插件这个问题解决了大半。superpowers 是给 OpenAI Codex CLI 使用的技能系统本质是一堆结构化的 Markdown 技能文件外加一个编排逻辑。装上之后Codex 会从“拿到需求直接写代码”变成“先想清楚、再定计划、再小步执行、再验证”。网上那些 superpowers 使用指南、superpowers 安装、superpowers 使用教程、codex superpowers、superpowers java 的热搜词问的其实是同一件事怎么让 AI 编码代理干活更靠谱、更有章法。这篇文章我会从一个实际使用者的角度把安装过程、核心机制、六个高频工作流、Java 项目里的落地方法、常见坑一次讲清楚。适合已经在用 Codex 但觉得它不够成体系的人也适合想给团队引入一套可复制 AI 开发流程的技术负责人。如果你只是偶尔让 AI 写个脚本那后面有的部分可能对你来说太重了但理解一下它对“AI 为什么需要流程”的解释也是有价值的。1.1 第一块短板AI 没有“章法”裸的 Codex 接到一个需求比如“帮我加个导出功能”它会直接开始写代码。写出来大概率能用但测试没有、边界条件没考虑、导出格式也没问你。问题不在于它能力不行而在于它把“写代码”当成了唯一动作。真实开发里资深工程师拿到需求会先问导出给谁用、什么格式、数据量多大、要不要异步。superpowers 把这些默认的流程显式化了先澄清需求brainstorm再拆解步骤plan再小步实现并用测试验证TDD最后审查code review。这些不是什么新概念就是把人脑子里那套流程搬给了 AI让它别上来就表演。1.2 第二块短板AI 没有“记忆”Codex 每次开会话都是“失忆重启”。项目背景、技术栈约束、用户偏好、上周刚做的架构决定全都不记得。你每次都要重新交代一遍而且交代了它也未必能贯彻到底。superpowers 加了长期记忆记忆以 Markdown 文件形式存在本地会话开始时会检索相关记忆做出重要决定时会把结论写回去。相当于给 AI 配了一个“项目笔记本”。这个设计很朴素但解决的是 AI 编程落地时最痛的问题——上下文连续性。1.3 第三块短板方法论无法沉淀很多团队试过用各种方式规范 AI 的产出最后都变成一段超长的 system prompt又难维护又难复用。superpowers 的思路是把可复用方法论沉淀为技能文件一个技能一个目录里面就是一份结构化的 Markdown。任何人 clone 下来就拥有同一套流程想改就改想加就加支持版本管理。它自己对技能设计有一套类似 SOLID 的要求核心是单一职责、可扩展、描述和实现分离。注意这里的 SOLID 跟面向对象那五个缩写不是一回事只是借了同一个名字强调设计原则。真正重要的是每个技能只做一件事描述写得足够清楚这样 AI 才知道什么时候该用它。1.4 这套系统适合谁、不适合谁适合的人有三类。第一类是已经在用 Codex 的开发者觉得它“聪明但飘”希望产出稳定。第二类是想统一团队 AI 工作流的 leader技能文件可以作为团队资产沉淀在 git 里。第三类是喜欢“一切可读可改”风格的工程师因为 superpowers 几乎所有行为都是 Markdown 和配置完全透明。不适合的人也有三类。第一类是只想用 GUI 编辑器、不愿意碰终端的人这套东西的学习成本主要在命令行。第二类是希望 AI 完全自主干活、自己不想 review 的人superpowers 反而会让你更多地参与流程判断。第三类是需要大量中文产出的团队——默认技能都是英文写的不过英文学起来并不难而且你可以自己写中文技能。2. 安装与初始化从零到跑通第一版2.1 先确认前置条件在装之前先确认三样东西Codex CLI 版本、git、Node 环境。Codex 从某个版本开始才支持插件子系统我的建议是先把 CLI 升级到最新版再操作省得遇到“plugin 命令不存在”这种问题。检查命令很简单codex --version git --version node --versionNode 版本建议 20 以上。我有一次在 Node 18 的老环境里跑安装脚本报了一串语法错误升级 Node 之后就没再出过问题。另外这一步做完之后最好先确定你能正常使用 Codex 登录并完成一次简单对话再动 superpowers不然装好了也没法验证效果。2.2 两条安装路径插件命令和 clone 脚本我自己实测用的路径是插件命令执行完基本上就完成了大半codex plugin install obra/superpowers如果你的 CLI 版本提示没有 plugin 子命令那就走另外一条路直接 clone 仓库再跑仓库里的安装脚本。脚本具体叫什么名字以 README 为准常见的是 install 或 setup 开头的脚本git clone https://github.com/obra/superpowers.git ~/.codex/plugins/superpowers cd ~/.codex/plugins/superpowers ./bin/setup.sh安装路径和脚本名在不同版本里确实有过调整所以我的建议是先试codex plugin install不行就去看仓库 README 的最新安装说明别在网上扒一篇老教程硬套。装完以后一定要验证。运行codex进入对话直接问“你装了什么技能”或者“列出可用技能”。如果它告诉你有一串技能可以用说明加载成功。如果它一脸茫然多半是插件没有真正加载继续看下面的排查部分。2.3 装完之后目录长什么样装完之后你的用户目录下会多出几个关键目录。以我本机为例大致结构是这样~/.codex/ ├── config.toml ├── skills/ │ ├── brainstorm/ │ │ └── SKILL.md │ ├── plan/ │ │ └── SKILL.md │ ├── tdd-executor/ │ │ └── SKILL.md │ ├── orchestrator/ │ │ └── SKILL.md │ └── memory/ │ └── SKILL.md └── memory/ ├── user-profile.md └── project-notes/具体路径和目录名可能会随版本变化但核心结构是稳定的技能是一堆 SKILL.md 文件记忆是另一个存放 markdown 的文件夹。理解这一点很重要因为后面你要定制和排查都得从目录结构下手。2.4 升级与常见的安装报错升级方式也有两条。插件方式就运行codex plugin update obra/superpowersclone 方式就进仓库目录拉最新代码重跑一遍脚本。我一般是每个月更新一次因为上游技能文件更新还挺频繁有时候静默修了不少 prompt 细节。安装过程中常见的坑有三个。第一个是plugin子命令不存在这个基本就是 CLI 版本太老升级解决。第二个是装完以后技能不生效优先检查~/.codex/config.toml里插件路径有没有声明有些版本不会自动写入配置需要手动加。第三个是 clone 仓库时网络抽风导致失败GitHub 连接不稳定这种事各地都有重试几次或者让公司网络管理员把仓库缓存到内网即可不需要搞什么特殊手段。3. 核心机制拆解技能、记忆与编排是怎么配合的3.1 技能的真实形态Markdown 加渐进披露很多人以为 superpowers 是什么黑科技其实它的核心就是 Markdown。一个技能就是一个目录目录里一个 SKILL.md 文件顶部有 YAML frontmatter 声明名称和描述下面是正文告诉 AI 这个流程具体怎么走。--- name: brainstorm description: 在动手写代码之前通过提问澄清需求并探索可行方案。适合需求模糊、改动范围大、预期不明确的场景。 --- # Brainstorm ## 目标 在写任何代码之前先和用户对齐需求…… ## 步骤 1. 提出最多 5 个关键问题……这里最关键的设计叫“渐进披露”progressive disclosure。Codex 每轮会话并不会把所有技能的全文都塞进上下文它只载入每个技能的名称和 description。只有当 AI 根据描述判断当前任务需要某个技能时它才会去读取那个 SKILL.md 的完整内容。这就是为什么技能很多却不烧上下文的原因。我在实际使用中慢慢意识到技能的 description 就是整个系统的“路由表”。写得好不好直接决定 AI 会不会在正确时刻调用正确技能。默认技能的描述经过大量打磨你自己写技能的时候这块反而比正文更需要花心思。3.2 记忆系统是怎么转起来的记忆系统的运行逻辑很朴素会话开始的时候一个叫 memory 的技能会对过往记忆做一轮检索把和当前任务相关的笔记加载到上下文里对话过程中如果出现了值得记录的结论比如“用户确认用 PostgreSQL 而不是 MySQL”“模块 A 的构建命令是 mvn -pl api -am test”它会把结论写回记忆文件。这套机制的好处是透明。记忆文件就是普通 Markdown你随时可以打开看它记了什么改掉记错的删掉过时的。我自己的习惯是每周花十分钟清理一次记忆文件把那些一次性过程删掉只保留稳定的项目决策和偏好记录。养成了这个习惯之后AI 的“长期表现”真的会一次比一次稳。不过也要注意记忆系统不是数据库它的检索靠的是文本相关性和模型判断不能指望精确过滤。所以记忆文件的质量比数量重要得多。我在后面第五章会专门讲怎么防止记忆膨胀。3.3 Orchestrator 是怎么“排兵布阵”的Orchestrator 是整套系统里最核心的技能相当于一个总调度。它不是一个传统的“做某件事”的技能而是一个决策技能它会读你的输入判断当前处于什么阶段然后决定调用哪个技能并把控制权转交过去。以我实际观察到的行为为例我输入“我想给项目加个暗色模式”Orchestrator 看到这段话之后识别出需求还不清晰于是触发 brainstorm 技能。brainstorm 流程走完产出方案和约束Orchestrator 再触发 plan。plan 生成分步计划之后Orchestrator 会盯着计划把每一步交给对应的执行技能。整个链路是显式的你能看到 AI 每一步在干嘛而不是一团黑盒。Orchestrator 还会维护一个 session status记录当前计划、当前做到哪一步、下一步是什么。这对长任务价值巨大因为中途打断之后 AI 能快速恢复现场。实测下来一个跨越多个会话的改动有 status 比没 status 恢复成本低得多。3.4 自己写一个新技能完整示例理解了机制之后最值得做的一件事就是写自己的技能。我举个例子假设团队要求所有新增日志必须结构化输出包含请求 ID 和耗时。我可以建一个技能mkdir -p ~/.codex/skills/logging-standard touch ~/.codex/skills/logging-standard/SKILL.mdSKILL.md 内容大致是--- name: logging-standard description: 按团队日志规范审查代码。当代码中出现 logger、LOG、日志输出时触发检查是否包含 requestId、耗时埋点并给出修改建议。 --- # 日志规范 ## 硬性要求 - 每行日志必须包含 requestId 字段 - 接口入口与出口必须打印耗时 - 禁止用 System.out 打印日志写完保存后再开一个 Codex 会话让它“用 logging-standard 技能看看这段代码的日志”。如果描述写得好它甚至不需要你点名看到 logger 就会主动调用。这个过程让我意识到superpowers 真正厉害的地方不是它自带的技能而是它把“让 AI 遵守团队规范”变成了一种可维护的工程实践。4. 高频工作流实战从需求到交付的一条龙4.1 Brainstorm先问问题再动手默认工作流的起点是 brainstorm。它的核心理念是在动手写代码之前先把需求问明白。我试过输入“我想给项目加个暗色模式”如果不用 brainstorm裸 Codex 可能会直接开始实现但走了 brainstorm它会先问暗色模式是针对 Web 还是桌面端要不要跟随系统主题现有样式变量是怎么设计的优先级和截止时间是什么一开始我觉得这有点烦但用久了才意识到它问的问题其实就是我自己在正式排期之前会问的问题。而且它的产出是一个“决策记录”把当时确认过的约束写下来后面所有相关代码都会基于这个记录执行。相当于把“需求评审会”压缩进了对话里。这个技能最有价值的地方恰恰是拦住 AI 自己拍脑袋。AI 最擅长在需求不明的时候给出一个“看起来合理但方向错了”的实现brainstorm 这个关卡能大幅降低这种风险。4.2 Plan 与项目简报动手之前先有地图brainstorm 结束之后Orchestrator 一般会触发 plan 技能。plan 的产出是一份 step-by-step 实施计划每条计划包含改哪个文件、前置依赖、验证方式、预计复杂度。这不是空话而是真正可执行的步骤每条都对应具体的文件和命令。我也会维护一个项目简报project brief相当于项目的常驻说明书里面写清楚项目是干什么的、技术栈是什么、构建命令是什么、目录结构怎么划分。这些信息会进入记忆成为 AI 做一切决策的背景。实践下来项目简报写到位的项目AI 的代码质量和路径选择明显更贴合项目实际而不只是“写出能编译的代码”。还有一个细节我要求计划里必须带上验证命令。比如“修改 UserService 后运行mvn -DtestUserServiceTest test”。这个习惯救了我很多次因为 AI 最容易犯的毛病就是写完代码不跑测试就直接宣布完成。把验证命令写进计划相当于把“必须验证”写进了流程。4.3 TDD 工作流实录红、绿、重构TDD 是 superpowers 里我收益最大的技能。它的执行顺序很严格先写一个会失败的测试跑一遍确认它是真的因为预期原因失败再写最小实现让它通过最后重构。这跟传统的“先写实现、再补测试”在体验上完全不同。举个例子我在一个 Node 项目里要加一个价格计算函数。TDD 技能的引导是先让我描述期望行为然后生成测试文件跑一次确认测试失败再让我确认“这个失败是预期的”然后才写实现。这个“先红后绿”的节奏看起来多花了时间但它带来了一个关键好处测试不是事后补的装饰品而是真正的行为契约。在 Java 项目里也是一样的节奏只是验证命令换成了 Maven。比如我常跑的命令是mvn -q -DtestOrderPriceTest test实测下来TDD 技能让 AI 写出的代码质量稳定了一个档次。因为“先写测试”这个动作强制 AI 先把行为定义清楚定义清楚了实现自然不容易偏。4.4 Debugging 与 Code Review让 AI 做有边界的活Debugging 技能是我在线上问题排查时最常用的。它的流程是先复现问题再用最小测试或日志把失败点缩小定位根因最后做最小修复。我最喜欢它的一点是“克制”——它不会在排查的时候顺手重构你的代码而是只修该修的地方修完就跑相关测试验证。Code Review 技能的边界感同样很强。给它一段 diff它会按优先级输出必须改的 blocker、建议调整的问题、纯风格意见。它不会做“简单说几句好话然后放行”这种敷衍行为但也绝不会改动面扩大到让你头疼。我团队现在已经把它当作本地自检的固定环节合代码之前先让 Codex 过一遍 diff能拦下不少低级错误。4.5 Java 项目里的实际应用把构建命令写进记忆搜索热词里有 superpowers java可见 Java 开发者对这个很感兴趣。我的经验是superpowers 本身不区分语言真正需要适配的是构建工具和项目结构的上下文。以我一个 Maven 多模块 Spring Boot 项目为例。第一次接入时我先把项目的构建特点写进了项目简报根目录是聚合 pom业务模块在order-service和user-service下运行测试用mvn -pl order-service -am test不希望 AI 随便跑全量测试因为耗时太长。这些约束进入记忆之后AI 在后续所有任务里都会遵守。有一次需求是给订单模块加状态流转校验。完整链路是这样的brainstorm 先确认了状态机规则和非法流转的边界plan 列出了要改的枚举、校验类、以及新增的 OrderStateTransitionTest然后 TDD 流程先写了状态流转的失败测试跑出红再实现校验逻辑跑绿最后 code review 检查了一遍 diff。整个过程里 AI 没有乱动别的模块验证命令也一直用的 Maven而不是想当然地跑 npm test。4.6 和其他 AI 工具的搭配worbuddy 怎么用 superpowers最近不少人搜“worbuddy 怎么用 superpowers”我实话实说我对这个工具的架构不是特别确定但这类问题的本质都一样能不能把这套技能机制从 Codex 搬到其他 AI 编程工具里。答案是能但要分情况。如果目标工具原生支持 Codex 兼容的技能或插件协议直接把 superpowers 仓库里的 skills 目录链接过去就行。如果它只支持自定义 system prompt 或规则文件那把 orchestrator 加常用技能合并成一份规则文件也能获得七八成效果。如果工具支持 MCP 这类动态上下文注入协议那还可以做按需加载这是最接近原生体验的路径。我看到社区里已经有人把 superpowers 技能移植到了 Claude Code 的插件体系上原理就是上面说的第一种路径。所以我的建议是不要执着于某个具体工具名先搞懂自己手上的工具支持哪种扩展机制。技能只是一堆 Markdown真正起作用的是“调度逻辑”哪个工具能让你把调度逻辑放进上下文哪个就能用。5. 常见问题与排查记录5.1 技能没生效、Orchestrator 不响应怎么办这个问题我遇到过不止一次。最典型的症状是你正常聊天但 AI 完全没有表现出用了任何技能说什么它都直接接话。排查顺序我总结成一条固定路径。先直接问它“列出你知道的技能”如果它列得出来说明加载正常只是这次会话它判断不需要触发技能属于正常行为。如果它列不出来再查安装路径和配置文件。用codex plugin list看插件状态检查~/.codex/下 skills 目录是否真实存在且里面是完整的 SKILL.md。最隐蔽的问题通常出在 YAML frontmatter手改技能文件的时候把冒号或缩进写错了模型解析失败整个技能就静默失效了。还有一种情况是触发了但没遵守这不是加载问题而是模型能力问题。我在下面 5.3 会细说。5.2 记忆文件越滚越大导致上下文质量下降记忆系统的设计者和使用者最容易犯的错就是“什么都记”。记太多之后检索出来的相关内容会很杂AI 反而不知道哪些是重点。我的处理办法是两条第一定期清理每周打开 memory 目录把“一次性过程记录”删掉只保留稳定结论第二修改 memory 技能的描述明确要求只记录项目决策、用户偏好、架构约束这类持久信息不记“刚才修了什么 bug”这种过程信息。另外重要项目我会单独建一个项目级记忆不让它和个人级记忆混在一起。多项目并行的时候这能明显减少“张冠李戴”的情况。5.3 模型选择对技能遵循度的影响Codex 里可以切换不同模型我从实际使用中得到的结论是不同模型对多步技能流程的遵循度差距很大。强推理模型在执行 orchestrator 引导的多轮流程时明显更稳定会老老实实走完“提问、计划、测试、实现、审查”这些步骤而快速模型在机械性的小步骤上表现不错但到了需要同时记住多步约束的场景就容易“跳跃式完成”——直接跳到实现跳过验证。我的用法是计划阶段和调试阶段用强推理模型纯重构和批量格式化这种机械任务切到快速模型。这本质上是拿 token 成本换稳定性按需分配比全程用一个模型省钱得多。5.4 环境与网络相关的坑除了技能本身的问题环境问题也不少。最常见的是公司网络 clone GitHub 仓库失败这种一般让网络管理员缓存一份到内网就行重试也行。还有公司统一 git 账号导致 Codex 自动提交失败这时候要在 Codex 的 git 配置里声明正确的用户信息而不是让 AI 每次想办法绕过去。多台机器同步也是一个隐藏需求。我现在把~/.codex/skills和 memory 目录纳入 dotfiles 管理团队里则用一个私有 git 仓库同步这样大家共用一套技能和一部分项目背景。技能文件的版本管理一旦跑起来你就能体会到它比“人人都有自己的 system prompt”好维护太多了。6. 实操心得与避坑建议6.1 我跑了两个月总结出的几条铁律第一条动手之前先要计划。哪怕是简单任务也要让 AI 先说一句“我打算改哪里、怎么验证”。这个习惯成本极低但能拦截掉一大半“改错文件、没跑测试”的问题。第二条技能的 description 比正文还重要。系统靠 description 判断何时调用技能描述写不清楚正文写再好也没用。后来我写技能一半时间花在打磨那一两行描述上。第三条TDD 的“先跑红”不允许跳过。只有先看到了预期的失败后面变绿才真正有意义。AI 有时候图省事会假装跑过测试你要能看出它没真的执行命令并强制它现场跑一遍。第四条记忆是共同资产不是 AI 私有的。它记的任何东西你都要能看懂、能改、能删。如果 AI 记的东西让你看不懂那说明记的方式错了应该调整而不是将就。第五条别急着写一堆自定义技能。先原样跑两周把默认技能的节奏吃透再定制也不迟。我见过太多人第一天装完就写七八个技能最后没有几个真正触发过。6.2 什么时候应该关掉 superpowerssuperpowers 不是万能药有些场景它反而是负担。比如一次性脚本、临时探索性实验、快速原型验证、纯问答式的语法咨询这些任务根本不需要完整的流程强行走 brainstorm-plan-TDD 只会让节奏变慢。我现在的工作习惯是Codex 里常驻 superpowers 处理正经开发任务但遇到临时问题会明确告诉它“这个问题不用走流程直接回答”。明白什么时候跳过流程和明白什么时候用流程同样重要。工具给了你一套方法论不等于每一个动作都要编进流程里关键是判断这件事的投入产出比。我个人的体感是装上 superpowers 之后Codex 从一个“很聪明但做事随性的临时工”变成了一个“能带的新人”。它依然会犯错但犯错方式变可预测了会在动手前问问题、会先写测试、会告诉你它打算怎么改。这些行为本质上不复杂就是一堆 Markdown 加上一点调度逻辑但它补上的恰恰是 AI 编程工具最缺的流程意识。如果你正在用 Codex建议先装上跑两周再决定要不要深入定制自己的技能体系。