企业官网建设流程全解析

1. 不是“超能力”，是一套工程化的工作流

我见过不少团队引入 AI 编程工具之后，第一周兴奋得不行，第二周开始嫌弃——“问它改个 Bug，它给我把整个模块重写了”“让它写个单元测试，它翻来覆去就那几个同名用例”“明明上下文里说了别动数据库脚本，它转头就改了迁移文件”。

问题不在于模型能力，而在于我们把它用成了“聊天框”。你把光标一放，把需求一贴，剩下的全靠模型当场发挥。结果发挥好的时候像超能力，发挥差的时候像抽卡。如果你也受够了这种状态，Superpowers 这套工作流值得认真研究一下。

Superpowers 不是某个大厂发布的商业产品，也不是某个语言特有的语法糖，它本质上是给 AI 编程代理（尤其是 Codex CLI 这类命令行编码代理）设计的一套“能力扩展框架”。它的核心思路很朴素：把零散的提示词、项目上下文、任务拆解规则、代码检查标准，组织成一个个可以被重复调用的“技能包”。你在项目里引入这些技能包之后，代理就不再是一个只会接话的模型，而是一个按你设定的规则行动的工具。

我第一次见到这个项目时，第一反应是“这不就是个模板库吗”。后来在真实的大型 Java 项目里用了两个月，才发现它卷得比我想象中深。它不是简单地把几个 Markdown 文件塞给模型，而是提供了一整套任务编排方式：什么时候该先搜索定位，什么时候该只读不改，什么时候可以动手写代码，写完代码之后要怎么验证收敛，每一步都有对应的约束和触发机制。这东西用对了，才是真正的“超能力”——不是让 AI 替你拍脑袋，而是让 AI 严格按照项目规范干活。

换句话说，Superpowers 的核心价值不在于模型回答得多聪明，而在于“确定性”。它让 AI 的输出从随机波动变成可预期的工程交付。拿我做 Java 后端迁移那段时间举例，过去让 AI 重构一个老模块，我得花大量篇幅跟它解释：Maven 还是 Gradle、Java 版本卡在多少、可不可以引入新依赖、日志规范是什么、异常要不要包装成自定义 RuntimeException。这些话每开一个新任务就得重说一遍。用 Superpowers 之后，这些信息全部固化成了项目级技能文件，代理每次开工前自动加载，我再也不用复制粘贴那几百字的“开场白”。

所以这篇内容我不打算写成翻译文档，而是想聊清楚三件事：Superpowers 怎么装、怎么在 Java 项目里落地、怎么跟 Codex CLI 打配合。顺便把我踩过的一些坑也一并交代清楚。

2. 安装 superpowers：给 CLI 补上“能力仓库”

2.1 先搞清楚你装的是什么东西

刚开始我看文档也懵，一会儿“skills”，一会儿“workflows”，一会儿“AGENTS.md”，感觉名词满天飞。后来在本地跑通了一个最小实验，才把概念理顺。

Superpowers 的安装目标不是你当前打开的 IDE，而是你本机全局的编码代理配置目录。装上之后，它会建立一个“能力仓库”，里面按目录组织各种技能。每个技能通常包含三个东西：说明文件（描述这个技能解决什么问题）、模板文件（给代理参考的标准做法）、脚本文件（如果需要执行命令，比如编译、测试、搜索）。代理启动时，Superpowers 会把这些技能注册到自己的工具列表里，并在你输入任务关键词时自动匹配。

按我自己的理解，它相当于给代理装了一堆“预设工具”，而不是只喂一段话。区别在哪里？只喂话，模型记住了是记住了，忘了就是忘了，经常在前面表现为“哦好的，我会记住”，转头就翻脸不认账。注册成技能之后，代理每次出发前会自动检查这个能力列表中哪些适用，按固定流程执行，执行顺序和判断标准都有文件可查，不确定性被大大压缩。

2.2 最小安装路径

不同平台、不同分支的安装方式会有差异，我建议你安装前先看一眼官方仓库的 README。我自己在 macOS 上走的完整路径大概是这样：

第一步，准备一个全局目录。我习惯放到~/.superpowers，这里存放所有的技能和配置。

第二步，通过包管理器拉取主程序。现在社区主流的安装方式是 npm 或者直接从源码构建，依赖 Node.js 环境。先确认本地 node 版本在 18 以上，再执行：

npm install -g superpowers-cli

装完之后可以用一条命令校验：

superpowers --version

如果环境干净，这里会直接输出版本号。如果你跟我一样机器上同时有多个 Node 版本管理工具，建议先切到 LTS 版本再装，避免因为全局权限问题卡在EACCES这类错误上。

第三步，初始化能力仓库：

superpowers init

