最近在折腾 Codex CLI 的时候我发现了一个叫 Superpowers 的开源技能框架它解决了一个特别实际的问题AI 编码代理能听懂你的意图但常常记不住过程。你明明说了要先写测试它写两行代码就急着拿结果你告诉它项目里已经有现成的工具函数它偏要自己重新造一个。Superpowers 的做法很朴素——把好工程师的工作习惯包括 TDD 流程、调试顺序、代码审查清单全部写成结构化的技能文件让代理在开工前先完整读一遍。模型还是那个模型但它的行为方式会稳定很多。这篇笔记记录我这段时间的实战经验包括安装步骤、技能原理解析、一个 Java 项目的完整实操以及常见坑的排查方法。内容比较偏实操适合已经在用或者正准备用 Codex CLI、想进一步提高 AI 编码代理稳定性的开发者。1. 项目整体设计与思路拆解1.1 为什么需要“技能”而不是单纯换个更大的模型很多人对 AI 编码工具有一个误解觉得效果不好就是模型不够聪明换个更大的模型就万事大吉。实际上大部分翻车现场不是模型不懂代码而是模型不知道“在这个项目里应该按什么顺序干活”。同一个模型你给它一句“帮我实现这个功能”它可能直接生成一大段代码但你给它一份“先写测试、跑测试、再实现、再重构”的步骤清单它就能按部就班地执行。Superpowers 的核心思路就在这里把隐性的工程经验变成显性的技能文件。更关键的是大模型的上下文窗口是有限的。你不可能在一个对话里把所有要求反复叮嘱一遍哪怕你说了二十轮对话之后它也会忘。技能文件则不同它是持久化存在的每次代理启动新会话时都会重新读取。它就像给一个能力很强但记性不好的实习生发了一本《员工手册》比每次开会时口头交代有效得多。我实际测下来启用技能集之后代理写出来的测试覆盖、代码拆分逻辑明显比“裸奔”状态要规范而且很少出现改 A 坏 B 的情况。1.2 Superpowers 的三大组成技能目录、AGENTS.md、记忆文件Superpowers 的结构不复杂核心就是三块内容。第一块是 skills 目录里面每个技能对应一个 Markdown 文件例如 tdd.md、debugging.md、refactoring.md。每个文件会描述这个技能在什么场景下触发、应该按什么步骤执行、每一步的验收标准是什么。第二块是 AGENTS.md这是代理启动时的入口文件相当于总纲。它里面写了项目的基本背景、常用命令以及应该优先启用哪些技能。第三块是记忆文件通常放在 .agents 或 .codex 目录下例如 progress.md 用于记录任务进度known_dependencies.md 用来记录项目依赖和易错点。这三块配合起来的逻辑很清晰AGENTS.md 负责“开门”——告诉代理你是谁、项目是什么skills 负责“给方法”——遇到具体任务时按哪套流程走记忆文件负责“记账”——这次改到哪一步了、哪里容易踩坑下次接着用。我建议你在落地的时候也保持这个三件套结构不要图省事只复制一个技能文件那样很快会乱。组成作用典型位置AGENTS.md项目总纲代理启动时优先读取~/.codex/ 或项目根目录/.codex/skills/可复用的工作流按场景触发~/.codex/skills/progress.md记录当前任务进度.codex/memory/known_dependencies.md记录依赖、易错点、特殊约定.codex/memory/1.3 与传统提示词工程的区别很多人会觉得这不就是在 AGENTS.md 里多写几句提示词嘛我自己也能做。区别在于两点。第一Superpowers 的技能文件是经过结构化的它不只是几句话而是一套包含触发条件、执行步骤、退出条件、输出格式的工作流定义。你自己随手写的提示词往往只有“你要认真写测试”这种抽象要求代理无法执行技能文件则会把“认真”翻译成“先运行测试确认失败再写实现再运行测试确认通过”这种可操作动作。第二传统提示词是依附于上下文的说得再多也会被后续对话冲淡技能文件是独立于对话框之外的项目资产可以多项目复用也可以团队共享。我在团队里就把常用的技能目录单独建了一个仓库新项目直接拉过来大家心照不宣地遵守同一套规则。相比每次都在聊天里重复交代这种资产化的方式维护成本低得多效果也稳定得多。2. 安装与配置一步一步让 Superpowers 跑起来2.1 环境准备先确认 Node、Git 和 Codex CLI在安装 Superpowers 之前你要确保机器上已经有 Node.js推荐 18 或以上版本、Git以及 Codex CLI 本身。Codex CLI 是 OpenAI 提供的终端编码代理工具Superpowers 相当于是给这个代理加载的外挂技能包所以代理本身必须能正常工作。node -v git --version npm install -g openai/codex codex --version如果 node 版本太低后续 npm 安装流程容易报错如果 Git 没装clone 仓库和读取配置都会有问题。这里我建议先把 Codex CLI 的服务端配置也就是 API 密钥或登录授权跑通随便在一个空目录里让它生成一个文件试试确认代理本身没问题再来折腾 Superpowers否则后面报错你会分不清是代理的问题还是技能集的问题。2.2 获取 Superpowersclone 还是直接复制Superpowers 的安装方式比较灵活最常用的做法是直接从 GitHub 克隆社区维护的仓库到本地然后把它接入 Codex 的配置目录。你在搜索框里搜 “codex superpowers” 的时候能看到一些社区仓库例如 obra/superpowers 或者类似命名的项目具体以你能找到的最新版本为准。我的做法是git clone https://github.com/obra/superpowers.git ~/superpowers当然如果你不想维护一个额外仓库也可以只把目录里的 skills 和 AGENTS.md 复制到自己项目的 .agents 或 .codex 目录下。两种方式各有好处Clone 方式方便随时拉更新适合长期重度使用复制方式更轻量适合只想在某个项目里试水。第一次用我建议先 clone因为这样你能看到完整的技能文件后面出问题也好排查。2.3 激活技能集项目级和全局级两个入口激活的过程实际上就是把 AGENTS.md 放到代理能读到的位置。Codex CLI 有两个加载层级全局配置目录一般是 ~/.codex/和当前项目根目录。如果你希望所有项目都默认启用 Superpowers就把仓库里的 AGENTS.md 复制到全局目录如果你只想在某个仓库里启用就把 AGENTS.md 和 skills 目录放到当前项目的 .codex/ 下面。mkdir -p ~/.codex cp ~/superpowers/AGENTS.md ~/.codex/AGENTS.md cp -r ~/superpowers/skills ~/.codex/skills这里有一个非常容易踩的坑Codex CLI 在启动时读的是一个固定的 AGENTS.md而不是你项目里随便起的什么 agents.md。文件名大小写、路径层级都必须对否则代理根本看不到你的技能表现就是“明明装了但它就是不按套路来”。我建议配置完成之后先休息一下执行下面的验证步骤确认加载成功再开始干活。2.4 验证加载让代理自己说出它有什么技能验证的方法很简单你直接打开 Codex CLI在会话里问一句“根据你刚才加载的 AGENTS.md你会使用哪些技能请列出技能清单。” 如果代理能准确说出 tdd、debugging、refactoring 这些技能说明 AGENTS.md 被读到了。如果它一脸茫然或者回答的是它自己脑补的内容那就需要检查路径和内容格式。我还习惯用一个更直接的验证方式随便丢给它一个和技能相关的小任务比如“按照 tdd 技能给下面这个函数补一个测试”。然后观察它第一步是直接写实现还是先写测试再跑测试。前者说明技能没生效后者说明技能已经进入它的工作流。这个验证比单纯看它能说出多少技能名字更可靠因为有些时候代理会“背”技能名但执行时还是按照默认习惯走。3. 核心技能模块解析与原理3.1 TDD 技能把“红-绿-重构”变成代理的肌肉记忆TDD 技能是 Superpowers 里我使用频率最高的一个它解决的是“AI 急着出结果不写测试”的毛病。技能文件里通常会把流程拆成五步第一步根据需求先写一个会失败的测试第二步运行测试确认它确实失败并记录失败信息第三步写最小实现让测试通过第四步再次运行测试确认通过第五步在测试保持绿色的前提下做重构。这一步一步看起来机械但对 AI 代理特别有效因为代理和初级工程师很像你不给步骤它就自由发挥你给一个明确的检查清单它会非常老实地执行。我在技能文件里会让代理“在动手写实现前先用一句话说明下一个要写的失败测试是什么”这一步能在很大程度上避免代理跳步。实际用下来测试先行之后代理写出的实现明显更收敛不会一上来就建十几个类也不会随手删掉已有测试。3.2 调试技能先定位根因再动手修调试技能的核心原则是“最小干预”。技能文件会要求代理先复现问题再阅读错误信息和堆栈然后提出一个根因假设最后才修改代码。很多翻车案例都是代理拿到一个报错就乱猜比如把端口冲突当成代码逻辑问题把类型错误当成数据库问题。有了调试技能之后代理会被强制要求按顺序排查并且在修改前说出自己的假设。我用下来觉得最有价值的指令是“在你修改任何代码之前先写一个 50 字以内的根因分析。” 就这一句话能让代理从“试错机器人”变成“理性排查者”。另外调试技能一般还会要求代理检查最近改动过的文件因为大多数 bug 都是最近改出来的这个思维习惯对 AI 尤其重要——它自己可能都不记得上一轮生成过什么代码让它优先排查自己最近的改动反而更容易找到问题。3.3 重构与代码审查技能重构技能和 TDD 技能通常搭配使用。技能文件会强调“小步重构”每次只提取一个方法、只改一个变量名、只删除一段重复逻辑每做一步都要运行测试。这样做的原因很现实AI 代理如果用一次大动作重构涉及的文件太多一旦出错排查起来非常痛苦而且大模型很容易在重构过程中悄悄改变行为的细节。小步走每一步都验证才能保证行为不变。代码审查技能则适合用在提交 PR 之前。技能文件会要求代理按照清单检查有没有安全问题、有没有边界条件遗漏、有没有命名不当、有没有明显重复代码、测试是否覆盖了关键路径。我通常会让代理先做完一轮自查再把结果贴在 PR 描述里。这样不仅节省了 Review 的时间也让 AI 在审查别人代码时有一个统一的基准而不是凭感觉说“看着没问题”。3.4 记忆系统让代理知道“上次干到哪了”记忆系统是我认为 Superpowers 最被低估的部分。编码任务往往不是一次会话能完成的而 Codex 这类终端代理每次会话开始时对之前的内容并没有主动认知。Superpowers 通过 progress.md 和 known_dependencies.md 来解决这个问题。progress.md 记录当前任务做到哪一步、下一步做什么、有哪些待验证内容known_dependencies.md 则记录项目里已经存在但容易踩坑的东西比如某个工具函数必须用特定方式调用、某个测试命令必须在根目录下执行。要让记忆系统工作关键是让代理在会话结束前主动回写。我会在技能文件里写死一条规则“每次完成一个子任务后更新 progress.md说明你做了什么、测试结果如何、下一步计划。” 同时在 AGENTS.md 里让代理开始任务前先读这些文件。初次配置时可能会觉得繁琐但坚持两三周之后你会明显感觉到代理的“记忆”越来越靠谱即使是隔了几天再继续同一个功能它也能无缝衔接。4. Java 项目实战从需求到提交的完整流程4.1 准备一个最小的 Java 工程听到“superpowers java”这个热搜词的时候我就知道很多人是想把技能集用在 Java 后端项目上。Java 项目因为编译、测试链路长AI 代理如果没有技能约束很容易在“生成代码”这一步就放飞自我从来不跑测试。我这里用一个最小的 Maven 项目做演示目标是实现一个简单的 Calculator 类包含 add 和 divide 两个方法并且要让代理严格按照 TDD 流程完成。先创建项目骨架mvn archetype:generate -DgroupIdcom.example -DartifactIdcalc -DarchetypeArtifactIdmaven-archetype-quickstart -DinteractiveModefalse进入项目目录确保mvn test能跑通初始状态。这一步很重要因为 TDD 的起点是“测试能跑、且能看到失败信息”如果初始测试框架本身就是坏的后面代理很容易把环境问题误判成业务问题。4.2 在 Codex 中触发 TDD 技能项目准备好之后我在 Codex 会话里输入tdd 请在 Calculator 类中实现 add 方法要求先写失败测试运行测试确认失败再写最小实现最后确认测试通过。每一步都要给出你在做什么、以及测试结果。注意我特意在指令里写了“tdd”这个触发词这对应技能文件中的触发条件。实际上Superpowers 并不是一个已经装好在 Codex 里的插件它的本质是“让代理按照 AGENTS.md 中描述的 tdd 技能去执行”所以你在提示中显式点名技能名能提高命中率。如果代理还是没反应我会补一句“你可以在你的技能列表里找到 tdd 技能的定义按照里面的步骤来。”4.3 会话执行实录步骤拆解与产物说明实际执行时代理的第一步是生成测试文件。它创建了 CalculatorTest里面先写了 add 方法的测试用例断言 Calculator.add(2, 3) 等于 5。然后它运行mvn test测试结果是失败的——因为 Calculator 类还没有 add 方法编译都过不了。这一步很关键它确认了“红”的状态。接下来代理进入实现阶段它给 Calculator 增加了 add 方法仅仅一行return a b;。再运行mvn test测试通过。到这里一个最简 TDD 循环就闭环了。整个过程比我预想的要干净没有出现代理直接甩出一个带 main 方法、甚至带命令行交互的完整程序这种无聊行为。这正是技能文件对步数的约束起的作用它知道“最小实现”意味着最小而不是“给你一个能跑的全部代码”。4.4 Java 实战中的心得与注意事项第一次跑通流程后我又让它用同样的方式实现了 divide 方法。这次代理自动考虑了除零异常在实现里抛出 IllegalArgumentException。我后来翻了它的 progress.md发现它把“除法需要考虑除零”写进了 known_dependencies.md 里这个细节让我觉得记忆文件确实在起作用。但是有一个坑我得提醒你Maven 项目的测试报告输出在 target/surefire-reports 目录下迭代快的时候 target 目录会很大。我建议在项目的 .gitignore 里把 target 写进去同时不要让代理去读 target 目录里的临时文件而是统一通过mvn test的标准输出判断结果。否则代理可能在 target 目录里乱翻浪费大量上下文还容易被过期的测试报告误导。4.5 技能组合从 TDD 到重构再到终态提交如果你觉得单个 TDD 流程太基础可以把几个技能串起来用。我在做一个小模块时会让代理遵循这样一个完整链路先用 tdd 技能把功能点逐个实现然后触发 refactoring 技能把重复的逻辑提取成私有方法再触发 code-review 技能让它站在审查者角度检查自己的代码最后把 progress.md 更新到“功能已完成等待提交”。这一个流程走完从代码质量到过程记录都齐了最后一个 commit 基本不用我再大改。当然技能组合需要写好触发顺序和边界条件。在 AGENTS.md 里我加了一段类似的话“当用户提出完整功能需求时默认启动工作流需求理解→tdd→重构→review→更新记忆。” 代理看到这个全局规则后处理任务的思路就会明显结构化。如果有些任务不需要全流程我会在指令中明确写“跳过特定技能”它也能够正确响应。5. 常见问题与排查技巧实录5.1 技能没加载代理不认 AGENTS.md这个是最常见的问题表现是技能文件明明已经复制过去了但代理就是不按照文件里的步骤执行。我通常按这个顺序排查先确认 AGENTS.md 是不是放在 Codex CLI 实际读取的路径上而不是放在你心里以为的路径上再确认文件名大小写完全一致然后重启 Codex 会话因为有些版本在会话开始时才加载配置中途追加的 AGENTS.md 不会被重新读取。如果都不行就在提示里显式写“请先读取 AGENTS.md”强制触发。5.2 代理不读记忆文件每次会话都像失忆Superpowers 的记忆文件是静态的代理不会自动去读除非 AGENTS.md 里有明确指令。我的解法是在 AGENTS.md 开头写一条硬性规则“每次会话开始先读取 .codex/progress.md 和 .codex/known_dependencies.md如果存在用它们作为上下文背景。” 同时在对话里可以直接说“根据 progress.md 继续”代理一般就能正确加载。如果还是不行说明你用的 Codex CLI 版本可能没有把自定义指令注入权限放开需要检查配置。5.3 代理陷入无限循环或越权操作AI 代理在 TDD 循环里偶尔会陷入“测试不过-改代码-再测试-再改”的无限循环浪费大量上下文。技能文件里一定要设置退出条件比如“同一处修改尝试三次仍未通过测试停下来向用户报告”。我更推荐在 AGENTS.md 里加一句“在执行任何可能影响大量文件的步骤之前先列出改动清单让用户确认”。这样虽然多了一次交互但能避免代理在无人看管时把项目改得面目全非。如果代理已经陷入死循环最快的紧急停止方式是 CtrlC 中断会话再重新开一个会话并让它先读取 progress.md从最近一次确认过的节点继续。永远不要在一个已经乱掉的会话里嗑到底上下文污染会让错误不断放大。5.4 版本兼容与依赖冲突问题速查我把这段时间遇到的环境类问题整理成了一个小表格方便你们排查现象可能原因解决方法代理不加载技能AGENTS.md 路径或大小写错误核对路径重启会话npm 安装失败Node 版本过低升级到 Node 18测试命令找不到Maven/Gradle 未配置检查 PATH使用完整命令代理读不到记忆文件开启时未执行读取指令在 AGENTS.md 中硬性要求读取代理频繁改无关文件缺少“改动前确认”规则在技能文件中增加确认节点配置后行为反而异常全局和项目 AGENTS.md 冲突保留一个入口另一个只做增量补充这张表看起来简单但每一条都来自真实的翻车经历。最让我印象深刻的是第二次配置时代理能说出全部技能名但执行时全部忽略最后发现是因为我同时放了全局和项目两个 AGENTS.md项目级的定义把全局的覆盖掉了而且写入的内容格式还是旧版。所以如果你用全局配置建议在项目里就不要放同名的 AGENTS.md或者明确让项目级文件只做增量补充。最后再分享一个小建议无论你怎么折腾 Superpowers都不要把它当成“装完就完事”的插件。真正重要的是那些技能文件里写的内容它们本质上是一份份工程思维模板。我一般会根据自己团队的项目类型把 tdd.md 里“运行测试”的具体命令从 mvn test 改成项目实际的命令把 debugging.md 里的日志路径也改成真实路径。技能和项目贴合得越紧代理的表现就越接近一个靠谱的同事。我个人使用下来最大的体会是Superpowers 不是一个魔法开关而是一套让你和 AI 代理对齐工作方式的“协议”。每次让它动手之前多问一句“你打算按哪套技能、先从哪一步开始”比任何模型参数都管用。这套流程我用了三周代码合入速度明显提升Review 时的争论也少了很多。希望这篇实战笔记能帮你少踩几个我已经踩过的坑。