企业官网建设流程全解析

Codex 出来之后，很多团队把 AI 编程助手接到了日常开发流里，但我身边几乎每个人都经历过同一个困惑：模型确实能写代码，可写出来的东西不稳定，有时候像资深工程师，有时候又像刚毕业的实习生。问题通常不在模型本身，而在你给它设定的“工作方式”。最近我在大量项目里反复实验了一套叫Superpowers的增强方案，它本质上不是模型，也不是新的 IDE，而是一套围绕 Codex CLI 的“技能包”体系，能让 AI 按你定义好的规范、流程和权限来干活。这篇文章我会从安装、配置、核心机制讲到 Java 项目里的真实落地案例，把适合团队参考的细节尽量写透。

1. Superpowers 到底是什么，为什么现在火起来

1.1 它解决的是 Codex 用户普遍痛点

先说痛点。Codex CLI 是 OpenAI 推出的命令行编程代理，它的工作方式是：你在终端里给它一个自然语言任务，它自动读代码、改文件、跑命令，甚至帮你提交 commit。这套东西对个人开发者来说已经很爽了，但放到真实工程里会遇到几个很现实的问题。

第一个问题是“上下文一次性”。每次会话开始，Codex 对项目是一无所知的。虽然 CLI 会自动扫描一些配置文件和项目结构，但它不会天然知道你团队的代码风格、提交规范、目录约定、禁止改哪些文件。这就导致同一个任务，今天干得很漂亮，明天换一种问法，它就可能把不该动的文件动了。

第二个问题是“任务过程不透明”。Codex 默认的交互是边想边做，它可能在某个文件里改了十几处，你很难追查它每一步的判断依据。你只能在最后 review diff，出了问题要么回滚，要么在后续对话里反复纠正。时间一长，团队会感觉这不是在“用 AI 编程”，而是“给 AI 擦屁股”。

Superpowers 的思路很直接：与其让 Codex 每次从空白的上下文里“自由发挥”，不如主动给它的工作环境里塞入一整套可复用的技能说明。这些说明不是空泛的 prompt，而是把“如何做代码审查”“如何写单元测试”“如何做 Java 项目依赖升级”这些高频任务，写成结构化的操作手册。Codex 启动后会先读到这套手册，再根据任务类型调用对应的技能模板，输出自然就更可控。

1.2 核心边界：它不是另一个模型，而是“技能外壳”

很多人误以为 Superpowers 是一个新的开源模型或者云端服务，第一次听到名字就去查模型榜单，结果什么都没查到。这里我帮你把边界划清楚：Superpowers 是一层“技能外壳”，跑在 Codex CLI 外面，也跑在你本地的代码仓库外面。它不改模型的推理内核，也不接管你的终端，只是在模型开始干活之前，把你要的技能清单和行动约束注入到上下文里。

你可以把 Codex 想象成一个能力很强但缺乏经验的实习生，Superpowers 则是你为这个实习生编写的《部门工作手册》。手册不会让实习生变得更聪明，但它确保实习生每一次干活前都先翻到正确的页面，按标准动作执行。没有手册，实习生靠猜；有手册，至少步骤和红线是稳定的。

这套方案的优点在于轻量化。它没有引入新的运行时，不需要你启动一个常驻服务，也不需要把代码推送到任何第三方平台。一切还是发生在本地命令行，敏感代码不离开你的机器，只是多了一堆 Markdown 格式的技能定义文件。这个轻量级的架构，让它在团队里推广的阻力非常小——只要装了 Codex CLI 的机器，复制一个技能包目录就能用起来。

1.3 它和普通 Prompt 工程的本质区别

你可能觉得，“那不就是写一些好的 prompt 吗？我平时也在用。”这里需要展开说一下。普通 prompt 是放在一次对话开头的文字，它解决的问题是“本次任务怎么执行”；Superpowers 里的技能是放在项目目录或者用户目录下、每次会话都会被反复加载的结构化指令，它解决的是“这个项目长期怎么被 AI 对待”。

