1. 项目概述1.1 这套 superpowers 到底是什么先别被这个名字唬住superpowers 不是某个颠覆性的 IDE也不是什么黑科技框架。往下拆一层它是一套围绕 Codex CLI 打造的能力增强方案核心思路是把 AI 写代码 这件事从问一句、答一句的对话模式升级成带记忆、带技能、带工作流的协作模式。我在本地跑这套配置已经有几个月了坦白说刚接触时我也觉得这就是一堆 Markdown 文件和配置项没什么了不起。但真正用进去之后最直观的变化是AI 不再像一个记性很差的实习生每次打开终端都要重新自我介绍一遍。它知道你项目的目标、技术栈、约定习惯甚至在遇到构建失败时会自动按预设的排查流程走而不是干巴巴地回一句请检查一下日志。如果你是在终端里用 Codex CLI 写过东西的人应该能秒懂这种痛点每次会话都要反复交代背景写点复杂的重构任务时容易丢失上下文遇到编译错误还得自己手动把日志喂给它。superpowers 这套东西就是专门解决这些琐碎又致命的问题的。1.2 它解决了什么问题适合谁用从使用场景来说superpowers 解决的问题可以归纳成三块上下文管理、流程标准化、多项目复用。上下文管理是最核心的。它通过一套分层的记忆系统全局记忆、项目记忆、会话记忆让 AI 在每次任务启动时自动加载相应背景资料。流程标准化则体现在技能skills和工作流workflows上你可以把重构一个模块或修一个 bug这类高频任务拆成固定的执行步骤AI 会按步骤来而不是自由发挥。多项目复用就更好理解了技能库和记忆文件都是独立存放的换项目时不用重新调教。适合谁用我建议这样的人群优先尝试重度使用 Codex CLI 的开发者尤其是同时维护多个仓库的人团队里负责搭 AI 编码环境的技术负责人以及对ai 结对编程这件事有耐心折腾的爱好者。如果你只是偶尔用 AI 补全几段代码superpowers 反而有点杀鸡用牛刀光是理解它的配置体系都需要不少时间。2. 内容整体设计与思路拆解2.1 为什么选择配置优先而不是插件优先很多人第一次看到 superpowers 的仓库结构时会有个疑问为什么不用插件机制非要用一堆 Markdown、YAML 和 Shell 脚本来组织功能这个取舍背后是有讲究的。插件机制虽然有封装优势但有一个潜在问题调试链路太长。你用 Codex CLI 跑一条命令背后实际执行的是某个插件封装的内部逻辑出了问题很难判断是插件 bug、配置错误还是模型理解偏差。而 superpowers 的配置文件几乎都是明文——技能是 Markdown 提示词命令是 Shell 脚本工作流是 YAML 编排每一层都能直接打开查看、修改、测试。另一个原因是为了可移植。插件通常绑定特定平台或运行时而这套方案对 Codex CLI 来说只是一堆普通文件把整个 skills 目录拷到另一台机器上只要路径和配置匹配就能直接运行不需要额外的安装器。对我这种经常在多台设备之间切换的人来说这一点特别重要。2.2 三层核心体系记忆、技能、工作流拆开这套方案的骨架其实只有三层记忆系统、技能系统、工作流系统。理解这三层就等于理解了整个 superpowers 的设计哲学。记忆系统解决的是AI 怎么知道你之前做过什么。它细分成三层全局记忆存放通用的偏好和约定比如代码注释使用中文、提交信息遵循 Conventional Commits项目记忆放在仓库内记录项目特定的架构决策、常见坑、目录约定会话记忆负责在单次对话里保持上下文不丢失。技能系统解决的是AI 怎么知道某个任务该怎么做。它的本质是一些经过整理的 Markdown 提示词每个技能有名称、描述、适用场景甚至可以有配套的脚本。工作流系统解决的是多个步骤怎么串起来。比如修复回归 bug这个任务先定位最近变更git diff再复现问题跑测试然后定位根因最后修复并补测试——这一整个链路可以编排成模板AI 拿到任务后按模板执行。这三个系统彼此独立、文件共享记忆文件里引用了技能技能里引用了工作流模板工作流执行时又反过来读取记忆。这就是为什么它叫superpowers——不是某个单一功能强大而是整套机制叠在一起产生了质变。2.3 设计上的取舍与代价任何方案都有代价superpowers 也不例外。最明显的代价是调教成本高。它不是一个开箱即用的工具装完之后你需要写自己的记忆文件、定制自己的技能才能在真实项目里用顺手。框架提供的默认技能只能覆盖通用场景具体到你自己项目的业务逻辑还是得靠定制。另一个代价是它会让 Auto 模式变得更啰嗦。因为技能和工作流本质上是把大任务拆成多轮小任务模型需要频繁读取上下文、执行脚本、检查中间结果。打开 verbose 日志时你会看到大量的内部调用记录如果对这套机制不熟悉会以为是不是哪里卡死了。所以我的建议是不要把它当插件来装要把它当一套可以按需裁剪的内部规范来理解。先用默认配置跑通一个简单任务然后逐个技能地改造成适合自己的版本循序渐进不要指望一天全配完。3. 核心细节解析与实操要点3.1 记忆系统的落地方式记忆系统是 superpowers 里最值得花时间研究的部分几乎所有体验上的提升都来自这里。它的实现方式并不复杂核心就是 Markdown 文件加约定式目录结构。在 Codex CLI 的配置目录macOS/Linux 下是~/.codex/Windows 下是%USERPROFILE%\.codex\里你会看到类似这样的结构.codex/ ├── config.toml # 全局配置决定模型和开关项 ├── memory/ │ ├── global.md # 跨项目通用的背景信息 │ └── project.md # 当前项目的专属约定 └── skills/ ├── debug-regression/ │ ├── SKILL.md # 技能的描述和触发条件 │ └── run.sh # 可选的辅助脚本 └── refactor-module/ ├── SKILL.md └── check.pyglobal.md里适合写这些内容你偏好的代码风格、常用的命令别名、讨厌被 AI 反复确认的事情、团队约定的命名规则。比如我会在全局记忆里写明所有新增的 Python 文件必须加类型注解禁止使用printf调试统一用logging。project.md则更细粒度只针对某个仓库。比如 CI 命令怎么跑、哪个目录是历史遗留代码没法动、数据库迁移的注意事项等等。每个项目的记忆文件单独维护换项目时 AI 自动切换加载不会串味。有一个容易被忽略的细节记忆文件不是越大越好。我在早期把项目记忆写得特别详细结果 AI 每次读取时都在无关紧要的信息上消耗 token。后来我学到的经验是记忆文件控制在 50 行以内只放每次干活前必须知道的事细节放到具体技能里按需加载。3.2 技能Skills如何编写与触发技能是 superpowers 最灵活的部分本质上它就是一组 Markdown 文件。一个技能文件夹里至少包含一个SKILL.md开头是 YAML frontmatter写明技能名称、描述、触发建议。下面这段是我改过的一版简化示例--- name: debug-regression description: 定位并修复回归问题优先检查最近的代码变更。 when: 用户反馈某个功能之前正常现在坏了或测试突然失败 ---frontmatter 下面的正文才是关键它描述这个技能的完整执行流程包括需要读取哪些文件、执行哪些命令、在什么条件下停止并向上汇报。写技能提示词时有一条铁律步骤要可执行、结果要可验证。不要写深入分析问题根源这种虚的要写先执行git log --oneline -10查看最近提交再根据提交说明锁定期限内变动的模块……。触发机制也很简单Codex CLI 在每次会话开始时会将技能列表注入上下文模型根据当前任务描述自行判断是否激活某个技能。所以技能描述写得越贴近真实任务场景触发准确率就越高。如果发现 AI 该用技能时没用或者在不需要时调用了基本都是描述写得不够精准。3.3 工作流编排的节奏把控工作流解决的是多步骤协调问题。以修复回归 bug为例我会把它编排成四个阶段复现阶段根据用户描述构造最小复现步骤跑相关测试定位阶段结合git diff和日志缩小嫌疑范围修复阶段提出修改方案确认后动手改代码验证阶段跑完整测试、静态检查输出变更摘要。每个阶段之间要有明确的出口条件比如复现阶段必须能稳定复现 bug否则不能进入定位阶段。这样设计的价值在于AI 不会在信息不足的情况下贸然动手改代码。节奏把控上有个容易踩的坑阶段步骤切忌过多。如果 AI 需要连续执行十步才能完成一个任务中途任何一步出错都可能让整个流程崩掉。更合理的做法是三到五步一个子任务子任务的产出物被下一个阶段消费保持每一轮的颗粒度小到模型能稳定执行。4. 实操过程与核心环节实现4.1 环境准备与安装步骤详解下面以本地环境为例演示从零到一安装并跑通这套方案。我用的环境是 macOS Homebrew如果你在 Linux 或 WindowsWSL上关键字换一下就一样。第一步准备 Codex CLI确保终端里已经能正常调用codex命令。如果没有安装可以用 Homebrewbrew install codex安装后验证版本codex --version这里有个重要的前置条件Codex CLI 需要依赖本地 Python 或 Node 运行时之一。它通过 JSON-RPC 调用本地工具所以环境里至少要有一个可用的运行时。如果你平时主要写 Python装好 3.10如果主要写 JS装好 Node 18。第二步拉取技能和记忆文件。superpowers 的配置内容以目录形式存放你可以直接从 GitHub 仓库克隆也可以手动创建。我自己倾向于手动建目录只保留自己需要的技能因为默认仓库包含太多技能全量引入反而会让模型在选择时选择困难降低响应质量。目录结构参考 3.1 节。第三步配置config.toml。这是我的核心配置文件片段model auto # 让 CLI 自动选择合适模型 verbose false # 平时不开排错时再打开 auto_exec true # 允许 AI 自主执行验证命令 skills_dir ~/.codex/skills # 技能目录 memory_dir ~/.codex/memory # 记忆目录model auto是我对比后的选择。固定模型虽然行为更可预测但遇到复杂任务时小模型处理不了、大模型又浪费auto 模式会根据任务复杂度动态切换配合 superpowers 的步骤拆分整体成本更低。第四步写一个最简的全局记忆文件做验证。我新建memory/global.md只写两行测试内容# 全局约定 - 所有脚本必须用 set -euo pipefail 开启严格模式。 - 代码注释使用中文代码标识符使用英文。这样写的好处是验证的效果足够明显——如果你让 AI 写一个 Shell 脚本它没有自动加上set -euo pipefail就说明记忆没生效问题出在哪一层也容易排查。第五步用一个实际任务拉通全流程。我以一个尚未配置技能的空仓库为例让codex初始化一个 Python 工具的骨架。正常预期是AI 生成完整项目结构时会先读取项目记忆和全局记忆生成的代码自动带上类型注解脚本开头自动加上严格模式。跑完这五步你已经完成了环境搭建和最小验证。下一步才是定制化。4.2 自定义一个实用技能以需求拆分为例自建技能是提升这套方案上限的关键一步。我建议新手第一个自建技能不要选太复杂的选一个你日常重复度最高的任务。我选的是需求拆分——把一段含糊的需求描述拆成可执行的开发任务列表。我的skills/task-decomposition/SKILL.md长这样--- name: task-decomposition description: 将模糊的需求描述拆分为可执行的开发任务列表按依赖关系排序。 when: 用户提供一段描述但没有明确的任务清单 --- 执行步骤 1. 列出需求中所有的显性功能点和非功能点 2. 对每个功能点拆解出前后端改动、数据模型变化、测试补充 3. 按依赖关系排序有依赖的任务排在前面 4. 输出 Markdown 格式的任务清单每个任务包含验收标准。 验证标准 - 每个任务都能独立验收 - 任务之间没有循环依赖 - 最终输出不超过 20 行。这个技能没什么技术含量但它的价值在于把怎么从含糊需求得到任务清单这件事的决策路径固定下来了不会每次让 AI 自由发挥。自定义技能的指导思路是不要试图用技能创造模型不具备的能力而是用技能约束模型已有的能力减少随机性。自建技能时还需要注意description和when的措辞。描述里应该包含你自己的表达习惯比如我在when里写模糊的需求描述没有明确的任务清单就是为了让触发更加精准。我实测发现如果when写得太笼统AI 容易在不需要的时候也调用技能白白增加多余的步骤。4.3 与 Codex CLI 的深度联动配置superpowers 的真正威力不在于独立运行而在于与 Codex CLI 的深度联动。配置上有一个我需要特别强调的点auto_exec必须配合可控的命令白名单使用。auto_exec true意味着 AI 可以在不需要你确认的情况下直接执行命令。这在自动跑测试、静态检查等场景下非常高效但如果 AI 误执行了破坏性命令比如git reset --hard、删除文件的命令后果会很严重。我的解决思路是把允许自动执行的命令限定在安全范围内。Codex CLI 支持通过配置允许自动执行特定二进制[allowed_commands] auto [pytest, python, git diff, git status, ls, grep]我基于常见最佳实践给出这个白名单pytest跑测试、git diff和git status是只读操作、ls和grep是信息查询。凡是涉及写操作的命令都保持让 AI 先输出方案、等我确认后再执行。这套约定虽然会让流程多一步交互但能将误操作风险降到最低。另一个与 Codex CLI 联动的重要配置是AGENTS.md。这个文件放在项目根目录Codex CLI 启动会话时会自动加载。它和项目记忆有分工AGENTS.md更偏向于当前会话的初始上下文项目记忆更像长期沉淀的认知。我的习惯是AGENTS.md只放构建命令、测试命令、目录结构、环境变量这些每次开发都要用的硬信息而project.md放架构决策、历史变更背景、常见坑这种需要时间积累的软信息。4.4 Java 项目中的实践路径superpowers java这个热搜词指向一个典型疑问这套方案能不能用在 Java或 JVM 系项目上答案是可以但做法上有些调整。Java 项目的特殊性在于构建链路过重。相比 Python 脚本、Node 脚本Java 项目通常有 Maven/Gradle 这一层AI 在探索代码时很容易被构建过程拖慢甚至因为依赖下载失败而卡住。我的处理思路有三步第一步在项目记忆的硬信息区写清楚构建命令和常用生命周期比如Web 模块用./mvnw -pl web -am test单独跑跳过 Checkstyle 用-Dcheckstyle.skiptrue让 AI 不要每次瞎猜。第二步把编译和测试封装成两个自定义技能分别应对高频场景。之前我写过一个名为java-contract-check的技能专门负责检查一个接口改动是否破坏已有调用方会让 AI 先编译受影响模块、再跑相关测试、最后输出调用链摘要。这样限定之后AI 在 Java 项目里的操作规范性明显提升。第三步也是我踩过坑后总结出来的经验Java 项目里要让 AI 多读pom.xml或build.gradle少直接搜代码。依赖关系、模块划分、Java 版本这些信息都藏在构建文件里让 AI 先读构建文件再进入源码能避开很多这个类明明存在却报找不到的假问题。下面这行是我在 Java 仓库里最常用的技能触发描述当用户提到编译错误或依赖冲突时先读取构建文件中的依赖声明再执行 mvn dependency:tree 分析冲突。这条经验的底层逻辑是Java 生态的问题大多是依赖关系导致的而不是代码本身的语法问题所以第一步必须是构建链路的上下文而不是源码。5. 常见问题与排查技巧实录5.1 记忆明明写了AI 却像没看到这是使用 superpowers 过程中最高频的故障尤其出现在刚装完的那几天。表现是你明明在global.md写了约定AI 生成代码时就是无视。排查思路按顺序走一遍第一步确认记忆文件路径。Codex CLI 读取记忆的路径由config.toml的memory_dir决定如果改过配置但没重启会话读的是旧路径这属于典型的配置改了但没生效。验证方法是启动一个新会话问 AI 你读到的记忆文件内容是什么如果回答为空或对不上就是路径问题。第二步检查记忆文件是否是 UTF-8 编码。带中文的记忆文件最容易踩这个坑如果文件被编辑器存成了 GBK 或带了 BOM解析时会产生不可见字符AI 读取时可能把整段内容当作乱码跳过。我习惯统一用 UTF-8 无 BOM 格式保存所有记忆和技能文件。第三步确认记忆内容本身没写超过理解范围的信息。模型不会执行记忆里的任意指令它只把记忆当作背景信息参考。如果在记忆里写永远不要用循环这在需要循环时是无法被严格执行的必须用技能约束。5.2 技能该触发不触发不该触发瞎触发技能触发机制虽然简单但实际使用中蕞容易出现两种问题该触发时没触发不该触发时被强行调用。先解决该触发时没触发。大多数情况是description或when写得太宽泛模型没能建立这个任务与这个技能之间的联想。我改用一种更场景化的描述方式把用户真实会说的话直接作为触发词候选比如when: 用户说这功能之前还好好的或帮我看看哪里改坏了描述贴近实际对话之后触发率显著提高。再解决不该触发时瞎触发。这种情况往往是因为技能描述里用了一些高频词比如优化分析模型在遇到任何优化请求时都想调用这个技能。对策是降低技能的通用性在when里加更多限定条件明确写清楚仅当用户明确提到 X 时才触发同时把技能的定位从通用能力改成专用流程。5.3 工作流跑到一半中断怎么办使用工作流时最容易遇到的问题多步骤跑到中间因为某个命令返回非零退出码而中断。我之前遇到过 AI 在跑测试时因为一个模块的测试环境没准备就绪直接终止了整个工作流后面的修复和验证都没执行进去。后来我的解决策略是分层写入。工作流的每一步结果都要求 AI 先输出到文件比如step1-result.md再决定下一步动作。这样即使中途中断也能从文件部分恢复不需要从头再来。同时要在技能描述里显式写明对非关键失败的处理方式。我现在会在工作流模板里补一句如果某个验证命令失败不要立即停止先输出失败原因并评估是否影响后续步骤只有影响结论时才终止。这个改动让工作流在真实项目上的通过率高了不少。5.4 配置在 Windows 上的注意点如果你在 Windows 原生环境非 WSL下用这套方案有几个坑要先避开。第一个是路径格式问题技能文件里但凡写了绝对路径都要改用正斜杠否则模型执行的命令很可能在解析时出错。第二个是 Shell 差异默认技能里很多命令是 Bash 脚本Windows 原生环境执行不了建议要么统一用 WSL要么把所有脚本改成 PowerShell 版。还有一个容易被忽略的点目录大小写。Windows 文件系统不区分大小写但 Codex CLI 的 skill 匹配可能区分如果技能目录名和配置里写的名称大小写不一致会出现技能文件明明存在却加载不到的问题。保持全小写命名是省心的选择。5.5 快速问题排查速查表整理一张实践中验证过的排查表按照现象 - 可能原因 - 解决手段的顺序排列现象可能原因解决手段记忆完全不生效路径配置错误检查config.toml的memory_dir确认与新会话匹配技能从不触发描述太宽泛或抽象改写when直接使用用户原话做触发词技能每次都被触发描述使用了过强的高频词增加限定条件缩小适用范围工作流中途中断某步返回非零退出码每步结果写文件允许非关键失败继续Windows 上脚本执行异常Bash 脚本不兼容换 WSL 或改 PowerShell 版脚本生成的代码不符合约定记忆文件编码有 BOM统一转为 UTF-8 无 BOM 格式AI 重复做无用操作有效技能少、上下文太杂精简技能数量让模型选择困难的概率下降6. 使用心得与最后一点建议6.1 最适合与不适合的场景我把这套方案跑了几个月之后对它的适用边界有了比较清晰的认知。它最适合的场景是中大型仓库的日常维护、有明确规则但规则繁琐的工程流程、以及需要跨多任务积累经验的长期项目。在这些场景下记忆系统和技能系统的价值会被放大很多倍。它不适合的场景也很明确你只是想快速验证一个想法、写个一次性脚本或者还在频繁改需求的原型阶段。这种情况下配置化的流程反而会拖慢节奏——AI 每次都要走流程、读记忆、检查上下文成本比直接用默认模式对话高得多。我在自己项目里也是两种模式混用需要探索和快速试错时用默认模式需要稳定执行长任务时切 superpowers。6.2 下一步可以怎么扩展如果你想继续往下深化有几个扩展方向值得关注。一是把工作流和 CI 流程对齐把技能的执行步骤对应到 Jenkins 或 GitHub Actions 的流水线阶段让本地 AI 辅助和远端自动化检查用同一套验证标准。二是根据团队编码规范定制一套团队级记忆包作为新成员环境初始化的一部分降低 AI 辅助编程的落地门槛。三是尝试用更细的粒度将技能模块化比如把代码审查拆成风格审查性能审查安全审查三个独立技能按需求分别触发。我在实际使用中比较深切的体会是superpowers 这类配置型方案真正的门槛不在安装而在约束自己持续维护。技能文件和记忆文件是越用越准的你每次修 bug、每次调整提示词都是在为这套系统积累肌肉记忆。别指望第一天配完就完美把它当成一个需要持续演进的内部工具来用效果会远超预期。