上次我在终端里敲下 codex让它重构一个老模块。半小时后回来它已经把代码改成了一千行连编译都没过。那一刻我意识到 Codex 缺的不是能力而是一套工作方法。后来我找到 Superpowers问题才真正解决。Superpowers 不是模型也不是传统插件它是一组预先定义好的技能文件能让 Codex CLI 在执行任务前先扫描代码、写方案、拆步骤、跑测试把 AI 从“只会动手的实习生”变成“有章法的工程师”。这篇文章适合正在用 Codex CLI、却总觉得它缺少项目级思考能力的人。我按安装、核心技能、实操案例、避坑经验四块来讲看完你基本就能自己把流程跑通。1. 先搞清楚 Superpowers 解决的是哪个问题1.1 Codex CLI 很聪明但它缺少“工作方法”Codex CLI 的定位是终端里帮你写代码的 AI 代理。它能读文件、改代码、执行命令这些基础能力非常强。可默认的工作模式是“你一句它一步”。你让它给用户模块加一个分页方法它可能立刻翻开文件在 Service 里插一个方法然后结束。这个过程看起来效率很高但如果你让它处理“订单模块需要增加退款流程同时把支付回调梳理清楚”这种多文件、多步骤的任务它大概率会直接从中间某个文件开始写忽略整体依赖关系最后交出一份表面能跑、一上线就出问题的改动。问题不在于模型本身而在于缺少前置流程。一个专业工程师接到重构任务时不会上来就改代码。他会先确认项目结构梳理依赖再写一个方案明确改动范围然后才动手。Codex 默认没有这套动作所以它经常“很勤快但方向不对”。Superpowers 就是给 Codex 补上这套流程的一套外部约定它让 AI 在动手前先学会“思考”。1.2 Superpowers 是一套“技能包”不是普通插件很多人第一反应是“这不就是一个 Codex 插件吗”其实不太一样。Superpowers 的核心是几十个 Markdown 格式的技能描述文件。每个文件定义了一种工作模式比如“先扫描整个代码库再回答”“先写一份改动提案等用户确认再动手”“任务拆成三个阶段并逐步验证”。Codex 启动时加载这些技能根据你的指令触发对应技能。你完全可以把这理解成给一个聪明的实习生发了一本员工手册。实习生的智商没有变但他做事的顺序、沟通方式、交付标准都被校准到了专业工程师的水平。这也是 Superpowers 最巧妙的地方它没有重新发明一套 Agent 框架也没有侵入式地改 Codex 内部逻辑只是用清晰的流程提示词把 AI 的默认行为“掰”到了更靠谱的方向上。1.3 它适合谁又不适合谁先说适合的人。第一类正在用 Codex CLI 或类似 AI 编程工具想提升任务完成质量的开发者第二类维护老项目经常需要跨文件改动的工程师第三类希望 AI 不仅输出代码还能输出方案、测试计划和风险清单的人。不适合的人也很明确。完全没接触过命令行的新手可能连 Codex 环境都还没跑通这时候再加技能包只会更乱。只希望 AI 补个函数、写个正则的轻量用户也不必折腾 Superpowers因为每个技能加载都会占用上下文窗口小任务反而被拖慢。还有一种人也不适合就是期待“一键全自动”的人。Superpowers 并不打算取代人做决策它只是让 AI 更规范地提出方案最后拍板的人依然是你。2. 三步完成 Superpowers 安装与验证2.1 前置环境版本与运行时检查在拉技能包之前先确认机器环境没问题。我吃过亏第一次装完一直加载失败后来发现是 Node 版本太老技能里某个脚本跑不动。先执行codex --version node -vCodex CLI 本身是 Node.js 应用建议 Node 版本不低于 18。部分技能还会依赖git、rg这类命令行工具所以git --version最好也看一下。如果版本太旧先用 nvm 把 Node 切换到一个较新的版本再重新进入 Codex 对话界面确认命令行本身能正常使用。不要跳过这步后面很多奇怪的报错都是环境不一致导致的。2.2 安装 Superpowers 技能包到本地目录目前社区里比较常见的安装方法是把技能仓库 clone 到本地的 Codex skills 目录。以 macOS 和 Linux 为例先创建目录再拉代码mkdir -p ~/.codex/skills git clone superpowers仓库地址 ~/.codex/skills/superpowers具体仓库地址请以你当前搜索结果里的官方链接为准下载前尽量点进去看一眼项目描述确认它适配的是 Codex CLI 而不是别的工具。clone 完成后目录结构大致长这样~/.codex/skills/superpowers/ ├── skills/ │ ├── codebase-scanner/ │ │ └── SKILL.md │ ├── proposal-writer/ │ ├── task-runner/ │ └── test-runner/ ├── AGENTS.md └── README.md这一步做完Codex 还不知道去哪找技能。需要告诉它技能目录的位置。不同版本配置方式略有差异我习惯在~/.codex/config.toml里加一行skills_path ~/.codex/skills保存后重启终端里的codex再输入/skills或者直接问它“你现在加载了哪些技能”。如果能看到 superpowers 下列出的技能名称说明安装成功。2.3 在 Trae Work CN 等 AI IDE 里安装有什么不同如果你用的是 Trae Work CN 这类 AI IDE不需要改 config.toml。通常到设置里找“技能 / Skills”或“Agent 扩展”面板把本地技能目录添加进去即可。不同版本命名可能不太一样但核心动作就是指定技能文件所在目录。这里要提醒一句IDE 内部的 skill 目录和 Codex CLI 的 skills 目录不一定共用别在 Codex 里装完就以为 IDE 里也能用。最好的验证方式是装完后在 IDE 的对话框里发一条指令让 AI 调用 codebase-scanner 扫描当前项目能输出摘要才算真正生效。界面显示“已加载”有时候只是配置成功不一定代表运行时能读到。2.4 验证安装是否真正生效我推荐用一个最小的任务做验证不要一上来就跑复杂命令。比如打开一个项目目录输入请使用 codebase-scanner 技能分析当前项目根目录的模块结构并输出一份简化依赖图。如果 AI 正常输出项目的目录层级、核心依赖、潜在风险点说明技能生效。如果它回答“我没有这个技能”大概率是技能目录没被扫描到或者配置路径写错。先回去检查skills_path再确认目录名称是不是superpowers最后重启终端。这类问题九成出在这三个环节。3. Superpowers 核心技能拆解AI 新员工手册里写了什么3.1 Codebase Scanner动手之前的“全局面板”这个技能的价值在于让 AI 在改代码之前先对整个项目做一次性体检。它会读取目录树、提取关键依赖、标记出高内聚和低内聚的模块最后给你一份简洁摘要。我在接手一个不熟悉的老项目时最喜欢先触发它。比如说“帮我把这个项目扫描一遍我想知道用户认证模块涉及哪些文件”它会先列出所有可能相关的文件而不是直接打开某一个文件就开始改。这个动作看着简单实际能拦住大量“改错地方”的问题。很多时候 AI 之所以改出不可维护的代码不是因为模型不聪明而是它在信息不足的情况下被迫做了决策。3.2 Proposal Writer先写方案再动手这个技能让 AI 在做大改动前生成一份“重构提案”或“功能提案”。提案内容包括现状分析、改动方案、影响范围、测试计划、回滚方案。你审核通过后再让它进入执行阶段。个人认为这是整个 Superpowers 里价值最高的一个技能。Codex 默认太“实干”了你让它改 100 行它能立刻动手但改完你才发现方向跑偏。有了提案流程90% 的方向性错误可以在动手之前被拦截。比如说让 AI 重构一个支付模块它可能会写现状是支付回调里混了订单状态更新逻辑建议拆出独立的支付状态机影响范围主要涉及支付服务和订单服务测试计划先补三个回归用例。这时候你就能看到它的思路及时纠偏而不是等改完再返工。3.3 Task Runner把大任务拆成可验证的小步骤Task Runner 的作用是把一个大任务拆解成一系列子步骤然后按依赖顺序逐步执行每步之间做验证或提交代码。它相当于给 AI 加了一套检查点机制。举个例子你说“给项目增加一个 Redis 缓存层”。如果让 Codex 直接做它可能一口气改十几个文件最后你都不知道从哪开始 review。但 Task Runner 会把它拆成分析现有数据读取链路、设计缓存结构和 key 规则、实现缓存操作类、接入核心路径、跑一轮回归测试。每一步完成都有输出你可以中途叫停也可以让 AI 分批提交代码。这种工作方式很接近一个中级工程师在真实项目里的推进节奏。3.4 Test Runner让 AI 自己写测试并跑通这个技能会在 AI 改完代码后自动生成或更新相关测试然后执行测试命令。如果测试挂了AI 会看失败日志尝试修复再继续测试最后提交代码。它最大的价值是防止“AI 改完就说改好了根本没验证”的尴尬。我过去踩过很多次坑Codex 信誓旦旦说“已完成”但一跑测试满屏红。装上 Test Runner 之后AI 至少在交付前会自己跑一遍测试并把测试结果附在回复里。注意它并不能保证测试一定通过但它能把“有没有验证”这件事变得透明。下面是核心技能速查表技能名称触发场景主要输出codebase-scanner不熟悉项目结构、跨模块改动前目录结构、依赖关系、风险点摘要proposal-writer需求复杂、改动范围大、需要评审现状分析、改动方案、测试计划、回滚方案task-runner多步骤任务、需要中途检查点子任务清单、执行进度、提交记录test-runner代码改动完成、需要验证测试用例、测试结果、修复记录4. 实操实录在旧项目里用 Superpowers 重构路由4.1 场景设定一个 2500 行的 Express 老项目我手头有一个 Express MongoDB 的旧项目所有路由都堆在app.js里总共 2500 行没有测试每次加功能都提心吊胆。目标很简单把路由拆成 auth、user、order 三个模块补一个基础冒烟测试同时写清楚 README。我给自己定了几条约束不能改变现有 API 的对外路径和响应格式每一步用 git 提交每一步必须能回滚。这种需求如果用默认 Codex它大概率会一次性改完所有文件过程中还可能顺手“优化”掉某些参数名。所以我这次把 Superpowers 整个流程串起来用。4.2 第一步用 codebase-scanner 建立全局面板我先在 Codex 里输入请用 codebase-scanner 技能分析当前项目我要知道 1. app.js 里注册了哪些路由 2. 数据模型有哪些 3. 哪些中间件是全局的。AI 很快输出了一张表把所有路由路径、对应回调函数、全局中间件列得清清楚楚。它还额外指出三个路由存在重复的校验逻辑建议拆分时顺便封装成公共方法。这个摘要让我后续拆分这部分时不需要自己一行一行翻 2500 行代码省了不少时间。4.3 第二步用 proposal-writer 确定改动边界紧接着我让 AI 用 proposal-writer 输出重构提案。提案里需要写清楚拆成 auth、user、order 三个路由模块统一通过app.use(/api/auth, authRouter)的方式挂载每一步用 git 提交并写明验证方式禁止改动数据库字段名。AI 生成提案后我发现它在影响范围里漏掉了app.js中一个启动时的数据库连接错误处理于是我追加了一条要求让它在拆分路由的同时保留主文件里的错误处理逻辑。确认提案没问题后我才让它开始改代码。这一步多花了十分钟但避免了一次方向性返工。4.4 第三步让 task-runner 按流程执行并用 test-runner 守门确认提案后我让 AI 用 task-runner 基于提案执行。它按顺序做了四件事先把现有逻辑复制到新路由文件再修改app.js的挂载路径接着跑一遍基础 curl 请求最后打一个 git commit。中途确实出了状况在复制一个路由时AI 弄丢了一个错误处理中间件导致某个接口在异常情况下会直接 500。好在 task-runner 在每步之间要求验证test-runner 自动生成了一个冒烟测试把这个错误给逮住了。AI 看了失败日志后补回了中间件重新跑测试通过然后提交。整个过程大概二十分钟比我预想中顺利得多。4.5 实操中值得注意的两个细节第一个细节提案不是用来“走形式”的它最大的作用是逼 AI 把自己想怎么做说清楚。你在审核提案时会立刻发现它有没有理解需求边界。如果它写的方案里出现了你不知道的依赖一定要追问否则后面执行必然跑偏。第二个细节任务拆得越细越容易发现问题。task-runner 如果在某一步失败它只会回退到最近一个检查点而不是把整个项目搞得一团糟。所以强烈建议在项目里启用 git并且在每个阶段结束前让 AI 提交一次。这样你随时可以 diff 看它到底改了哪里而不是只能听它一面之词。5. 常见问题排查与避坑别让技能包变成包袱5.1 技能不生效怎么办这是安装后最常碰到的问题。我把它整理成一个速查表症状可能原因排查方式AI 说没有这个技能技能目录未加载检查 config 里 skills_path 是否写对重启终端技能列表能看到但对话里触发不了指令里没带技能名在 prompt 里明确写“使用 xxx 技能”技能触发了但输出很乱技能文件格式不对检查 SKILL.md 头部是否有 YAML frontmatter某些技能能跑某些不能依赖的运行时工具缺失跑一遍node -v、git --version缺什么补什么我碰到最隐蔽的问题是在 Windows 下配置路径。路径分隔符如果用了反斜杠Codex 解析时可能出问题。统一改成正斜杠或者用双反斜杠转义一般就能解决。5.2 上下文被撑爆AI 开始胡言乱语Superpowers 的技能越多系统提示词前缀就越长上下文窗口会被提前占满。尤其是一些大项目AI 还需要读取大量文件很快就会超过上下文限制然后开始忽略早期指令甚至重复输出。解决办法只有一个精简技能。只保留自己高频使用的技能把用不到的移动到备份目录。还有一个小技巧大项目里先用 codebase-scanner 输出摘要再基于摘要做后续操作不要一次性把日志和全部源码都喂给 AI。上下文窗口是有限的把空间留给真正重要的代码。5.3 权限问题导致技能无法读取在 Linux 和 macOS 上如果技能目录没有读权限Codex 会静默跳过加载不报错但也不生效。先检查一下ls -la ~/.codex/skills/如果 owner 不是当前用户或者权限位是---执行chmod -R ur ~/.codex/skills有时候还要给目录加执行权限否则无法进入子目录chmod -R urx ~/.codex/skills5.4 不要过度自动化技能越多不代表越好这是我最想提醒的一点。第一次装好 Superpowers 后我兴奋地把所有技能全开了结果本来 5 分钟能改完的一个小需求AI 先扫描项目、再写提案、又加了一堆测试最后耗时比我手动改还久。后来我把默认技能收敛到两个codebase-scanner 和 proposal-writer。遇到真正需要多步骤重构的大任务才临时触发 task-runner。test-runner 只在涉及核心逻辑改动时启用。这样才找回了“可控”的感觉。Superpowers 的价值不在于让 AI 每次都跑完整套流程而在于当你需要更严谨的流程时它能接得住。反过来如果不管任务大小都让 AI 走完整套仪式流程那它就会变成新的负担。6. 写在最后快速上手的两个建议如果你现在正在折腾 Codex CLI我的第一个建议是先别把整包技能全部打开。装好 Superpowers 后只启用 codebase-scanner 和 proposal-writer 这两个技能用一周感受一下“有工作方法”和“只会接指令”之间的区别。等确实遇到需要大规模重构的任务再去把 task-runner 和 test-runner 打开。第二个建议是把“要求 AI 在改动前输出提案”写进项目根目录的AGENTS.md里。这样即使某次你忘记明确指定技能AI 也会因为这个项目级约定自动先做分析和提案。我试过这个办法之后Codex 的返工率明显降低它不再像个愣头青一样上来就改代码了。最后分享一个真实体会Superpowers 本身不会提升模型的智商它改变的是工作节奏。它把一个“你问一句、它答一句”的 AI 对话变成了一个“先调研、再提案、后执行、边验证”的协作流程。如果你愿意在流程上多花几分钟它带给你的回报远不止省下的那几个小时。希望这篇能帮你少走一点弯路。