企业官网建设流程全解析

如果你最近在折腾 Codex CLI 或者 Claude Code，大概率会频繁刷到 superpowers 这个词。它不是什么超级英雄电影，也不是某个游戏 Mod，而是一套给终端里的 AI 编程助手“叠 buff”的技能库——准确说，是一组按特定格式组织的 skills 集合，能让 Claude Code、Codex CLI 这类 Coding Agent 在项目里表现出远超默认配置的能力。我第一次看到这个项目时也以为是营销噱头，但实际用下来发现，它解决的是一个非常真实的痛点：默认的代码助手只会“被动回答”，而 superpowers 提供了一套机制，让它学会“主动干活”——比如批量重构前先做影响面分析、写测试前先列断言清单、修 Bug 前先复现现场。这篇文章我会从项目设计思路、安装配置、与 Codex 的集成实操，到自定义技能和 Java 项目里的具体用法，完整过一遍。不管你是刚接触 CLI Agent 的新手，还是已经在日常开发里深度使用 AI 编程助手的从业者，应该都能从这里拿到可以直接抄作业的东西。

1. 项目核心思路：为什么需要一套“技能库”而不是更好的 Prompt

1.1 从“问答式助手”到“流程式协作者”

默认情况下，你在终端里启动 Codex CLI 或 Claude Code，它本质上是一个“高级问答机器人”：你给它一个任务，它根据上下文生成代码、执行命令、返回结果。听起来很美好，但实际用两周就会发现瓶颈——它缺少“工作方法”。举个例子，你让它“给这个支付模块补几个边界测试”，它会真的去写测试，但不会先问你“支付状态机有哪些分支”，也不会主动检查覆盖率报告，更不会在写完以后跑一遍变异测试。这不是模型能力不行，而是它缺少一套“怎么拆解任务、按什么顺序执行、什么时候该停下来问人”的流程约束。

superpowers 的核心思路就是把这些“优秀工程师的工作方法”固化成可复用的技能文件。每个技能是一个带结构化元数据的 Markdown 文档，告诉模型：你是谁、你负责解决哪类问题、你在什么情况下启动、你执行时的标准动作是什么。模型在对话开始时会扫描这些技能清单，根据用户请求的意图匹配最合适的技能，然后按照技能里写的步骤一步步执行。这就像给一个很有天赋但没什么经验的新人配了一本《团队工作手册》，他不需要每次都在脑子里重新发明做事方法，直接照着手册执行就行。

1.2 为什么选“文本规则 + 目录约定”而不是插件 SDK

市面上也有不少 AI 编程插件走的是“深度集成 IDE API”的路线，比如直接注册代码补全事件、读取编译错误流。superpowers 选了一条完全相反的路：它只依赖两个基础机制——约定目录和 Markdown 文件。技能就是文档，文档就是代码。这样设计的好处极其明显：

第一，跨工具通用。写好的技能文件，Claude Code 能读，Codex CLI 也能读，未来任何支持自定义指令的 Agent 工具大概率都能用同一套格式。你不用为每个工具重写一套技能，投资一次，长期复用。

第二，可审阅、可版本管理。技能文件就是纯文本，放在 Git 仓库里，代码评审时直接看改动就行。团队成员能清清楚楚看到“为什么模型这次表现变好了”，因为就是有人给某个技能增加了两个步骤。这比黑盒的插件系统透明得多，也更符合工程团队的协作习惯。

第三，迭代门槛低。改一个技能文件之后重新加载即可，不需要编译、不需要重启服务、不需要发布插件包。我经常在项目里临时写一个“针对本项目特殊日志格式的排障流程”技能，用两天觉得不好用就直接改或删，试错成本几乎为零。

1.3 superpowers 的边界：它不替代模型，而是约束模型

这里有个容易误解的点：superpowers 不会增强模型的推理能力，它改变的是模型的“输出策略”。模型该会的还是会，不会的还是不会，但它会更规范地调用自己会的东西。比如模型本来就能执行grep、find、git log，但没有 superpowers 时它可能跳过排查直接生成猜测性代码；有了系统设计（System Design）技能约束后，它会老老实实先做代码定位、再查调用链、然后才改代码。换句话说，这套技能库教模型“在动手前先建立上下文，在改代码前先写验证计划”。

2. 安装配置全解析：目录结构、环境和第一跑通

2.1 获取项目与一键安装脚本做了什么

