1. superpowers 是什么：我给 Codex CLI 装的这层"技能包"

先给还没接触过的朋友一句话介绍：superpowers 是一个开源插件项目，作者在 GitHub 上的仓库名是 obra/superpowers，它把"技能、记忆、角色分工"这三样东西打包，接到 OpenAI 官方的 Codex CLI 和 Claude Code 这类终端 AI 助手上面。我这个月几乎每个工作日都在用，最大的感受可以用一句话概括：装上之前 Codex 像一个记性很差但很聪明的实习生，装上之后像一个手里有标准作业流程的老师傅。

先说痛点。Codex CLI 本身的能力不弱，它能读你的仓库、跑编译、跑测试、改代码，但它有两个天然短板。第一是没有跨会话记忆，昨天定好的技术方案，今天新开一个会话它完全不记得，你得重新把背景讲一遍。第二是没有内建的工作流程，你让它"用 TDD 的方式实现一个功能"，它可能会先写实现再补测试，甚至把测试和实现一次性全给你写完，根本没经历红绿重构的过程。这两个问题在小 demo 上不明显，一旦放到真实项目里，效率差距就非常大了。

superpowers 解决的就是这两件事。它把"该怎么做一件事"写成 markdown 技能文档，agent 遇到对应任务时按需查阅、按步骤执行；同时提供一套长期记忆机制，把关键的技术决策、项目约定、个人偏好存成文本文件，下次会话继续使用。它还带了一套角色体系，可以在一个会话里让 agent 切换不同的身份来分工协作。

这篇文章不是官方文档的翻译，是我自己实际用了一个月之后的完整记录：怎么装、怎么配、怎么在 Java 项目里跑通 TDD 流程、记忆系统怎么管、以及我踩过的几个坑。适合两类人看：一类是已经在用 Codex CLI 但觉得它"不够靠谱"的开发者，另一类是刚听说 superpowers 这个词、想搞清楚它到底能干什么的人。

1.1 为什么"技能包"比"多写几句提示词"有效

很多人第一反应是：我不装插件，直接在系统提示词里写"你要遵循 TDD、要写记忆"不就行了？我一开始也是这么想的，实际试下来发现差很远。

提示词是一次性的、静态的。你写在配置里那几句话，agent 每次会话都会看到，但它不会因为你写了"要遵循 TDD"就真的去遵循。原因很简单：上下文窗口里同时有很多指令，提示词只是一句话，没有任何操作细节，agent 很容易把它当成"用户偏好"而不是"必须执行的流程"。技能文档则完全不同，它是一份完整的操作手册，包含具体的步骤、检查点、完成标准。当 agent 判定任务匹配某个技能时，它会把整份手册读进上下文，然后按步骤执行，每完成一步还要自检。

另一个关键差别在于可维护性。提示词是死的，你改一次要重新加载配置；技能是活的，它是一堆独立的 markdown 文件，你可以随时往技能库里加新的技能，也可以让 agent 在实际执行过程中帮你完善某个技能文档。这就像你把团队的新人培训手册从"一段口头叮嘱"升级成了"一份可以不断迭代的 SOP"。

1.2 技能、记忆、角色：superpowers 的三个支柱

拆开来看，superpowers 做的事情其实不复杂，就三块。

第一块是技能库（Skills），也是核心。它的目录下按领域放了很多 markdown 文档，比如测试驱动开发、调试排错、代码审查、写技术方案、做依赖升级等等。每个文档描述一个完整的工作流程，agent 遇到对应场景就去查阅并按流程执行。技能库不是固定的，你可以写自己的技能，比如"发布前检查清单""数据库迁移流程"，相当于把团队规范变成了 agent 能自动执行的东西。

第二块是记忆（Memory）。超级助手最烦人的一点就是每次会话都"失忆"，superpowers 用纯文本文件把关键信息落盘。某个项目用了什么技术栈、你偏好的代码风格、已经拍板的技术决策，都可以写进记忆文件。下次会话 agent 启动时先查记忆，就能接上上次的话头。它不只是存你显式告诉它的东西，还可以在会话结束时自动总结本次的结论写入记忆。

