先直接说结论：superpowers这个项目，是今年上半年我见过最“懂开发者”的一个开源辅助工具。它是给OpenAI Codex CLI这类AI编程助手做的技能扩展包，让AI不再只是“你问我答”的代码生成器，而变成一个自带工作方法论、能主动规划任务的结对工程师。我第一次在GitHub上刷到它，是在Steve Yegge那篇《Superpowers: How Coding Assistants are Changing the World》的讨论帖里。文章里有句话说得特别准：大多数人不会用AI编程，问题不在于AI不够强，而在于AI没有一套“资深工程师该有的干活顺序”。superpowers就是把这句话做成了代码。
这个项目适合谁？主要是正在用Codex CLI、或者准备把AI编程落地到真实项目的开发者/团队负责人。如果你只是拿AI写点脚本、补个函数，那它对你帮助有限；但如果你要处理的是那种几千个文件的遗留代码库、要维护一套有测试有CI的工程体系，它会让你明显感觉到AI“开窍了”。往下读之前提醒一句：这不是一个开箱即用的插件，它需要你理解它的设计思路，然后花十分钟做一次配置。但这点投入，换来的是AI从“小学生”到“工程师”的跨越。
1. superpowers到底是什么：一个装在AI助手脑子里的“工程方法论”
1.1 从“会写代码”到“会干工程”的跳跃
先明确一个定义：superpowers不是编程框架，也不是独立运行的命令行工具。它是一个以Markdown文件和目录结构为核心的知识库，专门给AI编程助手读取。你把它配置到Codex CLI之后，助手每次启动都会先读一套“工作手册”，里面包含分析代码库、写测试、做重构、审计依赖、搭建新项目等几十种技能的详细流程。
关键词是“流程”。举个例子，普通情况下你让AI“帮我重构这个模块”，它大概率是直接给你抛一段重写后的代码，看起来好像没问题，但一跑测试就挂。superpowers的模式是：它先要求AI分析代码库结构，生成模块依赖图，列出重构风险点，然后建议你从风险最低的模块开始改，每改一处跑一遍测试。这个“先分析、再拆解、小步走、时时验证”的顺序，就是资深工程师和AI的最大区别。
1.2 项目想解决的问题：AI编程的三个痛点
我在实际用Codex CLI的过程中，遇到过三个特别典型的问题，superpowers基本就是冲着它们去的。
第一，AI缺乏全局视野。你让它改一个函数，它只看得到这个函数，看不到谁在调用它、改了之后会影响哪条链路。superpowers里的“代码库分析”技能，强制AI先建立全局地图再动手。
第二，AI容易“自信地胡说”。不少AI生成的代码看着工整，逻辑一推敲全是洞。superpowers的TDD工作流能让AI先写测试、再写实现，用可运行的测试用例来约束它的幻觉，这个理念对AI编程来说太关键了。
第三，AI的“手感”不稳定。同一个问题，今天问和明天问，可能给你两种完全不同的方案。superpowers用统一的技能模板把AI的输出拉到一个稳定的水平线上，不会因为模型的微调而飘忽不定。
1.3 它和普通Codex插件的本质区别
市面上给Codex做增强的工具不少，比如各种MCP服务器、提示词合集。superpowers的独特之处在于它的结构：整个项目就是一个AGENTS.md加上一个skills目录。AGENTS.md是总纲，告诉AI“你是一个有经验的工程师，遇到问题先想清楚再动手”；skills目录里每个Markdown文件是一个技能，AI会根据你的请求自动“召唤”对应的技能模板。
这种设计带来的好处是，你可以像搭乐高一样自由组合技能，而且整个流程对用户是完全透明的。换句话说，它不是黑盒，不是“装了就魔法生效”，而是把AI的思考过程变成了可以阅读、可以修改、可以自定义的文档。这一点，对我这种喜欢掌控细节的人来说，是致命的吸引力。
2. 安装与配置：十分钟让Codex CLI背上技能包
2.1 安装前的准备条件
老规矩，先说环境要求。superpowers本质上是一堆Markdown文件，技术上没有任何依赖，但对运行环境有两个要求：第一，你必须安装了Codex CLI并且能正常使用，这个不用多解释；第二，建议你的项目里已经有Git管理，因为superpowers的好几个技能（比如重构、代码分析）会依赖Git历史来评估变更影响范围。
完整准备工作就三步：
- 安装Node.js 18以上版本，虽然技能执行不依赖Node，但Codex CLI本身是Node生态，环境太老容易出诡异问题
- 确认Codex CLI已经初始化完毕，运行
codex --version能看到版本号 - 准备一个你想尝试的项目目录，最好是那种结构稍微复杂一点、有多个模块的仓库，效果直观
2.2 下载与核心配置步骤
安装方式很简单，直接把仓库克隆到本地目录：
git clone https://github.com/obra/superpowers.git ~/superpowers克隆完成后，核心工作变成“告诉Codex CLI去读这份工作手册”。Codex CLI的全局配置文件在~/.codex/config.toml，你需要编辑它，加上一段指向superpowers的指令。
具体配置方法，官方README推荐的是创建一个Profile，把superpowers作为独立配置加载。我用的是这种：
[profiles] [profiles.superpowers] extra_instructions = "/Users/你的用户名/superpowers/AGENTS.md"保存之后，启动Codex CLI时用codex --profile superpowers，AI就会带着这套技能包工作了。
如果你用的Codex版本较老，配置文件里还没有Profile功能，也可以把指令直接写在[experimental]段落：
[experimental] extra_instructions = "~/superpowers/AGENTS.md"这两种方式的效果是一样的，区别只在于Profile更适合多套配置切换。我把两套都写出来，你就知道自己该用哪种了。
2.3 验证技能是否生效
配置完之后别急着开工，先做一个30秒的验证。启动Codex后，随便找个项目问它一句：“请用一句话介绍你自己，并列出你现在能做的主要任务类型。”
如果配置成功，它不会像以前那样回答“我是AI助手”，而是会开始给你罗列：“我可以进行代码库结构分析、按TDD流程编写测试、审计项目依赖安全性、制定重构计划……”读到这些关键词，就说明AGENTS.md已经被加载了。
不过这里我要提一个容易踩的坑：如果你在某个Git仓库里启动了Codex，而仓库本身也带了一个AGENTS.md文件，那么两份工作手册会同时生效，指令可能会有冲突。我在初期使用时就遇到过AI突然变“啰嗦”的情况，排查了半天才意识到是项目级别和全局级别的指令叠在一起了。解决方法是优先级要心里有数：项目根目录的AGENTS.md覆盖范围更聚焦，全局配置管兜底，两者冲突的时候以项目级为准。
3. 核心技能拆解：它能帮AI工程师做哪些正经事
3.1 代码库分析：让AI先画地图再动手
这是所有技能里我用得最频繁的。以前的AI编程是“盲人摸象”，你让它改大象的耳朵，它不知道大象长什么样。superpowers里的analyze_codebase技能解决了这个问题。
触发方式也很简单，你只需要在对话里说一句：“请分析这个代码库的结构，输出一份总体概览。”AI会按技能模板执行一系列动作：扫描目录树、统计文件分布、识别主框架和入口文件、绘制模块依赖关系、标注测试覆盖情况。最后它会输出一份结构化的分析报告，包括技术栈总结、架构分层、潜在的技术债点。
我特别推荐在接手一个陌生项目时，第一件事就是让它跑这个技能。之前我接手一个内部后台系统，两万多个文件，以前靠人肉翻代码，至少得两三天才能理出头绪。现在五分钟一份报告，哪些模块能碰、哪些是祖传代码不能动，心里大概就有数了。
3.2 严格TDD工作流：用测试约束AI的想象力
这个技能是我认为superpowers最核心的资产，名字叫TDD或者write_tests。AI编程最大的痛点就是生成代码质量不稳定，而这个技能的思路非常朴素：让AI遵循测试驱动开发的节奏来写代码，用测试用例卡住它。
执行流程是这样的：AI先写一个失败测试，运行它确认红；然后写最小实现代码让测试通过，确认绿；最后进行重构，再跑一遍全量测试确认没有回归。整个过程里，它还会自己记录哪些文件修改了、测试结果是什么、还有哪些边界情况没覆盖。
我的实测感受是，这个模式有得有失。代价是速度变慢，以前让AI一把梭生成一个完整功能，现在它要先磨测试再磨代码，输出内容明显变多。但收益是代码质量大幅提升，尤其是逻辑复杂的业务代码。有一次我用它给一个支付回调模块写处理逻辑，它会主动提出：“这个场景还缺少一个幂等性校验的测试用例。”这种思考深度，是普通提示词模式很难激发出来的。
3.3 依赖审计与安全扫描：给项目做“体检”
项目管理里最容易被忽视的就是依赖安全。superpowers里的audit_dependencies技能，能把这件事变成AI的日常任务。
它支持自动识别项目里的依赖清单文件，比如Node项目的package.json、Python项目的requirements.txt、Java项目的pom.xml。识别之后，AI会调用包管理器的安全查询接口，把存在已知漏洞的依赖包拉出来，标注风险等级，并给出可升级的目标版本。
这里我要多说一句，很多开发者觉得“依赖审计”是CI/CD插件的事，没必要在AI里做。但我的体会是：插件只能告诉你“哪个包有漏洞”，AI能帮你判断“升级这个包会影响哪些业务模块，改动量大概多大”。这个决策信息，在技术方案评审会上特别有说服力。
3.4 新项目脚手架：一键搭建标准工程
这个技能适合“从零开始”的场景。以前用AI搭新项目，你得反复描述需求，它还经常给你一个结构残缺的样板。superpowers里的new_project技能内置了几种工程模板，包括前端Vite/React、全栈Astro、Express后端等，它会按照工程化标准一次性生成项目结构、写入基础配置、安装依赖并跑通构建。
我试过让它生成一个企业级前端项目，它不仅搭好了目录，还自动配好了ESLint、Prettier、Husky这些工程化工具，省了我大量重复劳动。不过有一点要注意，它默认生成的是偏现代风格的项目结构，如果你团队有自己固化的工程规范，最好还是基于自己的模板让AI做自定义，不要让AI自由发挥。
3.5 日常代码审查：第二个工程师帮你把关
code_review技能同样很实用。它的工作方式不是“事后检查”，而是让AI在开发过程中充当一个持续监督的角色。你可以把一段改动发给它，它会从可读性、健壮性、安全性、可访问性四个维度给出审查意见。
最有意思的是，它能发现“非语法错误”的潜在问题——比如你在自己代码里可能根本注意不到的资源泄漏，它会在审查报告里直接标注出来并建议修复方案。这对没有专职Code Review的团队来说，相当有价值。
4. 实操体验：带着superpowers改造一个遗留项目
4.1 用一个真实场景检验AI
光讲功能显得空，我拿一个实际项目来说说完整流程。五月份我把一个老项目交给了superpowers改造，那是一套2018年左右写的用户管理微服务，Spring Boot框架，代码风格比较混乱，测试覆盖几乎为零。
第一步，我启动Codex并加载superpowers配置，让它先做代码库分析。大概过了不到一分钟，它就给出了一个分层清晰的概览：Controller层有哪些黑洞逻辑、Service层哪些类承担了过多职责、数据访问层哪些地方存在安全隐患。逐条翻下来，惊讶的发现，它不仅理解了代码结构，还基本判断出了哪些模块是核心链路、哪些模块可以动刀。
第二步，我指示它选择其中一个service类，起了一个重构计划。它的做法很标准：先给出一份“当前问题列表”，再列出一份“重构步骤地图”，小步重构、每步保证编译通过、运行测试确认未破坏其他逻辑。这种风格的代码改动，比直接重写一大段逻辑要安全得多。
4.2 跟普通模式做的对比记录
我特意做了一个对比，同样一个功能改动，分别用普通Codex模式和superpowers模式跑一遍，测试结果差异在“及格分数线”之上拉得很开。普通模式下AI直接给了成品代码，看起来大差不差，但一翻边界场景就存在问题；superpowers模式下，它多花了一倍的时间写测试和校验，最终代码也更符合团队规范。
我统计过两个数字，虽然不严谨，但可以参考：普通模式的代码，回到测试环境跑一遍，三五个小问题是常态；superpowers模式生成的代码，通常一遍就能通过。代价是耗时多了50%左右，回答的字数也多出一大截。两者怎么选，不取决于工具本身，取决于你的场景——一次性任务脚本用普通模式就够了，核心业务代码交给superpowers模式更稳妥。
4.3 团队协作里的落地经验
superpowers还有一个容易被忽略的价值：它是可以被团队共享的。项目仓库克隆到本地后，你完全可以把它提交到团队的Git仓库里，所有人统一版本，统一技能包，AI的工作手册变成团队知识沉淀的一部分。
我建议团队里指定一位成员专门维护这个技能包，把团队自己的规范、模板、常见踩坑记录整理成新的skill文件，丢进skills目录。这样AI在干活时会自动参考这些团队私有的方法论，比传一个几百页的内部Wiki高效得多。我们团队就是这么干的，把周会上反复强调的“代码提交规范”做成了一个技能文件，AI每次生成提交信息时都会遵守。
5. 常见问题与避坑：我踩过的四次坑
5.1 安装后AI不读技能包
第一次配置完成后，我满心期待地启动codex，结果AI完全没有“新手艺”，回答风格跟以前一模一样。排查了半天，问题出在配置文件上：我用的Codex版本比较新，[experimental]段落已经被废弃了，必须写在[profiles]里它才认。如果你的配置在旧版有效、升级后失效了，大概率是这个原因。
5.2 Token开销明显变大
这个吓退了不少人。因为技能包要求AI先分析再动手，输出内容会膨胀，一次完整会话的token消耗可能翻倍。我的建议是：不要对简单任务开superpowers，日常语法问题、正则表达式这类工作直接普通模式；只有面对复杂任务、有依赖关系或需要动架构时，再切换到superpowers profile。养成这个习惯后，成本其实在可控范围。
5.3 多AGENTS.md冲突
前面提到过，项目根目录如果有自己的AGENTS.md，会和全局的superpowers产生冲突。这种冲突不表现为报错，而是AI行为变得混乱，有时候遵循项目指令，有时候遵循全局指令。我的排查思路是逐级查看：先看项目根目录有没有工作手册，再看全局有没有叠加。把这几个文件全检查一遍，行为基本就能恢复正常。
5.4 Windows路径导致读取失败
如果你在Windows上工作，配置路径里的斜杠方向很容易踩坑。Codex的配置解析器对Windows风格的反斜杠支持有限，我建议路径一律用正斜杠写：C:/Users/用户名/superpowers/AGENTS.md。另外一个冷门坑是，如果路径中包含空格，记得用引号把整段路径包起来。
6. 自定义skills与后续玩法：把方法论变成自己的武装
6.1 如何写一个属于自己的技能文件
superpowers的价值不止于开箱自带的技能，更在于它的开放性。skills目录下每个技能都是独立的Markdown文件，你要新增技能，复制一个现有模板，改几个关键字段就行。
结构并不复杂，四个部分：技能名称、适用场景、执行步骤、返回格式。比如我给团队写过一个“数据库迁移规范”技能，执行步骤是：先对比Schema差异，再生成迁移脚本，然后预览影响行数，最后询问确认。本质上就是把团队专家脑袋里的流程固化成一个文件，让所有用AI的同事都享受到资深DBA的“外挂”。
6.2 把它和团队规范深度绑定
自定义技能文件可以直接提交到Git仓库，变成团队工程资产。你甚至可以给它配置分支保护，更新走Pull Request流程，评审通过才能合入。这样做之后，团队AI开发会越来越标准化，任何一次代码变更都会遵循统一的质量门禁。
我见过做得比较极致的团队，把代码评审规范、日志格式、命名规范全部做进skill里，然后强制所有AI辅助开发走这个profile。有新人入职，先让他把AI配置好，再去看项目文档——相当于给新人配了一个随身“资深代码导师”。
6.3 进阶：让它成为你的“项目记忆库”
最后分享一个我的另类玩法：把项目的业务背景和常见坑做成一个全局说明文件，放进superpowers的AGENTS.md里。这样每次启动Codex，AI都会先“回忆”这个项目的来龙去脉、之前踩过哪些坑，而不是每次从零理解。
这个做法用了之后效果很夸张，AI对业务的理解会“持续积累”。不再是一台没有记忆的问答机，而是一个越用越懂你的虚拟同事。如果你已经把项目玩透了，我强烈建议你研究一下怎么把AI的“记忆”沉淀下来——这是比任何插件都有价值的一件事。
说回这个项目本身：很多人以为superpowers是给AI“加技能”，我倒觉得它更像给AI立规矩。限制它乱发挥，反而让它更可靠。这个思路，值得每个搞AI编程的人试一试。
