企业官网建设流程全解析

最早我是被这个关键词的中文搜索结果气到的：搜 superpowers，出来的全是游戏攻略和营销号软文，真正想找的那个给 Codex CLI 加技能的开源项目，反而要翻好几页。obra 在 GitHub 上开源的 superpowers 已经火了有一阵子，但对中文开发者来说还是个相对陌生的名字。简单说，它是给 Codex CLI 用的一套技能（skills）框架，作用是让 AI 编码助手从"会写代码"变成"会做工程"。我重度用了大概一个月，最大的感受是：它没有让 Codex 变聪明，但让它变得有纪律了。这篇文章把我从安装、自举、工作流拆解到 Java 项目实战的完整经验写下来，适合正在用 Codex 但觉得结果不受控的人，也适合想给团队 AI 编码流程立规矩的人。

1. 先搞清楚 superpowers 是什么：它不是插件，是一套"技能操作系统"

1.1 一个 skill 文件到底长什么样

很多人第一次听说 superpowers，第一反应是"又一个 AI 插件"。其实它和插件完全是两个物种。插件的核心是给编辑器加功能、加界面；superpowers 的核心是给模型加行为约束。它把软件工程里那些被验证了几十年的好习惯——先规划再动手、测试驱动开发、根因分析式调试——写成一篇篇结构化的 Markdown 文件，这些文件就是 skill。

一个 skill 文件通常长这样：

--- name: write-a-plan description: 在动手写代码之前，为当前任务产出一份可执行的分步计划 when_to_use: 当任务涉及多个文件、多个步骤，或需求还不完全清晰时 version: 1.0.0 --- # Write a Plan 1. 先阅读项目现有结构和 PLANS.md（如果存在） 2. 将任务拆解为不超过 15 分钟的小步骤 3. 每个步骤写清楚：意图、涉及文件、验证方式 4. 计划完成前不要动手写任何实现代码

前面的 YAML frontmatter 是元信息，其中 description 和 when_to_use 这两项最关键——它们是 Codex 判断"当前这个任务该调用哪个技能"的依据。正文才是真正的执行指令。这种"判断条件 + 执行步骤"的结构，本质上就是给模型用的决策树，让它不再靠猜来选工作方式。

1.2 自举机制：为什么安装过程需要 Codex 自己参与

superpowers 的安装流程里有一个非常特别的环节：它不只是把文件复制到某个目录，而是要启动一次 Codex 会话，让 Codex 自己把这些技能全部读一遍，并把"何时调用哪个技能"的规则固化到它的指令体系里。这个过程在项目里叫 bootstrap，中文社区习惯叫自举。

我一开始觉得这步很玄学，后来理解了：技能要生效，前提是模型真的"知道"这些技能的存在和使用时机。如果只是把 Markdown 文件丢在硬盘里，Codex 根本不会主动去翻。自举的本质，是让 Codex 在初始化阶段把这些技能的摘要信息加载进它的上下文——相当于入职第一天先读员工手册，而不是边干活边翻书。

技能文件有一个很好的特性：格式对人类和模型完全透明，没有任何黑盒。你可以随时打开技能库，逐字阅读每个文件的每一条规则，改成符合自己团队习惯的版本。这一点对技术团队非常重要，意味着这套框架可以被审查、被定制、被沉淀成团队资产。

1.3 和普通 prompt、插件、MCP server 的区别到底在哪

我见过不少人把 superpowers 和 MCP（Model Context Protocol）搞混，这里把几个概念一次说清：

一句话总结：MCP 解决的是"模型能调用什么工具"，superpowers 解决的是"模型应该以什么流程做事"。两者可以共存，superpowers 自己也支持通过 MCP 服务把技能和记忆暴露给 Codex 动态管理，后面讲 Java 实战时我会具体说。

1.4 它到底解决了我哪三个痛点

第一是任务边界失控。我之前直接让 Codex 修一个方法，它顺手重构了整整一个类，diff 大得没法 review。superpowers 的规划技能会强制先产出 PLANS.md，明确改动范围，动代码之前就能拦住这种"自由发挥"。

第二是跳过验证。裸用 Codex 时，它经常写完代码就宣布"完成"，不跑测试也不给验证命令。TDD 技能会强制它先写失败测试、再写实现、然后自己执行测试命令。这个改变是革命性的——AI 终于开始对自己的代码跑测试了。

第三是上下文丢失。上一步刚说过的项目约束，下一步就忘了。superpowers 的项目记忆机制会把这些约束持久化，每次新会话重新加载。说白了，就是给 AI 配了一个长期记忆盘。

2. 安装与自举：让 Codex 学会使用技能库的完整过程

