企业官网建设流程全解析

如果你也把 Codex CLI 当成日常开发的副驾，你大概率经历过这种时刻：丢给它一个稍微复杂的重构任务，它前十分钟干得像模像样，二十分钟后就开始原地踏步——反复读同一个文件、重复生成差不多的代码片段，甚至在某个子问题上钻牛角尖。问题不在 Codex 本身，而在于它缺少一套“干活的方法论”。Superpowers 要做的事情，就是把这套方法论装进 Codex 的脑子里。

Superpowers 不是一个独立的大模型，也不是 Codex 的替代品。它更像是一套挂在 Codex CLI 上的“技能包与工作流框架”，通过一系列结构化的 Markdown 技能文件，让 Codex 从“你问一句、它答一句”的被动问答模式，切换成“自主规划、分步执行、定期复盘、自我修正”的项目执行模式。对 Java 项目、多文件重构、测试补齐这类长链路任务，效果尤其明显。这篇文章我会从安装、技能文件编写、真实重构案例、踩坑记录几个角度，把它讲透。

1. Superpowers到底解决了Codex的什么问题

1.1 用了Codex却总觉得“差一口气”的真实体验

先说一个很多人的共性问题。Codex CLI 的原生能力并不弱，单轮代码生成、文件修改、命令执行都挺顺手。但一旦任务跨度变大，比如“帮我梳理这个模块的依赖关系，然后重构掉三个重复的 Util 类，最后把相关单测补上”，它就开始露怯。

我在实际项目里观察到的典型现象是：Codex 在执行过程中会逐渐丢掉最初的约束条件。比如你告诉它“不要改动公共接口签名”，它前两步还记得，第三步开始为了图省事直接改掉了接口签名；或者它会在某个文件的实现细节上过度纠结，却忘了整个任务的最终交付物是什么。

这不是模型智力不够，而是缺少项目级的“执行纪律”。Superpowers 解决的核心问题，正是这套纪律：它通过预置的技能文件，教会 Codex 在动手前先形成计划、在执行中维护 TODO 状态、在阶段性节点主动做代码审查和测试验证。一句话概括，原生 Codex 是个聪明的执行者，Superpowers 让这个执行者变成一个懂项目管理的人。

1.2 从“回答问题”到“执行项目”：Superpowers改变的是工作范式

我用一个类比说明这种范式差异。假设你雇了一个能力很强的工程师，但你不给他项目文档、不让他列计划、不要求他更新进度，只让他听你一句句指挥，他大概率会把事情搞砸——因为他没有上下文锚点，也没有自我检查的机制。

Superpowers 做的事情，相当于给这个工程师配了一套标准作业流程：接到任务后先写《作战计划》，把需求拆成可验证的小步骤；每一步执行完更新进度文件；遇到不确定的地方先查资料再动手；最后按 checklist 逐项验收。这套流程被固化在技能文件里，Codex 每次执行任务时都会主动去调取对应的方法论。

所以真正值得关注的不是它增加了多少新功能，而是它改变了人机协作的边界。以前你需要用很长很详细的 prompt 去约束 Codex 的行为，现在这些约束被结构化成可复用的技能文件，一次写好，长期复用。你只需要告诉它“用 planning 技能处理这个任务”，剩下的流程由技能文件驱动。

2. 安装与初始化：环境准备这一步比想象中容易翻车

2.1 安装命令与前置条件

Superpowers 的安装并不复杂，前提是你已经装好了 Codex CLI 并且能正常使用。当前它主要依赖 Node.js 环境，建议 Node 版本不低于 18，实测在 20.x 下最稳定。

安装我建议直接走全局 npm 路线：

npm install -g @superpowers/core

装完先别急着用，先跑一下初始化命令：

superpowers init

这一步会在你的用户目录下生成~/.superpowers/文件夹，里面包含 skills 子目录、配置文件和默认技能包。初始化完成后，在项目目录里启动 Codex，Superpowers 会自动被 Codex 识别为可用的技能提供方。

这里有个值得注意的细节：superpowers init不会自动帮你安装到 Codex 的插件目录里，它只是生成了数据文件。真正让两者连接起来的，是 Codex 的配置文件里对 MCP 或自定义指令目录的引用。不同版本的 Codex 配置方式有差异，建议敲一下codex --help看看当前的配置项名称。

