企业官网建设流程全解析

最近在折腾 Codex CLI 的时候，我把一套叫 superpowers 的开源技能包接到了工作流里，结果整个项目的推进方式发生了明显变化。以前让 AI 编程代理干活，总有一种“碰运气”的感觉——同一个问题，它今天这么修，明天那么改，有时候一次过，有时候绕一大圈。装上 superpowers 之后，最直观的感受是：代理不再靠临场发挥办事，而是像团队里一位有章法的工程师，按流程拆解任务、按步骤执行、按约定交付。这篇文章就围绕 superpowers 到底是什么、它怎么改变 AI 编程的协作方式、如何在 Codex 环境里安装配置，以及 Java 项目里怎么落地这套技能体系展开。不管你是刚接触编程代理的新手，还是已经在用 Codex、Claude Code 这类工具的资深开发，这篇文章都能给你一套可以直接抄作业的实操路径。

1. 为什么 AI 编程代理需要“技能包”，而不是靠一次性提示词硬问

1.1 一次提示词驱动模式的崩溃现场

先说一个真实场景。我之前让 Codex 去“修复某个 Java 模块的编译错误”，任务看似简单，但它第一次直接打开报错文件改了几行，结果引入了新错误；第二次它换了一种思路，把整个方法重写了，虽然能编译，但破坏了已有逻辑；第三次我不得不把完整的报错日志贴进提示词里，它才勉强收敛。问题就在于，AI 代理本质上是一个大模型驱动的执行者，它的“行为方式”完全取决于当前上下文里装载了什么信息。你在提示词里塞得越多，它表现得越好；但每次重新对话，这些信息几乎都要重来一遍。项目一旦复杂起来，靠“一次性填空”式的提示词驱动，根本无法保证稳定输出。

1.2 技能包的本质：像菜谱一样组织代理的做事方法

superpowers 解决的就是“稳定复现优秀行为”这件事。它的核心思路特别朴素：把代理做某类任务的步骤、约束、检查点，沉淀成一份份结构化的 Markdown 文件，我习惯叫它们“技能”。每个技能就像一张菜谱——上面写清楚这道菜需要什么食材、什么锅具、先做什么后做什么、出锅前怎么判断熟没熟。代理接到任务后，不是凭空发挥，而是先去“技能库”里找对应的菜谱，然后严格按照菜谱执行。

这种方法最大的价值是把“知识”从“上下文”里剥离出来。知识存放在独立文件里，不随对话消失，不占提示词配额，还能被多个任务、多个代理反复引用。你可以在技能库里放一个“修复 Java 编译错误”的技能，里面写明：先跑 mvn compile 抓取完整错误信息，再逐个定位出错文件，修改后重新编译确认，最后跑一遍相关单元测试。之后你再让代理修复编译问题，它就会自动检索并调用这个技能，而不是像第一次那样乱撞。

1.3 superpowers 的整体定位：让代理拥有自学习能力

这里要说明一点：superpowers 并不只是一个静态的提示词集合，它本质上是一套“代理技能框架”。它给代理定义了怎么理解技能文件、怎么匹配技能、怎么按步骤执行、怎么在任务中途发现技能不足时自己补写新技能。这套机制最关键的一点是“代理可以自己创建技能”。举个例子，代理在修改某个旧代码时，发现项目里有一套特殊的构建流程，它可以在完成修改后顺手把这个流程记录成一个新技能，下次遇到同类项目就能直接调用。说白了，superpowers 不仅给了代理鱼，还教会了它怎么结网、怎么保存猎物。

1.4 我最终选择这套方案的核心原因

市面上类似的方案其实有不少，有人喜欢把各种提示词写进系统提示里，有人用自定义的 CLI 工具封装固定流程。我最终选择 superpowers 这条路，原因是它有几个别人给不了的好处。

