企业官网建设流程全解析

最近工作圈子里聊superpowers的人突然多了起来，尤其是配合codex一起用的那批开发者。我最初看到几个 Java 同行在群里发截图，说自己的 AI 编码助手“突然开窍了”，会先写测试、会自己跑构建、改坏了还会回头修，当时第一反应是又出了什么黑魔法。后来耐着性子从安装到跑通一个 Spring Boot 接口完整试了一遍，才搞明白它其实是一套配置与技能集方案，把 AI 助手默认那种“问一句答一句”的被动工作方式，改造成了“接需求、拆任务、写代码、自测、修 bug”的完整工作流。

这篇文章不是官方文档的翻译，而是我从零开始装、配、用的一份实测记录。重点讲三件事：superpowers到底解决了什么问题，它安装配置的核心逻辑是什么，以及在一个真实的 Java/Maven 项目里怎么把它用起来。不管你用的是原生 codex cli，还是基于它的二次封装工具，底层思路基本一致，看完应该能直接照做。

1. 先搞明白 superpowers 到底是什么，别急着装

很多人一上来就 clone 仓库、跑安装脚本，结果装完发现 AI 助手的行为没有任何变化，就开始骂“又是割韭菜”。其实问题不出在工具上，而是没搞懂它的运行原理。

1.1 给 AI 编码助手装“外挂”：一个很朴素的需求

先还原一下默认状态下 codex cli 的工作方式。你给它一句“帮我写个用户注册接口”，它在终端里生成几段代码，你复制粘贴，然后自己去找 maven 编译错误，自己补测试，整个流程和搜索引擎差不多。问题在于，AI 本身能力是够的，但缺少一套约束机制，导致它不会主动规划、不会先写测试、也不会在改代码后自己跑验证。

superpowers这个项目想解决的，就是这件事。它本质上是一组打包好的规则文件和技能（skill）文件，安装之后会挂载到 AI 编码助手的会话进程里。AI 每次收到任务，会先读到这些规则，知道“哦，原来这个项目的老板要求我先拆任务、再写失败测试、然后实现、最后跑通才算完”。所以它带来的不是模型智商提升，而是工作习惯的规范化。用一个生活化的类比，就是给一个很聪明但没什么章法的实习生，发了一本极其详细的《项目操作手册》和一套《工具箱》，让他知道什么时候该用什么工具，做完一步下一步干什么。

这也是为什么很多人在推特上看到演示视频觉得“这 AI 成精了”，但自己装完却无感——大概率是没把配置正确挂载到会话里，AI 根本没读到那本手册。

1.2 为什么叫“超能力”：到底增强了哪些能力

superpowers里预置的技能通常覆盖几个方面。任务规划能力，让 AI 面对复杂需求先拆解再动手，而不是直接丢掉上下文就开始写；测试驱动开发能力，强制它先写失败的单测，再写实现代码，最后运行测试验证；调试巡检能力，在测试失败时自动读取错误日志、修改代码、重跑测试，直到通过；还有代码规范能力，让 AI 遵循项目的命名、目录结构、构建工具约定。

对 Java 开发者来说，这几项能力尤其对胃口。Java 项目普遍依赖 Maven/Gradle 构建，有严格的工程结构和单元测试习惯，AI 默认模式下经常写出不符合项目规范的代码，而有了配置约束之后，它会主动调用 Maven 相关技能，至少能做到“生成的代码能在当前工程里跑起来”。

当然“超能力”这个名字多少有点营销味，我更愿意把它理解为一套行为框架。它的价值不是让 AI 变聪明，而是让 AI 变得可靠。聪明是模型层面的事，可靠则是工程层面的事，后者恰恰是日常开发最需要的。

2. 安装前，先把环境和思路理清楚

任何工具装不上或者装了没用，八成是前置环境没对齐，或者安装方式选错。这节我把前置依赖和两种常见安装方式写清楚。

2.1 前置依赖：Node、Codex CLI、Git

我实测下来，superpowers这类技能集工具一般以 Node.js 脚本或 shell 脚本分发，所以几样东西是跑不掉的：Node.js（建议 18 或 20 以上，太低版本容易遇到语法不兼容）、Git（clone 仓库和版本管理用）、codex cli 或者兼容它的 AI 编码助手 CLI。Java 项目本身还需要 JDK 和 Maven/Gradle，这个和superpowers没有直接关系，但建议把 JDK 17+ 装好，Spring Boot 3.x 项目用得上。

