企业官网建设流程全解析

最近好几个朋友都在问同一个问题：superpowers 到底是个什么东西，怎么装，怎么用？这名字听着中二，但用过的都知道，它确实是给 Codex 这类 AI 编程工具上强度的。简单说，superpowers 是一套开源的提示词技能包，把 AI 编码助手从“能写代码”拔高到“会做事”——懂项目管理、会拆任务、能自我检查，核心就是通过结构化的技能文件，让模型在复杂项目里少犯浑、多干活。

我用 Codex CLI 也有小半年了，最初只是拿它补全函数、写写单测，但一碰到多文件重构、架构调整这种大活，模型就开始“自由发挥”，改坏一个地方就一路崩下去。后来换成 superpowers 这套技能层，最大的变化是它开始有“工作节奏”了：先计划、再动手、自己审、最后总结。如果你也在用 Codex 或其他支持自定义技能文件的 AI 编程工具，且正被“上下文记不住”“改完这头崩那头”折磨，这篇内容应该能帮到你。下面我会从设计和安装讲起，再拆核心技能包，拿 Java 项目的实战过程做个完整演示，最后把踩过的坑挨个列出来。

1. 整体设计思路：为什么要把“提示词”做成“技能包”

1.1 AI 编程工具的短板，恰恰是 superpowers 的切入点

先聊一个核心问题：Codex、Claude Code 这类工具，开箱即用和“真正好用”之间，差着一整层工程化能力。裸的 Codex 像一个能力很强但毫无章法的实习生——你问它什么它能答，但让它独立负责一个模块，它往往会忽略项目既有风格、跳过测试、甚至直接把不相关的代码一起改掉。问题不在模型本身，而是它缺少一套“工作方法”的约束。

superpowers 的思路很直接：把顶级工程师在真实项目里的工作习惯——先梳理需求、拆解任务、分步实施、测试验证、最后提交——固化成结构化的提示词文件。模型在会话启动时读取这些技能定义，就相当于领到了一本“工作手册”。这不是给模型增加知识，而是给模型的“行为模式”装上轨道。

我实际感受下来，这套思路比单纯在系统提示词里写“请仔细思考”要可靠得多。因为“仔细思考”是一句无效指令，而 superpowers 里定义的是具体动作，比如“读取项目结构后再创建实施计划”“每个步骤完成后回到主计划更新进度”——模型在执行时有了明确的检查点，自然不容易跑偏。

1.2 技能包的三大设计特性：组合、递归、自检

superpowers 的文件组织方式，我拆开看过之后觉得挺讲究，它有三个关键设计。

第一是组合性。它不是一个大而全的提示词文件，而是按场景拆成多个技能，比如处理开发任务、代码审查、撰写文档、修复 Bug 各一文件。你可以在一次会话里按需加载一个或多个技能，也可以让一个技能引用另一个技能，有点像函数调用。

第二是递归计划。这是我最喜欢的一点。当任务规模大时，它会自动把主计划拆成子任务，并且允许子任务继续拆分下一层。每个执行单元都足够小，模型在给定步内只处理一件事，上下文负担反而比一次性输出全部方案更轻。

第三是自我检查机制。每个技能在执行过程的结尾，通常都有一段强制性的“回顾”指令，比如检查是否偏离了原始目标、是否有未测试的变更、是否有被忽略的边界条件。这个机制直接对应到代码里，就是必须列出验证清单。有了这层，模型那种“活干完就交差”的毛病被压住了不少。

这里顺带提醒一句：superpowers 的核心其实是提示词工程，不是模型微调。所以它对你的 Codex 底层模型能力仍然有依赖——GPT-4o 级别以上的模型用起来效果才明显，太弱的模型就算给了技能文件，执行起来也容易变形。

2. 环境准备与安装：跟着做一遍就能跑起来

2.1 前置条件：先装好 Codex CLI

superpowers 官方主要面向 Codex CLI 设计，虽然社区里也有适配 Claude Code 或其他终端 AI 工具的分支，但第一次使用，我建议你就老老实实用 Codex CLI 来跑，遇到问题最好排查。

Codex CLI 的安装要求 Node.js 18 以上版本，我自己在 macOS 上用 nvm 管理的 Node 20 LTS，Linux 服务器上也测过，没遇到什么问题。如果你的机器上还没有 Node，先去官网装 LTS 版本。然后执行：

