企业官网建设流程全解析

说实话，在接触“superpowers”之前，我一直觉得给 AI 编码工具讲“工程规范”是一种徒劳。彼时的日常是：让 Codex 帮我修一个回调嵌套的报错，它秒回了“看起来是这里的闭包捕获问题”，改完本地跑测试确实也过了，但三个小时后，线上监控告诉我另一个函数被它顺手改没了。这种“单点能干、整体翻车”的体验，恐怕每一个重度用过 AI 编码助手的人都懂。于是当我看到 superpowers 这个项目在社区里被反复提起时，我的第一反应是：到底是什么东西，能让一群工程师愿意把 AI 工具的使用教程当“武功秘籍”来传？带着这个疑问，我前后用了差不多一周时间，把它在 Codex CLI 和 trae 工作台两条路上都跑了一遍。这篇文章不是官方文档翻译，而是我从“裸 Codex”切到“装上 superpowers 技能包”之后，对这件事的完整记录，包括安装路径、真实任务表现、三次踩坑闭环，以及我最后沉淀出的几条使用纪律。

1. 给 AI 配“外挂”之前，先认清裸 Codex 的真实短板：能答题，但交不了货

1.1 我印象最深的一次“完成式翻车”

事情发生在一个很普通的下午。我需要把一个 Python 服务里的 Redis 连接池从单例模式改成按租户隔离，改动量不大，但牵扯到十几个调用点。我当时的操作方式是直接把需求贴给 Codex：“把 redis_pool 改成按租户维度创建，所有 get_redis_connection 的调用都调整好。”它很快给出了一版完整的 diff，所有调用点确实都改了，我当时觉得效率真高，直接提交、合并、部署。

结果第二天早上，租户 A 的请求里混进了租户 B 的数据。原因并不复杂：Codex 在改get_redis_connection的时候，只改了函数的签名，但缓存 key 的拼接逻辑它没动，导致多个租户复用了同一个连接前缀。它把“签名层面的改动”完成了，却没有理解“按租户隔离”这件事的真正含义是数据隔离，而不是连接对象隔离。这种问题不是模型笨，而是任务定义和验证方式出了问题。我给了它一个动作指令，但没有给它一个完整的、包含约束和验收标准的任务描述。

1.2 工程化流程缺失，是 AI 编码最大的隐性成本

后来我把这类问题复盘了几次，发现一个共性：裸 Codex 适合回答“怎么改”，但不太擅长接手“一个完整的小型工程任务”。工程世界里真正可靠的工作流，是需求澄清、方案设计、任务拆分、测试先行、代码审查、回归验证这一整套链路。你让一个刚入职的实习生改代码，也会跟他说“先看上下文，再写测试，最后再提交”，但你把同样的话塞给 AI，它只会当成背景噪音，然后急着输出代码。

这就是 superpowers 想解决的原始问题。它不追求把模型换成另一个模型，也不追求一次性修掉所有代码生成错误，而是把工程师日常工作的流程、规范和验证方法，写成一套结构化的“技能文档”。当 AI 接到任务时，它不再直接生成代码，而是被引导着去经历一个完整的工程流程：理解问题、确认边界、写出失败测试、再动手实现、最后自查。听起来很基础，但对 AI 编码来说，这一步差了十万八千里。

我自己的体感是：裸 Codex 就像一个极聪明但极度缺乏耐心的外包工程师，你给什么指令它做什么，做完就交差，绝不主动多问一句；superpowers 的思路则是把“外包工程师”改造成“团队里的正式员工”，用一套流程文档让它先思考、再动手、自检后交付。如果你只在脚本里修一两个小 bug，这套流程确实显得笨重，可一旦面对真实业务里的跨文件改动、依赖升级、接口迁移，有没有这套流程，结果完全是两个质量级别。

2. 拆开 superpowers 的设计骨架：技能卡片、渐进披露与群体子代理

2.1 为什么是 Markdown：让 AI“读说明书”，而不是执行黑盒插件

我第一次看到 superpowers 的仓库结构时有点意外——它没有编译好的二进制，也不是一个需要安装的运行时，主体内容就是大量的 Markdown 文件。这些文件按领域分门别类，比如编码、协作、子代理、评审、依赖升级等，每个文件夹里都有类似SKILL.md这样的入口文件，里面写着这个技能的目标、触发条件、执行步骤、输入输出要求和注意事项。

这个设计最初让我觉得太“朴素”了，但用久了才理解它的聪明之处。AI 模型本身是基于文本推理的，你把流程写在代码里，它反而看不见；你把流程写在 Markdown 里，它读取上下文的时候就能直接“读到说明书”，并且按照说明书一步步执行。这相当于你面对一个持证但没经验的新人，与其塞给他一个复杂的内部系统，不如直接在工位上贴一张流程图，让他照着走。