验证环境的命令很简单：

node -v git --version codex --version java -version mvn -v

我在配置时发现一个容易忽略的点：codex cli 需要先完成认证和登录，否则后续安装脚本测试调用时会直接报权限错误。这个认证环节每家 CLI 不一样，有的是浏览器 OAuth，有的是 API Key，按官方文档走一遍即可。另外提醒一句，如果你在代理环境下操作，注意让终端代理对 GitHub 和 npm 生效，不然 clone 和安装依赖容易超时。

2.2 安装 superpowers 的两种典型方式

以社区最常见的做法为例，第一种是全局安装，把技能集放到用户目录，让所有项目共享。大概流程是：

git clone <你的仓库地址> ~/.superpowers cd ~/.superpowers ./install.sh

安装脚本一般会把技能目录、规则文件链接到 CLI 的配置目录里，或者生成一份引用文件。第二种是项目级挂载，适合需要定制或者团队统一规范的场景。在项目根目录执行一些初始化命令，把技能文件复制进来，然后在项目的 AGENTS.md 或等价配置里引入。

装完之后别急着用，先验证文件是否就位。通常你会看到类似这样的结构：

~/.superpowers/ ├── SUPER.md ├── AGENTS.md ├── skills/ │ ├── plan.md │ ├── tdd.md │ ├── debug.md │ └── java-build.md └── memory/ └── project-log.md

这些文件名在不同发行版里可能有差异，但总体的模块划分八九不离十。如果发现目录是空的或者只有 README，那说明安装脚本没有真正执行成功。这时候去看安装日志，多半是 shell 权限问题或者 Node 版本不对。

顺便提一下团队封装工具的情况。有些读者提到团队内部在用基于 codex 的二次封装工具（比如有人叫 workbuddy 之类的工作台），想知道能不能也用上superpowers。答案是能，只要底层还是调用同一套 CLI 协议，你只需把技能目录和规则文件挂载到封装工具对应的配置位置，原理是一样的。如果封装工具屏蔽了配置接口，那就只能等团队更新适配。

3. 核心配置拆解：技能是怎么被“叫醒”的

安装只是把文件放到硬盘上，真正决定 AI 行为的是配置文件里的引用关系和技能触发机制。这一节直接拆开看。

3.1 配置文件和目录结构：谁在指挥 AI

以我目前这套配置为例，项目根目录下会有一个AGENTS.md，这是 AI 编码助手启动时默认读取的规则文件。它相当于项目的“宪法”，里面写明了 AI 需要遵守的行为准则。而superpowers的技能文件则放在单独的目录里，通过在AGENTS.md中引用，让 AI 知道在什么场景下该去读哪个技能文件。

关键的引用方式一般是这样的：

# AGENTS.md ## 规则 - 开始任务前，必须先阅读 skills/plan.md 并输出实施计划。 - 涉及代码实现时，必须先写失败的单测，再写实现。 - 允许运行 mvn test 与 mvn compile 进行验证。 ## 技能 - 当任务包含测试时，加载 skills/tdd.md。 - 当构建失败时，加载 skills/debug.md。 - 当任务属于 Java 模块时，加载 skills/java-build.md。

AI 每次会话启动就会读到这份文件，所以它的行为不是随机生成的，而是被这些规则锚定住了。这一步是整个配置的灵魂，很多人安装完没感觉，就是因为 AGENTS.md 没有正确配置，AI 根本不知道技能文件的存在。

3.2 技能触发机制：AI 怎么知道自己该用哪个

技能文件本身不是被 AI“闭眼读”的，而是按需触发。常见的触发方式有几种：关键词触发、命令触发、上下文触发。比如当用户的自然语言里包含“测试”“单测”“test”这些词时，配置了tdd.md技能的 AI 会去加载它；当 AI 发现编译错误时，它会主动读取debug.md里的排查流程；当检测到当前目录有 pom.xml 时，它会调用 Java 构建技能。