2.2 superpowers init到底初始化了什么

很多教程会跳过这一步的细节，但我觉得值得展开。初始化后你会看到类似这样的目录结构：

~/.superpowers/ ├── config.json ├── skills/ │ ├── planning/ │ │ ├── SKILL.md │ │ └── reference/ │ ├── coding/ │ ├── test-driven-development/ │ ├── debugging/ │ └── ...更多技能包 └── prompts/

config.json控制 Superpowers 的全局行为，比如默认语言、是否自动调用技能、日志级别等。skills/下面每个目录都是一个独立技能，核心入口是SKILL.md文件。Codex 在每轮对话开始时会扫描这些技能文件，根据任务描述自动匹配并加载对应的方法论。

我建议初始化之后先不改任何配置，直接跑一个简单任务试试水，确认整个链路通了再动配置文件。很多人一上来就改 config，反而把默认的自动匹配逻辑搞乱了，后面排查起来很痛苦。

2.3 版本匹配与PATH：两个最容易翻车的点

实际安装过程中，我见过最多的两类问题，在这里先帮你排掉。

第一类是 Codex 和 Superpowers 的版本兼容问题。Superpowers 更新频率很高，而 Codex 本身也在快速迭代，两边的接口协议偶尔会脱节。如果你发现 Codex 启动后完全感知不到 Superpowers 的存在，先检查版本兼容性，而不是怀疑自己哪步装错了。保守的做法是看官方仓库的 Release 说明，找到标注“tested with Codex version xx”的对应版本。

第二类是 PATH 问题。npm 全局安装的包，如果你的 npm 全局目录不在系统 PATH 里，superpowers命令本身都执行不了。这种情况在 Windows 和部分 Linux 发行版上很常见。执行npm config get prefix看一下全局路径，确保它被加进了 PATH，否则后面每一步都会提示 command not found。

3. 技能系统：这是Superpowers真正的灵魂

3.1 CMD格式技能文件怎么读怎么写

Superpowers 的技能文件采用 CMD（Command Markdown）格式，本质上是一种带规范标记的 Markdown。开发者社区对这个格式的评价很高，因为它比传统 JSON 配置更可读，也比自由文本更好解析。

一个最小可用的 SKILL.md 长这样：

--- name: code-review description: 在完成任务后执行代码审查，检查潜在问题与遗漏 --- # Code Review Protocol 1. 读取当前任务涉及的 diff 2. 检查是否存在明显逻辑错误或边界条件遗漏 3. 输出审查结果，标记严重级别

开头的 YAML front matter 是元信息区，name是技能名字，description是技能用途的描述。Codex 匹配技能时主要依赖这个 description 字段，所以描述写得越具体，匹配准确率越高。下面正文部分就是你要给 Codex 的方法论指令，可以包含步骤、检查清单、注意事项，甚至是代码示例。

3.2 渐进式披露：让AI先看案卷目录，再调取细节

Superpowers 技能系统最关键的一个设计是“渐进式披露”。什么意思？简单说，就是不要让 Codex 一次性加载某个技能的完整细节，而是先让它看到技能的索引和摘要，等它确认需要深入时，再去读取具体步骤。

这样做的好处很明显：Codex 的上下文窗口是有限的，如果每个技能都全文加载，几十个技能很快就把上下文塞满了，真正执行任务时反而“失忆”。渐进式披露相当于案卷目录机制——先把目录给 AI 看，它根据目录判断需要哪份卷宗，再单独调取。这个设计对长任务的稳定性非常重要。

默认的技能包里，planning和coding这类基础技能都遵循这个模式。你解析某个技能文件时，会看到大量指向reference/子目录的引用，那些就是“卷宗”所在的位置。

3.3 一个最小可用技能的长什么样

我建议你从模仿开始写自己的技能。以“日志规范审查”为例，我自己写过这样一个简单技能：

--- name: log-audit description: 检查项目中是否使用统一的日志规范，包括日志级别、上下文字段、敏感信息脱敏 --- # Log Audit Checklist - [ ] 所有入口方法有 log.info 记录调用信息 - [ ] 异常分支统一使用 log.error，且附带异常堆栈 - [ ] 日志中不出现身份证号、手机号、Token 等敏感字段 - [ ] 业务日志必须包含 requestId 上下文

