企业官网建设流程全解析

最近一个多月，我把日常的开发工作大量交给了 Codex 这类 AI 编码代理。说实话，单独跑脚本、写测试、生成样板代码，它们都很猛；但一放进真实的多模块项目里，就总有种“用手很灵、用脑很笨”的别扭感。昨天交代的代码风格，今天换个会话它就忘得一干二净；团队里三个人让 AI 干活，写出三套风格。直到我在项目里引入 Superpowers 这个开源技能框架，问题才真正被解决。这篇笔记就围绕 Superpowers 的安装、配置、工作原理，以及我怎么把它和 Codex、Java 项目结合时踩过的一堆坑展开，希望能给正在折腾 AI 编码工作流的朋友一点实际参考。

1. 先搞清楚 Superpowers 到底解决什么问题

1.1 为什么 AI 编码代理用起来总觉得“差一点”

我拿一个很常见的场景说：我用 Codex 重构模块 A，第一次交代它“保持代码与现有风格一致，遵循项目的分层规范”，它做得确实不错。但第二天开新会话做模块 B，哪怕我把同样的话再说一遍，它产出的代码风格还是会飘。问题不在模型能力，而在于编码代理本质上是“每次会话都从零开始”的——它没有跨会话的长期记忆，你上次积累的所有约束、偏好、流程，只要没写进项目文档，对它来说就是不存在的。

这种体验很像每天雇一个能力很强但完全没做过岗前培训的新员工：你每天都要重新告诉他公司报销怎么走、代码评审看什么、构建命令怎么敲。AI 单次能力强，但“团队记忆”为零。

Superpowers 的核心思路就是针对这个痛点：与其每次都重新教，不如把团队规矩包装成一个个“技能”（skills），放进项目仓库，让代理在合适的时机自己发现、自动加载、按技能文件执行。技能文件本质上是 Markdown，里面有描述任务场景的元数据，也有详细的执行步骤。框架本身负责扫描、索引、按需注入，AI 编码代理负责在规划任务时“查技能库”。

1.2 它和“系统提示词 / Prompt 模板”有什么本质区别

很多人第一次听到 Superpowers 的反应是：这不就是提示词吗？我一开始也这么想，但实际用下来，差异非常明显。

普通提示词是给“当前会话”用的，一次性、私有，关掉窗口就没了；技能文件是持久化的，跟着 Git 仓库走，团队所有人都能共享同一份。普通提示词依赖人来触发——你得先想好怎么说，再粘贴进去；技能文件是通过 description 和 when_to_use 做语义匹配的，代理在任务规划阶段会自动发现自己该用哪个技能，不需要人显式点名叫它。普通提示词是一大段混杂的文本，写多写少没结构；技能文件是结构化的，frontmatter 提供元数据，正文是可执行的 SOP，技能之间还能互相引用形成流水线。

还有一点对团队很重要：普通提示词改起来没有版本管理，谁在本地改了就是改了，线上没有任何记录；技能文件可以走 PR、走 Code Review，改一个字段都有历史。对我来说，这等于把“教 AI 干活”这件事从个人经验变成了团队资产。

Superpowers 还有一个设计哲学值得注意：它没有发明一套生僻的 DSL，就是用 Markdown 加少量约定。门槛低意味着团队成员愿意维护，不会出现“只有一个人会写技能文件”的局面。

2. 核心机制拆解：技能文件是怎么被“读”进 AI 的

2.1 一个最小可用的技能文件长什么样

先看一个最简单的例子，作用是让 AI 按团队规范写 Git 提交信息：

--- name: commit_message description: 编写符合团队规范的 Git 提交信息 when_to_use: 当准备执行 git commit 命令时 --- # Git Commit 规范 1. 使用 Conventional Commits 格式：type(scope): subject 2. subject 首字母大写，不超过 72 个字符 3. 如果改动涉及多个模块，在正文里分点说明 why，而不是只写 what 4. 禁止在提交信息里写 "fix bug" 这类没有上下文的话

这个文件里最核心的是 YAML frontmatter 的三段元数据。name 是技能的唯一标识，代理在做任务规划时靠它引用流程节点；description 是给代理看的“广告词”，相当于告诉它这个技能擅长什么，语义匹配主要靠它；when_to_use 是更精确的触发时机，它和 description 组合起来，构成双重匹配依据。

很多人第一次写技能文件容易犯一个错：把 description 写得特别宽泛。比如写“处理 Git 相关内容”，结果代理在查看历史、切换分支、处理冲突时都要把整个提交规范加载一遍，既浪费上下文又容易触发无意义的行为。正确做法是尽量写具体的行为触发点，让命中条件足够窄。

