说实话第一次看到“superpowers”这个词出现在开发者工具的分类里时我愣了一下。超级英雄电影看多了的人第一反应都是那种发个光、飞个天的能力。但等你真正把这套东西装进你的 AI 编程助手比如 Codex CLI、Claude Code 这类工具里你会发现这个名字起得一点儿都不夸张——它确实能让原本只会“回答问题”的 AI突然变得像一个有工程素养的结对程序员。这篇文章我会从项目定位、设计思路、安装配置、真实项目实战到踩坑记录完整拆一遍这位“superpowers”保证你看完就能直接上手用。这个项目本质上是一组精心设计的技能包不是什么重型框架也不需要你改多少业务代码。它的核心价值在于把软件开发中最容易被 AI 忽略的“流程纪律”给补上了。很多人都有这种体验——AI 写代码很猛但让它从一个空目录开始独立完成一个功能模块时它经常东一榔头西一棒子写到一半忘了最初的目标甚至自作主张改了接口设计。superpowers 解决的就是这个问题它适合所有正在用 AI 辅助写代码的开发者尤其是那些想把 AI 从“问答工具”升级成“项目协作者”的人。1. superpowers 是什么先搞懂它在解决什么问题1.1 项目定位与核心痛点先聊一个几乎所有 AI 编程用户都会遇到的场景。你让 AI“帮我写一个用户注册接口”它啪一下给你生成了一堆代码看起来五脏俱全。但等你真的拿去用发现问题一大堆没有参数校验、异常处理只写了个 catch 没写日志、数据库字段和实体类对不上、连单元测试都没有。你让 AI 修它就局部打补丁修完这个又坏了那个最后你不得不自己撸起袖子重写。这个问题的根源不是 AI 不够聪明而是它缺少一套“工程方法论”。人类程序员之所以靠谱是因为我们脑子里有流程先理解需求再梳理边界然后设计接口接着写实现最后补测试、做自查。AI 默认没有这套流程你问什么它答什么它的“默认行为”是省事、直接给结果。superpowers 做的事情就是把这套流程以技能skills的形式装进 AI 的工作记忆里让它在动手之前先思考在写码之后先自查。项目本身是一套开源的能力增强包包含大量 Markdown 格式的技能文件和一个入口配置文档。它的工作方式非常朴素当你把技能文件放进 AI 编程助手指定目录并且让助手启动时读取入口文档后AI 就会被“引导”出一套更成熟的协作方式——它会在接到复杂任务时主动拆解步骤会先问清需求再动手会在写完代码后按清单自查。用技术圈的话说这不是给 AI 加“算力”而是给 AI 加“习惯”。1.2 适用场景与目标用户我自己用下来的体会是这套东西最适合三类人。第一类是“AI 重度用户”每天都在用 Codex CLI 或同类工具写代码但总觉得产出质量不稳定有时很好有时很糟那么 superpowers 能显著拉高你的“下限”。第二类是“项目维护者”你维护的代码库有多人协作想让 AI 帮忙改代码但又怕它乱改superpowers 里关于计划、约束、自检的技能能让 AI 的行为更可控。第三类是“想转型 AI 工程化的技术管理者”你可以把它当成一个范例看看如何把团队的开发规范、编码约定“固化”成 AI 能读懂、能执行的技能包。不过也要泼一盆冷水它不是银弹。如果你的 AI 编程助手本身连基本代码生成都做不好或者你对代码架构一无所知那装上 superpowers 也不会一夜之间变成架构师。它的定位是“放大器”——把你已有的开发纪律放大到 AI 身上。你的工程能力越强用它就越能感受到什么叫“如虎添翼”。2. 核心设计拆解为什么一组 Markdown 技能就能改变协作质量2.1 设计哲学把工程方法论固化进技能很多人第一次看到 superpowers 的文件结构时都会有点懵这不就是一堆 .md 文件吗对但这不是普通的文档它们是“可执行的方法论”。每个技能文件都有固定的格式包含名称、描述、触发条件和具体操作步骤。AI 编程助手启动时会读取这些文件把它们当成“额外的系统提示词”来理解自己该怎么做事情。这里的关键设计在于“描述”和“触发”的写法。比如一个叫“编写实施计划”的技能它的描述不会写“帮助用户写计划”而是写“当任务涉及多个文件修改、接口设计或架构决策时应当先输出一份实施计划并获得用户确认”。这样 AI 在遇到具体场景时会依据描述自动匹配到对应技能然后按照里面的步骤执行任务。整个过程不需要你在每次对话里重复强调“先做计划”技能机制会自动触发。我觉得这套设计最聪明的地方是把“不确定性”变成了“确定性”。平时跟 AI 对话它的行为有很大随机性同一个问题问两遍可能得到两套方案。但技能文件几乎是半固定地注入了 AI 的“工作记忆”只要触发条件满足它就会走固定的流程。这就像给新员工发了一本非常详细的操作手册而不是指望他每次都能随机应变。对于工程协作来说“稳定”比“惊艳”更重要。2.2 关键技能逐个看从头脑风暴到测试驱动superpowers 里最有价值的技能我抽几个典型说说。第一个是“澄清问题”——它会让 AI 在接受任务后、动手之前先向你提出关键问题。比如你要它做“报表导出”它会追问导出的数据量级多大超时怎么处理需要支持哪些格式这些问题如果放到开发后期才发现改造成本极高但 AI 现在会在开头就帮你把边界探明。第二个是“头脑风暴”。这个技能允许 AI 在动手写代码前生成多个备选方案比较各自的优劣再让你选择。我在一个订单系统的重构里用过原本我脑子里只有一个方案AI 直接给出三条路径最小改动方案、渐进式迁移方案、彻底重写方案并且列出了各自的成本、风险和依赖关系。这种感觉就像身边坐了一个资深同事你可以跟他充分讨论而不是被 AI 直接拽着走。第三个是“测试驱动开发”。这个技能不是说让 AI 写几个单元测试就完事而是让它严格遵循“红-绿-重构”的节奏先写一个失败的测试再写让测试通过的实现最后重构代码保持整洁。实测下来AI 在这种模式下生成的代码质量确实高不少因为测试先行把接口契约锁死了AI 自己也没办法“跑偏”。如果你配合 Codex 这类工具使用效果更明显它相当于给打野的 AI 装了一套固定的刷野路线。2.3 与内置系统提示词的本质区别有人会问现在的 AI 编程助手本身就有很强的系统提示词里面也写了“你要逐步思考、你要先理解需求”这和 superpowers 的技能有什么区别我自己对比过区别非常大。内置提示词是“通用建议”它试图覆盖所有场景所以颗粒度很粗AI 模型往往“注意不到”或者“选择性忽略”某一条。而 superpowers 的技能文件是“针对性指令”它把一类任务拆成了可以按图索骥的操作清单并且通过描述与触发机制让 AI 在特定时刻精确调用。用个不太严谨但好懂的类比内置提示词像是新员工入职时看的那本《公司规章制度》里面什么都写了但什么都记不住superpowers 则像是为每个岗位定制的《操作 SOP》你只要照着做就行。实际上为了让 AI 不忽略这些技能文件里还会刻意使用“应当”“必须”这样的强约束词同时在入口文档中指定调用策略。这套机制叠加在一起才真正改变了 AI 的工作习惯。3. 安装与配置从零开始把 superpowers 跑起来3.1 环境准备与仓库获取先明确一下superpowers 本身不依赖特定的 AI 模型或特定操作系统它的载体是通用的技能文件所以 Windows、macOS、Linux 都能用。你需要准备的只有一个一个支持“技能/指令目录”机制的 AI 编程助手比如 Codex CLI 或 Claude Code。我用的是 Codex 场景下文会一并说明。安装的第一步是获取 superpowers 的文件。在 GitHub 上搜索“superpowers”就能找到对应的仓库你可以在自己的项目目录外找一个固定位置放它比如~/superpowers。我自己的习惯是直接 clone 到用户目录下这样既不影响项目仓库的整洁又能在多个项目里复用。如果你只想小范围尝试也可以直接下载仓库里skills文件夹里你感兴趣的那几个技能文件不用整套全上。需要注意这跟我平时装一个 npm 包完全不同没有 lockfile没有依赖安装。你要做的只是把文件放到该放的位置然后让 AI 知道去哪里读它们。正因为机制简单它出问题的概率也低不会出现什么“依赖冲突”。唯一要小心的是别把仓库 clone 到项目根目录里否则版本管理会很难受。3.2 配置 Codex 与标准流程现在说说主流路线——在 Codex 环境里启用 superpowers。Codex 认可 AGENTS.md 这种项目级说明文件同时也支持从外部目录读取技能包。我采用的方案是在~/.codex/AGENTS.md这个全局说明文件里用一段话告诉 Codex“启动时额外读取/Users/你的用户名/superpowers目录下的技能文件”让它把这些内容当作操作规范来遵守。具体来说我会在 AGENTS.md 里这样写# 全局协作规范 ## 技能加载 - 每次会话开始先扫描 ~/superpowers/skills 目录了解当前可用的技能集合。 - 当任务满足某个技能的触发条件时必须严格遵循该技能文件中描述的步骤执行。 - 重点技能头脑风暴brainstorming、澄清问题clarifying、编写实施计划implementation_plan、测试驱动开发tdd、自查复盘review。这段配置的作用是让 Codex 在没有项目级 AGENTS.md 时也有一套默认的协作规则。配置完后你可以打开一个新的 Codex 会话随便问一句“根据我当前项目的结构列举你可以帮我做的事”如果助手在回答里提到了“我可以先进行需求澄清、再制定实施计划”等字眼说明技能已经被加载了。下一步把它用在真实项目里。3.3 针对具体项目启用技能全局配置只是第一步对不同的项目你可能还要微调。比如当一个 Java 项目连着用了 Maven、Spring Boot、MyBatis你希望 AI 在改动时始终遵循项目现有的分层结构那优先做的是在项目的AGENTS.md里写明项目背景和约定然后再让 superpowers 的技能基于这个背景发挥。我一般会在项目级AGENTS.md里加一段“项目技术栈与约束”比如# 项目约束 - 这是一个 Java 17 Maven 的多模块项目模块间依赖通过 dependencyManagement 管理。 - 新增代码必须遵循现有的 controller - service - mapper 分层禁止在 controller 里直接写 SQL。 - 单元测试必须使用 JUnit 5且测试类命名以 Test 结尾。 - 任何改动不得破坏现有 API 兼容性除非在实施计划中明确说明并获用户确认。这段内容与 superpowers 的技能文件会形成“112”的效果技能告诉 AI 该用什么流程项目说明告诉 AI 该遵守什么约束。因为项目级 AGENTS.md 的优先级高于全局配置每个项目都可以有一套自己的规矩。实测下来这招对大型老项目尤其好用AI 再也不会给你随手生成一套风格完全不同的代码了。4. 在真实项目里用起来以 Java 后端为例完全解析4.1 需求场景设定与第一步操作先用一个我最近真实做过的需求来说为一个订单服务增加“批量导出对账单”的接口。原始需求只有一句话“支持按月份导出对账单Excel 格式”但这句话背后全是坑数据量可能几十万、导出过程不能阻塞主线程、Excel 格式需要符合财务要求。如果没有 superpowersAI 大概率直接生成一个同步查询数据库然后返回文件流的控制器用完就炸。启用 superpowers 后我在 Codex 里输入“帮我在订单模块新增批量导出对账单功能具体要求见需求文档请按我们约定的流程执行。”AI 不是直接开写而是先触发了“澄清问题”技能。它一口气问了六个问题导出的字段范围是否包含退款记录时间边界是自然月还是自定义区间并发导出上限是多少文件生成后是存本地还是上传 OSS失败任务如何重试是否需要操作审计日志我当时心里一喜这些问题每一刀都切在要害上。后面在写“实施计划”时AI 给出了一个分四步的方案包括开发异步任务、用 EasyExcel 写分批查询、引入带超时控制的线程池、补一个查询接口用来下载生成好的文件。这个计划还专门标注了每一部需要修改的类名和涉及到的既有接口。整个过程就像有一个经验丰富的老后端在跟你做技术方案评审而不是一个闷头干活的代码生成器。4.2 测试驱动开发的实际落地方案确认后我要求 AI“严格按照 TDD 技能实现”。你可能好奇AI 真的会老老实实先写失败测试吗在 superpowers 的强约束下它会。它的做法是这样的先为异步任务调度器写测试断言在任务提交后能正确路由到指定的执行器这时实现类还不存在测试自然是红的接着创建极简实现让测试变绿最后再重构优化。最有价值的是它连“性能边界测试”都考虑到了。它写了一个测试模拟 10 万条订单数据的分批查询逻辑断言单批查询不超过 5000 条、内存峰值不超 200MB。这个测试一开始是失败的因为最初的实现用了全量查询。于是 AI 自己调整了实现改用游标方式分批拉取并用流式处理写入 Excel。一轮红绿重构下来我几乎没有手动改一行代码。这一部分的体验比我自己手写 TDD 还要严格。当然AI 生成的测试也不是闭眼就信。我会快速扫一眼重点关注是否有断言、是否有边界数据以及测试之间是否互相依赖。整体框架相对规范但测试数据里偶尔会出现“硬编码一个日期”的偷懒做法我会让它改成相对今天动态计算。这就是 superpowers 给你留出来的空间它把 AI 的产出提升到了工业级而你只需要做代码评审而不是从零开始帮你擦屁股。4.3 接线、接口设计与前后端联调导出接口不同于普通 JSON 接口它涉及异步任务、文件状态查询和最终文件下载三个链路。superpowers 里的“实施计划”技能会明确要求 AI 先输出接口设计草稿包括路径、请求参数、响应体结构再进入编码。在响应体设计上AI 给了一个很专业的方案提交导出任务返回taskId轮询状态接口返回pending/running/success/failed成功后返回下载 URL 和文件过期时间。这种设计省去了我后期不少麻烦。实际开发中AI 用后端框架的异步方法实现了任务提交用数据库表记录任务状态下载接口做了本地文件存在性校验。前端拿这套接口联调也非常顺因为它一开始就把各种边界状态都设计好了。如果你自己写过这种异步导入导出功能你一定会认同这类功能最怕的就是“半吊子接口”——提交完傻等、失败了没提示、下载没鉴权。有了流程约束AI 把这些细节都当成“必须项”而不是“可选项”来处理了。我这里给一个通用的实操建议在使用 superpowers 的时候不要急着让它一步到位。宁可多花两分钟在“澄清问题”和“制定计划”阶段也不要让 AI 直接进入编码。磨刀不误砍柴工这句话在 AI 协作场景下被体现得淋漓尽致。5. 踩坑记录常见问题与排查实战速查5.1 技能没生效配置路径与书写方式踩坑我最开始用 superpowers 时遇到的第一大坑就是“AI 完全无视技能文件”。打开会话问它“你会怎么做”它还是老一套直接给答案不澄清、不计划。排查了半天发现是路径问题——我把 superpowers clone 到了项目子目录里但 AGENTS.md 里写的是绝对路径前后不一致AI 压根没扫到。解决方法是统一路径规范。如果你把 superpowers 放在/Users/me/superpowers那所有配置里都用这个绝对路径不要写相对路径。另外AGENTS.md 里的措辞也要足够强硬。我之前写的是“可以参考”这几个字AI 真的就只是“参考”了一下然后继续我行我素。后来我改成“必须遵循且优先于通用行为”效果立竿见影。如果你也遇到技能时灵时不灵可以先打开会话让 AI 复述它读到了哪些技能文件一步就能定位问题。5.2 上下文爆炸与技能数量控制第二个坑是上下文超限。superpowers 默认带了几十个技能文件全部注入会话上下文后还没开始干活Token 就被吃掉了一大部分。尤其在 Codex 这类对上下文长度敏感的工具里很快就会出现“聊到一半突然忘记早期代码”的情况。我一开始很老实把整个 skills 目录全量加载结果就是频繁截断、生成质量断崖式下跌。正确做法是“按需裁剪”。我只保留最常用的六七个澄清问题、头脑风暴、实施计划、TDD、自检、复盘。其它不常用的技能先放在备用目录等真遇到对应场景再临时用/skills命令手动加载。这就像做菜调味料备齐但不意味着全倒进去放多了菜就废了。实测证明把技能瘦身之后AI 在长任务里的表现稳定得多前中期上下文都够用后期还能保持对大局的掌控。5.3 与 IDE 插件的冲突及行为漂移第三个值得说的问题是“双 Agent 打架”。我在 VS Code 里装了官方的 AI 插件同时又在终端里用 Codex CLI两边的会话共享同一个项目目录但各读各的配置文件。结果 AI 插件没加载 superpowersCodex 加载了两边对同一段代码的处理思路完全不一样我一度以为是 superpowers 出了 bug。排查思路很简单明确各工具的职责边界别让多个 AI 同时动同一个任务。我现在会规定架构设计、复杂重构交给 Codex superpowers单文件补全、解释代码交给 IDE 插件。这两个场景互不重叠也就没有冲突。还有一个隐藏坑是“行为漂移”——代码库长期只有你一个人维护在某个模块里用了非标准的写法superpowers 里的“自检”技能可能会认为它是不规范代码试图“纠正”它。我的建议是这类情况直接在项目约束里加白名单说明让技能知道这是“有意为之”。5.4 问题速查表现象可能原因解决动作AI 不遵循技能流程AGENTS.md 路径错误或措辞太弱统一路径改用“必须遵循”强约束描述会话中后期质量下降技能加载过多导致上下文超限只保留高频技能按需手动加载多个 AI 工具产出不一致不同工具配置未统一明确分工避免多 Agent 同任务并发代码风格被莫名改动技能自检规则与项目历史代码冲突在 AGENTS.md 中加白名单说明方案太保守/不够多样只触发单一技能没走头脑风暴主动要求“先给出三种方案再比较”这五个问题是我在实际跑项目中踩得最密集的。每个问题基本都能在五分钟内定位并解决因为你面对的只是配置文件和文本规则不是编译器也不是运行时崩溃。真正需要花时间的其实是理解“AI 为什么会做出这个行为”而这恰恰是 superpowers 这类工具最大的学习价值——它逼着你用工程的思维去管理 AI。6. 进阶玩法动手写一个属于自己的 superpowers 技能6.1 理解技能文件的标准结构用了一段时间 superpowers不少人会手痒能不能把自己团队的规范也做成技能完全可以而且不难。一个技能文件的核心结构其实很清晰最上面是 YAML 格式的 frontmatter包含技能名称、描述、触发条件下面正文是具体步骤用 Markdown 分节书写可以带代码示例、检查清单、禁止事项。我拿一个自己写的“数据库迁移规范”技能举例。它的描述是“当用户要求修改数据库表结构或数据迁移脚本时自动触发”触发条件写清楚AI 就不会在不相关场景里跳出来。正文步骤包括先查看现有迁移脚本命名规范、基于当前最新版本创建新脚本、写正反向迁移逻辑、在本地执行migrate验证、最后补充回滚演练记录。这个技能写完后我把它丢进项目的 skills 目录后续 AI 再做数据库变更时每一步都严格对照这个规范执行。6.2 编写实践从规范文档到技能文件写技能文件最忌“贪多”。有人恨不得一个技能解决所有问题最后写出来的东西又臭又长AI 根本记不住。我的经验是一条规则一份技能每份技能的步骤控制在五到八步语言尽量用祈使句像“列出”、“检查”、“确认”、“执行”这样的动词开头。描述部分要写清楚“是什么场景下用”和“目标是达到什么效果”这样 AI 才能准确触发和判断完成度。写完之后一定要做“实测验证”。我会构造一个针对性问题看 AI 有没有按技能走。比如测试“数据库迁移规范”技能我会故意说“帮我把 users 表加一个 nickname 字段”然后观察 AI 是否先检查已有迁移脚本、是否创建了带正确前缀的新脚本、是否主动提了一句“需要同时考虑回滚”。如果这些都没有我会回看是描述不准确还是步骤不够具体。这个过程本质上是在给你的技能包做单元测试。6.3 技能复用与团队共享最后分享一个进阶技巧把技能当成团队知识库来运营。我在团队里建了一个team-skills仓库里面除了 superpowers 原有的技能还沉淀了团队独有的发版流程、故障应急手册、代码评审标准。新成员加入时只需要把技能目录配好AI 就自动具备“老员工”的工作习惯团队规范培训的时间明显缩短了。运维方式很简单技能仓库用 Git 管理改了规范就提交 PR评审合并后大家各自git pull一下就能生效。与传统文档相比这种技能化规范最大的不同是“被动可用”——不需要人主动去查AI 会在正确时机主动调用。我现在已经不太愿意回到没有技能包的状态那种感觉就像从一个随时有人在旁边提醒的办公室里突然被扔回一个没人管你的会议室什么都要自己张罗。我自己的体会是superpowers 这类工具真正的门槛不在安装配置而在于你有没有想清楚“你希望 AI 用什么方式工作”。技能包是放大器你脑子里有一整套工程方法论它才能帮你把这套方法论复制到每一个新任务里。如果你只是把它当普通插件装上就完事那它无非是又多了一个吃上下文的工具罢了没什么意思。反过来说一旦你上手写了第一个自己的技能你就再也不想回头了。