写完后把它放到~/.superpowers/skills/log-audit/SKILL.md，重启 Codex，当你的任务描述里带“检查日志规范”这类语义时，它就会自动加载这个技能。注意文件名和目录名要保持一致，否则匹配逻辑会找不到入口。

4. 用Superpowers驱动Codex搞定一个Java重构任务

4.1 任务背景：从零到一的规划会话

理论知识说多了容易飘，我用一个真实做过的 Java 项目案例来演示完整流程。这个项目是一个内部服务，老代码里有三个功能重叠的工具类，分别叫DateUtils、TimeUtils、DateTimeHelper，方法互相调用、逻辑盘根错节，测试覆盖也基本是空白。

我启动 Codex 后，给的第一条指令是：

使用 planning 技能，为重构这三个日期时间工具类制定详细计划

注意这里的关键词“使用 planning 技能”，它触发了技能匹配机制。Codex 随即加载了 planning 技能文件，没有急着改代码，而是先输出了重构计划：合并公共方法、确定新类DateTimeUtil的 API 边界、标注需要保留的兼容方法、列出需要新增测试的用例清单。

这一步的价值在于，以前我会自己花半小时梳理这些依赖关系，现在 AI 在技能框架的约束下替我把前序工作做完了，而且因为这个过程是可复现的，我可以直接 review 它的计划内容，发现不合理的地方及时纠正。

4.2 拆解执行循环：调研、草稿、实现、验证

Superpowers 的规划技能会把后续工作拆成几个明确的子任务：先调研现状，再写实现草稿，然后逐步落地修改，最后统一验证。每个子任务之间会主动暂停，让我确认后再继续。

我在这个 Java 项目里实际经历的执行循环是这样的：

1. Codex 先扫描了三个类的全部引用关系，输出依赖清单
2. 它新建了一个草稿文件，把新类的骨架和方法映射表列出来，标注了哪些旧方法需要保留
3. 确认后，它按计划逐步创建DateTimeUtil，每完成一个方法组就跑一次编译
4. 全部迁移完成后，它主动用git diff带我过了一遍改动清单，再按测试技能的要求补了 8 个单元测试用例

整个过程中我不是旁观者，更像是项目经理，在每个节点做确认和纠偏。这种体验和裸 Codex 的“一股脑改完”完全不同，风险可控得多。

4.3 实测效果：和裸Codex的差别在哪

同样这个重构任务，我也用裸 Codex 试过一次。它确实也能完成，但差别在于：裸 Codex 会一次性修改大量文件，中间缺少阶段性的编译验证；改到一半如果你提出新的约束，它可能已经忘了之前的决定，然后产生大量返工。

用 Superpowers 驱动的流程，改动量差不多，但有几个直观的差异：一是中途没有出现“结构性返工”，因为规划阶段就把 API 边界锁死了；二是测试是分批补齐的，而不是任务尾部突击生成，基本不需要大改；三是全程有可见的计划文件，我可以随时查看任务进展，不用靠记忆回顾上下文。

单从时间上看，这套流程不一定更快，甚至可能比裸 Codex 慢一点。但它的收益在质量和确定性上，对于要交付到生产环境的代码，这种确定性比速度值钱得多。

5. 哪些事该交给Superpowers，哪些事真的不该

5.1 适合的场景：长链路、多文件、需要纪律的活

根据我的使用经验，Superpowers 的优势场景有三个特征：任务链路长、涉及文件多、执行纪律要求高。

典型包括：跨模块重构、技术栈迁移、测试补齐计划、数据库脚本整理、复杂 Bug 的排查流程。这类任务里，真正的难点不是某一行代码怎么写，而是如何在几十个文件之间保持一致的决策和风格。Superpowers 的规划和状态跟踪机制，对这类场景是天然的补强。

另外一个容易被忽略的合适场景是“需要定期执行的工程规范任务”，比如日志规范审计、依赖安全检查、代码风格一致性检查。把它写成技能文件后，每次一条指令就能驱动 Codex 按固定流程执行，相当于把团队规范变成可执行的工程代码。

5.2 不适合的场景：别把它当成 prompt 增强器

但如果说 Superpowers 是万能的，那也不客观。我在一开始也犯过这个错误，试图用它优化所有 Codex 交互，后来发现有些任务引入技能反而是负担。

