企业官网建设流程全解析

1. 项目概述：Codex的超能力从哪来

说实话，我第一次看到"superpowers"这个项目名的时候，心里想的是"又一个中二味十足的开源项目"。但等我真正把它装进Codex CLI里跑了两周之后，我收回这句话。superpowers这个项目给AI编程助手带来的变化，确实配得上"超能力"这三个字。

如果你已经在用OpenAI的Codex CLI做日常开发，大概率会遇到这么几个场景：同样是让它改一个bug，有时候它表现得像十年老架构师，有时候又像刚毕业的实习生，发挥非常不稳定；你让它遵循项目里的代码规范，它嘴上答应，写出来的代码却还是自己那套风格；你想让它执行一套固定的流程，比如先写测试再写实现，它总是做着做着就跳步骤。这些问题不是Codex本身笨，而是你缺少一套系统化引导它的机制。superpowers就是来补这个短板的。

简单来说，superpowers是一个开源框架，专门用来给Codex CLI注入持久化的行为准则、可复用的技能包和快捷命令。它不是要替代Codex，而是站在Codex和你的项目之间，把"怎么跟这个AI助手协作"这件事变成了一套有章法的流程。你可以把它理解为：给一个聪明但散漫的实习生，配上了一套标准作业手册和工具箱。装上之后，你再跟Codex说"帮我修复这个测试失败"，它就知道要先理解失败原因、再写最小修复、最后跑全量验证，而不是瞎蒙一通。

这个项目适合谁？我认为最适合三类人：一是深度使用Codex CLI、觉得效果时好时坏的人；二是团队里想让AI辅助开发的流程标准化的人；三是想研究怎么用AGENTS.md和技能文件体系来驯服AI助手的人。如果你是刚接触Codex的新手，也可以装，但建议先熟悉Codex的基本用法，否则你很难分辨哪些进步是superpowers带来的。

2. 整体设计与核心机制拆解

2.1 三层能力模型

superpowers最核心的设计思路，是把给AI的"指令"分成了三个层级。理解了这个分层，你基本就理解了整个项目的精髓。

最底层是AGENTS.md规则文件，它相当于宪法，定义了AI在你项目里工作的所有基本原则。比如项目的技术栈是什么、代码风格偏好、构建命令有哪些、禁止做什么。这一层是持久的，Codex每次进入项目都会读到。

中间层是技能（Skills），它相当于一套SOP手册集合。每个技能是一个Markdown文件，针对某类任务给出具体的操作步骤和决策依据。比如"如何写单元测试""如何做代码审查""如何排查内存泄漏"。技能不是全部都塞给AI，而是按需加载——你在对话里触发某个关键词，Codex才会去读对应的技能文件。

最上层是命令（Commands），它是预定义好的对话入口，相当于快捷宏。你输入一个斜杠命令，比如 /review，Codex就知道接下来要做一轮完整的代码审查流程，自动调用相关技能和规则。

这个分层设计的高明之处在于，它没有试图一次性把海量信息塞给AI。做过大模型提示工程的人都知道，上下文窗口是有限的，指令越多，AI越容易迷失重点。superpowers的做法是把指令分级缓存、按需加载，让AI在每一刻只关注当前任务需要的知识。这个思路完全可以平移到我们日常写提示词的实践中。

2.2 AGENTS.md规则系统

AGENTS.md这个概念现在已经被很多AI编程工具接受了，它本质上是一个给AI看的项目说明书。superpowers对这套系统的增强在于，它不仅仅让你写规则，还提供了一整套规则模板和加载机制。

在官方推荐的目录结构里，你的项目根目录会有一份根级AGENTS.md，定义了全局规则。如果你在子目录里再放AGENTS.md，Codex进入那个子目录时就会合并加载。这非常像我们在工程里做的配置分层：全局配置做兜底，局部配置做覆盖。

我自己的项目里，根级AGENTS.md会写这些东西：项目语言和框架、包管理器、测试命令、代码风格要点、禁止事项（比如不允许生成没跑过的代码）、依赖引入规范。有个容易忽略的细节是：AGENTS.md里不要写空泛的口号，比如"写出高质量的代码"——AI不会因为这句话而改变行为。你要写的是可验证的、具体的指令，比如"所有新增的函数必须附带Javadoc"，它才能严格执行。

superpowers自带了一套AGENTS.md初始化模板，覆盖了工程配置、代码风格、安全注意事项等项目必备条款。你只要照着模板删改就行，不用从零开始想。

2.3 Skills技能系统