第三块是角色（Agents）。它在一个人机对话会话里支持多种角色切换，比如项目经理角色负责拆任务、开发角色负责写代码、调试角色负责排查问题。听起来很玄，本质就是不同的角色对应不同的行为约束和上下文，让 agent 在会话里"分身"完成各环节的工作。

这三块叠加起来的效果，是从"一个会聊天的代码补全工具"变成"一个能独立推进任务的工程协作者"。当然它不是万能的，底层的 Codex 模型能力决定了天花板，superpowers 做的是把天花板下面那部分"流程纪律"补上。

2. 安装与初始化：从零到能用的完整流程

这部分写给还没装过的人。我装的时候踩了不少坑，这里给出一条完整可复现的路径，从环境准备到验证生效，每一步都说清楚为什么这么做。

2.1 环境准备：先确认这几样东西

在装 superpowers 之前，我建议你先把基础环境理清楚，缺任何一样后面都会出怪问题。

首先是操作系统。superpowers 的安装脚本是 shell 脚本，macOS 和 Linux 上最顺畅，Windows 用户建议用 WSL2，在 WSL 里装 Linux 发行版再操作，比在 PowerShell 里硬折腾省心得多。我最初就是在 Windows 原生环境里试的，结果光是路径分隔符和权限问题就耗了半天。

然后是 Node.js。Codex CLI 本身是 npm 包，需要 Node.js 环境，建议 20 及以上版本。你可以在终端里执行node --version确认，如果版本太老，建议先升级，否则后面装 Codex CLI 或者插件时经常出现莫名其妙的依赖问题。

最后也是最重要的：你必须已经有一个能正常使用的 Codex CLI。如果没有，先执行下面的命令安装并登录：

npm install -g @openai/codex codex --version codex login

codex login会走浏览器的 OAuth 流程，登录成功后 Codex 才能调用模型。这一步完成标准是：你在终端里敲codex，随便问一句"你好"，它能正常回复。基础环境到这一步就绪，后面装 superpowers 才有意义——插件只是增强层，底层 agent 必须本身能跑通。

2.2 三步完成安装

superpowers 的安装方式很直接，就是克隆仓库然后跑安装脚本。我推荐的路径：

git clone https://github.com/obra/superpowers.git cd superpowers ./install.sh

这里有个重要的选型问题：clone 到哪个目录。很多教程直接让你 clone 到临时目录，装完就把仓库删了，结果过两天技能文件全丢了。我的建议是 clone 到一个固定位置，比如~/superpowers或者~/.codex/superpowers，让它长期待在那里。原因后面讲踩坑的时候会细说。

安装脚本做的事情，大致可以理解为三步。第一，把插件的技能库、入口指令、辅助脚本复制到 Codex 的配置目录（通常是~/.codex下面的某个子目录）；第二，在你的 Codex 全局配置里追加一段入口说明，让 agent 每次启动都知道自己有一份技能库和记忆库可以使用；第三，创建记忆目录和初始文件。整个过程中如果遇到Permission denied之类的权限报错，先给脚本加执行权限再重新跑：

chmod +x install.sh ./install.sh

2.3 装完怎么确认真的生效了

装完不等于生效，很多人的问题恰恰出在"以为自己装好了"。我的验证习惯是三步走。

第一步看配置。打开~/.codex/config.toml，正常情况下应该能看到和 superpowers 相关的引用，可能是一段说明文字，也可能是指向某个文件的路径。如果你完全看不到 superpowers 相关的内容，说明安装脚本没有正确修改配置，需要重新跑。

第二步开一个新会话直接问。在终端里运行codex开一个新会话，然后问它："你当前加载了哪些技能？请把你知道的 superpowers 技能列出来。"如果它一脸茫然甚至说不知道 superpowers 是什么，那说明入口指令没有生效，多半是配置没加载。这里有个细节：一定要开新会话，旧的会话上下文里没有新的配置。