安装 superpowers 非常简单，克隆仓库然后跑安装脚本：

git clone https://github.com/obra/superpowers.git cd superpowers ./install.sh

脚本会做的事主要有三件。第一，把技能文件复制（或建立软链接）到当前用户的家目录下，常见位置是~/.claude/skills/和~/.codex/skills/。第二，检查当前是否安装了 Claude Code 或 Codex CLI，如果缺少会提示你补齐。第三，生成一份 README 风格的技能清单索引，方便你后续自己查阅。

如果你是在团队项目里用，不建议直接跑全局安装，更推荐把技能库放进项目仓库的.claude/skills/和.codex/skills/目录下。这样所有 clone 这个仓库的成员都能用同一套技能，不同项目还能用各自定制的技能集合。我实测下来，项目级技能目录的优先级高于全局目录，也就是说同一个技能名，项目里的版本会覆盖全局版本——这个机制非常适合在不同项目里微调团队规范。

2.2 核心目录与文件格式：SKILL.md 究竟长什么样

技能文件的核心就是一个 Markdown 文件，文件名随意，但目录名就是技能名，文件本身统一叫SKILL.md。目录里还可以放参考资料、模板、脚本等附件，模型在执行技能时能按需读取附件内容。一个典型技能目录结构如下：

~/.claude/skills/ ├── plan-architecture/ │ └── SKILL.md ├── system-design/ │ ├── SKILL.md │ └── templates/ │ └── design-doc.md ├── bug-hunting/ │ ├── SKILL.md │ └── examples/ │ └── regression-analysis.md └── maven-debug/ ├── SKILL.md └── scripts/ └── analyze-build-log.py

SKILL.md 的正文必须带 YAML frontmatter，至少包含name和description两个字段。name是技能标识，description最关键，因为模型就是靠读这个字段来判断“当前任务要不要唤起这个技能”的。描述写得越具体、越覆盖触发场景，技能被正确唤起的概率就越高。正文部分则是步骤式的工作流，可以是“先做 A，再做 B，最后用 C 验证”，也可以直接给模板和检查清单。

2.3 第一次实操：从加载到确认技能生效

安装完以后，怎么验证技能真的被模型读到了？最简单的方法是在交互式终端里直接问一句“你现在加载了哪些技能？”如果模型能列出 skill 清单，说明加载正常。如果它只回复“我没找到任何技能”，优先检查路径：当前版本的工具通常只认~/.claude/skills/、~/.config/claude/skills/、.claude/skills/这几个位置，装完以后建议先用ls确认文件确实落到了对的地方。

另外一个细节：技能文件的目录名建议不要带空格，别用中文命名。虽然理论上模型能理解中文目录名，但真实测试中我发现，带空格或特殊字符的目录名偶尔会导致技能无法被索引到。用kebab-case命名最稳，比如system-design、bug-hunting、maven-debug。

3. 与 Codex CLI 的组合：配置文件、上下文构建与技能唤起机制

3.1 Codex 下如何让技能生效：AGENTS.md 与技能双通道

Codex CLI 与 Claude Code 的技能机制不完全一致。Claude Code 有原生 skills 支持，直接在配置里指定即可；而 Codex 的较早版本主要依靠AGENTS.md文件来注入项目级指令，如果想让技能文件在 Codex 里同样生效，最直接的做法是在项目根目录的AGENTS.md中增加一段“技能使用指南”，把~/.codex/skills/下有哪些技能、各自用途、何时调用写清楚，再附上“开始任何任务前先检索技能列表”的要求。

我个人的实际做法是双通道并行：技能文件依旧放在skills目录里作为“知识库”；AGENTS.md里则只写一段精炼的“工作协议”，比如：

# 工作协议 - 用户在要求“规划”“设计”“重构”“写测试”“排查故障”时，优先检索对应技能并按其流程执行。 - 执行涉及多文件修改的任务前，先输出影响文件清单。 - 所有代码改动完成后，必须运行一次项目现有的测试命令。

这样设计的理由很简单：技能是“怎么做”的详细手册，AGENTS.md是“何时用技能”的触发开关。二者配合，Codex 才能在正确的时候把技能文件里的步骤真正执行起来。

3.2 技能唤起失败怎么办：从描述改写到手动手动指定