npm install -g @openai/codex

装完确认一下版本：

codex --version

看到版本号输出，说明 CLI 基础环境已经就绪。另外需要注意一点，Codex CLI 首次运行会让你登录 OpenAI 账号并配置 API Key，这一步不要跳过，因为 superpowers 本质上是在 Codex 的会话层注入额外的系统提示，底层还是走 Codex 的模型接口。

2.2 安装 superpowers 技能包：两种方案对比

安装 superpowers 本质上就是把它仓库里的技能文件下载到 Codex 能扫描到的目录。我实测过两种方式。

方式 A：直接克隆到默认技能目录（推荐）

git clone https://github.com/workspin/superpowers.git ~/.codex/skills/superpowers

这个命令把整个项目仓库克隆到~/.codex/skills/superpowers目录。Codex CLI 在启动交互会话时，会自动扫描技能目录下的所有技能文件并加载索引。

克隆完之后，在项目里创建一个.codex目录，并写入项目级配置：

mkdir -p ~/.codex

然后启动 Codex：

codex

在会话中输入：

superpowers

正常情况下，模型会识别到 superpowers 技能包已经激活，并显示当前可用的技能列表。如果没反应，检查一下你克隆的目录结构，确认技能文件是否真的在superpowers/skills/下，而不是被多套了一层目录。

方式 B：以子模块方式集成到项目（适合团队协作）

如果你公司里的项目是多人协同开发，我更推荐把 superpowers 作为 git submodule 加到项目仓库里。这样每个同事 clone 项目时，技能包会跟着一起下来，大家使用的技能版本完全一致，不会出现“我能加载技能你却不能”的尴尬情况。

git submodule add https://github.com/workspin/superpowers.git .codex/skills/superpowers

然后在项目根目录放一个AGENTS.md或者项目说明文件，里面注明“本项目使用 superpowers 技能包，请在 Codex 会话中激活”。这种方式我用了之后感觉团队协作顺畅很多，新同事上手也快。

2.3 验证安装是否成功的三个信号

安装之后，怎么确定自己真的装好了？我总结三个验证信号：

• 在 Codex 交互会话中输入superpowers，模型能正确列出技能清单。
• 询问模型“你当前的工作流程是什么”，它的回答里会出现计划、执行、回顾这类结构化步骤，而不是直接说“我很擅长写代码”。
• 让它执行一个稍微复杂的任务（比如重构某个函数并添加单测），观察它的输出是否包含“首先读取项目结构”这类预动作，而不是上来就直接给代码。

这三个信号全部满足，才算真正激活成功。我见过有人只克隆了仓库但没有启动会话时激活，导致技能不生效，后面排查了半天。

3. 核心技能包解析：它到底提供了哪些“超能力”

3.1 技能包的文件组织与加载机制

克隆下来的 superpowers 仓库，核心内容都在skills目录下。每个技能是一个带编号的子目录，比如001-development-workflow、002-code-review、003-testing、004-documentation等。每个目录里有一个SKILL.md，这是技能的定义文件，里面写明了这个技能的适用场景、使用步骤、输出格式、自检清单。有些技能还会附带几个额外的提示词文件，用于子场景的进一步细分。

加载机制我在使用时是这样理解的：当你在会话中激活 superpowers 后，模型会把技能目录里的文件内容作为上下文的一部分进行理解，并把技能文件中定义的流程作为它的行为准则。一个很直观的表现是，激活了开发工作流技能后，即使你不说“请先做计划”，它也会默认先输出一个实施计划，因为技能文件里面的第一步就是“创建计划”。

这里有个容易忽略的点：技能文件不是越多越好。如果一次会话里同时激活了太多技能，模型的上下文会被大量提示词占满，反而影响实际代码生成的可用窗口。我自己通常一次只激活一个主技能，比如做开发任务就只激活开发工作流，做完开发再激活审查技能做第二轮检查。

3.2 核心技能逐个拆解：工作流、审查、测试、文档

superpowers 提供的技能有十几个，我实际高频使用的就四个，这里逐个拆一下。

development-workflow：开发主流程

