如果你每天都在跟代码打交道尤其是最近开始依赖 AI 编程助手来写需求、改 Bug、做重构那你大概率遇到过这样的场景AI 写得头头是道结果一跑就报错上下文一长它就把你最开始说的需求忘得一干二净同一个项目的规范每个会话都要重新讲一遍心累到想摔键盘。最近社区里很火的 superpowers 项目就是冲着这些问题来的。它不是某个新的编程语言也不是一个 IDE 插件而是一套专门给 AI 编程助手尤其适合 Codex CLI 这类终端型 Agent用的“技能库 工作流引擎”。装上它之后AI 不再是那个“你问一句它答一句”的被动工具而是一个会先做计划、再动手改代码、最后还会自查验证的“半自动结对程序员”。这套方案在国外开发者圈子里讨论度很高尤其是 codex superpowers、superpowers java 这几个关键词的热度一直没下去国内也有不少人在研究 superpowers 安装和教程。这篇文章我就从自己实际折腾的体验出发聊聊 superpowers 的底层思路、核心机制、安装步骤以及我拿一个 Java Spring Boot 老项目做实战测试的完整记录。不管你是刚开始接触 AI 编程还是已经在用 Codex 但觉得不够顺手这篇文章应该都能给你一些能直接抄走的经验。1. 先想清楚superpowers 到底解决了什么问题1.1 单用 AI 编程助手时的三个尴尬现场先说我自己。过去一年我重度使用过好几款 AI 编程工具最常用的就是终端里的 Codex CLI。说实话单论“生成代码”这件事它的水平已经很能打了——写个工具类、生成单元测试、解释一段陌生代码基本都能给出靠谱的答案。但你一旦把它投入到真实项目里问题就冒出来了。第一是上下文丢失。AI 的上下文窗口是有限的哪怕是最新的长上下文模型也不可能装下一个中型项目的所有细节。你让它改 A 模块可能改着改着它就把 B 模块之前定好的接口约定抛到脑后了。你催它“我之前不是说过了吗”它只会一脸无辜地道歉然后继续猜。第二是行为不稳定。同一个项目你今天让它“按照项目现有的异常处理规范来写”它能写得像模像样明天新开一个会话再说同样的话它可能给你抛出一套完全不同的错误码设计。AI 不是没有能力而是缺少一套稳定的“行为准则”来约束它每次的输出风格。第三是缺少流程意识。让 AI 直接改代码它往往拎起键盘就干改完了也是直接写进文件里完全不管什么先看影响面、再写测试、最后跑验证这一套工程流程。结果就是它改得越快你 review 得越心惊胆战。当时我的想法很简单如果能给 AI 建一套“项目说明书和操作规范”让它每次干活之前先看说明书再按规范一步步来是不是就能解决大部分问题superpowers 就是这个思路的成熟落地。1.2 superpowers 的核心设计给 AI 建立“肌肉记忆”我在看 superpowers 项目文档和源码的时候最直观的感受是它把“教 AI 做一个合格的软件工程师”这件事拆成了三层。第一层是技能库Skills。你可以把它理解成一套 markdown 格式的“专业手册”每本手册讲清楚一个能力比如“怎么写代码审查”“怎么拆解需求”“怎么写测试”。AI 在干活之前会先去读这些手册按手册里的步骤来操作。第二层是工作流Workflows。superpowers 约定了一套“先计划、再执行、后验证”的循环流程。AI 每次接到需求都会先输出影响面分析和实施计划等你确认后再开始改代码改完之后还会主动检查有没有破坏现有功能。第三层是记忆Memory。项目关键信息、当前进度、技术决策都会被记录到特定的项目文件里。AI 每次会话开始时先读取这些文件相当于带着前一回合的记忆继续工作。这三层叠加起来产生的效果不是“AI 变聪明了”而是“AI 变得靠谱了”。它不再自由发挥而是有一本很厚的操作手册时刻约束着它。我第一次看到这套东西的时候心里其实是不以为然的这不就是写几个 markdown 提示词吗但真正跑起来之后我才发现难的不是写提示词而是把提示词组织成一套可复用的、能被 AI 稳定执行的系统。superpowers 的价值恰恰在于这套“系统设计”而不是某一个单独的技巧。2. 核心能力拆解技能、循环、上下文管理2.1 技能库给 AI 装上一摞“专业手册”如果你用过 Anthropic 的 Agent Skills再来看 superpowers 的 skills 目录会觉得很亲切——超级相似的设计理念。superpowers 把每一个技能定义成一个独立目录里面放一个 markdown 文件。文件头部是一段 YAML 格式的元信息声明这个技能叫什么、适合在什么场景触发、需要什么前置条件。正文部分则是详细的步骤指南告诉 AI 应该按什么顺序做什么事。我随便截一个我自己写的技能文件片段给你看--- name: plan-change description: 在开始修改代码之前先分析影响面并输出实施计划 trigger: 用户提出新的功能需求或修改需求时自动触发 --- # 变更计划流程 1. 先阅读项目根目录下的 PROJECT.md 和 AGENTS.md了解项目背景与规范。 2. 识别本次变更涉及的文件、模块、接口输出影响面清单。 3. 按“新增/修改/删除”三列列出具体改动点。 4. 评估风险标记出可能破坏现有功能的改动。 5. 在 PRD 或对话中输出计划等待用户确认后进入执行阶段。写技能文件本质上是在给 AI 写“操作说明书”而且这份说明书它真的会去读。实践下来我最大的心得是技能文件要写得足够具体但不能变成僵硬的教条。太笼统的话 AI 照样自由发挥太琐碎的话 AI 会把它当成流程噪音直接忽略。先跑起来的做法是先只配三五个核心技能跑顺了再逐步增加。技能不是越多越好就好比你给新人安排入职培训不能第一天就把厚厚一整本 SOP 砸他脸上——他消化不了的。2.2 迭代循环强制“先想后做”superpowers 最让我受用的是它对 AI 工作节奏的约束。有了这套循环之后AI 的行为模式发生了非常明显的变化。以前我让 Codex 加一个数据库字段它直接就开始改实体类、改 Mapper、改 Service全程零沟通。现在它会先停一下列出“这几张表会被影响”“这个接口的返回值会变化”“建议同步更新 API 文档”然后问我是否按这个方案来。说白了superpowers 把开发任务拆成了三个阶段Plan分析需求定义影响范围输出执行清单。Build按清单逐项实施每完成一个子任务做一个标记。Verify检查代码可编译、测试可运行、关键逻辑符合需求整理变更摘要。这个循环最关键的环节其实是 Verify。大多数情况下AI 自己写出来的 Bug 它是发现不了的但当它被强制要求“把验证过程写下来”时它会更倾向写更保守的代码也更愿意补测试。我自己的实测体验是跑了这个循环之后AI 生成的代码第一次编译通过率可能有明显下降因为它更谨慎了但最终交付的代码质量、可维护性、和我 review 时需要改的东西都显著变少了。这就跟你自己写代码多花点时间做设计是一个道理。2.3 上下文与项目记忆解决 AI 的“职场失忆症”另一个让我眼前一亮的设计是项目记忆机制。superpowers 建议你在项目根目录维护几个固定文件比如 PROJECT.md项目背景与说明、AGENTS.mdAI 代理规范、PROGRESS.md当前进度与待办。AI 每次会话开始时会自动读取这些文件相当于一个新人入职第一天先看项目简介和团队规范。你可以把关键的架构决策、目录约定、技术选型理由都写在里面AI 在后续生成代码的时候就会刻意遵守。有一次我测试它是否真的会读这些文件故意在 PROJECT.md 里写了一句“本项目禁止使用 Lombok”然后让它生成一个新实体类。它生成的代码果然用了传统的 getter/setter。虽然不能 100% 保证每次都严格执行但多数时候它能做到。这个设计的本质是把 AI 从“无状态工具”变成了“有记忆的协作者”。你不需要每次都在 prompt 里重复你的技术偏好和项目约束那些被沉淀在文件里的内容AI 会自己去看。3. 环境准备与安装从零到跑通3.1 前置依赖需要准备哪些基础环境开始装 superpowers 之前先把前置环境准备好。我实测的环境是 macOS zshWindows 用户建议用 WSL 或者直接用 Git Bash整体路径逻辑差不多。第一步是装 Node.js注意版本要 18 以上。命令行用node -v检查如果版本太老会直接影响后面 Codex CLI 的安装。第二步是确保 Git 没问题因为 superpowers 仓库是通过 Git 拉取的。git --version能输出版本号就行。第三步是准备一个 AI 编程 CLI 工具。superpowers 目前最锦配的是 OpenAI 的 Codex CLI安装命令很简单npm install -g openai/codex装完之后先运行一次codex并登录你的 API 账号。我这里不展开说账号层面的东西重点是你本地至少要能正常跟 Codex CLI 对话。如果你用的是其他支持技能机制的 AI 编码 Agent思路是一样的——后面把技能和配置文件挂到对应目录就行。3.2 拉取 superpowers 仓库并配置技能环境准备好之后拉取 superpowers 本体。目前社区里比较活跃的版本来自 obra/superpowers 这个仓库直接 clone 到本地目录git clone https://github.com/obra/superpowers.git ~/superpowers拉下来之后我会先进去看一眼目录结构重点看两个东西skills目录和AGENTS.md文件。前者是所有技能定义后者是被 AI 自动读取的核心行为规范。接下来要做的是把技能目录挂到你的 Codex 配置目录下。不同机器、不同用户路径会有差异我自己的做法是直接做软链接mkdir -p ~/.codex/skills ln -s ~/superpowers/skills/* ~/.codex/skills/如果你不想全局生效只想在某个项目里用那就在项目根目录下建.codex/skills目录再把技能文件复制或软链过去。我建议新手先全局装跑通之后再按项目隔离。最后把 superpowers 仓库里的AGENTS.md复制到你的项目根目录。这份文件会约束 AI 的工作方式最核心的是写明要遵循的技能调用流程。你也可以基于自己的团队规范改写它这是整个系统里最值得花时间定制的一份文件。3.3 第一次跑通验证怎么确定安装成功装完之后先别急着上复杂需求跑一个最小测试确认系统是通的。随便新建一个临时目录复制一份 AGENTS.md 进去然后启动 Codex CLI在对话里输入请按照 superpowers 的工作流程帮我对这个目录做一个项目结构分析并输出一份简单的 PROGRESS.md。如果一切正常你会看到 AI 先生成一个计划也许它会调用 plan-change 技能然后检查当前目录的文件结构最后生成一个简洁的进度文件。这个过程中如果它输出了一些“遵循 AGENTS.md 中的流程”之类的话基本可以判断技能文件已经被读取了。这里有个容易踩的坑很多人在 Codex 的某个会话里测试发现 AI 完全不按 superpowers 来原因是 Codex CLI 启动时并没有读取新的 AGENTS.md。解决方案是退出当前会话重新启动因为 AGENTS.md 是在会话初始化时加载的中途改配置不会热生效。4. 实战记录给一个 Java 老项目加上 CSV 导出功能4.1 项目背景与目标为了验证 superpowers 在真实项目里的表现我拿一个自己维护的 Spring Boot 订单系统做了个实验。这个项目有完整的 Controller / Service / Mapper 分层用的是 MySQL 数据库订单表已经有一万多条测试数据。需求是按查询条件导出订单 CSV 文件要求包含订单号、用户手机号、商品名称、下单时间、订单金额、订单状态这几个字段并且金额要保留两位小数。这个功能说大不大说小不小但涉及的改动点不算少数据库查询、DTO、导出工具、Controller 接口、接口文档还有一个隐藏问题——手机号要在导出时做脱敏。放在以前我直接让 AI 写它会唰唰给你生成一遍代码但大概率漏掉脱敏需求也不会去关心分页和大数据量导出的问题。4.2 提示词怎么写给 AI 最有效我最终的提示词大概是这样的格式项目order-serviceSpring Boot 3 MyBatis-Plus MySQL。 需求新增一个订单 CSV 导出接口 /api/orders/export支持按时间范围、订单状态查询后导出。 约束 1. 手机号必须做脱敏导出文件里只能看到前 3 后 4 位中间以 * 代替。 2. 金额字段保留两位小数避免科学计数法。 3. 数据量上限 10 万条超出时直接返回错误信息。 4. 导出文件名格式为 orders_yyyyMMddHHmmss.csv。 验收标准 - 本地启动项目后调用接口能生成合法 CSV 文件。 - 涉及到的 Service / Controller / 工具类都应该有对应的单元测试。 请先分析影响面再开始实施。相比我以往“帮我写个导出功能”这种含糊指令这版提示词多了两个关键部分约束和验收标准。没有约束AI 会按自己默认的偏好来写可能挺好但不适配你的业务没有验收标准AI 就会“改完就跑”根本不会主动验证。我特意没有在提示词里提到技能文件想看看它能不能自己判断。实测结果Codex 读完项目结构和 AGENTS.md 之后主动调用了 plan-change 技能输出了影响面清单然后才开始动手。4.3 观察 superpowers 风格的执行过程第一个阶段是 Plan。AI 输出了这样一份计划新建 OrderExportDTO用于承载导出字段新建 CsvExportUtil 工具类负责字段映射与格式化修改 OrderService 新增导出查询方法注意处理 10 万条上限修改 OrderController 新增导出接口设置响应头补 OrderServiceTest 和 CsvExportUtilTest 单元测试。这份计划和我想的改动点基本一致但它额外标注了两个风险点手机号脱敏需要在导出层做而不是查询层做避免影响原有查询接口大数量导出要用流式写法而不是把所有数据查出来放进内存防止 OOM。后者我确实没想到它连代码都没开始写就先把这个坑标出来了。第二阶段是 Build。它开始逐个文件地创建和修改。比较让我意外的是AI 每写完一个文件都会在 PROGRESS.md 里追加记录改了哪个文件、改了什么、是否引入新的依赖。整个过程像是有个人在一边写代码一边跟你说“我现在在改哪个文件改了什么下一步准备做什么”。第三阶段是 Verify。它没有直接跑整个项目因为本地数据库环境不一定完整但主动检查了几件事XML Mapper 里有没有对应的结果映射、新增工具类是否能被 Spring 容器管理、Controller 的路径和方法是否和已有路由冲突。最后它还跑了一遍它能跑的两个单元测试。最终导出的 CSV 文件我手动验证了一下手机号确实被脱敏成类似138****1234的格式金额也保留了两位小数文件编码是 UTF-8 开头带 BOMExcel 直接打开不乱码。4.4 实战中踩过的坑这次实验整体顺利但不代表 superpowers 就没问题。我在前前后后的一周测试里踩过几个坑逐一讲一下。第一个坑技能目录路径写错导致 AI 读不到技能。有一次我把 skills 软链接到了错误目录结果是 AI 完全不按流程来直接自由发挥。排查下来发现是 Codex 读取技能的路径不是我以为的那个目录。解决方案很简单在 AGENTS.md 里加了一行说明把技能文件的绝对路径写清楚让 AI 找不到就去那里找。第二个坑PROGRESS.md 被 AI 自己覆盖。有一次测试新技能时AI 误把 PROGRESS.md 里我手写的“技术债务记录”部分用它的生成内容覆盖掉了。不能说它恶意但它对一个“进度记录文件”的理解和我想要的不完全一样。解决办法是后续在 AGENTS.md 里增加了说明PROGRESS.md 的“手动维护区域”不允许 AI 未经询问直接修改。第三个坑一次性配了太多技能反而让 AI 变得“行动迟缓”。我刚开始图新鲜把仓库里几乎所有技能都挂上了结果 AI 每次做一个极小的改动都要先跑一遍写计划、拆任务、做验证的完整流程并且它会在多个技能之间来回横跳。后来我把技能精简到五个核心项终于恢复了正常节奏。这个跟现实里的团队管理一个道理流程是为了兜底不是为了束缚手脚。5. 常见问题与排查技巧实录5.1 问题速查表我整理了自己和群里几位朋友遇到的典型问题做成一张速查表方便你直接对照排查症状可能原因解决方式AI 完全没有按流程走直接回答/直接改代码AGENTS.md 没有被加载确认项目根目录存在 AGENTS.md退出当前会话重新启动技能文件调用了但毫无效果skills 目录路径不对或文件格式写错检查软链接指向确认 YAML frontmatter 格式正确且 name 唯一AI 每次都输出冗长的计划改一行代码也很慢技能配置太多触发条件太宽泛精简技能数量合并重叠能力调整 trigger 描述PROGRESS.md 内容被意外覆盖缺少“禁止修改区域”的约束在 AGENTS.md 中明确哪些小节是手动维护、不可改动Codex CLI 启动报错找不到命令Node 版本过旧或全局安装路径未生效升级 Node 到 18检查 npm 全局 bin 路径AI 生成的 CSV 中文乱码缺少 BOM 头或编码不对在写入文件时使用 UTF-8 with BOM 编码5.2 三个容易被忽略的配置细节除了上面这些故障还有三个细节我建议你一开始就留意。第一技能文件的命名和描述里要包含明确的触发场景。比如“当用户要求修改代码前调用此技能进行影响面分析”。如果描述写得模棱两可AI 可能根本不知道什么时候该用它。第二superpowers 的流程设计是配合 Git 工作流使用的。我个人的建议是不要把 superpowers 当成“自动执行机”而是把它当成你的“结对编程搭档”。每次你确认它的计划之后让它在一个功能分支上干活这样你随时可以用 git diff 审视改动出问题了也能干干净净地回滚。第三多关注 AGENTS.md 的迭代而非一次性定稿。我自己的 AGENTS.md 已经改了三轮从最初的通用版本逐渐变成真正适配我开发习惯的专属配置每跑一个项目就把新的教训补进去。这就像调自己的编辑器配置没有标准答案只有不断打磨。写在最后我自己的体会是superpowers 这套东西最打动人的地方不在于某个惊艳的单点技巧而在于它把 AI 从一个“你问它答的问答机器”变成了“一个有基本职业素养的开发协作者”。以前我花很多时间在 prompt 里反复交代背景、强调规范、提醒它不要犯低级错误现在这些约束被固化在技能文件和项目记忆里AI 每次开工前自己就会去读、去遵守。我知道有些人会觉得这套配置工作量太大懒得折腾。但从我实测下来的收益看前期花半小时配置后面每次开发都能省下大量“重复调教 AI”的时间这个投入是很划算的。你也不需要一上来就全套照搬可以先装好基本技能跑几次小任务找感觉再把项目特有的规范慢慢沉淀进 AGENTS.md 和 PROGRESS.md。最后再分享一个小技巧每次跑完一个重要任务我都习惯性地让 AI 用几句话总结一下“这次踩了什么坑、下次要避免什么”。把这些沉淀到项目记忆里你会发现 AI 在你的项目上会越来越“懂事”。这大概就是 superpowers 的题中之义——不是给 AI 装上什么黑科技超能力而是给它一套能持续积累、不断演进的工作方法。