第三步验证记忆目录。执行ls看一下~/.codex下面有没有生成 superpowers 相关的目录结构，里面应该有记忆文件。如果目录结构都不存在，说明安装脚本执行不完整，回到上一步重新检查。

这三步全过，才算真正装好了。我见过不少人在第一步就发现配置根本没被改，还以为是自己的问题——其实就是安装脚本某个环节静默失败了，这种情况下面有专门的排查章节。

3. 配置机制拆解：技能为什么是"按需加载"而不是"全塞进上下文"

理解了安装流程，还得理解它的工作机制，否则你遇到问题根本不知道从哪下手。这一节我把 superpowers 的配置和加载逻辑拆开讲清楚。

3.1 技能文件长什么样

技能的本质是一个 markdown 文档，通常放在技能库的 skills 目录下，每个技能一个子目录。我打开过几个技能文件看，结构基本是：文件开头有一段"元信息"，写清楚技能叫什么、在什么场景下使用、触发关键词是什么；正文是操作步骤，每一步都有明确的动作和完成标准。

以 TDD 技能为例，它写的不是"你要写测试"这种空话，而是一步一步的流程：先根据需求写出一个会失败的测试用例；运行测试确认它在预期的地方失败（红灯阶段）；写最小实现代码让测试通过；再次运行全部测试确认没有破坏其他功能（绿灯阶段）；最后在测试保护下做重构。每一步都有检查点，比如"如果测试没有先失败就通过了，那么说明测试写错了，需要回头检查断言"。

这个格式本身就是有用设计的核心。agent 读技能文档时，它不是在读一句口号，而是在读一份可以被检查的操作清单。它能按步骤执行，还能自我检查是否跳步。这是普通提示词完全做不到的。

3.2 按需加载：为什么上下文不会被撑爆

很多人担心：如果技能库里有几十个技能，每个文档还那么长，Codex 的上下文窗口装得下吗？这正是 superpowers 设计上最巧妙的地方——它不会把所有技能一次性塞进上下文。

实际的加载机制是分层的。每次会话启动时，agent 只读取一个入口索引，这个索引比较短，大致写着"你有一个技能库，当遇到 XX 类型任务时，去查技能目录下的技能列表，找到匹配的技能文档再阅读"。当你的任务进来了，比如你说"帮我写一个测试"，agent 先看技能列表，发现"测试驱动开发"这个技能与任务匹配，于是它调用读文件能力打开对应技能文档，把完整流程读进上下文，然后才动手。

这个"先索引，再按需展开"的机制，让它能维护一个大技能库而不影响日常对话的上下文占用。我自己的经验是，技能越多越好，只要描述写得清晰，agent 就能准确匹配，不会出现"技能太多导致对话变笨"的情况。反过来如果你把几十个技能全写进一个文件里让 agent 每次启动都读，上下文很快就不够用了，对话质量会明显下降。

3.3 记忆是怎么读写和落盘的

记忆机制的实现同样很朴素：就是一堆 markdown 文件，放在记忆目录里。目录通常按项目或按主题分成多个文件，比如memory/spring-boot-project.md、memory/个人偏好.md这种粒度。

读取时机是会话开始。入口指令会提示 agent 先查看记忆目录，了解这个项目的背景和已经做过的决策，再开始干活。这就是它能"接上上次话头"的原因。写入时机主要是两类：一类是你明确告诉它"记住这条约定"，agent 会把内容追加到对应记忆文件；另一类是会话结束时，agent 总结本次的关键决策写进记忆里。

这个机制的关键在于规则要写清楚。我刚开始用的时候，agent 经常不主动写记忆，后来我在会话里加了一条固定指令："每次会话结束前，把本次做出的技术决策和原因写入记忆文件。"从那以后就稳定多了。你不需要懂代码，只需要理解一个原则：记忆文件是给 agent 看的"项目维基"，你对它写什么，它下次就"记得"什么。