技能唤起本质上是一个“意图匹配”过程，模型会对比用户请求和技能描述的相关度。描述写得太泛，比如在“生成测试”的技能描述里只写“处理测试相关任务”，模型可能把任何沾边的请求都路由过去，造成频繁误触发；描述写得太窄，模型又可能完全看不见它。理想的 description 应该包含：触发动作、目标对象、典型场景、排除条件。

如果调了几次描述还是无法稳定唤起，还有一个兜底方法：在对话里直接指定“请使用 maven-debug 技能来处理这个报错”。如果模型执行力正常，它会严格按照该技能的 SKILL.md 逐步执行。这一步在 Codex 里同样适用，因为技能本身就是一种可被显式索引的上下文。

3.3 实操案例：为 Codex 配置一个项目级“代码审查”技能

我最近给一个团队项目配置了代码审查技能，过程比较有代表性。先新建目录~/.codex/skills/pr-review/，然后创建SKILL.md，frontmatter 里name写pr-review，description写“在用户要求代码评审、检查 Pull Request、审查变更列表时使用，重点关注逻辑正确性、边界条件、异常处理和测试覆盖”。

正文部分我列出了完整步骤：先运行git diff获取变更内容，再定位每个变更文件所属的模块上下文，然后按列表逐项检查（空指针风险、并发安全、资源释放、事务边界），最后输出带严重等级的评审意见表。配置完以后实测，Codex 在收到“帮我 check 一下这个分支的改动”时，就直接按技能执行了，评审意见的结构化程度比默认状态高了不止一个档次。

4. 实操过程：Java 项目里的典型用法与技能定制

4.1 从零搭三个 Java 场景：构建、单测、排障

superpowers 在 Java 项目里能玩出很多花样，我先按常见场景拆解。第一个场景是构建：你让 Codex“帮我修一下项目构建失败”，默认行为往往是它直接去看 pom.xml 猜测问题。有了技能约束后，模型会先执行mvn -DskipTests compile复现失败，再读取target/surefire-reports或编译日志里的第一个报错，然后沿报错栈定位源码文件，最后才提出修复建议。

第二个场景是单测生成：让模型“给某个工具类写完整单测”。默认它可能一口气生成几百行测试，里面一半是无效断言。定制技能后，模型会先读取该类的方法签名，列出需要覆盖的分支和边界值，把清单给你确认，然后才逐个方法写测试。这样生成的测试覆盖率更扎实，也更容易通过评审。

第三个场景是故障排查：线上日志里抛了一个 NullPointerException，默认模型可能直接让你“检查空指针”，等于没说。技能约束后，模型会先让你提供堆栈、相关日志片段、最近改动记录，然后基于堆栈逐步反向推理，把可能的原因按概率排序列出来，再针对每个原因给出验证方式。这套流程写进技能文件后，排查效率提升非常明显。

4.2 自制一个实用技能：Maven 构建失败分析器

自己写技能没有想象中复杂，以“Maven 构建失败分析器”为例。新建目录~/.claude/skills/maven-debug/，创建SKILL.md：

--- name: maven-debug description: 当用户报告 Maven 构建失败、编译错误、依赖冲突、测试失败时使用。先复现再分析，不给出未经日志验证的结论。 --- # Maven 构建失败分析 ## 触发条件 - 用户提到 mvn 命令执行失败 - 用户贴出 BUILD FAILURE 日志 - 用户说“依赖冲突”“编译错误”“单测挂了” ## 执行步骤 1. 复现构建：运行 `mvn -DskipTests compile`，记录完整输出。 2. 定位第一个错误：从日志中提取第一个 ERROR 级别信息，忽略后续连锁错误。 3. 识别错误类型： - 编译错误：定位到出错文件与行号，查看相关 import 和泛型签名。 - 依赖冲突：运行 `mvn dependency:tree`，查找版本冲突的可传递依赖。 - 测试失败：读取 `target/surefire-reports/*.txt`，提取失败断言行。 4. 生成修复建议：每条建议必须附带“为什么这样做”的解释，不直接改代码。 5. 验证修复：若用户同意修改，修改后重新运行 `mvn -DskipTests compile`。 ## 注意事项 - 不要先用“可能是 X 问题”来猜测，先看日志再下结论。 - 不要一次性修改多个变量：一次只解决一个失败原因。 - 如果修复涉及依赖版本升级，提醒用户检查兼容性。