第一，技能文件不占用对话上下文。如果你把一套完整的工作规范塞进 system prompt，几十次对话之后，上下文窗口大概率会被撑爆。但技能文件是外挂的，代理只在需要时读取相关内容，日常对话里不需要一直挂在嘴边。

第二，技能可以版本化管理。一组技能就是一个目录，里面全是文本文件，天然适合 Git 管理。团队里谁改了技能、改了哪一步、为什么改，都能留痕。

第三，多代理可以共用同一套技能库。Codex、Claude Code 这类工具读的是同一套 Markdown 技能，只要格式约定一致，理论上你可以在不同工具之间无缝迁移工作习惯，不用为每个工具重写一套提示词。

2. 核心细节解析与技能文件实操要点

2.1 技能库的目录结构到底怎么摆

第一次接触 superpowers 的人，最容易在目录结构上犯迷糊。这里放一个我实际在用的技能库布局：

superpowers/ ├── AGENTS.md ├── skills/ │ ├── create-skill.md │ ├── improve-skill.md │ ├── reflect-on-work.md │ ├── java/ │ │ ├── compile-fix.md │ │ ├── test-isolation.md │ │ └── module-scan.md │ └── general/ │ ├── code-review.md │ └── commit-message.md └── plans/ └── current-plan.md

AGENTS.md 是整个技能库的“总入口”，代理启动时先读这个文件，了解自己拥有的能力和工具；skills 目录里按领域分子目录，每个技能一个 Markdown 文件；plans 目录用来存放当前任务的执行计划，代理会在开始工作前先写一份计划，然后逐步完成并勾选。这个结构看起来简单，但每个部分都有明确的作用。

AGENTS.md 文件的内容不需要特别长，我一般会写清三件事：代理在处理任务时可以使用的“技能索引”、代理在任务开始前需要做什么准备（比如先读项目结构）、代理在完成每个子任务后应该如何更新计划文件。记住，AGENTS.md 是给代理看的导航页，不是让代理背下来的规则清单，所以内容要精简，只写必要的“元信息”。

2.2 单个技能文件的骨架与设计原理

技能文件是整个体系的细胞，它的格式决定了代理能不能准确理解并执行。我比较推荐使用 YAML frontmatter 加正文 Markdown 的结构。举一个我常用的“编译问题修复”技能的例子：

--- name: java-compile-fix description: 当 Java 项目存在编译错误时使用。适合处理 Maven 或 Gradle 项目的编译失败问题。 when_to_use: 编译失败、类找不到、包不存在、JDK 版本不兼容 steps: 1. 运行 mvn compile 或 gradle compileJava 获取完整错误列表 2. 按错误顺序逐一定位源文件 3. 修改前阅读该文件的类结构和依赖关系 4. 修改后重新运行编译命令，确认错误数量减少 5. 编译通过后运行相关单元测试 6. 总结错误原因和经验，更新技能文件 ---

写技能文件有一个核心原则：只写步骤和方法，不写具体答案。你不需要告诉代理“遇到这个错误就改成这样”，而应该告诉它“遇到这个错误，先做 A 再做 B 再验证 C”。答案会因为项目不同而千变万化，但方法是可以沉淀复用的。这个文件放在 java 子目录下，前台靠 frontmatter 里的 description 字段和 when_to_use 字段来做匹配，后面正文则承载详细的执行步骤。

2.3 对 Java 项目最有用的技能组合

我因为日常主要是写 Java 后端，所以在技能库里为 Java 场景单独开了一个子目录，沉淀了三类非常常用的技能。

第一类是编译修复技能。Java 项目编译失败是家常便饭，尤其是多人协作的大项目里，依赖冲突、JDK 版本不一致、缺失 import，各种问题都有。编译修复技能的核心就是让代理遵循“先拿完整错误列表—逐一定位—修改—再编译验证”的闭环，避免它看到一个错误就埋头改，改完发现还有十个错误。