如果说AGENTS.md是"宪法"，那Skills就是"案例库"。每个技能文件都是一份Markdown文档，里面用结构化语言描述了"面对某类任务时，应该怎么做决策、按什么顺序执行、有哪些坑要避开"。

superpowers内置了不少技能，我挑几个印象深刻的：代码审查技能（会给出审查清单和分级标准）、测试驱动开发技能（强制先写失败测试再写实现）、调试技能（教AI用科学方法二分定位问题）、重构技能（小步重构、每步都跑测试）。这些技能的质量相当高，明显是作者从实际工程经验里提炼出来的，不是随便写写的套话。

技能的加载机制很有意思：它在对话里靠关键词触发。举个例子，我在对话里提到"修复这个bug"，Codex会自动匹配到调试技能，然后它就会按照调试技能里的方法执行。如果你不想用技能，也可以关闭这个自动匹配。触发之后，技能内容会作为上下文注入，AI的思考方式会明显向技能文件里描述的方法靠拢。

这个机制解决了一个很实际的问题：你不需要每次都在对话里重复叮嘱AI该怎么做。技能文件写一次，永久生效，而且所有项目都能复用。我现在自己的技能库里大概积累了几十个自定义技能，覆盖代码审查、SQL优化、Docker镜像瘦身、接口文档生成这些高频场景，每次让AI干活之前，它都会自动带上对应的作战手册。

3. 安装与快速上手

3.1 环境要求

安装superpowers之前，你需要先准备好两样东西：一个能正常运行的Codex CLI环境，以及Git。Codex CLI的安装方式我这里不多啰嗦，官方文档里有很详细的说明，核心是安装之后要完成登录认证，确保在终端里执行 codex 能正常对话。

还有一个容易被忽略的准备工作：确认你的Codex版本不要太旧。superpowers的一些功能依赖Codex对AGENTS.md和技能的加载特性，如果你用的是非常老的版本，可能加载机制都不一样。我建议在装superpowers之前先把Codex升级到最新版本，省得后面踩一些莫名其妙的版本坑。

系统方面，macOS和Linux都没问题，Windows用户我建议用WSL2来跑，因为整个工具链在Windows原生终端下的行为偶尔会有细微差异，文件路径、软链接这些都可能出问题。

3.2 安装步骤

安装流程并不复杂，我在一个干净的Ubuntu环境上完整跑过一次，整个过程五分钟以内。大致分三步。

第一步，把项目仓库拉下来。这个项目的GitHub仓库地址我放在后面说明里。你不需要fork，直接clone主仓库就行，反正技能文件自己也会不断增删。

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

第二步，运行安装脚本。脚本会做的事情是：在Codex的配置目录里建立好技能目录、命令目录的软链接或者拷贝，把核心AGENTS.md放置到合适的位置，完成初始化。有些环境下它会问你要不要设置默认的Codex配置文件，我建议你选择是，除非你已经有一套非常个性化的配置了。

./install.sh

第三步，验证安装结果。装完之后进入任何一个你准备用Codex开发的项目目录，打开Codex CLI，在对话里问它一句"你有哪些可以使用的技能？"。如果它能列出一串技能名称，说明加载成功了。我发现一个更直观的验证方式：直接在对话里触发一个技能关键词，比如"review this code"，看它的输出是不是明显带上了一种结构化的审查逻辑。如果是，说明技能真的被触发了。

3.3 初始化与验证

到这里其实还没完。superpowers装了只是第一步，关键是每进入一个新的项目目录，Codex需要知道这个项目的AGENTS.md在哪里。所以你在每个项目里，要么在项目根目录放一份AGENTS.md，要么让Codex能往上找到全局规则。

实操中，我更推荐的做法是：项目根目录放一个精简版的AGENTS.md，专注写项目特定的技术栈和命令；全局的、跟技能相关的规则交给superpowers管理。这样层级清晰，各管各的。

验证阶段的几个常见检查点我也列一下：

• 检查技能目录里是否有内容，确认软链接生效。
• 检查Codex对话里是否能列出技能清单。
• 跑一次简单的任务（比如"请对这个项目做结构分析"），看它的行为风格是否和装之前有明显不同。

我自己刚开始安装的时候，犯过一个低级错误：clone下来之后忘了运行安装脚本，直接就在项目里开Codex，然后用了一会儿觉得"这不是跟之前一样吗"。后来才反应过来，规则文件都没有落盘，等于白装。所以安装完之后一定先验证，别急着干活。

4. 核心功能实操与实战配置

4.1 开发模式：让AI深度参与日常开发

