企业官网建设流程全解析

最近我在给 Codex 调教工作流的时候，发现十个人里有八个人都在聊 superpowers。这个词在开发者圈子里已经快变成一个固定搭配了：superpowers 使用指南、superpowers 安装、superpowers java、codex superpowers，随手一搜全是教程。但我翻了很久，大多数文章不是讲得太玄，就是把安装过程一笔带过，实操的时候该踩的坑一个没少。

所以这篇文章我打算彻底讲清楚：superpowers 到底是什么、它解决什么问题、怎么安装、怎么在真实的 Java 项目里用起来，以及我实际用下来遇到过哪些坑。本文不念说明书，只讲经过验证的操作路径，适合已经在用 Codex 这类 AI 编程工具、但觉得“AI 能干活但不听话”的开发者。

1. 先搞清楚 superpowers 到底是什么

1.1 我为什么开始折腾 superpowers

我最早遇到的问题是：用 Codex 帮我改代码，它总是“一步到位”但“一步跑偏”。让它修一个 bug，它顺手把整个模块的命名风格改了；让它补单元测试，它只写了两个 happy path，边界条件全没覆盖；让它做代码审查，它给的建议像是从通用规范里复制粘贴的，完全没结合项目上下文。

后来我才意识到，问题不在 Codex 本身，而在“没有给它结构化的做事方法”。大语言模型非常擅长单点生成，但不擅长自己组织一套多层次的工作流。如果没有明确步骤和约束，它就会用最省 token 的方式完成任务，结果就是我们常见的“看起来在干活，实际在瞎干”。

superpowers 的思路就是给这类 AI 编程代理安装一套“技能包”。它不是一个模型，不是花哨的 IDE 插件，而是一堆经过整理的 markdown 技能文件，每个技能文件都对应一种工作能力。比如规划能力、实现能力、测试能力、代码审查能力。AI 代理加载这些技能之后，会按照文件里的步骤来思考和执行，而不是自由发挥。

1.2 superpowers 与普通 prompt 的核心区别

很多新手会把 superpowers 理解成“一堆好用的 prompt”，这没错，但不完整。普通 prompt 是一次性的，你需要每次都重新把要求打一遍；superpowers 里的技能文件是持久化的，AI 每次工作前都能主动读取对应的技能说明，把“操作手册”固定在项目里。

它和传统插件还不一样。插件往往需要安装运行时、依赖某个框架，而 superpowers 的每个技能本质上就是一个目录，里面有SKILL.md作为主说明文件，可能还附带一些辅助脚本、模板、示例代码。你甚至不需要联网下载任何二进制，只要把目录放到项目里，让 AI 能读到就行。

这里我做了一个小对比表，方便理解：

它的核心价值是“把工作方法固化下来”。团队里如果每个人都用同一套 superpowers，AI 生成的代码风格和操作流程就会高度一致，这是在多人协作场景下最有吸引力的点。

2. 安装 superpowers 的思路和两种常用方式

2.1 装之前先把环境确认好

superpowers 本身不是一个大型软件，它对环境要求很低。理论上你只要有 Git 和 Node.js 就能跑，如果你是在 Java 项目里用它，还需要把 Maven 或 Gradle 先装好，因为很多技能脚本会直接调用构建工具。

我用一句口诀概括安装要点：先确认 CLI 能跑，再拉仓库，然后跑安装脚本，最后手动验证技能文件是否被识别。顺序不能乱，很多人跳过了最后一步，结果 AI 根本没读到技能，全白干。

我实际测试时的环境：

• 操作系统：macOS（Linux 同理）
• CLI：Codex 最新版
• Node.js：v20.11+
• Git：2.39+
• Java 项目：JDK 17 + Maven 3.9

如果你在公司电脑上装，先确认能不能访问 GitHub，以及有没有全局代理配置。这里我不展开，但环境不通会导致拉取失败或者安装脚本卡住。

2.2 方式一：从仓库克隆并跑安装脚本

这是官方 README 里最推荐的安装方式，也是我觉得最适合新手的路径。打开终端执行：

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