2.1 前置条件先检查一遍

在动手之前，确保三件事没问题：Codex CLI 已经安装并且能正常对话；系统是 macOS 或 Linux，Windows 用户建议开 WSL；本机有可用的包管理工具，比如 Homebrew 或 npm。如果你平时用科学的方式管理 Node 版本，注意一下 npm 全局安装的权限，别装完发现命令找不到。

另外提醒一句：网上搜 superpowers 会搜到一堆同名项目，有游戏、有前端库，别搞混了。本文说的是 GitHub 上 obra/superpowers 这个仓库，针对的是 Codex CLI 的技能框架。装之前最好先去仓库 README 确认一下项目全名和当前推荐安装方式，工具迭代很快，以官方文档为准最稳。

2.2 三种安装方式，任选其一

我自己用的是 Homebrew 方式：

brew install obra/superpowers/superpowers

没有 Homebrew 的话，官方也提供 npm 方式：

npm install -g @obra/superpowers

第三种方式是从 GitHub Releases 页面下载对应平台的预编译二进制，解压后放进 PATH 目录。这种方式最适合 CI 环境或者不方便装包管理器的服务器。

装完先验证一下：

superpowers --version

能正常输出版本号，说明 CLI 本身没问题了。

2.3 自举：让 Codex 把技能库"读进脑子"

接下来是最关键的步骤。运行：

superpowers bootstrap codex

严格来说，具体子命令名在不同版本里可能略有差异，装完后先跑superpowers --help看一眼官方提示。这个命令会输出一段引导说明，大意是：新建一个 Codex 会话，然后在会话里粘贴一段特定的激活提示，让 Codex 自己去下载、解压、安装技能库，并把技能接入它的指令体系。

我第一遍卡在这里了：以为运行完 bootstrap 就完事了，直接回原来的 Codex 会话继续聊天，结果技能完全没生效。后来才发现，技能是在新会话启动时加载的，老会话里 Codex 根本不知道你装了新东西。所以自举完成后，一定要关掉旧会话，重新开一个。

2.4 验证技能库是否加载成功

重开会话后，直接问 Codex："你现在有哪些技能？"正常情况它会列出一串技能名，比如 brainstorm、plan、TDD、debugging、commit-message 这类，每个还带一句话说明。能列出这串名字，说明技能库已经进入了它的上下文。

还可以直接检查文件系统。技能库默认放在~/.codex/skills/目录下，进去看一眼就能发现每个技能对应一个文件，全是纯文本 Markdown，没有加密也没有二进制格式。这一点我特别喜欢——你完全可以把整个技能库通读一遍，搞清楚 Codex 到底被灌输了哪些行为准则，而不是把它当黑盒用。

提示：如果你在这个目录里看到的技能文件很少，或者 Codex 回复"我不确定你有技能"，大概率是自举那一步没走完，或者会话没重启。重跑一遍 bootstrap 流程，然后再开新会话。

3. 核心工作流拆解：从需求澄清到提交信息的每一步

3.1 需求澄清：brainstorm 技能先拦住"想当然"

superpowers 的第一个环节不是写代码，而是 brainstorming。这个设计非常反直觉，却是我觉得最值钱的部分。以前我扔给 Codex 一个需求，它默认我的需求是完整的、清晰的，直接闷头就开干。结果经常出现"我要的是 A，它做出来的是 B"。superpowers 的 brainstorm 技能要求它在动手前先和我确认关键问题，比如边界条件、异常路径、兼容性要求——这些恰恰是我之前懒得写清楚、又最容易出问题的地方。

一开始我会嫌烦："我只是让你加个导出按钮，你问这么多干嘛？"后来被坑过几次就老实了：需求澄清省掉的每一分钟，都会在后面用十倍的返工时间还回来。现在我会主动配合这个环节，把模糊的地方在会话里聊清楚，再放它去干活。

3.2 计划产出：PLANS.md 为什么能改变 review 体验

需求澄清之后，进入 plan 环节。Codex 会产出一份 PLANS.md，结构大致是：

• 本次任务的目标和验收标准
• 涉及的文件清单，标注新增/修改/删除
• 分步实施顺序，每一步都有明确产出物
• 每步的验证方式（测试命令、人工检查点）

这份文件的出现，把"AI 改代码"从事后审查变成了事前审查。以前 Codex 直接提交一堆 diff，我只能看到结果，看不到它为什么这么设计、为什么选这条路径。现在计划先落地，方向不对可以在零代码成本的时候纠正。而且 PLANS.md 本身就是项目资产，新人接手时看一眼就能理解设计意图，比读代码快得多。

3.3 TDD 技能：让 AI 先写失败测试，而不是先写实现

