企业官网建设流程全解析

说实话，我最近已经被命令行 AI 编码代理搞得又爱又恨。爱的是它写工具脚本、补单元测试确实快；恨的是但凡任务稍微涉及一点全局理解——比如让 Codex CLI 去改造一个没人维护的老模块——它就像个刚入职的热血新人，上来就动手，改完一跑测试，红了一片。后来我在 GitHub 上刷到 Superpowers 这个项目，花了一个周末把它接入到我的工作流里，这才发现问题不全在模型，而在我们根本没给代理一套"如何做工程"的行为框架。这篇文章就把我的完整使用过程拆开讲：Superpowers 到底是什么、它的工作机制怎么设计、怎么配合 Codex CLI 落地，以及我实际用下来哪些地方真香、哪些地方必须小心。

1. 当 AI 代理不再只是"代码生成器"：Superpowers 的定位是什么

先说我最直观的感受。以前用 Codex CLI 写一个独立的小函数，它表现像天才；但把它扔进一个几千文件的仓库里，让它"帮我找到订单模块的重复逻辑并合并"，它经常给我交来一份结构漂亮的方案，但里面引用的文件路径根本不对，或者把另外一处正在被使用的公共方法给顺手删了。

这不是模型蠢，而是它缺少一个合格的工程师在面对任务时天然具备的几步动作：先搞清楚上下文、再确认约束、然后才动手，最后还要跑验证。Superpowers 这个项目，本质上就是把这些工程动作做成了一组可持续加载的技能文件，让代理在接到任务时按流程走。

1.1 先说说命令行编码代理的三个典型毛病

我见过的翻车现场大致可以归成三类，你可以对照一下自己有没有遇到过。

第一个是缺乏上下文探索。代理拿到一个 issue 描述，经常直接跳到它认为"最相关"的代码文件里开始改，完全不看调用方、不搜历史改动、不查测试覆盖。对小型代码库这可能还好，但在稍微大一点的项目里，它改的往往是表面症状，问题根子在三层调用之下的另一个模块里。

第二个是不做验证闭环。它告诉你"改好了"，但你问它跑测试了吗，它会说"我没找到测试命令"。更常见的版本是：它自己在脑子里推演了一遍，觉得逻辑正确，就不再实际执行。对 AI 代理来说，想象里的正确和真实的正确之间，经常隔着一大堆编译错误和隐藏的边界条件。

第三个是不遵守项目约定。每个团队都有自己的代码风格、目录组织和约定俗成的写法，比如错误处理统一用某个返回结构、数据库访问必须走 repository 层。代理不知道这些的时候，写出来的代码看着能用，但和整个项目格格不入。

1.2 Superpowers 解决的核心问题

后来我才理解，这几个毛病的共同根源，是我们在用"生成答案"的思路去驱动一个应该"执行过程"的代理。你给模型一个大 prompt，让它一次输出最终方案，它当然倾向于一步到位，跳过中间那些不可见的过程。

Superpowers 的思路反过来了。它提供的是一个行为框架：代理不是只给你结果，而是像真实工程师那样，先研究再行动，行动完再验证。我自己理解它像是给代理装了一个"项目操作系统的调度器"——不同的技能（Skills）就是不同的 App，接到任务后先判断该启动哪个 App，按里面的流程一步步执行，并且把每步结果记录下来。

1.3 一个很容易踩的误区：以为它是某个具体工具

我最初以为 Superpowers 是一个独立的 CLI 工具，装完就能用，后来发现理解错了。它更像是一套结构化的技能包 + 工作流约定，运行载体是 Codex CLI、Claude Code 这类命令行编码代理。代理本身还是那个代理，但因为它先读到了 Superpowers 提供的技能说明书，行为方式会明显不同——从一个"直接给答案的人"变成一个"先立规矩再干活的人"。

适合用它的，是每天都在命令行里和编码代理打交道、并且手上确实有多个非 toy 项目的开发者。如果你只是偶尔让 AI 写个一次性脚本，那确实没必要上这套东西，反而会觉得流程太重。

2. 工作引擎拆解：Superpowers 的"先探索、后行动、再复盘"循环

我刚开始用的时候，比较惊讶的是它并不神秘。Superpowers 没有用任何黑魔法，它靠一套非常朴素的执行循环让代理变得可靠。我把这套循环拆开看，发现核心思想就是工程管理教科书里常写的 PDCA 循环，只不过被翻译成了代理能执行的指令。

