企业官网建设流程全解析

我给自己立过不少规矩，其中一条是：AI 编程助手用不好，多半不是模型不行，而是人没有把工作流收拾明白。去年我用 Codex 干活，一开始和大多数人一样，觉得多敲几行提示词就能解决所有问题，结果经常出现改 A 坏 B、测试没跑就提交、重构到一半上下文丢失的尴尬局面。后来我把一套叫 superpowers 的技能体系引入日常开发，情况才真正稳定下来。这篇文章不是官方文档的复读，是我自己在 Java、前端和日常脚本任务里折腾了几个月后的真实总结。我会尽量讲清楚它解决什么问题、怎么装、怎么配、怎么在项目里落地，以及哪些地方最容易踩坑。

1. 我和 Codex 之间只差一套"superpowers"

1.1 一开始我以为多敲几行提示词就能解决

我先交代一下背景。我日常要维护的代码库很杂：有历史遗留的 Java 服务、有前端 React 项目、还有一堆自动化脚本。Codex 这类编程 Agent 刚火起来的时候，我确实被它的代码生成能力惊艳到，写个算法、补个单元测试都很顺手。

但用着用着就发现不对劲。同一个需求，我今天写两段提示词能搞定，明天换一种说法，它输出的代码风格完全不同，甚至把不该动的文件也给改了。更烦的是，它不知道我项目的代码规范，不知道哪些目录绝对不能动，也不知道我习惯先写测试再写实现。换句话说，它很聪明，但不了解"我的规矩"。

我一开始以为是提示词写得不够长、不够具体。试过把整个 README 粘贴进去，试过写超长的 system prompt，也试过在每次对话开头重复一遍项目背景。效果有，但不持久。提示词稍微长一点，模型的注意力就被稀释，真正要紧的约束反而被忽略。这感觉就像你请了一个能力很强但记性不好的实习生，每次都要重新交代工作方式，一旦交代得不够清楚，他就按自己的想法来了。

1.2 从"能跑"到"稳定跑"：差距在标准化

后来我看到一个观点，大意是：Agent 用得好的团队，不是提示词写得好，而是把"怎么干活"做成了可复用的标准操作流程。这个说法我一开始不太服气，觉得太抽象。直到我把同一类重构任务连续执行了五次，每次都要重新组织提示词，才意识到问题的本质。

模型本身的能力当然重要，但"稳定"比"聪明"更能决定你在生产环境里敢不敢把活交给它。所谓 superpowers，给我的感觉就是给 Codex 装了一套标准化的外置大脑。它不替代模型，也不替代人的判断，而是把那些一遍又一遍重复的指令、规则、检查项，固化成一个个可以被随时调用的技能文件。以后我要让 Codex 干活，不是靠临场发挥写提示词，而是直接调用一个经过验证的技能包。

这套东西解决的核心痛点有三个：

• 上下文不连贯：一次会话里塞太多背景信息，模型容易抓不住重点；拆成技能文件后，每个技能只关注一件事。
• 行为不稳定：同样一句话，不同模型版本、不同会话里的输出差异很大；技能文件把步骤固化成了 checklist，输出方差明显变小。
• 经验不沉淀：我在一个项目里总结的教训，换个项目又得从头说起；技能文件可以在项目之间复用，团队也可以共享。

1.3 这套体系适合谁来用

如果你只是偶尔让 AI 帮你写个正则表达式、翻译一段注释，那 superpowers 这套东西对你来说可能过重了。杀鸡用牛刀，没必要。

真正适合引入它的是这几类场景：

• 中度以上体量项目：代码库有一定规模，改动影响面大，需要 Agent 在动手前先理解模块边界。
• 高频重复的开发任务：比如批量修 lint、加单元测试、升级依赖、重构某个固定模式，这类任务非常适合固化成技能。
• 多语言多项目切换：你在 Java、TypeScript、Python 之间来回切换，如果没有统一的规范层，每个项目都要重新建立约束。
• 团队协作：你想让所有成员用 Agent 时的行为标准一致，而不是各自发明一套提示词。

2. 拆开看 superpowers 的构成：技能文件、钩子与命令

2.1 技能文件：给 Agent 的操作手册

先聊最核心的部分。我自己的理解是，superpowers 由一整套有结构的 Markdown 文件组成，每个文件解决一个具体动作，比如"写单元测试""做安全审查""重构数据库访问层"。文件名统一叫 SKILL.md，放在约定好的目录里，Agent 在需要的时候会自动找到它。

一个合格的 SKILL.md 不是把提示词换个后缀那么简单。它至少应该包含这几个部分：

