最近在 GitHub 上看到一个叫 superpowers 的项目翻了翻 star 数涨得很快评论区一堆人在 Codex CLI、Claude Code 里折腾它。一开始我以为又是什么花里胡哨的 prompt 合集但实际用下来发现它解决的恰恰是编码 Agent 最让人头疼的那几个问题模型拿到需求直接开写、写到一半忘了最初的约定、报错之后胡猜乱改。这篇文章我就以自己的实操经历为主线聊聊 superpowers 到底是什么、为什么值得装、以及怎么在 Codex CLI 这类终端工具里把它配置好并真正用起来。这篇文章适合已经在用或准备用 Codex CLI、Trae 这类 AI 编码工具的朋友尤其是那些觉得默认行为不够可控、想给 Agent 建立一套明确工作流的人。我会尽量把配置过程和踩坑细节写清楚方便你直接照着操作。1. superpowers 到底是什么给 Codex 的“超能力技能包”先纠正一个容易混淆的点superpowers 不是一个模型也不是一个独立运行的命令行工具它是一套专门为编码 Agent 设计的技能包skill pack。所谓技能在 AI Agent 的语境里本质上是结构化的提醒规则和操作流程告诉模型在什么场景下应该按什么步骤思考、执行什么样的动作。1.1 它不是模型而是“调用模型的方法”我见过不少朋友第一次接触这个项目时误以为装上 superpowers 就等于换了一个更强的模型结果发现对话还是原来的模型效果却确实不一样了于是觉得神奇。其实背后的原理很简单superpowers 通过注入一套前置指令让模型在回答前先经过一遍系统化的思考流程。举个例子默认情况下你让 Codex 改一个 bug它可能直接给你一段修复代码。但接入 superpowers 的 debug 类技能后模型会先要求你提供重现步骤、查看错误堆栈、分析可能原因然后再给出修复方案。这就是“技能包”存在的意义——它改变了模型的工作方式而不是模型的智力水平。1.2 为什么叫 superpowers四个核心能力来源项目叫 superpowers是因为它重点强化了编码 Agent 最薄弱的四个环节计划先行让 Agent 在动笔写代码之前先输出实现计划列出文件、函数、接口变更点。系统化调试遇到 bug 时引导 Agent 按证据链排查而不是凭直觉瞎试。测试驱动推动 Agent 先写失败测试再实现功能让测试成为需求的“可执行说明书”。需求追问在需求描述不清晰时主动向用户提问澄清而不是硬着头皮开写。这四个能力听起来不复杂但放到 Agent 身上默认行为往往完全相反。模型是典型的“机会主义者”你给它一个模糊任务它会倾向于快速给出一个看起来合理的结果而不是花时间追问或做计划。superpowers 的作用就是用结构化的 skill 文件把这种行为“掰”回来。1.3 使用它的前提与适合人群想用好 superpowers你需要具备以下基础条件有一个支持自定义指令或技能加载的编码 Agent 工具比如Codex CLI、Trae其他兼容工具也可以。对命令行基础操作不陌生至少会使用git clone、编辑配置文件。有基本的编程经验因为 superpowers 的大多数技能都服务于真实编码场景纯小白可能会觉得概念太密。如果你平时只是用 AI 写写文案、做做表格那这个技能包大概率帮不上忙。但如果你是那种每天都让 Agent 写代码、改 bug 的人它带来的收益会非常明显尤其是面对多文件项目时Agent 的行为会从“怎么快怎么来”变成“怎么稳怎么来”。2. 为什么要装它原生编码 Agent 的四个致命短板我在没装 superpowers 之前曾在一个中型 Python 项目上被 Codex 连续坑了好几次后来认真复盘发现原生 Agent 的行为模式存在四个非常典型的短板。搞清楚这些问题你才能真正理解 superpowers 的设计动机。2.1 模型爱直给结果不爱讲过程默认情况下你问 Agent “帮我实现一个用户登录接口”它大概率会直接甩给你一段完整的 Flask/FastAPI 代码中间没有任何计划、没有文件划分、没有依赖分析。这在简单场景下没问题但项目一旦复杂直接给结果往往意味着忽略了现有代码结构、接口约定、数据模型关系。我见过最夸张的一次Agent 在一个已有数据库模型的项目里直接另起炉灶又建了一套模型因为它根本没有先去读已有的模型文件。superpowers 的 plan 技能就是强制模型先“读代码、出计划、列影响面”再开始动手。2.2 模型没有“长时记忆”开头约定结尾忘大模型的上下文窗口虽然越来越大但对话一长早期约定的细节照样会被稀释。你第一句话要求“所有接口返回格式统一为{code, data, msg}”写到第五个文件的时候它很可能已经用回了裸数据返回。这个问题不是模型笨而是注意力机制天然如此。superpowers 的做法是把关键约束写进技能文件并在合适的时机提醒模型“回顾项目规范”。它相当于给模型发了一张持续可见的便签而且这张便签不是放在对话历史里被冲淡而是每轮都可能被重新激活。2.3 模型对报错信息的处理是“敷衍式”的遇到报错时原生 Agent 最常见的反应是根据报错信息猜一个原因然后把代码改一版再跑一次不行就再猜。这种“瞎猜循环”在小 bug 上偶尔能蒙对遇到真正的疑难杂症就非常浪费时间。superpowers 的 debug 技能要求模型遵循一套严谨的调试流程先确认环境、再找最小复现、然后看堆栈定位、最后验证修复。你会发现思路一旦被流程框住模型的行为会从“碰运气”变成“做排查”。2.4 默认工具链缺少工程流程约束很多团队其实有编码规范、有测试要求、有代码审查流程但这些约束很难被塞进默认的 Agent 行为里。Codex CLI 虽然支持项目级配置但如果你不主动写规则模型就完全不知道有这些约束。superpowers 的核心优势就在这儿它不是单一指令而是一整套可组合的技能体系。一个团队可以在技能里固化自己的工程规范比如强制要求每次提交前跑测试、强制要求写类型注解、强制要求更新文档。Agent 在这些技能的约束下工作行为方式会更接近一个“懂规矩的初级工程师”。3. 安装与配置从 GitHub 到 Codex CLI 的全流程实操接下来进入正题我以 Codex CLI 为主要演示对象讲解如何拉取 superpowers 项目并把它接入到你的 Agent 工作流中。整个安装过程本质上就三步获取文件、写入配置、验证加载。3.1 获取 superpowers 项目文件superpowers 代码托管在 GitHub 上项目名就是superpowers搜索关键词“superpowers github”很容易找到。拿到仓库地址后直接克隆到本地固定目录git clone https://github.com/owner/superpowers.git ~/superpowers提示仓库地址中的owner以官方 README 为准不同镜像和 fork 的地址可能不同。我建议你克隆后用ls看一下目录结构确认是否存在skills目录或类似命名的技能目录。克隆下来之后项目目录里通常会有多个子目录或文件每个技能对应一个文件夹里面有一个SKILL.md文件这是技能的核心定义。它的结构大致是superpowers/ ├── README.md └── skills/ ├── plan/ │ └── SKILL.md ├── debug/ │ └── SKILL.md ├── tdd/ │ └── SKILL.md └── ...SKILL.md的头部一般有name、description之类的元信息frontmatter正文则是具体的操作指令。这个设计非常像静态站点生成器里的 Front Matter 约定只不过这里服务的是 Agent 的行为控制。3.2 接入 Codex CLI 的两种方式拿到技能文件后接下来要让 Codex CLI 在每次对话时能读到这些规则。我的经验是两种方式可以搭配使用方式一在项目级AGENTS.md中引用Codex CLI 支持在项目根目录放一个AGENTS.md文件里面的内容会自动附加到每次请求的上下文中。你可以在里面显式地告诉模型去加载 superpowers 的技能文件# 项目说明 本项目的 AI 编码流程遵循 superpowers 技能包。 请先阅读 /Users/你的用户名/superpowers/skills 目录下的技能定义。 遇到编码任务时先触发对应的 skill再按 skill 中的步骤执行。这样做的好处是按项目生效不同项目可以引用不同的技能组合坏处是每新建一个项目都要配置一次。方式二在 Codex CLI 全局配置中引用Codex CLI 的配置文件一般位于~/.codex/config.toml你可以在配置里加上自定义指令让它对所有项目生效。不同版本字段名可能不一样核心思路是把 superpowers 目录的路径写进模型的系统提示词或者额外的指令列表里。注意Codex CLI 版本更新频繁配置字段可能存在差异。我第一次装的时候照着一个旧教程写信总配置结果模型完全不理会技能包后来仔细看官方 README发现新版已经改成读取AGENTS.md的优先级更高了。所以配置前务必瞄一眼项目文档以官方推荐路径为准。3.3 Trae 等图形 IDE 的接入思路关键词里有人提到了“trae work cn 安装 superpowers skill”说明很多朋友是在 Trae 这类图形化 AI IDE 里使用的。Trae 的底层能力模型与 Codex 不完全相同但加载 skill 的思路是相通的找到 IDE 的“自定义指令”或“角色/技能”设置入口把 skill 内容粘贴或挂载进去。如果你在 Trae 里找不到直接的技能目录我的建议是先看 Trae 的设置页面里有没有“自定义提示词”“规则文件”之类的选项。如果有“从文件导入规则”的功能直接把SKILL.md文件的路径或内容导入。如果只有文本输入框那就把SKILL.md的核心指令精简复制进去。需要特别提醒图形 IDE 的 skill 加载机制往往是非标准的同一个技能包可能会有兼容性问题。我的处理方式是把 superpowers 里最核心的 plan 和 debug 两个技能手动粘贴到 Trae 的全局规则里其他技能按需再说。先保核心再图全量这是我在图形 IDE 里验证过的稳妥策略。3.4 验证是否加载成功配置完成后别急着写业务代码先验证一下技能包有没有真正生效。最简单的方法是在对话里打一个测试请求比如我要在项目里新增一个用户注册接口请按 superpowers 的规范处理。如果配置生效模型应该会先输出实现计划列出涉及的文件、函数、数据结构然后再开始写代码。如果模型直接甩出一段代码说明技能包没有加载成功需要回头检查配置路径和优先级。4. 核心技能拆解Plan / Debug / TDD 到底怎么用superpowers 里技能很多但真正高频使用的是 Plan、Debug、TDD 这三板斧。我把每个技能的核心逻辑和实操要点拆开讲。4.1 Plan 技能强制让 Agent 先画图纸Plan 技能要解决的问题很简单AI 太喜欢直接动手了。在软件开发里直接动手写代码通常意味着跳过架构思考、忽略已有约束、缺少迁移路径。尤其当你面对的是一个有一定规模的项目时没有计划的直接实现基本等于裸奔。接入 Plan 技能后模型的响应流程会变成先阅读理解任务识别涉及的核心模块。输出一份简明实现计划包括要修改的文件、要新增的依赖、接口签名、数据流。把计划展示给用户等待确认后再开始执行。我实际用下来的感受是Plan 技能最适合两种场景一是新功能开发二是跨模块重构。这两个场景一旦跑偏返工成本极高。有了计划在前你可以在一分钟内心算出 Agent 的路线图是否合理从而避免它一头扎进坑里。提示如果你觉得 Agent 输出的计划太长、太啰嗦可以在技能文件里加一条规则“计划控制在 10 行以内优先列出改动文件和关键函数签名”。技能是死的人是活的学会改规则才是进阶玩家。4.2 Debug 技能从“瞎猜”到“证据链”Debug 技能是我个人最推荐的一项。因为编码 Agent 写的代码是否优雅是次要问题能不能定位 bug 才是主要问题。原生模型面对报错时喜欢“跳跃式”推理靠猜来产生新的代码superpowers 的 debug 技能则把模型按进一条证据链里要求用户提供完整报错信息包括堆栈位置、环境版本、操作步骤。分析报错前最后一次成功状态定位变更点。用最小化复现方式比如写一段独立脚本、用一个测试用例来隔离问题。验证修复是否真的解决了根因而不是把报错藏起来了。有一次我调试一个 Node.js 的异步问题模型按 debug 流程一步步排查最终发现是事件循环里的一个错误捕获遗漏导致的。整个排查过程看起来就像一个经验丰富的开发者戴着头灯在暗房里找保险丝而不是实习生乱拔电线。4.3 TDD 技能把测试当作需求说明书TDD也就是测试驱动开发是很多开发团队想推却推不动的实践。原因很简单写测试的即时反馈太低很多人写着写着就放弃了。但模型没有这个心理负担你让它先写测试它就老老实实写。superpowers 的 TDD 技能核心动作是让 Agent 围绕“红-绿-重构”循环工作红先写出失败测试明确业务的期望行为。绿写最小代码让测试通过不做多余设计。重构在测试保护下改进代码结构保证行为不变。我建议你在让 Agent 实现某个功能时明确加上一句“先写测试再写实现”。你会发现模型先写测试时会自动把需求的边界条件想得更清楚因为它必须用代码表达“什么行为才算正确”。用测试倒逼需求澄清比自己写需求文档再让模型实现要可靠得多。4.4 其他常用技能速览除了三件套superpowers 还包含一些细分技能我整理了一个速查表技能方向主要作用适用场景需求澄清追问用户收集完整需求需求描述模糊、缺边界条件文件阅读强制阅读相关代码后再动手多文件项目、老代码修改规范执行遵守项目级规范格式、命名、提交团队协作、有代码规范约束文档同步修改代码后同步更新文档开源项目、接口文档、README这些技能不一定每次都会触发但它们的存在能显著提升 Agent 的“职业感”。我甚至觉得superpowers 最大的价值不是某个技能本身而是它塑造了一种“先规划、再行动、勤反馈”的 Agent 人格这种人格才是它被称为 superpowers 的原因。5. 进阶使用技巧与工作流编排当你能熟练使用单技能之后下一步就是把这些技能串成一个完整的工作流。这里我分享几个我自己摸索出来的编排思路。5.1 把技能串成一个完整任务流假设我现在要让 Agent 给一个 Flask 项目增加 JWT 登录认证理想的任务流是需求澄清 → 项目读码 → 输出计划 → TDD 测试先行 → 写实现 → 跑测试验证。我现在的习惯是在对话里一次性把这个流程提给模型我的目标是在现有 Flask 项目里加入 JWT 登录认证。 请遵循以下流程 1. 先读取项目结构确认已有依赖和模型定义 2. 输出实现计划不超过 10 行 3. 按超级技能优先写失败测试 4. 实现功能直到测试通过 5. 最后更新 README 的接口说明。这样做的效果非常明显。模型每一步都有明确指令不会从“加 JWT”跳到“重写整个用户模块”。而且因为计划先行我在它动手前就能发现潜在问题比如它打算新建一个auth.py但项目里其实已经有security.py我可以提前打住。5.2 如何给技能写自定义约束superpowers 原生的技能规则大概率是放之四海而皆准的通用规范但你的项目一定有特殊约定。我的做法是在项目级AGENTS.md里叠加自定义约束而不是去改 superpowers 的文件。比如我们的团队要求所有写操作的接口都必须记录审计日志那么我会在AGENTS.md里加一条所有涉及数据修改的接口必须在完成核心逻辑后调用 audit.log(user, action, target)否则视为任务未完成。superpowers 帮 Agent 建立流程骨架自定义约束则告诉它“你的代码要符合我们家的地基”。两者配合Agent 的表现会非常接近一个熟悉团队规范的老开发。5.3 让 Agent 在长任务中不跑偏的提示技巧长任务最容易出现的问题不是模型不会做而是做了一半忘记上下文。superpowers 虽然能缓解这个问题但无法完全消除。我常用的补救手段是分段确认每完成一个阶段让模型用 3 行以内总结当前状态下一个阶段开始前要求模型先读取上一步的改动再继续如果任务超过 5 个文件改动我会把阶段节点拆得更细宁可多对话几次也不要让它一口气闷头写。这个过程有点像一个靠谱的开发者在群里同步进度而不是闷头写代码三个小时然后丢给你一堆 commit。慢是慢一点但出错的概率直线下降。5.4 结合上下文缓存的小建议如果你的 Agent 工具支持上下文缓存比如某些 API 的 prompt caching那可以考虑把 superpowers 的技能文件按“全局规则”和“项目规则”分开管理。全局规则放系统级项目规则放AGENTS.md。这样做一方面节省 token另一方面也避免全局规则过于臃肿拖慢响应速度。我第一次把整个 superpowers 目录都塞进配置时每次请求都额外消耗了大量 token响应也明显变慢。后来我把“通用方法论”和“项目专属约束”分开效果好了很多。技能包不是越多越好够用就好。6. 常见问题与避坑实录最后这部分我把实际操作中遇到过的典型问题整理出来按排查思路讲清楚。这些问题在网上资料里很少一次性说明白建议你收藏备用。6.1 模型完全不理会技能怎么办如果你发现模型对你的技能指令视若无物大概率不是模型坏掉了而是技能的优先级太低。在 Codex CLI 这类工具里系统提示词的指令层级高于用户指令有些版本的全局配置优先级高于AGENTS.md有些则相反。我的排查步骤是确认配置写入位置正确全局 vs 项目级。用一条简单指令测试模型是否响应你的规则比如“按规则先列计划再写代码”。检查技能文件路径是否有拼写错误尤其是用户目录名~有时在子进程里不会被自动展开。确认没有其他全局规则与 superpowers 冲突把影响降到最低。6.2 Trae 里使用了技能但没效果Trae 这类图形 IDE 的规则加载机制往往比 CLI 更隐蔽而且版本差异极大。有用户反馈在“Trae work cn”环境里安装了 superpowers skill 后没有效果我遇到过的常见原因有三类规则入口找错了有些版本需要在项目设置里单独开启“读取自定义 Skill”的开关默认是关闭的。内容格式不兼容Trae 的规则输入框可能不支持 Markdown frontmatter需要手动去掉头部元信息只保留正文步骤。模型版本不支持某些轻量模型对长指令的理解能力偏弱即便你把技能内容喂进去它也无从遵循。这种情况下换一个更强的基础模型才是正解。6.3 多技能同时触发导致冲突superpowers 的技能如果能同时触发有时候会产生重复指令。例如plan技能要求“先列计划”而另一个自定义规则却要求“立即开始写代码”模型就会陷入混乱。我处理这类冲突的原则是给优先级排序。在AGENTS.md里明确写上如果多个技能指令存在冲突优先级从高到低为 1. 用户最新明确指令 2. 项目安全规范如数据删除必须确认 3. superpowers 通用技能 4. 其他优化建议有了这个优先级声明模型在冲突场景下就不会随机发挥行为可预期了很多。6.4 提示词太长消耗 token 太猛superpowers 的技能文件本身不短你把所有技能都挂载到每次请求里token 消耗非常可观。更麻烦的是有些按 token 计费的服务会让你钱包肉疼。我的建议是控制挂载粒度全局只挂载最通用的 plan、debug 两个技能项目级再按需引入 TDD、文档同步等长期不用的技能果断移出主配置需要时再临时引用。提示如果你的模型请求频率高建议观察一下每次请求的 token 消耗通常技能包的 overhead 大概在几百到一两千 token。这个开销对效果提升而言完全值得但如果你的模型上下文窗口本来就小就要小心不要把窗口撑爆。6.5 最后再分享一个实用小技巧我给所有使用 superpowers 的朋友同一个建议不要把它当作固定不动的“安装包”而要当作一套可以随意修改的方法论模板。我在实际项目里会把团队踩过坑的编码约束定期追加到项目的AGENTS.md里让 Agent 跟着团队一起“成长”。这样用了一段时间之后你会发现自己和 Agent 的配合越来越默契很多以前需要反复交代的事情它自己就记住了。根据我个人经验superpowers 这类技能包真正的价值不在于它自带多少技能而在于它提供了一个“把工程经验结构化喂给模型”的范式。整个链路由“人写规则”和“模型执行”构成规则写得越贴合实际模型的表现就越超预期。这套思路无论是用在 Codex CLI、Trae 还是其他 Agent 工具上都值得一试。
superpowers：为Codex CLI打造的AI编码Agent技能包，让写代码更可控
最近在 GitHub 上看到一个叫 superpowers 的项目翻了翻 star 数涨得很快评论区一堆人在 Codex CLI、Claude Code 里折腾它。一开始我以为又是什么花里胡哨的 prompt 合集但实际用下来发现它解决的恰恰是编码 Agent 最让人头疼的那几个问题模型拿到需求直接开写、写到一半忘了最初的约定、报错之后胡猜乱改。这篇文章我就以自己的实操经历为主线聊聊 superpowers 到底是什么、为什么值得装、以及怎么在 Codex CLI 这类终端工具里把它配置好并真正用起来。这篇文章适合已经在用或准备用 Codex CLI、Trae 这类 AI 编码工具的朋友尤其是那些觉得默认行为不够可控、想给 Agent 建立一套明确工作流的人。我会尽量把配置过程和踩坑细节写清楚方便你直接照着操作。1. superpowers 到底是什么给 Codex 的“超能力技能包”先纠正一个容易混淆的点superpowers 不是一个模型也不是一个独立运行的命令行工具它是一套专门为编码 Agent 设计的技能包skill pack。所谓技能在 AI Agent 的语境里本质上是结构化的提醒规则和操作流程告诉模型在什么场景下应该按什么步骤思考、执行什么样的动作。1.1 它不是模型而是“调用模型的方法”我见过不少朋友第一次接触这个项目时误以为装上 superpowers 就等于换了一个更强的模型结果发现对话还是原来的模型效果却确实不一样了于是觉得神奇。其实背后的原理很简单superpowers 通过注入一套前置指令让模型在回答前先经过一遍系统化的思考流程。举个例子默认情况下你让 Codex 改一个 bug它可能直接给你一段修复代码。但接入 superpowers 的 debug 类技能后模型会先要求你提供重现步骤、查看错误堆栈、分析可能原因然后再给出修复方案。这就是“技能包”存在的意义——它改变了模型的工作方式而不是模型的智力水平。1.2 为什么叫 superpowers四个核心能力来源项目叫 superpowers是因为它重点强化了编码 Agent 最薄弱的四个环节计划先行让 Agent 在动笔写代码之前先输出实现计划列出文件、函数、接口变更点。系统化调试遇到 bug 时引导 Agent 按证据链排查而不是凭直觉瞎试。测试驱动推动 Agent 先写失败测试再实现功能让测试成为需求的“可执行说明书”。需求追问在需求描述不清晰时主动向用户提问澄清而不是硬着头皮开写。这四个能力听起来不复杂但放到 Agent 身上默认行为往往完全相反。模型是典型的“机会主义者”你给它一个模糊任务它会倾向于快速给出一个看起来合理的结果而不是花时间追问或做计划。superpowers 的作用就是用结构化的 skill 文件把这种行为“掰”回来。1.3 使用它的前提与适合人群想用好 superpowers你需要具备以下基础条件有一个支持自定义指令或技能加载的编码 Agent 工具比如Codex CLI、Trae其他兼容工具也可以。对命令行基础操作不陌生至少会使用git clone、编辑配置文件。有基本的编程经验因为 superpowers 的大多数技能都服务于真实编码场景纯小白可能会觉得概念太密。如果你平时只是用 AI 写写文案、做做表格那这个技能包大概率帮不上忙。但如果你是那种每天都让 Agent 写代码、改 bug 的人它带来的收益会非常明显尤其是面对多文件项目时Agent 的行为会从“怎么快怎么来”变成“怎么稳怎么来”。2. 为什么要装它原生编码 Agent 的四个致命短板我在没装 superpowers 之前曾在一个中型 Python 项目上被 Codex 连续坑了好几次后来认真复盘发现原生 Agent 的行为模式存在四个非常典型的短板。搞清楚这些问题你才能真正理解 superpowers 的设计动机。2.1 模型爱直给结果不爱讲过程默认情况下你问 Agent “帮我实现一个用户登录接口”它大概率会直接甩给你一段完整的 Flask/FastAPI 代码中间没有任何计划、没有文件划分、没有依赖分析。这在简单场景下没问题但项目一旦复杂直接给结果往往意味着忽略了现有代码结构、接口约定、数据模型关系。我见过最夸张的一次Agent 在一个已有数据库模型的项目里直接另起炉灶又建了一套模型因为它根本没有先去读已有的模型文件。superpowers 的 plan 技能就是强制模型先“读代码、出计划、列影响面”再开始动手。2.2 模型没有“长时记忆”开头约定结尾忘大模型的上下文窗口虽然越来越大但对话一长早期约定的细节照样会被稀释。你第一句话要求“所有接口返回格式统一为{code, data, msg}”写到第五个文件的时候它很可能已经用回了裸数据返回。这个问题不是模型笨而是注意力机制天然如此。superpowers 的做法是把关键约束写进技能文件并在合适的时机提醒模型“回顾项目规范”。它相当于给模型发了一张持续可见的便签而且这张便签不是放在对话历史里被冲淡而是每轮都可能被重新激活。2.3 模型对报错信息的处理是“敷衍式”的遇到报错时原生 Agent 最常见的反应是根据报错信息猜一个原因然后把代码改一版再跑一次不行就再猜。这种“瞎猜循环”在小 bug 上偶尔能蒙对遇到真正的疑难杂症就非常浪费时间。superpowers 的 debug 技能要求模型遵循一套严谨的调试流程先确认环境、再找最小复现、然后看堆栈定位、最后验证修复。你会发现思路一旦被流程框住模型的行为会从“碰运气”变成“做排查”。2.4 默认工具链缺少工程流程约束很多团队其实有编码规范、有测试要求、有代码审查流程但这些约束很难被塞进默认的 Agent 行为里。Codex CLI 虽然支持项目级配置但如果你不主动写规则模型就完全不知道有这些约束。superpowers 的核心优势就在这儿它不是单一指令而是一整套可组合的技能体系。一个团队可以在技能里固化自己的工程规范比如强制要求每次提交前跑测试、强制要求写类型注解、强制要求更新文档。Agent 在这些技能的约束下工作行为方式会更接近一个“懂规矩的初级工程师”。3. 安装与配置从 GitHub 到 Codex CLI 的全流程实操接下来进入正题我以 Codex CLI 为主要演示对象讲解如何拉取 superpowers 项目并把它接入到你的 Agent 工作流中。整个安装过程本质上就三步获取文件、写入配置、验证加载。3.1 获取 superpowers 项目文件superpowers 代码托管在 GitHub 上项目名就是superpowers搜索关键词“superpowers github”很容易找到。拿到仓库地址后直接克隆到本地固定目录git clone https://github.com/owner/superpowers.git ~/superpowers提示仓库地址中的owner以官方 README 为准不同镜像和 fork 的地址可能不同。我建议你克隆后用ls看一下目录结构确认是否存在skills目录或类似命名的技能目录。克隆下来之后项目目录里通常会有多个子目录或文件每个技能对应一个文件夹里面有一个SKILL.md文件这是技能的核心定义。它的结构大致是superpowers/ ├── README.md └── skills/ ├── plan/ │ └── SKILL.md ├── debug/ │ └── SKILL.md ├── tdd/ │ └── SKILL.md └── ...SKILL.md的头部一般有name、description之类的元信息frontmatter正文则是具体的操作指令。这个设计非常像静态站点生成器里的 Front Matter 约定只不过这里服务的是 Agent 的行为控制。3.2 接入 Codex CLI 的两种方式拿到技能文件后接下来要让 Codex CLI 在每次对话时能读到这些规则。我的经验是两种方式可以搭配使用方式一在项目级AGENTS.md中引用Codex CLI 支持在项目根目录放一个AGENTS.md文件里面的内容会自动附加到每次请求的上下文中。你可以在里面显式地告诉模型去加载 superpowers 的技能文件# 项目说明 本项目的 AI 编码流程遵循 superpowers 技能包。 请先阅读 /Users/你的用户名/superpowers/skills 目录下的技能定义。 遇到编码任务时先触发对应的 skill再按 skill 中的步骤执行。这样做的好处是按项目生效不同项目可以引用不同的技能组合坏处是每新建一个项目都要配置一次。方式二在 Codex CLI 全局配置中引用Codex CLI 的配置文件一般位于~/.codex/config.toml你可以在配置里加上自定义指令让它对所有项目生效。不同版本字段名可能不一样核心思路是把 superpowers 目录的路径写进模型的系统提示词或者额外的指令列表里。注意Codex CLI 版本更新频繁配置字段可能存在差异。我第一次装的时候照着一个旧教程写信总配置结果模型完全不理会技能包后来仔细看官方 README发现新版已经改成读取AGENTS.md的优先级更高了。所以配置前务必瞄一眼项目文档以官方推荐路径为准。3.3 Trae 等图形 IDE 的接入思路关键词里有人提到了“trae work cn 安装 superpowers skill”说明很多朋友是在 Trae 这类图形化 AI IDE 里使用的。Trae 的底层能力模型与 Codex 不完全相同但加载 skill 的思路是相通的找到 IDE 的“自定义指令”或“角色/技能”设置入口把 skill 内容粘贴或挂载进去。如果你在 Trae 里找不到直接的技能目录我的建议是先看 Trae 的设置页面里有没有“自定义提示词”“规则文件”之类的选项。如果有“从文件导入规则”的功能直接把SKILL.md文件的路径或内容导入。如果只有文本输入框那就把SKILL.md的核心指令精简复制进去。需要特别提醒图形 IDE 的 skill 加载机制往往是非标准的同一个技能包可能会有兼容性问题。我的处理方式是把 superpowers 里最核心的 plan 和 debug 两个技能手动粘贴到 Trae 的全局规则里其他技能按需再说。先保核心再图全量这是我在图形 IDE 里验证过的稳妥策略。3.4 验证是否加载成功配置完成后别急着写业务代码先验证一下技能包有没有真正生效。最简单的方法是在对话里打一个测试请求比如我要在项目里新增一个用户注册接口请按 superpowers 的规范处理。如果配置生效模型应该会先输出实现计划列出涉及的文件、函数、数据结构然后再开始写代码。如果模型直接甩出一段代码说明技能包没有加载成功需要回头检查配置路径和优先级。4. 核心技能拆解Plan / Debug / TDD 到底怎么用superpowers 里技能很多但真正高频使用的是 Plan、Debug、TDD 这三板斧。我把每个技能的核心逻辑和实操要点拆开讲。4.1 Plan 技能强制让 Agent 先画图纸Plan 技能要解决的问题很简单AI 太喜欢直接动手了。在软件开发里直接动手写代码通常意味着跳过架构思考、忽略已有约束、缺少迁移路径。尤其当你面对的是一个有一定规模的项目时没有计划的直接实现基本等于裸奔。接入 Plan 技能后模型的响应流程会变成先阅读理解任务识别涉及的核心模块。输出一份简明实现计划包括要修改的文件、要新增的依赖、接口签名、数据流。把计划展示给用户等待确认后再开始执行。我实际用下来的感受是Plan 技能最适合两种场景一是新功能开发二是跨模块重构。这两个场景一旦跑偏返工成本极高。有了计划在前你可以在一分钟内心算出 Agent 的路线图是否合理从而避免它一头扎进坑里。提示如果你觉得 Agent 输出的计划太长、太啰嗦可以在技能文件里加一条规则“计划控制在 10 行以内优先列出改动文件和关键函数签名”。技能是死的人是活的学会改规则才是进阶玩家。4.2 Debug 技能从“瞎猜”到“证据链”Debug 技能是我个人最推荐的一项。因为编码 Agent 写的代码是否优雅是次要问题能不能定位 bug 才是主要问题。原生模型面对报错时喜欢“跳跃式”推理靠猜来产生新的代码superpowers 的 debug 技能则把模型按进一条证据链里要求用户提供完整报错信息包括堆栈位置、环境版本、操作步骤。分析报错前最后一次成功状态定位变更点。用最小化复现方式比如写一段独立脚本、用一个测试用例来隔离问题。验证修复是否真的解决了根因而不是把报错藏起来了。有一次我调试一个 Node.js 的异步问题模型按 debug 流程一步步排查最终发现是事件循环里的一个错误捕获遗漏导致的。整个排查过程看起来就像一个经验丰富的开发者戴着头灯在暗房里找保险丝而不是实习生乱拔电线。4.3 TDD 技能把测试当作需求说明书TDD也就是测试驱动开发是很多开发团队想推却推不动的实践。原因很简单写测试的即时反馈太低很多人写着写着就放弃了。但模型没有这个心理负担你让它先写测试它就老老实实写。superpowers 的 TDD 技能核心动作是让 Agent 围绕“红-绿-重构”循环工作红先写出失败测试明确业务的期望行为。绿写最小代码让测试通过不做多余设计。重构在测试保护下改进代码结构保证行为不变。我建议你在让 Agent 实现某个功能时明确加上一句“先写测试再写实现”。你会发现模型先写测试时会自动把需求的边界条件想得更清楚因为它必须用代码表达“什么行为才算正确”。用测试倒逼需求澄清比自己写需求文档再让模型实现要可靠得多。4.4 其他常用技能速览除了三件套superpowers 还包含一些细分技能我整理了一个速查表技能方向主要作用适用场景需求澄清追问用户收集完整需求需求描述模糊、缺边界条件文件阅读强制阅读相关代码后再动手多文件项目、老代码修改规范执行遵守项目级规范格式、命名、提交团队协作、有代码规范约束文档同步修改代码后同步更新文档开源项目、接口文档、README这些技能不一定每次都会触发但它们的存在能显著提升 Agent 的“职业感”。我甚至觉得superpowers 最大的价值不是某个技能本身而是它塑造了一种“先规划、再行动、勤反馈”的 Agent 人格这种人格才是它被称为 superpowers 的原因。5. 进阶使用技巧与工作流编排当你能熟练使用单技能之后下一步就是把这些技能串成一个完整的工作流。这里我分享几个我自己摸索出来的编排思路。5.1 把技能串成一个完整任务流假设我现在要让 Agent 给一个 Flask 项目增加 JWT 登录认证理想的任务流是需求澄清 → 项目读码 → 输出计划 → TDD 测试先行 → 写实现 → 跑测试验证。我现在的习惯是在对话里一次性把这个流程提给模型我的目标是在现有 Flask 项目里加入 JWT 登录认证。 请遵循以下流程 1. 先读取项目结构确认已有依赖和模型定义 2. 输出实现计划不超过 10 行 3. 按超级技能优先写失败测试 4. 实现功能直到测试通过 5. 最后更新 README 的接口说明。这样做的效果非常明显。模型每一步都有明确指令不会从“加 JWT”跳到“重写整个用户模块”。而且因为计划先行我在它动手前就能发现潜在问题比如它打算新建一个auth.py但项目里其实已经有security.py我可以提前打住。5.2 如何给技能写自定义约束superpowers 原生的技能规则大概率是放之四海而皆准的通用规范但你的项目一定有特殊约定。我的做法是在项目级AGENTS.md里叠加自定义约束而不是去改 superpowers 的文件。比如我们的团队要求所有写操作的接口都必须记录审计日志那么我会在AGENTS.md里加一条所有涉及数据修改的接口必须在完成核心逻辑后调用 audit.log(user, action, target)否则视为任务未完成。superpowers 帮 Agent 建立流程骨架自定义约束则告诉它“你的代码要符合我们家的地基”。两者配合Agent 的表现会非常接近一个熟悉团队规范的老开发。5.3 让 Agent 在长任务中不跑偏的提示技巧长任务最容易出现的问题不是模型不会做而是做了一半忘记上下文。superpowers 虽然能缓解这个问题但无法完全消除。我常用的补救手段是分段确认每完成一个阶段让模型用 3 行以内总结当前状态下一个阶段开始前要求模型先读取上一步的改动再继续如果任务超过 5 个文件改动我会把阶段节点拆得更细宁可多对话几次也不要让它一口气闷头写。这个过程有点像一个靠谱的开发者在群里同步进度而不是闷头写代码三个小时然后丢给你一堆 commit。慢是慢一点但出错的概率直线下降。5.4 结合上下文缓存的小建议如果你的 Agent 工具支持上下文缓存比如某些 API 的 prompt caching那可以考虑把 superpowers 的技能文件按“全局规则”和“项目规则”分开管理。全局规则放系统级项目规则放AGENTS.md。这样做一方面节省 token另一方面也避免全局规则过于臃肿拖慢响应速度。我第一次把整个 superpowers 目录都塞进配置时每次请求都额外消耗了大量 token响应也明显变慢。后来我把“通用方法论”和“项目专属约束”分开效果好了很多。技能包不是越多越好够用就好。6. 常见问题与避坑实录最后这部分我把实际操作中遇到过的典型问题整理出来按排查思路讲清楚。这些问题在网上资料里很少一次性说明白建议你收藏备用。6.1 模型完全不理会技能怎么办如果你发现模型对你的技能指令视若无物大概率不是模型坏掉了而是技能的优先级太低。在 Codex CLI 这类工具里系统提示词的指令层级高于用户指令有些版本的全局配置优先级高于AGENTS.md有些则相反。我的排查步骤是确认配置写入位置正确全局 vs 项目级。用一条简单指令测试模型是否响应你的规则比如“按规则先列计划再写代码”。检查技能文件路径是否有拼写错误尤其是用户目录名~有时在子进程里不会被自动展开。确认没有其他全局规则与 superpowers 冲突把影响降到最低。6.2 Trae 里使用了技能但没效果Trae 这类图形 IDE 的规则加载机制往往比 CLI 更隐蔽而且版本差异极大。有用户反馈在“Trae work cn”环境里安装了 superpowers skill 后没有效果我遇到过的常见原因有三类规则入口找错了有些版本需要在项目设置里单独开启“读取自定义 Skill”的开关默认是关闭的。内容格式不兼容Trae 的规则输入框可能不支持 Markdown frontmatter需要手动去掉头部元信息只保留正文步骤。模型版本不支持某些轻量模型对长指令的理解能力偏弱即便你把技能内容喂进去它也无从遵循。这种情况下换一个更强的基础模型才是正解。6.3 多技能同时触发导致冲突superpowers 的技能如果能同时触发有时候会产生重复指令。例如plan技能要求“先列计划”而另一个自定义规则却要求“立即开始写代码”模型就会陷入混乱。我处理这类冲突的原则是给优先级排序。在AGENTS.md里明确写上如果多个技能指令存在冲突优先级从高到低为 1. 用户最新明确指令 2. 项目安全规范如数据删除必须确认 3. superpowers 通用技能 4. 其他优化建议有了这个优先级声明模型在冲突场景下就不会随机发挥行为可预期了很多。6.4 提示词太长消耗 token 太猛superpowers 的技能文件本身不短你把所有技能都挂载到每次请求里token 消耗非常可观。更麻烦的是有些按 token 计费的服务会让你钱包肉疼。我的建议是控制挂载粒度全局只挂载最通用的 plan、debug 两个技能项目级再按需引入 TDD、文档同步等长期不用的技能果断移出主配置需要时再临时引用。提示如果你的模型请求频率高建议观察一下每次请求的 token 消耗通常技能包的 overhead 大概在几百到一两千 token。这个开销对效果提升而言完全值得但如果你的模型上下文窗口本来就小就要小心不要把窗口撑爆。6.5 最后再分享一个实用小技巧我给所有使用 superpowers 的朋友同一个建议不要把它当作固定不动的“安装包”而要当作一套可以随意修改的方法论模板。我在实际项目里会把团队踩过坑的编码约束定期追加到项目的AGENTS.md里让 Agent 跟着团队一起“成长”。这样用了一段时间之后你会发现自己和 Agent 的配合越来越默契很多以前需要反复交代的事情它自己就记住了。根据我个人经验superpowers 这类技能包真正的价值不在于它自带多少技能而在于它提供了一个“把工程经验结构化喂给模型”的范式。整个链路由“人写规则”和“模型执行”构成规则写得越贴合实际模型的表现就越超预期。这套思路无论是用在 Codex CLI、Trae 还是其他 Agent 工具上都值得一试。