我打个比方你就明白了。这就像你在 IDE 里装了一堆插件，插件不是同时运行，而是等你在文件里敲出特定代码时才给出提示。superpowers的技能文件就是给 AI 的“插件”，AGENTS.md 里的规则就是插件的激活条件。

多个技能之间还可以协作。比如 AI 接到一个“给订单模块加个状态查询接口”的任务，流程可能变成：先读取 plan.md 拆解任务，然后用 tdd.md 的规则先写测试，再用 java-build.md 的技能跑 Maven 编译，最后用 debug.md 处理测试失败。整个过程像一个流水线，而不是一个孤立的单次回答。

3.3 给 Java 项目定制一份自己的配置

superpowers默认技能里大概率有通用的编程技能，但 Java 项目的构建方式和脚本语言完全不同，所以定制一份 Java 专属配置是很有必要的。我自己的配置里就额外加了一个java-build.md：

# skills/java-build.md ## 构建指令 - 当前项目使用 Maven，执行命令 mvn compile、mvn test、mvn package。 - 模块路径变化时，使用 -pl 参数指定模块。 - 编译失败时，先读取错误日志中的 Java 文件路径和行号，修复后再编译。 ## 代码风格 - 使用 SLF4J 进行日志输出。 - 错误处理统一返回 Result<T> 包装类型。 - 不要在实体类里写业务逻辑。

这一步的好处是 AI 在项目里生成代码时，会自带“这个项目是 Maven 结构、需要统一返回类型”这类上下文，而不是输出一堆风格随缘的代码。我建议每个 Java 团队都维护一份这样的技能文件，成本极低，收益却很明显。

4. 实战：用 superpowers 在 Java 项目里跑通一个接口

前面讲了一堆原理，这节来点真刀真枪的。我以一个 Spring Boot 项目为例，目标是在项目里新增一个用户注册接口，并带单元测试。整个过程我都让 AI 按照superpowers的规则自主完成，我只负责观察和记录。

4.1 场景设定与初始状态

项目是标准的 Spring Boot 3.x + Maven 结构，JDK 17，已经初始化好了一个空的 Spring Boot 工程。项目根目录下放好了 AGENTS.md 和 skills 目录，并且已经验证了superpowers配置能被 codex cli 读取。

让我特别提一下初始化这一步。我并没有手动写任何业务代码，只是把工程骨架弄好，剩下的交互都发生在终端里。这种“人写环境、AI 写代码”的工作方式，适合作为团队协作的模板，因为环境一致性有保障，AI 生成的代码也更容易跑通。

然后我给出第一个指令：

请使用项目里的技能规则，为我实现用户注册接口。要求先给出实施计划，再写测试，最后实现并运行测试验证。

注意这里我特意在 prompt 里强调“使用项目里的技能规则”，这是为了引导 AI 主动去读 AGENTS.md 和对应技能文件。如果你的配置正确，AI 不会立刻开始写代码，而是先输出一段计划。

4.2 从规划到落地的完整过程

AI 的第一轮回答是计划拆解，大致内容是：新建 UserController、UserService、UserRepository，建立数据库表结构（这里用 H2 内存库），定义用户注册请求体，编写失败的单元测试，再实现逻辑。这和人类工程师的思路基本一致，说明 plan.md 技能确实生效了。

接下来的流程让我印象很深。AI 没有直接写实现代码，而是先在 test 目录下写了UserControllerTest，里面用 MockMvc 请求注册接口，断言返回结果。写完测试后，它主动执行了：

mvn test -Dtest=UserControllerTest

结果自然是编译失败，因为对应接口还不存在。这时候 AI 进入 debug.md 技能的处理流程：读取编译错误信息、定位缺少哪些类、回到 main 目录补实现代码，再重新跑测试。这个“失败-修复-重跑”的循环重复了三次，第一次是缺少依赖，第二次是请求参数校验不符合预期，第三次终于全绿。

整个过程我没有干预一行代码。如果你以前被 AI 生成的代码坑过，应该能理解这种体验的差异——它不再是给你一堆“看起来对但不可能编译通过”的代码块，而是会在当前工程里自己构建、自己发现错误、自己修复。

4.3 过程中 superpowers 真正起作用的地方