superpowers有一个让我觉得真正提升了开发体验的功能，是它把AI的使用方式分成了几种"开发模式"。

在普通问答模式里，你问一句它答一句，适合查API、问概念。但在开发模式里，它会表现得像一个搭档：你告诉它当前项目的状态、需要实现的目标，它自己会拆解任务、读相关文件、按技能执行、给出可提交的改动，并在最后用测试验证自己写的代码。

我实际用下来的感觉是，切到开发模式之后，Codex的主动性明显增强。它会自己去看项目结构，而不是等你喂代码片段；写完代码会主动跑测试；遇到不确定的地方会停下来问你，而不是闷头瞎写。这套行为逻辑不是神奇的魔法，就是靠AGENTS.md里的规则一句一句约束出来的。

启动开发模式的方式有两种，一种是进入Codex之后用斜杠命令切换，另一种是在项目AGENTS.md里默认设置。如果你主要是想拿Codex当结对编程伙伴用，我建议直接在项目里默认开启开发模式，省得每次手动切。

在Java项目里用这个模式特别爽。我维护的一个Spring Boot老项目，模块多、依赖关系乱，之前让Codex改代码时常踩到别的模块，一跑测试就炸。开了开发模式、配好技能之后，它干活前会先花时间摸清模块依赖图，改动前还会检查影响范围。当然这不是绝对可靠，但出错率确实降低了一大截。

4.2 自定义技能实战：为Java项目定制专属作战手册

很多人的使用误区是：装上superpowers之后，觉得自带技能够用就行。但真正让这个工具产生质变的，是你会写自己的技能文件。我拿一个Java项目的实际例子来说说怎么定制。

比如我经常处理"升级依赖版本"这种活。以前让Codex升级某个Maven依赖，它总能升级成功，但经常忽略兼容性问题，比如某个API在新版本里废弃了，或者某个传递依赖跟现有的库冲突。这些坑每次都要我事后提醒。

后来我写了一个"升级Java依赖"的技能，内容大致包括：

• 先读取pom.xml，确认当前版本和目标版本。
• 检查目标版本的Release Notes里是否有breaking changes。
• 升级后执行mvn test compile，找出编译错误。
• 逐个解决编译错误，优先使用官方迁移指南里的方案。
• 跑全量测试，重点关注改动涉及模块的上下游模块。
• 最后生成一份变更说明，列出升级影响。

写技能文件的时候有个核心技巧：描述步骤时要具体，但不要过度约束。你不需要告诉AI"第2行代码怎么改"，你只需要告诉它"采用什么策略、避开什么坑、验证什么指标"，让它在执行细节上有发挥空间，在方向和准则上没有自由度。

写完技能文件之后，把它放进技能目录，然后在对话里触发它对应的关键词。比如我把上面这个技能的关键词设为"upgrade-dependency"。之后只要在对话里提到"升级依赖"，Codex就会自动加载这套流程。实测下来，升级依赖这件事的返工率低了很多，我不用再跟在后面检查它漏没漏跑测试了。

4.3 命令系统：把复杂流程变成一句话

命令系统是superpowers的另一个效率利器。你可以把一串操作打包成一个斜杠命令。

以我自己为例，我最常用的是 /tdd 命令，流程是：读取需求描述、按照测试驱动开发的节奏（先写失败测试、实现最小代码、跑测试变绿、重构）执行任务，每完成一个节点都要做一次状态汇报。以前我需要在对话里打一大段话让Codex按TDD来写，现在只需要敲一个斜杠命令。

另一个高频使用的是 /review 命令，它会执行一轮代码审查：先列出变动的文件清单，然后逐个文件分析，按"正确性、性能、安全、可读性、测试覆盖"五个维度输出问题列表，最后给出修改建议和优先级排序。这个命令的输出质量非常高，我已经把它固化到了团队的日常开发流程里。

自定义命令也不复杂。原理很简单：命令本质上就是一串预设好的提示词，当你敲下斜杠命令时，系统会把后面的内容拼接成一个完整的请求，连同相关技能一起喂给Codex。你只需要按照模板写好命令定义文件即可。

命令和技能配合起来，效果是叠加的。命令负责发起流程，技能负责流程中每个环节的执行细节。这个设计有点像把朴实的"宏"和"函数库"绑到一起用。

4.4 AGENTS.md里的Java环境配置模板

针对Java项目，我分享一个我已经跑顺的AGENTS.md片段，你可以直接参考着改。