2.1 一个完整的"超能力工作流"是怎么跑的

拿一次典型任务来说，我让代理去"修复支付回调里的并发问题"。没有 Superpowers 之前，它大概率会直接打开回调文件开始分析；接入了 Superpowers 之后，它的执行路径会长这样：

• Research（研究）：先扫描项目结构，搜索支付回调相关的所有调用方和数据表，列出代码现状与潜在风险点，而不是急着下结论。
• Plan（计划）：基于研究结果生成一份改动计划，写明要改哪些文件、影响哪些模块、需要加什么测试。
• Implement（实施）：按计划逐步修改，每完成一个文件就做一次小验证，而不是攒到最后统一处理。
• Verify（验证）：实际运行相关测试、静态检查或编译，把输出结果记录下来。
• Reflect（复盘）：总结这次改动是否符合项目约束，有没有遗漏的调用方，并把关键结论写回会话文件。

这个循环听起来像废话，但难就难在让代理愿意执行。Superpowers 做的，就是把每一步拆成代理看得懂、也愿意去做的具体指令，并且在循环之间嵌入"必须输出中间产物"的要求。

2.2 技能文件：给代理看的"标准化作业指导书"

Superpowers 里的每个技能，本质上是一份 Markdown 文件或一组文件，里面包含这个技能的触发条件、适用场景、操作步骤和验收清单。你可以理解成给代理看的 SOP，或者更生活化一点：像是给一个厨师的菜谱，里面不仅写了菜怎么做，还写了"什么时候不能做这道菜""做完之后怎么自检"。

我在实际使用中发现，技能文件写得越具体，代理执行得越稳。比如研究类技能会要求代理先回答几个问题（改动的核心目标是什么、当前实现有哪些潜在路径、哪些地方不在本次范围内），再允许它进入计划阶段。这个"回答完问题才继续"的机制，有效避免了代理自作主张乱跑。

2.3 Session 文件：让代理记得自己干过什么

这是我喜欢 Superpowers 的一个设计。每次任务开始时，代理会创建一个 session 记录文件，把任务背景、发现的事实、制定的计划、执行的步骤和验证结果都写进去，每个阶段更新一次。

这么做的好处太明显了。以前和 Codex CLI 对话，聊到第十四轮，它基本忘了第三轮确认过的约束；现在它会先读 session 文件，再根据以前的记录继续。我遇到任务被中断再恢复的场景，靠 session 文件能无缝接上，不用把上下文重新喂一遍。

2.4 为什么"过程监督"比"结果监督"更可靠

这里我想说一个我自己的判断。模型生成的代码，质量稳定性远不如我们想象中高。一次生成的答案可能 90 分，下一次同样的问题可能就只有 40 分。问题在于，如果你只盯"最终输出"，你根本看不出来 40 分是怎么来的。

Superpowers 真正有价值的地方，是它把隐性过程变成了显性产物——中间的研究笔记、计划、验证记录都在那。我作为人类审查者，不需要完全信任代理的结果，我可以打开 session 文件和各个阶段记录，看看它的思考路径有没有跑偏。这个过程监督的工作方式，我认为比任何"再生成一次碰运气"的调优都更扎实。

3. Codex CLI 集成实战：安装、配置与第一次运行

理论聊完，直接进入实操。我目前的主力组合是 OpenCode 系的 Codex CLI 加 Superpowers。老实说，这个项目更新很快，你看到的目录结构可能和我当时不完全一样，但核心接入思路基本没变——把技能目录暴露给代理，并在工作开始时要求它使用这套流程。

3.1 安装 Codex CLI 与获取 Superpowers

如果你还没有 Codex CLI，第一步很简单，需要 Node.js 环境：

npm install -g @openai/codex

装完以后，先跑一次codex确认它能正常工作。这里有个小提示：如果你在公司内网或代理受限环境，Codex 的登录验证和大模型请求都算在对外网络流量里，需要先确认网络策略是否允许。

接着获取 Superpowers 仓库。我当时用的是这个地址，如果仓库迁移了，以项目 README 上的最新地址为准：

git clone https://github.com/jesse-vincent/superpowers cd superpowers

仓库结构不复杂，核心部分是 skill 文件，按技能类型分了目录，里面每个 Markdown 文件就是一个技能。我一般先花十分钟浏览一遍有哪些技能名字，后面触发的时候心里有数。

3.2 让 Codex 在任务中读取技能文件