这条命令会在你当前用户目录下创建~/.superpowers目录结构，并在你的 shell 配置文件里注入一个代理启动辅助脚本。它的作用是让 Codex CLI 这类工具下次启动时能自动找到技能目录。

2.3 目录结构到底长什么样

初始化完成后，结构大概是这样：

.superpowers ├── skills │ ├── java-refactoring │ │ ├── SKILL.md │ │ ├── template.md │ │ └── validate.sh │ ├── dependency-analysis │ │ ├── SKILL.md │ │ ├── template.md │ │ └── rules.json │ └── ... ├── workflows │ ├── bug-fix.md │ └── feature-dev.md ├── AGENTS.md └── config.json

SKILL.md是技能的主描述文件，代理会用它判断“这个任务能不能用这个技能处理”。template.md是输出模板，告诉代理最终交付物要长成什么样。validate.sh是自动校验脚本，用来检查这次改动有没有通过测试、有没有违反静态检查规则。AGENTS.md是全局行为准则，类似于整个代理的“员工手册”，优先于大多数临时提示词。

这套结构最舒服的一点是，它把“人告诉 AI 该怎么做”这件事变成了“AI 自己查手册后再做”。你只要把判断规则写清楚，代理会自己去匹配，不需要每次对话都手动强调。

3. Java 项目里的正确用法：别让超级能力变成过度设计

3.1 Java 项目接入时我最关注的三件事

我日常工作主要是 Java 后端，Maven 和 Gradle 项目都接触，代码库动辄几十个模块。接入 Superpowers 之前，我先明确了三个目标：构建流程不能被破坏、代码风格必须统一、依赖变更必须走审查。这三件事是我对 AI 编码工具最低的容忍线。

拿代码风格来说。过去用 AI 辅助开发，最烦的就是它生成的代码“看起来没问题，但不像是这个项目里写的”。有人喜欢var满天飞，有人习惯写完整类型，有人用Optional做空值兜底，有人坚持Objects.requireNonNull。这些东西靠临时提示词约束效果很差，因为模型在聊到一半的时候容易丢失上下文。Superpowers 的解决方式是把风格规则写进技能模板。

我在java-refactoring技能里写了一段约束：

- 使用 Java 17 语法，但不要使用 var 声明公有 API 参数和返回值。 - 所有对外方法参数使用 final 修饰。 - 禁止在既有代码中混入新的 Lombok 用法，除非项目内其他模块已经使用。 - 日志统一使用 slf4j，私有静态常量 logger 命名为 log。

这段描述每次代理执行重构任务时都会被读取，相当于把团队编码规范做成了自动执行的检查项。实际效果很直观：以前每轮让 AI 改代码，我都要花一轮对话来纠正“变量命名”“日志写法”这些细节，现在很少需要了。

3.2 把 Maven 构建校验接入技能

第二步是让代理在“改完代码”之后能自动验证，而不是交差了事。我给 Java 项目配置了一套子技能，命名为maven-verify，它不是让代理自己去猜，而是固定执行三条命令。

第一条是编译：

mvn -q compile

第二条是跳过集成测试的运行单元测试：

mvn -q test -DskipITs

第三条是静态检查：

mvn -q verify -DskipTests -Dspotbugs.skip=false

如果这三条命令有任何一个非零返回，技能模板里要求代理停下来，阅读报错，修正之后重新执行，直到全部通过，才能进入交付环节。

这里有个细节值得注意：不要让代理在任何情况下都跑全量测试。大项目通常包含大量集成测试，跑一次可能二十分钟，而且对环境有依赖，比如要连数据库、要拉取某个测试容器。正确的做法是让技能文件里带上触发条件，只有改动到基础设施相关代码时，才执行完整测试链路。这个判断逻辑不需要写太多行，关键是明确“什么时候可以跳过”“什么时候必须全跑”，把它固化成一串 if-else 规则。

3.3 依赖变更必须“报备”

Java 项目里最危险的操作就是让 AI 给pom.xml加依赖。它可能为了修一个顺手的小问题，给你从 Maven 中央仓库拉进来一个新版本的 JSON 库，然后整个项目的依赖冲突问题就像多米诺骨牌一样倒下来。

我在这里定的规则很硬：任何pom.xml的变更，代理都不得直接修改，只允许生成变更建议文件，由人工去合并。我是通过工作流文件实现的。在dependency-change技能里写清楚：先分析现有依赖树，再评估引入新库的必要性，最后输出dependency-proposal.md，里面要包含版本号、依赖坐标、引入原因、潜在冲突点。代理可以在建议文件里写“我建议引入 XX 版本”，但没有权限直接往pom.xml里写代码。