举个例子。你告诉 Codex“请保持代码风格一致”，这句话写十遍，它依然不知道什么叫“一致”。但如果你在技能包里定义了一个style-guide技能，里面写明“缩进用 2 空格，不用 tab”“类名用 PascalCase 命名，私有字段前缀m”“禁止引入没有任何业务含义的魔法数字”，同时包含一份自动触发规则，那么 Codex 在改动代码时就会真正做到有据可依。

而且，普通 prompt 只存在一次对话里，换新会话就要重新讲一遍；Superpowers 的技能文件是持久化在仓库里的，团队成员 clone 下来就自带这套约束。新同学加入项目，看到技能目录，也就等于看到了 AI 协作约定，这种“把工程规范以文件形式沉淀下来”的做法，才是它真正有生命力的地方。

2. 安装与基础配置：从零到第一个技能

2.1 环境准备与依赖检查

动手装之前，先把基础环境理一遍。Superpowers 不是独立二进制包，它的运行依赖两个东西：本地有 Codex CLI，以及本地能访问 OpenAI 兼容接口。你不需要已经开通 Codex 的付费订阅，只要 Codex CLI 能正常跟你选定的模型对话，Superpowers 就能工作。

安装 Codex CLI 本身很简单，官方推荐的是 npm 全局安装。我建议你在干净目录里先确认版本，避免环境变量混乱：

node -v npm -v codex --version

如果codex命令还没装，执行：

npm install -g @openai/codex

装完之后，建议先做一次最小验证，用一个最简单的任务让 Codex 跑通整个链路，比如让它读取当前目录的文件列表并输出。这一步不是浪费，它能确认你的网络连接、API Key、终端权限都没问题，免得后面装完 Superpowers 才发现问题出在最底层。

接下来确认你已经知道 Codex 配置文件的默认位置。在 Linux 和 macOS 上，它通常是~/.codex/config.toml；Windows 上则位于%USERPROFILE%\.codex\config.toml。这个文件后面我们会用到，所以先打开看一眼现有内容。如果你之前从没手动改过，文件可能只有一行 model 配置，这很正常。

2.2 初始化 Superpowers 配置目录

Superpowers 的安装原则是“不污染 Codex 核心目录，不修改模型行为，只新增技能资产”。我建议在用户目录下建一个独立的目录来存放所有技能文件，名字就叫superpowers：

mkdir -p ~/.codex/superpowers/skills mkdir -p ~/.codex/superpowers/templates mkdir -p ~/.codex/superpowers/commands mkdir -p ~/.codex/superpowers/rules

如果你是从 GitHub 上的开源版本安装，也可以直接克隆整个仓库，然后做软链接。比如你希望把技能库维护在单独的 Git 仓库里，方便多台机器同步，可以这样：

cd ~/.codex git clone https://github.com/your-org/superpowers superpowers ln -s ~/.codex/superpowers/skills ~/.codex/superpowers/skills-link

我个人更推荐“目录就是仓库”的做法，也就是把整个~/.codex/superpowers作为 Git 仓库来管理。这样技能文件的增减、修改，都有记录。别小看这个细节，技能文件本质上是“AI 时代注释良好的代码规范”，它值得被版本化。后续团队里有人补充了新技能，合并的时候一样走 Pull Request。

初始化完成之后，我们需要在里面放第一个技能文件。先建一个最基础的overview.md，它的作用是告诉 Codex：当你读取到这套技能目录时，先明白自己“被期望用什么样的姿态工作”。这个文件不需要写得很长，但一定要交代清楚最基本的行动原则，比如“永远不要修改未被请求的文件”“遇到不确定的步骤先问再动手”“所有命令执行前先说明目的”。这一段相当于整个技能体系的总纲，后面每个具体技能都好比总纲的条款展开。

2.3 在 Codex 中绑定技能：AGENTS.md 机制

光有技能目录还不够，Codex 不会自己跑去读这些文件。这里需要用到 Codex CLI 的一个关键机制：AGENTS.md。它是 Codex 启动会话时会主动扫描的项目说明文件，相当于“给代码代理看的 README”。

做法很简单：在项目根目录（或者在用户全局目录~/.codex/AGENTS.md）里，写入一段引导文字，明确告诉 Codex 去加载 Superpowers 技能库中的索引文件。