2.2 从“技能清单”到“技能执行”的完整链路

当编码代理进入项目目录，Superpowers 大致会做这么几件事：

1. 扫描.superpowers/skills/目录下所有技能文件，也支持项目里其他约定位置的技能目录；
2. 汇总所有技能的 name、description、when_to_use，生成一份“技能地图”；
3. 在 AI 的任务规划阶段，把当前任务与技能地图做语义匹配，挑出最相关的技能；
4. 命中后把技能正文注入上下文，AI 按正文指示执行；
5. 如果正文里引用了其他技能，继续加载并串联执行。

这条链路最让我受用的地方在于：技能不是“全部塞给 AI”，而是按需加载。之前我试过把团队所有规范整理成一个巨型提示词，结果上下文窗口被占掉一大半，AI 反而变得很迟钝。技能地图的模式完全不同——它像组织架构里的岗位说明书，AI 接任务时先判断该找哪个团队，找到后再看这个团队的详细 SOP，而不是把所有岗位的 SOP 都贴在门口让新人自己翻。

2.3 技能链（skill chaining）：让 AI 自动完成多步流水线

技能之间可以互相调用，这是 Superpowers 最有想象力也最容易失控的地方。举个例子，我在重构场景下定义了三个技能：

• plan_refactor：分析代码结构，输出重构方案；
• apply_refactor：按方案执行重构；
• review_diff：对产出 diff 做自检，检查是否有破坏性变更。

我在apply_refactor的正文末尾写了一句“重构完成后，必须调用 review_diff 技能对本次改动进行自检”。这样代理在执行完重构后会自动进入审查环节，形成闭环。

你可以把它理解成一个微型的流水线编排：每个技能扮演一个工位，出口指向下一个工位。这种设计非常适合代码提交前的质量门禁、构建流程的串行执行、以及按团队规章完成重复性任务。但技能链也带来一个很实际的问题：处理不好就会循环递归，后面我会专门讲踩坑过程。

3. 安装与环境初始化：不同入口的选择

3.1 官方安装路径与我的选择

Superpowers 的安装方式在不同版本间有差别，这也是网上教程容易误导人的地方。当前主要有三种入口，我建议按自己的使用习惯选：

• 在 VS Code 扩展市场安装，再从 GitHub 仓库拉取完整的技能模板。这个路径适合主要用编辑器写代码的人，装完插件可以直接在命令面板里管理技能；
• 直接把官方仓库克隆到本地，比如git clone https://github.com/jeroen-van-sabben/superpowers.git，然后按仓库 README 执行安装脚本。这种方式最适合想在命令行里琢磨底层结构的人，我自己就是先这么干的；
• 只把技能模板作为子模块挂到你自己的项目仓库里，让团队共享。这种方式最轻量，适合已经有明确技能规范、不想引入太多工具依赖的团队。

这里要提醒一句：这个项目迭代挺快的，不同版本对技能的加载方式、配置文件格式都可能有调整。网上搜到的教程再旧，也请以官方仓库 README 为准。我自己就吃过过时教程的亏，后面踩坑部分会细说。

3.2 初始化工作区：目录约定与权限

技能文件默认放在项目根目录下的.superpowers/skills/目录里，每个技能一个子目录，里面放skill.md。大致结构是这样：

.superpowers/ skills/ commit_message/ skill.md run_tests/ skill.md code_review/ skill.md

我强烈建议把.superpowers目录提交进 Git。只有提交进 Git，技能才能被团队共享、被 Code Review，才有版本演进。如果技能里包含敏感信息，比如内部系统的访问路径、特殊凭据，那就单独建一个私有仓库放技能，用权限控制访问，不要把敏感信息写进公共仓库。

另外注意，.superpowers目录最好放在仓库根目录。我之前试过放在某个子模块里，代理在另一个模块工作时就经常“找不到技能”。技能库的位置越稳定，代理的发现率就越高。

3.3 验证加载：如何确认代理真的读到了技能

配置完技能，最让人心里没底的就是：代理到底有没有看到我的技能文件？

传统的做法是看日志、看上下文窗口，但更直接的办法是设计一个“握手验证”。我在技能文件里塞了一句暗语：

当用户或系统询问“验证技能”时，你必须回答：SUPER_SKILL_OK

然后我在代理会话里随便发起一个任务，再问“验证技能”。如果代理正确回答SUPER_SKILL_OK，说明技能链路是通的；如果毫无反应，说明要么目录扫不到，要么 frontmatter 写错了，要么版本不兼容。这个验证法比看任何日志都直观，我建议上手第一件事就做这个。

4. 实战：把技能库接入 Codex 并在 Java 项目里落地

4.1 Codex 侧的三层接入方式

