superpowers开源项目：给AI编程助手装上“手脚”，让Codex跑完整开发流程

“superpowers”这名字一听就挺中二的但如果你用过Codex这类AI编程助手大概就能明白它想表达什么AI写代码的能力早就够了真正缺的是“干杂活”的自主性。你让大模型写个排序算法它提笔就来但你要是让它自己拉分支、跑测试、处理合并冲突、顺手按规范把代码提交上去它就开始犯迷糊了。superpowers这个开源工具干的就是这件事——给AI编程助手装上“手脚”让它不只会写代码还能像真人开发者一样把整个工作流跑完。我最初是被“codex superpowers”这几个热词勾过去的想着这又是哪个包装得很玄学的项目结果把仓库拉下来一看发现思路意外地朴素不提供代码库不搞复杂框架就是一堆写得极其讲究的Markdown技能文件外加一套把它们注入AI上下文的加载机制。用下来一个月这东西确实改变了我用Codex的方式所以今天干脆把这个项目的设计思路、安装步骤、核心技能用法、以及我踩过的坑全部摊开来讲一遍。不管你已经重度依赖AI编码助手还是只在空闲时拿它写点脚本这篇都值得看完尤其是后面那部分针对“技能没生效”和“AI乱跑命令”的排查实录全是拿真金白银的token换来的经验。1. 项目到底在解决什么问题先说一个可能被很多人忽略的事实现在的AI编程助手比如Codex、Claude Code、Cursor本质上是“单线程选手”。你给它一个明确的小任务它能完成得不错但你要是把它放到一个完整的开发流程里让它在几十个文件之间来回跳、执行命令、根据报错改代码、再跑测试、最后提交它很快就会“断片”。为什么因为大模型本身没有记忆之外的东西它的上下文窗口再大也浪费不起一步步看文件、敲命令、检验结果这种琐碎的往返开销。superpowers对这个问题的解法不是把AI做成更强的代码生成器而是把“开发者日常的工作流”变成一份份结构化的技能文档在每回合任务开始前强制注入给AI。说白了它给AI补上了方法论层面的缺失怎么做Git提交怎么在动手前先规划怎么把一个大任务拆成小步骤怎么在执行命令前先确认风险。这些东西对老程序员来说是习惯对AI来说却是从未见过的“行业默契”而superpowers就是把这些默契写成了AI能读懂的规范。1.1 为什么普通的prompt搞不定这件事有人会想那我直接在系统提示词里写上一段“你要先规划再行动提交时写规范的commit信息”不就行了我一开始也这么干过实测效果非常不稳定。原因在于提示词只能影响模型的输出风格无法真正约束它的行为路径。你告诉它“先规划”它可能真的列了个1234但列完之后还是直接跳到最后一步开始改代码你告诉它“提交信息要规范”它确实写了规范的标题却完全漏掉了提交前该跑的lint和测试。superpowers的做法从根本上规避了这个问题它把每一个技能都写成了带决策树结构的文档。比如git技能里明确写了“在创建提交前必须先运行这个命令检查状态”、“遇到合并冲突时必须先展示冲突文件内容再决定策略”AI在执行过程中读到这些指令时走的是“看到条件→执行对应动作”的路径而不是靠模型脑补。这就是“技能文件”和“普通提示词”之间的本质差异——一个是可执行的流程描述一个只是风格建议。1.2 和Codex天生的适配性也许是因为作者ThePrimeagen本身就是Vim和Neovim社区的活跃人物superpowers对Codex的支持做得特别顺手。它不改变Codex的运行机制而是通过Codex本身支持的配置方式把skills目录注册进去。这样一来每次启动Codex时superpowers的所有技能文档都会作为上下文的一部分被加载AI变“聪明”了但你完全感知不到多了一层工具链。和Claude Code这种自带技能市场的工具相比superpowers最大的优势在于透明。所有技能文件都是纯文本Markdown你可以翻开任何一个文件逐行读它到底教了AI什么有不满意的直接改掉。这种设计特别对胃口——我不太信任一个黑盒帮我规定AI的行为边界但我很乐意自己动手调一堆明明白白的文档。2. 安装和配置5分钟把超能力接进Codex如果只是拉仓库、丢进某个目录那也不需要单独写这么多字。实际上superpowers的安装有几个容易忽略的细节特别是配置注入的那一步很多人就是卡在这里导致技能一直不生效。2.1 克隆项目并理解目录结构先把项目拿下来:git clone https://github.com/ThePrimeagen/superpowers.git目录结构很干净最核心的就这么几个部分skills/技能文件主目录里面全是带编号的Markdown文档像git-workflow.md、local-command-execution.md每个文件都对应一个明确的能力领域。CLAUDE.md一个入口描述文件里面说明AI应该如何理解和使用这些技能。scripts/辅助脚本主要是自动配置和注册用的。不要小看CLAUDE.md这个文件虽然名字看起来是给Claude用的但它描述的是通用加载协议。Codex会把它当作项目级别的指令来读取这是让AI理解“我拥有哪些技能”的关键入口。2.2 注册到Codex配置装好之后真正的重头戏是让Codex认可这个目录。如果你用的是官方Codex CLI需要在~/.codex/config.toml里把skills目录的路径注入到额外的CLI参数中。具体做法是编辑配置文件加入这样一段model gpt-5 [extra_cli_args] -c /你的绝对路径/superpowers/CLAUDE.md这段配置的意思是用-c参数告诉Codex每次启动时携带这个文件。注意路径必须写绝对路径这一点坑了不少人——我一开始用相对路径结果技能一会儿生效一会儿不生效排查了半天才发现是路径解析问题。如果没有config.toml也可以用环境变量或者在项目目录下手动放一个AGENTS.md来引用。不过说实话config.toml是体验最稳定的方式因为它在全局生效不会因为你切换了项目目录就丢失配置。设置好之后重启Codex会话让它重新加载配置。2.3 验证技能是否真的生效很多人配置完成后就直接开工结果发现AI行为和以前完全一样于是以为装了个寂寞。我自己用下来最快确认是否成功的方法是直接问AI一句“你现在能访问哪些技能列出技能名称和用途。”如果配置正常AI会直接列出git-workflow、local-command-execution、github-mcp等技能并大致说明用途。正常情况下superpowers加载后AI的回答会明显更有结构比如告诉你“我拥有以下能力建议我们从规划阶段开始”。如果没有请先回头检查路径再看是否重启了会话——这一步的成功率直接决定了后续所有体验别跳过。3. 核心技能拆解AI是怎么变“靠谱”的配置好之后你去实际操作时应该会注意到AI的行为模式开始改变那是因为某一个技能文件正在起作用。superpowers里场景最常用、出镜率最高的3个技能值得挑出来逐个讲透。3.1 git-workflow让AI学会正经提交代码绝大多数AI编程助手生成的代码最后死在提交这一步commit信息写成“update files”或者干脆不跑测试就把代码推上去了。superpowers里的git-workflow.md就是专门治疗这个毛病的。这个技能文件的厉害之处在于“检查前置条件”的思维。它明确要求AI在提交之前必须按顺序执行这几件事运行git status和git diff搞清楚到底改了哪些文件。检查是否包含调试代码、临时文件、无关改动。运行测试和linter。写符合约定式提交规范Conventional Commits的commit信息。有了这份技能约束之后你会发现AI提交的commit信息从“fix stuff”变成了“fix(parser): handle empty input edge case”。这背后的逻辑不是模型变聪明了而是技能文件里的流程把它的行为锁死了你不满足前置条件就别想进入下一步。更有意思的是这个技能文件还教AI怎么处理分支和合并。以前我让Codex拉一个新分支它可能直接在当前分支上改搞得一团糟现在它会在动手前先确认分支状态新建分支、切分支、最后再把改动带过去。这些都是靠着技能文件里的流程规范实现的不需要你任何额外干预。3.2 local-command-execution给AI开放终端权限很多AI编程工具的默认策略是“绝不碰终端”理由是安全性。但如果你做过稍微复杂一点的任务比如“帮我跑一下测试脚本根据报错修一下”这种就知道不碰终端的话AI根本没能力闭环。superpowers里专门有一个技能文件来定义AI如何在本地执行命令以及什么时候应该停下来问人。让我印象最深的是这个技能文件里对命令分类的处理方式。它把命令分成了“低风险”和“高风险”两类低风险命令像ls、cat、git statusAI可以直接跑但高风险命令像rm -rf、git push --force、pip install必须先列出计划并征求确认。这样一来即便是给AI开放了终端权限我心里也踏实得多。实际使用中这个技能确实让我敢让Codex去npm test、go build了。以前我得时刻盯着它会不会自作主张改装环境现在它会在执行npm install前停下来问一句“这一步会修改package.json是否继续”这种边界感正是技能文件写得细致带来的好处。3.3 github-mcp打通GitHub的最后一公里除了本地命令superpowers还利用了Codex的MCP支持接入了GitHub上的动态这样AI就能在本地任务和远程仓库之间串起来。比如你在issue里看到一个bug直接让Codex去“查看这个issue定位相关代码修复后在本地验证再开启一个PR指向main分支”在老的工具链里这是天方夜谭但在superpowers的流程约束下这种多跳操作变成了日常。它和直接调用GitHub API不同MCP让AI像一个真正能操作账号的用户那样创建PR、评论issue、检查workflow运行状态。配合前面说的git-workflowAI可以把从“读issue”到“开PR”的完整链路走通全程你只需要在关键节点拍板。这种自动化程度在我刚开始用的时候确实超出了预期。4. 实战让Codex带着superpowers跑完一个真实任务理论讲再多不如直接走一遍真实的任务流程。我拿一个实际场景来演示用户报了一个issue说某个JSON解析函数在遇到空数组时抛异常我们让superpowers加持下的Codex从零开始去把这个问题修复并跑完整个提交流程。4.1 启动阶段AI会先读超级技能我打开Codex输入的命令很简单“处理GitHub上issue #42描述的bug修复完成后自动开PR。”如果是没有superpowers的Codex它可能会愣一下然后直接开始写代码甚至找不到issue在哪。但在superpowers加持下AI第一反应是先加载自己掌握的技能列表然后明确告诉我“我将按以下流程处理读取issue→定位代码→创建分支→修复→运行测试→提交→推送→创建PR。”这一下就体现出差距了。它在动手前先同步给我一个可预期的工作计划让我知道接下来它将怎么做。而且这个计划的格式来自git-workflow.md中定义的阶段划分不是模型自己随口编的——这很重要因为模型自己编的计划经常漏步骤而技能文件里定义的流程是固定的、完善的。4.2 执行阶段它真的按流程一步步来了AI先读取issue内容然后开始搜索相关代码。这里有一次让我惊讶的操作它在改动前特意先创建了一个分支fix/json-empty-array-handling而不是粗暴地在main分支上改代码。这说明技能文件里的分支规范起了作用。修复过程本身很快因为是个典型边界问题加上一个判空逻辑就行。真正体现出superpowers价值的是后续动作AI在改完后并没有急着宣告完成而是自己跑了npm test发现有一个关联测试挂了又回头修了一下直到所有测试通过。然后它运行了lint确认代码风格没问题才提交代码。这整个过程我几乎是旁观者清。唯一需要我介入的地方是它推送分支前问了我一句“是否推送到远程并创建PR”这正是本地命令行技能里对“高风险操作”的确认机制在起作用。4.3 收尾阶段PR描述比我自己写的还规范如果说前面这些步骤已经在很多工具里见过了那最后这步还是让我服气它生成的PR描述非常完整包括了问题复现步骤、根因分析、修复思路、测试结果。这个PR描述是严格按照git-workflow.md里的模板来写的AI甚至知道我项目的测试命令是什么这明显是技能文档里包含了“提交前检查清单”的结果。从下达命令到PR创建完成全程不到5分钟而我需要做的只是回答了一个“是否需要推送”的确认问题。这种自动化程度放在几年前简直不敢想AI不再是一个代码填空工具它正在变成一个真正能跑流程的虚拟开发助理。4.4 失败场景流程约束真的有用吗有人可能会想如果代码改错了、测试没跑过这个流程是不是就卡住了实际我也见过几次。确实会卡住但方向是正确的。AI发现测试失败后会停下来把失败信息展示给我征求下一步指令而不会自作主张地删除测试或者让它失效来“通过”测试。这在以前的裸Codex环境里是做不到的——它很可能为了完成任务悄悄把测试断言改掉。这就是技能文档和普通提示词的巨大区别提示词只能让模型“倾向于”正确的行为而结构化的流程文档能在关键节点强制它停下来给人类一个干预的窗口。这种体验一旦用上就很难再退回没有superpowers的日子。5. 常见问题与避坑实录这个项目用了一个月不是没遇到过问题。有几个坑非常典型而且大概率你也会踩到我直接整理成速查表拿过去对照就行。症状可能原因解决方案AI不识别任何技能表现和没装一样配置路径写成了相对路径或没有重启Codex会话检查config.toml改用绝对路径重启会话技能部分生效比如会规划但不会提交技能文件太多导致上下文截断部分技能没被加载按需精简skills目录删除当前项目不需要的技能文件AI总在执行命令前停下来问东问西风险确认机制过于保守在local-command-execution.md中调整风险命令列表放行可信命令提交信息格式不够规范加载的技能文档不是最新版定期拉取更新或者自己修改技能文件里的commit规范示例多个项目共用一套技能配置有些技能不适用于所有项目类型根据项目类型在CLAUDE.md里设置条件触发标签5.1 踩坑技能文件的优先级问题一个特别值得展开的坑是如果你自己的系统提示词或项目说明文件和superpowers里的技能文件发生冲突AI会无所适从。我有一次在一个严格遵循内部提交规范的项目里使用superpowers它默认采用的约定式提交风格和公司规范不一致导致CI脚本挂了。解决办法是在CLAUDE.md里显式声明“如果本项目存在其他规范以项目规范为准”。这个声明要放在文档靠前的位置AI在读提示词时会把它视为高优先级指令。这个经验也可以反过来用如果你发现自己对AI的某些控制不起作用多半是优先级被别的提示词或系统指令覆盖了试着把关键指令提前。5.2 实测心得别一股脑把所有技能都塞进去superpowers仓库里带的技能文件比默认情况下可能多得多如果你不做任何处理全部保留Codex每次启动都要加载大量上下文。这倒不是说会直接爆掉上下文窗口而是会挤占很多空间导致AI在长对话中后半段开始“健忘”行为退化成没有superpowers的状态。我的做法是只保留当前项目真正需要的技能文件。比如纯前端项目我就只留git-workflow和local-command-execution需要碰GitHub的再加一个github相关技能。与其让AI囫囵吞枣地了解二十种技能不如让它精通三五个真正常用、且和当前任务强相关的技能。5.3 安全话题命令权限不是开得越大越好最后必须提醒一句虽然superpowers能让你把终端权限开放给AI但你得想清楚你愿意承受多大风险。我的原则是默认只放行读取类和无副作用的命令对于安装依赖、修改配置、推送代码等操作永远保持中间有一道人确认的关卡。你当然可以修改技能文件把确认机制全部关掉让AI一条龙全自动执行但如果你在一个生产环境仓库里这么玩我只能说祝你好运。superpowers给了你充分的控制权但用不用这种控制权考验的是你自己的工程素养。我的建议是确认机制留着它多问你一句你回的也就几秒钟但可能帮你省掉一整个下午的灾难恢复。6. 这些技能文件也是你的学习资料聊了这么多用法还有一个我意外的收获superpowers的技能文件本身就是一份非常好的“AI行为规范写作”教材。它不是随便讲讲“要做高质量提交”而是把每个动作的前置条件、执行顺序、异常处理都写得清清楚楚。读这些文件你会潜移默化地学会怎么给AI下指令、怎么定义可执行的流程。我现在整理自己的团队AI规范时就直接借鉴了superpowers的文档结构先定义目标再描述前置检查再写执行步骤最后给异常分支的处理方案。这种结构化的规范比单纯写“请仔细分析并完成以下任务”有效十倍。如果以后ai工具会接管越来越多开发环节那么“会写AI规范”本身就会成为程序员的一项核心竞争力而superpowers就是一套很值得研究的写作范例。