这一步是核心。Superpowers 不会自动注入到 Codex 里，你必须明确告诉代理"哪些文件是你的工作规范"。我采用的方式是在项目根目录放一个AGENTS.md文件，把技能目录引用进去，内容大致是这样：

# 项目工作约定 - 本项目使用 Superpowers 工作流。 - 当任务涉及需要诊断、重构或实现复杂功能时，先读取 ~/superpowers/skills 下的对应技能文件，然后按技能中的步骤执行。 - 每个任务开始前创建 session 文件，记录研究结论与计划；每完成一步，更新 session 文件。

如果你愿意，也可以直接在 Codex 的配置上下文里加入全局指令，但我更推荐放项目根目录。原因是 AGENTS.md 是跟着仓库走的，团队其他人克隆项目后也会自动生效，不依赖个人机器上的配置。

3.3 不同项目如何规范路径

如果你的项目仓库不属于自己的个人账号，或者不能随便放额外文件，也可以把技能引用放到~/.codex/config.toml的上下文指令里。大概长这样：

[model_providers] # 你自己的模型提供商配置 ... [instructions] files = ["~/superpowers/INSTRUCTIONS.md"]

这里要特别说一句：网上很多教程给了精确的配置字段，但我发现 Codex CLI 更新频繁，字段名偶尔会调整。最稳的做法是运行codex --help或查看文档确认你当前版本的指令注入方式。我当时花了半小时折腾配置，最后发现版本升级后语法已经变了。

3.4 第一次运行应该测试什么

配置完以后别急着接大任务，先用一个中等体量的任务验证整条链路。我当时的自测用例是让 Codex 分析一下某个模块的功能与边界，指令这样写：

请使用 Superpowers 工作流来分析 src/utils/price.ts 的职责边界，并输出研究报告。

第一次跑完，我从输出里看到它没有立刻改代码，而是先列出文件结构、搜出调用方、写了一段研究笔记，然后才给出结论。那一刻我就知道事成了——因为它终于没有碰代码之前就开始改代码了。

另一个观察是 token 消耗会上升。流程变长、中间文件变多，每次任务的 token 用量大概比直接问要高 20%-40%。如果你用的是按量计费的大模型，这个成本要提前算进去。但在可靠性收益面前，我个人认为这点额外开销是完全值得的。

4. 我实际用下来的应用场景、效果与翻车教训

理论和配置都讲完了，这一部分我挑了几个真实的实战场景，把效果和坑都摊开说。

4.1 遗留项目探索：最大的惊喜

我接手过一个老模块，一个服务里有三套几乎一样的订单状态判断逻辑，分散在不同文件里。以前这种任务我会自己花一下午读代码，或者让代理直接搜关键词，然后整理一份"相关代码清单"。

用 Superpowers 的研究技能之后，它主动做了这几件事：画出模块之间的依赖关系、找出三套逻辑各自的调用入口、对比它们的状态枚举差异、最后产出一份推荐合并顺序的报告。而且因为它全程使用 session 文件记录，我发现它某一步对某接口的判断有误时，可以直接在 session 里指出来，它修正后重跑了后续分析。这种"可被纠正的过程"价值极大。

4.2 用 TDD 流程实现新功能

写一个新功能时，Superpowers 的 TDD 技能会在代理写任何实现代码之前，要求先写一个失败测试。这对不习惯 TDD 的人来说会有点烦，但效果立竿见影。

我让代理实现一个带过期时间的本地缓存。按流程，它先写测试用例覆盖缓存命中、过期、并发读写等场景，然后看着测试失败，再实现真正代码。这个过程中最让我放心的一点是，代理不会在实现到一半时偷偷改测试来迎合代码——技能里有明确要求：测试文件必须保持任务开始时的定义。最后跑下来，测试全绿，而且覆盖了我原本想手动补的边界情况。

4.3 重构一个老模块：依赖分析与安全网

重构是我最担心代理搞砸的场景，因为一次改名会连锁影响到所有调用方。Superpowers 给我带来的改变是，它把重构分成了两段：先做依赖分析，再执行迁移。

代理会把目标模块的所有直接调用方、间接调用方、测试引用全部列一遍，并确认没有遗漏后才开始改名。改完之后，它会跑项目的完整测试集，而不是只跑相关模块。我遇到过一次它分析遗漏了某个冷门调用方，但当时项目里恰好有编译时检查能兜住，这也提醒我：无论代理流程多完善，人类 review 依赖分析结果这一步不能省。