而且 Markdown 对人类也友好。团队里任何一个人都能打开技能文档阅读、修改、补充，不需要懂插件开发，不需要编译部署。我后来把团队自己的代码规范、发布检查单也写成了同类文档，AI 读取的积极性和效果，比我之前在提示词里贴一大段规则好得多。原因不难理解：独立的技能文件意味着独立的上下文，AI 在需要时才去读，而不是在整个对话里背负着几千字规范，读到后面早就忘了前面。

2.2 渐进式披露：控制上下文膨胀的关键

继续说刚才那个点。如果你把一份 5000 字的工程规范直接写进系统提示词，模型不是读不懂，而是注意力会被稀释。它处理长文本时，天然会更关注前后两端的部分，藏在中间的规则很容易被忽略。superpowers 用的方式叫“渐进式披露”：平时只给 AI 一个技能目录索引，相当于告诉它“你手边有哪些说明书、分别讲什么”；等它接到具体任务，再按需去读取对应的完整文档。

打个比方：你入职一家新公司，HR 不会第一天就把全部制度手册塞给你，而是先给你一份员工手册目录；等你要报销了，才去翻报销流程那一章。AI 也是一样，任务如果是“给 API 写接口文档”，它只需要读文档生成相关的技能，不需要把“如何重构数据库迁移脚本”的完整流程也加载进上下文。这种机制既省 token，又提高了指令的命中率。

我实际观察 Codex 在加载技能后的行为时发现，它的思考过程会明显多出一些“中间步骤”，比如先输出“我找到了编码流程文档，先按计划阶段执行”，然后才开始拆解需求。这种变化不是模型变聪明了，而是它的工作记忆不再被无关规则占用，能更专注地执行当前最该做的事。

2.3 子代理与“群体模式”：并行协作的代价与收益

superpowers 里还有一类比较进阶的设计：子代理（subagent）和群体模式。简单说，当一个任务足够大时，主代理可以拆出多个子代理分别负责不同环节，比如一个子代理做代码实现，另一个子代理同时做代码评审，再有一个子代理专门跑测试验证。它们之间通过一种类似消息传递的方式交换结果，最后由主代理汇总。

这套机制听起来很酷，但它不是银弹。我自己的实际经验是：任务越复杂、拆分越清晰，群体模式的价值越大；但如果任务本身只涉及一个文件里的 50 行改动，强行走“多代理并行”，反而会带来额外的调度开销和上下文切换成本。后面我专门有一节会讲我踩到的一次多代理协同卡死问题，这里先给结论：子代理适合“并行评审”和“独立模块实现”，不适合“强依赖顺序的任务”。

3. Codex CLI 安装 superpowers 的完整实操：从目录规划到首次验证

3.1 安装前的三个前置判断

在动手之前，建议先做三个判断，能省掉后面很多麻烦。

第一，确认你的 Codex CLI 版本。superpowers 这类技能包对 CLI 的版本有一定要求，因为技能文件依赖模型读取项目文档的能力，太老的版本可能连自定义指令文件都不认。我的建议是用最新稳定版，别用 beta。

第二，想清楚技能包要装在哪里。装在当前项目目录，好处是只对当前项目生效，适合公司代码库有严格隔离要求的场景；装到用户级目录（比如~/.codex），好处是全局生效，所有项目都能用。我个人推荐先做全局安装，再在具体项目里按需覆盖，这样体验最平滑。

第三，确认你的模型上下文窗口够大。虽然 superpowers 用了渐进式披露，但技能索引和任务分析依然会占用一部分 token。如果你用的是小上下文窗口的模型，跑复杂任务时容易中途“失忆”。至少要用中高端模型，并且把单次任务控制在合理范围内。

3.2 落地目录与 AGENTS.md 钩子的配置

安装本身不复杂，核心是把技能包克隆到本地，然后让 Codex 知道它存在。我当时采用的目录结构大致是这样：

~/.codex/ ├── AGENTS.md └── superpowers/ ├── skills/ │ ├── coding/ │ │ ├── plan-first/ │ │ │ └── SKILL.md │ │ └── test-before/ │ │ ├── SKILL.md │ │ └── examples/ └── README.md

先说 AGENTS.md 这个文件，它是 Codex 读取的全局指令入口。我之前一直忽略它的价值，直到这次才意识到，它就是连接项目与技能包的“钩子”。我在~/.codex/AGENTS.md里写的是这样一段话：