# Java 项目规则 ## 环境信息 - 语言版本: Java 17 - 构建工具: Maven 3.9+ - 测试框架: JUnit 5, Mockito - 项目管理: 多模块Maven项目，根目录包含父pom.xml ## 工作流程 - 每次修改代码前，先明确依赖模块，避免破坏模块边界 - 所有变更必须先通过 mvn test 后再提交 - 遇到测试失败时，先阅读失败日志定位根因，禁止盲目修复 ## 代码风格 - 遵循项目已有的Checkstyle配置 - 新增公共API必须附带Javadoc说明 - 禁止引入未在pom.xml中声明的依赖

这个模板的作用是给Codex划定一个清晰的"工作边界"。写规则的时候注意顶部的"环境信息"很重要，因为Codex在不知道技术栈的情况下常常会做出错误的默认假设。比如你没告诉它这是个Maven多模块项目，它可能会只编译当前模块的代码，然后自信地说测试全通过了，实际上别的模块早就被你改坏了。

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

5.1 安装阶段的问题

我见过最多的安装问题，是技能目录没有正确地链接到Codex的配置目录。表现是：安装完superpowers后进入Codex，输入命令想看技能列表，结果一片空白，一个技能都列不出来。

这个问题的根源，多数情况下是安装脚本执行时，Codex的配置目录还不存在。Codex CLI通常是在你第一次运行它的时候才创建配置目录的，如果你先装了superpowers再运行Codex，脚本可能找不到目标目录，技能链接自然就不存在了。

解决办法也很简单：先手动运行一次 codex 命令，让它完成初始化创建目录，然后再重新执行superpowers的安装脚本。我遇到这类问题第一反应永远是"重跑一下安装脚本"，十次有八次能解决。

还有一个环境坑：个别Linux发行版的软链接行为不一样，导致技能文件是"拷贝"而不是"链接"过去的。这时候你后续更新superpowers仓库里的技能文件，本地的副本不会跟着变。建议装完之后查一下本地技能目录里的文件是不是软链接——如果显示的是普通文件，确认一下安装脚本当时是不是用了复制模式。为了保持可更新性，我宁愿删掉重链，也不想用拷贝的版本。

5.2 配置阶段的问题

配置阶段最大的坑，是AGENTS.md写得太长太杂。我一开始恨不得把所有规范都塞进去，结果Codex的行为变得笨拙且犹豫——它每写一行代码都要想想自己的行为是不是违反了哪条规则，创造力反而被束缚了。

后来我学到一个原则：AGENTS.md里只放"不可违背的硬约束"，比如技术栈、构建命令、禁止项；把"如何做一件具体的事"的方法论都放到技能文件里。这样规则文件短小精悍，AI注意力不分散，技能文件又能保证在需要的时候才加载。

还有一个小细节容易被忽视：AGENTS.md换行和特殊字符。Codex解析Markdown的时候，有时候会把某些特殊符号当作格式符号处理，导致规则没有按预期生效。我碰到过一次，AGENTS.md里的某个代码块因为反引号嵌套错误，让Codex整个理解错乱了。排查的方法是在Codex对话里直接问它"当前项目的AGENTS.md里写了哪些关于测试的要求"，如果它答不出来或者答错了，基本可以断定是文件格式有问题。

5.3 使用阶段的问题

使用阶段我遇到最多的问题是"技能没有被触发"。你明明在对话里提到了关键词，但AI好像完全没看到技能文件。

排查思路其实很标准。第一步，确认技能文件确实放在了正确目录，并且文件名格式没问题。第二步，确认关键词在技能文件的元信息里声明过。第三步，在对话里直接问AI"你现在正在使用哪些技能"，看它能不能正确列举——能列举但没执行，说明是理解层面偏差；不能列举，说明是加载机制出了问题。

我自己遇到过一次很隐蔽的问题：我在两个技能文件里设置了同一个关键词，后来发现Codex每次只加载其中一个，而且不一定是我想用的那个。从那以后我给自己定了个规矩：每个关键词全局唯一，技能职责边界清晰，宁可多写几个技能文件，也不要一个技能文件里塞一堆杂活。

最后再分享一个使用心得：superpowers不是"装了就不用管"的工具，它需要随着项目的演进持续维护。技能文件要不断新增、修正、删减，AGENTS.md要根据项目实际情况调整。我每周都会花一点时间翻看一下这周让AI干活时有哪些地方不顺，把经验沉淀成新的技能规则。用久了你会发现，这才是superpowers真正的超能力——它逼着你把自己对工程的理解，逐步固化成一个AI搭档能读懂、能执行的体系。这套积累，比任何单个技能文件都有价值。