这套约束帮我拦住了至少三次事故。有一次它为了处理一个 JSON 字段反序列化问题，想要引入一个轻量级 JSON 工具库。我看了建议文件才意识到，项目里已经有 Jackson，只是用法不对，正确方案是配置一个自定义反序列化器，而不是新增依赖。如果让它直接改pom.xml，代码可能能跑，但维护成本和依赖膨胀就埋下了。

4. 与 Codex 联动：从“问题”到“改动”的完整链路

4.1 为什么是 Codex CLI

我日常测试过几种主流 AI 编程代理，Codex CLI 给我的感觉是最适合跑 Superpowers 这种工作流的。原因很简单：它天然以命令行工具的形式存在，系统提示词可以由用户自定义，并且可以中途调用外部脚本。Superpowers 本质上就是通过响应能力把 Codex 变成一个有自主工作流意识的开发者助手。

如果你还没装 Codex CLI，装完后先在项目根目录确认一下环境：

codex --version

目前它需要登录 OpenAI 账号，部分版本还需要配置 API Key。这一步不同版本差异很大，建议直接按官方最新的认证方式来。

启用 Superpowers 的能力仓库，需要在 Codex 的配置文件里把~/.superpowers/AGENTS.md作为附加系统提示词，并开放技能目录的读取权限。我自己的配置大致思路是这样的：

{ "model": "gpt-5", "extraContextFiles": ["~/.superpowers/AGENTS.md"], "allowedDirectories": ["~/.superpowers", "./"] }

配置完成后，启动 Codex CLI，它会自动读取全局行为准则。这个时候你再下任务，代理就不只是会聊天，而是会先从技能库里匹配可用的能力，再按工作流文件拆解任务步骤。

4.2 一个典型的“Bug 修复”闭环演示

我拿一个真实案例来演示一下工作流是怎样的。某次项目里有个接口偶发超时，线上日志指向一个老旧的同步调用，但没人愿意手动去查这条链路。

我向 Codex 发的指令很简单：

调查 payment-service 中订单状态轮询超时问题，按照 bug-fix 工作流处理。

代理收到指令之后的动作分了几步：

第一步，读取workflows/bug-fix.md。这个文件会告诉它流程是：定位问题、复现问题、分析根因、提出方案、实现修复、自动测试、输出总结。

第二步，它从技能库里匹配了java-debugging技能。技能里规定要先用搜索工具在代码库中找到相关类和配置，而不是凭记忆猜。

第三步，它沿着调用链找到了订单状态查询走的是一个同步 HTTP 调用，并且该调用设置了 10 秒超时，而支付网关平均响应时间是 8 秒。高峰期一拥堵，频繁触发超时。

第四步，它按模板提出了候选方案：改异步轮询、调大超时时间、引入熔断降级。并且在方案末尾标出推荐项是异步化，但风险和改动范围都大，建议先做超时时间调优缓解。

第五步，在得到我确认后，它进入实现阶段。按照maven-verify技能，先后执行编译和单元测试，全部通过后生成了变更摘要。

整个过程我没有去纠正它的任何步骤，它也没有跑偏重写其他模块。核心原因就在于bug-fix.md工作流文件把行动的边界画好了，技能模板又规定了每一步应该怎么做。这不是某一次大模型发挥好，而是这套机制的稳定性体现。

4.3 自定义一条新技能的最小写法

Superpowers 的一个特点是技能可以自己扩展。你不需要等官方更新的技能包，自己写一个也就十几行。

以“生成 Controller 层代码”为例。我写了一个generate-controller技能，结构非常简单：

--- name: generate-controller description: 根据 service 接口生成 Spring MVC Controller 层代码 triggers: - 生成controller - 新建controller - controller层代码 --- ## 要求 1. 根据已有 service 接口方法生成 RESTful Controller。 2. 统一使用 @RestController，不额外引入旧的 @Controller。 3. 返回类型统一封装到 Result<T>。 4. 参数校验使用 @Validated + 分组校验。 5. 不要生成无用的 swagger 注解。

这个文件放在skills/generate-controller/SKILL.md里就可以了。之后在 Codex 里只要提到“生成 controller”，代理就会自动去读这个技能的约束。你会发现它的命中率比临时提示词高很多，因为临时提示词需要你在对话里完整复述需求，而技能文件可以让代理在一开始就自查“输出是否满足约束”。

5. 我踩过的坑和现在的固定操作流程

5.1 坑一：技能文件写成了“建议”，而不是“规则”

刚开始用 Superpowers 的时候，我把 SKILL.md 写得像一篇散文。比如“尽量保持代码简洁”“注意异常处理”“规避明显的设计问题”。这种表述看着没问题，但对代理来说太模糊了，它的输出和没写这些几乎没有区别。