用完之后回头看，真正起作用的地方有三个。第一个是任务规划，AI 没有被大需求吓住，而是先把任务拆成模块和步骤，整体节奏稳了很多。第二个是测试优先，它先写测试再写实现，等于给自己设了验收标准，后面修改代码时心里有底。第三个是构建验证闭环，AI 会主动执行 Maven 命令而不是默认跳过，这让最终交付的代码基本都是能跑的状态。

当然也不是没有坑。我在第二次测试运行时发现 AI 一直盯着旧的测试结果看，没有注意到我改了 application.yml 里的数据源配置。后来我手动加了一条规则：每次修改配置类或 yml 文件后，必须重启应用上下文重跑测试。加了这条规则之后，同类问题再没出现过。

这恰好说明了一个要点：superpowers不是万能药，它是一个可以持续改进的规则框架。你每遇到一个新问题，都可以把应对方法写成一条新规则塞进去，AI 下次就会自动避开。这套“用规则对抗不确定性”的玩法，才是最值钱的部分。

5. 常见问题与排查技巧

使用过程中我踩了不少坑，也帮几个群友排查过问题。这里整理成速查表，遇到类似症状可以直接对号入座。

5.1 问题速查表：症状、原因、处理方式

排查这类问题有一个通用思路：先验证 AI 的会话里到底有没有读入规则。你可以直接在对话里问一句“当前项目下你读了哪些规则文件”，如果 AI 答不出 AGENTS.md 里的内容，说明挂载有问题；如果答出来了但行为不遵守，那就是规则本身写得太模糊，需要把触发条件和执行步骤描述得更具体。

5.2 团队封装工具与自定义场景的处理

关于团队封装工具（比如之前提到的 workbuddy 一类的工作台），我的建议是不要硬怼，先看它有没暴露“自定义规则目录”或“额外上下文文件”之类的入口。很多封装工具虽然界面不一样，但底层还是会拼接一份系统提示词，只要你能把 AGENTS.md 的内容通过它的配置项注入进去，技能就能生效。

如果封装工具完全不开放配置，那就退一步，把superpowers里的关键规则手工摘出来，作为团队内部文档的一部分，由人肉确保 AI 生成代码后按规则审查。这当然没有自动挂载方便，但总比 AI 天马行空强。

还有一个容易忽略的场景：非 Java 项目。superpowers的思想完全不绑定语言，Python 项目可以把 java-build.md 换成 pip + pytest 的技能，Node 项目则换成 npm + jest。真正可复用的不是某个文件，而是“规则驱动 AI 行为”这套方法论。

5.3 几条实操避坑心得

最后分享几条从实操里摸出来的经验，这些在官方文档里基本看不到。

第一，规则永远不要写得太抽象。像“注意代码质量”这种规则，AI 读了等于没读。要把行为和验收标准写清楚，比如“接口必须返回 Result 包装类型”“测试类命名必须以 Test 结尾”，AI 才有执行依据。

第二，不要把技能目录和项目源码混在一起。技能文件是给 AI 读的上下文，不是业务代码，混在一起容易被误打包部署。我一般把技能配置放在项目根目录下单独的.ai/目录或 docs 目录，并通过 AGENTS.md 引用。

第三，给 AI 设置文件操作边界。superpowers增强了 AI 的工具调用能力，这意味着它可能去修改配置文件和无关代码。可以在规则里明确“无提示时不得删除文件”“只允许修改指定模块下的文件”，避免 AI 自作主张破坏工程结构。

第四，定期更新技能集和规则。AI 模型在升级，技能文件也需要跟着调。我每两周会刷新一次项目规则，把团队近期踩的坑补充进去，相当于给 AI 持续做“经验培训”。这套体系跑起来之后，我发现团队里新人上手项目的速度都变快了——因为他们面对的 AI 已经学会了团队的所有约定。

按照我个人经验，superpowers这类工具最大的价值不是立刻提升代码生成速度，而是帮你建立了一套可管理的 AI 行为规范。以前 AI 是黑盒，用完就忘；现在它每次完成任务的路径、用到的技能、遇到的问题，都能通过规则文件沉淀下来。这种积累越久，AI 在项目里的表现越稳定。如果你正在用 codex cli 或者类似的 AI 编码助手，真心建议花半小时装一套试试，然后从一个小功能开始调教，慢慢你会上瘾的。