企业官网建设流程全解析

在风头正热的时候，网上到处都在聊“superpowers”，但说实话，真正把它讲清楚的中文资料没几篇。我去年底第一次接触这个项目的时候也懵了，看名字以为是个花里胡哨的“超能力插件”，装上以后才发现它干的其实是另一件事：把AI编程助手从“你问一句它答一句”的状态，变成“你给它一个目标它按规范干完”的状态。这篇文章我就以自己在真实项目里的使用经验为主线，把superpowers是什么、怎么装、怎么在Java项目里用、踩过哪些坑，一次性说清楚。不管你是刚听说这个名字、装到一半卡住，还是已经装好但不知道怎么用它干活，这篇都适合你。

1. 它不是一个超能力插件，而是一套“AI工作流说明书”

1.1 先弄清楚Codex CLI的痛点在哪里

superpowers是围绕Codex CLI工作的一组技能包，所以先得说Codex CLI本身。Codex CLI是OpenAI出的一个跑在终端里的AI编程助手，能读你的代码库、执行命令、改文件、跑测试，非常接近一个“住在终端里的结对程序员”。我刚开始用的时候很兴奋，但用了一周就发现了几个越来越难受的问题。

第一个问题是每次会话都像失忆。你今天让它用TDD方式写一个模块，它写得规规矩矩；明天新开一个会话让它写另一个模块，它可能一上来就先把实现代码写了，根本没想着先写测试。不是它变笨了，而是你每次教它的“工作方式”没有沉淀下来。第二个问题是上下文一长就跑偏。一个任务聊到二三十轮之后，它经常忘了最开始定下的约束，比如“不要改公共接口”、“不要引入新依赖”，它照样干。第三个问题是缺少标准动作。有经验的开发者拿到需求会先拆解、再写测试、再小步实现，但Codex默认没有这套肌肉记忆，你说“帮我实现这个功能”，它就真的直奔实现去了。

这些问题不是Codex本身能力不够，而是缺少一层“工作流层”。superpowers就是来解决这个的。

1.2 superpowers的本质：用Markdown技能包把工作流固化下来

superpowers的作者是Jesse Vincent（网名obra），他做过不少知名开源项目，做superpowers的原因也很朴素：他在用Codex的时候发现，与其每次在提示词里反复教AI“你该按什么流程走”，不如把这些流程写成一套可复用的“技能包”，让Codex在需要的时候自动加载。

这套机制简单说就是：每个技能就是一个Markdown文件，文件头部有一段YAML格式的元信息，包含了技能的名字、描述、适用场景；正文部分就是给Codex的详细指令，告诉它拿到什么任务后按什么步骤做、每一步有哪些注意点。

比如TDD技能，正文里会写着类似这样的话：“当用户要求你实现一个新功能时，先写一个会失败的测试，运行它确认失败，再写最小实现让测试通过，最后做重构。”这个流程对老程序员来说不稀奇，但问题是Codex默认不会自动这么做，而技能包会把这段“肌肉记忆”直接塞进它的工作上下文里。

所以我说它是一套“AI工作流说明书”，一点不夸张。它没有改变Codex的底层能力，改变的是Codex拿到任务后的执行方式。你可以理解成：Codex本身是一个什么都会一点的新人程序员，superpowers是给他配的SOP手册，告诉他遇到什么情况该按什么流程来。

1.3 为什么说它把“被动问答”变成了“主动执行”

我用的时间越久越觉得，这个区分特别关键。默认状态下，你在Codex里说“帮我看看这段代码”，它是被动的，你说什么它做什么。但当你装了superpowers，并且在对话里说了一句“use the review skill”之后，Codex会做的就不再是“看一眼然后点评几句”了，而是会主动去调用git diff、逐个文件检查变更、按代码审查清单逐项过，最后给你一份结构化的审查报告。

这背后的原理不玄乎：技能包把“做什么、按什么顺序做、做到什么程度”都写清楚了，模型把这些指令当成了任务约束来执行。所以superpowers的实际效果，是把你的工程经验、团队规范、个人偏好，翻译成了AI能稳定遵守的指令。这也是它和普通提示词最大的区别——普通提示词是一次性的，技能包是可积累、可复用的。

2. 安装superpowers：环境要求与三步初始化

2.1 前置环境：Node.js版本、Codex CLI版本一个都不能错

聊安装之前，先把环境说清楚。superpowers本身是用npm发布的包，所以Node.js是必须的。我个人建议Node.js版本至少18，20以上更好，因为技能包的安装脚本用到了不少较新的Node特性，版本太老容易在安装阶段报错。检查命令是node -v和npm -v，不到位的先去把Node环境补上。