后来我把规则改成了带否定条件和明确指令的表达方式，比如“禁止 catch Exception 后吞掉异常”“所有 throw 出的业务异常必须是 BizException 类型”“不得在 Controller 中打印堆栈日志”。规则越具体，代理的执行越可预测。

如果你发现自己写完了技能之后跑任务，代理还是我行我素，先检查一下技能文件里面有没有出现“尽量”“可能”“建议”这类软性词汇。有的话，把它们改成“必须”“禁止”“只能”。它们语义的确定性完全不同。

5.2 坑二：给了代理过大的文件写入权限

Superpowers 最诱人的一点是它可以调用本地脚本，甚至可以自己做文件操作。但这同时也意味着风险。如果你给代理开放的目录是整个家目录，它可能在你不知情的情况下改动无关配置文件。

我现在的做法是权限最小化。在 Codex 配置里只开放项目根目录、临时目录和.superpowers/skills目录。除此之外，像~/.ssh、~/.aws这类敏感目录一律封死。代理如果需要读取环境信息，应该通过明确的安全接口，而不是直接翻文件系统。

这里再补一个非常关键的细节：我从来不在任务指令里写“你随便看下有没有问题就改一下”。“随便”这个词对代理来说太危险了。我所有任务都要求它先给出改动计划和范围，等确认后再动手。这不是为了流程僵化，而是为了在出问题的时候有据可查。

5.3 坑三：Java 项目与技能仓库版本管理脱节

Superpowers 的技能文件是跟着你本地环境走的，默认不在项目仓库里。这就导致了一个问题：项目里换了新同事，他本地没有这些技能，AI 编码的行为表现就完全两样。

我的解决方法是把技能仓库纳入到 dotfiles 管理，并且按项目维度单独抽出项目级技能。项目根目录下放一个superpowers/目录，里面是针对当前项目的技能和工作流，然后把这个目录提交到 git。全局放通用技能，项目里放专项约束，两者叠加使用。

这样做还有一个额外的好处：技能变更可以跟随代码评审走。你在 code review 的时候，如果发现某个 AI 生成的代码风格不符合要求，可以直接在项目技能里加一条规则，下次它就不会再犯。这些规则会跟着仓库走，而不是只存在你个人电脑里。

5.4 我目前的固定操作流程

经过这几个月的折腾，我现在接手一个 Java 项目时，流程已经基本固定下来：

第一步，克隆代码仓库，确认 Java 版本和构建工具。

第二步，在项目根目录执行superpowers init的局部初始化模式，为项目生成一个初始技能目录。

第三步，根据项目实际情况补充三条规则：代码风格约束、构建校验命令、禁止涉及的安全边界（比如密钥、生产数据库配置、支付相关逻辑）。

第四步，启动 Codex CLI，加载全局和项目两个技能源。

第五步，跑一个最小的任务验证链路，比如让代理找一个老接口的单元测试缺失情况。如果它输出的结果符合预期，说明整个链路通了。

日常使用中，我的角色更像一个项目经理：分配任务、验收输出、补充规则。具体的代码搜索、修改实现、单元测试跑批，都交给代理来完成。工作流稳定之后，手里能并行推进的事情明显变多了。

6. 真正花时间的地方：持续维护技能而不是追新

很多人在接触 Superpowers 这类工具之后，会陷入一个误区：到处收集新技能，技能包越装越多，最后反而不知道该怎么用。我自己也经历过这个阶段。后来我砍掉了绝大部分花哨技能，保留了六七个真正与日常工作强相关的能力：代码搜索、Java 重构、Maven 校验、依赖变更分析、接口生成、Bug 排查。

原因很简单：Superpowers 的价值密度来自你对技能库的理解和维护，而不是从仓库里复制粘贴的数量。比如你给它准备了一个“重构技能”，技能文件里写着如果项目里有pmd.xml就要读取它的规则集，并且把编译期要用到的参数都写明白。代理只有真正理解了这些规则，才能在你预期它配合的地方发力。

维护技能的最佳时机，是刚踩完坑之后的那十分钟。趁着你记忆最清楚、问题的上下文还热着，把这次的教训写成一条规则加进技能文件。比如那次我遇到“代理为了修一个方法，把同一个类里三个不相关方法也重构了”，我就在 maven-verify 技能里加了一条：“改动范围不得超过任务说明中指定的类和方法；若确需改动相邻代码，必须先输出说明并等待确认”。从那之后，类似的越界行为基本没有再发生过。

换句话说，Superpowers 给你的不是一句“包治百病”的 AI 咒语，而是一套可以被持续打磨的 AI 协作体系。你今天写下的每一条规则，都会成为接下来每一次编码任务中代理自动遵守的纪律。学会把规则固化下来，比催着模型“聪明一点”要可靠得多。