# AGENTS.md 在开始任何编码任务之前，请先阅读本项目约定的技能与规则： 1. 读取并遵循用户全局技能库：~/.codex/superpowers/README.md 2. 任务类型与技能文件对应关系，见 ~/.codex/superpowers/skills/index.md 3. 所有自动化脚本必须符合 rules/automation.md 中的安全约束

这样做的好处是，每个项目都能用自己根目录下的AGENTS.md来定制要启用哪些技能。如果你是一个多语言仓库，可以在AGENTS.md里写清楚“Java 相关任务切换到 java 技能集，前端任务切换到 frontend 技能集”。

需要提醒的是，AGENTS.md不是每次都从零解析。Codex 会把它作为会话开头的固定上下文，但我实测下来，技能文件数量如果过多，token 占用会明显上升，单次会话的成本和响应速度都会受影响。所以不要一股脑把所有技能都塞进全局配置，而是要按项目实际需求去裁剪。我的习惯是全局只放 3 个通用技能，剩下的按项目挂载。

3. 核心机制拆解：技能、命令与上下文

3.1 技能包的三层结构

深入体验下来，一个成熟的 Superpowers 技能包，不应该只是“一堆 Markdown 文件”，它需要有清楚的层次结构。我把它分成三层：总则层、技能层、实例层。

总则层就是上一节说的README.md、index.md、rules/目录里放的安全与风格红线。这一层回答的是“AI 在这个项目里能做什么、不能做什么”。比如“不得向公网发送任何请求”“不得在未确认的情况下删除分支”“所有新增依赖必须显式写入到包管理文件”。这些内容大概率不会在一个具体任务里被完整用到，但它们会像常量一样被 Codex 反复参考。

技能层是核心。每个技能文件是一个独立的 Markdown，文件名与任务类型一一对应。比如skills/code-review.md对应代码审查，skills/java-refactor.md对应 Java 重构，skills/test-writing.md对应测试编写。文件里需要包含触发词、输入要求、执行步骤、输出格式、完成标准。我建议所有技能文件都遵循统一模板，这样 Codex 在“选择技能”时不容易混乱。

实例层则是把技能落到具体场景时产生的文件，比如某个组件重构后的对比文档、一次依赖升级的变更清单。这些不一定需要全部留给 Codex，更多的是给人类工程师做 review 用的。你可以让技能执行完成后，把操作摘要写到一个session-notes/目录，这类文件还能反向用于训练团队的提示词质量。

3.2 命令保留与代码守护

Superpowers 里有一个让我特别看重的设计，就是“命令保留区”。简单说，在技能文件里，可以明确指定哪些命令被允许执行、哪些命令必须经过用户确认。你不希望 Codex 在重构过程中顺手执行一个git push，更不希望它未经确认就npm install一堆依赖进生产分支。

具体实现上，我是在rules/automation.md中定义了一张“命令分级表”，比如：

Codex 读到这张表后，行动会规矩很多。这个方法比在对话里反复说“你要小心”有效得多，因为规则以代码形式固定下来了。实测下来，启用命令保留区之后，误操作概率下降非常明显，尤其是“AI 自作主张安装依赖”这类问题几乎被根治了。

另一个和命令保留配套的机制是“文件守护名单”。有些文件不允许 AI 动，比如config.toml、AGENTS.md本身，或者包含密钥的环境变量文件。我通常在规则文件里加一段：任何修改涉及守护名单中的文件，必须预先展示完整 diff，否则不能继续。这相当于给 AI 装了一道只针对敏感文件的只读锁。

3.3 权限分级与安全模型

Superpowers 的安全模型不需要做得像企业级后端一样复杂，但至少应该把“用户权限”和“任务权限”分开。我习惯在技能库里定义三种角色视角：

• 只读执行者：只能读取代码、生成报告、分析风险，不能改任何文件。适用于代码审查、架构分析。
• 受控开发员：可以改代码文件，但命令执行范围和文件守护名单受控。适用于日常开发任务。
• 全权运维员：可以执行构建、依赖更新、运行测试，但依旧禁止推送到远程分支。适用于发布准备、工程自动化。