然后就是Codex CLI，它是superpowers的运行底座，基本上可以理解成“没有Codex就没有superpowers”。安装Codex CLI很简单，官方推荐npm install -g @openai/codex，装完以后跑一下codex --version确认版本号能正常打印出来。这里我多说一句：Codex CLI本身就要求你有一个可用的OpenAI账号并完成登录授权，如果codex本身还不能正常对话，那superpowers装得再漂亮也没用。所以我的建议是，先花十分钟把Codex CLI从安装到首次对话完整跑通，再碰superpowers，不然出了问题根本分不清是哪层的毛病。

如果你已经能正常使用Codex CLI，那环境这块就只剩一件事：确认有权限在全局目录安装npm包。很多人在这一步踩坑，比如在Linux或macOS上直接npm install -g报EACCES权限错误。我的做法是优先用nvm管理Node版本，这样全局安装目录就在用户目录下，不需要sudo。用sudo装全局npm包短期能解决，但后续很容易出现目录权限混乱的问题，不建议。

2.2 安装与初始化命令详解

环境就绪之后，安装superpowers就两步。

第一步是安装superpowers本体：

npm install -g @obra/superpowers

装上以后，终端里就有了superpowers这个命令。先别急着用，第二步是初始化技能库，让它把默认技能包安装到Codex CLI的配置目录里。不同时期项目推荐的具体命令略有变化，你以仓库README为准，大致是这样：

superpowers install

这个命令会把所有内置技能写进~/.codex/skills目录（macOS和Linux是这个路径，Windows下会在用户目录的对应位置）。执行完之后你可以看一眼这个目录，里面应该会出现一堆以技能名命名的文件夹，比如tdd、explain-code、review这些，每个文件夹里都放着一个Markdown指南文件。看到这些文件，说明技能库已经就位了。

接下来有个容易忽略的点：Codex CLI需要知道技能目录在哪里。有些版本的Codex会自动扫描~/.codex/skills，有些版本则需要在Codex的配置文件里指定。我的建议是装完superpowers之后，直接打开~/.codex/config.toml看看，确认里面有类似skills = ["~/.codex/skills"]这样的配置。如果没有，手动补上这一行再重启Codex，保守但有效。

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

装完以后怎么确认不是“假装装好了”？我一般看两个信号。

第一个信号是文件层面：ls ~/.codex/skills能看到技能文件夹，说明superpowers install这一步成功。第二个信号是行为层面：在Codex CLI里新建一个会话，输入一句“use the explain-code skill”，如果它回应的方式明显是“先拆解代码结构、再逐行解释、最后给总结”，而不是泛泛地跟你说“这段代码意思是……”，那就说明技能已经被加载并且生效了。

这里有个很容易安心的判断方法：没加载技能时，Codex的回答风格和平时闲聊区别不大；加载技能后，你会明显感觉它做事“有章法”了，会主动分步骤、列观察项、按清单走。这个体感差异，比看什么日志都来得直观。

如果你在验证时发现它完全没有技能加载的样子，别急着怀疑人生，大概率是配置路径没对上或者版本有差异。这类问题的完整排查思路我放在第5章专门讲，这里你可以先回到~/.codex/config.toml检查配置项是否存在。

3. 上手实操：技能触发逻辑与高频技能拆解

3.1 技能怎么被触发：自然语言触发词的设计逻辑

安装只是开始，真正用起来的第一步是理解触发逻辑。superpowers的技能不是像插件那样“装了就自动常驻”，而是按需加载。它的工作方式是：你在对话里明确提到某个技能，Codex会去技能库里找到对应的Markdown文件，把里面的内容当作工作约束来执行。

最稳妥的触发格式是英文：use the <技能名> skill。比如use the tdd skill、use the review skill。这个格式我建议你形成肌肉记忆，因为它最不容易产生歧义。我也试过纯中文触发，比如“用TDD技能来写”，在多数情况下也能被正确识别，但如果Codex版本较老或者技能描述里的关键信息是英文，中文触发的识别率会下降。

你可能会问，为什么superpowers不把所有技能全部塞给Codex，让它自己判断什么时候用哪个？答案很现实：技能全部常驻会占用大量上下文窗口，反而降低回答质量。而且很多技能之间有隐含的先后关系，比如“先解释再审查”和“先审查再解释”结果完全不同。所以按需加载这个设计看似麻烦，实际是取舍之后的最优解。

3.2 高频技能逐个拆解

我在真实项目里用得最多的是这几个，逐个说下它们各自解决什么问题。