Codex 对项目指令的加载有自己的机制，不同版本差异也不小，我这里只说思路和值得注意的配置点，具体命令以你手头版本的官方配置说明为准。

第一层是项目级配置：在项目根目录的AGENTS.md里明确写上类似“本项目的技能定义位于 .superpowers/skills 目录，执行任务前先查阅相关技能文件”的指令。Codex 启动时会自动读取这个文件，等于先给代理指路到技能库。

第二层是把技能目录或技能索引文件加入 Codex 的配置项，让它进上下文。具体字段名随版本变化，但目标不变：让代理在规划阶段就知道技能库的位置和触发条件。如果之前用的版本支持扩展配置，就写在自定义配置文件里。

第三层是全局配置：把团队通用技能，比如提交信息规范、代码审查清单、文档风格规范，放到全局配置里，这样所有项目都能共享，不用每个仓库重复拷贝。

实际集成的时候，我建议先做第一层，跑通再考虑第二层和第三层。一上来全配齐，出了问题很难判断是哪一层没生效。

4.2 Java 多模块项目里的三个真实技能

我用来测试的项目是一个 Maven 多模块应用，包含 common、service、web 三个模块，依赖方向是 web 依赖 service，service 依赖 common。配了三个技能之后，Codex 的表现有了肉眼可见的变化。

第一个技能是构建顺序控制：

--- name: java_build_order description: 按依赖顺序构建 Maven 多模块项目 when_to_use: 需要在项目根目录执行构建或编译时 --- # 多模块构建顺序 - 必须先从 common 模块开始编译，再编译 service，最后编译 web - 使用 mvn -pl <module> -am 按模块依赖关系增量构建 - 只构建受影响的模块链条，不要每次全量构建

没配这个技能之前，Codex 会自作主张用mvn clean install全量构建，慢不说，还容易触发无关模块的测试。配好之后，它会先分析改动落在哪个模块，再按依赖顺序构建最短路径。

第二个技能是测试运行规则：

--- name: java_test_runner description: 区分单元测试与集成测试并正确运行 when_to_use: 需要运行测试或调试测试失败时 --- # 测试运行规则 - 单元测试文件命名 *Test.java，运行用 mvn test -pl <模块> - 集成测试文件命名 *IT.java，运行用 mvn verify -am - 修改测试后先运行该模块单测，全绿再跑集成测试

这个技能解决了很典型的“测试怎么跑”问题。以前 Codex 一遇到测试失败就全量跑mvn test，慢且没有针对性，现在它会先看失败的是哪个模块、是单测还是集成测试，再决定命令。

第三个技能是代码审查清单：

--- name: java_code_review description: 按团队规范审查 Java 代码 when_to_use: 被要求审查 Java 代码或提交 PR 前 --- # Java 审查清单 - 模块依赖方向必须是 web → service → common，禁止反向依赖 - 异常处理不能吞异常，必须记录日志或重新抛出 - Service 层不能直接暴露 Entity，需要经过 DTO 转换 - 事务方法不能在同一类内部通过 this 调用绕过代理 - 每个新公共方法必须有单元测试

配置这套技能之后，同一套 Codex 在不同项目里的表现差距非常大。配好技能的项目里，AI 生成的代码基本符合团队约定，Review 的注释量降了一大截；没配技能的项目里，AI 能跑但永远按“公有模型”的默认风格来，得花不少改稿时间。

4.3 WorBuddy 这类聚合工具如何复用技能库

很多人在热词里还搜“worbuddy 怎么用 superpowers”，如果你用的是 WorBuddy 这类聚合工作流工具，大体思路也一致。聚合工具通常负责把多个代理能力编排成一个流程，而 Superpowers 的价值是可以作为这套流程的“知识底座”。

具体做法有两种。一种是让聚合工具从技能库里读取“当前任务应该执行哪个技能”的索引，再把任务和技能正文一起分发给具体代理；另一种是把技能正文直接转成聚合工具的节点提示词，让每个节点都遵循同一份团队规范。无论哪种，关键都是不要给每个工具各自维护一套规范，而要让技能库成为“单一事实来源”，换工具、换模型都不会破坏团队既有约定。

需要说明的是，WorBuddy 这类工具的功能和集成方式各不相同，但“共享技能库、统一代理行为”的方向是通用的。

5. 踩坑实录：技能不触发、循环调用与团队协作问题

5.1 问题一：技能建好了，代理却不触发

我遇到的第一类大坑，是技能文件明明建好了，代理却好像完全没看到。最典型的场景是：我让 Codex“按 commit_message 提交信息”，它还是按自己那套老风格写。