这个权限分级怎么落地？我是在agenda机制里实现的。启动任务前，Codex 会根据标题中是否包含[review]、[dev]、[ops]这样的标签，选择加载那一套技能和规则。人工只需要在提出任务时带上标签，剩下的事情交给技能包自动路由。

这套模型我认为最大的价值是让 AI 的“自由度”和“风险控制”解耦了。以前大家不敢放权给 Codex，是因为能力越大，破坏力越大。现在有了权限分级，你可以放心让它读整个仓库做全局分析，却不让它有随意改写关键配置的权利。这在做大型依赖升级、历史代码梳理时特别有用。

4. 实战：用 Superpowers 跑一个 Java 项目改造

4.1 从技能模板到任务清单

理论讲再多，不如看一次真实的运行过程。我拿团队里一个老 Java 项目来举例。这个项目的问题很典型：实体类直接暴露到 Controller 层，业务逻辑散落在 Service 里，测试覆盖率不到 15%。我们今天要让 Codex 先做一轮全面体检，再挑一个模块做“接口层封装”的改造示例。

首先，我把这次任务定义为一个[review]类型的操作，并指定加载java技能集。技能包会先在顶层README里确认 Java 项目的约定，比如 Maven 作为构建工具、JUnit 5 作为测试框架、类路径遵循com.company.product包结构。这些信息不是 Codex 从代码里猜出来的，而是技能包预先写好的。

然后，技能包里的java-refactor.md会引导 Codex 按顺序执行以下观察步骤：先读pom.xml确认依赖版本，再扫src/main/java的包结构，最后用find命令统计实体类和 Controller 数量。它输出的不是一份流水账，而是一张“改造优先级表”，每个候选类都会标注影响范围、风险等级、建议方案。这场面跟一个资深工程师进场看代码的判断路径几乎一致。

4.2 Codex 在技能约束下的执行流程

确认好任务清单后，我把任务改为[dev]标签，并启动针对OrderController的接口层封装改造。技能文件要求 Codex 先展示计划再动手，计划大概是这样的：

目标: 为 OrderController 引入独立的 Service 层接口 将 Entity 转为 DTO 返回给前端 改动范围: - src/main/java/com/company/product/service/OrderService.java - src/main/java/com/company/product/service/impl/OrderServiceImpl.java - src/main/java/com/company/product/controller/OrderController.java 风险点: - 现有单元测试依赖老的 Controller 返回类型，需要同步更新 产出: - 完整 diff - 变更说明文档

Codex 在技能包里读到“必须保留原有对外 API 的语义”这条规则，于是没有改动接口路径和参数结构，只是在内部把返回值换成了 DTO，并且补充了映射逻辑。整个过程里，它严格遵守命令分级表，跑mvn test之前先询问我，因为我设定的规则是构建命令属于“谨慎执行”。它也没有顺手格式化整个项目的代码风格，因为技能里明确说了“只处理与本次任务相关的文件”。

最终它提交了 4 个文件的改动，生成了一段清晰的 summary，列出每一项改动对应的原因。我花了几分钟扫了一遍 diff，没有发现多余修改。这和没有技能包的 Codex 行为差别很大。过去它可能会顺手把 import 顺序改了、把 Controller 里的日志写法换掉，这些“额外发挥”才是 review 时最头疼的地方。

4.3 Java 技能集的核心规则与效果

这个案例里，Java 技能集的关键规则并不在于写了多少条，而在于“掐住了 Java 项目的几个命门”。它重点关注四个方面：包结构合理性、可变状态隔离、接口与实现分离、测试覆盖要求。比如在改造实体映射的时候，技能要求“禁止在 DTO 里暴露任何实体类的类名”，Codex 就会主动改掉那些隐含耦合的字段命名，而不会只做机械的一对一搬移。

另一个让我印象深刻的点是，技能包在处理 Maven 依赖时，会先检查中央仓库的最新小版本，再对比当前 pom 里的版本，按照“只在有明确修复或安全公告时才建议升级”的原则生成报告。这一点比很多人在 prompt 里写“升级所有过时依赖”要稳得多，后者往往会让 AI 盲目升到一个不兼容的版本，导致部署时炸出一堆问题。

