superpowers：为AI编程工具注入资深工程师工作流的开源技能集

写这篇superpowers的使用指南之前我先说一个很典型的场景。你手上明明有Codex CLI这种挺强的AI编程工具让它给项目加个小功能它上来就动了几个文件结果把无关模块的测试搞挂了让它修个bug它不先确认复现路径直接重写整个函数。问题不在模型能力而在AI缺少一套资深工程师的干法。superpowers要解决的就是这件事。它是一个开源的AI编程技能集通过注入自定义skill让Codex CLI、Claude Code这类工具在动手前先做需求梳理、开发时按测试驱动推进、重构时小步提交甚至会把关键决策文档化。说白了superpowers不是又一个AI助手而是给现有AI助手装的一套SOP流程库。这篇文章我会从设计思路、安装部署、核心技能、完整实操到问题排查一条龙讲清楚适合正在用AI编程工具、但希望让它从会写代码进化到会好好写代码的开发者。1. superpowers是什么它解决的其实是AI编程最后那20%的差距1.1 为什么AI编程工具总让你觉得差点意思现在的代码大模型单看能力已经能完成相当复杂的编程任务。可一旦真把它放到真实项目里不少人会有一个共同感受它像是一个技术很强但没什么工作经验的实习生。你让它改一个按钮颜色它能把整个组件重写一遍你让它加一个接口它不先看一眼现有代码风格直接按自己习惯来你明确说了不要动数据库结构它还是给表加了字段。这不是模型笨而是模型默认行为模式决定的。大模型擅长的是根据上下文生成最大概率的下一段内容它天然倾向于快速产出完整答案而不是像资深工程师那样先问需求、再拆任务、每步验证。这中间的差距就是工作习惯。一个正常的人类工程师接手项目时一定会先读README、看目录结构、了解代码规范动手之前一定先确认需求边界写代码时一定先想测试怎么过遇到方案取舍一定会在PR描述里写清楚理由。AI编程工具缺的恰恰是这套肌肉记忆。1.2 superpowers在AI编程链路里到底改了什么superpowers并没有修改任何模型参数它靠的是prompt工程加流程控制把上面说的那些工作习惯以技能文件的形式注入到AI的对话上下文中。项目核心由两部分组成一份项目级指令文件常见的是AGENTS.md以及一个放在skills目录下的技能集。你可以这样理解AGENTS.md相当于给AI看的项目交接文档一进项目就先读知道这里有什么规矩skills目录则是一套新员工入职手册里面有各种场景下的标准作业流程。比如brainstorming技能规定了开发新功能前必须先输出需求与设计文档TDD技能规定了必须先写失败测试、再写实现、再重构。AI在对话中看到这些指令后会按照里面的步骤一步步执行而不是凭感觉自由发挥。我实际测试下来最直观的感受是它开始会反问了。以前你说给列表加个筛选它马上写代码装了superpowers之后它会先问筛选条件有几个空结果展示什么筛选后要不要保留分页参数然后把这些问题整理成一份设计文档让你确认了才开始动手。这个变化对长期维护项目的人来说价值非常大。2. 安装与接入让Codex CLI快速拥有superpowers2.1 安装前置条件与环境准备在装superpowers之前先把环境确认清楚不然后面排查起来很麻烦。我的建议是先满足以下三个条件本地已经装好Codex CLI并且能正常发起对话。你可以在终端输入codex进入交互模式确认能收到回复。当前项目是一个git仓库因为superpowers的安装脚本和AGENTS.md机制都默认你在一个项目目录里操作。确认你的Codex CLI版本较新至少支持文件读写和工具调用旧版本可能无法正确读取skills目录。这些条件都满足后你把终端切到项目根目录准备好开始安装。2.2 两种安装方式npm安装与让AI自己装我第一次接触superpowers时觉得它最酷的一点是官方推荐你直接让AI自己安装自己。你不需要手动复制一堆文件只需要在Codex CLI里输入一段指令让它去仓库把README读一遍然后按文档完成安装。实际效果非常好因为superpowers自己的文档写得足够清楚AI完全有能力照着操作。在项目根目录启动codex会话输入codex进入交互式对话后输入这段提示词请从github上的obra/superpowers仓库获取安装说明阅读README后将superpowers安装到当前项目中。安装完成后告诉我该项目使用了哪些工作流。AI会自动克隆仓库、读取安装文档、把AGENTS.md和skills目录放到正确位置。整个过程大概需要一两分钟你只需要在它确认安装方案时回答继续。如果你更习惯手动控制也可以用第二种方式把仓库克隆到本地手动把AGENTS.md和skills目录复制进项目。大致命令是git clone https://github.com/obra/superpowers.git /tmp/superpowers cp /tmp/superpowers/AGENTS.md . cp -r /tmp/superpowers/skills ./skills注意具体要复制哪些文件以仓库实际结构为准我这边克隆下来看到的主要就是AGENTS.md和skills目录但不同版本可能略有差异。复制完以后建议用编辑器打开AGENTS.md确认一下引用路径是否正确。2.3 接入Codex CLI后的状态验证安装完成不等于万事大吉我建议先做一个20秒的验证确认superpowers真的生效了。最直接的办法新开一个Codex会话注意一定要新开旧会话的上下文里可能还没加载新文件然后问AI请阅读当前项目的AGENTS.md然后列表说明在我接下来开发新功能时你会按照哪些步骤工作如果superpowers已经生效AI会罗列出brainstorming、TDD、逐模块构建、决策日志等流程。如果它只是泛泛地说我会先了解需求再写代码那多半是文件位置放错了或者会话没有重新加载。此时回到项目根目录用ls确认AGENTS.md和skills目录是否存在再新开一个会话重试。另外提一句AGENTS.md里的内容尽量不要随意删减。我见过有人为了精简把其中关于skills的引用去掉了结果AI立刻回到之前那种自由发挥的状态。AGENTS.md是superpowers和AI之间的接线口这块别动。2.4 其它支持skills的工具怎么接入superpowers这套设计之所以流行是因为它踩中了AI编程工具的一个共同趋势通过文件系统加载项目级指令。Codex CLI读的是AGENTS.mdClaude Code读的是CLAUDE.mdTrae这类支持skills目录的编辑器思路也完全一样。如果你用的是Trae安装方式不需要另找什么特殊插件直接在项目根目录放好AGENTS.md和skills文件夹然后在对话里明确告诉AI请遵守项目根目录AGENTS.md中的工作流就行。和Codex CLI相比只是工具名称不同底层机制是通用的。这其实也是我把superpowers推荐给团队用的原因一套技能文件不同工具都能接。3. 核心技能拆解这些超能力到底教AI做了什么3.1 brainstorming动手前先把问题想透brainstorming是superpowers里最出名的技能也是我用了之后感知最强的一个。它解决的痛点是AI拿到需求就直接写代码结果写了半天发现需求理解错了。触发brainstorming的场景很明确当用户提出一个新功能、一个新模块或者一个需求描述模糊的改动时AI不会立刻动手而是先进入需求梳理模式。它会围绕需求提出一系列澄清问题比如这个功能的核心使用场景是什么有哪些边界条件验收标准是什么有没有明确不做的内容。等关键信息都拿到后AI会输出一份简短的需求与设计文档内容包括背景、方案概述、涉及模块、风险点然后等你确认。我第一次用时还有点不适应因为过去习惯了提需求AI直接干活现在它反过来问我问题。但多跑几次后发现这种做法能拦下很多拍脑袋的需求。你可以在提示词里加上请先进行brainstorming输出设计文档后再进入开发这样流程就有了明确起点。3.2 TDD工作流先写测试再写代码TDD测试驱动开发是superpowers内置的另一个核心技能。它的执行节奏非常标准先写一个失败的测试运行测试确认红灯再写最小实现让测试变绿最后重构并再次运行测试。整个过程AI会分步汇报而不是一次性把代码和测试全部丢给你。这个技能的效果有点反直觉。表面上先写测试再写实现感觉多了一道工序好像更慢了。但实际跑下来它帮你省掉的是后面调试的时间。AI写的代码不一定第一版就正确但只要你把测试用例描述清楚它自己就能通过测试判断实现有没有偏。在Codex CLI里你可以直接说请使用TDD工作流程来实现这个接口AI就会先产出测试文件。比较稳妥的做法是让它在每个阶段结束后都运行一次测试并把结果贴给你这样你能实时看到红绿变化。3.3 逐模块构建与变更控制改一小步验证一小步逐模块构建这个技能对老项目尤其有用。大模型特别喜欢大开大合你让它加一个功能它可能顺手重构了附近的三个模块。superpowers的做法是强制AI把大任务拆成小模块一个模块完成并验证通过后再进入下一个模块。我在实际使用中深有体会。以前让AI加一个任务归档功能它可能把列表查询、状态机、前端展示全改了出问题都不知道从哪查起。使用逐模块构建后AI会先拆出任务清单比如第一步新增归档接口第二步改造列表查询去掉已归档任务第三步补充测试。每完成一步它会汇报改动了哪些文件、测试是否通过我再决定是否继续。这种节奏让代码审查变得特别轻松因为你永远能看到增量diff而不是一份巨大的改动。3.4 决策日志与精炼错误两个容易被忽略的好习惯除了上面几个大技能superpowers还有两个容易被忽略但相当实用的技能。第一个是决策日志。当AI在开发中遇到方案A还是方案B的选择时它会主动把背景、可选方案、选择理由写进项目的决策日志目录。这其实就是架构决策记录ADR的思路只不过以前是人工写现在AI帮你起草。比如你让它选数据库索引方案它会在日志里写明选了复合索引而不是单列索引原因是查询条件稳定且可以覆盖高频查询。这种记录对团队协作价值极高一个月后回来看代码你还能知道当时为什么这么做。第二个是精炼错误处理。AI在调试时经常面对一长串报错堆栈superpowers会要求它先把错误信息精炼成关键摘要再基于这个问题去搜索或定位。这个习惯看着不起眼但能显著减少AI被报错信息带着跑偏的情况。它不再盲目地把整个堆栈贴进搜索框而是先归纳出错误类型和触发点。顺便说一句这套技能集还有一个自更新机制当AI在工作流中发现更好的做法时可以按规范把新习惯记录下来等于你的AI会越用越懂你的项目。为了让你对技能全貌有个直观印象我整理了一个简易对照表技能名称触发场景AI会做什么brainstorming新功能、需求模糊先澄清问题输出需求与设计文档确认后再开发TDD工作流新增接口、修bug先写失败测试红→绿→重构分步汇报逐模块构建功能偏大、改动范围广拆解小模块一模块一验证减小diff范围决策日志方案取舍、架构选择记录背景、方案、理由到决策日志文件精炼错误处理报错定位、调试提炼错误摘要避免被堆栈带偏更新技能新工作方式验证有效把新习惯写回技能库持续进化4. 实操记录用superpowers完成一次完整开发流程4.1 场景设定给一个待办服务加归档功能光讲技能有点抽象我拿一个实际跑过的场景来说。假设现在有一个Node.js写的待办事项API功能很简单创建任务、查看列表、完成任务。我想加一个归档功能要求是归档后的任务不物理删除而是状态变为archived列表接口默认不展示已归档任务同时需要保留归档时间字段。放在以前让AI直接做它大概率会先改数据模型再加接口再改列表查询一口气提交一大份代码。这次我特意按superpowers的流程走了一遍。4.2 完整交互流程实录我先在项目根目录启动Codex CLI输入请按照当前项目的AGENTS.md工作流帮我实现任务归档功能。需求任务可以归档归档后状态变为archived列表接口默认不返回已归档任务保留归档时间。AI的第一反应不是写代码而是进入了brainstorming。它接连问了几个问题归档后需不需要恢复操作既然要保留归档时间是新增一个archivedAt字段还是复用updatedAt列表接口的分页参数需不需要传一个包含已归档任务的开关每个问题都在点子上。我回答之后它输出了一份简短的开发计划文档把方案确定为新增archivedAt字段加一个归档接口列表查询默认过滤archived状态。确认完方案它才进入TDD。先写了归档接口的单元测试运行一次测试红灯然后补了接口实现再跑测试绿灯接着小步重构把过滤逻辑抽成公共方法再跑全量测试确认没破坏原有功能。在这个过程中它还往决策日志里写了一段记录为什么用软删除而不是物理删除核心原因是业务上需要保留审计痕迹。这个动作没人提示是工作流自带的。最后它提醒我可以提交代码了并建议我检查一下改动范围。我大致扫了一眼改动集中在模型、接口、测试三个文件没有无关代码混进来。4.3 驱动AI的提示词写法要点从上面这次实操里我总结出几个和superpowers配合的提示词写法要点。第一明确声明走流程。在需求描述后面加一句请按照AGENTS.md中的工作流执行AI就不会跳过前置步骤。第二锁定改动范围。如果这是老项目可以补一句不要修改与本次需求无关的模块配合逐模块构建技能能有效抑制AI的顺手优化冲动。第三要求分步汇报。叮嘱它每完成一个模块列出改动文件和测试结果这样你能随时喊停不至于等它闷头改完几十个文件再回头看。第四把验收标准写进需求。比如上面那个例子如果你希望列表接口可通过参数强制包含已归档任务应该在需求阶段就提出来brainstorming环节的澄清问题会帮AI把这个约束落到设计文档里。5. 常见问题与排查技巧实录5.1 技能没生效先查这三处有读者问过我明明装好了superpowers但AI还是老样子上来就写代码。遇到这种情况我一般按三个方向排查。第一检查AGENTS.md是不是真的在项目根目录。AI只会读取它当前工作目录下的指令文件你放错了层级它根本看不到。第二检查是不是没有新开会话。AI的上下文是会话级的老会话里没有加载新指令必须重新发起一个会话才会读取AGENTS.md。第三检查提示词里有没有明确要求。有些工具在上下文不是很紧张时未必会主动把AGENTS.md的所有步骤都执行一遍你在对话里把请按工作流来说清楚效果立竿见影。5.2 AI上来就写代码不做需求梳理这是很多人装了superpowers之后最大的困惑明明有brainstorming技能AI怎么还是直接写我遇到的实际情况是往往是因为需求描述得太完整了AI判断不需要额外澄清。比如你把技术方案都定好了说帮我加一个POST /archive接口接收id把任务的status改成archived再写个测试AI自然直接执行。它不傻不会放着明确指令不干非去做需求梳理。所以如果你希望它先做设计就不要把技术细节全部提前定死或者明确用指令打断它先不要写代码先做brainstorming输出方案后再动手。5.3 测试不过还被AI强行推进怎么办superpowers的TDD流程设计得挺好但实操中总会有意外比如AI写完实现后测试还是红的它却直接跳到下一步重构。我的处理方式是在对话里加一句硬约束测试没有全部通过之前不允许继续往下推进也不能提交代码。如果它还是不听就让它在每次操作后先把测试命令的输出粘贴出来。另外有些项目测试本身跑得慢AI容易跳过运行直接假装测试过这时候我会明确指定命令比如用npm test运行测试并把结果贴出来。让AI把证据亮出来比口头上说好了没问题可靠得多。5.4 项目变大后体验下降的处理思路用了一段时间后你可能会发现项目文件一多AGENTS.md里的技能说明占用的上下文越来越长反而影响AI响应速度。这不是bug而是上下文窗口的物理限制。我的做法是给AGENTS.md做瘦身只保留最核心的流程引用把具体的技能详细内容留在skills目录里让AI按需读取。也要定期清理skills目录里那些不再使用、或者被更好方案取代的旧技能别让一本SOP手册变得又厚又没人看。这里附一个问题速查表遇到类似情况可以直接对照排查现象可能原因处理方式AI不读AGENTS.md文件位置不对或会话未刷新放到项目根目录新开会话重试AI直接写代码需求描述过细或未要求走流程提示先brainstorming后开发测试失败仍继续缺少硬性约束要求先贴测试结果通过后再推进技能卡住不执行等待用户确认或上下文过长输入下一步指令或精简技能文件内容改动范围失控没有锁定模块边界明确不修改无关模块按模块分步交付6. 自定义技能把团队的开发规范也变成superpowers6.1 skill文件的基本结构与写法superpowers最有价值的一点是它允许你写自己的技能。项目里每个技能其实就是一个目录下的一份SKILL.md用Markdown描述触发条件和执行步骤。结构并不复杂一般包含三块技能名称和用途、触发场景、操作步骤。我放一个极简示例# SKILL: 前端组件开发流程 ## 触发场景 - 新增前端组件 - 修改已有组件的样式或交互 ## 流程 1. 先确认组件的使用场景与现有设计规范 2. 按模板、样式、逻辑、测试的顺序实现 3. 每个文件控制在较小规模避免组件文件过重 4. 运行相关测试并汇报结果写完这份文件后把它放到项目的skills目录下启动新会话时让AI读取一遍它就能按这个流程走。用熟了以后完全可以把团队的代码规范、评审清单、发布检查项全部写成技能文件让每个用AI工具的同事都按同一套标准交付。6.2 把团队规范沉淀成superpowers的完整案例我帮团队做过一个很典型的事情把后端接口开发规范写成了一份自定义技能。以前团队成员用AI写接口风格五花八门有人用类有人用函数有人不写参数校验有人不写文档注释。我写了一个技能文件规定所有新增接口必须包含入参校验、统一返回结构、异常处理、测试用例四个部分步骤里还写明校验规则要与现有校验器保持一致。结果效果远超预期。AI在开发新接口时会主动按照这个规范生成代码团队成员不用再花时间在code review里一遍遍纠正风格。这种沉淀一旦做起来团队内部的AI使用体验会快速拉齐新人也更容易上手。对我个人来说这也是持续使用superpowers的最大动力。最后分享一个我自己的使用体会这套工具真正值钱的地方不是那些开箱即用的技能而是它给了我一种给AI制定工作方式的框架。安装它很简单难的是你愿意配合它的流程把自己的需求先说清楚、把改动范围控制住、把测试跑完再谈下一步。如果你只是想让AI一口气生成一大段代码superpowers可能还会让你觉得繁琐但如果你在意的是代码质量和长期可维护性多花这两分钟走流程绝对划算。