企业官网建设流程全解析

最近我把 Codex CLI 从“能用”调教到“好用”，起关键作用的就是一套叫 superpowers 的技能包。社区里 “codex superpowers”、“superpowers 使用教程” 的热度一直很高，但很多人把它当成某种神秘插件，其实它没那么玄——superpowers 本质上是一组用 Markdown 编写、遵循 Agent Skills 规范的技能文件，装上之后，你的 AI 编码助手会先规划、再拆任务、最后用测试兜底，行为方式从“立刻写代码”变成“先把活想清楚”。

这篇文章我就以 Codex CLI 为例，把 superpowers 到底是什么、为什么值得装、怎么装、以及我在 Java 项目里的实际使用记录一次讲清楚。不管是刚接触 AI 编程助手的新手，还是已经在用 Claude Code、Gemini CLI 的老手，只要你希望 AI 不仅能生成代码，还能像个正经工程师一样干活，这篇都值得看完。

1. superpowers 是什么：它不是插件，而是一套“工作方法说明书”

1.1 项目来源和核心机制

superpowers 是 Jesse Vincent（社区都叫他 obra）开源的技能集合，仓库名称就叫 obra/superpowers。它的设计目标很明确：把资深工程师的工作习惯，固化成一堆可复用的 Markdown 技能文件。这些文件放在固定的 skills 目录里，AI 编码助手在对话过程中检测到对应关键词时，会自动加载里面的指令，然后按照预设的工作流执行。

这里要强调一个很多人混淆的点：superpowers 不是插件，不是 Agent，也不是模型微调。它不改一行模型代码，只是通过结构化的提示词文档，把“怎么做项目”的流程塞进了工具的上下文里。你可以把它理解成给一位能力很强但经验不足的新员工发了一本《岗位实操手册》，手册里写了“接到需求先做什么、写代码前要产出什么、做完怎么验证”。

这套机制的底层依赖是 Anthropic 提出的 Agent Skills 规范。简单说，只要你的编码工具支持在指定目录读取 SKILL.md 文件，就能挂载 superpowers。Codex CLI、Claude Code、Gemini CLI 这些主流工具基本都支持，只是各自的 skills 目录路径略有不同。很多人搜“superpowers 安装”，装完发现不生效，八成就是目录放错了位置，后面我会专门讲。

1.2 它解决的是“AI 会写代码，但不会做项目”的问题

我在实际使用 AI 编程助手一年多，最头疼的其实不是它写不出代码，而是它“太敢写、太急着写”。给它一个需求，它恨不得一次性把整个模块生成完，然后丢给你一句“完成了”。结果往往是：没读项目 README，不知道已有约定，把别的文件改坏了，或者压根没写测试，你根本不敢合。

superpowers 就是冲着这些痛点去的。它通过一系列强约束技能，比如 planning、TDD、debugging、system-thinking，逼着 AI 在动手之前先做调研、先写计划、先设计测试。听起来像给 AI 增加了不少流程负担，但实际用下来，对于跨文件修改、新功能开发、老项目重构这类任务，这种“慢下来”反而让最终交付质量高出一大截。

1.3 和普通提示词的本质区别

可能有人觉得，我直接在对话里写“你先做个计划，再写测试，最后实现”不就行了？我也这么干过，但效果非常不稳定。普通提示词是一次性指令，这轮对话记住了，下一轮开新会话又忘光。而且没有模块化组织，AI 很容易在长篇对话里丢失约束。

superpowers 不一样。它把不同场景的工作流拆成了一个个独立技能文件，AI 检测到“请用 TDD 技能”或“帮我做一个 plan”时，会精准加载对应文件里的完整流程。技能之间还能互相调用，比如 debugging 技能会引导 AI 先复现问题、再读代码、然后调用 TDD 技能补回归测试。这是普通提示词做不到的组合能力。

2. 为什么值得装：它把 AI 从“代码生成器”变成“协作者”

2.1 不装的时候，AI 编码助手有哪些通病

我先把话说透：不装 superpowers，AI 也能干活，但典型毛病一个都跑不了。第一个毛病是不读上下文就开写。我让 Codex 给一个支付模块加个回调接口，它连项目里已有的 Result 封装类都不看，直接 return 一个 Map，风格和全项目完全不一致。第二个毛病是过度重写。改一个方法，它把整个类格式全部重排，代码 diff 大得没法 review。