这是整个技能包的基石。它规定了模型在接到开发任务时的标准流程：读取项目结构、创建主计划、将主计划拆分为子任务、逐个执行子任务、在每个子任务完成后更新计划、最终回顾验证。我实际用下来的感受是，它最值钱的地方不是“做计划”，而是“每完成一步就更新计划”。这听起来简单，但裸 Codex 经常会跑着跑着忘了初始目标是什么，活干完才发现偏了方向。

这个技能还会在计划开头强制你定义“完成标准”。没有明确完成标准的任务，模型不会动工，而是先反问你需要什么结果。这个特性在需求不清晰的时候特别有用，等于逼你把想法想清楚了再让它写代码。

code-review：代码审查助手

这个技能把模型变成了一个挑刺的同事。它会让模型逐文件检查代码风格、逻辑正确性、边界条件、安全风险、测试覆盖，然后按严重程度输出问题清单。我在重构完一个模块后，会把代码先丢给它审一遍，往往能发现一些自己没注意到的空指针风险或并发写入问题。不过要说句公道话，它的审查结论也有误报，需要人工判断，不能盲信。

testing：测试生成与执行

这个技能专注于测试。它的亮点在于不是无脑生成一堆断言，而是先分析被测代码的分支覆盖情况，再针对未覆盖的分支设计测试用例。在 Java 项目里，它会读取 Maven 或 Gradle 配置来确定测试框架版本，生成的 JUnit 5 测试基本拿来就能跑。不过它生成的测试偶尔会对 Mockito 的 when/thenReturn 用法比较啰嗦，我会在让它生成测试之前把项目现有的测试风格贴给它做参考。

documentation：文档撰写

这个技能负责把代码库改造成文档友好的状态。它可以生成 README、架构说明、模块设计文档，甚至可以按照项目现有文档的格式风格输出，避免文档风格前后不一致。我团队里维护的几个内部项目，现在都委托给这个技能起草第一版文档，我再花十分钟校对补充，效率确实上来了。

3.3 技能组合使用：一次完整任务的执行链路

实际使用时，技能不是孤立运行的。我的一次典型任务链路是这这样：

在 Codex 会话中激活 superpowers，告诉模型“我要给订单模块增加一个导出 Excel 的功能”。模型先加载开发主流程，读取项目结构，然后输出一个主计划，包含“新增导出工具类”“新增 Controller 接口”“编写单元测试”“更新接口文档”四个子任务。执行完子任务后，我让它切换到测试技能，补全边界测试。最后激活代码审查技能，对整个 diff 做一轮检查，发现导出工具类里拼接文件路径的方式在 Windows 环境下有兼容问题，人工修正后收工。

这条链路跑下来，最明显的收益是“每一步动作都有据可依”。模型不再东一榔头西一棒子，而是像被一根线串起来一样，一步接一步。前提是你在每个子任务完成后稍微看一眼结果，确认方向没偏，再让它继续下一步。

4. Java 项目实战：用 superpowers 重构一个订单模块

4.1 实战背景与项目环境

我拿一个真实的订单模块重构来演示。项目是一个基于 Spring Boot 3.2 的微服务，订单模块里有一个OrderService类，里面塞了太多逻辑：价格计算、库存扣减、优惠券校验、通知发送全挤在一个类里，方法超过 300 行，已经有同事开始抱怨没法维护了。

重构目标很明确：把OrderService拆成PricingService、InventoryService、CouponService、NotificationService四个类，保持对外行为不变。

这种重构对 AI 编程工具来说其实是比较有挑战的，因为它涉及多个文件的创建与修改，而且必须保证拆完后原有接口不变、依赖关系清晰、所有现有测试仍然通过。不用 superpowers 的话，Codex 大概率会一次性输出全部代码，看起来很完整，但实际上很容易漏掉某个依赖注入的配置。

4.2 重构实操流程与关键指令

我在 Codex 会话中激活 superpowers 的 development-workflow 技能后，输入的指令是这样的：

请使用 superpowers 工作流重构 OrderService。目标是把价格计算拆分到 PricingService，库存扣减拆分到 InventoryService，优惠券校验拆分到 CouponService，通知发送拆分到 NotificationService。保持对外行为不变，现有测试必须全部通过。

模型先没有直接写代码，而是给出了一个主计划，并列出了需要读取的文件清单：OrderService.java、OrderController.java、application-context配置文件、现有的测试类。随后它逐个子任务推进。