• explain-code（代码解释）：让Codex不是泛泛地讲代码“做了什么”，而是按“整体结构→关键函数→边界条件→潜在问题”的结构做一次完整讲解。适合接手不熟悉的项目，或者做技术评审前快速过代码。
• tdd（测试驱动开发）：这是我觉得superpowers里最值钱的技能。它强制Codex先写失败的测试，再实现，再重构。它会把“先红灯、再绿灯、再重构”这个节奏拆成多个小步骤，每一步都停下来等你确认。对于追求可维护性的团队，这个技能可以说是直接给AI装上了开发规范。
• review（代码审查）：让Codex基于当前分支的改动做审查，它会主动跑git diff，检查变更文件，按正确性、可读性、安全性、性能等维度给出意见。注意它和你在聊天框里说“帮我看看这段代码”有本质区别——它会先明确“审查范围”是哪些改动，再逐条过。
• git-work（Git工作流）：规范化Git操作流程，包括生成符合规范的提交信息、检查分支状态、处理合并冲突前的准备工作。我通常在一个任务开始时先让Codex用这个技能确认当前分支干净，避免中途提交把无关文件混进去。

这几个技能覆盖了我日常开发流量的八成。剩下的比如brainstorming（需求拆解）、debugging（问题定位），我用的频率低一些，但同样值得你打开技能文件看一眼它们的触发条件和适用场景。

3.3 一次完整的TDD技能实战演示

光看解释不如来一次实际操作。我在一个Java项目里曾经让Codex用TDD技能实现一个简单的订单金额计算器，需求是“计算含税金额，税率10%，低于100元的订单免运费”。

我在Codex会话里输入的是：

use the tdd skill 实现一个OrderCalculator，方法 calculateTotal(amount) 返回含税金额；金额低于100元时额外返回免运费标记。

有意思的事情发生了。它没有直接甩给我一个类文件，而是先问我：“这个需求有没有边界情况需要确认？比如金额正好等于100元时，要不要收运费？税率是固定10%还是可配置？”这一步就是技能包里的“需求澄清”步骤在起作用。我补充说“等于100元也免运费，税率先固定”。

然后它就按TDD流程来了：先在src/test/java下写了OrderCalculatorTest，写了一个会失败的测试；运行测试，确认红灯；再新建OrderCalculator.java，用最简实现让测试通过；最后跑一遍全量测试，做了一次小的重构把重复计算抽成方法。整个过程它都会停下来告诉我下一步是什么、为什么要这么做。

这个体验和我平时用裸Codex完全不同。裸Codex大概率会一次性写完实现类，然后“好意”地问你要不要补个测试。而TDD技能是反过来的：测试先行，每一步都有明确节奏。这就是技能包的价值。

4. Java项目里的使用心得：从代码审查到测试生成

4.1 Java场景下最该先启用的三个技能

如果你和我一样主要写Java，那superpowers里最值得你先用起来的是这三个组合：review、tdd和explain-code。

先说为什么是这三个组合。Java项目普遍比脚本语言项目更讲究结构和规范，类职责、接口边界、异常处理这些事，默认状态的Codex不会主动去管。开了review技能之后，你每次提交前让它过一遍变更，它给出的审查意见会更贴近“有经验的Java同事在看你的代码”这种感觉，比如会提醒你“这里应该用Optional而不是返回null”、“这个异常不应该吞掉”、“流式处理可以简化这段循环”。

tdd技能在Java里尤其好用，因为Java生态的测试框架成熟，JUnit 5配AssertJ已经成了标准配置。技能让Codex自动生成测试类时，它会按Maven/Gradle的标准目录结构来放测试代码，不会把测试塞到main代码里。我第一回看到它自动建src/test/java目录的时候还挺感慨，这就是技能包内置的工程意识。

explain-code技能则适合你刚接手一个老模块时使用。我有个维护了三年的支付模块，接手时完全没有文档，我就是让Codex用这个技能把核心链路逐行过了一遍，半小时后就对整个模块的时序和风险点心里有数了。

4.2 处理Java特有问题：Lombok、泛型、依赖版本

但Java场景不是没有坑。我用了几个月下来，有几个和Java特性相关的细节想单独提醒你。

第一个是Lombok。review技能经常会对Lombok生成的代码表示困惑，因为它看的是源码文件上的@Data注解，看不到生成后的getter/setter。有几次它甚至建议我“手动补全getter和setter”，我直接拒绝了，然后在技能描述里加了一句“项目中使用了Lombok，生成的方法不需要手动实现”，后续审查意见就正常多了。所以我的经验是：Java项目用superpowers，越早把项目上下文告诉它，它后续的产出越不容易跑偏。