第三个毛病，也是我最不能忍的：不写测试。它会用“我没有运行环境”“这个逻辑比较简单”之类的理由跳过测试，有时候甚至假装跑了测试，其实根本没跑。我后来养成了一个习惯：凡是 AI 说“测试通过”，我都要在本地手动再跑一遍。这些话听起来像吐槽，但只要你重度用过 AI 编码助手，大概率都遇到过。

2.2 装上之后，行为发生了哪些肉眼可见的变化

我第一次在 Codex CLI 里挂上 superpowers 后，做了一个最简单的实验：让它给一个工具类加一个新方法，并且明确要求使用 TDD 技能。整个过程让我有点惊讶，它没有像以前那样直接甩代码，而是先问我：“这个方法的边界条件是什么？允许 null 吗？异常怎么处理？”然后自己写了一个失败的单元测试，跑一遍确认红，再写实现，再跑一遍确认绿，最后还主动提出做一次小重构。

这背后其实就是 TDD 技能文件在起作用。AI 在上下文里读到了这样一段约束：红灯阶段必须先写一个失败测试，绿灯阶段再去写恰好能通过的实现，重构阶段必须保持所有测试通过。这套流程一旦被严格执行，AI 产出的代码质量会肉眼可见地提升。不光是测试，planning 技能还会让它在动手前把任务拆成步骤，我确认后它才真正开始写代码。

2.3 什么场景适合用，什么场景反而别用

我也得泼盆冷水，superpowers 不是万能的。它适合的是结构性、有一定复杂度的任务，比如跨模块开发、接口设计、重构、疑难 Bug 排查。这些任务需要规划、需要测试、需要系统思考，AI 走完整套流程收益很大。

但如果只是简单的“JSON 转成 Java 对象”“正则帮我写一个”“这行代码什么意思”，就完全没必要触发技能流程。强行让 AI 先写 PLAN.md 再写测试，只会增加延迟，也显得很滑稽。工具是死的，人得学会判断什么时候走大流程，什么时候直接问。我自己的经验是：超过 20 行代码的改动，或者涉及多个文件的改动，才值得让 AI 走 planning + TDD 流程。

3. 安装与配置：把 superpowers 挂到 Codex CLI 上

3.1 安装前的环境准备

安装 superpowers 本身非常简单，但有几个前置条件需要注意。第一，你需要一个支持 Agent Skills 规范的编码前端，我这里以 Codex CLI 为例。第二，本机最好装了 Git，因为我们要 clone 仓库。第三，如果你打算在 Java 项目里跑 TDD 技能，那 Maven 或 Gradle、JDK 都得准备好，AI 只是帮你写代码，运行测试还是得靠本机环境。

另外我建议你把 Codex CLI 升级到比较新的版本。老版本对 skills 目录的支持不完整，可能出现“技能文件明明在那里，但 AI 就是读不到”的情况。这种问题排查起来非常抓狂，所以最好开始就排除掉版本因素。

3.2 快速安装步骤

安装方式我推荐直接 clone 仓库然后手动复制技能目录，因为这样你能清楚地知道文件被放到了哪里，后面排查也方便。打开终端，依次执行：

git clone https://github.com/obra/superpowers.git cd superpowers ls skills

你会在 skills 目录下看到一堆子目录，每个子目录里都有一个 SKILL.md 文件，这就是一个独立技能。接下来把整个 skills 目录复制到 Codex CLI 的全局技能目录：