从结果价值来看，这类 Java 改造任务，在使用技能包前大概需要一个高级工程师全程盯 2 到 3 小时，边看 Codex 操作边及时纠正。使用技能包后，Codex 大部分时间在安静地按步骤执行，人工变成了“审批人”，只在关键节点看计划、看 diff、放行命令。这不是省了 20% 时间，而是把整个工作模式从“人机协同调试”转变成了“带权限约束的自动执行”。

5. 常见问题与排查实录

5.1 技能文件未被 Codex 读取怎么办

这应该是出现频率最高的一个问题。你明明把技能文件写好了，AGENTS.md 也配置了，但 Codex 执行任务时还是像失忆一样，完全对不上技能定义。遇到这种情况，我建议按下面的顺序排查。

先检查AGENTS.md的路径和权限。Codex 对项目根目录的识别，取决于你在哪个目录启动codex，如果在子目录里启动，可能扫不到根目录下的AGENTS.md。解决方法是：所有自动化任务尽量在项目根目录启动，或者在你项目的AGENTS.md里用绝对路径引用技能库位置。

再检查技能文件的命名和触发词是否匹配。比如技能文件里写的触发词是“code-review”，但你对话里说的是“帮我看下代码”，Codex 可能不会联想到这个技能。我的做法是在技能index.md里维护一个“用户说法”到“技能名”的映射表，把常见的自然语言表达都提前绑定好。比如“检查一下代码质量”“这块重构一下”都映射到对应技能，这样命中率会明显提高。

最后看上下文长度。技能文件过多或过长，可能被 Codex 的上下文窗口截断。我的建议是每个技能文件正文控制在 300 行以内，把最关键的约束写进去，细节放到模板目录里按需加载。如果技能库已经膨胀得很厉害，定期做一次清理和合并，比一味地往里堆内容更有效。

5.2 常见报错速查手册

排查问题要多点耐心，不要一碰到异常就急着改技能文件。我有一点经验：大多数和“模型表现不稳定”相关的报错，根子不在模型，而在“上下文规则互相冲突”。这时候你打开技能库，逐条检查是否存在“A 规则说可以做，B 规则说不允许”的矛盾指令，把冲突解决了，问题自然消失。

5.3 团队落地时容易踩的坑

最后聊几个团队落地时特别容易踩的坑。第一个坑是“技能文件越多越好”。其实技能文件数量一旦超过 20 个，Codex 在每次会话里都要消耗大量 token 去“浏览索引”，响应速度和准确率都会下降。我的建议是把技能分为“常驻”和“按需”两类，常驻技能只放最通用的 5 到 7 个，按需技能通过触发词动态加载。

第二个坑是“规则写得像法律条文”。如果你用一堆“应当”“必须”“建议”来写规则，Codex 很难判断优先级。更好的做法是给出明确的“如果、则”语句，例如“如果目标文件是 DTO，则不可以使用实体类名”，这比“注意解耦”有用得多。

第三个坑是“没有人工审查环节就全自动跑”。Superpowers 再怎么强，它依然需要人工做最终把关。我给团队立的规矩是：所有涉及多文件修改的任务，必须先生成一份改动计划文档，人工确认后 Codex 才能执行；执行完成后，所有 diff 必须展示出来，哪怕是在终端里分页查看。这个流程看起来很朴素，但恰恰是它能长期稳定运行的关键。

说实话，我自己花过很长时间在“如何写一个完美的 prompt”上，后来才意识到，真正的杠杆不在那几句临场话术上，而在于把团队的工程规范、任务流程和红线，变成一套可持续复用的技能资产。Superpowers 最吸引我的地方，正是它把这件事变成了随手可维护的 Markdown 文件。每个人都能补充一条规则、完善一个模板，下一代接手的人打开目录，看到的不只是冷冰冰的命令，而是所有人踩过坑之后沉淀下来的共同约定。如果你也想在团队里试试，我建议从一个最痛的任务开始，比如代码审查，先把第一个技能跑顺，再逐步铺开。那种“AI 第一次按你的规矩把事办妥”的感觉，会给你继续投入下去的底气。