说实话我一开始对 superpowers 这种带点中二感的项目名是持怀疑态度的。直到我把日常编码工作流彻底切到它上面用了一个多月才承认这个名字没起错。起因很简单裸用 Codex CLI 的时候它确实能改代码但它不记得自己上一秒决定过什么。你打断它让它别动某个文件转头它就把你刚确认的方案推翻了。superpowers 解决的正是这个问题——它给 AI 编码代理加了工作记忆、任务清单和检查点。听起来不玄实际用下来体感变化很大。这篇文章我打算按自己的实操路径来写覆盖安装、初始化、核心工作流、配置调优、踩坑排查这几个部分。无论你是刚听说这个名字还是已经装了但没跑顺或者正从其他 AI 工作流比如 worb 那套玩法迁过来应该都能找到能直接抄作业的内容。1. 先说清楚 superpowers 到底是什么1.1 它填了 Codex CLI 的一个大坑用过 Codex CLI 的人应该都有同感单次对话里它很聪明但一旦对话长了它就开始失忆。你前面跟它确认过架构方案后面它自己实现的时候能写出一个完全不符合方案的版本。不是它笨是它的上下文管理天然就是一次任务一次命。superpowers 不是要替代 Codex CLI而是给 Codex 这类编码代理套上一层工作流框架。它把让 AI 改代码这件事拆成两个阶段思考Think和执行Act。思考阶段负责把约束、方案、文件结构写进记忆文件执行阶段才让模型动手改代码。这样每次起新会话模型都能通过读记忆文件快速恢复上下文而不是靠对话历史猜你之前说了什么。用个生活化的类比裸 Codex 像一个很聪明但记性差的实习生你交代完事情转头他就忘superpowers 是给他配了一本工作日志每次干活前先翻日志再按日志里写的步骤来。你不指望他记住所有事你只指望他按流程办事。1.2 和裸 Codex CLI 比多了什么我整理了一下实际使用中的差异最直观的有四点会话记忆每次会话的决策、待办、约束都会落盘下次会话可以恢复。任务清单AI 自己把需求拆成步骤按序执行而不是一股脑改完所有文件。检查点回滚每次关键改动前自动建立 Git 检查点改坏了可以快速恢复。多角色分工架构师角色负责设计方案开发者角色负责写代码两个角色轮换执行。这几点单独拿出来都不稀奇但组合在一起效果完全不一样。以前我让 AI 改一个跨模块的功能它经常改完 A 忘了 B或者明明说了不要动测试文件它还是动了。现在这些约束都写进记忆文件每次执行前模型会自动读一遍再也不会出现我说过但你忘了的情况。1.3 谁适合用它如果你只是偶尔让 AI 写个脚本、补个正则那 superpowers 对你来说可能偏重裸 Codex 就够了。但如果你属于下面几类人我强烈建议试一下日常重度使用 AI 编码工具经常让 AI 改多个文件的开发者。需要在团队里推广 AI 辅助开发但担心 AI 乱改代码的 Tech Lead。维护老项目尤其是 Java 这种重结构项目需要 AI 先理解架构再动手的人。之前用过 worb 这类自主编码工作流觉得思路不错但缺少记忆和回滚能力的人。它适合的是把 AI 编码当成一条正经工作流来用而不是当一次性问答来用的人。门槛不高但需要你先接受把思考过程写下来这件事。2. 安装与初始化半小时跑通2.1 前置环境准备安装前先确认三件事缺一个后面都会卡壳。第一Node.js 环境。superpowers 主程序依赖 Node.js我建议装 LTS 版本18 以上。版本太老会出现各种奇怪的依赖报错排查起来很浪费时间。第二Codex CLI 已经配好并且能正常登录使用。因为 superpowers 本质上是调度 Codex 干活Codex 本身没配好superpowers 装了也没用。这里的认证配置直接用 Codex CLI 官方文档里的默认方式就行不需要额外设置。第三Git 初始化。superpowers 的检查点机制是基于 Git 的它会在项目目录里自动创建提交。如果项目目录还没有 Git 仓库初始化的时候它会尝试帮你建一个但我还是建议你自己先git init并提交一个初始版本这样后续回滚更干净。提示如果你是在公司内网环境用记得先确认 Codex CLI 本身的 API 访问是通的。我遇到过好几次superpowers 装好了但启动就报错最后查下来是 Codex CLI 的认证压根没通过。2.2 安装方式与验证安装命令很简单我这边用 npm 全局安装npm install -g superpowers装完以后验证一下superpowers --version如果输出了版本号说明主程序装好了。有些环境里会提示command not found这通常是 npm 全局 bin 目录不在 PATH 里后文排查部分我会细说。除了 npm项目仓库的 README 里也会提供其他安装方式。我个人的建议是除非你有特殊理由否则优先用包管理器装方便后续升级。我见过有人直接源码 clone 下来跑升级的时候容易忘过俩月就落后一个大版本。装好之后在项目目录里运行superpowers init它会自动检测当前目录的 Git 状态和语言类型生成一个.superpowers目录。看到输出里有Initialized字样就说明成功了。2.3 初始化项目并理解生成的文件初始化完成后进入.superpowers目录看一下你会看到几个子目录和文件。这些文件看起来不起眼但整个工作流的灵魂都在里面。最核心的是memory.md。这个文件用来记录项目的长期约束、架构决策、哪些文件不能动等重要信息。它跟会话日志的区别在于会话日志是流水账memory 是沉淀下来的高价值信息。我会在 Think 模式里把需要长期记住的东西写进去。然后是一个briefs/目录用来存放任务简报。每次你要让 superpowers 干活之前通常要先写一个 brief描述这次要做什么。它有点像给 AI 的工作派单写清楚需求、范围、验收标准。还有一个sessions/目录每次会话的运行记录都存在这里。包括模型的输出、执行步骤、检查点状态。后面你想复盘上次它到底改了哪些文件翻这个目录就行。注意.superpowers目录要提交到 Git 仓库里。我最初以为它是本地缓存加进了.gitignore结果团队成员各自为战记忆文件完全没同步。后来把它提交上去新成员 clone 下来就自带全部上下文上手快很多。2.4 第一次会话从想法到任务清单初始化完先别急着写代码跑一个最简单的会话感受一下。在项目目录里启动superpowers进入交互式界面后你看到的不是普通聊天窗口而是一个有两个模式切换的界面Think 和 Act。初次使用先从 Think 模式开始。输入一个简单需求比如这个项目的依赖关系整理一下输出到 docs 目录。superpowers 不会马上动手改代码而是先把这个需求拆解成一个任务清单写进当前会话的工作区里。它会问到一些关键信息比如输出文件格式、需要覆盖的范围。答完这些你会看到它生成类似这样的清单扫描项目全部依赖描述文件解析依赖关系并整理成结构化数据生成 Markdown 格式的依赖说明文档到 docs/dependencies.md自我检查清单完整性看到清单生成你就知道这个工具的思路了让 AI 活干之前先把活想明白。这一步其实就是它区别于裸 Codex 的最大分野。3. 核心工作流Think / Act 双模式与 Java 项目实战3.1 Think 模式把约束写进记忆Think 模式是 superpowers 最有价值的地方也是最容易被新手跳过的地方。很多人上来就切 Act 模式让它改代码结果又回到了裸 Codex 的老路——改完发现跟期望不符。Think 模式要干的事很简单把这次任务涉及到的背景、约束、方案全部写进记忆。我通常会在 Think 模式里跟它对话确认以下信息项目当前的整体结构是怎样的。这次改动涉及哪些模块哪些模块严禁触碰。技术选型有没有限制比如 Java 项目必须用某个版本的 JDK。代码风格和测试要求是什么。它会把对话中确认过的重要内容自动追加到 memory.md。注意是追加不是覆盖。所以你在 Think 模式里说的每一句有效信息都会成为后续所有会话的上下文。我自己的习惯是每次开始一个新功能先花五到十分钟进 Think 模式把功能目标、涉及文件、约束条件跟它过一遍。等清单生成并且确认无误后再切到 Act 模式。这个过程看起来比裸 Codex 多了一步实际上省掉的是后面反复纠偏的时间。3.2 Act 模式让 AI 按清单执行确认清单没问题后切到 Act 模式。这时候 AI 才真正开始改文件。Act 模式跟普通 AI 编码的最大区别是它严格按照清单逐项执行。执行完当前这一步会回头验证一下这一步是否完成然后才进入下一步。每完成一个阶段它会主动创建一个 Git 检查点提交信息由它自己生成。我在实际使用中发现一个很关键的点Act 模式下尽量不要中途打断它。如果你发现清单本身有问题应该先切回 Think 模式修正记忆和清单再回到 Act 模式继续。因为中途随便插入新指令它会尝试把新指令塞进当前步骤里容易打乱节奏。如果确实需要中途停可以用它内置的暂停快捷键先停下来查看当前改动确认没问题再继续。这比强行中断进程要安全得多。3.3 Java 项目里的实际配置很多人都问 superpowers 对 Java 项目支持怎么样毕竟 Java 项目结构重、依赖多、改起来牵一发动全身。我自己在一个 Maven 管理的 Spring Boot 项目上用了一个多月说说实际体验。第一次接 Java 项目时Think 模式里一定要先把项目的模块边界讲清楚。比如core 模块是领域层不能依赖 infrastructure 模块这种约束刚开始不写清楚Act 模式里模型很容易在 package 依赖上放飞自我。我在 memory.md 里维护的信息包括JDK 版本约束必须是 17不能用 21 特性。Maven 模块结构web 依赖 serviceservice 依赖 dao禁止反向依赖。统一异常处理的位置新增异常必须放在 common.exception 包。数据库变更必须单独提交 SQL 脚本不允许自动改实体类。把这些写进记忆后Act 模式的表现稳定很多。它改代码时会主动提到根据记忆中的约束这里不应该直接操作实体类然后停下询问我。这种有意识的停顿正是我要的效果。另外 Java 项目有个天然便利改动错误很难藏住因为编译器会直接告诉你哪里有问题。我在 Act 模式执行完一个阶段后会手动跑一遍mvn -q compile确认没有新增编译错误再让它继续。这个习惯帮我拦下了不少低级问题。3.4 检查点与回滚怎么放心让 AI 改代码敢让 AI 大规模改代码底气完全来自检查点机制。superpowers 在每次任务阶段切换时都会自动提交但提交粒度不一定符合你的预期。我一般会在动手前自己先打一个手动检查点git tag sp-before-feature-xxx然后让 AI 干活。如果后面发现改动方向不对直接用 Git 回滚到这个 taggit checkout sp-before-feature-xxx -- .这种方式比依赖 AI 自动检查点更可靠因为自动检查点是在它自己觉得完成了的时候创建的而你觉得不对的点可能跟它不一致。还有一点要注意检查点不是万能的。如果 AI 执行中途改了数据库脚本而且这个脚本已经跑过了那回滚代码文件并不能回滚数据库状态。所以涉及数据库变更的任务建议先把数据库脚本单独备份一份再让 AI 动手。4. 配置调优让 superpowers 更贴近你的团队4.1 模型与上下文控制superpowers 默认调用 Codex CLI 配置的模型但实际用下来不同任务的模型偏好有差异。架构设计、整理任务清单这类的 Think 模式任务我倾向于用一个推理能力更强、更慢的模型让方案更严谨。纯执行类的 Act 模式任务可以用一个响应更快、成本更低的模型因为执行逻辑已经通过清单约束好了不需要它额外发挥。配置方式一般是在 superpowers 的配置文件里指定模型组我的做法是{ model: { think: reasoning-model, act: fast-model } }具体模型名看你 API 环境里能用什么。重点在于思路把想和做拆给不同模型整体成本反而比全部用强模型更低执行速度更快。上下文控制方面我发现记忆文件不是越写越长越好。memory.md 塞到几百行之后模型读取和忽略关键信息的概率都会增加。我的经验是每个阶段结束时花点时间把 memory.md 里已失效的内容删掉保持精简。这跟维护代码库是一个道理欠债太多终归要还。4.2 多会话并行与任务隔离superpowers 支持同时开多个会话每个会话有独立的上下文和记忆。这意味着你可以让一个会话跑 A 功能的重构另一个会话跑 B 功能的 bug 修复互不干扰。但并行有个前提两个任务尽量不要改同一个文件。否则 Git 检查点会打架回滚一个会影响另一个。我的做法是按模块划分任务边界。比如模块 A 的改动开一个会话模块 B 的改动开另一个会话它们各自的检查点互不相关。任务隔离还有一个好处一个会话如果跑偏了直接丢弃这个会话就行其他会话完全不受影响。以前我在裸 Codex 里开多个对话经常搞混哪个对话改的是哪块代码现在每个会话就像一个独立的工作分支状态一目了然。4.3 从其他 AI 工作流迁移比如 worb 系列最近不少从 worb 这类 AI 自主编码玩法转过来的朋友问我之前那套习惯怎么搬到 superpowers 上我的回答是思路可以完全平移但要接受一个关键差异。worb 类工具更强调让 AI 多跑一会儿尽量少打扰superpowers 则强调先想清楚再执行。迁移时你要做的第一件事是把你以前在脑内完成的需求拆解转移到 Think 模式的清单里。以前你可能直接扔给 AI 一个需求让它自己折腾现在你花几分钟跟它确认边界、生成清单剩下的活儿它自己干。整体下来AI 自主发挥的空间和 worb 差不多但可控性强很多。具体步骤上我建议按这个顺序来先在空项目里跑通一个最简单的需求熟悉 Think/Act 切换。把你的项目架构说明整理成文档喂给 Think 模式写入记忆。挑一个边缘小功能做完整的迁移测试习惯看清单和检查点。确认没问题后再拿核心模块试水。这套流程走下来迁移过程通常两三天就能完成而且你对新工作流的理解会比直接上来就用深得多。4.4 团队协作规范建议团队使用 superpowers最怕的是一半人用了、一半人没用结果记忆文件被各种互相覆盖。我们团队最后定下来的规范是每个功能分支必须独立跑一个 superpowers 会话不得在主分支上直接让 AI 改代码。每次启动会话前先git pull同步最新的.superpowers/memory.md避免基于过期记忆干活。涉及架构方向的约束只能由架构师角色写入 memory.md开发者角色只能追加任务细节。所有 AI 自动生成的检查点提交合并前必须 rebase 成一个干净的提交避免提交历史里塞满AI commit。这些规范不是写出来好看的真的能少吵很多架。尤其是 memory.md 的写入权限如果不加限制每个人把个人偏好都塞进去最后记忆文件会变成一锅粥模型反而不知道该听谁的。5. 踩坑记录与排查速查表5.1 安装后 command not found这个是我见过最多的问题。装完执行superpowers提示找不到命令不是没装上而是 npm 全局 bin 目录没在 PATH 里。先查一下 npm 全局目录npm config get prefix然后把输出目录下的bin路径加到 shell 配置文件的 PATH 里。以 bash 为例export PATH$(npm config get prefix)/bin:$PATH加完重开终端命令就能找到了。这个问题跟 superpowers 本身没关系是 Node.js 环境的通病但卡住的人不少。5.2 模型输出被截断用长上下文任务时偶尔会遇到模型输出到一半被截断执行状态卡住不动。我排查后的主要原因是单个步骤里让它做的事太多。它的清单步骤拆得不够细一步里塞了大量改动模型一次性输出超过限制就被砍了。解决办法有两个一是在 Think 模式里明确要求步骤粒度控制在单文件级别二是直接把大步骤在清单里拆掉让它每次只动一个文件。我倾向用第二个办法因为粒度变细之后检查点的位置也更精确。5.3 循环停不下来Act 模式有时候会陷入某种循环比如自检不通过就反复修改同一个地方。遇到这种情况先别急着把进程杀了。先看一下它反复修改的理由如果理由是同一个且次数超过三次大概率是记忆里没有给出足够的约束。切回 Think 模式把此问题改用其他方案处理写进记忆再切回 Act 模式让它继续。如果切出去再切回来还在循环那就直接丢弃当前会话重新开一个在 brief 里明确写出如果连续两次自检不通过停止并向我询问。把停止条件写清楚比在循环中干预高效得多。5.4 Git 提交过乱AI 自动提交的粒度有时候让人抓狂。它可能为一个单文件改动创建三个提交也可能所有文件混在一个提交里。我在配置里开启了提交合并选项后情况好很多。另外也建议你给自动生成的提交信息格式加上约束比如默认添加[ai]前缀这样一眼就能分辨哪些提交是 AI 生成的review 的时候可以快速筛选。5.5 排查速查表症状可能原因处理方式命令找不到npm bin 目录不在 PATH将 npm prefix/bin 加入 PATH初始化卡住Codex 认证未通先验证 Codex CLI 可独立使用执行中途截断单步骤粒度太大强制拆分为单文件步骤反复修同一处缺少约束记忆Think 模式补充规则并重置会话提交历史混乱自动提交粒度不合适开启提交合并并加 [ai] 前缀并行会话互相干扰任务边界重叠按模块划分会话边界检查点回滚丢了新代码回滚了不同会话的改动确认两个会话无文件交集这套排查表是自己在各种诡异情况里磨出来的大部分问题其实都指向同一个根源任务开始前没把约束写清楚。但凡你想省掉 Think 模式那几分钟后面大概率要花几倍时间在返工上。我个人现在最习惯的节奏是每天开工前花十分钟把当天要做的改动写进 brief然后让 superpowers 在独立会话里干我专注 review 它生成的检查点。用了一个多月最大的感受是用 AI 改代码这件事从碰运气变成了一条有流程的流水线。工具本身还在快速迭代但 Think 先于 Act 这个思路我觉得是当前 AI 编码工具里最值得借鉴的设计——先想清楚再动手这句话同样也是对开发者自己说的。