3.4 入口指令生效的底层逻辑

入口指令到底是怎么让 agent 遵守的？说白了，就是配置文件里那一段说明，让 Codex 每次启动时都读到它。它相当于给 agent 设定了一个初始上下文：你是谁、你有哪些工具、遇到什么情况该怎么做。

这个机制和 AGENTS.md 很像，但更进一层。AGENTS.md 是项目级的静态说明，告诉 agent"这个项目是什么样的"；superpowers 的入口指令是动态的，它不仅描述现状，还定义了 agent 的"行为方式"——去哪里找技能、去哪里查记忆、什么时候写记忆。打个比方：AGENTS.md 是公司的规章制度海报，superpowers 是给新人配的导师手册，后者告诉你遇到具体事情该找谁、按什么流程办。

理解这一层之后，遇到"配置没生效"之类的问题，你就知道排查方向了：先看入口指令有没有被 agent 读到，再看技能有没有正确匹配，而不是像无头苍蝇一样乱试。

4. 实战：用 TDD 技能在 Java 项目里开发一个计算器

光讲概念没用，直接上实战。这一节我用一个完整的 Java Maven 项目演示 superpowers 的 TDD 技能怎么约束 agent，同时对比一下"有技能"和"没技能"的行为差异。

4.1 为什么用 Java 举例而不是 Python

我查了最近的热搜词，发现很多人搜"superpowers java"，说明大家最关心的是这工具在 Java 这种重型项目里到底好不好用。我特意选 Java，有三个原因。

第一，Java 项目的步骤链路长：先有 Maven 或 Gradle 构建，再有编译、测试、打包多个环节，任何一个环节出问题都会让整个流程卡住。这种项目最需要流程纪律，也最能体现技能的价值。第二，Java 的编译器很严格，agent 想"蒙混过关"很难，代码有问题直接编译失败，瞒不过去。第三，Python 项目里 agent 的自由度大，很多时候跳步了也不报错；Java 项目里你要是跳了"先写测试"这一步，直接就露馅了。所以拿 Java 演示，说服力最强。

4.2 五分钟准备一个可运行的 Maven 项目

先创建项目骨架。用 Maven 的 archetype 生成一个最简的 Java 项目：

mvn archetype:generate \ -DgroupId=com.example \ -DartifactId=calc \ -DarchetypeArtifactId=maven-archetype-quickstart \ -DinteractiveMode=false cd calc

接着在pom.xml里加上 JUnit 5 依赖，否则 agent 写测试的时候会因为没有测试框架而卡住。我把加入依赖单独拿出来说，是因为这个细节特别容易忽略：你要是没提前配好测试框架，agent 可能会自己上网搜依赖并写进 pom.xml，这样也不是不行，但一来耗时，二来容易引入版本冲突。提前配好，让它专注于业务逻辑：

<dependency> <groupId>org.junit.jupiter</groupId> <artifactId>junit-jupiter</artifactId> <version>5.10.2</version> <scope>test</scope> </dependency>

配好后跑一次mvn test确认项目本身是健康的。这一步很重要，它建立了"初始状态正常"的基线，后面 agent 改乱了代码你马上能分辨出来。

4.3 在会话里让 agent 按 TDD 技能干活

项目就绪后，开一个 Codex 会话，工作目录切到calc下，然后输入这样的指令：

这是一个 Maven Java 项目。请使用你掌握的 TDD 技能，为 Calculator 类实现一个整除方法 divide(int a, int b)，要求：两个整数相除返回 int；除数为零时抛出 IllegalArgumentException。

接下来重点观察它的行为序列，这是判断技能是否真正生效的关键。