这个技能文件总共不到 40 行，但实测效果非常明显，因为模型每次分析构建失败时都被强制“先复现再分析”，杜绝了它凭空臆测的毛病。

4.3 技能文件里的“坑”：模型会照做的边界

写技能容易，让模型稳定照做则需要摸清边界。第一，步骤要足够原子化，每步只做一件事，一次性要求模型“分析问题、定位缺陷、修改代码、补测试、跑构建”五连，它往往会在中间某个环节偷工减料，最常跳过的就是“验证”。所以技能步骤里一定要把验证单独列为必须步骤，并明确具体验证命令。

第二，避免在技能里写互相矛盾的规则。比如前面说“不要直接改代码”，后面又说“如果用户要求就直接改”，模型会困惑，最后表现就是两次执行的结果不稳定。规则之间要层次分明，明确“用户明确要求”作为更高优先级。

第三，技能正文要主动留白，不要试图覆盖所有分支。模型在具体执行时会根据上下文填充细节，你只需要定义流程骨架和关键checkpoint。我见过有人把技能写成一本书，结果模型执行时反而迷失在大量细节里，每一步都在犹豫要不要按“特殊情况”走。

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

5.1 技能加载后不生效，优先排查这五个地方

我踩过的坑不少，整理成一张速查表，效率最高：

5.2 上下文占用与 token 开销控制

技能越多，每次对话时模型需要扫描的文件就越多，token 消耗自然上涨。我实测过，加载 10 个技能后，基础 token 开销大约增加 20% 左右，但这部分成本换来的行为规范是值得的。不过要注意别在全局目录堆几十个技能，尤其不要让某个技能的 SKILL.md 里贴一大段完整代码，那是灾难。技能文件篇幅控制在 60 行以内，附件类参考资料按需单独存放，不要全塞进主文件。

5.3 Codex 与 Claude Code 行为差异实测

同一个技能文件在两种工具里的表现并不完全一致。Claude Code 对技能的执行更“死板”，步骤顺序严格照做；Codex 则更灵活，会自主调整顺序甚至跳过它认为不必要的小步骤。因此如果你在 Codex 里发现某个技能没有被完整执行，不要第一时间怀疑技能写错了，先看看是不是模型自主决定简化了流程。对策是在步骤里显式声明“这些步骤缺一不可”，并且每个步骤写明产出物，把流程变成“不完成上一步就无法进入下一步”的链条。

6. 扩展经验：让技能库活起来的三个进阶玩法

6.1 把团队规范直接“翻译”成技能

很多团队有详细的编码规范文档，但模型往往不会主动翻查。把这些规范浓缩成技能文件后，约束效果立竿见影。我接手过一个项目，规范文档要求“所有对外接口的异常必须包装成 BizException，禁止裸抛 RuntimeException”，写成技能后，模型新生成的业务代码里就极少再出现裸抛异常。注意，这里不是让模型读整个规范文档，而是提取其中最硬性的约束，转成步骤式检查项放进技能里。

6.2 生产环境故障复盘反哺技能库

每次线上事故复盘都会产出“下次要提前检查的指标”，这些经验最适合沉淀为技能。比如某次生产事故是缓存穿透导致的，复盘结论是“发版前要评估热点 key 的并发量”。我把它写进 code-review 技能，从此每次代码评审模型都会自动关注缓存穿透风险点。技能库因此变成了团队经验的活体记录，价值随使用时长递增。

6.3 技能之间互相调用：让 Agent 学会“分工协作”

高级用法是让一个技能调用另一个技能。比如“大型重构”技能里可以写“在执行步骤一之前，调用 system-design 技能生成目标架构方案”。这样模型会把多个技能串成流水线，表现更像一个真正的技术负责人。我在实际项目里配合这个机制做过一次模块拆分，Agent 先产出架构方案，再生成影响面清单，再逐步迁移代码，最后跑回归测试，整个过程的推进节奏比我手动指挥要顺畅得多。

我个人在实际操作中的一个体会是：superpowers 这类技能库最核心的价值不是“让 AI 变得更聪明”，而是“让 AI 的行为变得更可预期”。你不再跟一个每次表现都随机的黑盒打交道，而是在跟一套你亲手设计的流程执行器协作。如果你刚装好不知道怎么下手，我建议别贪多，先挑一个自己最痛的点——比如“代码审查”或“构建排障”——写一个十几行的技能，对比一下开启前后的差异，你会立刻感受到这套思路的威力。