第二个是泛型和类型擦除。explain-code在解释复杂的泛型嵌套时，偶尔会陷入“看起来说了很多、实际没说到点子上”的境地。我的处理办法是让它“解释的时候给出具体类型示例”，而不是停留在泛型符号层面。比如解释List<? extends T>时，我会让它用List<? extends Number>举两个实际例子来说明限制。

第三个是依赖版本。Codex生成的代码有时候会引入它“记忆里”的依赖版本，而这个版本可能和你项目里的其他依赖冲突。我后来在自定义技能里明确加了一条：“生成代码时不要自动添加新依赖；如果需要新依赖，先列出建议的artifactId和groupId，等确认后再修改pom.xml。”这个约束帮我省了很多处理依赖冲突的时间。

4.3 用自定义指令补足Java团队规范

说到自定义技能，这里展开讲一讲。superpowers最被低估的能力，不是它自带的那些技能，而是你能自己写技能。

在~/.codex/skills下新建一个文件夹，比如叫java-project-rules，在里面创建一个Markdown文件，文件头写上技能的元信息，正文就是你希望Codex遵守的规则。我自己就写了一个，核心内容大概是这样：

--- name: java-project-rules description: Use when working on Java backend projects in this repository --- - 所有新类必须放在 src/main/java 下对应的包结构中 - 所有测试必须放在 src/test/java 下，测试方法使用 JUnit 5 注解 - 禁止在代码中直接 catch Exception 后不做任何处理 - 新依赖必须经确认后才可加入 pom.xml - 代码中不允许出现 System.out.println，日志请使用 SLF4J

写完之后，在会话里说一句use the java-project-rules skill，Codex就会把这套规则加载进上下文。之后你再让它写代码，它会默认遵守这些团队规范。对我来说，这才是superpowers的真正用法——它不是给你一套固定的超能力，而是给了你一套定义超能力的语法。

有时候我会觉得，这个东西的本质是“把团队里隐性的开发约定，显性化成AI能读的文档”。以前带新人，要把这些规矩口头说一遍；现在直接写成技能文件，新人和AI都在同一条起跑线上。

5. 我踩过的坑与完整排查思路

5.1 技能不生效：先查Codex配置再查技能文件

最常见的问题就是：明明说了use the review skill，但Codex根本没进入审查状态，回答得像普通聊天。遇到这种问题，我建议你按下面的顺序排查，不要乱试。

第一步看~/.codex/config.toml里有没有配置技能目录。这是最容易被忽视的。技能装好了不代表Codex知道去读它，配置项缺失的话，它安安静静地“假装没看见”也不是没可能。确认配置里存在技能路径后，重启Codex会话再试一次。

第二步看~/.codex/skills目录下的文件结构。每个技能文件夹里，指南文件必须在正确的位置。如果文件缺失或者文件名不对，同样会导致技能加载失败。可以对比一下技能文件夹里的结构和项目仓库的示例是否一致。

第三步看措辞。use the review skill这个格式之所以我推荐，是因为它包含两个关键信息：触发动词use、目标技能名review。如果你只说了“帮我看看这个改动”，Codex可能没有足够信号把review技能调起来。这时候换个说法，明确提技能名，然后再试一次。

这一步一步走下来，绝大多数“技能不生效”的问题都能定位到上面三个环节之一。

5.2 版本不兼容导致的行为异常

第二个坑和版本有关。superpowers迭代很快，Codex CLI的更新频率也不低，两边版本差距大了之后，会出现一些“说不上哪里坏，但就是不对劲”的异常。

我自己遇到过一次，升级Codex CLI之后，原来能用的TDD技能突然不触发TDD流程了，它的回答变得像普通代码生成。当时我第一反应是技能文件损坏，检查半天发现文件好好的。后来排查到这一步：我本地的superpowers包版本还是几个月前的，而Codex已经升了两三个大版本，两者之间有些技能调用方式已经变了。

解决办法不复杂：重新安装最新版superpowers包，重新执行初始化命令，把技能文件刷新一遍。我后来养成了一个习惯，每隔几周看一眼superpowers和codex是否发布了新版本，升级时两边一起动，别只升一边。用npm outdated -g可以一次看到全局包的更新情况，比较省事。

5.3 “更新后行为变了”的应对方法

和5.2紧密相关的是另一种情况：你没有主动动任何东西，但某一天突然发现同一个技能的行为变了。这通常不是你的配置出了问题，而是技能包的内容被上游更新了。