第二类是测试隔离技能。很多 Java 项目跑全量测试非常慢，动辄十几分钟。这个技能会让代理在修改完代码后，先用 Maven 的-Dtest=ClassName#methodName方式只跑相关测试类或单测方法，确认逻辑没被破坏，再决定要不要跑全量。这个细节极大提升了代理的迭代效率，也降低了它对 CI 资源的占用。

第三类是模块扫描技能。Java 工程往往是一个多模块的 Maven 项目，代理如果不先搞清楚模块之间的依赖关系，经常会出现“改了 A 模块却不重新构建 B 模块”的情况。模块扫描技能会要求代理先执行mvn dependency:tree读取依赖关系，再定位当前修改落入哪个模块、影响哪些下游模块，最后在编译和测试阶段一并验证。

2.4 实操要点：技能粒度越小越好用

我在试用过程中踩过最大的坑，就是把技能写得太大、太全。一开始我试图把“Java 项目日常开发”整个写成一个技能，里面从项目初始化、代码编写、测试到部署全都有。结果代理每次调用这个技能，都要看完一整篇几千字的文档，执行的时候反而犹豫不决，不知道该从哪一步开始。

后来我把技能拆成“一个任务一个技能”，粒度控制在每次执行不超过六到八个步骤。这样代理匹配得快、理解得准、执行得稳。技能名字和描述也要起得足够明确。description 里要写清楚“什么时候该用、什么时候不该用”，代理才能精准调用。比如一个技能描述写成“Java 编译错误修复”，就比较模糊；写成“当 Maven 项目编译失败时使用，适合处理类找不到、包不存在、版本冲突等错误”，代理一看就知道该不该调用它。

3. 安装配置与 Codex 集成实操过程

3.1 前置环境准备

在动手之前，先把环境列个清单。你需要准备好以下几样东西：一个能正常运行的 Codex CLI 环境，这个不必多说；一个 Git 客户端，用来拉取技能库；以及目标项目的构建工具，比如 Java 项目对应的 Maven 或 Gradle。如果你用的是别的编程语言，也同理，先把对应语言的工具链准备好。

我建议把 superpowers 技能库单独放在一个固定目录，比如~/.superpowers，然后在不同的项目里通过软链或复制的方式引入。这样技能库可以全局维护，任何项目需要时都能快速接入。

3.2 安装技能库的完整步骤

整个安装过程，我把它分成四步走。

第一步，把技能库拉取到本地。在终端里执行 Git 克隆命令，把 superpowers 仓库复制到~/.superpowers目录。这里要说一下，这个仓库本身的结构基本不需要改动，它的顶层目录就是 AGENTS.md、skills 和 plans 三个部分，拉下来就能用。

第二步，给 Codex 配置技能库路径。Codex 在启动会话时会读取项目根目录或用户配置目录下的 AGENTS.md 文件。你可以在~/.codex/AGENTS.md这个全局配置里加上一行指向技能库的引用，让代理知道“我的技能库在哪个位置”。这样所有项目都能共用同一套技能库，不需要每个项目重新配置。

第三步，在目标项目里建立技能库入口。我通常会在项目根目录放一个 AGENTS.md，里面写明本项目使用的技术栈、构建命令、测试命令，并按需引用全局技能库里对应的子技能。由于 Java 项目的构建命令往往固定，这一步能把项目级信息和技能库的通用能力结合起来。

第四步，验证技能是否被加载。最简单的方式是直接在 Codex 里问一句：“你能列出当前可用的技能吗？”如果代理能报出技能库里的各个技能名称和适用场景，说明加载成功。

3.3 Java 项目接入技能库的额外配置

Java 项目用的一个是静态语言，编译信息是代理最重要的反馈信号。我在项目级 AGENTS.md 里会特意写上这几个信息：项目使用的构建工具（Maven 还是 Gradle）、JDK 版本号、常用的编译命令、测试命令和测试报告输出位置。这些信息看似是项目常识，但对代理来说却至关重要。它只有知道了这些基础约束，才能在执行“编译修复技能”时选对命令。