脚本会检查你的 CLI 配置目录，然后把技能文件复制到全局目录里。装完以后，你启动 Codex 或者 Claude Code 时，它会在启动阶段扫描这些目录，并列出可用的技能。

我第一次跑的时候脚本卡了几秒，控制台没有任何日志。后来才知道是脚本在等权限确认，按了一次回车才继续。所以这里有个经验：如果安装脚本看起来“卡住了”，先等一下，不要立刻 Ctrl+C。

装完之后，建议手动验证一下目录结构。通常你会看到类似这样的路径：

~/.codex/skills/ ├── brainstorm/ │ └── SKILL.md ├── planning/ │ └── SKILL.md ├── implementation/ │ ├── SKILL.md │ └── templates/ └── testing/ ├── SKILL.md └── checklist.md

验证方法很简单：直接问你的 Codex“你现在有哪些技能”，如果它能列出来一堆带说明的技能名字，就说明安装成功。

2.3 方式二：手动配置到项目里

有时候你并不想把 superpowers 装到全局，而是只想给某个项目使用。比如一个团队统一用一套定制技能，就不应该依赖成员个人的全局目录。这种情况下，我推荐手动配置到项目里。

以 Codex 为例，你可以在项目根目录创建一个类似.codex/skills的目录，然后把需要的技能文件夹整个复制进去。之后在这个项目目录里启动 Codex，它会自动加载项目级技能。

对于 Java 项目，我通常建议在项目根目录放一个superpowers/文件夹，专门存放团队技能和脚本。这样做的好处是，技能文件跟随 Git 仓库走，新成员 clone 下来就自动拥有同一套能力，不需要额外安装。

手动配置的步骤如下：

1. 创建项目技能目录，例如.codex/skills。
2. 从 superpowers 仓库复制你需要的技能文件夹过去。
3. 用桌面端或 CLI 测试 AI 是否能读取到技能。
4. 在 README 里记录技能使用方法，方便同事上手。

这种方式比全局安装更可控，也更能体现团队协作价值。

2.4 安装前后对比：AI 的行为差异

安装之前，我让 Codex“给一个 Java 类写单元测试”，它直接生成了一堆 JUnit 代码，然后就不管了。装完 superpowers 之后，同样的请求，它会先输出测试计划，列出覆盖列表，询问我是否需要数据夹具，最后才生成代码。它甚至会用技能文件里的 checklists 来自查一遍。

这种变化不是玄学，而是因为它加载了技能文件里对任务的定义和流程约束。我特别建议新手安装完先做这个对比实验，否则你很难体会到 superpowers 的价值。

3. 在 Java 项目里用 superpowers 跑通一个实战任务

3.1 任务背景：给一个计算器类补全单元测试

我选了一个非常典型的场景：一个 Java 项目里有Calculator类，包含add、divide、power这几个方法。我想让 Codex 基于 superpowers 的“测试技能”，帮我把单元测试补全。

这个场景能充分展示 superpowers 的效果，因为需求看起来简单，但隐藏了不少坑：divide方法要考虑除零异常，power方法要考虑大数溢出和负数指数，这些细节如果没有测试计划，AI 很容易漏掉。

先看下原有的 Java 类长什么样：

public class Calculator { public int add(int a, int b) { return a + b; } public double divide(int a, int b) { return (double) a / b; } public long power(int base, int exponent) { return (long) Math.pow(base, exponent); } }

这个类有个明显的常识性问题：divide方法没有处理b == 0的情况。这种逻辑缺陷正好是 AI 技能发挥作用的地方，因为它会引导 AI 先思考输入边界，而不是直接机械翻译代码。

3.2 使用技能的第一步：先规划再动手

在 superpowers 里，最核心的一个技能就是“计划先行”。我并没有直接让 Codex 生成测试代码，而是先让它使用 planning 技能输出一份计划。

具体的做法是，在启动 Codex 之后，我给它这样的指令：

请先使用 planning 技能，分析这个项目中 Calculator 类需要覆盖的测试场景，然后输出一份测试计划。不要直接写代码。

然后 Codex 加载了技能文件，输出了一份比较完整的计划。计划里包含这些要点：

