先说个可能让不少人不太舒服的结论如果你还在让编码 Agent 问一句答一句地写代码那它在项目里的角色顶多算一个“手速很快、但不太懂事”的实习生。我用了小半年 Codex CLI起初的体感就是少敲了点键盘、补了点样板代码真正让我觉得“这东西像个队友”的转折点是给 Codex CLI 配上了 superpowers 这套开源项目。superpowers 并不是什么魔法模型也不是 IDE 插件它本质上是一套专门为 Codex CLI 这类 Agentic 编码工具设计的“提示词操作系统”。它通过 AGENTS.md、分层指令、技能库和项目记忆把 AI 的工作方式从“写函数”升级成“跑工程流程”。装上之后AI 会先拆需求、出方案再小步实现最后自己 review 代码、补文档、写提交信息整套动作就像有经验的工程师在旁边按节奏推进。这篇文章适合正在用 Codex CLI、或者被同类工具“高潜低产”搞到头疼的开发者。如果你想让 AI 从“被动回答”变成“主动干活”并且想直接复现一套可落地的工程工作流那下面这些内容应该能帮到你。我会从为什么非装不可讲起再到安装步骤、核心机制拆解、完整功能迭代实测最后把我踩过的坑和自定义技能的经验一起交底。1. 为什么我必须给 Codex 装一套“操作手册”superpowers 解决的三个真实痛点没装 superpowers 之前我总觉得 Codex 身上有种说不出的“半吊子感”。它能写出能跑的代码但总是差那临门一脚不拆任务、不记上下文、写完了不检查。后来我认真复盘了一下发现所有问题都可以归结为三个非常具体的痛点而 superpowers 恰好是围绕这三个痛点设计的。1.1 痛点一AI 会动手但不会按流程办事默认状态下的 Codex CLI你给它一句“给登录模块加个验证码”它会非常直接地开始改代码。表面上它完成了“加验证码”这个动作但实际交付的东西往往很单薄它可能只加了验证码字段和校验逻辑输入频率限制没做错误提示文案不统一测试也没有补。你让它写一个“创建订单接口”它能写但它不会先问“这个接口需不需要幂等需不需要防重事务边界在哪”这些工程上必须回答的问题默认状态它一概不问埋头就写。问题出在哪底层大模型本身并不内建“软件工程流程”这套知识它的系统提示词里只有通用的安全约束和格式要求没有“先分析需求、列候选方案、确认边界、再动手”这种职业习惯。而 superpowers 做的事情就是把这些职业习惯显式写成技能文档让 Agent 在执行任务时按步骤打开。它把“要求 AI 按流程做事”从一句空话变成了一个可以被加载、被执行的提示词剧本。1.2 痛点二跨会话的项目记忆几乎为零第二个让我很抓狂的点是Codex CLI 每次开一个新会话几乎都是“我失忆了请重新介绍这个项目”。虽然多轮对话里有上下文可一旦你关掉终端再开一个新会话它对外部世界的理解就只剩下 AGENTS.md 和项目代码目录结构。团队里那些真正影响决策的东西——为什么选这个框架、为什么错误码是这种风格、哪块逻辑历史包袱重不能动——默认的 Codex 一概不知。superpowers 的解法很朴素把项目级记忆变成一种明确的文件约定让 Agent 在开工前先读“项目记忆”并且在做出重要决策后主动写一段决策记录。这样一来跨会话不再是“每回都重新认识项目”而是“每次先翻一眼上次的会议纪要”。这个体验的差异本质上就是从“雇了个天天失忆的新人”到“来了个看日报就能接手的顾问”。1.3 痛点三写完代码不等于完成交付裸 Codex 的另一个大毛病是“交了活就结束了”。它不会回头看自己写的 diff不会主动补测试更不会更新 README。你让它封装一个工具函数它封装完就停在那边界条件没测调用方没改文档没写。我一度以为这是模型能力问题后来发现这是“流程缺位”问题——没有哪个环节告诉它“你还没做完你还要自查”。superpowers 把“交付前自我 review”变成工作流里的一环。它内置了代码审查、实现后复盘这类的技能在一个任务执行完毕后Agent 会主动重读一遍自己的改动检查边界条件、检查重复代码、确认测试覆盖甚至把变更要点记录下来。那一刻你会明显感觉到AI 在“完成”和“交付”之间终于有了一道该有的工序。2. 从裸装到启动superpowers 的安装、目录布局与第一次对话既然痛点清晰了那就直接进入实操。这一部分我把自己安装时看到的输出、目录结构、注意事项全部记录下来照着走就行。2.1 安装前需要准备什么安装 superpowers 之前你要确保本机已经装好了 Codex CLI 并完成账号登录因为它的所有运行场景都依附于 Codex 的会话能力。其次建议你找一个中小型项目先做实验别一上来就对着完整的大仓库直接启用不然第一次跑的时候你很难分辨某个奇怪行为是 superpowers 引起的还是项目本身太复杂导致的。有一个容易被忽略的点如果你之前手动改过~/.codex/AGENTS.md装之前一定先备份。这个文件是 Codex CLI 的全局指令入口superpowers 的安装脚本会修改它。不备份的话你原来调好的自定义规则可能被覆盖事后想找回只能靠记忆重写。其他前置条件基本没有它不引入新密钥不要求额外注册服务所有改动都只是文件级别的操作风险面很小。2.2 安装命令与安装过程实测安装方式很简单官方 README 提供的是经典的 curl 管道脚本我这里按记忆复述一下以仓库 README 的最新命令为准# 从 superpowers 仓库拉取安装脚本并执行 curl -fsSL https://raw.githubusercontent.com/obra/superpowers/main/scripts/install.sh | bash执行完之后你会看到类似这样的输出脚本先备份旧的AGENTS.md接着写入新的AGENTS.md然后拉取一份技能列表到本地。整个过程是纯文件操作不编译、不装依赖正常情况下十几秒就结束。如果你对管道脚本有顾虑也可以手动安装先把仓库 clone 下来然后手工把所有内容复制到~/.codex/目录下效果一样。但我不太推荐手动方式因为仓库的文件结构在不同版本里可能有调整跟着脚本走最省心。注意装完脚本后建议立刻打开~/.codex/AGENTS.md看一眼。如果它和你之前自定义的内容发生了合并你要确认合并结果是否合理。这一步很重要我后面还会专门讲到 AGENTS.md 冲突的坑。2.3 装完后的目录结构长什么样安装完成之后~/.codex/目录下会多出一批新文件和子目录核心结构大概是这样的~/.codex/ ├── AGENTS.md └── skills/ ├── brainstorm_plan/ ├── implementation/ ├── review/ ├── post_implementation_review/ └── ...其中AGENTS.md是总入口Codex CLI 每次新会话都会先读它。skills/里装的是一堆技能文件夹每个技能本质上是一份或多份 Markdown 文档里面写了这个技能的触发条件、执行步骤和验收标准。你可以把每个技能理解成“给 Agent 的一本剧本”它不是程序逻辑而是提示词逻辑。我第一次看到这堆目录时愣了一下因为它看起来太“轻”了全是 Markdown没有任何可执行文件。恰恰是这一点让我对它好感倍增——这意味着整个系统的行为完全可审查、可修改你不需要懂代码只要会写 Markdown就能调教 Agent 的做事方式。这一点对团队推广也极其友好因为没有人需要去理解复杂源码改文档就是改流程。2.4 第一次对话AI 的行为立刻不一样装完之后我特意开了一个新会话输入的是“先别写代码帮我理解一下这个仓库的支付部分然后给一个增加导出功能的方案。”放在没装 superpowers 之前Codex 大概率会直接开始翻代码然后给出实现代码。但装了之后它先做了一件事读取项目结构、列出一堆待确认的问题、然后输出了一段“当前理解 涉及模块 候选方案 风险点”的完整分析。那一刻我的感受是AI 的表现模式和之前完全不一样了它不再是“你抛一个点它接一个点”而是“你给一个目标它先帮你把地图摊开”。这种变化不是玄学而是因为 AGENTS.md 里的分层指令告诉它接到任务第一件事不是动手而是先理解上下文、澄清需求、提出计划。对任何用惯了默认 Codex 的人来说这个“第一次对话”的冲击感是最直观的。3. 分层指令与技能系统superpowers 的核心设计为什么“反直觉地有效”很多人第一次接触 superpowers 都会有个疑问这玩意不就是一堆 Markdown 吗凭什么一堆文档就能让 AI 变强这就要说到它的核心设计——分层指令和技能系统。理解这部分你才算真正会用而不是只会装。3.1 分层指令先定价值观再给方法论superpowers 在 AGENTS.md 里并不是把所有规则一股脑堆在一起而是采用了明显的分层结构。第一层先定义 Agent 的自我认知和行为原则比如“你是资深工程师要主动澄清需求、要对结果负责”第二层再定义它在代码库中的行动原则比如“改动前先理解现有代码、优先小步提交”再往后才是具体场景的方法论。这种结构和军队手册很像先讲使命与价值观再讲操典最后才是具体岗位的 SOP。为什么分层而不是堆砌因为大模型在长上下文中有一个很现实的问题注意力会被稀释。如果你给它一长串平铺的规则它很容易“看是看到了但不知道哪条优先”遇到具体任务时靠缘分选择遵循哪一条。分层之后Agent 每次只需要关注当前阶段对应的那一层规则之间的优先级也天然被层级表达出来了。这是一个反直觉但非常有效的设计不是让它记住更多规则而是让它每一刻只需要处理更少的规则。3.2 技能把好习惯固化成“按钮”技能系统是 superpowers 最核心的部分它解决的是“好习惯如何重复发生”的问题。你可以把技能想象成菜谱厨师不会把整本菜谱背下来而是做哪道菜就翻哪一页。Agent 也一样平时只加载总指令当它判断当前任务属于“实现功能”还是“代码审查”时才去打开对应的技能文档按里面的步骤执行。这样做的好处有三个。第一是省上下文技能按需加载不用每次会话都把几十个技能文档全塞进去。第二是可迭代团队觉得流程有问题直接改 Markdown 即可不需要改代码、不需要升级什么包。第三是可组合一个任务可以串起多个技能先用 brainstorm 技能拆需求再进 implementation 技能写代码最后用 review 技能收尾。我特别想强调“可组合”这件事因为这才是它像工作流引擎的原因。单个技能只是某个环节的 SOP但 Agent 可以在一次任务里连续触发多个技能形成一条完整的流水线。这就是为什么 superpowers 的效果不是“某个提示词厉害”而是整套流程设计厉害。3.3 项目记忆让 agent 像老员工一样记住约定除了分层指令和技能superpowers 还会强化对“项目记忆”的利用。实操中我慢慢总结了一套自己的用法在项目根目录建一个docs/decisions/文件夹要求 Agent 每次做出重要技术决策后往里面追加一条简短的决策记录内容包括背景、决策、理由、影响。这个习惯一旦形成效果立竿见影。举个例子我们项目里有段时间纠结支付回调的重试策略后来决定用指数退避而不是固定间隔。有了决策记录之后后续新会话再也不需要从头讨论一遍Agent 打开文件就能理解“为什么这里没法简单改成固定重试”。它像一个老员工的工作笔记把团队里最值钱的那部分知识沉淀了下来。而这在裸 Codex 时代基本不可能发生——因为它没有人告诉它“做完决策要记下来”。4. 实操走一遍用 superpowers 完成一次完整功能迭代说了这么多机制可能你已经在想真实项目里跑一遍是什么样的为了让你有直观感知我拿最近做的一个 Java 支付模块改造作为例子完整走一遍从需求分析到最终交付的流程。4.1 场景设定给 Java 支付模块加幂等校验任务背景是这样的payment-service模块的createOrder接口存在重复下单风险客户端超时重试时同一个userId merchantOrderId可能被提交两次。需求约束有四条幂等键由userId merchantOrderId生成幂等窗口为 24 小时窗口内重复请求返回原订单号而不是报错接口层行为要兼容旧客户端不能要求它们改造请求头补充单元测试覆盖重复请求场景。换成默认 Codex面对这种需求大概率会直接开始往 controller 里塞逻辑。但 superpowers 会先进入它工作流里的第一阶段。4.2 brainstorm 阶段先出方案再动手我在对话里明确告诉 Codex“请先做方案分析不要写代码。”它随即打开了任务规划类的技能流程输出了三个候选方案第一个是 RedisSETNX做分布式锁实现幂等第二个是数据库唯一索引兜底第三个是本地内存ConcurrentHashMap做轻量去重。然后它自己加了分析本地方案在单实例下可用一旦服务多实例部署就失效数据库唯一索引能兜底但不能完全解决并发窗口下的重复请求RedisSETNX在当前架构里最合适因为服务本来就依赖 Redis 做分布式缓存。让我比较意外的是它还主动追问了几个边界问题24 小时窗口结束后过期数据怎么清理事务回滚时幂等键要不要回填响应返回原订单号是否需要额外的一次查询这些问题在裸 Codex 时代根本不会自己冒出来。说白了brainstorm 这个阶段的价值不是让 AI 给你写方案文档而是它替你把需求里的坑先趟了一遍。4.3 implement 阶段按 diff 粒度推进方案确认后我让它继续实现。这时候它不是一口气把所有文件改完而是按照小步子的节奏推进先加一个IdempotencyService跑一遍测试再改CreateOrderService里的核心逻辑再跑测试最后接 controller 层的入口再跑测试。每次改动都以 diff 为单位改完就验证验证过了再往前走。中间我还特意打断了一次。我提出“幂等键里加一个来源端标识避免同一个用户在 Web 端和移动端同时下单时互相幂等。”我的本意是直接让它改没想到它先停下来重新评估这个改动会改变幂等键的定义需要同步调整注释、测试用例还涉及已有的幂等键是否有兼容转换问题。这个反应让我挺感慨——如果它没有先形成“改动前先评估影响面”这个习惯很可能就直接把键换了然后线上存量请求全变成重复请求。4.4 review 阶段交付前自己审自己功能写完、单测跑过之后我一度以为流程结束了。结果 superpowers 自动进入了 review 阶段重新读了一遍自己的 diff输出了几个怀疑点幂等键为空字符串时校验是否覆盖到了Redis 键过期和事务提交之间的时序有没有可能造成“先删除键再回滚事务”的问题重复请求返回原订单号时是否真的走的是查询逻辑而不是直接返回缓存这些问题有些是我之前想过但没来得及提的有些是它自己从技能文档里学来的检查项。最终它修掉了一个潜在 NPE补了一个测试用例还更新了接口说明文档。讲真看到它“写完代码主动回头检查”这个动作的时候我才意识到以前默认 Codex 最大的缺的不是能力而是没人教它“交付前要回头看看”。5. 我踩过的坑与调优经验AGENTS.md 冲突、token 开销和自定义技能模板工具再好用起来总有反直觉的地方。这一部分我把自己真实踩过的坑整理出来每一条都是因为不在意而浪费过时间的教训希望对你有帮助。5.1 坑一AGENTS.md 被覆盖了我第一次给项目接 superpowers 时项目根目录里本来就有自己写的AGENTS.md里面放了一些项目专属规范比如“错误码必须统一从 ErrorCode 枚举引用”“禁止在 Service 层直接操作 Redis 连接”。装完 superpowers 后我发现在某些对话里 Agent 的行为变得很怪一会儿表现得知道 superpowers 的流程一会儿又突然忘了。查了半天才发现Codex CLI 的指令加载机制里全局~/.codex/AGENTS.md和项目根目录的AGENTS.md会同时生效。superpowers 写的是全局文件而项目根目录的AGENTS.md如果写了不少条目并且某些条目和它冲突Agent 在执行时就会出现“两套规则打架”的混乱感。我的处理办法是项目根目录的文件只保留业务专属约定凡是涉及工作方法的规则都交给 superpowers 的全局配置。如果你必须修改全局配置记得在备份的基础上做增量修改不要整体重写否则下回升级脚本一跑你的修改又会消失。5.2 坑二上下文窗口被技能文档塞满用了一段时间后我开始大量自定义技能结果 Codex CLI 的响应明显变慢偶尔还出现“一句话没说完就截断”的情况。后来我做了个实验把会话刚开始时的完整系统提示词 dump 出来看了一眼发现技能文档被加载了不少冗余内容而真正执行任务用到的其实只有两三个技能。也就是说大量技能文档白白占用了上下文窗口。解决方式有三个我后来都在用。第一控制每个技能文档的长度只保留步骤骨架和验收标准详细说明拆到独立文档里用到时再让 Agent 读。第二在对话里明确指定技能比如直接说“用 implementation 技能处理这个改动”减少它自己翻找技能文档的频率。第三把不常用的技能移出主目录放进按场景分组的子目录需要时再临时引入。5.3 坑三技能不是越堆越好刚开始接触技能系统时我犯过一个特别典型的错误我把所有“我认为对的规则”都写成技能比如“所有方法必须写 JavaDoc”“禁止在代码里留 TODO”“函数行数不能超过 50 行”。结果 Agent 的行为变得极其拧巴尤其在 review 阶段它开始疯狂挑自己代码的刺这个没写注释、那个行数超了、那个命名不够优雅最后为了满足规则把本来很清晰的一小段代码拆成一堆碎片。后来我才想明白技能包里的规则要分两类一类是行为收束规则比如“必须先跑测试再提交”另一类是质量调优规则比如命名规范、注释密度。前者应该做成技能因为它在流程中起作用后者更适合放进项目记忆里做参考而不是变成强硬的验收标准。自定义技能时验收标准一定要客观可判定尽量用“测试通过、无重复代码、关键路径有日志”这类事实性描述少用“高质量、优雅、健壮”这种主观词。5.4 自定义一个团队技能最小可运行模板最后分享一个我实际给团队加过的自定义技能模板非常小但很实用做的是“每日站会总结”。放在这里给你做个参考看完你就能照着设计自己的技能。# 技能名: daily_standup_summary # 触发条件: 用户说“生成站会总结”或“今天改了什么” # 步骤: 1. 运行 git log --since24 hours ago --prettyformat:%h %s 2. 按模块归类提交记录 3. 检查 git status标出未提交的改动和 TODO 4. 输出三段式 - 昨日完成 - 今日计划 - 阻塞问题 # 验收标准: - 三类信息齐全 - 每条提交都有对应的简短描述 - 未提交改动单独列出不能混进“昨日完成”存放位置一般是~/.codex/skills/daily_standup_summary/下面具体文件名可以参考仓库里已有技能的组织方式。这个技能上线后团队每天开早会前让 Codex 跑一遍大家的站会从“现场翻 git 记录”变成了“照着 AI 总结念”效率提升很明显。说实话用到现在我已经不太满足于拿 superpowers 只干“写代码”这件事了。它给我最大的启发其实是“把工作方法固化成文件”这套思路本身给 Agent 装文档、定流程、留记忆它就不再是问答机器而是一个可以跟着你节奏推进项目的人。如果你也想从“让 AI 帮我写代码”升级到“让 AI 跟着我一起干活”我建议你从装好它、完整跑通一次迭代开始中间踩坑了再回来调技能这个循环本身就是最有价值的部分。