本环境已启用 superpowers 技能包。 技能包根目录：~/.codex/superpowers。 执行任何编码任务前，请先查看 skills/coding 下的相关流程文档； 涉及协作或评审时，请查看 skills/agency 下的子代理说明。

这段话的作用不是让 AI 把所有技能都读一遍，而是给它一个“起始索引”。它看到 AGENTS.md 之后，会知道有这么一个技能包存在，以及触发什么条件时该去翻哪份文档。这一步做对了，后面任务执行才会出现“先规划、再动手”的行为变化。

3.3 用一条包含验收标准的最小任务做验证

装完之后别急着上大任务，先跑一个最小的验证任务。我的经验是，这个任务不能是“写一个 hello world”，因为 hello world 根本触发不了任何工程流程。也不要一开始就让它重构整个模块，因为一旦翻车，你很难判断是技能没加载还是任务本身的问题。

我当时用的验证任务是：“在项目里新增一个带单元测试的 URL 解析工具函数，输入为 URL 字符串，输出为协议、域名、路径三个字段的字典，要求包含异常处理。”这个任务足够小，但包含实现、测试、异常处理三个环节，能逼着 AI 走一遍完整流程。验证时重点观察两点：第一，AI 在写代码前有没有输出“读取技能文档”或“按计划执行”之类的中间说明；第二，AI 有没有主动写测试，而不只是实现功能。如果这两点都出现，说明技能包已经生效。

3.4 已验证的常见安装陷阱

安装过程中最容易翻车的三个点，我提前说一下。

一是路径写错。很多人喜欢把技能包放到带空格的目录，比如D:\My Files\superpowers，结果 AI 读取时路径解析失败。官方文档当然支持转义，但何必给自己添堵呢，路径里不要有空格和中文字符。

二是 AGENTS.md 命名不匹配。Codex 认的是AGENTS.md，Claude Code 认的是CLAUDE.md，如果你在多个工具之间共用技能包，一定要确认该建哪个文件。我一开始在 Codex 的全局目录里放了CLAUDE.md，结果 Codex 完全没反应，排查了半小时才发现是文件名不对。

三是版本回退。有些技能包更新后依赖了新的 AGENTS.md 写法，但你的 Codex CLI 版本没跟上，导致钩子失效。所以每次拉取新的技能包之前，顺手把 CLI 也更新一下，能省不少事。

4. 把 superpowers 接进 trae 工作台：另一个 AI 工具的集成思路

4.1 trae 工作台为什么需要同样的技能机制

如果你用过 trae 工作台就知道，它本质上是一个把 IDE、AI 助手、自动化任务编排在一起的开发环境。它的 AI 能力和 Codex 类似，同样面临“会答问题但不会主动走工程流程”的问题。社区里常见的热搜词“trae work cn 安装 superpowers skill”，说的就是用户想在这个工作台里也装上同一套技能机制，让 AI 从“随手生成代码”变成“按流程完成任务”。

我的观点是，这个需求很合理。技能包的核心价值不绑定某个特定 CLI，它只是一堆 Markdown 流程文档，任何支持指令文件读取的 AI 工具都能复用。trae 工作台只要能让 AI 读取项目级或用户级的说明文件，就等于具备接入 superpowers 的基础条件。

4.2 集成方案对比与推荐路径

我在 trae 工作台里尝试过两种接入方式，简单对比一下。

第一种是把技能包克隆到项目目录里，然后在项目的指令文件里写钩子。优点是隔离性好，这个项目单独引入技能包，不会影响其他项目；缺点是你得在每个想用的项目里重复配置，养成习惯之后还行，但初期的复制粘贴成本比较高。

第二种是在工作台的用户级配置目录里放一份全局技能包，然后在全局指令文件里声明钩子。优点是一次配置、处处生效，所有在 trae 工作台开的项目都能自动享受到流程约束；缺点是如果你同时维护好几个差异很大的项目，通用的技能规则偶尔会显得不够贴切。

我最终采用的是第二种，但在具体项目里用项目的指令文件覆盖了部分规则。举个例子，全局技能包默认要求所有代码改动必须配测试，但工具链项目里有一些一次性脚本，本来就不需要长期维护的测试用例，这时候我会在项目指令文件里补充一条豁免说明，让 AI 识别到“该目录为 scripts 工具目录，不做强制测试要求”。这样既保留了流程约束的通用性，又不会因为规则太死板而影响效率。

4.3 双工具共用技能库的同步问题

还有一个很实际的问题：如果你同时使用 Codex CLI 和 trae 工作台，技能包是各放一份，还是共用一份？