我的实测里，agent 的行为是这样的：先是静默片刻，它应该是在技能库里找到了 TDD 技能文档并读取了流程；然后它没有直接写实现，而是先创建了CalculatorTest.java，写了三个测试用例：正数相除、整除结果、除数为零抛异常；写完测试后它主动执行了mvn test，验证测试处于失败状态——这一步通常会有编译失败，因为Calculator类还不存在，但这正是红灯阶段应该有的状态。

看到测试失败后，它才开始创建Calculator.java，写了最简单的实现。再跑一次mvn test，这次测试通过了。最后它没有立刻收工，而是停下来问我："测试覆盖了异常场景和正常场景，是否需要补充边界用例？"整个过程就是标准的 Red-Green-Refactor，我没有额外催促，它自己就按流程走完了。

这个结果让我挺惊讶的，因为就在前一周，同一个项目、没有 superpowers 的时候，我给 Codex 下了几乎一样的指令，它直接噼里啪啦把Calculator.java和CalculatorTest.java一次写完，然后告诉我"完成"。表面上效率很高，但仔细观察它的测试没什么边界意识，而且它完全没有先跑一次失败的测试来验证测试本身是有效的——这意味着它写的测试到底能不能测出问题，它自己也不知道。

4.4 有技能和没技能的对比

我把两轮实验的行为列成了一张表，差异一目了然。

注意我并不是说没技能时 Codex 永远做不好，它有时候也会写得挺好。但没有流程约束的时候，它的行为是不可预期的：这次很好，下次可能就把异常处理丢了。技能的作用是把"高质量行为"变成"稳定复现的默认行为"，这才是它最重要的价值。

4.5 实测中的几个注意事项

第一，首次运行mvn test时 Maven 需要下载大量依赖，可能卡几十秒甚至更久，agent 有时候会误以为命令卡死而中断操作。我建议在进入会话前先手动跑一次mvn test把依赖缓存好，可以省掉很多麻烦。

第二，agent 执行命令需要权限。Codex CLI 默认会请求你授权运行命令，你在会话里尽快给它授权，否则它跑测试的过程会反复被打断。如果公司电脑有严格的执行策略，建议先在企业环境里评估好权限方案再引入这个工具。

第三，技能不是"一次加载永远有效"。如果你发现 agent 开始跳流程了，通常是因为会话上下文被其他内容冲掉了技能文档的注意力。这时候最简单的做法是重新提一句："请回顾你加载的 TDD 技能，按照它的流程继续。"这一句话往往就能把它拉回正轨。

5. 跨会话记忆：让 Codex 过一夜还记得你的技术决策

如果说技能是 superpowers 的"工作方式"，那么记忆就是它的"大脑存储"。这一节我讲一个真实的隔夜实验，以及我在使用记忆功能过程中总结出来的一套方法。

5.1 一个真实的隔夜实验

我手头有个 Spring Boot 项目，对象转换一直用的手写工具类。有一天我让 Codex 帮我评估要不要引入 MapStruct，它在会话里分析了依赖注入、性能、可维护性几个维度，最后建议引入 MapStruct，还把理由写在了对话里。会话结束时，我补了一句："把这次的技术决策和理由写入记忆文件。"

第二天新开一个会话，我故意没有提供任何背景，直接问它："这个项目的对象转换方案定了吗？"它沉默了一下，然后回答："根据之前的决策，本项目使用 MapStruct 替代手写转换器，理由是统一类型转换逻辑、减少样板代码、提升可维护性。当前迁移状态记录在项目的迁移计划中。"那一刻确实有点震撼——它真的"记得"昨天的事情。

作为对比，我在另一个没有记忆功能的环境里做过同样的实验：第一天明确告诉 Codex 一个技术约定，第二天新会话里问它，它完全想不起来，重新把代码读了一遍又给了一套新的建议，甚至和昨天的结论相反。这个对比很好地说明了记忆功能为什么重要：AI 的聪明程度在一个会话内是稳定的，但跨会话的能力完全取决于有没有持久化机制。

5.2 我总结出的记忆使用三板斧

