开箱一个叫 superpowers 的东西说实话第一次看到这个项目名我还以为是哪个中二少年给脚本起的绰号。直到我把它接进自己的 Codex 工作流跑通了几个真实任务才意识到这名字其实起得挺贴切——它干的活就是把一个“能用”的编码智能体升级成“懂规矩、能接力、可复盘”的工程助理。这篇内容我围绕 superpowers 的安装、核心机制、典型工作流和踩坑经验展开适合正在用 Codex CLI、觉得每次对话都像开盲盒、想把手动指令沉淀成可复用资产的人。下面这些内容大多来自我实际使用和排查过程中的记录部分机制细节属于基于通用实现逻辑的合理推断我会在涉及的地方说明清楚方便你自己验证。1. 先说清楚 superpowers 解决的是什么问题很多人第一次听说 superpowers下意识会问它是不是又一个 AI 编程框架答案是否定的。它更像一层“行为准则层”直接贴在 Codex CLI 这类编码智能体的外面。我的理解是它想解决的核心矛盾是大模型的单次对话能力很强但跨任务、跨会话的行为一致性很差而工程开发恰恰最吃一致性。1.1 Codex CLI 的“裸奔”困境裸装一个 Codex CLI你面对的是一个非常原始的能力集合你给它一段话它给你改一堆文件然后对话结束。听起来没什么问题但真正一上手就会难受。比如我想让它按团队规范写提交信息每次都要重新叮嘱一遍让它重构一个老模块它可能上一轮还保持着不错的编码风格下一轮就开始“自由发挥”更麻烦的是如果任务做到一半断了下一次会话它完全不记得之前做了什么。这个问题的本质不是模型不够聪明而是缺少“结构化的意图传递渠道”。你用自然语言描述需求模型能理解但自然语言的歧义太大、细节太碎每次描述都在消耗上下文窗口。superpowers 的做法是把这一类“反复要交代的上下文”固化下来变成各种各样的 skill需要时直接按名字激活而不是每次都用大白话重新描述一遍。1.2 superpowers 的设计定位给编码智能体装上行为约束层我自己跑了一段时间后对它的定位有了个更具体的理解superpowers 不是替代 Codex 的另一个编码工具而是站在 Codex 与用户之间的一层“策略层”。它负责三件事第一把高频、标准的操作流程封装成可命名的技能第二维护一份可以跨会话继承的工作记录让智能体知道自己“刚才”做过什么第三提供非交互模式下的自动推进能力让任务在无人盯守时也能保持节奏。一个比较容易混淆的点是superpowers 并不“增强模型推理能力”它增强的是“工作流的工程化程度”。模型还是那个模型但干活的方式从“想到哪说到哪”变成了“按流程走、按规范写、按记录交接”。这一点想明白了你就会发现它其实适合两类人一类是把 Codex 当日常生产力工具、但觉得每次会话重启成本太高的人另一类是团队里想统一 AI 编码行为规范、但又不想自己从零写一堆提示词工程的人。2. 安装与初始化从零跑通第一个增强会话安装 superpowers 本身不难真正容易踩坑的是“装完了不知道该怎么验证成功”。我第一次装的时候就是命令全部执行成功但跑第一个任务的时候感觉跟裸 Codex 没什么区别一度以为装了个寂寞。后来才明白需要手动激活 skill而且有一个明确的最小验证路径。2.1 环境前置条件以我自己的 Mac 环境为例下面是能正常跑起来的几个前置条件按重要性排序Codex CLI 已安装并且可以正常发起对话。这一步没搞定的话后面所有环节都免谈。你可以先跑一句最简答的codex say hello验证。Node.js 版本够新。superpowers 的安装器本身是 npm 包构建技能运行时也会依赖较新的 Node API。我建议直接用 18 以上的 LTS 版本太老的版本在安装阶段就可能有依赖解析失败的问题。终端能正常访问 npm 仓库。这个看似废话但公司内网环境经常有镜像源问题后面我会单独说。git 已经初始化并且当前项目有远端仓库。如果你的电脑上没有安装 git安装过程会少掉一个关键依赖有些版本在初始化时会在当前项目下创建.superpowers目录并自动 commit这一步需要 git 支持。这些条件里最容易忽略的是最后一条。我没仔细看文档就直接跑安装结果它提示要创建 git 提交来“记录初始状态”我才发现自己根本没在 git 仓库里。2.2 安装的具体命令步骤整个安装路径一般分三步走# 1. 全局安装命令行工具 npm install -g superpowers # 2. 在当前项目下初始化技能目录与记忆库 superpowers init # 3. 将常用技能包安装进本地技能库 superpowers install core这里解释一下每步干了什么。第一步是把你本地环境里多出一个superpowers命令它是后续所有操作的入口。第二步会在当前目录生成一个.superpowers的隐藏目录里面有 skills、memory、sessions 这几个子目录分别用来放技能定义、长期记忆和会话记录。第三步是把官方维护的核心技能包拉取到本地。这里有一个值得注意的细节superpowers init不是全局一次性的。它会在每个项目目录下都生成一份.superpowers配置这样做的理由是技能和记忆需要跟具体项目绑定。我一开始图省事在~/下初始化了一次结果换到项目目录后又得重新初始化。当然你也可以在全局配置里指定默认技能路径方法是在.superpowers/config.json里加上globalSkillsPath: ~/.superpowers/skills这样不同项目可以共享同一份技能库而记忆仍然按项目隔离。2.3 验证是否安装成功最小化测试会话安装完成后我强烈建议先跑一个最小测试而不是直接扔一个大型重构任务进去。最小测试的目的是确认“技能激活机制”已经生效。我用的验证命令长这样codex 请激活 skill:review然后帮我审查当前分支的改动输出中文审查结果要求按严重程度排序。正常情况下你会看到 Codex 在思考过程中引用review这个技能文件里的规则然后输出带优先级的审查列表。如果你发现它只是凭直觉随便说了几句并没有按技能里定义的格式输出那就说明技能没有被成功加载很可能问题出在 skill 目录权限或者 config 文件路径上。判断技能激活成功的硬性标准输出结果里出现了该技能特有的大纲结构或术语。比如 review 技能的独特输出结构是“变更概要、风险点、建议动作”如果你看到这三个小节基本就是激活成功了。2.4 安装阶段的两个高频报错与对策我在安装时遇到过两个问题后来在几个朋友那边也复现过值得写一下。第一个是 npm 安装时报ELIFECYCLE错误通常是因为某依赖包下载超时。我给出的方案是检查 npm 镜像源是否过旧直接换成官方源或者公司内部稳定源重试。第二个是superpowers init后提示 Python 相关依赖缺失这个在新版本里很少见但如果你用的是旧版本需要在系统里装好 Python 3.8。这两类问题都不是 superpowers 本身的问题而是环境问题排查路径都比较直接。3. 核心机制拆解Skill、记忆库与自动化会话如何协作装好只是第一步真正让 superpowers 从“装了个寂寞”变成“真香”的是你理解并开始使用它的三个核心机制技能库、记忆库、自动化会话。它们各自的职责不一样组合起来才是完整的工作流。3.1 Skill 体系把提示词变成可复用资产Skill 本质上是把一整段“指令 规则 输出格式要求”打包成一个可命名的模块。举个例子你不加 superpowers 的时候如果你想让人工智能跑一次代码审查你得写这么长一段话“请检查当前分支的改动先看是否有明显逻辑错误再看命名是否符合项目规范输出按严重程度排序重点标注可能导致线上问题的地方。”这段话每次都要重新打一遍而且每个模型的输出风格还不固定。有了 skill 之后你只需要说一句“用 review 技能审查当前改动”系统会从技能目录加载一个名为review.md的规则文件里面包含审查维度、输出模板、甚至“禁止使用模糊措辞”等约束。这样有三个好处第一上下文窗口被节省下来模型不必消化一大段临时指令第二输出格式可以做到跨会话稳定方便后续对接自动化流程第三技能文件可以在团队成员之间共享形成团队级的“行为规范”。技能文件本身是纯 Markdown结构上一般包含用途说明、适用场景、执行步骤、输入要求、输出格式。如果你愿意完全可以自己写一个新技能把它放到.superpowers/skills/目录下下次就能直接用。这一点我在第 6 章会详细展开。3.2 记忆库让跨会话的任务不至于“失忆”用过 Codex 的人都知道新开一个会话模型对你的项目一无所知所有上下文都要重新给。superpowers 用了一个“记忆库”机制来缓解这个问题它会自动把一段任务的核心结论存入记忆文件下一次会话启动时再自动加载作为初始上下文的一部分。说“缓解”是因为它并不能百分之百还原上一次会话的所有细节它实际做的事情是任务进行中把当前的项目状态、已改动文件、决策依据、遇到的障碍记录到记忆目录里新的会话启动时如果检测到存在对应任务的记忆文件就会优先读取让模型带着“之前大概发生了什么”的认知开始干活。用我自己的体会来打个比方裸 Codex 像是一个只有短期记忆的临时工你每次都要从头交代有记忆库的 Codex 像一个带着工作日志的同事他第二天来上班时至少知道昨天干到了哪一步、留下了哪些待办。后者在连续几天的迭代任务里体感差距相当明显。3.3 自动化会话从“一问一答”到“跑完汇报”第三个机制是自动化会话它可以简单理解成“不交互模式”你把任务目标和约束写进一个会话文件然后让 Codex 自己按照技能的节奏执行直到完成或者遇到必须人工决策的关口。它在非交互模式下会遵循技能文件定义好的步骤继续往下走而不是干一步问一句。我最常用的场景是让它在晚上自动执行一轮“迁移准备”读取当前代码库的 API 调用情况、生成调用清单、按技能要求输出迁移评估报告然后把报告写进指定目录留给第二天早上我来审阅。这种模式省掉的不是几分钟而是“我这下能不能走开去开会”的那种心理负担。但要注意自动化会话有一个默认的安全底线遇到有破坏性的操作比如批量删除文件、强制提交、覆盖远端分支它会停下来等你确认。如果你确认风险可控可以在技能里显式声明“本任务允许删除指定目录下文件”否则不用尝试用自动化模式绕过人工确认。3.4 三种机制的配合关系一次完整任务的运行轨迹只看单个机制容易晕我结合一次真实的“临时改动”任务来梳理它们的配合关系。假设任务是“给当前项目增加一个记录请求日志的中间件”。第一步自动化会话启动读取记忆库。系统发现项目是 Spring Boot 结构过往偏好是把切面类放在aspect/包下这些信息自动进入上下文。第二步会话按技能库里的“feature 开发”技能执行先分析现有项目结构再确认改动点然后生成代码最后跑测试。第三步任务过程中它会把“已新建 LogAspect.java已修改 WebConfig.java”这类状态写入记忆文件。第四步完成后它输出一份摘要包含改动文件和测试结果。你会发现这个流程里没有哪一步是特别惊艳的智能但整体却非常“稳”。这其实就是 superpowers 的价值——不追求单次对话的惊艳而追求一个任务从开始到交付的过程中所有环节都有章可循。4. 真实工作流实测从需求到代码提交的完整链路上面讲了一堆机制不看实际效果等于白讲。这一章我把自己最近跑过的三个真实场景复盘一下包括输入的命令、遇到的情况、以及我原以为会和实际结果的差异。4.1 场景一用核心技能跑一次遗留模块重构我接手了一个写了两年的老模块方法体臃肿、职责混乱团队一直想重构但没人敢动。我的目标是让 Codex 在超级技能体系下先产出一份重构方案而不是上来就改代码。我的执行命令codex 激活 skill:refactor分析 payment-service 模块的当前结构输出重构方案重点关注方法粒度、依赖方向、可测试性。要求先不要改任何代码。运行效果让我意外的地方在于它按 refactor 技能里定义的分析框架输出了完整文档包含现有结构摘要、坏味道定位、目标结构、迁移风险、建议分阶段执行计划。而且因为技能里强制要求“先分析后修改”它哪怕遇到明显可以立刻优化的小问题也不会跳步去改而是先记在“待处理清单”里。这件事给我的启发是重构这个活儿在 AI 的加持下最大的价值不是“让它帮你写新代码”而是“让它按一套稳定的标准帮你把问题识别清楚”。以前团队里做重构方案至少需要两三天而这次它只用了不到半小时就产出了初稿我只需在它生成的方案上调整优先级和取舍。4.2 场景二Java 项目里与 Maven 多模块的配合搜索热词里有 “superpowers java”这个我专门在 Java 项目里试过。你要是在一个多模块 Maven 工程里直接对 Codex 说“帮我把公共模块里过时的工具类替换掉”它大概率会拆错模块、改错依赖因为多模块工程的上下文比单模块复杂太多了。superpowers 在这个场景能做两件事一是技能文件里可以预置“多模块工程操作规范”比如规定“所有跨模块改动必须先确认pom.xml依赖关系再决定修改范围”二是记忆库可以记录上一轮会话已经处理过哪些子模块避免下一轮重复分析。我实测的一次任务是“将 common-utils 模块中已废弃的 HttpClient 工具替换为基于 Java 11 HttpClient 的实现”。在技能约束下它先绘制了依赖关系图确认只有 order-service 和 user-service 两个模块引用了这个工具类然后才动手改代码最后自动更新了依赖声明。整个流程非常接近一个资深开发者的操作顺序而这一整套规则并不需要我现场指导它全部来自技能文件里的预设。4.3 场景三自动生成提交信息与变更摘要还有一个很小但每天都会用到的场景提交信息。我们团队有比较严格的提交信息规范普通人的写法总是五花八门AI 也不例外。早期我不加约束的时候让 Codex 生成提交信息它经常输出一段小作文跟规范要求完全不符。superpowers 处理这个问题的思路很简单写一个commit-message技能规定输出格式必须是feat(scope): description结构描述不超过 50 个字符并且禁止使用感叹号。之后每次提交前我只需要跑一句codex 激活 skill:commit-message根据当前 git diff 生成提交信息。输出结果从不会跑偏永远是整洁的一行式描述。这里不涉及任何“高级智能”纯粹是规则约束带来的稳定性。我会说这是超级技能体系最有价值的一课AI 开发最缺的不是智力而是“可预期的行为”。4.4 实测数据与体感对比以下是我在自己项目里记录的一组粗略对比数据不作为严谨基准测试仅作参考任务类型裸 Codex 平均耗时superpowers 加持后主要差异点重构方案生成无法直接完成需要大量追问约 20 分钟有固定分析框架不需要逐步引导多模块 Java 改动容易改错模块需反复纠正约 35 分钟有依赖关系检查前置步骤提交信息生成输出不符规范1 分钟以内稳定输出固定格式跨会话任务接力基本完全失忆约 2 分钟恢复上下文记忆库自动加载列出这些不是为了证明它“更快”更准确的说法是“少了很多拉扯”。裸 Codex 给我的感觉是每次都要重新调教而 superpowers 的这套机制把调教过程固化了下来才省下了大量时间。5. 避坑清单与调试心得文档里不会写的事安装和使用本身不难但把 superpowers 真正用好绕不开几个隐性坑。这些坑不是文档不写而是它们通常只在特定规模或特定类型项目里才会暴露出来。我按自己在实际项目中遇到的问题整理成一份避坑清单。5.1 坑一技能文件越长模型表现反而越差这是一个非常反直觉的问题。我在刚开始使用的时候总觉得技能文件写得越详细越好恨不得把一个任务的所有注意事项全塞进去。可是跑出来的结果反而越来越“呆”模型会对一些本不重要的约束过度解读。原因在于上下文窗口是有限的技能文件会占用上下文空间当技能文件本身的描述过长模型真正能用来推理的窗口就被压缩了。我后来调整了两个做法一是控制单个技能文件不超过 150 行能写清楚“做什么、怎么做、输出什么”就够了二是把那些很长的背景说明放进记忆库而不是技能库。记忆库的内容只有在相关任务启动时才加载技能文件却会在大场景中被高频引用价值不同。5.2 坑二跨项目共享技能时要注意内存泄露问题如果你像我一样把技能目录放到全局共享路径任何项目都能调用同一个技能库这时候要注意一个问题某些技能会被改写成能“记忆上下文”导致不同项目之间的记忆被串掉。我当时就遇到过一个很奇怪的现象在 A 项目里跑任务会话记录里出现了 B 项目的文件名。追查后发现问题出在技能文件里定义了一些绝对路径的检索逻辑而全局技能被两个项目共用记忆索引发生了串扰。解决方式很简单如果技能与特定项目逻辑强相关就把技能放到.superpowers/skills的本目录下而不是全局路径。这算是我踩得最深的一个坑。5.3 坑三自动化会话的“假完成”现象自动化会话在无人盯守时可能出现一个让我警惕的现象“它以为自己完成了但实际上并没有。”比如有一次我让它执行一个数据迁移脚本的生成任务它跑完之后输出了一段“迁移已完成”的日志但实际上它只是生成了脚本文件并没有执行迁移动作。后来我养成了一个习惯设置会话任务时在目标里明确区分“生成脚本”和“执行脚本”不让模型自己决定两者等价。凡是涉及外部副作用的操作在技能里应该显式规定“执行完成后必须输出验证命令和预期结果”。简单说自动化会话适合用来推进分析、生成、整理类工作不适合直接放权去执行不可逆操作。5.4 调试三板斧打印、会话回放、技能断点遇到问题怎么调试我常用的方式有三种都是低成本高回报的做法。第一种是开启详细日志在运行命令时加--debug参数观察技能加载过程。如果发现技能没有被引用优先检查路径和权限。第二种是回放会话。superpowers 会把每次会话存成 JSON 记录你可以用超能力会话回顾命令打开上一次会话的完整上下文看看模型当时是如何理解技能指令的。这一步在排查“为什么这次输出不符合预期”时作用非常大。第三种是我自己研究出来的偏方在技能文件中间插入一段“调试标记”让模型在执行到某一步时输出特定短语用来确认执行路径是否符合预期。定位到问题后去掉标记就行。6. 关于 superpowers 的后续扩展思路从使用者变成定义者到这里整个 superpowers 的使用闭环已经基本打通。但我想说的是真正让它产生“超级能力”复利效应的不是直接用官方提供的技能而是把自己团队的经验沉淀成自定义技能。这个部分我提供两个最实用的扩展方向以及附带的代码骨架。6.1 自定义技能的标准骨架这里是我常用的一个模板你可以照着改。以“数据库迁移检查”为例--- name: db-migration-check description: 检查数据库迁移脚本的安全性输出风险报告。 --- ## 执行步骤 1. 扫描项目中的迁移文件目录。 2. 对每个迁移文件检查是否包含破坏性操作DROP、DELETE 无 WHERE。 3. 若存在破坏性操作标注风险等级并给出替代方案。 ## 输出格式 ### 风险清单 - 文件路径 - 风险等级 - 具体问题 - 建议动作 ## 约束 - 必须逐文件检查不得跳过。 - 禁止未经确认直接修改数据库结构。写完之后放到.superpowers/skills/db-migration-check.md下次任务启动前说一句“激活 skill:db-migration-check”就能用。你会发现一个规律凡是团队里反复强调过 3 次以上的开发规范、检查清单、代码约定都值得被固化成技能。这个转化过程就是流程资产化的过程。6.2 团队级技能库的维护与迭代单机版 skill 足够个人使用但如果团队多人协作我更建议把技能库放进一个独立 git 仓库用 PR 流程来维护变更。每次有人总结出新的经验就发一个 PR其他人 review 后合并再同步到各自项目的技能目录。这里有一个实操细节技能库的每次变更建议配上版本说明说明“之前哪里不好用、现在改了什么”。因为技能的改动影响面可能很大一旦某个行为约束被放宽所有依赖它的任务都会跟着改变输出。我开始维护团队技能库之后才真正理解“提示词也是代码”这句话的分量。6.3 与 CI 工作流结合把技能变成自动化流水线最后一个扩展方向是把技能接入 CI 流程让静态的规则在代码合入前自动生效。比如我们可以定义一个ci-code-review技能在每次 Push 之后让 Codex 自动跑一次代码审查审查结果直接以评论形式提交到 PR 上。这个思路的执行前提是你已经拥有了稳定的技能输出否则自动化流程只会把不稳定的输出放大。所以我的建议是先在本地充分验证技能再上 CI。别一上来就把整个流程自动跑起来否则你会收到大量质量不一的机器评论最终大家只会选择忽略它。从我这段时间的实操感受来看superpowers 这类工具最值得投入的地方其实不在“某一个技能有多强”而在于它把 AI 编码从“不可预期的对话”变成了“可管理的工作流”。即使是同一个 Codex 模型在技能库完善前后的表现差距完全可以让人产生“换了个人”的错觉。如果你刚接触它我建议你先从最常用的三四个技能跑起跑熟了之后再慢慢把自己的经验写进去。这个过程不需要一步到位但每沉淀一个技能你之后的每一个同类任务都会省下一大段重复交代的时间。