我建议共用一份，但要解决同步问题。最简单的方式是把技能包放在一个独立目录，比如~/dev/superpowers，然后在 Codex 的~/.codex/AGENTS.md和 trae 工作台的全局指令文件里，都引用这个绝对路径。这样你更新一次技能包，两个工具都能用到最新版本，不会出现“Codex 里已经改了流程，trae 里还是旧规则”的错位。

不过要注意，共用路径有个前提：两个工具运行时的用户权限一致。如果你在 trae 工作台里用的服务账号和命令行用户不是同一个，可能因为权限读不到技能文件。我自己就遇到过 trae 工作台因为沙箱权限问题，读不到用户主目录下的技能包，最后只能把技能包再复制一份到项目目录里。

5. 实测记录：让我处理的三件真实任务，superpowers 把过程改成了什么样

5.1 任务一：重构一份 400 行 Python 数据处理脚本

我挑了一个真实的历史包袱：一份 400 行的 Python 脚本，主要功能是清洗导入的 Excel 数据，逻辑里塞了大量 if-else，变量命名混乱，还有两处明显的重复代码段。以前这种任务我是不敢全权交给裸 Codex 的，因为它很可能只做表面重构，把行数缩下去，但语义改成另一套行为。

在用 superpowers 之后，它的处理路径明显不同。它先输出了一段“任务分析与技术方案”，拆出了三个子任务：数据清洗逻辑抽取、重复代码合并、错误处理统一。然后它没有直接动手，而是先写了一个用来验证行为等价的最小测试集，再开始重构。最终输出的代码量虽然没有大幅缩减，但结构清晰了很多，而且测试全绿。这个过程中最让我满意的地方是，它没有自作主张改变任何对外行为，所有的重构都是在我确认了“行为保持一致”的目标下进行的。

5.2 任务二：跨端新增会员积分查询接口

第二个任务更接近日常业务开发：在已有的 Web 服务里新增一个会员积分查询接口，同时需要改前端页面把积分展示出来。这个过程涉及后端路由、数据库查询、前端 API 调用、页面渲染四个环节，任何一环漏掉，功能都交付不了。

裸 Codex 遇到这类任务时，容易出现“后端写得完整，前端调用模块忘了改”，或者反过来。superpowers 的流程化处理在这里起了作用。我观察到的执行顺序是：先列接口设计，再确认数据库字段，然后同时拆出后端实现、前端联调、测试验证三个子任务，最后汇总成一份改动清单。整个过程中间它甚至还自己停下来，问我积分字段在旧表里叫point还是points，这种主动澄清在之前很少见。

5.3 任务三：升级依赖并处理破坏性变更

第三个任务是最折磨人的：把一个内部 SDK 从 2.x 升级到 3.x，其中有两个公开方法改了签名，一个配置项被移除。这类任务最怕 AI 直接全局搜索替换，然后留下一堆编译错误。

用 superpowers 跑下来的流程是：先读取依赖升级相关的技能文档，了解推荐的逐步升级策略；然后列出所有调用点；接着逐个评估签名变更影响；最后才修改代码并运行测试。虽然整体耗时比裸 Codex 直接干要长，但几乎没有返工，一次通过。这个对比让我彻底接受了“慢一点但不出错”的理念。

5.4 耗时、token 与返工次数对照

我简单做了一个不严谨的对比记录，数据仅供感受趋势：

看出来了吗？时间变长了，token 消耗变多了，但返工次数大幅下降。在业务代码里，“返工”的代价远远不止时间成本，还包括你从上下文里重新捡回思路、重新定位问题、重新部署验证的整个过程。所以我后来对团队的判断标准很简单：如果你更在意最终交付质量，而不是聊天框里那几秒钟的“首 token 延迟”，superpowers 带来的稳定性是值得的。

6. 三次翻车的排查链路：装上了不代表就生效

6.1 故障一：技能被完全无视，AI 依然裸奔

第一次跑任务时，我全程盯着输出，期望看到“读取技能文档”之类的迹象，结果什么都没有。它直接开始写代码，行为跟没装技能包时一模一样。我第一反应是 AGENTS.md 没被读取，于是按这个方向排查。

我先确认了 AGENTS.md 文件的位置和命名，没问题。然后又检查了文件内容里有没有写错路径，也没问题。最后我尝试在对话里直接问 AI：“我们的环境里配置了哪些技能文档？”，它的回答暴露了真相——它根本没读取到那个全局配置。进一步排查后发现，Codex 的全局指令文件在最新版里改名为AGENTS.md，但我之前创建的是旧格式文件.codex/instructions.md，两者完全没有被合并。删掉旧文件、重建正确命名的文件之后，问题才解决。

6.2 故障二：技能文档和项目实际约束互踩

