最近大家都在聊 AI 编程口号喊得震天响什么“AI 替你写代码”“Agent 自主开发”。可真把活儿交出去不少人发现事情没那么简单写个 Demo 没问题一问项目里的业务细节就露馅多步任务做着做着就忘了上下文改完代码连测试都不跑就敢跟你汇报“完成”。我一开始也觉得是模型不够强后来折腾了几轮才发现问题多半出在流程上——AI 不缺代码能力缺的是“怎么像个正经工程师一样干活”的约束和引导。这就是我关注superpowers这类项目的原因。它不是模型不是 IDE 插件而是一套开源的技能包和工作流目标很直白给 Codex 这类编程 Agent 叠加“资深工程师的方法论”。装上之后Agent 会先规划再动手遇到问题知道怎么拆解写完代码记得验证而不是一上来就瞎改文件。这篇文章就围绕superpowers的安装、使用和原理做一次完整拆解包括我在 Java 项目里的真实体验、和其他协作工具联动的玩法以及排查过程中踩过的坑。无论你是在用 Codex CLI还是在研究怎么让 AI 更靠谱地接活这篇都值得看完。1. 从“会写代码”到“会干活”Superpowers 要解决的真正痛点1.1 AI 编程工具的“三分钟热度”困境现在的编程 Agent 给人最初的冲击感很强。你丢给它一个需求“帮我写一个带分页的博客系统”它哗啦哗啦给你生成一堆文件甚至能跑起来那一刻你会觉得程序员要失业了。但别高兴太早等需求稍微复杂一点——比如“在现有的用户模块里加一个积分体系并且要兼容老数据”——Agent 的表现立刻两极分化。有的会自顾自地创建新文件把老逻辑晾在一边有的会在十几个文件之间反复横跳改到一半忘了最初的目标还有的更离谱改完代码不跑测试就说完成了。这背后的原因不复杂。模型本身的智能水平并不差但它在默认状态下是“自由发挥”的没有项目全貌认知、没有步骤约束、没有“先想清楚再写代码”的强制节点。就像一个刚入行的新人代码能力有 80 分但工程素养只有 30 分。你直接命令他“把这个模块改好”他可能非常积极地动手但方向完全跑偏。superpowers想解决的就是这中间的 50 分差距。它的思路不是给你换个更强的模型而是给 Agent 一套完整的工作协议什么时候该停下来思考思考什么问题用什么格式输出计划按什么顺序执行修改做完之后要跑哪些验证。这些都是资深工程师每天都在做的事只是被打包成了可复用的“技能”。1.2 为什么不是更贵的模型而是更靠谱的工作流有一种很流行的观点是“只要模型够强就不需要调 prompt不需要什么技能包”。这个观点听起来很爽但实际操作中不太成立。即便模型再强它面对一个具体项目时依然缺乏组织约束它不知道你团队要求一次提交不要超过 200 行不知道你们的老系统里哪些模块是动不得的雷区也不知道改完接口之后要同步更新下游调用方。你可以把这些都写进 prompt但问题在于一个任务描述里塞的东西越多模型越容易忽略后面的部分。更好的方式是像superpowers这样把约束和流程做成“按需加载”的模块。需要规划的时候就加载规划技能需要调试的时候就加载调试技能Agent 不会被一大段冗长的系统提示冲昏头脑而是像人一样在不同阶段调用不同的方法。我用一个生活化的类比来解释工具链再好也就是给你一把好刀而技能包相当于刀法。你手上是一把大马士革刀但刀法稀烂切菜照样切到手反过来一把普通菜刀配上一套扎实的切配流程出来的活可能更稳定。AI 编程工具已经足够锋利了缺的恰恰是一套值得信赖的切配流程。2. Superpowers 的底层逻辑把资深工程师的方法论“技能化”2.1 技能包Skill Pack机制拆解superpowers的核心单位是“技能包”英文通常叫 Skill Pack。你可以把它理解成一本本 Markdown 写成的“操作手册”每一本规定了一个具体场景下 Agent 应该怎么行动。比如有一个技能包叫“实现规划”它告诉 Agent在动手之前先列出当前系统的相关模块、数据流、风险点再输出一份任务拆解列表最后等着人类确认。又比如有一个技能包叫“调试复盘”它规定 Agent 在做完修改之后必须回顾最初的目标逐条核对是否全部完成如果有遗漏就继续补。这套机制最妙的地方在于技能包不会被一次性全部塞进上下文。项目里可能有几十个技能包但 Agent 在每次对话里只会根据当前任务激活相关的两三个。这样既保证了上下文不被无关内容挤占又让技能的描述质量更高。具体到 Codex CLI 这类工具上技能包通常常驻在项目里的skills/目录Agent 通过约定好的目录扫描机制发现它们需要时以特定格式调用。我最初以为技能包就是普通的 prompt 模板试过之后才发现区别很大。普通模板是“一次性”的用户在对话里粘贴一段长长的指令Agent 照着做但做完就忘下一轮对话又得重新粘贴。而技能包是“可注册、可发现、可反复调用”的Agent 能感知到技能的存在并且在获得明确信号时主动加载执行。这就好比一个新人手边放着一本随时可以翻的规章手册而不是领导在开工前念一遍长篇大论。2.2 规划—执行—验证三段式工作流superpowers的另一块基石是把工作过程强制拆成三个阶段的循环规划阶段执行阶段验证阶段。规划阶段 Agent 不允许写代码只允许调查项目结构、阅读关键文件、提出计划。执行阶段严格按计划推进每完成一个子任务就在计划清单上打钩。验证阶段则是跑测试、查 diff、回顾需求全部通过了才把结果交给人类。这个三段式听起来简单但对 Agent 行为的改善是立竿见影的。默认状态下Agent 接到任务是“一步到位”模式脑子里没有计划的概念容易在细节里迷失有了强制的规划节点后它必须先输出方案你可以在它动手之前就把跑偏的苗头掐灭。我在实际使用中深有体会一次让 Codex 给一个老的 Java 服务加导出功能它刚打算在 Controller 里直接堆上传逻辑时由于规划技能要求先生成“影响面分析”它自己就发现了这个问题最后写出的计划比我预期的还要严谨。验证阶段的价值往往被低估。很多 Agent 翻车的场景是改完代码宣布完成但项目根本编译不过。superpowers把“必须验证”写进了工作协议要求 Agent 主动运行构建命令、运行测试甚至观察测试日志中是否有新的 warning。这能拦住一批“看起来完成了实际上没完成”的假成功。2.3 为什么用 Markdown 而不是代码来描述技能这一点可能是很多人忽略的细节。技能包文件全部是 markdown 格式不是 .ts 或 .py 代码背后有一个很实在的考量技能包既要给人看也要给模型看。Markdown 对 LLM 的解析相当友好结构清晰、层级分明模型读取时能很快抓住要点而对于人类维护者来说Markdown 又是最容易阅读和修改的格式你可以把一大段技能说明当作写文档一样去组织。此外Markdown 是纯文本天然支持 git 版本管理。技能包改错了可以 revert想对比两个版本的差异可以直接 git diff。如果你在一个团队里推广 AI 工程规范这几乎是唯一合理的载体——你没法要求每个团队的成员都会写代码但要求他们会写 Markdown 文档这就现实多了。社区里的技能包项目也大多采用这个格式你可以直接在 GitHub 上 fork 一份别人的技能包按自己团队的规范改一版pull request 流程完全走代码评审的路子。3. 安装与初始化三步让 Codex 装上 Superpowers3.1 环境准备与依赖检查在拉取技能包之前先确认你手头的环境是齐的。superpowers不是独立的可执行程序它是寄生在 Codex CLI 这类 Agent 工具上的配置与技能层所以你的机器上必须已经有一个能正常工作的 Codex CLI。所谓“能正常工作”指的是你已经配好了 API 权限并且在最简单的任务上跑通过一次对话。另外需要确认安装了 git因为技能包的获取和更新都靠 git 完成。我常用的检查命令组合是这样的codex --version git --version如果两个命令都能正常输出版本号就说明基础环境没问题。接着我会用一个极小的任务做“冒烟测试”比如让 Codex 读取当前目录下的一个文件内容并简单总结。这个小任务能验证 API 链路通不通免得后面装完技能包才发现其实 Agent 本身就在报错白折腾半天。还有一点值得提前说superpowers项目本身在持续迭代不同版本对 Codex CLI 的支持程度可能不同。稳妥的做法是先看一眼项目的 README确认当前分支对 Codex CLI 的兼容性说明再决定拉取哪个分支。有些老项目用的是main分支但最新的工作重心放在了experimental分支上。如果你只想求稳用默认分支加最新稳定版 Codex CLI 的组合能免掉 90% 的兼容性烦恼。3.2 拉取技能包与目录结构说明环境就绪之后拉取技能包本身非常简单本质上就是克隆一个仓库到你指定的目录。我用的是项目的默认推荐方式把仓库放到家目录下的.superpowers文件夹然后在项目级或用户级配置里引用它。git clone https://github.com/example/superpowers.git ~/.superpowers克隆完之后建议花几分钟熟悉一下目录里的核心结构。典型的技能包仓库通常会包含这些部分skills/技能包的存放目录每一个子文件夹就是一个技能里面含SKILL.md文件agents/面向不同 Agent 工具Codex CLI、其他终端 Agent的适配配置docs/使用文档、设计理念和最佳实践examples/不同语言和使用场景的示例工程。skills/目录是你之后最常打交道的地方。每个技能的SKILL.md文件里有一段 YAML front matter声明技能的名称、描述、适用场景正文部分则是具体的操作步骤和规范要求。你完全可以把它当作“给 AI 员工看的岗位说明书”来理解。3.3 把 Superpowers 注册到 Codex CLI技能包拉下来之后并不会自动生效你需要在 Codex CLI 里“注册”它。当前多数主流做法是通过项目下的AGENTS.md文件来声明技能目录的位置。这个文件会被 Codex 自动发现相当于告诉 Agent去哪里找这些技能、哪些技能在什么情况下启用。以典型的配置为例在项目根目录创建或修改AGENTS.md写入类似下面的内容# Project Agent Configuration ## Superpowers Skills The following skill directories are available for this project: - User Skills: ~/.superpowers/skills When starting a task, check the skills directory for instructions relevant to the task.这段配置的作用是让 Agent 在每次会话启动时都知道技能包的位置并且被要求按需查找技能。配置完成后重启 Codex CLI随便开始一个新会话先确认基础命令是否正常。如果你在 Codex 的会话里执行技能列表命令能看到superpowers的相关技能已经出现就说明注册成功了。补充一个我自己的习惯我会先跑一个最轻量的技能验证端到端链路。比如让 Agent 读取某个技能包的说明并总结它应该如何规划一个任务。如果它能准确复述技能包里的关键步骤说明技能已经被真正加载而不是仅仅“看起来被加载了”。这一步验证多花两分钟能省下后面排错的好几个小时。4. 核心技能拆解与实际场景配置4.1 技能库全景规划、调试、重构、测试普通的 Agent 提示词只会告诉 AI“你是一个编程助手”而技能包给的是“你遇到这种情况时按这几步做”。我把目前社区里最常用的一批技能整理成了表格方便你按需取用技能名称触发方式核心作用典型应用场景实现规划接到复杂需求时激活先做影响面分析输出任务拆解清单多文件跨模块的功能开发调试复盘测试失败或结果不符时激活定位根因、尝试修复、回归验证排查线上 bug、修复测试报错代码审查完成修改后激活自查代码规范、逻辑漏洞、边界问题提交前自检、减少返工重构助手识别到重复代码时激活设计重构方案分步执行并保持行为不变清理老项目里的坏味道测试驱动从零开发新功能时激活先写失败测试再实现逻辑最后让测试通过新模块开发、需求明确的功能这些技能不是孤立的它们组合起来就是一个完整的工程闭环。你在新需求里先调用规划技能再按计划实现实现过程中遇到问题调用调试技能写完调用代码审查技能。熟练掌握后你会感觉自己不是在指挥一个代码生成器而是在给一个远程的初级工程师派活。4.2 实战在 Java 项目里用 Superpowers 做一次增量重构理论讲再多不如看一次实战。我用一个真实的 Java 项目场景来说说整个过程。任务是给一个老服务加一个“用户行为日志导出”接口看起来不复杂但这个服务已经跑了几年中间换过好几拨人代码里的历史包袱相当重。如果是我自己动手先得花大半天读代码、理依赖、摸清老项目的套路。而现在我在 Codex CLI 里发出任务“请为现有的用户模块新增行为日志导出接口。先按照技能包完成影响面分析和实施计划计划确认后再动手实现。”Agent 首先激活了规划技能。它没有立刻写代码而是先后打开了pom.xml确认依赖关系检查了UserController和LogService的现有结构甚至翻看了数据库访问层的 DAO 代码。几分钟后它输出了一份计划内容包括新增一个ExportController提供导出入口复用现有的LogService查询方法不新建数据访问层在 service 层增加一个导出专用的组装方法避免直接返回大对象导致内存压力。计划的最后还标注了两个风险点老系统的一个查询方法没有分页直接导出可能导致 OOM另一个风险是日期的时区处理容易出问题。这份计划比我预想的专业尤其那两个风险点确实只有熟悉项目的人才能提出来。我确认计划后Agent 才进入执行阶段。它按照计划逐项完成每个文件修改后都会生成简短说明并标出改动是否符合计划。最后一步是验证阶段Agent 主动跑了mvn -q compile和相关的单元测试。中途确实遇到了测试失败——它调整了一个Date的类型转换参数导致一个旧测试断言不过。这时调试技能发挥的作用很大Agent 没有直接改测试去迎合代码而是检查了新代码的时区处理逻辑发现确实有边界问题于是调整了实现最终让原有测试全部通过新增的导出测试也稳定通过。整个过程我从头到尾没有动过一行代码只在关键节点上做确认。耗时大约一个多小时包含读代码和分析的时间换成人工怎么也要半天以上。更重要的是Agent 全程没有让我操心“它是不是在瞎改”每个步骤都有计划有依据这比它多快完成都让我安心。4.3 和其他工具联动WorkBuddy 这类团队场景怎么玩superpowers不只活在 Codex CLI 的终端里它的技能包格式被不少团队级 AI 工具采纳。最近很多人搜“worbuddy 怎么用 superpowers”我猜大概率是在团队协作的场景里遇到了同一个问题如何在群里或者工作流工具里让 AI 也具备“先规划再执行”的能力。以 WorkBuddy 这类团队协作 Agent 工具为例通用做法是把技能包目录挂载为团队的共享知识源。你可以把skills/里的技能文件同步到团队项目的共享空间然后在工作流配置中设置一个基础指令任何来自成员的需求Agent 都要先检查共享空间中的技能目录按照对应的技能流程执行。这样团队里的每个人都能受益于同一套工程规范而不只是你终端里那个 Codex。实际效果我最满意的一个场景是在团队协作群里说了一句“帮我在用户模块加一个导出功能按咱们的导出规范来”。Agent 自动找到了团队共享空间里的“导出功能技能”和“数据库变更审批技能”先输出了一个影响面分析和 DB 变更说明然后按流程执行。如果没有提前挂载技能包它大概率只会给一段“需求已收到”的客套回复然后处理得相当随意。有了技能包之后它至少知道你们团队的“导出规范”是什么这本质上就是把工程师的方法论沉淀成了团队资产。5. 进阶玩法与效果调优5.1 按自己的项目定制技能模板技能包最大的自由度在于可以随便改。社区提供的通用技能包遵循的是“普遍适用”的原则但每个团队都有自己的特殊约定。比如你们项目要求所有数据库变更必须经过审批或者要求每次提交必须关联需求单号这些都是通用技能包不会替你考虑的事。我的建议是从两个方向开始定制。第一是修改现有技能包的约束条文。打开SKILL.md在“执行规范”部分加入你们团队的硬性要求比如“在修改任何数据库迁移脚本之前必须生成一份变更说明放在 docs/db 目录下”。这样 Agent 在执行相关技能时会自动遵守这些约束。第二是新建团队专属技能包。比如你们团队经常做接口联调就可以写一个“接口联调检查技能”规定 Agent 在改动接口时必须列出下游调用方清单判断是否影响兼容性。这个技能包在社区里大概率找不到但它恰恰是你们团队最需要的。一个很实在的技巧是给技能包设置明确的触发条件。在 SKILL.md 的 front matter 里写上“当任务涉及接口变动时自动激活”比让 Agent 靠读正文来判断什么时候用更可靠。反正技能系统的设计目标就是按需加载你在触发条件上写得越清楚Agent 在正确场景下调用技能的概率就越高。5.2 上下文预算与 token 成本控制很多人担心装了这么多技能包是不是每次对话都把全部技能文件塞进去如果你也是这么想的那我告诉你完全不是。技能包是“按需发现”的Agent 不会把整个技能目录一股脑读进上下文。它在接到任务时先通过技能清单的简短描述判断哪个技能相关再读取对应技能的详细文件。这是一个两阶段的过程比把所有技能都塞进去不知道省多少 token。我观察到一个典型的对话场景一个包含规划、调试、代码审查三个技能包的任务技能加载相关的 token 消耗只占全部对话 token 的 10%~15%。也就是说大头依然是代码和上下文本身技能包的额外开销并不大。真正会让 token 飙升的是让 Agent 反复读取大文件而不是技能本身。当然如果你的项目技能包特别多比如超过了二十个还是应该做一下“技能瘦身”。保留最常用的核心技能把低频场景的技能挪到备注而非默认加载清单里。技能包的触发机制虽然智能但也不是万能的加载太多反而可能让 Agent 在技能选择上犹豫不决影响效率。5.3 让 Agent 记住人类口味偏好配置最后一个进阶玩法是我个人最喜欢的把“代码风格偏好”写成一个技能包。举个例子我和团队的习惯是Java 代码里的私有方法放在公有方法下面变量命名优先用动词开头标明用途禁止在 Controller 里写业务逻辑。这些习惯在 code review 时容易被提出来但让 Agent 在每次对话中自动遵守以前几乎做不到。现在我会把这类偏好整理成一个“编码风格技能包”。里面用非常明确的条款列出团队的代码风格要求比如“Controller 层只负责参数校验和返回包装所有业务逻辑必须写入 Service 层”并配上正反两个小例子。由于这个技能包带有明确的触发条件“涉及 Java 代码修改时自动激活”Agent 在实战中会先读取它再开始写代码。实测下来代码风格相关的 review 意见确实减少了很多。一个比较直观的例子是以前 Agent 生成的方法体经常一大坨变量命名也是能简写就简写装了偏好技能包之后生成的代码结构明显更规整方法的职责更单一。它当然还做不到完全替代人肉 code review但至少在你亲手 review 之前已经帮你挡掉了很多一眼就能看出来的风格问题。6. 常见问题与排查经验实录6.1 技能不被加载问题出在路径和注册上如果你按完步骤发现 Agent 完全没有使用技能的迹象第一步不是怀疑技能包有问题而是检查注册链路。最常见的原因是AGENTS.md里的路径写错了。比如技能包仓库克隆到了~/.superpowers但配置里写的却是~/.superpower一字之差Agent 就死活找不到技能。排查时我通常按这个顺序来先确认技能目录真实存在再确认AGENTS.md里的路径和目录名完全一致最后重启 Codex 会话加载一个新的对话再测试。如果还是不行就手动在对话里给 Agent 一个明确的提示“请阅读 ~/.superpowers/skills 下的技能文件并按照它们来规划本次任务。”如果 Agent 在明确指引下依然不读那多半是配置加载机制的问题需要回去检查 Codex CLI 的版本和AGENTS.md的读取规则。还要提醒一句AGENTS.md的文件名大小写是敏感的写成agents.md在某些工具里不会被识别。别笑这个问题我至少见过三次。6.2 Agent“假遵守”技能行为却完全没变更隐蔽的问题是技能明明被加载了Agent 也声称自己在按技能执行但实际输出跟没装技能包之前一模一样。这种情况是技能包使用中最让人头疼的。原因通常有两个。第一个是任务描述太模糊比如你只说“帮我优化一下这段代码”但没说清楚是性能优化还是可读性优化Agent 加载了重构技能也无法确定该按哪套规范执行。解决办法是给 Agent 更明确的任务边界在一个具体目标下激活对应的单一技能。第二个可能原因是技能包的描述太泛Agent 无法根据当前任务判断它适用于什么场景。这种情况下你要做的是在技能文件开头加上更明确的触发条件让人一眼能看出它的适用范围。还有一个从实践中总结的经验单一技能包的效果往往好于多个技能包同时启用。多个技能包会给出互相冲突的优先级Agent 不知道该听谁的最后可能“哪个都没听”。如果你发现技能好像不起作用试着把任务拆小一次只激活一个技能效果会立竿见影。6.3 模型版本差异带来的兼容性波动技能包本质上是对 Agent 行为方式的引导它能不能被遵守很大程度取决于底层模型的能力。不同模型对技能的遵循度差异是真实存在的。有的模型能完美消化比较长的技能说明按步骤执行每一步都对得上有的模型读完了但会在执行细节上自由发挥尤其是在多步骤任务的中间环节。我的验证方法是准备一个固定的“技能校验任务”内容保持不变每次升级模型或切换 Agent 工具后都跑一遍。比如任务就是“读取某个技能包在计划阶段输出任务拆解清单不要产生任何代码改动”。如果输出结果符合预期就继续不符合就检查是模型理解问题还是技能描述问题。这个方法成本低效果直观强烈推荐常折腾工具链的人试试。如果你发现某个模型对技能包的遵循度特别低也别急着改技能描述。可以先观察它到底是“没读”还是“读了没按着做”。没读的话问题在加载机制读了没按着做更多是模型本身的指令遵循能力问题这种情况下换个更强的模型或者把技能说明写得更短更直接往往立竿见影。最后再说一个我自己的使用体会。superpowers这类技能包带来的真正转变不是让 AI 瞬间变成十项全能而是让它从一个“盲目自信的代码生成器”变成了一个“知道自己在干什么的执行者”。这种转变在短任务上是看不出来的但在动辄需要处理十几个文件、包含多个子任务的大工程上简直救命。我个人是从一个 Java 老项目开始用起来的现在已经离不开了每次让 Codex 干活前都会先确认技能包目录挂载正常。你如果刚开始接触我的建议是别贪多先用好“规划”和“验证”这两个技能等你习惯了 Agent 的节奏再逐步加新的技能包。踩过几次坑之后你就会发现真正让 AI 生产力翻倍的往往不是模型本身而是你给它的那套工作方法。
Superpowers：给Codex编程Agent装上资深工程师方法论
最近大家都在聊 AI 编程口号喊得震天响什么“AI 替你写代码”“Agent 自主开发”。可真把活儿交出去不少人发现事情没那么简单写个 Demo 没问题一问项目里的业务细节就露馅多步任务做着做着就忘了上下文改完代码连测试都不跑就敢跟你汇报“完成”。我一开始也觉得是模型不够强后来折腾了几轮才发现问题多半出在流程上——AI 不缺代码能力缺的是“怎么像个正经工程师一样干活”的约束和引导。这就是我关注superpowers这类项目的原因。它不是模型不是 IDE 插件而是一套开源的技能包和工作流目标很直白给 Codex 这类编程 Agent 叠加“资深工程师的方法论”。装上之后Agent 会先规划再动手遇到问题知道怎么拆解写完代码记得验证而不是一上来就瞎改文件。这篇文章就围绕superpowers的安装、使用和原理做一次完整拆解包括我在 Java 项目里的真实体验、和其他协作工具联动的玩法以及排查过程中踩过的坑。无论你是在用 Codex CLI还是在研究怎么让 AI 更靠谱地接活这篇都值得看完。1. 从“会写代码”到“会干活”Superpowers 要解决的真正痛点1.1 AI 编程工具的“三分钟热度”困境现在的编程 Agent 给人最初的冲击感很强。你丢给它一个需求“帮我写一个带分页的博客系统”它哗啦哗啦给你生成一堆文件甚至能跑起来那一刻你会觉得程序员要失业了。但别高兴太早等需求稍微复杂一点——比如“在现有的用户模块里加一个积分体系并且要兼容老数据”——Agent 的表现立刻两极分化。有的会自顾自地创建新文件把老逻辑晾在一边有的会在十几个文件之间反复横跳改到一半忘了最初的目标还有的更离谱改完代码不跑测试就说完成了。这背后的原因不复杂。模型本身的智能水平并不差但它在默认状态下是“自由发挥”的没有项目全貌认知、没有步骤约束、没有“先想清楚再写代码”的强制节点。就像一个刚入行的新人代码能力有 80 分但工程素养只有 30 分。你直接命令他“把这个模块改好”他可能非常积极地动手但方向完全跑偏。superpowers想解决的就是这中间的 50 分差距。它的思路不是给你换个更强的模型而是给 Agent 一套完整的工作协议什么时候该停下来思考思考什么问题用什么格式输出计划按什么顺序执行修改做完之后要跑哪些验证。这些都是资深工程师每天都在做的事只是被打包成了可复用的“技能”。1.2 为什么不是更贵的模型而是更靠谱的工作流有一种很流行的观点是“只要模型够强就不需要调 prompt不需要什么技能包”。这个观点听起来很爽但实际操作中不太成立。即便模型再强它面对一个具体项目时依然缺乏组织约束它不知道你团队要求一次提交不要超过 200 行不知道你们的老系统里哪些模块是动不得的雷区也不知道改完接口之后要同步更新下游调用方。你可以把这些都写进 prompt但问题在于一个任务描述里塞的东西越多模型越容易忽略后面的部分。更好的方式是像superpowers这样把约束和流程做成“按需加载”的模块。需要规划的时候就加载规划技能需要调试的时候就加载调试技能Agent 不会被一大段冗长的系统提示冲昏头脑而是像人一样在不同阶段调用不同的方法。我用一个生活化的类比来解释工具链再好也就是给你一把好刀而技能包相当于刀法。你手上是一把大马士革刀但刀法稀烂切菜照样切到手反过来一把普通菜刀配上一套扎实的切配流程出来的活可能更稳定。AI 编程工具已经足够锋利了缺的恰恰是一套值得信赖的切配流程。2. Superpowers 的底层逻辑把资深工程师的方法论“技能化”2.1 技能包Skill Pack机制拆解superpowers的核心单位是“技能包”英文通常叫 Skill Pack。你可以把它理解成一本本 Markdown 写成的“操作手册”每一本规定了一个具体场景下 Agent 应该怎么行动。比如有一个技能包叫“实现规划”它告诉 Agent在动手之前先列出当前系统的相关模块、数据流、风险点再输出一份任务拆解列表最后等着人类确认。又比如有一个技能包叫“调试复盘”它规定 Agent 在做完修改之后必须回顾最初的目标逐条核对是否全部完成如果有遗漏就继续补。这套机制最妙的地方在于技能包不会被一次性全部塞进上下文。项目里可能有几十个技能包但 Agent 在每次对话里只会根据当前任务激活相关的两三个。这样既保证了上下文不被无关内容挤占又让技能的描述质量更高。具体到 Codex CLI 这类工具上技能包通常常驻在项目里的skills/目录Agent 通过约定好的目录扫描机制发现它们需要时以特定格式调用。我最初以为技能包就是普通的 prompt 模板试过之后才发现区别很大。普通模板是“一次性”的用户在对话里粘贴一段长长的指令Agent 照着做但做完就忘下一轮对话又得重新粘贴。而技能包是“可注册、可发现、可反复调用”的Agent 能感知到技能的存在并且在获得明确信号时主动加载执行。这就好比一个新人手边放着一本随时可以翻的规章手册而不是领导在开工前念一遍长篇大论。2.2 规划—执行—验证三段式工作流superpowers的另一块基石是把工作过程强制拆成三个阶段的循环规划阶段执行阶段验证阶段。规划阶段 Agent 不允许写代码只允许调查项目结构、阅读关键文件、提出计划。执行阶段严格按计划推进每完成一个子任务就在计划清单上打钩。验证阶段则是跑测试、查 diff、回顾需求全部通过了才把结果交给人类。这个三段式听起来简单但对 Agent 行为的改善是立竿见影的。默认状态下Agent 接到任务是“一步到位”模式脑子里没有计划的概念容易在细节里迷失有了强制的规划节点后它必须先输出方案你可以在它动手之前就把跑偏的苗头掐灭。我在实际使用中深有体会一次让 Codex 给一个老的 Java 服务加导出功能它刚打算在 Controller 里直接堆上传逻辑时由于规划技能要求先生成“影响面分析”它自己就发现了这个问题最后写出的计划比我预期的还要严谨。验证阶段的价值往往被低估。很多 Agent 翻车的场景是改完代码宣布完成但项目根本编译不过。superpowers把“必须验证”写进了工作协议要求 Agent 主动运行构建命令、运行测试甚至观察测试日志中是否有新的 warning。这能拦住一批“看起来完成了实际上没完成”的假成功。2.3 为什么用 Markdown 而不是代码来描述技能这一点可能是很多人忽略的细节。技能包文件全部是 markdown 格式不是 .ts 或 .py 代码背后有一个很实在的考量技能包既要给人看也要给模型看。Markdown 对 LLM 的解析相当友好结构清晰、层级分明模型读取时能很快抓住要点而对于人类维护者来说Markdown 又是最容易阅读和修改的格式你可以把一大段技能说明当作写文档一样去组织。此外Markdown 是纯文本天然支持 git 版本管理。技能包改错了可以 revert想对比两个版本的差异可以直接 git diff。如果你在一个团队里推广 AI 工程规范这几乎是唯一合理的载体——你没法要求每个团队的成员都会写代码但要求他们会写 Markdown 文档这就现实多了。社区里的技能包项目也大多采用这个格式你可以直接在 GitHub 上 fork 一份别人的技能包按自己团队的规范改一版pull request 流程完全走代码评审的路子。3. 安装与初始化三步让 Codex 装上 Superpowers3.1 环境准备与依赖检查在拉取技能包之前先确认你手头的环境是齐的。superpowers不是独立的可执行程序它是寄生在 Codex CLI 这类 Agent 工具上的配置与技能层所以你的机器上必须已经有一个能正常工作的 Codex CLI。所谓“能正常工作”指的是你已经配好了 API 权限并且在最简单的任务上跑通过一次对话。另外需要确认安装了 git因为技能包的获取和更新都靠 git 完成。我常用的检查命令组合是这样的codex --version git --version如果两个命令都能正常输出版本号就说明基础环境没问题。接着我会用一个极小的任务做“冒烟测试”比如让 Codex 读取当前目录下的一个文件内容并简单总结。这个小任务能验证 API 链路通不通免得后面装完技能包才发现其实 Agent 本身就在报错白折腾半天。还有一点值得提前说superpowers项目本身在持续迭代不同版本对 Codex CLI 的支持程度可能不同。稳妥的做法是先看一眼项目的 README确认当前分支对 Codex CLI 的兼容性说明再决定拉取哪个分支。有些老项目用的是main分支但最新的工作重心放在了experimental分支上。如果你只想求稳用默认分支加最新稳定版 Codex CLI 的组合能免掉 90% 的兼容性烦恼。3.2 拉取技能包与目录结构说明环境就绪之后拉取技能包本身非常简单本质上就是克隆一个仓库到你指定的目录。我用的是项目的默认推荐方式把仓库放到家目录下的.superpowers文件夹然后在项目级或用户级配置里引用它。git clone https://github.com/example/superpowers.git ~/.superpowers克隆完之后建议花几分钟熟悉一下目录里的核心结构。典型的技能包仓库通常会包含这些部分skills/技能包的存放目录每一个子文件夹就是一个技能里面含SKILL.md文件agents/面向不同 Agent 工具Codex CLI、其他终端 Agent的适配配置docs/使用文档、设计理念和最佳实践examples/不同语言和使用场景的示例工程。skills/目录是你之后最常打交道的地方。每个技能的SKILL.md文件里有一段 YAML front matter声明技能的名称、描述、适用场景正文部分则是具体的操作步骤和规范要求。你完全可以把它当作“给 AI 员工看的岗位说明书”来理解。3.3 把 Superpowers 注册到 Codex CLI技能包拉下来之后并不会自动生效你需要在 Codex CLI 里“注册”它。当前多数主流做法是通过项目下的AGENTS.md文件来声明技能目录的位置。这个文件会被 Codex 自动发现相当于告诉 Agent去哪里找这些技能、哪些技能在什么情况下启用。以典型的配置为例在项目根目录创建或修改AGENTS.md写入类似下面的内容# Project Agent Configuration ## Superpowers Skills The following skill directories are available for this project: - User Skills: ~/.superpowers/skills When starting a task, check the skills directory for instructions relevant to the task.这段配置的作用是让 Agent 在每次会话启动时都知道技能包的位置并且被要求按需查找技能。配置完成后重启 Codex CLI随便开始一个新会话先确认基础命令是否正常。如果你在 Codex 的会话里执行技能列表命令能看到superpowers的相关技能已经出现就说明注册成功了。补充一个我自己的习惯我会先跑一个最轻量的技能验证端到端链路。比如让 Agent 读取某个技能包的说明并总结它应该如何规划一个任务。如果它能准确复述技能包里的关键步骤说明技能已经被真正加载而不是仅仅“看起来被加载了”。这一步验证多花两分钟能省下后面排错的好几个小时。4. 核心技能拆解与实际场景配置4.1 技能库全景规划、调试、重构、测试普通的 Agent 提示词只会告诉 AI“你是一个编程助手”而技能包给的是“你遇到这种情况时按这几步做”。我把目前社区里最常用的一批技能整理成了表格方便你按需取用技能名称触发方式核心作用典型应用场景实现规划接到复杂需求时激活先做影响面分析输出任务拆解清单多文件跨模块的功能开发调试复盘测试失败或结果不符时激活定位根因、尝试修复、回归验证排查线上 bug、修复测试报错代码审查完成修改后激活自查代码规范、逻辑漏洞、边界问题提交前自检、减少返工重构助手识别到重复代码时激活设计重构方案分步执行并保持行为不变清理老项目里的坏味道测试驱动从零开发新功能时激活先写失败测试再实现逻辑最后让测试通过新模块开发、需求明确的功能这些技能不是孤立的它们组合起来就是一个完整的工程闭环。你在新需求里先调用规划技能再按计划实现实现过程中遇到问题调用调试技能写完调用代码审查技能。熟练掌握后你会感觉自己不是在指挥一个代码生成器而是在给一个远程的初级工程师派活。4.2 实战在 Java 项目里用 Superpowers 做一次增量重构理论讲再多不如看一次实战。我用一个真实的 Java 项目场景来说说整个过程。任务是给一个老服务加一个“用户行为日志导出”接口看起来不复杂但这个服务已经跑了几年中间换过好几拨人代码里的历史包袱相当重。如果是我自己动手先得花大半天读代码、理依赖、摸清老项目的套路。而现在我在 Codex CLI 里发出任务“请为现有的用户模块新增行为日志导出接口。先按照技能包完成影响面分析和实施计划计划确认后再动手实现。”Agent 首先激活了规划技能。它没有立刻写代码而是先后打开了pom.xml确认依赖关系检查了UserController和LogService的现有结构甚至翻看了数据库访问层的 DAO 代码。几分钟后它输出了一份计划内容包括新增一个ExportController提供导出入口复用现有的LogService查询方法不新建数据访问层在 service 层增加一个导出专用的组装方法避免直接返回大对象导致内存压力。计划的最后还标注了两个风险点老系统的一个查询方法没有分页直接导出可能导致 OOM另一个风险是日期的时区处理容易出问题。这份计划比我预想的专业尤其那两个风险点确实只有熟悉项目的人才能提出来。我确认计划后Agent 才进入执行阶段。它按照计划逐项完成每个文件修改后都会生成简短说明并标出改动是否符合计划。最后一步是验证阶段Agent 主动跑了mvn -q compile和相关的单元测试。中途确实遇到了测试失败——它调整了一个Date的类型转换参数导致一个旧测试断言不过。这时调试技能发挥的作用很大Agent 没有直接改测试去迎合代码而是检查了新代码的时区处理逻辑发现确实有边界问题于是调整了实现最终让原有测试全部通过新增的导出测试也稳定通过。整个过程我从头到尾没有动过一行代码只在关键节点上做确认。耗时大约一个多小时包含读代码和分析的时间换成人工怎么也要半天以上。更重要的是Agent 全程没有让我操心“它是不是在瞎改”每个步骤都有计划有依据这比它多快完成都让我安心。4.3 和其他工具联动WorkBuddy 这类团队场景怎么玩superpowers不只活在 Codex CLI 的终端里它的技能包格式被不少团队级 AI 工具采纳。最近很多人搜“worbuddy 怎么用 superpowers”我猜大概率是在团队协作的场景里遇到了同一个问题如何在群里或者工作流工具里让 AI 也具备“先规划再执行”的能力。以 WorkBuddy 这类团队协作 Agent 工具为例通用做法是把技能包目录挂载为团队的共享知识源。你可以把skills/里的技能文件同步到团队项目的共享空间然后在工作流配置中设置一个基础指令任何来自成员的需求Agent 都要先检查共享空间中的技能目录按照对应的技能流程执行。这样团队里的每个人都能受益于同一套工程规范而不只是你终端里那个 Codex。实际效果我最满意的一个场景是在团队协作群里说了一句“帮我在用户模块加一个导出功能按咱们的导出规范来”。Agent 自动找到了团队共享空间里的“导出功能技能”和“数据库变更审批技能”先输出了一个影响面分析和 DB 变更说明然后按流程执行。如果没有提前挂载技能包它大概率只会给一段“需求已收到”的客套回复然后处理得相当随意。有了技能包之后它至少知道你们团队的“导出规范”是什么这本质上就是把工程师的方法论沉淀成了团队资产。5. 进阶玩法与效果调优5.1 按自己的项目定制技能模板技能包最大的自由度在于可以随便改。社区提供的通用技能包遵循的是“普遍适用”的原则但每个团队都有自己的特殊约定。比如你们项目要求所有数据库变更必须经过审批或者要求每次提交必须关联需求单号这些都是通用技能包不会替你考虑的事。我的建议是从两个方向开始定制。第一是修改现有技能包的约束条文。打开SKILL.md在“执行规范”部分加入你们团队的硬性要求比如“在修改任何数据库迁移脚本之前必须生成一份变更说明放在 docs/db 目录下”。这样 Agent 在执行相关技能时会自动遵守这些约束。第二是新建团队专属技能包。比如你们团队经常做接口联调就可以写一个“接口联调检查技能”规定 Agent 在改动接口时必须列出下游调用方清单判断是否影响兼容性。这个技能包在社区里大概率找不到但它恰恰是你们团队最需要的。一个很实在的技巧是给技能包设置明确的触发条件。在 SKILL.md 的 front matter 里写上“当任务涉及接口变动时自动激活”比让 Agent 靠读正文来判断什么时候用更可靠。反正技能系统的设计目标就是按需加载你在触发条件上写得越清楚Agent 在正确场景下调用技能的概率就越高。5.2 上下文预算与 token 成本控制很多人担心装了这么多技能包是不是每次对话都把全部技能文件塞进去如果你也是这么想的那我告诉你完全不是。技能包是“按需发现”的Agent 不会把整个技能目录一股脑读进上下文。它在接到任务时先通过技能清单的简短描述判断哪个技能相关再读取对应技能的详细文件。这是一个两阶段的过程比把所有技能都塞进去不知道省多少 token。我观察到一个典型的对话场景一个包含规划、调试、代码审查三个技能包的任务技能加载相关的 token 消耗只占全部对话 token 的 10%~15%。也就是说大头依然是代码和上下文本身技能包的额外开销并不大。真正会让 token 飙升的是让 Agent 反复读取大文件而不是技能本身。当然如果你的项目技能包特别多比如超过了二十个还是应该做一下“技能瘦身”。保留最常用的核心技能把低频场景的技能挪到备注而非默认加载清单里。技能包的触发机制虽然智能但也不是万能的加载太多反而可能让 Agent 在技能选择上犹豫不决影响效率。5.3 让 Agent 记住人类口味偏好配置最后一个进阶玩法是我个人最喜欢的把“代码风格偏好”写成一个技能包。举个例子我和团队的习惯是Java 代码里的私有方法放在公有方法下面变量命名优先用动词开头标明用途禁止在 Controller 里写业务逻辑。这些习惯在 code review 时容易被提出来但让 Agent 在每次对话中自动遵守以前几乎做不到。现在我会把这类偏好整理成一个“编码风格技能包”。里面用非常明确的条款列出团队的代码风格要求比如“Controller 层只负责参数校验和返回包装所有业务逻辑必须写入 Service 层”并配上正反两个小例子。由于这个技能包带有明确的触发条件“涉及 Java 代码修改时自动激活”Agent 在实战中会先读取它再开始写代码。实测下来代码风格相关的 review 意见确实减少了很多。一个比较直观的例子是以前 Agent 生成的方法体经常一大坨变量命名也是能简写就简写装了偏好技能包之后生成的代码结构明显更规整方法的职责更单一。它当然还做不到完全替代人肉 code review但至少在你亲手 review 之前已经帮你挡掉了很多一眼就能看出来的风格问题。6. 常见问题与排查经验实录6.1 技能不被加载问题出在路径和注册上如果你按完步骤发现 Agent 完全没有使用技能的迹象第一步不是怀疑技能包有问题而是检查注册链路。最常见的原因是AGENTS.md里的路径写错了。比如技能包仓库克隆到了~/.superpowers但配置里写的却是~/.superpower一字之差Agent 就死活找不到技能。排查时我通常按这个顺序来先确认技能目录真实存在再确认AGENTS.md里的路径和目录名完全一致最后重启 Codex 会话加载一个新的对话再测试。如果还是不行就手动在对话里给 Agent 一个明确的提示“请阅读 ~/.superpowers/skills 下的技能文件并按照它们来规划本次任务。”如果 Agent 在明确指引下依然不读那多半是配置加载机制的问题需要回去检查 Codex CLI 的版本和AGENTS.md的读取规则。还要提醒一句AGENTS.md的文件名大小写是敏感的写成agents.md在某些工具里不会被识别。别笑这个问题我至少见过三次。6.2 Agent“假遵守”技能行为却完全没变更隐蔽的问题是技能明明被加载了Agent 也声称自己在按技能执行但实际输出跟没装技能包之前一模一样。这种情况是技能包使用中最让人头疼的。原因通常有两个。第一个是任务描述太模糊比如你只说“帮我优化一下这段代码”但没说清楚是性能优化还是可读性优化Agent 加载了重构技能也无法确定该按哪套规范执行。解决办法是给 Agent 更明确的任务边界在一个具体目标下激活对应的单一技能。第二个可能原因是技能包的描述太泛Agent 无法根据当前任务判断它适用于什么场景。这种情况下你要做的是在技能文件开头加上更明确的触发条件让人一眼能看出它的适用范围。还有一个从实践中总结的经验单一技能包的效果往往好于多个技能包同时启用。多个技能包会给出互相冲突的优先级Agent 不知道该听谁的最后可能“哪个都没听”。如果你发现技能好像不起作用试着把任务拆小一次只激活一个技能效果会立竿见影。6.3 模型版本差异带来的兼容性波动技能包本质上是对 Agent 行为方式的引导它能不能被遵守很大程度取决于底层模型的能力。不同模型对技能的遵循度差异是真实存在的。有的模型能完美消化比较长的技能说明按步骤执行每一步都对得上有的模型读完了但会在执行细节上自由发挥尤其是在多步骤任务的中间环节。我的验证方法是准备一个固定的“技能校验任务”内容保持不变每次升级模型或切换 Agent 工具后都跑一遍。比如任务就是“读取某个技能包在计划阶段输出任务拆解清单不要产生任何代码改动”。如果输出结果符合预期就继续不符合就检查是模型理解问题还是技能描述问题。这个方法成本低效果直观强烈推荐常折腾工具链的人试试。如果你发现某个模型对技能包的遵循度特别低也别急着改技能描述。可以先观察它到底是“没读”还是“读了没按着做”。没读的话问题在加载机制读了没按着做更多是模型本身的指令遵循能力问题这种情况下换个更强的模型或者把技能说明写得更短更直接往往立竿见影。最后再说一个我自己的使用体会。superpowers这类技能包带来的真正转变不是让 AI 瞬间变成十项全能而是让它从一个“盲目自信的代码生成器”变成了一个“知道自己在干什么的执行者”。这种转变在短任务上是看不出来的但在动辄需要处理十几个文件、包含多个子任务的大工程上简直救命。我个人是从一个 Java 老项目开始用起来的现在已经离不开了每次让 Codex 干活前都会先确认技能包目录挂载正常。你如果刚开始接触我的建议是别贪多先用好“规划”和“验证”这两个技能等你习惯了 Agent 的节奏再逐步加新的技能包。踩过几次坑之后你就会发现真正让 AI 生产力翻倍的往往不是模型本身而是你给它的那套工作方法。