• 触发条件：什么情况下应该使用这个技能，什么情况下不应该用。
• 输入要求：这个技能需要哪些前置信息，比如文件路径、接口定义、目标版本。
• 执行步骤：按顺序排列的操作步骤，尽量细到每一步都有明确输入输出。
• 检查清单：执行完之后的验收项，用来兜底。
• 反模式：明确告诉 Agent 哪些事情不能做，比告诉它该做什么更重要。

拿我最常用的"代码审查"技能来举例。它的前置条件写的是"仅用于已有代码的修改评审，不适用于从零开始的新文件"；执行步骤里有一条是"先读取 git diff，理解变更范围，再按影响面从大到小逐文件评审"。检查清单里有"是否修改了与本次需求无关的文件""是否存在 TODO 或调试输出被遗留"。

这套结构的好处是，它逼着我把模糊的"帮我看看代码改得对不对"变成了一个可执行的检查流程。Agent 拿到这个文件后，不再是自由发挥，而是按路径走。输出质量的下限被拉高了。

2.2 钩子机制：在合适时机介入

技能文件解决的是"怎么干活"的问题，钩子解决的是"什么时候介入"的问题。我对钩子的理解很朴素：在 Agent 的某个动作发生之后，自动触发一段脚本来做校验或转换。

举一个我实际遇到的例子。我团队里有人习惯用print()调试，提交前总忘删。后来我在 Codex 的配置里加了一个后置钩子：当 Agent 完成文件编辑操作后，自动运行一段脚本扫描目标目录下所有改动过的 Python 文件，如果发现print(或debugger关键字，直接拦截并提示 Agent 清理。这个改动之后，"测试代码误入生产环境"的问题基本绝迹。

钩子特别适合处理这类"模型不会主动记住，但对质量影响很大"的约束。你可以用它在编辑后自动格式化、在生成代码后自动跑测试、在文件变更后检查是否越过了目录边界。本质上，钩子把一些本来需要人在 review 阶段发现的问题，前移到了生成阶段。

2.3 命令宏观编排：把复杂动作收敛成一句话

lastly，还有一个我越用越顺手的部分：自定义命令。它有点像给技能文件套了一层快捷方式。原来我要完成"重构这个模块并补充测试"可能需要写一大段启动指令，现在只需要在配置文件里注册一个命令，然后告诉 Agent"执行重构任务，目标模块是 xxx"。

这套东西和 IDE 里的宏录制思路很像。你先把一个复杂的完整流程跑通，验证步骤和参数都没问题，然后把它保存在配置里。以后不要再每次从零开始组织语言，直接调用命令即可。我自己维护了一个命令清单，覆盖了常见操作，比如提交前安全检查、依赖升级、API 兼容性检查。时间久了，这个清单本身就变成了一份团队的操作规范文档。

3. 安装与初始化的实操记录

3.1 初始化前你要想清楚的事

先说明一点，我接下来写的是我自己的安装路径，不同环境、不同版本在细节上会有差异，但整体思路是通用的。

我建议在动手之前先花二十分钟回答几个问题：你希望这套体系管到哪一层？是所有代码改动都要经过技能文件，还是只在特定任务上启用？你有没有一个专门的目录来放技能文件？想清楚这些，再开始配置，效率会高很多。

3.2 一步步安装

我这边环境是 macOS，安装了最新版的 Codex CLI。第一步先确认 Codex 能正常运行，然后创建一个统一存放技能文件的目录，我放在了~/.codex/skills/下面。

mkdir -p ~/.codex/skills mkdir -p ~/.codex/hooks

接着，把技能文件放进去。比如我建了review这个技能，目录结构是这样的：

~/.codex/skills/review/ └── SKILL.md

然后编辑 Codex 的配置文件~/.codex/config.toml，把技能目录和钩子注册进去。核心配置思路如下：

# 指定技能文件根目录 skills_path = "~/.codex/skills" # 注册后置钩子：编辑完成后触发 [hooks.PostToolUse] matcher = "edit" hook = "~/.codex/hooks/post_edit.sh"

配置完成后重启 Codex 会话，让它重新加载配置。初次使用时，我建议先拿一个简单的任务做验证，比如让 Agent 调用"代码审查"技能检查当前 git 仓库的改动，看它是否能正确读取技能文件并按步骤输出结果。

3.3 最容易翻车的几个环节

这个部分我踩过的坑比较有价值，列出来供参考。

第一，目录权限和路径匹配。有一段日子，Agent 始终读不到技能文件，查了半天发现是配置里的路径写成了相对路径。在 Agent 的工作目录里，相对路径的起点并不总是用户主目录，非常容易出错。建议所有技能文件路径都写绝对路径，或者用~展开，并确认执行用户有读取权限。

第二，技能文件本身的格式要求。我看过一个说法：技能文件对结构有比较严的约定，乱写会导致解析失败。这是真的。最开始的版本，我把步骤写得像散文，Agent 读完表示没有可执行的步骤。后来改成明确编号的步骤和 checklist，情况立刻改善了。用代码块、列表、表格这类结构化的方式组织内容，远比一大段文字有效。

第三，钩子脚本不符合语言环境的假设。钩子脚本默认是按 bash 执行的，但如果你系统默认 shell 不是 bash，可能在环境变量上有坑。我有一个脚本在本地跑得好好的，放到钩子里就报command not found，排查后发现是 PATH 没有继承。处理办法是在脚本第一行写上#!/usr/bin/env bash，然后在调用钩子的时候明确指定解释器。

下面是我实际遇到的几个问题及处理方式的汇总，供排查参考：

4. 在 Java 项目里落地：一个真实的重构任务

4.1 任务背景与目标

理论讲再多，不如拉一个真实任务出来遛遛。我拿前阵子做的一个 Java 项目来举例。

项目是一个老旧的订单服务，核心逻辑写在一个超级类OrderService里，方法数量超过两百个，还混着 SQL、缓存、消息发送和导出报表的逻辑。说是"重构"，其实就是把一个牵一发动全身的类拆成几个职责清晰的类，并且不能让现有接口的行为发生变化。

这种任务用传统方式做，最怕两个问题：一是拆分过程中不小心改了业务行为，二是拆到一半上下文断掉，后面的人根本不知道前面改到哪里了。以前这种任务我至少要花两个完整工作日，全程高度紧张。

4.2 用 superpowers 拆解重构流程

这次我用了一个专门为"Java 类拆分重构"设计的技能文件。它的执行路径相当清晰：

第一步，读取目标类的完整源码，按职责将方法分组，要求输出一个分组清单，每个组标注方法名、依赖的字段和外部调用点。

第二步，根据依赖关系决定拆分顺序。规则很简单：被依赖最多的组先拆，牵涉面小的组后拆。这一步在技能文件里写得很死，就是为了避免 Agent 贪图方便先挑了简单但被大量依赖的方法开刀。

第三步，每拆出一个新类，立即执行一次编译和已有测试。这一步不等到最后统一验证，因为那会儿问题会堆成一坨。

第四步，全部拆完后，跑一遍全量回归，并检查是否有方法在原类和目标类中重复存在。

整个过程中，我只需在开始时提供目标类路径和期望的包名，剩下的步骤由技能文件引导 Agent 完成。它每次动手前都会回顾自己完成了哪一步、下一步是什么，这比在对话里反复追问进度要踏实得多。中途 Agent 有一次提出要把sendNotification方法从一个已拆出的类里再挪回去，理由是它同时被两个类依赖。如果按日常写法，我可能就顺着它调整了，但因为技能文件里明确写了"拆分后不跨类共享私有方法，公共方法收敛到新的工具类"，它最后选择了更合理的方案，新建了NotificationDispatcher。

4.3 效果对比与收益分析

这个任务最后花了四小时完成，中途我和 Agent 交互的次数不超过十次。最让我意外的一个效果是，Agent 在每一步都很自觉地执行了编译。这个动作其实很费 token，但技能文件坚持要求它做，结果确实值得。有一次拆到一半，一个方法引用了OrderService里的私有字段，编译立刻失败，Agent 马上停下来调整方案，避免了在错误方向上继续浪费。

对比一下传统流程和这套流程：

实事求是地说，它并没有让 Agent 变得更聪明，重构动作里的关键判断依然是人做的。但我明显感觉，原来像风筝一样的 Agent 行为被一条线拴住了，我敢把更大的活交给它，自己只需要在关键节点把把关。

5. 从个人效率到团队规范

5.1 团队接入前需要统一什么

个人用得顺手之后，自然会想着拉团队一起用。但这里面有个隐蔽的坑：个人的技能文件里往往藏着大量个人偏好，它们未必适合团队。

比如我在自己的 review 技能里写了"不允许使用var声明局部变量"，这是个人口味。拿给团队用，得先去掉这行，改成团队实际的规范。换句话说，团队接入的第一步不是安装工具，而是确定一份大家认同的基线规范。这份基线至少要涵盖三个方面：代码风格约束、安全红线、常见任务的验收标准。

风格约束不需要重写，直接引用团队已有的代码规范文档即可。安全红线要写得非常明确，比如"禁止生成硬编码密钥""禁止将日志输出敏感字段"，这类约束放进其他位置，在 use 时不会稳定生效，单独做成技能文件效果最好。常见任务的验收标准，其实就是把我们平时 review 时总在重复说的话，固化成 check list。

5.2 Agent 行为统一之后，代码审查也变了

团队接入后，一个有趣的变化是：代码审查的对象不再只是代码，还包括 Agent 的行为轨迹。以前 review 一个 PR，就是打开 diff 看代码对不对。现在我会先看 Agent 的执行步骤记录，确认它有没有按团队技能文件走。如果它跳过了中间验证步骤，那即使最终代码看起来是对的，也要打回去重来。因为不按流程走，极有可能隐藏了某个尚未暴露的问题。

此外，技能文件本身也要进 review 流程。团队成员在使用过程中提出的改进建议，如果验证有效，就更新文件。我把技能文件也放进了 git 仓库，和代码一起管理。这样每次变更都有历史记录，谁改的、为什么改，清清楚楚。

5.3 渐进式接入比一步到位更稳

我见过一些团队，刚引入 Agent 就想全面铺开，让所有任务都走技能文件。结果是文件写了一堆，Agent 反而变迟钝了，因为每次执行都要读入大量无关指令，浪费上下文不说，还可能造成决策干扰。

我们的做法是渐进式。先在低风险、高频的场景里试点，比如"生成单元测试""批量格式化"这类任务。跑了两周，验证稳定性没问题，再扩展到重构和代码审查。一步到位看着效率高，但排查问题的时候会因为变量太多而无从下手。渐进式接入有个额外的好处，它能逐步培养团队对 Agent 的信任感。信任这东西，只能靠一次次稳定完成积累起来。

6. 扩展 superpowers：把团队经验沉淀成新技能

6.1 技能文件的骨架与最佳实践

这套体系用得久了，你会发现自己最大的收获不是让 Agent 写代码更快，而是把手头积累的经验变成了一套可以复用的操作手册。我建议每个想长期使用的人都学会自己写技能文件，别只靠现成的。

我的写法习惯是，新建一个目录，命名要一看就懂，比如optimize-sql，里面放一个SKILL.md。文件开头先用一两句话说明这个技能的用途，然后明确触发条件。接下来是执行步骤，用编号列表，不厌其细地写。最后列检查清单和反模式。这里分享一个我常用的模板骨架：

# 技能名称 ## 用途 这个技能用于... ## 触发条件 - 满足以下任一情况时使用： - 不满足以下条件时不要使用： ## 输入 - 必填参数： - 可选参数： ## 执行步骤 1. ... 2. ... ## 检查清单 - [ ] 事项1 - [ ] 事项2 ## 反模式 - 禁止... - 不要...

6.2 编写技巧：关键不是列步骤，而是写验收条件

大部分新手写技能文件，容易光顾着写步骤，忘了写验收条件。我自己的体会是，验收条件比步骤更重要。

步骤写得再详细，Agent 在执行过程中也可能遗漏或者做错。但是，如果你明确写出了"完成后的代码必须通过mvn test""所有新增公共方法必须有 javadoc""敏感信息不得出现在日志中"，Agent 就有一个事后的自查依据。这相当于在代码生成的末尾强行加了一道质量门禁。

举个例子，我写过一个"spring-boot-依赖升级"的技能文件。执行步骤就三步：读取pom.xml，升级指定依赖版本，运行测试。看起来很简单，但真正起作用的其实是验收条件部分——它要求 Agent在升级后检查是否有javax.*导入变成了jakarta.*，是否有 API 调用方式需要同步调整。没有这些验收条件，升级依赖这种简单任务的失败率其实很高。

6.3 测试和迭代：技能文件也要有版本

最后分享一个我一直在坚持的习惯：新写的技能文件，我不会直接拿真实任务跑，而是先在一个野生的 demo 仓库里试运行。demo 仓库故意保留了一些常见问题，比如不规范的命名、缺失的测试、遗留的调试代码。技能文件如果能在这个"脏"仓库里稳定完成任务，我才敢放到真实项目里。

技能文件也是一个会腐烂的资产。模型的版本在升级，代码规范在演变，团队里来了新人，这些变化都会让旧技能变得不再适用。所以隔段时间就要回访一下，看看有没有已经过时的约束。我自己是每个月花一点时间，把使用频次较低的几个技能文件拿出来重新审视。该删的删，该改的改。这一轮轮迭代下来，留下的每一个技能文件基本都经受过实战检验。

这个思路放到团队里价值更大。新人加入时，不需要老人一遍遍口头交代项目规则，直接把技能仓库地址发过去，让他跟着 Agent 的操作过程熟悉工作流，既能快速上手，也能尽早发现问题反馈回来。

最后再分享一个我个人的小习惯：所有技能文件我都用中文写执行步骤，但关键命令和路径保持英文原样。因为中文描述能让我在回顾文件时快速形成场景理解，而命令保留原始形态避免了复制粘贴出错。这个小习惯帮我省掉了很多来回试错的成本。如果你也准备在自己的开发环境里把 Codex 用透，我强烈建议从三个最头疼的重复性任务开始，先把它们固化成技能，用顺了再加新的。从一个小切口进去，远比一上来就把整个工作流全部塞进这套体系靠谱得多。