第二次翻车更有意思。superpowers 的流程文档里明确要求“所有外部依赖必须有版本锁定”，但我手上那个项目是个历史遗留系统，好几个依赖一直没锁版本，当前跑通纯靠运气。AI 严格执行了技能文档，准备把一整套依赖规范化，这完全偏离了我的交付目标。

这一下让我意识到，技能包是通用规则，不等于每个项目的现实约束。解决方式是我在项目指令文件里加了一段覆盖声明：“本项目为遗留系统，暂不执行依赖版本锁定规则，相关问题需先向项目负责人确认。”AI 在下一次执行时先查看了项目指令，优先采用了项目级规则，绕开了技能包里的默认约束。这件事给我的经验是：技能包给 AI 的是一套“最佳实践”，但你必须在项目层给 AI 留一个“例外出口”，否则它会一本正经地给你制造大量新问题。

6.3 故障三：多代理协同卡死，反馈延迟拖出了天际

第三次踩坑发生在子代理模式。我给一个中型任务开了多代理并行，预期是主代理拆分任务后，子代理同时工作，最后并行汇总。但实际跑起来的时候，主代理一直在等待一个子代理的返回，而那个子代理又因为要依赖另一个子代理的输出而阻塞了，形成了一个循环等待。

我盯着终端看了快十分钟，进度条一动不动，最后只能强制中断，改用单代理模式重新跑，十几分钟就搞定了。经验教训是：多代理并行适合“任务可以真正独立拆分”的场景，一旦子任务之间存在依赖关系，就必须在主代理层面明确执行顺序，否则协作本身会成为瓶颈。我后来在技能文档里加了一条规定：使用多代理模式之前，必须先判断子任务之间是否存在依赖关系，存在则串行执行。

7. 高阶玩法与我的日常使用纪律：把技能包用成团队规范

7.1 第一课：给任务写“需求文档”，而不是“动作清单”

很多人在用 AI 编码工具时习惯下指令：“把某处的函数名改成 XX”“给某接口加一个参数”。这种动作清单式的指令，只会让 AI 变成高级补全工具。superpowers 的完整流程只有在任务描述足够清晰的时候才能发挥最大价值。我现在的习惯是给 AI 一个目标、几个约束、一组验收标准，而不是具体动作。

比如我会写：“目标是让会员积分在订单详情页可见；约束是不改动现有订单接口的返回结构；验收标准是前端能拿到积分字段并在页面展示。”剩下的方案设计、代码实现、测试覆盖，由 AI 在技能流程的引导下自己完成。这个转变是我这一周最大的心得，也是技能包真正“生效”的前提。

7.2 第二课：沉淀自己的私有技能卡

用习惯了之后，我不再满足于 superpowers 自带的那套通用技能，开始把团队内部的高频操作也写成技能卡。比如我们有一个固定的发版流程，涉及版本号更新、构建产物校验、发布说明生成，以前每次都是人工提醒；现在我把完整流程写成了技能文档，放进技能包，AI 接到“发版”类任务时就会自动按流程执行。

这种自定义技能卡的价值在于，它把团队的隐性知识显性化了。任何一个新成员加入，不需要有人口口相传，AI 就已经懂了一半规矩。就算哪一天不依赖 AI 了，这套文档本身也是一份很好的团队知识库。

7.3 第三课：学会给 AI 卸担子，关闭完整流程

最后说点反直觉的。superpowers 不是所有场景下都应该开着的。如果是“帮我解释一下这段正则是什么意思”，或者“这段代码里有没有明显的内存泄漏”，这类问答型任务走完整流程既浪费 token，也没必要。我现在的做法是给技能包加了一个轻量模式：遇到明显属于“解释、问答、单点分析”类的请求，AI 直接回答，不触发冗长的任务规划。

这个轻量模式是我自己在技能文档里加的约束，效果是日常问答响应更快，同时涉及“改动代码”“跨文件修改”“依赖升级”这些触碰真实生产逻辑的任务时，流程照旧。让 AI 知道什么时候该走流程、什么时候该直接回答，才算是把技能包真正用熟了。

我在实际项目里最后留下的配置其实非常简单：一份全局 AGENTS.md、一份按需读取的技能目录、再加上来自项目层的少数例外规则。真正改变 AI 行为的，不是文档数量，而是你愿意让它在动手前多想几步。装完 superpowers 后第一次运行复杂任务，看到它在写代码之前先停下来列方案，你可能会觉得不习惯，甚至觉得它变慢了。但经历过几次“它能一次性交付，而不需要你在后面跟着擦屁股”之后，你就明白这种停顿感才是高质量的来源。