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快速拥有superpowers

2.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.md，Claude Code读的是CLAUDE.md，Trae这类支持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会越用越懂你的项目。

为了让你对技能全貌有个直观印象，我整理了一个简易对照表：

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手册变得又厚又没人看。

这里附一个问题速查表，遇到类似情况可以直接对照排查：

6. 自定义技能：把团队的开发规范也变成superpowers

6.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可能还会让你觉得繁琐；但如果你在意的是代码质量和长期可维护性，多花这两分钟走流程，绝对划算。