• 正常情况下的加法测试
• 大数相加溢出测试
• 正常除法测试
• 除数为零的异常测试
• 负指数测试
• 幂运算结果溢出测试
• 边界值输入测试

这里你能看到，superpowers 的价值不是“让 AI 更聪明”，而是“让 AI 不偷懒”。它把程序员平时做测试设计时的那套经验模板化了。

3.3 让 AI 按计划执行并生成代码

计划确认之后，我再告诉 Codex：

计划已经确认，请按计划逐条实现测试，并用 Maven 运行所有测试，最终告诉我哪些用例通过、哪些失败。

这次生成的质量明显高很多。它不仅写了@Test方法，而且还给divide方法预设了ArithmeticException的断言，因为在计划阶段就已经识别出了除零问题。

Codex 最终生成的测试类大概长这样：

import org.junit.jupiter.api.Test; import static org.junit.jupiter.api.Assertions.*; class CalculatorTest { private final Calculator calculator = new Calculator(); @Test void add_shouldReturnSumOfTwoNumbers() { assertEquals(5, calculator.add(2, 3)); } @Test void add_shouldHandleOverflow() { assertEquals((long) Integer.MAX_VALUE + 1, calculator.add(Integer.MAX_VALUE, 1)); } @Test void divide_shouldReturnQuotient() { assertEquals(2.5, calculator.divide(5, 2), 0.0001); } @Test void divide_shouldThrowWhenDivisorIsZero() { assertThrows(ArithmeticException.class, () -> calculator.divide(1, 0)); } }

注意，这时候 AI 生成的测试代码里提到了calculator.divide(1, 0)会抛异常，但原类里其实没有这个逻辑。这一步是非常重要的：检测到了一个 bug。也就是说，superpowers 成功地把 AI 从“代码生成器”变成了“工程质量审查员”。

3.4 修复代码并回归测试

测试跑完之后有红有绿，Codex 主动分析了失败原因，并建议修改Calculator类中的divide方法。在它的技能文件里，有一条规则是“修复代码前必须重新分析原有逻辑”。于是它先给出修复方案，再修改代码。

最终的divide方法被改成：

public double divide(int a, int b) { if (b == 0) { throw new ArithmeticException("Cannot divide by zero"); } return (double) a / b; }

修改之后，再次运行mvn test，所有测试通过。

这个流程看起来平淡，但实际上已经完成了一个完整的“计划—执行—验证—修复”循环，这正是 superpowers 最核心的日常工作模式。如果你只用普通 prompt，Codex 大概率会直接生成一堆代码，然后跑一次测试告诉你通过，完全不会主动检查被测类本身的逻辑缺陷。

3.5 在 Java 项目里使用 superpowers 的最佳实践

我用了大概两周之后，总结出几个适合 Java 项目的黄金姿势：

• 项目根目录固定一个 skills 目录，让团队成员共享同一套技能。
• 把 Maven/Gradle 的 wrapper 纳入版本管理，确保 AI 执行的构建命令在任何机器上结果一致。
• 让 AI 每次动手前先写计划，并保存在一个plans/目录里，方便追溯。
• 技能文件里的模板不要盲改，先确认改动不会影响其他技能的执行流程。

这些做法不复杂，但对稳定性提升非常大。尤其是 Maven wrapper 这一点，我在 CI 环境里遇到过太多次“本机能跑、CI 上跑不了”的问题，都是因为大家用的 Maven 版本不一致。

4. 常见问题与排查技巧实录

4.1 装了技能但 AI 完全没反应

这是最常见的问题，很多人安装 superpowers 后，发现 AI 的行为跟以前一模一样，感觉白装了。

我遇到这种问题会按顺序排查：

1. 检查技能目录是否在 CLI 扫描范围内。不同的 CLI 可能只扫描特定路径，比如.codex/skills还是~/.codex/skills。
2. 询问 AI 当前可用技能。直接问“你现在有哪些技能”，如果它列不出来，说明技能没有加载。
3. 确认 SKILL.md 的格式。有些技能文件用了 YAML front matter 来声明名称和描述，如果格式错了，CLI 会跳过。