不适合的场景包括：单文件的小改动、临时查询、快速原型验证。这类任务本身链路短，不需要多层规划，技能文件的加载反而会拖慢响应，甚至引入不必要的流程约束。有一次我只是想快速改一个配置项，结果 Codex 自动加载了 planning 技能，绕着弯输出了五步计划，纯属脱裤子放屁。

另外一个不建议的场景是“你还不清楚自己想要什么的时候”。技能系统的本质是把方法论结构化，它默认你是带着明确目标来的。如果你连目标都是模糊的，规划步骤越多，产出的废稿就越多。这时候先做调研和澄清，而不是急着上技能框架。

5.3 社区里那些配套工具（worbuddy之类的）是什么定位

如果你搜索 Superpowers 相关教程，大概率还会看到 worbuddy 这个词。它经常和 Superpowers 出现在同一个话题下面，很多人的第一反应是这两者是不是同一个东西。据我了解，worbuddy 是社区围绕 Codex 工作流做的另一个辅助插件，聚焦在更细化的编辑操作和文件管理体验上。

我的理解是，它和 Superpowers 并不互斥，甚至可以叠加使用：Superpowers 负责方法论和流程，worbuddy 负责操作层的流畅度。但我个人把主要精力放在 Superpowers 上，worbuddy 没有深度使用过，具体用法建议直接看它的仓库 README，那里描述得比我转述更准确。工具这事，用顺手了就是好工具，没必要强求全家桶。

6. 我踩过的坑和对应的排查思路

6.1 skills目录没生效：问题往往在初始化路径

第一次遇到技能不生效时，我折腾了好久。技能文件明明写对了，但 Codex 就是不加载它。后来发现，问题出在我把技能放进了项目目录，而 Superpowers 默认只扫描用户目录下的~/.superpowers/skills/。

还有一个隐蔽的坑：如果你在项目里启动了多个 Codex 会话，其中部分会话是继承自初始化之前的环境，那它也读不到新加的技能。解决办法很简单——修改技能文件后，把当前 Codex 会话彻底退出再重启，不要用会话内重载的快捷操作，那个不一定覆盖技能缓存。

6.2 技能文件写对了却不触发：名称和描述的匹配逻辑

技能没有触发，还有一种更隐蔽的原因：description 写得太泛。Codex 匹配技能本质上靠语义近似，如果你的 description 是“处理任务”，那它和任何任务都能沾边，实际结果就是大概率匹配到一个更具体的技能，或者干脆不匹配。

我后来养成了一个习惯：description 里尽量包含明确的行为动词和领域名词，比如“检查 Java 项目的日志规范”比“日志审计”要好用得多。如果你发现某个技能在正确场景下总是抢不到匹配，优先优化 description，而不是改正文。

6.3 上下文膨胀：长任务跑到后半段开始“失忆”怎么办

长任务跑到后半段，Codex 偶尔会表现出“记忆模糊”，比如忘了最初定下的 API 边界，或者重复完成之前已经做过的步骤。Superpowers 环境下这个现象好一些，但并未完全消除。

我的应对方案是：在任务关键节点，主动要求 Codex 把当前进度摘要写进项目的progress.md文件。这个文件相当于外部记忆，即使上下文被压缩，它也能通过读取该文件恢复关键状态。这也是我个人觉得最实用的一招，比任何配置调优都有效。

6.4 版本迭代太快：锁定版本比追新更稳

最后提一个心态层面的坑。Superpowers 目前还在快速迭代期，语义化版本之间偶尔会有破坏性变更。我一开始喜欢追最新版，结果有两次升级后，之前的技能文件突然不兼容，排查了大半天。

现在我的做法是，项目里固定一个经过验证的版本，只在确实需要新特性时才升级，升级前先看变更日志。如果你是在生产环境依赖这套流程做交付，锁定版本带来的稳定性，比新功能带来的新鲜感重要得多。

我个人在实际操作中的体会是，Superpowers 的效果高度依赖你怎么用它。把它当成一个“流程框架”而不是“补丁包”，在长链路任务里设计好计划文件、状态文件和验收清单，它的价值才能完全发挥出来。同时记得把常用的审查、测试、日志规范沉淀成技能文件，一次封装，反复复用。工具本身不复杂，复杂的是把你脑子里的方法论，翻译成 AI 能稳定执行的文档——这件事一旦做通，Codex 的产出质量会有一个明显的跃迁。