superpowers 对 TDD 的贯彻比我预想的要严格。执行计划时，Codex 不是直接写实现，而是严格走"红灯—绿灯—重构"三步：先写一个会失败的测试，跑一遍确认失败，再写恰好让测试通过的最小实现，跑测试确认通过，最后重构代码并再次验证。

我以前也试过在 prompt 里要求 Codex"先写测试再写代码"，但它总是阳奉阴违，写着写着就跳到实现了。原因很简单，口头指令没有流程约束力。superpowers 的 TDD 技能把它变成了分步执行的规则，加上技能描述里明确写了"这是所有编码任务的默认路径"，Codex 几乎没有偷懒的空间。我实测下来，它对 JUnit 这类测试框架的调用频率明显变高了，不是嘴上说说，是真跑。

3.4 调试技能：从"随机改代码"到"根因分析"

另一个直接改善体验的是 debugging 技能。裸用 Codex 时，它遇到 bug 的第一反应是"猜一个可能的原因然后改掉"，经常把相关代码全动一遍，最后 bug 还在，还引入新问题。superpowers 的调试技能则给出一套标准排错路径：

1. 先复现问题，写清楚复现步骤和预期行为；
2. 用日志、断点或二分法定位根因，而不是靠猜测；
3. 针对根因提出修复方案，评估影响面；
4. 修复后补充回归测试，防止复发。

这套流程本质上就是人类资深工程师的排查套路，被固化成了模型可以照做的 checklist。我印象最深的一次：Codex 定位到一个并发问题，通过分析线程日志找到了真正的竞态条件，修完之后还补了一个压力测试。那个瞬间我真的有种"这才是队友"的感觉。

3.5 提交信息与自查：把流程的最后一公里走完

代码改完不等于任务结束。superpowers 的 commit-message 技能会要求 Codex 根据实际改动生成符合 Conventional Commits 规范的提交信息，比如 feat、fix、refactor 这种前缀，并把它在 PLANS.md 中完成的任务勾掉。

更有意思的是自查环节：Codex 会把最终改动范围和计划做对比，如果超出计划，必须说明理由——是需求变了，还是发现了计划外问题。这个"自觉汇报偏差"的机制，让我在 code review 时省了大量时间，diff 范围基本都在预期内，偶尔有偏差也带着解释，不需要我再满屏找"为什么这里动了"。

4. Java 项目落地：把技能链跑进 JVM 生态

4.1 为什么 Java 开发者尤其需要这套流程

Java 项目可能是最让 AI 编码助手露怯的场景之一。构建链路长，Maven 和 Gradle 版本复杂；测试框架多，JUnit 4 和 JUnit 5 写法差异大；代码规范重，Checkstyle、Spotless 稍不注意就挂 CI。裸用 Codex 时我踩过的坑包括：用 JUnit 4 的语法写 JUnit 5 的测试、不知道项目用的是 Maven wrapper 还是全局 mvn、改完代码格式化不符合规范导致流水线红灯。

superpowers 的价值在于：它允许你把这些项目特有的约束写成技能或项目记忆，让 Codex 每次开工前自动加载。语言无关的通用技能管住流程，项目定制的规则管住细节，两者配合，Java 项目才能让 AI 真正放手干活。

4.2 我在 Java 项目里做的三件配置

第一件，把构建命令写进项目记忆。很多 Java 仓库用 Maven wrapper（./mvnw），如果 Codex 直接跑系统 mvn，很可能因为版本不一致翻车。我在项目记忆里明确写了一句："本仓库统一使用 ./mvnw 执行构建，禁止直接调用系统 mvn"——从那以后它再没跑错过。

第二件，补齐测试技能。默认的 TDD 技能是语言无关的，对 Java 缺一些约定。我新增了几条规则：Java 测试统一使用 JUnit 5；包结构遵循 src/main/java 和 src/test/java；测试类命名以 Test 结尾。这几条看起来简单，实际效果立竿见影，生成的测试代码风格和团队惯例完全对齐。

第三件，把格式化纳入"完成定义"。我不希望 Codex 只是"功能跑通就交差"，所以在技能里加了硬性要求：提交前必须执行 Spotless 格式化，并跑完本地全量测试。一开始它偶尔会漏，现在基本养成习惯，CI 红灯率大幅下降。

4.3 一个真实场景：给订单服务加"取消订单并退回库存"

把流程串起来看，假设需求是"取消订单并退回库存"。

第一步，brainstorm 技能会追问我：库存退回是同步还是异步？取消后是否允许重新下单？如果取消失败该如何回滚？需求聊清楚后，进入计划环节，PLANS.md 列出要修改的 OrderService、库存客户端、新增的 OrderCancelTest 等文件清单。

