superpowers:为Codex CLI注入记忆与检查点的AI编码工作流

说实话，我一开始对 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 不会马上动手改代码，而是先把这个需求拆解成一个任务清单，写进当前会话的工作区里。它会问到一些关键信息，比如输出文件格式、需要覆盖的范围。答完这些，你会看到它生成类似这样的清单：

1. 扫描项目全部依赖描述文件
2. 解析依赖关系并整理成结构化数据
3. 生成 Markdown 格式的依赖说明文档到 docs/dependencies.md
4. 自我检查清单完整性

看到清单生成，你就知道这个工具的思路了：让 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 依赖 service，service 依赖 dao，禁止反向依赖）。
• 统一异常处理的位置（新增异常必须放在 common.exception 包）。
• 数据库变更必须单独提交 SQL 脚本，不允许自动改实体类。

把这些写进记忆后，Act 模式的表现稳定很多。它改代码时会主动提到"根据记忆中的约束，这里不应该直接操作实体类"，然后停下询问我。这种"有意识的停顿"正是我要的效果。

另外 Java 项目有个天然便利：改动错误很难藏住，因为编译器会直接告诉你哪里有问题。我在 Act 模式执行完一个阶段后，会手动跑一遍mvn -q compile，确认没有新增编译错误再让它继续。这个习惯帮我拦下了不少低级问题。

3.4 检查点与回滚：怎么放心让 AI 改代码

敢让 AI 大规模改代码，底气完全来自检查点机制。superpowers 在每次任务阶段切换时都会自动提交，但提交粒度不一定符合你的预期。

我一般会在动手前自己先打一个手动检查点：

git tag sp-before-feature-xxx

然后让 AI 干活。如果后面发现改动方向不对，直接用 Git 回滚到这个 tag：

git 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 差不多，但可控性强很多。

具体步骤上，我建议按这个顺序来：

1. 先在空项目里跑通一个最简单的需求，熟悉 Think/Act 切换。
2. 把你的项目架构说明整理成文档，喂给 Think 模式写入记忆。
3. 挑一个边缘小功能做完整的迁移测试，习惯看清单和检查点。
4. 确认没问题后，再拿核心模块试水。

这套流程走下来，迁移过程通常两三天就能完成，而且你对新工作流的理解会比直接上来就用深得多。

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 排查速查表

这套排查表是自己在各种诡异情况里磨出来的，大部分问题其实都指向同一个根源：任务开始前没把约束写清楚。但凡你想省掉 Think 模式那几分钟，后面大概率要花几倍时间在返工上。

我个人现在最习惯的节奏是：每天开工前花十分钟，把当天要做的改动写进 brief，然后让 superpowers 在独立会话里干，我专注 review 它生成的检查点。用了一个多月，最大的感受是"用 AI 改代码"这件事从碰运气变成了一条有流程的流水线。工具本身还在快速迭代，但 Think 先于 Act 这个思路，我觉得是当前 AI 编码工具里最值得借鉴的设计——先想清楚，再动手，这句话同样也是对开发者自己说的。