4.4 我踩过的坑：技能教条化带来的死角

Superpowers 不是银弹，我也翻过几次车。最典型的一种情况是过度流程化：一个只需要改一行配置的任务，代理还在先创建 session、写研究笔记、列详细计划，输出了一堆和任务无关的过程文档。后来我在使用指令里加了"简单任务可跳过完整流程"的约定，才好一些。

第二种情况是多个技能互相冲突。有一次我想做代码优化，结果代理同时读取了优化技能和重写技能的执行流程，两边都有"重写整个模块"的倾向，差点把一个稳定的模块推倒重来。这个问题后来靠我在 AGENTS.md 里明确任务优先级解决的：当技能发生冲突时，优先执行研究技能的依赖分析结论。

4.5 针对 Java 项目的额外注意点

如果你像一些在 Java 技术栈里的朋友一样，主要用 Maven 或 Gradle 项目，有两点需要额外注意。

一是验证成本天然更高。Java 项目的编译和测试比脚本语言慢很多，代理每次 Verify 都要等 Maven 跑完一整个模块，token 和等待时间都会明显上去。我给 Java 项目配置时有意识地做了裁剪：让代理只跑-pl 模块名 -am这类精准构建，而不是根目录全量 build。

二是类型与框架约束多。比如 Spring 项目里 Bean 的代理模式、MyBatis 的 Mapper 接口，代理靠文本理解很容易绕晕。我在 Java 项目的 AGENTS.md 里写明了"所有数据库操作必须先查找现有 Mapper 方法，不得自行创建 Session"，这个问题就少多了。

5. 给准备入坑的人：配置建议和边界认知

最后这节，是我用了这个小一个月后的沉淀。有些是配置建议，有些是我踩过之后才明白的边界。

5.1 什么样的代码库获益最大

我的经验是，单体大仓库、多模块项目、遗留代码这三类场景收益最大。因为这些项目里，上下文理解比代码生成重要得多，代理缺的不是写代码的能力，而是看懂项目的能力。反过来，如果你是做十几个独立小脚本的仓库，每个脚本几百行，业务流程一目了然，Superpowers 带来的过程开销反而可能拖慢你。要理性评估自己的场景再决定上不上。

5.2 把团队规范改写成自定义技能

Superpowers 真正让我喜欢的一点是，它允许你扩展自己的技能。我现在已经把团队常用的错误码规范、提交信息格式、模块分层约束，都写成了一个自定义技能文件放进去。

改写的门槛很低，你只需要遵循和其他技能一样的 Markdown 格式：写清技能用途，再写操作步骤和自检清单。这样代理在动手前会先读这份团队特有规范，写出来的代码就不再是"看着没错"而是"符合我们项目风格"——这个差距，只有在你对比过之后才会意识到有多大。

5.3 权限、隐私与代码审查

这里必须提醒一句：使用这类工具，代码内容会发给大模型提供商处理。涉及商业敏感代码的项目，一定要确认公司政策允许。我自己的习惯是：核心算法模块、未公开的商业逻辑，从不丢给这类代理做分析，宁可自己花时间看。

另外，Superpowers 在工作流里会执行 git 相关操作和运行测试命令，本质上是有项目写入权限的。我建议你第一次接入时盯紧一点，最好先在一个专门的测试分支上跑通几个任务，确认它的行为符合预期后再放到主开发分支上。

5.4 三条给新手的落地建议

如果你打算试，我给出最实在的三条建议。第一条，先跑通一个小项目再上大仓库，别一上来就让它重构核心模块。第二条，务必阅读一遍你自己的 session 文件，把你的要求写得更明确，它是你观察代理思考过程唯一窗口。第三条，保持每周翻一次技能仓库的习惯，因为这个项目迭代很快，社区里会不断有新技能被合入，过两周你可能就从里面发现一个刚好能解决你当前痛点的技能。

我个人目前的配置方案是：项目根目录一份 AGENTS.md，技能库目录保持每周同步一次，简单的配置修改任务允许代理跳过完整流程。这套方案我用下来，最大的改变不是代理生成的代码变聪明了，而是它至少不再像一个没头苍蝇一样乱飞了。最后分享一个小技巧：如果你给 Codex 的命令以 "请按 Superpowers 工作流执行" 开头，它读到 AGENTS.md 的时候会更明确地进入对应状态。这个前缀，几乎相当于把代理的"工程师人格"先叫醒，再让它干活。