如果你跟我一样每天花大量时间在终端里跟 AI 编程助手较劲你应该也遇到过这个场景让它“实现一个功能”它唰唰唰吐出一大段代码但细看下来要么没理解需求要么东缺一块西漏一段要么直接跑不通。你不得不一遍遍补充上下文、纠正错误最后发现——AI 写代码挺快但“干活”这件事它远远不合格。“superpowers”这个项目就是冲着这个问题去的。它不是某个具体的库也不是一个函数而是一整套基于 Agent Skills 机制的工作流技能包。装好之后你的 AI 编程助手不再是“你给一句它写一段”的代码生成器而会变成一个会先问需求、再出方案、然后写测试、最后才动实现的“见习工程师”。GitHub 上它的热度涨得很快相关教程和讨论也越来越多Codex CLI、Claude Code、Trae 这些工具的用户都在折腾怎么把它跑起来。这篇东西我尽量讲透superpowers 到底是什么、它的核心机制怎么工作、在 Codex CLI 上怎么装、装完之后哪些技能是真有用的以及我实际用下来踩过的坑。不想讲太多理论希望你看完能直接在自己的终端里把同样的流程跑起来。1. superpowers 解决的不是“写代码”而是“干活”1.1 为什么 AI 助手经常“会写代码不会干活”先聊聊我对 AI 编程助手的不满这大概也是 superpowers 走红的基础。大多数时候我们用 AI 助手的方式是“给一个任务等一个答案”。这个模式对于“写个脚本处理 CSV”“写一个快速排序”这类边界清晰的小问题非常好用但一旦任务变成“给我们的用户系统加一个找回密码功能”问题就出来了。为什么因为 AI 的“一次生成”模式根本不适合复杂任务。一个功能可能涉及数据库表、邮件服务、前端页面、路由鉴权、错误处理、日志埋点还关系到现有的代码风格和业务约束。这些信息不可能塞进一次对话里。于是 AI 只能猜然后自信地输出一大坨代码。你让它改它又基于错误的假设继续猜越改越乱。我自己最崩溃的一次是让 AI 帮我重构一个模块的异常处理。它以为自己理解了我的意思直接把整个模块重写了改了十多个文件的接口——但我只是想在原有结构里把try-catch规范一下。它太想“把事情做完”了反而做过了头。这个问题的本质不是模型不够聪明而是没有人告诉它一个合格的工程师应该如何工作。真人接手一个任务第一步会做什么先搞清楚需求再确认影响范围然后给方案拆步骤最后才动手。AI 没有这个本能它只有“尽快生成看起来最合理的答案”这个本能。superpowers 要做的就是把这个工作流替 AI 补上。1.2 我理解的 superpowers 是什么superpowers 的作者是 Jesse Vincent开源圈的老熟人。它本质上是一个Agent Skills 集合里面装了大量结构化的技能文件每一个技能都对应工程师日常工作中的一种能力需求澄清、技术方案设计、测试驱动开发、子任务拆分、代码审查、写提交信息、系统化排错等等。当你给 AI 助手安装并启用这些技能后它就不再是“裸奔”的模型了。它会按照技能文件里的流程指引和你进行多轮交互。比如在动手写代码前它会先用“brainstorming”技能跟你反复确认需求把模糊的想法逼成一份明确的产品需求文档接着用“plan”技能产出技术方案再用“TDD”技能要求自己先写测试最后才进入实现阶段。这套东西厉害的地方在于它把“资深工程师的工作方法论”变成了模型的显式指令。模型不需要在每次对话中自己悟出“我应该先问清楚需求”因为技能文件已经把这一步写死了。它必须这么做否则就无法进入下一个环节。我刚开始用的时候最大的感受是“烦”——它怎么这么多问题但跑了几个真实任务之后我服气了。正是因为它在前期烦了我十分钟后面实现阶段几乎没有返工。相比之下以前那种一言不合就开干的模式表面痛快实际全是暗坑。1.3 什么样的项目最适合它superpowers 并不是万能的。我建议按这个标准判断值不值得用任务复杂度高涉及多个文件、多个模块、需要设计方案的任务收益最大。单纯让 AI 写一个 20 行的工具函数没必要走完整工作流。需求不明确的场景你只有一个模糊想法连自己都没想清楚要什么。这种时候 brainstorming 技能的价值极高它会逼你把需求想明白。团队协作项目AI 产出代码时需要符合团队既有的风格和约束一套标准化的 workflow 可以让 AI 的输出质量保持稳定。教学和学习场景让新手观察“一个功能从需求到实现应该怎么推进”这比直接看代码有教育意义得多。如果你只是把 AI 当“高级补全插件”在用那 superpowers 对你来说可能有点重。但如果你跟我一样想把 AI 当成一个真正能交付任务的协作者这套工作流值得认真研究。2. 核心机制Skill 文件、渐进式披露和工作流编排2.1 Skill 文件是怎么组织的Agent Skills 机制本身并不神秘。它的核心是一个叫SKILL.md的文件里面用 Markdown 写了这个技能的名称、描述、适用场景、完整的工作步骤、必须遵守的规则以及可能用到的模板。superpowers 的仓库结构差不多是这样的根目录下一堆以技能命名的子目录每个目录里都有一个SKILL.md。目录名就是技能名比如skills/brainstorming/SKILL.md、skills/plan/SKILL.md、skills/tests/SKILL.md。AI 助手会扫描这些文件把技能列表装进自己的“工具箱”。每个技能里还可能有附加资源。举例说“plan”技能可能包含一个技术方案模板文件AI 在处理任务时会参考这个模板去写方案“commit”技能可能包含一个规范提交信息的格式示例。这些附加资源让技能不只是“说说而已”而是真的可以落地执行。我拆开看过几个技能文件里面写得相当细致不是那种“你应该好好做计划”的空话而是类似于“如果需求中提到 X 场景你需要追问 Y 信息”这种带决策树味道的明确指引。这就是它和普通 Prompt 最大的区别——普通 Prompt 是告诉模型“要专业”技能文件是告诉模型“具体怎么做才叫专业”。2.2 渐进式披露为什么不用一个超级大 Prompt一个自然的疑问是既然工作流这么重要为什么不写一个包含所有流程的超级长 Prompt一次性扔给模型这就是 superpowers 设计里非常巧妙的地方——它采用了渐进式披露的策略。AI 助手在最开始只需要知道“有哪些技能”以及“每个技能是用来干什么的”而不用把每个技能的完整执行细节都加载进上下文。当它判断当前任务需要某个技能时才去读取那个技能的详细SKILL.md把完整的步骤加载进来。这个设计对 token 消耗和响应质量影响巨大。如果你把所有技能的完整指引一次全塞给模型上下文动不动就几万 token模型反而会“看不过来”该执行的步骤被淹没在无关信息里。而渐进式披露保证了在任何一个时刻模型聚焦的都是当前任务真正需要的指令。我打个比方你就明白了。你入职一家公司HR 不会第一天就把员工手册、部门规范、技术文档、公司战略全丢给你。你只需要知道要去哪个部门报到等真正开始做某个项目时再去翻对应的流程文档。superpowers 的 skill 机制就是这个逻辑。Codex CLI 之所以能兼容这套机制也是因为它的自定义指令系统支持按需加载——模型读取到技能列表后会在需要时打开具体的.md文件来获得操作指引。这一点我在后面安装部分会详细展开。2.3 工作流编排从头脑风暴到提交代码讲完机制再看 superpowers 的“完整工作流长什么样”。我拿一个真实任务举例给一个内部工具增加“批量导入用户数据”的功能。在没有 superpowers 的老模式下我可能会直接说“帮我加一个批量导入用户的功能。”AI 立刻开始写代码然后我一遍遍发现它漏了文件上传校验、没考虑重复用户、CSV 编码格式搞错了……来来回回折腾大半天。在 superpowers 模式下流程是这样的brainstormingAI 先不写代码。它会问我导入的数据有哪些字段重复用户如何处理最大支持多少行需要提供导入结果反馈吗错误数据是跳过还是终止有没有现成的用户模型可以复用问完一轮输出一份 PRD 让我确认。plan确认需求后AI 产出技术方案新增哪些接口、数据库层面需不需要做调整、用什么方式解析 CSV、前端如何提供下载错误报告入口并列出实现顺序和风险点。TDD测试驱动开发方案确认后AI 不会立即写实现而是先写测试用例构造合法 CSV、非法 CSV、重复数据、过大文件等场景全部写成失败的测试。implementation测试写好后AI 才开始实现代码目标是让测试通过。代码质量和覆盖率有测试兜底基本不用担心“改崩”。commit实现完成后AI 把代码交回给我审查并生成规范化的 commit message甚至包括这次变更涉及的文件和影响面总结。你发现没有这整套流程就是把一个资深开发者的日常节奏搬进了模型的行为逻辑里。从需求澄清到方案设计到测试优先到逐步实现每一步都有输出产物都有检查点。我确认过 PRD 和技术方案之后后面几乎没有再被 AI 的“自作主张”坑过。3. 在 Codex CLI 里装好 superpowers 的完整过程3.1 先把 Codex CLI 跑起来在折腾 superpowers 之前你得有一个能跑 AI 模型的终端环境。我自己主力用的是 Codex CLI。OpenAI 开源的终端编程代理安装很简单只要机器上有 Node.js 18 及以上版本一条命令就能搞定npm install -g openai/codex装完之后在终端输入codex就能进入交互模式。首次使用它会要求你配置 API 相关的认证信息这里我就不展开讲了按官方提示操作即可。我手里这个版本的 Codex CLI 已经支持自定义指令也就是能读取~/.codex/prompts/目录下的 Markdown 文件作为自定义指令这为跑 superpowers 提供了基础。如果你还没跑起来 Codex CLI先别急着往下装 superpowers。有任何版本兼容问题或者命令行报错优先检查 Node 版本和网络连通性。把这个基础环境弄干净后面会省很多事。3.2 把 superpowers 仓库装到正确的位置superpowers 官方主要面向 Claude Code 生态但因为它本质上是 Markdown 技能文件所以只要你的工具支持自定义指令加载就能借用这套技能。在 Codex CLI 里的装法我实际操作下来是这样的先把仓库克隆到本地git clone https://github.com/obra/superpowers.git然后如果你用的是 Codex CLI把技能文件放到它的自定义指令目录。以我的环境为例Codex 会读取~/.codex/prompts/下的.md文件。因此我需要把 superpowers 里的技能文件复制或者软链接到这个目录下mkdir -p ~/.codex/prompts cp -r superpowers/skills/* ~/.codex/prompts/这样做的效果是我在 Codex 交互界面中就可以通过/命令看到这些技能列表模型能够感知到这些技能的存在并在需要时读取其内容作为工作指引。如果你用的是 Claude Code路径则是~/.claude/skills/直接把 superpowers 仓库里的技能目录克隆或软链接过去即可mkdir -p ~/.claude/skills ln -s $(pwd)/superpowers/skills/* ~/.claude/skills/这里有个小细节要提醒你不要整个仓库一股脑拷过去只拷skills子目录。仓库根目录还有一些示例和说明文档放进技能目录反而会让模型误以为那些也是可用的技能导致它在技能选择时出现混乱。我一开始图省事直接全量拷贝结果模型老是引用一些不存在的技能名字排查了半天。3.3 在 Trae 这类 IDE 环境中适配现在很多人已经不在纯终端里干活了Trae、VS Code、Cursor 这类 AI IDE 才是日常主力。“trae work cn 安装 superpowers skill”这个搜索词的出现说明很多人在尝试把 superpowers 搬进 IDE。以 Trae 为例它本身是支持 Agent Skills 机制的如果你的 Trae 版本里能找到“技能”或“Skills”相关的配置入口可以直接指定一个技能目录。在这里把 superpowers 的skills目录配置进去和上面终端里的逻辑是完全一致的。配置好之后你在 Trae 里唤起 AI 编程助手它同样能识别到这些技能并按照工作流执行。我个人的建议是在 IDE 里跑 superpowers优先确认你的 IDE 是否支持“按需读取技能文件”的机制。很多 IDE 的对话系统实现方式是把系统提示词一次性拼好不支持后续按需读取文件这种情况下技能文件虽然存在但模型不会主动去读效果会大打折扣。遇到这种情况一个退而求其次的办法是把关键的技能内容通过项目级规则文件比如AGENTS.md或项目说明文件注入给模型。虽然少了“渐进式披露”的精髓但至少能让模型遵循核心的工作步骤。这不是最优解但在不支持完整 skill 机制的 IDE 里属于能用方案。4. 逐个实测核心技能哪些是真有用的4.1 brainstorming把模糊需求逼成 PRD如果只能选一个技能留下来我会选brainstorming。这听起来不像是什么炫酷的技术但实际用过之后我发现它解决了我跟 AI 协作中最大的痛点——需求不清导致的返工。它的工作方式是用苏格拉底式提问把需求边界一点点逼出来。比如我让它“给博客系统加一个标签云功能”它不会立刻开写而会问我标签云的排序逻辑是什么按文章数排序还是按名称标签需要管理页面吗老文章的标签怎么迁移标签数量多的时候怎么展示这轮问询通常会持续十几分钟最后输出一份结构完整的 PRD。刚开始我嫌烦但做完一个项目之后我明白了它的价值。以前我让 AI 直接写一个功能它憋出来的代码大概率有 30% 的需求理解偏差。现在前置把这些偏差通过对话全部消灭掉实现阶段的返工率骤降。关键节点是PRD 输出后AI 会让我确认。这个“确认动作”非常重要等于在需求层面设立了一道人工审核关卡。我在实际工作中发现很多所谓“AI 不靠谱”的负面体验根源都是需求没有确认就开干最后自然全是偏差。4.2 plan 与 TDD从设计到测试的两道保险需求确认之后plan技能开始介入。它会产出一份技术方案文档内容涵盖模块划分、接口设计、数据结构变更、实现顺序、风险提示。这份方案同样要经过我的确认才能进入下一阶段。某种程度上plan 技能相当于一个“强制设计评审”让 AI 把思路摊开在桌面上而不是直接“黑盒式”地生成代码。TDD 技能是另一道保险。它的逻辑非常朴素实现代码之前先写测试用例。AI 会分析 PRD 中的功能点拆分成具体的输入输出场景生成测试代码。这些测试这时候跑是失败的因为它们测试的功能还没有实现。等测试写好AI 才开始写实现。目标是让测试从红变绿。在这个机制下我基本不用担心 AI 悄悄改接口或者跳过某些边界场景因为测试会暴露一切。这个体验比“写完代码自己 review”要省心太多了。这里我需要额外说明TDD 技能并不适用于所有场景。像探索性脚本、一次性原型、快速实验这类项目过分追求先写测试会让你非常难受。我自己一般只在核心业务代码或公共库上启用完整的 TDD 流程其他场景就跳过。4.3 subagent 并行执行拆任务时别忽略上下文边界superpowers 里的subagent技能指导模型将一个大任务拆分成多个可以独立执行的子任务然后并行推进。听起来很美好但它对项目的要求其实很高子任务之间必须高度解耦否则并行起来会出现“两个子任务同时改一个文件”的冲突。我用它重构过一个前端项目里的工具函数库效果不错。AI 把“数据转换”“日期处理”“字符串校验”“DOM 操作”分别拆成不同子任务每个子任务有明确的输入输出和测试要求并行完成后由主任务统一集成。但我也要提醒你当你发现一个任务很难拆分成“互不依赖”的子任务时不要强行拆。如果两个子任务都依赖同一个底层模块并行执行时它们很容易产生不一致的假设。这种情况我一般选择串行推进或者先让 AI 完成公共依赖再拆子任务。4.4 bug solver系统化排错胜过灵机一动bug-solving是我后期才用上的技能但它的价值被低估了。以前我让 AI 看 bug它往往直接根据错误信息给一个修复建议然后我改完发现还有下一个 bug。现在这个技能会强制 AI 按一套标准流程来排错建立错误复现路径、查看相关日志、提出多个假设、逐个验证、定位根因、再给修复方案。我印象最深的是一次线上故障排查。AI 一开始怀疑是数据库连接池耗尽按照它给的假设去查结果不是。它没有放弃而是按照技能流程重新检查了另一个假设——Redis 集群的 key 过期策略。最终定位到是一个缓存雪崩问题。放在以前模型可能早就开始胡猜了但有了系统化的排错流程它会像工程师一样做排除法。这套排错流程对新手特别友好。如果你对系统运维经验不足AI 的“按步骤排查”本质上是在教你一套调试方法论先复现、再假设、再验证。学会了这套流程以后自己处理问题也有章可循了。5. 实操中的坑和调参经验5.1 模型能力决定体验别用小模型跑复杂 skillsuperpowers 的理念再先进最终执行的还是底层模型。我在 Codex CLI 里用自带的小参数模型跑过一次完整的 plan 流程效果非常拉胯技能要求它追问需求它追了两轮就开始自问自答让它输出技术方案它写出来的东西深度不够和直接生成代码没区别。后面我换成了能力更强的高端模型体验立刻上了一个台阶。它能认真执行技能文件里的每一步追问的问题有深度产出的方案也能看出逻辑链条。我的结论是superpowers 这类工作流框架适配的本来就是聪明模型小模型连基本指令遵循都费劲加再多工作流也是白搭。如果你在 Codex CLI 的config.toml里配置了模型跑 superpowers 时建议把模型能力拉满。token 消耗确实会大一些但考虑到它会显著减少返工次数综合成本其实更划算。5.2 中文项目的适配改改 prompt 也能 worksuperpowers 的技能文件默认是英文这在处理中文项目时偶尔会出现“翻译腔”。比如它产出的 PRD 和技术方案文风偏洋气关键术语也是英文风格。这不影响功能实现但在团队协作中会比较违和。我的做法是在项目根目录的AGENTS.md里加几句说明告诉 AI“所有产出的文档和提交信息都使用中文遵循团队命名风格”。加了这一条之后它的输出就正常多了。还有一种情况是项目本身有特殊规范比如数据库表命名要求全局唯一、接口返回结构必须带固定状态码。这些规范技能文件不知道但你可以在AGENTS.md里写清楚配合技能工作流使用效果更好。superpowers 解决的是“怎么做”项目规范解决的是“做成什么样”两者不冲突。5.3 上下文爆炸和 token 控制这是我的另一个实战教训。superpowers 的完整工作流会持续多轮对话每轮对话都会携带前面的上下文。当项目稍大、PRD 和技术方案又长的时候很容易触发上下文超限。尤其是 plan 技能产出的方案文档一次可能就好几千 token如果中途再加载多个技能文件上下文消耗极快。应对办法有三个任务分段执行不要试图在一个会话里跑完全流程。需求澄清和方案设计用一个会话实现阶段看到前面输出保存后另开一个会话加载上下文继续。及时清理无关内容比如反复修改过的旧方案、已经确认的冗长日志这些尽量手动清出会话。使用摘要代替全文在进入实现阶段时让 AI 先总结前面的 PRD 和方案要点用精简版上下文继续推进。5.4 什么时候不该用 superpowers实事求是地说不是所有任务都适合走这套流程。我总结了几类场景建议你绕开一行代码能搞定的修改比如改个文案、调个参数。走 superpowers 全流程纯属浪费 token。明确边界的算法实现比如“写一个函数计算最长公共子序列”。这种情况直接给要求就行。探索性任务比如“帮我看一下这个报错是什么意思”。这种任务需要的是即时反馈不是结构化流程。涉及高度交互的实验比如“临时试试某种写法”。TDD 和严格计划在这里只会拖后腿。我的原则是把 superpowers 当成重型武器只在值得投入的多文件、多步骤、高复杂度任务中使用。日常小任务直接裸奔反而效率更高。这不是说 superpowers 不好而是说工具要和场景匹配。6. 从用 skill 到写 skill把这个思路变成自己的6.1 一个 skill 的本质就是一份“带模板的工作方法”用了一段时间 superpowers 之后我开始琢磨自己写技能。打开它的技能文件看结构发现门槛比想象中低——一个SKILL.md文件核心就是描述清楚三件事我是什么、什么时候用我、我怎么做。“我是什么”写在文件开头给一段不超过几句的功能描述方便模型快速判断这个技能是否匹配当前任务。“什么时候用我”写在 description 里说明适用场景和边界。而“我怎么做”是正文主体把工作流程拆成步骤每一步有明确的输入、动作和输出。听起来很普通但真正写起来才会发现这实际上是在倒逼你把“自己怎么做事的”想清楚。我写第一个自定义 skill 是“代码 review checklist”把我平时 review 代码关注的要点全部列了进去安全、性能、可读性、边界条件、命名规范、测试覆盖。以前这些要点存在我脑子里现在它们变成了一份结构化的技能文件AI 替我去执行。6.2 把团队规范沉淀为多个独立技能如果你在带一个小团队或者经常和 AI 协作做项目我强烈建议做一个动作把你团队的规范、最佳实践和常犯错误整理成一组自定义技能。这样每次 AI 进入项目时都能用统一的工作方式输出质量下限会被拉得很高。我们团队的技能列表现在已经不止 superpowers 了还包括前端代码规范技能规定组件组织方式、状态管理选型、样式方案。接口设计技能规定 RESTful 风格、错误码规范、接口文档格式。数据库迁移技能规定迁移脚本的写法、回滚要求、上线检查事项。每个技能都是独立的 Skill 文件AI 根据任务自动加载互相不干扰。这种做法带来的好处是即使是新同学操作 AI 完成开发任务产出的代码风格和架构选择也能保持团队水准不会因为“同学 A 的 Prompt 写得好、同学 B 写得差”而出现巨大质量差异。6.3 我的扩展心得先建立执行检查再优化执行速度最后分享一个我折腾技能文件的心得先保证 AI 每一步都做对再考虑让它少做几步。我见过不少人嫌 superpowers 流程长擅自删减步骤结果又回到“AI 瞎猜代码”的老路上。我的建议是第一二次使用先完完整整跑一遍标准流程感受每个技能的产出物到底有什么价值。当你对整个流程有感觉之后再根据自己的项目类型做减法。比如小型工具项目可以跳过完整的 plan只保留 brainstorming 和 TDDAPI 服务项目则可以砍掉部分文档环节把重点放在接口设计和测试上。我最近在做的是把我这两年的 AI 协作经验整理成几个内部技能。这个过程本身也很有意思——你需要非常清晰地把“好习惯”写成一二三步模型才能照着做。而当你真的写出来之后你会发现这些技能不仅对 AI 有用对新人培训也特别有价值。