第一板斧：会话结束前固定让它总结并写入记忆。我几乎每次会话结束都会说："请把本次会话的关键决策、原因、以及尚未完成的事项写入记忆文件。"这句话的效果立竿见影，它会把散落在对话里的信息结构化地落到 markdown 文件里。你不需要知道它具体写了什么，下次会话它能回答出来就是有效。

第二板斧：项目开始时让它先查记忆再看代码。开新会话的第一条指令我通常会写："先查看记忆目录，了解这个项目的背景和技术决策，再开始分析。"这样它就不会一上来就闷头读全部代码，而是带着记忆里的上下文去匹配代码，效率高很多。这里要注意，你要确认它真的去查了记忆文件，而不是随口答应。可以追问一句："你刚才查到了哪些和本项目相关的记忆？"确认它确实执行了。

第三板斧：重要的约束要明确说"记住"两个字。普通对话里说的话，agent 不一定认为需要写入记忆；但如果你说"记住这条约束：本项目的数据库迁移脚本必须由人工执行"，它就会把这条约束写入记忆文件，并且后续会话都会遵守。这相当于给 AI 一个显式的"写盘指令"。

5.3 记忆文件膨胀了怎么办

记忆机制用久了必然面临一个问题：文件越来越大，agent 每次会话都要读大量历史，反而拖慢分析速度。我遇到过一次，agent 在会话开始时读了一个 3000 多行的记忆文件，结果光"理解上下文"就花了很长时间，而且有些历史决策已经过时，误导了当前任务。

我的建议是三条。第一，按项目分文件，不要一个全局文件装所有内容；每类主题一个文件，让 agent 能精确读取。第二，只记决策和约束，不记过程。agent 不需要记住"我昨天花了三小时排查了一个问题"这个过程，它只需要记住"最终决定使用方案 A"这个结论。第三，定期手动清理，把过时决策标记为"已废弃"，或者干脆删掉。我大概是每两周清理一次，把已经落地的决策归档，只留下仍然有效的约束。

还有一个教训：别把敏感信息写进记忆文件。因为记忆文件是纯文本存放在本地，如果里面有数据库密码、API Key 之类的机密，一旦泄露就是事故。把这里当成"开发笔记本"来对待，只记工程决策，不记密钥凭据。

6. 踩坑记录：安装和使用的四类问题排查链路

工具再精巧也是软件，我用下来遇到不少问题。这一节我不直接给答案，按照我实际排查的顺序来写，因为学会排查思路比记住答案更有用。

6.1 报错一：安装脚本报 Permission denied

我第一次运行./install.sh就报错了，提示权限不够。很多人都遇到这个问题，因为仓库拉下来的文件默认没有执行权限。解决很简单：

chmod +x install.sh ./install.sh

这个坑本身不难，但它带出了一个更大的坑：如果安装脚本在某个步骤静默失败，你是看不到明确报错的。所以装完一定要回到前面说的"三步验证"那里检查配置和目录结构，确认真的生效了。权限问题只是最表面的一层，下面往往还藏着别的问题。

6.2 报错二：配置改写了但 agent 不认识 superpowers

这是最让人困惑的一类问题：安装脚本正常完成，config.toml里也能看到 superpowers 的内容，但新会话里问 agent，它一脸茫然。我的排查链路是这样的。

第一步，确认 Codex CLI 版本。codex --version看看版本号，如果版本比较旧，可能不支持配置里的某些字段。这就像你给一个老系统加了新配置项，它不认识自然不生效。解决方法是升级：

npm install -g @openai/codex@latest

升级后重新开一个会话再问一次。

第二步，确认入口指令在会话里真的被读到了。你可以直接问 agent："你的系统级指令里有哪些？请复述其中关于技能的部分。"如果它复述不出来，说明入口指令根本没加载，原因多半是配置文件解析失败或者缓存问题。这时候可以删掉会话记录缓存，重新开一个干净会话。

第三步，如果还不行，干脆把config.toml里 superpowers 相关的段落截图记下来，然后删掉，重新跑一遍安装脚本，让它重新写入。很多时候重装比手动修改配置更干净。