另外，我强烈建议在项目根目录维持一个标准的 Maven 目录结构：src/main/java放主代码，src/test/java放测试代码，根目录放pom.xml。如果你把代码放在非标准目录里，代理每次都得先花大量时间探索项目结构，技能的效率会大打折扣。保持标准结构，代理就能把有限的上下文用在真正重要的逻辑上。

3.4 用一次真实对话验证技能生效

装完之后怎么确认它真的生效？拿一个小任务试一试就知道了。我在一个 Java 工程里故意留下一处编译错误，然后在 Codex 里说：“当前项目编译失败，请使用 java-compile-fix 技能处理。”如果配置成功，你会看到代理并没有直接打开文件乱改，而是先运行mvn compile拉出错误列表，然后逐条分析错误与源文件的对位关系，再动手修改，修改完重新编译，最后还跑了一下相关的单元测试。

以上这套流程走下来，完全可以确认 superpowers 已经在你的工作流里正常工作了。以后你再遇到编译错误、测试失败、依赖问题，不必每次从头给代理解释背景，技能库会自动匹配最合适的处理流程。这个收益随着你沉淀的技能数量增加，会越来越明显。

3.5 配置过程中的常见误区

我在配置初期犯过几个错误，这里提前帮你排掉。第一个误区是把技能库直接复制到项目里而不是引用。如果你直接把几百个技能文件复制进项目仓库，每次修改技能库都要同步到所有项目，非常麻烦。正确做法是全局放一份技能库，项目里只在 AGENTS.md 里写引用路径。

第二个误区是忘记区分“全局技能”和“项目技能”。全局技能应该放那些无论做什么项目都用得上的方法，比如代码审查、提交信息规范、错误记录反思；项目技能则应该聚焦技术栈和业务特定流程，比如“Spring Boot 项目启动失败排查”。两者混在一起会导致代理在无关场景下检索到错误技能，反而降低效率。

4. 常见问题与排查技巧实录

4.1 现象：代理说“已了解技能”，但执行时并不遵守

这是很多人接入 superpowers 后遇见的第一个坑。代理在对话里能复述技能的内容，但真正动手时却绕开技能里的步骤，凭自己的感觉直接改代码。出现这种情况，多半不是代理理解能力的问题，而是技能文件里的指令不够强。

我的解决办法是：在技能文件开头明确写上一句“必须严格按照以下步骤执行”，并在 AGENTS.md 里统一约定“在处理匹配技能描述的任务时，不得跳过技能中任何步骤”。这句话对代理的约束力远比想象中大。它本身不具备强制力，但显式的指令能显著提高代理的遵循率。如果还是不听，那就把技能文件的设计改一改，把它从“建议怎么做”改成“按照这个顺序做，不得跳过”。

4.2 现象：代理反复犯同一个编译错误

Java 项目里最常见的低效行为是：代理改了一个文件，编译又报错，它再去改下一个文件，如此循环，但你发现它每次都是在同一个错误上打转。这种情况之所以发生，是因为代理缺少“全局错误视图”。它只看到了当前这个错误，没有意识到整个模块里还有一连串相关的错误。

我在技能文件里特意加了“先获取完整错误列表，按错误数量排序后再开始修改”这一步骤。实测效果非常好。代理先拉出全部错误，然后从第一个错误开始依次处理，每处理完一个就重新编译，确认错误列表在减少。这样做表面上多跑了几次编译，实际上省掉了大量“改了这里、坏了那里”的来回折腾。建议每个 Java 编译修复技能里都加上这么一条，它可以靠编译错误数量作为代理的进度条，让代理始终清楚自己处于什么位置。

4.3 现象：对话上下文被技能文件撑爆

