1. Superpowers是什么为什么值得折腾先直接说结论Superpowers是给Codex CLI用的“技能包”扩展工具目前GitHub上已经有不少关注度。它的核心思路很朴素——把那些你在编程助手对话里反复粘贴的“系统提示词”、项目规范、脚手架模板、错误排查套路全部沉淀成一套可复用的技能配置让AI助手按你的项目规则干活。热词里有个很关键的组合是“codex superpowers”说明大部分人接触这个项目都是因为Codex。用过Codex CLI的开发者应该都有同感它比网页版的对话助手更贴近项目本身能在本地文件系统里直接改代码、跑命令、提交Git但默认配置下它“像个聪明但散漫的实习生”——你让写接口就写接口遇到报错就报错不会主动去查项目里其他文件的约定也不会检查改动有没有破坏既有逻辑。Superpowers解决的就是这个“主动性”和“规范性”的问题。这个项目具体能做什么呢它可以给你正在用的代码编辑器严格说是Codex所支持的工作目录挂载一组可插拔的技能例如让AI先读项目的README、构建脚本、目录结构再去动手改代码为不同的语言框架Java、Python、Node等提供定制的代码规范与排错流程把“遇到编译错误时应该按什么顺序排查”这样经验性的操作路径写成AI能照做的技能文档为AI助手配置一条明确的“不做清单”比如不自动改配置中心、不擅自升级第三方库版本。简单讲它把AI从“你说一句我动一下”变成了“按你团队的规矩自动干活”。如果你经历过AI改完代码后莫名其妙坏了构建、或者AI写出的代码风格和项目里其他地方完全不一致那Superpowers就是冲着这个痛点来的。它也不挑水平——老手可以自己扩展技能文件新手跟着默认配置用也能明显感觉到效果。接下来这篇内容我会从安装、目录结构、核心技能解析到常见问题完整讲一遍实际使用中积累的经验和踩过的坑部分细节会结合常见实践做合理扩展。2. 环境准备与安装从零到能跑通的完整流程2.1 先确认你的基础环境Superpowers本身是一个“指挥框架”它不直接提供AI能力而是依赖本地的Codex CLI作为执行引擎。所以第一步不是装Superpowers而是先确认环境里有可用的Codex。这里说的Codex指的是OpenAI开源的CLI工具codex命令。它和ChatGPT网页端不是一回事CLI版本可以直接在你当前项目的目录下执行能读取文件、运行shell命令、查看git diff。安装Codex本身很简单用npm全局装就行npm install -g openai/codex装完先验证一下版本codex --version如果你的机器上已经有Node.js环境这一步通常不会出问题。我之前遇到最多的情况反而是Node版本太老——Codex要求Node 18及以上装完报错先别慌先看一眼node版本。然后是身份认证。Codex首次使用需要登录OpenAI账号CLI会弹出浏览器窗口做授权登录成功后在命令行里会显示确认信息。这一步没有太多技巧需要注意的是网络环境要稳定登录过程如果中断重新在终端执行一次codex命令即可。2.2 安装Superpowers主体基础环境就绪后Superpowers的安装基本可以用“一条命令”概括。项目官方推荐的安装方式是拉取Git仓库到本地然后初始化配置git clone https://github.com/works-hal/superpowers.git cd superpowers npm install如果你是macOS或Linux还有个更省事的curl安装脚本但说实话我比较推荐手动clone——因为后面你要自定义技能文件迟早会想去翻仓库里自带的那些示例手动clone下来的目录结构一目了然。安装完成后项目里会生成一个配置文件通常是superpowers.json它记录了启用哪些技能集。默认配置会启用基础技能包包括错误排查、代码审查、提交信息规范这些通用项。安装指南里会有些环境相关的系统适配问题不同操作系统略有差异Windows用户可能会遇到一点小问题后面常见问题部分我会单独说。2.3 把Superpowers挂到Codex上装完Superpowers本体还不够关键是让Codex知道去哪里找这些技能。这里需要做的是在Codex的配置目录里设置一个环境变量或提示文件路径让Codex启动时自动装载Superpowers的提示词体系。不同版本的Codex配置方式有差别。老版本是在~/.codex/config.toml里写配置新版则支持在项目根目录放AGENTS.md这类提示文件来补充项目上下文。Superpowers的思路是把所有技能文档组织成Markdown文件并通过一个总入口文件告诉Codex“技能都在这个目录里”。按常见实践我会在Codex的全局配置里加上这样一段[extra_body] # 指向你的superpowers技能目录配置完后重新打开一个终端进入你的目标项目目录启动codex交互模式问一句“你能看到哪些superpowers技能”正常情况下AI会报出一串技能名称。这就说明挂载成功了。2.4 新手最容易忽略的步骤重启会话说实话我第一次装完Superpowers满心欢喜地启动Codex结果发现AI行为和之前一模一样完全不像是加载了技能。后来才发现问题出在会话状态Codex的会话是独立的只有新会话才会重新读取配置和提示文件。旧会话里AI的上下文已经固定了你中途改再多的配置它也感知不到。所以装完Superpowers一定要退出当前会话重新进入项目目录再启动codex。这个细节看起来很小但坑了不只我一个人。社区里凡是说“装完没效果”的帖子一大半都是这个问题。3. 核心配置与技能系统拆解3.1 Superpowers的目录结构长什么样Superpowers把“技能”做成了一组目录和文件每个技能其实就是一份带格式的Markdown说明。它的好处在于你不用懂任何编程只要会写Markdown就能定义一套AI应该遵循的规则。典型的目录结构是这样的superpowers/ ├── skills/ │ ├── core/ │ │ ├── analyze-error.md │ │ ├── code-review.md │ │ └── commit-message.md │ ├── languages/ │ │ ├── java.md │ │ ├── python.md │ │ └── typescript.md │ └── workflows/ │ ├── feature-request.md │ └── bug-fix.md └── superpowers.json每个技能文件里写的是“行为指令”。比如code-review.md里会写先查看git diff逐文件检查是否有明显的逻辑漏洞、有无调试残留代码、命名是否清晰如果发现问题按严重程度给出修改建议不要直接改代码。AI读到这个技能后在做代码审查时就会按这套流程走。superpowers.json是总开关里面列了启用的技能列表。你可以只启用自己需要的技能比如我现在只启用了Java调优和错误排查把前端相关的技能全关掉了减少不必要的上下文开销。3.2 提示词工程在Superpowers里怎么体现很多人问Superpowers和直接往Codex里粘贴一大段提示词有什么区别区别在于组织性和可复用性。直接粘贴提示词每次会话都要重复而且提示词一长AI读到后面的内容往往会“忘记”前面的规则。Superpowers把提示词拆成了独立模块每个模块负责一个场景Codex在遇到对应场景时才会调用对应技能的参考文档。这样做有三个好处上下文更干净、规则更聚焦、扩展更方便。以Java技能为例java.md里会写明优先遵循项目已有的包结构写新类时参照相同层级类文件的风格遇到编译错误时先检查import是否完整再检查泛型类型是否匹配不要随意给方法添加throws Exception除非项目里已有类似写法。这些都是非常有针对性的约束粘贴一大段通用提示词很难达到这种精细度。用生活化的类比来解释普通提示词像是一张写满注意事项的便签贴在电脑屏幕上时间久了你自己都会无视它Superpowers技能则像一套SOP每张便签只负责一个操作环节用到哪个环节就自动调用对应那张而且换项目时可以整套换掉。3.3 自定义技能按团队规范沉淀AI行为真正让Superpowers发挥价值的是自定义技能。举个例子我们团队在后端开发里有个约定所有对外接口的响应结构必须包含code、message、data三个字段错误码错误信息必须从统一的枚举类中取禁止在业务代码里直接写数字。要让Codex遵守这个约定之前只能每次会话开头贴一遍这个规范麻烦且容易漏。有了Superpowers之后我只需要在workflows/下建一个api-response.md把上述规则写清楚然后把它加入superpowers.json。之后每次让Codex写接口它都会自动去读这个技能文件严格按照团队规范生成代码。再比如一个非常实用的技能是“数据敏感度检查”。在技能文件里写明所有涉及用户手机号、邮箱、身份证号的日志输出必须脱敏不允许把完整SQL打印到控制台配置文件中的密钥必须从环境变量读取。AI写代码时就会自动规避这些问题省掉不少人工审查的返工。3.4 技能文件不要“贪多”自定义技能虽好但有一个很实际的教训技能不是越多越好。AI的上下文窗口是有限的你不能期望它一次记住二十个技能文件的全部内容。更合理的做法是只保留那些高频使用、对代码质量影响最大的规则。我一开始往配置里塞了一大堆技能包括代码格式化风格、注释语言要求、接口命名规范、异常处理习惯、单元测试覆盖率要求……结果Codex的响应速度肉眼可见地变慢而且偶尔会出现“选择了A技能里的规则但违反了B技能里的要求”这种自相矛盾的行为。精简到五个核心技能之后情况好了很多。4. 实操过程用Superpowers带AI完成一个Java模块4.1 场景设定这一节用实际案例来说明Superpowers在真实项目中怎么用。假设你现在要在一个Spring Boot项目里新增一个“用户积分查询接口”涉及的部分有数据库表、Mapper层、Service层、Controller层。这个任务不大不小但涉及跨层改动很能体现Superpowers的约束能力。为了演示更有代表性我把任务设置成带有隐性要求的这个项目里已经有一个类似的“用户等级查询接口”团队要求新接口的风格与旧接口保持一致。4.2 任务执行全过程启动Codex后我输入第一句指令在现有项目中新增用户积分查询接口参照已有的用户等级查询接口的代码风格保持三层架构一致。注意我没有在指令里写任何具体的技术细节——积分表叫什么、Mapper接口用什么命名、Controller返回什么结构这些全都交给AI结合Superpowers技能去判断。如果放在没有Superpowers的裸Codex里它很可能会直接开写但用了Superpowers之后它会先读取项目结构找到用户等级查询接口的代码分析它的包路径、命名习惯、Response结构然后照着这个模板开发。实际执行中AI会主动列出它的行动计划第一扫描项目目录定位等级查询相关的Controller、Service、Mapper第二读取这些类文件归纳代码风格第三查看数据表结构确认积分字段第四生成新接口代码第五编译并执行相关测试。这个过程里Java技能文件起的作用非常明显——AI会主动遵守项目里已有的包结构不会自作主张创建新包。4.3 过程中Superpowers干预了什么我观察到一个很有意思的细节默认技能里有一条是“改动代码前先查看git log了解最近的提交习惯”结果AI在动手之前先翻了一遍提交历史发现团队最近的提交信息全是feat: 描述的格式于是在完成任务后它甚至主动给出了符合这个格式的提交信息建议。还有一个值得提到的细节任务执行到一半我发现AI准备在一个常量类里新增一个magic number积分倍率10但项目里这个数字其实已经在配置文件中定义过了。在裸Codex环境下AI通常会“自作主张”地写进代码里Superpowers的代码审查技能在后台悄悄拦了一道在生成代码后运行的review环节AI自己识别出了这个重复定义然后改为从配置类中注入。这正是Superpowers带来的一种体感差异它让AI从“完成任务就行”变成了“按正确的方式完成任务”。这个差异没法用一段话准确描述但如果你用过一段时间再回到裸Codex会有一种“窗口期后退”的强烈不习惯。4.4 这套流程值得注意的时间成本说点实在的加了Superpowers之后AI完成任务的时间确实变长了。裸Codex可能在几秒内直接输出代码而Superpowers会因为“先读项目结构再做方案再执行”的流程多花一些时间。在我的测试里同样一个“新增查询接口”任务裸Codex大约需要40秒Superpowers需要90秒左右。这个额外时间花得值不值我个人的结论是值因为需要人工review和返工的时间明显少了。以前裸Codex生成的代码大概率有几处不符合项目规范你得自己改现在Superpowers生成的代码基本可以“无痕接入”省掉的是看代码挑毛病的时间这笔账怎么算都划算。4.5 做一次人工检查别全信AI我必须要强调Superpowers只是降低AI出错的概率不是消除错误。每次AI完成任务后我还是会人工做一次完整的git diff检查。Superpowers的优势在于diff里的改动大部分是符合规范的我需要关注的只是业务逻辑本身有没有理解偏差。这种“把力气花在刀刃上”的方式才是AI辅助开发的理想状态。普通提示词方式像是带着一个不熟悉规矩的新同事你得事无巨细地交代细节Superpowers方式像是带了一个已经培训过的新同事你只需要说清楚任务目标就好。5. 常见问题与排查技巧实录5.1 装完SuperpowersCodex没任何变化这是被问得最多的问题。原因一般是三类第一类Codex的会话没有重启。前面说过旧会话不会重新读取配置新会话才会。处理方式很简单退出当前会话重新进入项目目录再启动codex。第二类技能目录路径配错了。检查一下superpowers.json里的路径是否是绝对路径因为有些情况下相对路径会解析到用户目录而不是项目目录。建议一律使用绝对路径。第三类Codex版本太旧。Superpowers依赖新版Codex的项目感知能力如果你的codex版本太老建议先执行npm update -g openai/codex升级到最新。5.2 Windows用户遇到git bash执行npm install失败我见过几个Windows用户在安装依赖时遇到node-gyp报错基本都是因为本机缺C编译工具链。这属于纯环境问题和Superpowers本身关系不大。解决方法有两个一是装Visual Studio Build Tools二是改用WSL环境安装。我个人的建议是既然你都在接触Codex这类AI开发工具了长期看用WSL体验会好很多文件路径、权限处理、性能都更接近Linux服务器环境。5.3 AI提示找不到某个技能如果你添加了自定义技能但AI反馈找不到对应的技能先排查是不是技能文件名和超级powers.json里的名称不一致。superpowers.json里写的是技能ID而技能文件里的YAML frontmatter中也要有匹配的name字段。两边的名称如果不匹配AI会静默跳过这个技能不报错也不提示。还有一个小概率问题技能文件的编码不是UTF-8。AI工具处理非UTF-8编码的文本时容易出乱码尤其是从Windows记事本复制过来的内容建议用VS Code存成UTF-8格式。5.4 技能文件到底放项目里还是放全局这是个经常见的“最佳实践”问题。我个人的经验是通用技能错误排查、代码审查、提交信息规范放全局项目专属技能接口响应结构、数据脱敏规则、包结构规范放项目仓库。原因在于技能文件本身也是需要版本管理的资产。你把业务规范放进了代码仓库团队成员拉下来就能共享如果放在全局目录你换了电脑又忘了备份这些积累的规则就全没了。Superpowers的GitHub仓库里其实也推荐这种“全局项目”的二层结构。5.5 如何调试自定义技能的“AI不听话”最后说一个经验性的问题你写了技能规则AI却不执行到底怎么回事根据我的踩坑经验最常见的还是规则本身写得不够“可操作”。举个例子你写“代码风格要统一”AI无法把这个指令落地成具体动作但如果你写“新代码的命名风格与同目录已有文件的命名风格保持一致包名使用小写字母方法名使用驼峰”AI就知道具体怎么做了。技能文件写完后建议做一个“最小化验证”单独让Codex执行一个只涉及该技能的小任务观察它的行为是否符合预期。如果符合再放进真实项目如果不符合调整规则表述再试。这样避免把一堆规则丢给AI之后根本分不清是哪条规则出了问题。6. 从个人使用到团队协作的扩展思考Superpowers的价值不止于个人提效它更接近于一条让AI“团队化”的路径。本质上它把AI对齐团队规范的成本从“每次会话重新交代”降到了“一次配置长期生效”。如果团队希望所有人都能在开发中使用AI辅助编码我建议你可以把维护技能文件这件事当成一个正式工程来做由团队里最有经验的工程师来写“显性规范”新人在AI的辅助下能更快遵守这些规范代码评审时如果发现AI经常犯同一类错误就把对应规则补进技能文件里下次它就不会再犯了。这种“反馈闭环”是Superpowers在使用中逐渐沉淀出的最高价值——它越用越贴合你的项目而不是每次会话后回到原点。关于项目名里的“superpowers”这个说法从我实际体会来看它确实带来了从基础AI能力向定制化能力的跨越感。但这个能力不值得盲目吹捧它更像是一个“插件系统”给你提供的核心工具是“可定制、可沉淀、可复用”。真正让它发挥作用的是你对项目规范的理解是否清晰、对AI能力的边界是否有把握以及你是否愿意花时间去打磨那些技能文件。
Superpowers：为Codex CLI打造可复用技能包，让AI按项目规范干活
1. Superpowers是什么为什么值得折腾先直接说结论Superpowers是给Codex CLI用的“技能包”扩展工具目前GitHub上已经有不少关注度。它的核心思路很朴素——把那些你在编程助手对话里反复粘贴的“系统提示词”、项目规范、脚手架模板、错误排查套路全部沉淀成一套可复用的技能配置让AI助手按你的项目规则干活。热词里有个很关键的组合是“codex superpowers”说明大部分人接触这个项目都是因为Codex。用过Codex CLI的开发者应该都有同感它比网页版的对话助手更贴近项目本身能在本地文件系统里直接改代码、跑命令、提交Git但默认配置下它“像个聪明但散漫的实习生”——你让写接口就写接口遇到报错就报错不会主动去查项目里其他文件的约定也不会检查改动有没有破坏既有逻辑。Superpowers解决的就是这个“主动性”和“规范性”的问题。这个项目具体能做什么呢它可以给你正在用的代码编辑器严格说是Codex所支持的工作目录挂载一组可插拔的技能例如让AI先读项目的README、构建脚本、目录结构再去动手改代码为不同的语言框架Java、Python、Node等提供定制的代码规范与排错流程把“遇到编译错误时应该按什么顺序排查”这样经验性的操作路径写成AI能照做的技能文档为AI助手配置一条明确的“不做清单”比如不自动改配置中心、不擅自升级第三方库版本。简单讲它把AI从“你说一句我动一下”变成了“按你团队的规矩自动干活”。如果你经历过AI改完代码后莫名其妙坏了构建、或者AI写出的代码风格和项目里其他地方完全不一致那Superpowers就是冲着这个痛点来的。它也不挑水平——老手可以自己扩展技能文件新手跟着默认配置用也能明显感觉到效果。接下来这篇内容我会从安装、目录结构、核心技能解析到常见问题完整讲一遍实际使用中积累的经验和踩过的坑部分细节会结合常见实践做合理扩展。2. 环境准备与安装从零到能跑通的完整流程2.1 先确认你的基础环境Superpowers本身是一个“指挥框架”它不直接提供AI能力而是依赖本地的Codex CLI作为执行引擎。所以第一步不是装Superpowers而是先确认环境里有可用的Codex。这里说的Codex指的是OpenAI开源的CLI工具codex命令。它和ChatGPT网页端不是一回事CLI版本可以直接在你当前项目的目录下执行能读取文件、运行shell命令、查看git diff。安装Codex本身很简单用npm全局装就行npm install -g openai/codex装完先验证一下版本codex --version如果你的机器上已经有Node.js环境这一步通常不会出问题。我之前遇到最多的情况反而是Node版本太老——Codex要求Node 18及以上装完报错先别慌先看一眼node版本。然后是身份认证。Codex首次使用需要登录OpenAI账号CLI会弹出浏览器窗口做授权登录成功后在命令行里会显示确认信息。这一步没有太多技巧需要注意的是网络环境要稳定登录过程如果中断重新在终端执行一次codex命令即可。2.2 安装Superpowers主体基础环境就绪后Superpowers的安装基本可以用“一条命令”概括。项目官方推荐的安装方式是拉取Git仓库到本地然后初始化配置git clone https://github.com/works-hal/superpowers.git cd superpowers npm install如果你是macOS或Linux还有个更省事的curl安装脚本但说实话我比较推荐手动clone——因为后面你要自定义技能文件迟早会想去翻仓库里自带的那些示例手动clone下来的目录结构一目了然。安装完成后项目里会生成一个配置文件通常是superpowers.json它记录了启用哪些技能集。默认配置会启用基础技能包包括错误排查、代码审查、提交信息规范这些通用项。安装指南里会有些环境相关的系统适配问题不同操作系统略有差异Windows用户可能会遇到一点小问题后面常见问题部分我会单独说。2.3 把Superpowers挂到Codex上装完Superpowers本体还不够关键是让Codex知道去哪里找这些技能。这里需要做的是在Codex的配置目录里设置一个环境变量或提示文件路径让Codex启动时自动装载Superpowers的提示词体系。不同版本的Codex配置方式有差别。老版本是在~/.codex/config.toml里写配置新版则支持在项目根目录放AGENTS.md这类提示文件来补充项目上下文。Superpowers的思路是把所有技能文档组织成Markdown文件并通过一个总入口文件告诉Codex“技能都在这个目录里”。按常见实践我会在Codex的全局配置里加上这样一段[extra_body] # 指向你的superpowers技能目录配置完后重新打开一个终端进入你的目标项目目录启动codex交互模式问一句“你能看到哪些superpowers技能”正常情况下AI会报出一串技能名称。这就说明挂载成功了。2.4 新手最容易忽略的步骤重启会话说实话我第一次装完Superpowers满心欢喜地启动Codex结果发现AI行为和之前一模一样完全不像是加载了技能。后来才发现问题出在会话状态Codex的会话是独立的只有新会话才会重新读取配置和提示文件。旧会话里AI的上下文已经固定了你中途改再多的配置它也感知不到。所以装完Superpowers一定要退出当前会话重新进入项目目录再启动codex。这个细节看起来很小但坑了不只我一个人。社区里凡是说“装完没效果”的帖子一大半都是这个问题。3. 核心配置与技能系统拆解3.1 Superpowers的目录结构长什么样Superpowers把“技能”做成了一组目录和文件每个技能其实就是一份带格式的Markdown说明。它的好处在于你不用懂任何编程只要会写Markdown就能定义一套AI应该遵循的规则。典型的目录结构是这样的superpowers/ ├── skills/ │ ├── core/ │ │ ├── analyze-error.md │ │ ├── code-review.md │ │ └── commit-message.md │ ├── languages/ │ │ ├── java.md │ │ ├── python.md │ │ └── typescript.md │ └── workflows/ │ ├── feature-request.md │ └── bug-fix.md └── superpowers.json每个技能文件里写的是“行为指令”。比如code-review.md里会写先查看git diff逐文件检查是否有明显的逻辑漏洞、有无调试残留代码、命名是否清晰如果发现问题按严重程度给出修改建议不要直接改代码。AI读到这个技能后在做代码审查时就会按这套流程走。superpowers.json是总开关里面列了启用的技能列表。你可以只启用自己需要的技能比如我现在只启用了Java调优和错误排查把前端相关的技能全关掉了减少不必要的上下文开销。3.2 提示词工程在Superpowers里怎么体现很多人问Superpowers和直接往Codex里粘贴一大段提示词有什么区别区别在于组织性和可复用性。直接粘贴提示词每次会话都要重复而且提示词一长AI读到后面的内容往往会“忘记”前面的规则。Superpowers把提示词拆成了独立模块每个模块负责一个场景Codex在遇到对应场景时才会调用对应技能的参考文档。这样做有三个好处上下文更干净、规则更聚焦、扩展更方便。以Java技能为例java.md里会写明优先遵循项目已有的包结构写新类时参照相同层级类文件的风格遇到编译错误时先检查import是否完整再检查泛型类型是否匹配不要随意给方法添加throws Exception除非项目里已有类似写法。这些都是非常有针对性的约束粘贴一大段通用提示词很难达到这种精细度。用生活化的类比来解释普通提示词像是一张写满注意事项的便签贴在电脑屏幕上时间久了你自己都会无视它Superpowers技能则像一套SOP每张便签只负责一个操作环节用到哪个环节就自动调用对应那张而且换项目时可以整套换掉。3.3 自定义技能按团队规范沉淀AI行为真正让Superpowers发挥价值的是自定义技能。举个例子我们团队在后端开发里有个约定所有对外接口的响应结构必须包含code、message、data三个字段错误码错误信息必须从统一的枚举类中取禁止在业务代码里直接写数字。要让Codex遵守这个约定之前只能每次会话开头贴一遍这个规范麻烦且容易漏。有了Superpowers之后我只需要在workflows/下建一个api-response.md把上述规则写清楚然后把它加入superpowers.json。之后每次让Codex写接口它都会自动去读这个技能文件严格按照团队规范生成代码。再比如一个非常实用的技能是“数据敏感度检查”。在技能文件里写明所有涉及用户手机号、邮箱、身份证号的日志输出必须脱敏不允许把完整SQL打印到控制台配置文件中的密钥必须从环境变量读取。AI写代码时就会自动规避这些问题省掉不少人工审查的返工。3.4 技能文件不要“贪多”自定义技能虽好但有一个很实际的教训技能不是越多越好。AI的上下文窗口是有限的你不能期望它一次记住二十个技能文件的全部内容。更合理的做法是只保留那些高频使用、对代码质量影响最大的规则。我一开始往配置里塞了一大堆技能包括代码格式化风格、注释语言要求、接口命名规范、异常处理习惯、单元测试覆盖率要求……结果Codex的响应速度肉眼可见地变慢而且偶尔会出现“选择了A技能里的规则但违反了B技能里的要求”这种自相矛盾的行为。精简到五个核心技能之后情况好了很多。4. 实操过程用Superpowers带AI完成一个Java模块4.1 场景设定这一节用实际案例来说明Superpowers在真实项目中怎么用。假设你现在要在一个Spring Boot项目里新增一个“用户积分查询接口”涉及的部分有数据库表、Mapper层、Service层、Controller层。这个任务不大不小但涉及跨层改动很能体现Superpowers的约束能力。为了演示更有代表性我把任务设置成带有隐性要求的这个项目里已经有一个类似的“用户等级查询接口”团队要求新接口的风格与旧接口保持一致。4.2 任务执行全过程启动Codex后我输入第一句指令在现有项目中新增用户积分查询接口参照已有的用户等级查询接口的代码风格保持三层架构一致。注意我没有在指令里写任何具体的技术细节——积分表叫什么、Mapper接口用什么命名、Controller返回什么结构这些全都交给AI结合Superpowers技能去判断。如果放在没有Superpowers的裸Codex里它很可能会直接开写但用了Superpowers之后它会先读取项目结构找到用户等级查询接口的代码分析它的包路径、命名习惯、Response结构然后照着这个模板开发。实际执行中AI会主动列出它的行动计划第一扫描项目目录定位等级查询相关的Controller、Service、Mapper第二读取这些类文件归纳代码风格第三查看数据表结构确认积分字段第四生成新接口代码第五编译并执行相关测试。这个过程里Java技能文件起的作用非常明显——AI会主动遵守项目里已有的包结构不会自作主张创建新包。4.3 过程中Superpowers干预了什么我观察到一个很有意思的细节默认技能里有一条是“改动代码前先查看git log了解最近的提交习惯”结果AI在动手之前先翻了一遍提交历史发现团队最近的提交信息全是feat: 描述的格式于是在完成任务后它甚至主动给出了符合这个格式的提交信息建议。还有一个值得提到的细节任务执行到一半我发现AI准备在一个常量类里新增一个magic number积分倍率10但项目里这个数字其实已经在配置文件中定义过了。在裸Codex环境下AI通常会“自作主张”地写进代码里Superpowers的代码审查技能在后台悄悄拦了一道在生成代码后运行的review环节AI自己识别出了这个重复定义然后改为从配置类中注入。这正是Superpowers带来的一种体感差异它让AI从“完成任务就行”变成了“按正确的方式完成任务”。这个差异没法用一段话准确描述但如果你用过一段时间再回到裸Codex会有一种“窗口期后退”的强烈不习惯。4.4 这套流程值得注意的时间成本说点实在的加了Superpowers之后AI完成任务的时间确实变长了。裸Codex可能在几秒内直接输出代码而Superpowers会因为“先读项目结构再做方案再执行”的流程多花一些时间。在我的测试里同样一个“新增查询接口”任务裸Codex大约需要40秒Superpowers需要90秒左右。这个额外时间花得值不值我个人的结论是值因为需要人工review和返工的时间明显少了。以前裸Codex生成的代码大概率有几处不符合项目规范你得自己改现在Superpowers生成的代码基本可以“无痕接入”省掉的是看代码挑毛病的时间这笔账怎么算都划算。4.5 做一次人工检查别全信AI我必须要强调Superpowers只是降低AI出错的概率不是消除错误。每次AI完成任务后我还是会人工做一次完整的git diff检查。Superpowers的优势在于diff里的改动大部分是符合规范的我需要关注的只是业务逻辑本身有没有理解偏差。这种“把力气花在刀刃上”的方式才是AI辅助开发的理想状态。普通提示词方式像是带着一个不熟悉规矩的新同事你得事无巨细地交代细节Superpowers方式像是带了一个已经培训过的新同事你只需要说清楚任务目标就好。5. 常见问题与排查技巧实录5.1 装完SuperpowersCodex没任何变化这是被问得最多的问题。原因一般是三类第一类Codex的会话没有重启。前面说过旧会话不会重新读取配置新会话才会。处理方式很简单退出当前会话重新进入项目目录再启动codex。第二类技能目录路径配错了。检查一下superpowers.json里的路径是否是绝对路径因为有些情况下相对路径会解析到用户目录而不是项目目录。建议一律使用绝对路径。第三类Codex版本太旧。Superpowers依赖新版Codex的项目感知能力如果你的codex版本太老建议先执行npm update -g openai/codex升级到最新。5.2 Windows用户遇到git bash执行npm install失败我见过几个Windows用户在安装依赖时遇到node-gyp报错基本都是因为本机缺C编译工具链。这属于纯环境问题和Superpowers本身关系不大。解决方法有两个一是装Visual Studio Build Tools二是改用WSL环境安装。我个人的建议是既然你都在接触Codex这类AI开发工具了长期看用WSL体验会好很多文件路径、权限处理、性能都更接近Linux服务器环境。5.3 AI提示找不到某个技能如果你添加了自定义技能但AI反馈找不到对应的技能先排查是不是技能文件名和超级powers.json里的名称不一致。superpowers.json里写的是技能ID而技能文件里的YAML frontmatter中也要有匹配的name字段。两边的名称如果不匹配AI会静默跳过这个技能不报错也不提示。还有一个小概率问题技能文件的编码不是UTF-8。AI工具处理非UTF-8编码的文本时容易出乱码尤其是从Windows记事本复制过来的内容建议用VS Code存成UTF-8格式。5.4 技能文件到底放项目里还是放全局这是个经常见的“最佳实践”问题。我个人的经验是通用技能错误排查、代码审查、提交信息规范放全局项目专属技能接口响应结构、数据脱敏规则、包结构规范放项目仓库。原因在于技能文件本身也是需要版本管理的资产。你把业务规范放进了代码仓库团队成员拉下来就能共享如果放在全局目录你换了电脑又忘了备份这些积累的规则就全没了。Superpowers的GitHub仓库里其实也推荐这种“全局项目”的二层结构。5.5 如何调试自定义技能的“AI不听话”最后说一个经验性的问题你写了技能规则AI却不执行到底怎么回事根据我的踩坑经验最常见的还是规则本身写得不够“可操作”。举个例子你写“代码风格要统一”AI无法把这个指令落地成具体动作但如果你写“新代码的命名风格与同目录已有文件的命名风格保持一致包名使用小写字母方法名使用驼峰”AI就知道具体怎么做了。技能文件写完后建议做一个“最小化验证”单独让Codex执行一个只涉及该技能的小任务观察它的行为是否符合预期。如果符合再放进真实项目如果不符合调整规则表述再试。这样避免把一堆规则丢给AI之后根本分不清是哪条规则出了问题。6. 从个人使用到团队协作的扩展思考Superpowers的价值不止于个人提效它更接近于一条让AI“团队化”的路径。本质上它把AI对齐团队规范的成本从“每次会话重新交代”降到了“一次配置长期生效”。如果团队希望所有人都能在开发中使用AI辅助编码我建议你可以把维护技能文件这件事当成一个正式工程来做由团队里最有经验的工程师来写“显性规范”新人在AI的辅助下能更快遵守这些规范代码评审时如果发现AI经常犯同一类错误就把对应规则补进技能文件里下次它就不会再犯了。这种“反馈闭环”是Superpowers在使用中逐渐沉淀出的最高价值——它越用越贴合你的项目而不是每次会话后回到原点。关于项目名里的“superpowers”这个说法从我实际体会来看它确实带来了从基础AI能力向定制化能力的跨越感。但这个能力不值得盲目吹捧它更像是一个“插件系统”给你提供的核心工具是“可定制、可沉淀、可复用”。真正让它发挥作用的是你对项目规范的理解是否清晰、对AI能力的边界是否有把握以及你是否愿意花时间去打磨那些技能文件。