第二步进入 TDD 执行：Codex 先写 OrderCancelTest，预期订单状态变更和库存回滚，跑一遍确认失败；然后写取消逻辑，再跑./mvnw test直到绿灯；最后做重构，把取消逻辑中重复的库存调用抽成公共方法。

第三步提交：commit-message 技能生成了feat(order): add cancel order with stock rollback这样的提交信息，并把 PLANS.md 里的对应项勾掉。整个链路走完，我最省心的不是 Codex 写得多好，而是每一步它都自己验证，而不是拍胸脯说"应该没问题"。

4.4 MCP 集成：让技能和记忆可以被动态管理

如果你在用 Claude Code、Cursor 这类支持 MCP 的客户端，superpowers 还有一个可选的 MCP server 模式，可以把它注册进客户端的 MCP 配置里。注册之后，客户端就能通过工具调用动态查询技能列表、读取项目记忆、甚至创建新技能，不需要手动改文件。

我在 Codex 的 config.toml 里配置过一次，好处是可以在对话中直接说"把之前那条构建规范写进项目记忆"，它真会自己动手写文件。对团队协作来说，这降低了维护成本——不用每个人手动同步技能文件，MCP 拉取即可。

5. 三十天实测：踩过的坑、总结的技巧和它改变我的三个瞬间

5.1 坑一：技能不是越多越好，约束越少越好

我刚上手时陷入过一个误区：觉得技能库机制这么灵活，应该把自己能想到的规范全塞进去。结果 Codex 每次开工前要读一大堆技能，反而不知道该优先执行哪个，经常出现"计划说做 A，最后交付了 B"的错乱。后来我把技能按场景重新梳理，核心流程技能保留默认，项目特有规则只放记忆文件，不再单独建技能，效果立刻变好。技能库是给模型减熵的，不是增熵的，越聚焦越有效。

5.2 坑二：计划质量直接取决于需求质量

superpowers 的 code review 环节确实能拦住大部分偏差，但有一个环节它拦不住：需求本身模糊时，计划也会模糊，甚至错误。有一次我图省事，把需求描述得含糊，计划阶段它产出了一份看起来完整、实则方向跑偏的方案，我偷懒没仔细审，结果后面返工了整整一天。现在我的经验是：brainstorm 阶段多花十分钟，把边界条件和异常路径聊透，后面能省一小时。这个环节千万别跳。

5.3 坑三：验证命令要按项目实际改，不能照搬默认

TDD 技能默认会跑一些通用测试命令，但 Java 项目差异很大，有 Maven 也有 Gradle，有 JUnit 4 也有 JUnit 5，还有 Lombok、Mockito 这些依赖。如果技能里的验证命令和项目实际不符，Codex 就会跑错命令，然后得出"测试挂了"的错误结论。解决办法就是我在 4.2 里说的，把项目真实的测试命令和构建方式写进项目记忆，确保它每一步都能验证在正确的环境里。

5.4 三个让我回不去的瞬间

第一个瞬间，是它在 Java 项目里主动跑完./mvnw test告诉我绿灯的那一刻。过去一年我习惯了 AI 写完代码丢给我验证，那是我第一次感觉到工作流闭环了。

第二个瞬间，是它修完一个并发 bug 后补了一个压力测试。那不是我会要求它做的事，但它是技能里"修复后补回归测试"这条规则驱动出来的。规则和纪律真的能让 AI 多走一步。

第三个瞬间，是看到技能文件被团队成员 review、修改、扩展。我意识到这套东西已经超越了"工具"，成了团队工程文化的载体。那些文件里写的每一条规则，都是从我们的真实教训中沉淀出来的，这比任何文档都鲜活。

用一句话总结我的体会：superpowers 并没有让 Codex 变得更聪明，它只是让 Codex 变得"有纪律"。而纪律恰恰是 AI 辅助编程时代最稀缺的东西。如果你现在用 Codex 还处于"让它干啥它也干，但总让你提心吊胆"的状态，我强烈建议花一个下午把它装上，然后耐着性子陪它完整走一遍规划—TDD—调试—提交的流程。你可能会和当初的我一样，第一次觉得 AI 队友终于可以放心把后背交给它了。

最后分享一个小技巧：第一次跑完整流程时，把 Codex 的每一步输出都保存下来。后面再和它合作，当你觉得它"不对劲"时，翻一翻这些早期输出，你会更清楚地看到它是从哪一步开始偏离流程的。这比任何使用说明都更能教会你如何控制和引导 AI 协作，也是把 superpowers 从"工具"变成"习惯"的关键一步。