6.3 报错三：技能文档路径不对，agent 找不到技能

有一次我把 superpowers 仓库 clone 到了/tmp/superpowers这个临时目录，安装跑完一切正常。过了两天系统清理临时目录，仓库被删了，然后 agent 就再也找不到技能了。排查了半天才发现，入口指令里写的技能路径指向的还是那个临时目录。

这个坑的教训是：路径在安装时就被写死进了配置，所以安装前就要选好固定目录。我的经验是 clone 到~/.codex/superpowers，让它和配置在一起。如果你想改位置，改完之后需要重新跑安装脚本，让入口指令里的路径同步更新。不要手动去改路径字符串，容易漏改。

6.4 报错四：记忆文件被"读爆"，agent 反而变笨了

这个属于使用层面的问题：记忆文件越写越多，agent 启动时读的上下文越来越大，表现得越来越"啰嗦"但越来越不聪明。我一度以为是模型变笨了，后来排查发现是记忆文件太乱。

排查思路是这样：先看记忆目录下有哪些文件，按修改时间和大小排个序，找出那些上千行的老文件；然后打开看内容，发现里面既有有效决策，也有大量过时的过程记录。解决方法是把记忆文件拆分、精简，只留下有效的约束和决策，过时的内容要么删除要么标记为"已废弃"。清理完再开新会话，agent 明显"清醒"了很多。

这个问题的根源在于：记忆功能本身不会帮你判断什么该记、什么不该记，它只会照单全收。所以记忆内容的"卫生"需要你自己维护，这是使用任何记忆型 AI 工具都必须付出的维护成本。

6.5 通用排查思路：遇到问题先分清层级

最后总结一套通用的排查链路，无论遇到什么问题，按这个顺序走基本都能定位。

先分清楚是哪个层面出了问题：是安装层面（脚本没跑完、配置没写入）、加载层面（配置写了但 agent 没读到）、还是执行层面（agent 读了但没按流程做）。安装层面的问题看目录结构和配置文件，加载层面的问题在会话里直接追问 agent，执行层面的问题给它一句"请回顾技能流程"通常就能纠正。

第二步是检查版本。不管是 Codex CLI 还是 superpowers 本身，都是快速迭代的项目，版本不匹配是最常见的问题源头。安装前看一眼作者仓库的 README，确认当前推荐的最低版本。

第三步是最小复现。不要在一个复杂的项目里排错，建一个空目录，放一个最简单的文件，重新跑流程。这样能把变量压缩到最少，很多问题在最小环境下会变得极其明显。这套思路不仅能用在 superpowers 上，排查任何 AI 编程工具的问题都适用。

7. 最后说点我的个人体会

写到最后，我不想做什么宏大总结，就说几句实际的感受。

这个工具最适合的人，不是那些只拿 AI 写点小脚本的开发者，而是需要在真实项目里稳定交付的人——尤其是 Java、Go 这类工程约束强的领域。它解决的核心问题不是"让 AI 更聪明"，而是"让 AI 更守规矩"。聪明的模型很多，但愿意按流程一步一步走、不跳步、不自作主张的模型，靠的是流程把这个行为约束出来。

我的建议是，别一上来就把官网示例抄一遍，先挑一个你日常最痛的点，比如"每次让 AI 改代码都不跑测试"，然后写一个只有三五步的技能文档，让 agent 严格执行。从一个点开始，比全面铺开更容易坚持。等这个流程稳定了，再把团队规范、发布清单这些逐步沉淀成技能，慢慢你就有了一份可以复用的"团队 AI 操作手册"。

还有一个我自己的习惯：每周挑一个下午，把本周和 agent 协作的会话记录过一遍，看看哪些流程经常被打断、哪些指令需要反复说。这些观察就是最好的新技能素材。工具迭代很快，但"把经验沉淀成流程"这件事，什么时候都不会过时。