第一个子任务是创建PricingService。它先读取了OrderService里与价格计算相关的代码块，抽取成独立类，并在OrderService里把原逻辑替换为对PricingService的调用。这里我注意到一个细节：它没有盲目复制原始逻辑，而是把计算过程中用到的几个 BigDecimal 舍入模式统一提取为常量，放在新类里。

第二个子任务是处理依赖注入。OrderService原先是一个被@Service标注的类，直接通过字段注入各个依赖，重构后OrderService需要注入新创建的四个服务类。模型在新增类上加了@Service注解，并为OrderService添加了构造器注入。因为它读取了项目的 Spring 配置上下文，知道这个项目使用了构造器注入风格，所以没有用字段注入。这是它读取项目结构后主动适配的结果。

第三个子任务是迁移测试。它把OrderServiceTest中针对价格计算的测试迁移到了新的PricingServiceTest，并补了几个原先缺失的边界测试——比如订单金额为 0 时，价格计算不应该出现负数的折扣结果。这个补测试的动作有些出人意料，但符合它技能文件里“对新类必须有完整测试覆盖”的检查点。

整个重构过程大概花了十来分钟，期间我在两个子任务完成时暂停检查了代码。拆完后的结果比较理想：原OrderService从 300 行降到 90 行，只负责流程编排，新类各司其职。所有测试通过后，我激活了 code-review 技能做了二次检查，它提醒我CouponService里有一个未使用的@Autowired字段，清理掉之后收工。

4.3 Java 项目里的上下文管理技巧

Java 项目有一个特殊性：它比 Python 或 Node 项目有更多的配置文件、依赖声明和样板代码。这对 AI 编程工具很不友好，因为模型很容易被无关的配置信息干扰，浪费上下文窗口。比如你让它改一个业务代码文件，它可能会把pom.xml里的依赖坐标也读进来，而这些信息对当前任务毫无帮助。

我实测了几个提升 Java 项目体验的小技巧：

• 在.codex配置里设置忽略列表，把target、build、node_modules这些生成的目录排除掉，避免模型扫描时浪费 token。
• 对超大项目，先手动把相关模块的目录结构告诉模型，再让它读取重点文件，而不是让它从根目录开始漫游。比如上面那个重构，我直接告诉模型“代码在order-service/src/main/java/com/example/order/下”，它立刻就能定位，不会在无关模块里打转。
• 涉及到 Lombok 的项目，务必在会话里说明“本项目使用 Lombok 的 @Data 注解”。因为模型有时不理解为什么没有 getter/setter 方法，会尝试在类上补全方法，造成代码膨胀。提前声明注解的用法，可以避免这类无效操作。

5. 常见问题与排查技巧：连踩带填的实操记录

5.1 技能文件不生效的排查顺序

我遇到过好几次“明明激活了 superpowers，但模型行为完全没变化”的情况。总结下来，大概率是这几个原因之一。

路径不对是最常见的问题。如果你把仓库克隆到了~/.codex/skills/下，但 Codex 实际扫描的目录是~/.codex/plugins/或者项目内部的.codex/skills/，那一切都白搭。我建议启动 Codex 后，用指令“列出你当前加载的所有技能”来验证，模型能答出具体技能名，说明扫描成功；如果答不出，就检查目录位置。

技能文件目录层级多套了一层。有些版本克隆下来的仓库，技能文件不在skills/根目录下，而是嵌套在了superpowers/skills/的下一层。Codex 扫描时读不到，所以不生效。解决方式是把技能目录文件移动到正确层级，或者修改配置里的路径指向。

模型上下文已经溢出。如果你在同一个会话里聊了很久，上下文窗口塞满了历史对话，模型可能已经“忘”了技能的存在。我的处理方式是用clear指令清空会话，重新激活 superpowers。这虽然粗暴，但在长会话场景下是最快的恢复手段。

5.2 上下文管理问题：会话太长导致技能“失忆”

跟模型协作最大的敌人就是上下文窗口。superpowers 的技能文件本身要占用一定的上下文空间，再加上项目文件内容、对话历史，很容易把上下文挤爆。表现就是，模型开始忽略你明确指定的要求，比如让它用 JUnit 5 它偏给你写 JUnit 4，让它只改 Service 层它改完 Controller 层。