技能太多、每个技能又写得太长，代理在检索完技能后依然会把全文读入上下文，占掉了本来可以用于项目代码的窗口空间。做了一段时间后，我的技能库膨胀到两百多个文件，个别技能几百行，最终导致代理论证问题时上下文捉襟见肘。

处理办法分三步：第一条，控制单个技能文件篇幅，正文不超过一百五十行，超了就拆；第二条，在技能文件背后放一个“摘要区”，只记录关键步骤，让代理先读摘要、按需读全文；第三条，定期清理技能库，把长时间没被调用的技能归档到 archived 目录里。这与代码重构的道理是相通的——不是写得越多越好，而是保留被频繁使用的高价值技能。

4.4 排查速查表

4.5 独家避坑技巧

最后分享几个常规文档里不太会写的经验。第一，技能文件名就用小写加横线的风格，例如fix-import-order.md，不要用大写或空格，这样代理检索时不容易出错。第二，在技能文件的 frontmatter 里加一个version字段，每次修改技能内容就递增版本号。这不是给代理看的，而是给团队协作时追踪技能演进用的。第三，每过一两周，让代理跑一个“技能库复盘”任务，让它扫描所有技能文件的调用率，标记出几个月都没用过的技能。这个技巧本质上是让 AI 帮你维护 AI 的技能库，长期下来收益很高。

5. 实操心得与后续扩展思路

5.1 一次真实的 Java 项目修复体验

我印象最深的一次，是给一个多模块的 Maven 项目修 CI 构建问题。那个项目一共有五个子模块，CI 在第三个模块上编译崩溃。以前我让代理直接去处理，它打开第三个模块的报错文件就改，结果改完之后第四个模块接着报错。反复两轮，代理也没什么进展。

那次我改用 superpowers 的模块扫描加编译修复组合技能。代理先用mvn dependency:tree把模块依赖关系列出来，发现第三个模块是第二个模块的上游，它先检查了第二个模块的编译状态，果然问题出在公共依赖的类变更上。它先在第二个模块里修好了对应类的 API 变更，然后再重新构建第三个模块，一次通过。整个过程代理没有乱跳，完全是按技能里定义的顺序在推进。这个体验让我彻底信服：技能驱动的代理行为，质量上限远高于提示词驱动的随机发散。

5.2 把技能体系扩展到团队协作

superpowers 不只能用于个人工作流，它在团队协作里也能发挥价值。我建议团队把这套技能库放进 Git 仓库，由团队成员共同维护。新成员入职时，不需要读几十页文档，只需要让代理读一遍技能库，它就能按照团队约定完成常见任务。团队里解决过疑难问题的经验，也可以随手抽象成一个新技能，沉淀进共享技能库。这样一来，团队的知识不再藏在个别资深工程师的脑子里，而是逐步转变成一种可检索、可复用、可迭代的资产。

5.3 结合 CI 与测试工具做深度联动

我现在正在尝试进一步把技能库和 CI 流程联动起来。简单的做法是在 CI 脚本里加一步“预检技能”，让代理先跑一遍编译修复技能、代码规范技能，再提交代码。更进一步的想法是，把 CI 失败日志自动喂给代理，让它结合技能库生成修复补丁，再由人工审查后合入。这样形成的闭环，等于给 CI 系统配了一个会自动诊断和修复常见问题的“虚拟工程师”。虽然还没完全跑通，但已经能看到明显收益——重复性故障的修复时间比原来缩短了一倍以上。

5.4 给新手的第一个小建议

如果你刚开始接触这套玩法，不要一上来就想着建一个特别完善的技能库。我的建议是，从手头最频繁、最痛苦的一个任务开始，比如“修编译错误”或“写单元测试”，先写一个最简单的技能，花一天时间在真实项目里用起来，再根据代理的表现不断迭代它。等这一个技能稳定了，再去扩展第二个、第三个。毕竟技能库是一个活的东西，它不是一步到位的，而是在持续使用中越来越强大。