还有一种情况是，你在一个子目录里启动 CLI，而技能目录在项目外层，扫描不到。解决办法是始终从项目根目录启动，或者用 CLI 提供的配置指定路径。

4.2 Java 项目里的编码问题

superpowers 的技能脚本里经常会有“读取文件内容”、“生成代码文件”这一类操作。如果项目里有中文注释或者中文资源文件，终端默认编码不是 UTF-8 时，AI 读取的内容会乱码，它生成的代码也可能因为编码问题编译失败。

我的解决方法是，在技能执行前先设置 JVM 文件编码，直接在 Maven 的pom.xml里加上：

<properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> </properties>

或者在终端里临时设置：

export JAVA_TOOL_OPTIONS="-Dfile.encoding=UTF-8"

这个小动作能避免很多从编码引发的问题。不要小看这个，我至少看过三个人因为乱码问题放弃了 superpowers。

4.3 技能文件太多导致上下文爆炸

我用 superpowers 的初期，把所有技能都复制进项目里，结果发现 AI 每轮对话都会读取一大堆技能说明，上下文很快就满了。而且推理速度明显变慢，甚至会出现前后记忆混乱的情况。

后来我改成按需加载：项目里只放当前阶段需要的技能。比如我刚接到一个重构任务，就只放 planning、implementation、testing 三类。等重构完成，再把 documentation 技能放进去。

如果你是全局安装，也可以通过配置禁用不必要的技能。不要贪多，技能多不等于效果好，结构化的工作流才是核心。

4.4 技能修改失效或冲突

团队协作时，很可能会有人偷偷改了技能文件，结果其他人拉代码之后发现 AI 行为变了。这时候最好的排查办法是查看技能文件的 Git 提交历史。因为 superpowers 本身就是普通文件，完全可以纳入版本控制。

如果出现技能冲突，比如两个技能都定义了“测试规范”，AI 可能会不知道用哪个。我建议在文件名上做统一前缀，比如java-testing、web-testing，避免内部描述重叠。

5. 我的一些心得和避坑建议

5.1 不要把 superpowers 当成黑盒

很多人的第一个反应是“我装一个 superpowers 就完事了”，但这是错误用法。它最有价值的地方在于技能文件完全开放，你能看到 AI 每一条行为规范是从哪里来的。一旦觉得 AI 做得不好，你应该去改技能文件，而不是去改 prompt。

我现在的做法是，每遇到一次 AI 执行质量不佳的情况，都会沉淀一条新的规则到技能文件里。比如有次它生成的代码没有遵循团队的日志规范，我就把日志格式的要求写进了implementation/SKILL.md。慢慢地，superpowers 越来越像一个团队的“数字化操作手册”。

5.2 对 Java 生态要有一点额外耐心

superpowers 最初并不是为 Java 设计的，很多技能模板里的示例脚本都偏向 JavaScript 或 Python。你用 Java 项目跑的时候，技能文件里的命令可能需要手动调整。比如构建命令从npm test改成mvn test，依赖安装从npm install改成mvn dependency:resolve。

第一次对接时你可能觉得麻烦，但这其实是好事。它逼着你把项目里“人做的操作”全部显性化。当你把 Java 项目的构建、测试、打包流程都写清楚之后，AI 在项目里的可用性会上升一个档次。

5.3 从“装技能”到“造技能”

最后我想说，superpowers 的真正价值不是“开箱即用”的那几十个技能，而是它提供了一套组织 AI 能力的框架。你完全可以在项目里创建自定义技能，把团队特有的规范、流程、checklist 都写成技能文件。

我亲自做过一个最折腾的例子：给一个老旧的 Spring Boot 项目创建“增量重构技能”。这个技能会指导 AI 每次只重构一个模块、每次改动不超过 200 行、每次重构后必须跑全量测试。因为有了这个技能，那段时间我的重构频率反而变快了，风险却降低了不少。

这个东西后续的扩展空间真的很大。你可以把它当成团队知识库的“可执行版本”，让 AI 不只是一个生成代码的工具，而是真正融入团队工作流的成员。如果你也想让 Codex 从“会写代码”变成“会做人”，我强烈建议你亲自把 superpowers 装一遍，跑一个真实任务，体验一下区别。