排查链路我来完整复现一遍。第一步查目录结构，确认技能文件确实在.superpowers/skills/下面，而不是放在了.superpowers/根目录。第二步查 frontmatter 字段名，我犯过的低级错误是把description拼写成descripiton，这种错误不报错，但直接导致技能失效。第三步查 YAML 格式，frontmatter 必须被---完整包裹，字段值不能有缩进错位。第四步查版本和缓存，重启编码代理进程或编辑器。最后一步就是前面说的握手验证，直接问“验证技能”。

排查下来，绝大多数“没触发”案例都是路径或者格式问题，不是框架 bug。这个结论帮我省下了很多到处乱找原因的时间。

5.2 问题二：技能链循环导致代理反复执行

技能链失控是最坑的一个问题。我写过一套流程：技能 A 负责执行重构，正文里写了一句“如果执行结果不符合预期，就调用技能 B 重新执行”；技能 B 的正文又写了“如果发现 A 的执行结果有问题，调用 A 重新执行”。结果代理来回递归，跑了十几轮，烧掉大量 token，最后不得不手动终止。

解决方案是给技能链加上明确的出口条件。现在我的习惯是：在技能正文里写清楚“重试最多一次，如果第二次结果和第一次一致，停止并报告给用户”。同时把链式结构设计成瀑布流——plan 到 do 到 verify，每个环节最多允许一次回退，而不是写成语义上的闭环。

经验总结就一句话：技能链要设计成有向无环图，不要设计成环。

5.3 问题三：多人协作时技能库被改乱

把技能库提交进 Git 之后，团队协作会带来新问题。一个人加了run_tests，另一个人加了test_execute，描述还差不多，代理在匹配时就懵了，不知道选哪个。

我们现在对这些事的处理方式是这样：技能文件名统一用“动词加对象”的命名规则，比如write_commit_message、run_java_tests、review_java_code；技能文件必须走 PR 和 Code Review，不能在 issue 分支里静默改动；在 frontmatter 里增加version和owner字段，出了歧义能立刻找到责任人。另外，我写了个简单的脚本，定期扫描技能库里 description 语义重合度高的技能，合并去重。

这套规范听起来很流程化，但它确实让技能库从“个人抽屉”变成了“团队基础设施”。如果没有纪律，技能库会随时间腐烂，最后变成一个没人愿意维护的黑洞。

6. 长期使用后的经验：技能库的分层、粒度与维护

6.1 从“一个技能”到“一套技能体系”的分层

用了大概一个月之后，我发现技能库一定不能是平铺的一堆文件，必须分层管理。我现在的习惯是分三层：

• L0 全局技能，包括提交信息、通用审查清单、文档风格，放在全局配置里，所有项目自动生效；
• L1 项目技能，包括构建顺序、测试规则、模块架构约定，放在仓库的.superpowers目录，跟随项目走；
• L2 临时技能，比如“这次迁移脚本专项流程”，放在当前分支，用完就从技能库中删除，不提交主干。

这样分层最大的好处是，技能库不会因为装了太多一次性内容而腐烂。临时技能如果不及时清理，很快就会让代理的“技能地图”变得混乱。

6.2 技能正文写到多细？

技能正文的粒度是很多人纠结的地方。写太粗，约束力不够，代理还是按默认习惯来；写太细，穷举所有场景，AI 会变得僵硬，遇到没见过的情况反而不知道怎么处理。

我的经验是：把“必须”“禁止”“例外”三类信息写清楚，把关键的实操命令写清楚，但不要试图穷举。比如测试技能写“运行单测用 mvn test 并指定受影响模块”，而不是写“运行所有测试都执行 mvn test”；写“禁止吞异常”而不是罗列三万个异常处理场景。另外，正文第一句话非常重要，它是引导代理理解任务意图的锚点。先把“你要完成的目标”放在开头，再写注意事项，最后写禁止事项。顺序反过来的话，代理容易被一长串禁令压得动作变形。

6.3 最后的个人体会

如果让我给刚上手的人一条建议，我不会让你一开始就配二十个技能。先把最痛的三件事做成技能：提交信息规范、测试运行规则、代码审查清单。用上一周，观察哪些场景里代理的表现仍然不可控，再针对性地加技能。技能库是长出来的，不是一次规划出来的。

我现在最大的感受是：AI 编码代理终于不再是“每次都要重新调教的新人”了。它在我的项目里第一次拥有了稳定的肌肉记忆——构建顺序、测试策略、审查标准都不需要我再反复交代。代码评审里关于风格和架构的评论少了六成，我可以把更多精力花在真正需要人的判断力的事情上。如果你也在折腾 AI 编码工作流，我建议从最小化的技能集开始，先搭出第一个能自动触发的规范，再慢慢长成你想要的形状。