技能本质上是Markdown指令文本，上游项目完全可以调整正文里的步骤顺序和措辞，这些改动不需要你重新安装也会被拉取。我遇到过的一次变化是review技能增加了“安全漏洞检查”环节，之后每次审查都会多出一节专门讲安全问题，范围比之前广了。

如果你对特定项目的产出要求很严格，不想让技能行为悄悄变化，我的建议是：在确认技能稳定后，把当前版本记录在项目README里，或者干脆复制一份技能文件到项目目录并改为引用本地版本。前一种做法适合大多数场景，后一种更“锁死”。我自己是两种结合：快速项目用默认技能，长期维护的核心项目用本地锁定版本。

5.4 兜底方案：不用技能关键词也能调用技能

最后说一个兜底技巧。万一你无论如何都触发不了某个技能，还有一个土办法：直接把技能文件的内容告诉Codex。你不需要会说use the xx skill，你只需要打开技能文件，把正文里的指令原样复制粘贴到对话里。

这不是绕路，而是有用意的。当你粘贴完整技能内容时，Codex同样会把那套步骤当作约束来执行，效果和正常触发几乎一样。我用这个方法扛过好几次版本不稳定的时期，也用来排查过“到底是技能没加载，还是技能本身写得不好”的问题。如果你复制了完整的技能内容之后，Codex的表现依然不理想，那问题就不在加载机制上，而在技能本身的指令质量上。

这个方法还有一个变体：把自己的工作流写成一段150字以内的简短指令，不建技能文件，直接贴在对话里。对临时性的任务，这个轻量方式比建一个完整的技能文件更快。

6. 关于“worbuddy怎么用superpowers”这类问题的统一回答

6.1 worbuddy这类平台上的superpowers是什么

这半年来我看到不少朋友在worbuddy之类的内容聚合或导航平台上搜“superpowers怎么用”，然后越搜越糊涂。这里我想统一说清楚：你在大多数内容平台上看到的superpowers，指的基本上还是同一个开源项目，也就是围绕Codex CLI的那套技能包。它不是一个独立软件，更没有所谓的“worbuddy专用版”。那些平台只是内容的搬运工，把GitHub上的项目说明和社区教程做了二次整理。

所以如果你是在某个博客站或导航站看到“superpowers使用指南”，内容大概率是换了个说法介绍同一件事。判断方法很简单：看文章里提到的安装命令是不是npm install -g @obra/superpowers，如果是，那就是同一个东西。

6.2 图形界面工具调用superpowers的基本链路

也有人问，我不想在终端里操作，有没有图形界面能直接用superpowers？答案是：最终链路还是绕不开Codex CLI，但你可以换一个操作入口。比如在支持Codex的编辑器集成环境里打开终端，在集成面板里启动一个Codex会话，然后在会话里使用技能。本质上你做的事情和前面讲的没有区别：启动Codex会话→输入use the xx skill→开始干活。

我理解大家想要“图形化”的真实需求，大多是希望减少在终端和编辑器之间切换的割裂感。这个可以通过把Codex会话窗口固定在编辑器侧边栏来解决。我在VS Code里就是拉了一个终端面板，专门跑Codex，写代码在主编辑区，看Codex输出在侧边，体感上已经非常接近“IDE内置AI助手”了。

6.3 在博客教程平台上检索superpowers资料的技巧

最后分享几个检索技巧。第一，搜索时带上codex前缀，搜“codex superpowers”比只搜“superpowers”精准得多，因为后者会混进来一大堆和“超能力”有关的无关内容。第二，搜“superpowers安装”或“superpowers使用教程”时，优先看发布时间，超过半年的教程要留意命令是否过时。第三，看到任何教程，先看它有没有给出可以验证的步骤，比如“检查~/.codex/skills目录是否出现技能文件夹”——一个可被验证的步骤比十句“很强大、很好用”都值钱。

按这个方式去检索和筛选，你基本能在十分钟内判断一篇教程对你的版本有没有参考价值，不至于跟着过时命令白折腾半天。

我个人用了superpowers大半年，最大的体会是：它真正的价值不在于让AI变得更“聪明”，而在于让AI变得“守规矩”。每次打开Codex之前，我会想清楚这次任务该用哪个技能、希望它按什么步骤执行，而不是像以前那样含糊地丢一句话。这个习惯一旦养成了，产出的质量提升是肉眼可见的。最后再分享一个小技巧：如果你在某个项目里反复让Codex做同一套流程，把它写成一个自定义技能文件放进~/.codex/skills，你会发现——整理指令的过程，其实也是在帮你自己理清楚日常工作里哪些步骤是真正必要的。