superpowers实战：让AI编码工具从裸奔到工程化交付

说实话在接触“superpowers”之前我一直觉得给 AI 编码工具讲“工程规范”是一种徒劳。彼时的日常是让 Codex 帮我修一个回调嵌套的报错它秒回了“看起来是这里的闭包捕获问题”改完本地跑测试确实也过了但三个小时后线上监控告诉我另一个函数被它顺手改没了。这种“单点能干、整体翻车”的体验恐怕每一个重度用过 AI 编码助手的人都懂。于是当我看到 superpowers 这个项目在社区里被反复提起时我的第一反应是到底是什么东西能让一群工程师愿意把 AI 工具的使用教程当“武功秘籍”来传带着这个疑问我前后用了差不多一周时间把它在 Codex CLI 和 trae 工作台两条路上都跑了一遍。这篇文章不是官方文档翻译而是我从“裸 Codex”切到“装上 superpowers 技能包”之后对这件事的完整记录包括安装路径、真实任务表现、三次踩坑闭环以及我最后沉淀出的几条使用纪律。1. 给 AI 配“外挂”之前先认清裸 Codex 的真实短板能答题但交不了货1.1 我印象最深的一次“完成式翻车”事情发生在一个很普通的下午。我需要把一个 Python 服务里的 Redis 连接池从单例模式改成按租户隔离改动量不大但牵扯到十几个调用点。我当时的操作方式是直接把需求贴给 Codex“把 redis_pool 改成按租户维度创建所有 get_redis_connection 的调用都调整好。”它很快给出了一版完整的 diff所有调用点确实都改了我当时觉得效率真高直接提交、合并、部署。结果第二天早上租户 A 的请求里混进了租户 B 的数据。原因并不复杂Codex 在改get_redis_connection的时候只改了函数的签名但缓存 key 的拼接逻辑它没动导致多个租户复用了同一个连接前缀。它把“签名层面的改动”完成了却没有理解“按租户隔离”这件事的真正含义是数据隔离而不是连接对象隔离。这种问题不是模型笨而是任务定义和验证方式出了问题。我给了它一个动作指令但没有给它一个完整的、包含约束和验收标准的任务描述。1.2 工程化流程缺失是 AI 编码最大的隐性成本后来我把这类问题复盘了几次发现一个共性裸 Codex 适合回答“怎么改”但不太擅长接手“一个完整的小型工程任务”。工程世界里真正可靠的工作流是需求澄清、方案设计、任务拆分、测试先行、代码审查、回归验证这一整套链路。你让一个刚入职的实习生改代码也会跟他说“先看上下文再写测试最后再提交”但你把同样的话塞给 AI它只会当成背景噪音然后急着输出代码。这就是 superpowers 想解决的原始问题。它不追求把模型换成另一个模型也不追求一次性修掉所有代码生成错误而是把工程师日常工作的流程、规范和验证方法写成一套结构化的“技能文档”。当 AI 接到任务时它不再直接生成代码而是被引导着去经历一个完整的工程流程理解问题、确认边界、写出失败测试、再动手实现、最后自查。听起来很基础但对 AI 编码来说这一步差了十万八千里。我自己的体感是裸 Codex 就像一个极聪明但极度缺乏耐心的外包工程师你给什么指令它做什么做完就交差绝不主动多问一句superpowers 的思路则是把“外包工程师”改造成“团队里的正式员工”用一套流程文档让它先思考、再动手、自检后交付。如果你只在脚本里修一两个小 bug这套流程确实显得笨重可一旦面对真实业务里的跨文件改动、依赖升级、接口迁移有没有这套流程结果完全是两个质量级别。2. 拆开 superpowers 的设计骨架技能卡片、渐进披露与群体子代理2.1 为什么是 Markdown让 AI“读说明书”而不是执行黑盒插件我第一次看到 superpowers 的仓库结构时有点意外——它没有编译好的二进制也不是一个需要安装的运行时主体内容就是大量的 Markdown 文件。这些文件按领域分门别类比如编码、协作、子代理、评审、依赖升级等每个文件夹里都有类似SKILL.md这样的入口文件里面写着这个技能的目标、触发条件、执行步骤、输入输出要求和注意事项。这个设计最初让我觉得太“朴素”了但用久了才理解它的聪明之处。AI 模型本身是基于文本推理的你把流程写在代码里它反而看不见你把流程写在 Markdown 里它读取上下文的时候就能直接“读到说明书”并且按照说明书一步步执行。这相当于你面对一个持证但没经验的新人与其塞给他一个复杂的内部系统不如直接在工位上贴一张流程图让他照着走。而且 Markdown 对人类也友好。团队里任何一个人都能打开技能文档阅读、修改、补充不需要懂插件开发不需要编译部署。我后来把团队自己的代码规范、发布检查单也写成了同类文档AI 读取的积极性和效果比我之前在提示词里贴一大段规则好得多。原因不难理解独立的技能文件意味着独立的上下文AI 在需要时才去读而不是在整个对话里背负着几千字规范读到后面早就忘了前面。2.2 渐进式披露控制上下文膨胀的关键继续说刚才那个点。如果你把一份 5000 字的工程规范直接写进系统提示词模型不是读不懂而是注意力会被稀释。它处理长文本时天然会更关注前后两端的部分藏在中间的规则很容易被忽略。superpowers 用的方式叫“渐进式披露”平时只给 AI 一个技能目录索引相当于告诉它“你手边有哪些说明书、分别讲什么”等它接到具体任务再按需去读取对应的完整文档。打个比方你入职一家新公司HR 不会第一天就把全部制度手册塞给你而是先给你一份员工手册目录等你要报销了才去翻报销流程那一章。AI 也是一样任务如果是“给 API 写接口文档”它只需要读文档生成相关的技能不需要把“如何重构数据库迁移脚本”的完整流程也加载进上下文。这种机制既省 token又提高了指令的命中率。我实际观察 Codex 在加载技能后的行为时发现它的思考过程会明显多出一些“中间步骤”比如先输出“我找到了编码流程文档先按计划阶段执行”然后才开始拆解需求。这种变化不是模型变聪明了而是它的工作记忆不再被无关规则占用能更专注地执行当前最该做的事。2.3 子代理与“群体模式”并行协作的代价与收益superpowers 里还有一类比较进阶的设计子代理subagent和群体模式。简单说当一个任务足够大时主代理可以拆出多个子代理分别负责不同环节比如一个子代理做代码实现另一个子代理同时做代码评审再有一个子代理专门跑测试验证。它们之间通过一种类似消息传递的方式交换结果最后由主代理汇总。这套机制听起来很酷但它不是银弹。我自己的实际经验是任务越复杂、拆分越清晰群体模式的价值越大但如果任务本身只涉及一个文件里的 50 行改动强行走“多代理并行”反而会带来额外的调度开销和上下文切换成本。后面我专门有一节会讲我踩到的一次多代理协同卡死问题这里先给结论子代理适合“并行评审”和“独立模块实现”不适合“强依赖顺序的任务”。3. Codex CLI 安装 superpowers 的完整实操从目录规划到首次验证3.1 安装前的三个前置判断在动手之前建议先做三个判断能省掉后面很多麻烦。第一确认你的 Codex CLI 版本。superpowers 这类技能包对 CLI 的版本有一定要求因为技能文件依赖模型读取项目文档的能力太老的版本可能连自定义指令文件都不认。我的建议是用最新稳定版别用 beta。第二想清楚技能包要装在哪里。装在当前项目目录好处是只对当前项目生效适合公司代码库有严格隔离要求的场景装到用户级目录比如~/.codex好处是全局生效所有项目都能用。我个人推荐先做全局安装再在具体项目里按需覆盖这样体验最平滑。第三确认你的模型上下文窗口够大。虽然 superpowers 用了渐进式披露但技能索引和任务分析依然会占用一部分 token。如果你用的是小上下文窗口的模型跑复杂任务时容易中途“失忆”。至少要用中高端模型并且把单次任务控制在合理范围内。3.2 落地目录与 AGENTS.md 钩子的配置安装本身不复杂核心是把技能包克隆到本地然后让 Codex 知道它存在。我当时采用的目录结构大致是这样~/.codex/ ├── AGENTS.md └── superpowers/ ├── skills/ │ ├── coding/ │ │ ├── plan-first/ │ │ │ └── SKILL.md │ │ └── test-before/ │ │ ├── SKILL.md │ │ └── examples/ └── README.md先说 AGENTS.md 这个文件它是 Codex 读取的全局指令入口。我之前一直忽略它的价值直到这次才意识到它就是连接项目与技能包的“钩子”。我在~/.codex/AGENTS.md里写的是这样一段话本环境已启用 superpowers 技能包。 技能包根目录~/.codex/superpowers。 执行任何编码任务前请先查看 skills/coding 下的相关流程文档 涉及协作或评审时请查看 skills/agency 下的子代理说明。这段话的作用不是让 AI 把所有技能都读一遍而是给它一个“起始索引”。它看到 AGENTS.md 之后会知道有这么一个技能包存在以及触发什么条件时该去翻哪份文档。这一步做对了后面任务执行才会出现“先规划、再动手”的行为变化。3.3 用一条包含验收标准的最小任务做验证装完之后别急着上大任务先跑一个最小的验证任务。我的经验是这个任务不能是“写一个 hello world”因为 hello world 根本触发不了任何工程流程。也不要一开始就让它重构整个模块因为一旦翻车你很难判断是技能没加载还是任务本身的问题。我当时用的验证任务是“在项目里新增一个带单元测试的 URL 解析工具函数输入为 URL 字符串输出为协议、域名、路径三个字段的字典要求包含异常处理。”这个任务足够小但包含实现、测试、异常处理三个环节能逼着 AI 走一遍完整流程。验证时重点观察两点第一AI 在写代码前有没有输出“读取技能文档”或“按计划执行”之类的中间说明第二AI 有没有主动写测试而不只是实现功能。如果这两点都出现说明技能包已经生效。3.4 已验证的常见安装陷阱安装过程中最容易翻车的三个点我提前说一下。一是路径写错。很多人喜欢把技能包放到带空格的目录比如D:\My Files\superpowers结果 AI 读取时路径解析失败。官方文档当然支持转义但何必给自己添堵呢路径里不要有空格和中文字符。二是 AGENTS.md 命名不匹配。Codex 认的是AGENTS.mdClaude Code 认的是CLAUDE.md如果你在多个工具之间共用技能包一定要确认该建哪个文件。我一开始在 Codex 的全局目录里放了CLAUDE.md结果 Codex 完全没反应排查了半小时才发现是文件名不对。三是版本回退。有些技能包更新后依赖了新的 AGENTS.md 写法但你的 Codex CLI 版本没跟上导致钩子失效。所以每次拉取新的技能包之前顺手把 CLI 也更新一下能省不少事。4. 把 superpowers 接进 trae 工作台另一个 AI 工具的集成思路4.1 trae 工作台为什么需要同样的技能机制如果你用过 trae 工作台就知道它本质上是一个把 IDE、AI 助手、自动化任务编排在一起的开发环境。它的 AI 能力和 Codex 类似同样面临“会答问题但不会主动走工程流程”的问题。社区里常见的热搜词“trae work cn 安装 superpowers skill”说的就是用户想在这个工作台里也装上同一套技能机制让 AI 从“随手生成代码”变成“按流程完成任务”。我的观点是这个需求很合理。技能包的核心价值不绑定某个特定 CLI它只是一堆 Markdown 流程文档任何支持指令文件读取的 AI 工具都能复用。trae 工作台只要能让 AI 读取项目级或用户级的说明文件就等于具备接入 superpowers 的基础条件。4.2 集成方案对比与推荐路径我在 trae 工作台里尝试过两种接入方式简单对比一下。第一种是把技能包克隆到项目目录里然后在项目的指令文件里写钩子。优点是隔离性好这个项目单独引入技能包不会影响其他项目缺点是你得在每个想用的项目里重复配置养成习惯之后还行但初期的复制粘贴成本比较高。第二种是在工作台的用户级配置目录里放一份全局技能包然后在全局指令文件里声明钩子。优点是一次配置、处处生效所有在 trae 工作台开的项目都能自动享受到流程约束缺点是如果你同时维护好几个差异很大的项目通用的技能规则偶尔会显得不够贴切。我最终采用的是第二种但在具体项目里用项目的指令文件覆盖了部分规则。举个例子全局技能包默认要求所有代码改动必须配测试但工具链项目里有一些一次性脚本本来就不需要长期维护的测试用例这时候我会在项目指令文件里补充一条豁免说明让 AI 识别到“该目录为 scripts 工具目录不做强制测试要求”。这样既保留了流程约束的通用性又不会因为规则太死板而影响效率。4.3 双工具共用技能库的同步问题还有一个很实际的问题如果你同时使用 Codex CLI 和 trae 工作台技能包是各放一份还是共用一份我建议共用一份但要解决同步问题。最简单的方式是把技能包放在一个独立目录比如~/dev/superpowers然后在 Codex 的~/.codex/AGENTS.md和 trae 工作台的全局指令文件里都引用这个绝对路径。这样你更新一次技能包两个工具都能用到最新版本不会出现“Codex 里已经改了流程trae 里还是旧规则”的错位。不过要注意共用路径有个前提两个工具运行时的用户权限一致。如果你在 trae 工作台里用的服务账号和命令行用户不是同一个可能因为权限读不到技能文件。我自己就遇到过 trae 工作台因为沙箱权限问题读不到用户主目录下的技能包最后只能把技能包再复制一份到项目目录里。5. 实测记录让我处理的三件真实任务superpowers 把过程改成了什么样5.1 任务一重构一份 400 行 Python 数据处理脚本我挑了一个真实的历史包袱一份 400 行的 Python 脚本主要功能是清洗导入的 Excel 数据逻辑里塞了大量 if-else变量命名混乱还有两处明显的重复代码段。以前这种任务我是不敢全权交给裸 Codex 的因为它很可能只做表面重构把行数缩下去但语义改成另一套行为。在用 superpowers 之后它的处理路径明显不同。它先输出了一段“任务分析与技术方案”拆出了三个子任务数据清洗逻辑抽取、重复代码合并、错误处理统一。然后它没有直接动手而是先写了一个用来验证行为等价的最小测试集再开始重构。最终输出的代码量虽然没有大幅缩减但结构清晰了很多而且测试全绿。这个过程中最让我满意的地方是它没有自作主张改变任何对外行为所有的重构都是在我确认了“行为保持一致”的目标下进行的。5.2 任务二跨端新增会员积分查询接口第二个任务更接近日常业务开发在已有的 Web 服务里新增一个会员积分查询接口同时需要改前端页面把积分展示出来。这个过程涉及后端路由、数据库查询、前端 API 调用、页面渲染四个环节任何一环漏掉功能都交付不了。裸 Codex 遇到这类任务时容易出现“后端写得完整前端调用模块忘了改”或者反过来。superpowers 的流程化处理在这里起了作用。我观察到的执行顺序是先列接口设计再确认数据库字段然后同时拆出后端实现、前端联调、测试验证三个子任务最后汇总成一份改动清单。整个过程中间它甚至还自己停下来问我积分字段在旧表里叫point还是points这种主动澄清在之前很少见。5.3 任务三升级依赖并处理破坏性变更第三个任务是最折磨人的把一个内部 SDK 从 2.x 升级到 3.x其中有两个公开方法改了签名一个配置项被移除。这类任务最怕 AI 直接全局搜索替换然后留下一堆编译错误。用 superpowers 跑下来的流程是先读取依赖升级相关的技能文档了解推荐的逐步升级策略然后列出所有调用点接着逐个评估签名变更影响最后才修改代码并运行测试。虽然整体耗时比裸 Codex 直接干要长但几乎没有返工一次通过。这个对比让我彻底接受了“慢一点但不出错”的理念。5.4 耗时、token 与返工次数对照我简单做了一个不严谨的对比记录数据仅供感受趋势任务裸 Codex 耗时superpowers 耗时裸 Codex 返工次数superpowers 返工次数印象中的 token 消耗重构 Python 脚本12 分钟25 分钟2 次0 次高约 50%跨端新增接口30 分钟40 分钟3 次1 次高约 30%依赖升级35 分钟50 分钟4 次0 次高约 60%看出来了吗时间变长了token 消耗变多了但返工次数大幅下降。在业务代码里“返工”的代价远远不止时间成本还包括你从上下文里重新捡回思路、重新定位问题、重新部署验证的整个过程。所以我后来对团队的判断标准很简单如果你更在意最终交付质量而不是聊天框里那几秒钟的“首 token 延迟”superpowers 带来的稳定性是值得的。6. 三次翻车的排查链路装上了不代表就生效6.1 故障一技能被完全无视AI 依然裸奔第一次跑任务时我全程盯着输出期望看到“读取技能文档”之类的迹象结果什么都没有。它直接开始写代码行为跟没装技能包时一模一样。我第一反应是 AGENTS.md 没被读取于是按这个方向排查。我先确认了 AGENTS.md 文件的位置和命名没问题。然后又检查了文件内容里有没有写错路径也没问题。最后我尝试在对话里直接问 AI“我们的环境里配置了哪些技能文档”它的回答暴露了真相——它根本没读取到那个全局配置。进一步排查后发现Codex 的全局指令文件在最新版里改名为AGENTS.md但我之前创建的是旧格式文件.codex/instructions.md两者完全没有被合并。删掉旧文件、重建正确命名的文件之后问题才解决。6.2 故障二技能文档和项目实际约束互踩第二次翻车更有意思。superpowers 的流程文档里明确要求“所有外部依赖必须有版本锁定”但我手上那个项目是个历史遗留系统好几个依赖一直没锁版本当前跑通纯靠运气。AI 严格执行了技能文档准备把一整套依赖规范化这完全偏离了我的交付目标。这一下让我意识到技能包是通用规则不等于每个项目的现实约束。解决方式是我在项目指令文件里加了一段覆盖声明“本项目为遗留系统暂不执行依赖版本锁定规则相关问题需先向项目负责人确认。”AI 在下一次执行时先查看了项目指令优先采用了项目级规则绕开了技能包里的默认约束。这件事给我的经验是技能包给 AI 的是一套“最佳实践”但你必须在项目层给 AI 留一个“例外出口”否则它会一本正经地给你制造大量新问题。6.3 故障三多代理协同卡死反馈延迟拖出了天际第三次踩坑发生在子代理模式。我给一个中型任务开了多代理并行预期是主代理拆分任务后子代理同时工作最后并行汇总。但实际跑起来的时候主代理一直在等待一个子代理的返回而那个子代理又因为要依赖另一个子代理的输出而阻塞了形成了一个循环等待。我盯着终端看了快十分钟进度条一动不动最后只能强制中断改用单代理模式重新跑十几分钟就搞定了。经验教训是多代理并行适合“任务可以真正独立拆分”的场景一旦子任务之间存在依赖关系就必须在主代理层面明确执行顺序否则协作本身会成为瓶颈。我后来在技能文档里加了一条规定使用多代理模式之前必须先判断子任务之间是否存在依赖关系存在则串行执行。7. 高阶玩法与我的日常使用纪律把技能包用成团队规范7.1 第一课给任务写“需求文档”而不是“动作清单”很多人在用 AI 编码工具时习惯下指令“把某处的函数名改成 XX”“给某接口加一个参数”。这种动作清单式的指令只会让 AI 变成高级补全工具。superpowers 的完整流程只有在任务描述足够清晰的时候才能发挥最大价值。我现在的习惯是给 AI 一个目标、几个约束、一组验收标准而不是具体动作。比如我会写“目标是让会员积分在订单详情页可见约束是不改动现有订单接口的返回结构验收标准是前端能拿到积分字段并在页面展示。”剩下的方案设计、代码实现、测试覆盖由 AI 在技能流程的引导下自己完成。这个转变是我这一周最大的心得也是技能包真正“生效”的前提。7.2 第二课沉淀自己的私有技能卡用习惯了之后我不再满足于 superpowers 自带的那套通用技能开始把团队内部的高频操作也写成技能卡。比如我们有一个固定的发版流程涉及版本号更新、构建产物校验、发布说明生成以前每次都是人工提醒现在我把完整流程写成了技能文档放进技能包AI 接到“发版”类任务时就会自动按流程执行。这种自定义技能卡的价值在于它把团队的隐性知识显性化了。任何一个新成员加入不需要有人口口相传AI 就已经懂了一半规矩。就算哪一天不依赖 AI 了这套文档本身也是一份很好的团队知识库。7.3 第三课学会给 AI 卸担子关闭完整流程最后说点反直觉的。superpowers 不是所有场景下都应该开着的。如果是“帮我解释一下这段正则是什么意思”或者“这段代码里有没有明显的内存泄漏”这类问答型任务走完整流程既浪费 token也没必要。我现在的做法是给技能包加了一个轻量模式遇到明显属于“解释、问答、单点分析”类的请求AI 直接回答不触发冗长的任务规划。这个轻量模式是我自己在技能文档里加的约束效果是日常问答响应更快同时涉及“改动代码”“跨文件修改”“依赖升级”这些触碰真实生产逻辑的任务时流程照旧。让 AI 知道什么时候该走流程、什么时候该直接回答才算是把技能包真正用熟了。我在实际项目里最后留下的配置其实非常简单一份全局 AGENTS.md、一份按需读取的技能目录、再加上来自项目层的少数例外规则。真正改变 AI 行为的不是文档数量而是你愿意让它在动手前多想几步。装完 superpowers 后第一次运行复杂任务看到它在写代码之前先停下来列方案你可能会觉得不习惯甚至觉得它变慢了。但经历过几次“它能一次性交付而不需要你在后面跟着擦屁股”之后你就明白这种停顿感才是高质量的来源。