mkdir -p ~/.codex/skills cp -R skills/* ~/.codex/skills/

如果你用的是 Claude Code，目录则是~/.claude/skills或者项目里的.claude/skills。Gemini CLI 也有自己的对应目录，具体路径建议直接看仓库 README，因为它更新频率不低，以最新文档为准。

我个人的习惯是优先使用项目级目录，也就是在项目根目录下建.codex/skills，把需要的技能放进去。这样有两个好处：第一，技能跟着仓库走，团队成员 clone 下来就能用；第二，不同项目可以放不同技能，不会出现全局技能污染。如果你今天在给一个 Spring Boot 项目写代码，明天切到一个纯前端项目，全局技能里那套 Java 测试流程反而可能碍事。

3.3 安装后怎么验证是否生效

装完别急着写需求，先花一分钟验证。打开 Codex CLI，新建一个会话，直接问它：“what skills do you have?” 或者 “列出你当前可用的技能”。如果 superpowers 挂载成功，它会把 skills 目录下识别到的技能名称告诉你，比如 TDD、planning、debugging 这些。

我遇到过一种情况：技能文件复制过去了，AI 也能读到，但对话里提到“TDD”时它没反应。原因通常是 SKILL.md 里的 name 字段或者 description 触发的关键词和我表述的不一致。superpowers 的触发方式依赖技能文件里的描述文本，AI 通过语义匹配决定要不要加载。你直接说“用测试驱动开发的流程”，可能比说“用 TDD”更容易命中。这个问题下面专门讲。

3.4 Java 项目里怎么用 superpowers

很多人在搜“superpowers java”，其实问的就是 Java 项目接入方式。我建议在 Java 项目根目录建.codex/skills，只复制你需要的技能，比如 TDD、planning、debugging、java-common 之类的。

然后打开 Codex CLI，输入类似这样的指令：“使用 TDD 技能，为 OrderService 添加 findById 方法，该方法在订单不存在时抛出 OrderNotFoundException。”你会发现 AI 会先识别项目的构建工具，是 Maven 还是 Gradle，再确定测试框架是 JUnit 5 还是 TestNG，然后按照红灯、绿灯、重构的流程执行。这里我提醒一句：项目初始化信息非常重要。如果项目结构特殊，比如用了多模块 Maven，最好先让 AI 读一下根 pom.xml，再让它动笔。

4. 核心技能拆解：superpowers 使用指南

4.1 planning：动手之前，先让 AI 交一份“作战计划”

planning 是我使用频率最高的技能。触发方式很简单，你可以在需求描述里明确说“先做一个 plan”，AI 就会加载规划流程。它的执行路径大概是：先扫描项目结构，读 README、AGENTS.md 之类的说明文档，梳理现有代码，然后输出一份 PLAN.md，列出要实现的目标、拆解出的任务列表、每个任务的依赖顺序。

你可能会问：AI 生成一份计划不是更浪费时间吗？我的体会是：对于小改动确实浪费时间，但对于跨文件需求，这份计划能救你的命。因为你在确认阶段就能发现 AI 的理解有没有跑偏。比如上个星期我让它给一个数据同步模块加断点续传，它生成的计划里居然出现了“引入消息队列”这种我完全没提过的方案。我当场就否掉了，让它在现有文件里做增量修改。如果没有 planning 这一步，它可能直接就开始写消息队列的代码了。

计划确认后，AI 会把 PLAN.md 当作执行蓝图，后续每一步都对照计划来。你可以随时要求它“打开计划，汇报进度”。唯一要注意的是，如果计划文件生成在项目目录里，记得把它加进 .gitignore，别提交到仓库。

4.2 TDD：红灯、绿灯、重构，这套流程治“乱写代码”很管用

TDD 技能在 Java 项目里特别好用，因为它和 JUnit 是天作之合。标准流程分三步：红灯阶段，先写一个失败测试，明确新功能的预期行为；绿灯阶段，写恰好能让测试通过的实现代码；重构阶段，在测试保护下优化代码结构，去掉重复。

这个顺序有一个容易忽略的价值：它逼着 AI 先想清楚“怎么验证”，再想“怎么实现”。很多时候我们让 AI 直接写功能，它写出来的东西表面看着对，但一跑测试就露馅。而 TDD 流程把测试写在前面，等于是给后续所有改动上了一道保险。我在实操中会让 AI 在红灯阶段把测试运行结果贴出来，确认它确实看到失败，再进入绿灯阶段。这样可以防止 AI 假装写了测试。

4.3 debugging：用证据链代替瞎猜

排障是 AI 最容易被高估的场景，因为模型很擅长一本正经地胡说。superpowers 里的 debugging 技能设计得比较务实：先要求 AI 复现问题，再让它收集日志、堆栈、相关代码这些证据，然后基于证据提出假设，最后用最小改动修复，并补一条回归测试。

我以前让 AI 修 Bug，它经常直接给我一版重写的代码，理由是“这代码写得不太好”。有了 debugging 技能后，它会强制自己先回答几个问题：这个 Bug 是必现还是偶发？最近改过哪行代码？日志里有什么异常？这些都是新手工程师最容易忽略的基本功。说实话，我有时候觉得这套流程对我自己排错也有参考价值。

4.4 system-thinking、code-review 以及其他值得关注的技能

除了上面几个，superpowers 还带了不少有意思的技能。system-thinking 会在 AI 修改某个模块时，主动分析上下游依赖和潜在副作用。code-review 则会按一个审查清单逐项检查代码：有没有边界条件、有没有资源泄漏、日志是否合理、命名是否清晰。

我实际用下来，code-review 技能是最容易给惊喜的。让 AI 自己 review 自己写的代码，虽然听起来有点自欺欺人，但它的视角确实和“写代码模式”不同，经常能挑出我忽略的 edge case。我的用法是：AI 实现完一个功能后，我会追加一句“现在用 code-review 技能审查你刚才的代码”，往往能多抓出几个问题。

5. 实操记录：在 Spring Boot 项目里用 superpowers 完成邮箱校验模块

5.1 需求背景和第一轮对话

为了让你对整套流程有直观感受，我记录一次真实的实操。项目是一个 Spring Boot 用户服务，需求是给注册接口增加邮箱格式校验。我打开 Codex CLI，输入：

先使用 planning 技能为以下需求生成计划：在现有用户注册流程中增加邮箱格式校验，采用项目现有的异常体系，不改变接口签名。

你会看到 AI 先列出了项目探索步骤。它读取了 controller、service、exception 包的代码，确认了项目用的是自研 BusinessException，而不是全局返回错误码。然后在 PLAN.md 中写了三条任务：定义 EmailValidator 工具类、在 UserService 中集成校验、补充单元测试。

这一步我对计划做了调整：我要求把校验逻辑放在 service 层，因为 controller 层目前只做参数接收。AI 更新了计划，然后问我是否确认执行。我输入“确认”，它才开始写代码。

5.2 进入 TDD 流程后的关键代码

确认计划后，我追加了一句：“按 TDD 技能执行。”AI 先创建了测试类 EmailValidatorTest，写了一个失败测试：

class EmailValidatorTest { @Test void shouldRejectInvalidEmail() { assertFalse(EmailValidator.isValid("not-an-email")); } }

它运行测试，确认红灯，然后写实现：

public class EmailValidator { private static final Pattern PATTERN = Pattern.compile("^[A-Za-z0-9+_.-]+@[A-Za-z0-9.-]+$"); private EmailValidator() {} public static boolean isValid(String email) { if (email == null || email.isBlank()) { return false; } return PATTERN.matcher(email).matches(); } }

随后运行全部测试，确认绿灯。这一步我特意观察了它的行为：它没有直接改 UserService，而是先问我要不要把校验逻辑放进现有 validate 方法里。这说明计划文件确实在起作用，它知道自己还没执行到“集成”这一步。

5.3 集成与验证阶段

在集成阶段，AI 修改了 UserService 的注册方法，在保存用户前调用了 EmailValidator.isValid，失败时抛出 BusinessException。它还顺手补了一个集成测试，测试注册接口对非法邮箱返回 400。最后我自己在本地跑了一次mvn test，全部通过。

整个过程中 AI 没有碰 controller 层，也没有改动其他无关文件。对我这种有代码洁癖的人来说，这体验比之前的裸奔状态好太多了。以前让 Codex 干这活，它大概率会直接塞一个 Spring 的 @Email 注解进去，然后告诉你“搞定了”，完全不考虑项目里已经有一套自定义校验规范。

6. 常见问题与排查实录

6.1 技能文件放好了，但 AI 就是识别不到

这个问题我遇到过不下三次。排查顺序是这样的：第一步确认你的工具版本支持 Agent Skills；第二步检查目录路径，Codex CLI 在用~/.codex/skills，项目级是.codex/skills，Claude Code 是.claude/skills，别放混；第三步检查 SKILL.md 文件是否直接在技能目录下，不要多套一层目录；第四步，开一个新会话再试，因为技能通常在会话初始化时加载。

如果还是不行，就在对话里直接问 AI 的可用技能。它还说不出来，就把仓库 README 里的安装文档和你的目录结构逐行对比，基本都能解决。还有一种隐蔽情况：项目根目录有 .gitignore 把 skills 目录忽略了，某些工具扫描时会跳过被忽略的目录，非常坑。

6.2 生成的计划太长，AI 光写计划就花了好几分钟

planning 技能默认会把计划写得比较细，但如果你只想快速推进，可以在需求里直接指定计划格式，比如“计划不超过五条，每条一句话”。AI 会尊重这个约束。我后来养成了一个习惯：让 AI 先给出“一句话目标 + 三条以内任务”的极简计划，确认方向对了，再让它展开细节。这比让 AI 一次性产出一份十页计划效率高得多。

6.3 AI 在 Java 项目里写测试时用的 JUnit 版本不对

这是个高频问题。比如项目用的是 JUnit 5，AI 却写出 JUnit 4 的@Test导入和Assert.assertEquals，甚至引入 TestNG。原因是技能文件本身是通用的，不感知项目具体技术栈。

解决办法很简单：在需求描述里显式带上技术栈信息，比如“使用 JUnit 5、Java 17、Maven”。或者更稳妥一点，在项目根目录维护一份 AGENTS.md，写明构建工具、JDK 版本、测试框架、常用代码风格。AI 在规划阶段会优先读这个文件，很多技术栈错配问题都能提前避免。

6.4 AI 不按技能执行，问了 TDD 还是直接写实现

这种“有技能不用”的情况，我摸索出一个规律：触发词太模糊。你说“测试先行”或“TDD 一下”，AI 不一定能把它和 SKILL.md 里的名字对上。最稳定的做法是直接说“加载并执行 TDD 技能”，或者“使用 superpowers 中的 planning 技能”。描述得越明确，AI 越容易命中对应文档。

另一个原因可能是会话上下文太长，技能指令被冲掉了。遇到这种情况，我一般直接开一个新会话，把需求和“使用 XXX 技能”放在第一句话。

6.5 有人问“worbuddy 怎么用 superpowers”这类问题

社群里经常看到“worbuddy 怎么用 superpowers”这样的提问，我理解大家真正想问的是：能不能把 superpowers 接到我习惯使用的编码工具或工作流里。答案是可以，而且原理都一样。不管它叫什么名字，只要它支持 Agent Skills 或兼容的技能加载机制，你要做的就是找到它的 skills 目录，把 superpowers 里的技能放进去，然后确认工具版本够新。核心从来不是某个特定工具，而是“项目有技能目录”这件事。

6.6 常见问题速查表

7. 我的使用心得与后续玩法

7.1 别把流程当仪式，价值在于“前置思考”

我得说句实话：superpowers 的每个技能本身并不复杂，planning 就是先写计划，TDD 就是先写测试，这些道理工程师都懂。它真正值钱的地方，是把这些道理变成了 AI 默认的行为习惯。以前我每次都要在需求里反复叮嘱，现在只要挂载了技能，它自己就会走流程。

所以我建议你不要为了用技能而用技能。一个 30 秒能改完的配置项，非要走完整 TDD 流程，那就是给自己添堵。判断标准很简单：这个改动如果交给一个中级工程师，对方需要做设计、需要验证、需要保护性测试吗？需要，就让 AI 走完整流程；不需要，直接问答即可。

7.2 把 superpowers 当成“新人培训手册”，按需改造

superpowers 的技能文件是 Markdown 写的，这意味着你可以很轻松地改造成适合自己团队的样子。我就在 TDD 技能文件里加了一条：“如果项目使用 JUnit 5，测试类命名必须以 Test 结尾；不允许使用 System.out 输出。”AI 后续生成的代码就完全遵守了这条规则。

我强烈建议你把团队自己的代码规范、异常处理约定、日志规范写进 AGENTS.md，再配合 superpowers 的技能文件使用。两者叠加的效果，比你单独用任何一个都强得多。本质上，这就是把团队里“高年级工程师带新人”的方法论，原样复制给了 AI。

7.3 多学一手：自己也能写技能文件

用了几个星期后，我开始尝试给自己的工作流写自定义技能。比如我写了一个 release 技能，里面规定 AI 发布前必须做这几件事：检查版本号、更新 CHANGELOG、运行全量测试、检查未提交文件。目录结构很简单：

my-company-skills/release/SKILL.md

SKILL.md 里写清楚 name 和 description，正文就是 Markdown 指令。AI 看到“使用 release 技能”后，就会按照正文执行。这套机制的学习成本非常低，但收益可以累积。你能不能把团队里那些“老师说了一万遍还是会有人忘”的事，都写成技能塞给 AI？我觉得可以，而且值得试。