我自己的做法是控制单次会话的任务粒度。一次会话只做一个子任务，比如“创建 PricingService”是一个会话，“迁移测试”是另一个会话。这样可以避免同一次会话里塞入太多上下文。superpowers 的递归计划其实也在帮你做这件事——它推荐的方式就是每个子任务独立执行、独立验证，这不是没有原因的。

另外要养成好习惯：激活 superpowers 后，先把任务背景一句话说清楚，不要用隐晦的指代。模型没有你脑子里对“那个老方法”的记忆，交代清楚上下文，比后面多次纠正要省事得多。

5.3 模型输出质量不稳定的应对思路

有朋友问过我，为什么同样一段指令，有时候模型执行得很好，有时候就拉垮？我观察下来，影响因素主要是模型版本和会话状态。OpenAI 每次更新模型后，对提示词的理解方式会有些微变化，superpowers 的技能文件可能也需要配合升级。遇到这种情况，先去仓库看看有没有更新，git pull拉到最新版本，很可能就能恢复。

如果更新后还是不行，问题可能出在技能文件与其他自定义指令打架了。检查你在系统级或项目级配置的 AGENTS.md 或者其他自定义提示词，看里面是否定义了与 superpowers 冲突的行为。比如模型遵循了“每次修改代码必须立即运行格式化”，而 superpowers 的流程要求“所有任务完成后再统一格式化”，这种冲突会让模型行为变得混乱。解决办法是精简自定义提示词，尽量让 superpowers 独掌流程控制。

5.4 团队协作场景：多语言项目怎么办

有网友问我在多语言项目里怎么用，尤其是代码库中既有 Java 又有前端 TypeScript 的情况。我的经验是：让 superpowers 的技能流程保持统一，但针对语言差异在会话里显式说明。

比如切换处理前端代码时，我会告诉模型“当前处理的文件是 TypeScript，遵循项目的 ESLint 规则”。superpowers 的工作流照样适用，计划、执行、回顾的骨架不变，只是具体执行时的代码风格检查标准由我另行指示。这里不要指望 superpowers 自己“感觉”出当前文件的语言规则，它是靠你给的上下文做判断的。

还有一点，团队内多人同时使用时，建议把技能包固定到某个版本，而不是都指向 main 分支。我吃过亏：同事早上更新了技能包，下午我发现模型行为跟昨天不一样了，排查半天才意识到是技能包的提示词变了。后来我们统一在项目里锁版本，这种情况就消失了。

6. 实操心得与避坑指南：一些写在最后的私货

用 superpowers 大概一个月后，我的工作方式确实被改变了。最明显的一点是，我变得不再畏惧让 AI 去做“大事”。以前让 Codex 改一个跨多文件的功能，总是提心吊胆，怕它改出隐藏 bug。现在我会先打开 superpowers 的工作流，让计划先跑起来，再做分步验收。哪怕最后代码还是要人工微调，但整体流程是可控的。

有几条心得想留给后来者。

第一条：不要跳过计划审查环节。superpowers 生成主计划后，花一分钟看看计划对不对，比自己苦干两小时然后返工要划算得多。如果计划有问题，直接告诉模型修改，不要将错就错往下走。

第二条：阶段性验收要舍得打断。很多人在模型执行子任务时会一直等，直到所有代码输出完才去验证。我建议每个子任务输出后都花几秒钟扫一眼关键逻辑，尤其是涉及数据库操作和外部接口调用的部分。被验证过的代码，最终合入时才有底气。

第三条：善用测试技能作为安全网。我的习惯是任何模块改动结束后，激活 testing 技能生成或补全测试。这不是为了让测试数量好看，而是为了让回归校验自动化。重构类操作如果没有测试兜底，改动再小我心里也不踏实。

第四条：keep 住变化，定时更新技能包。superpowers 的仓库更新还挺活跃的，作者一直在根据社区反馈调整提示词。每隔一两周去拉一次更新，能让技能行为保持在一个比较好的状态。拉完更新后，拿手头一个小任务试跑一遍，确认没有异常再切入正式工作。

最后分享一个扩展思路：superpowers 的技能文件本质上是开放格式，你可以基于它的结构，结合自己团队的业务节奏写自定义技能。比如我团队有一套上线前 checklist，我把步骤写成技能文件放在同一个技能包目录下，Codex 在会话中就能直接调用。这个扩展点，比它自带的那些技能还要值钱——因为这是真正把团队经验沉淀到 AI 工作流里的方式。