企业官网建设流程全解析

第一次用 Codex CLI 的时候，我有种很强烈的违和感：它明明能一口气写完一个模块，却总是按着对话记录一句一句追着我确认需求。模型能力摆在那里，问题出在工作流上——你给它的是零散 prompt，它自然只能回你零散的结果。后来我把 superpowers 接进了同一个 CLI，才意识到原来缺的是一套“技能系统”：让 AI 在干活前先有章法，在干活中能调脚本，而不是每次从空白对话开始“随机应变”。

这篇文章不是官方文档的翻译，而是我把 superpowers 装进日常开发流程后的完整实践记录。内容包括它解决了什么问题、全局安装和项目级安装怎么选、内置技能哪些最实用、如何给 Java 项目写一个自定义技能，以及我踩过的几个坑。适合正在用 Codex CLI、Claude Code 这类终端 AI 助手，又觉得它们“不太听话”的开发者参考。

1. 关于superpowers：它到底是什么，以及为什么AI编码助手急需“技能系统”

1.1 终端AI助手的真实痛点：有模型，没有“打法”

现在的主流终端 AI 助手，比如 Codex CLI、Claude Code，本质上都是把大模型塞进一个命令行壳子里。它们的原始形态非常朴素：用户输入一句指令，模型返回一段回复。听起来没问题，但真正做项目时会发现三个明显的短板。

第一是无状态。每次对话都是独立的，AI 不记得你昨天定过的代码规范，不记得这个仓库的测试命令是mvn test而不是gradle test，更不记得你上次让它“先写接口再写实现”的约定。第二是回答模式单一。你让它修 bug，它就真的只“修”，不会先去读相关代码、复现问题、解释根因，而是直接给一段改好的代码。改完往往引入新问题。第三是缺少可编程的中间层。模型只是一个文本输入输出的黑盒，你没法在它干活的过程中插入一个“脚本”，让它先跑测试再告诉你结果。

也就是说，模型本身不笨，但它的工作流是“裸奔”的。传统工程里我们有 CI、有 lint、有代码模板来约束和辅助人的行为，可终端 AI 助手却什么都没有。

superpowers 就是冲着这个问题来的。它是一个开源项目，目的不是替换某个 AI 助手，而是给这些 CLI 助手加上一层“技能层”。你可以把它理解成一套插在模型和项目之间的工具箱：里面放了各种“技能文件”，每个技能都告诉 AI 在特定场景下该按什么步骤、用什么标准去干活。AI 不需要重新发明轮子，只需要识别场景、翻出对应技能、照着执行。

1.2 三个核心组件：规则文件、技能目录、可执行脚本

superpowers 的实现并不玄学，它主要靠三个东西协同工作。

第一个是全局规则文件。在 Codex 里是AGENTS.md，在 Claude Code 里是CLAUDE.md。这类文件会作为系统提示的一部分持久化地注入每个对话，相当于给 AI 立了一部“工作手册”。superpowers 的做法是把自己的位置和技能目录结构写进这份手册里，这样 AI 从一开始就知道：遇到某类任务时，去哪个目录找什么文件。

第二个是技能目录。里面是一个个 Markdown 文件，文件名就是一个技能名，比如debugging.md、brainstorming.md。每个文件描述了这项技能的适用场景、操作步骤、输出标准。AI 在对话中会根据用户需求去“发现”这些技能文件，然后照着执行。这部分相当于一套可检索的 SOP 库。

第三个是交互式脚本，也就是.skill文件。这是 superpowers 和其他提示词工程方案最大的区别：技能不只是文档，还可以是 bash 脚本。AI 可以执行这些脚本、传入参数、读取结果、再决定下一步。比如调试技能可能会先让 AI 跑一段命令收集报错信息，再让 AI 结合报错内容去修代码。

用一个不太严谨但好懂的说法：AGENTS.md 是岗位说明书，skills 目录里的 md 文件是操作手册，.skill脚本是别人帮你写好的自动化工具。三者合在一起，AI 才从“聊天对象”变成“能按流程办事的执行者”。

1.3 它适合谁，解决什么问题

我在把它用于日常工作后，觉得最有价值的人群有三类。

一是深度使用终端 AI 助手的开发者。如果你已经在用 Codex CLI 或 Claude Code 写代码，但总觉得结果不稳定、风格不统一，那么 superpowers 能把这些“不稳定”收敛到一套可复用的流程里。

二是希望统一团队 AI 协作规范的团队。把技能目录放进项目仓库后，所有成员用 AI 干活时都会遵循同一套标准，比如先写测试再实现、提交前必须跑全量检查。这比口头约定可靠得多。

三是在特定技术栈上有重复工作的人。比如 Java 项目里每次都要让 AI 生成单元测试骨架、分析 Maven 依赖树、生成 MyBatis 映射文件。这些完全可以用一个自定义技能封装起来。

反过来说，如果你只是偶尔让 AI 写一段一次性脚本，不需要长期一致的“行为模式”，那 superpowers 确实有点杀鸡用牛刀。它适合的是把 AI 当成长期协作对象的场景。

2. 安装前的关键抉择：环境要求、版本选择与作用域规划

2.1 先确认环境：依赖比想象中轻

安装前最好先确认自己机器上有这几样东西：git、node（建议 18 以上）、一个 Unix shell（macOS 和 Linux 自带 bash，Windows 上建议用 Git Bash 或 WSL）。另外必须有至少一个终端 AI 助手，比如 Codex CLI 或 Claude Code。

node这个依赖其实不是 superpowers 运行必需的，而是因为很多技能脚本会用 Node 来处理文本、解析 JSON。如果你计划后面写自定义技能并用到 JavaScript，最好提前装好。版本不用太纠结，18/20/22 都能跑。

CLI 助手那边，Codex 和 Claude Code 官方都在快速迭代，superpowers 对两者的支持方式有细微差别，但核心逻辑一致：都是通过规则文件告诉 AI 技能系统在哪里。安装前建议看一眼项目仓库 README 的最新说明，因为这类项目一个月可能变好几个版本。我下面写的路径和命令只代表我实测过的一种合理方式，具体以你 clone 下来的仓库为准。

2.2 全局安装、用户级安装还是项目级安装

superpowers 官方提供了几种安装位置，刚开始很容易搞混。我按自己的经验整理成一张表：

我个人的建议是：先全局装一遍，跑通默认技能。再根据实际需要往具体项目里放项目级技能。尽量不要一开始就在全局和项目级各放一套，那样会出现同一个技能名两个版本的问题，AI 不知道该信哪个。

2.3 模型选择与交互式能力的边界

superpowers 里有相当一部分技能依赖“交互式执行”，也就是 AI 在对话中途能够运行.skill脚本并读取输出。这意味着你用的模型和 CLI 必须具备函数调用或等价能力。目前 Codex CLI 和 Claude Code 的默认模型基本都支持，但如果你在配置里强行切了一个不支持工具调用的模型，技能就会退化成普通文档，AI 只能读，不能执行。

另外，CLAUDE.md/AGENTS.md里的内容会占据一定上下文窗口。技能文件写得越长，被 AI“读到”的成本就越高。后面讲避坑时我会展开说，这里先记住一个原则：技能文件要短、聚焦、可扫描，别写成一本百科全书。

3. 安装实操：从命令到验证

3.1 克隆仓库并了解目录结构

我用的方式是直接 clone 到 home 目录：

git clone https://github.com/obra/superpowers.git ~/.superpowers

clone 完成后进目录看一眼结构，通常能看到：

~/.superpowers/ skills/ brainstorming.md debugging.md ... scripts/ ... AgentRules/ ...

重点在skills目录。你可以理解成这些都是预置的“插件”。后续你写的自定义技能也放这里，文件名就是技能名。

3.2 注册全局规则文件：让AI知道技能在哪

光有技能文件还不够，AI 不会主动去~/.superpowers里翻东西。你必须把它写进规则文件里。Codex 的话编辑~/.codex/AGENTS.md，Claude Code 的话编辑~/.claude/CLAUDE.md。文件不存在就创建一个。

我当时的配置大致是这么一段：

You have access to a collection of "superpowers" stored in ~/.superpowers/skills. When the user asks you to perform a task that matches one of these skills, you MUST read the corresponding .md file and follow its instructions exactly. If a related .skill script exists, you may run it to interact with the environment.

核心就三句话：技能在哪、什么时候读、读完后怎么办。注意路径要用绝对路径，避免 AI 在不同工作目录下找不到。如果你在项目级也放了技能目录，可以再追加一条说明，告诉 AI 项目目录优先还是全局目录优先。我的习惯是项目级优先，因为团队规范通常更具体。

3.3 项目级安装：让团队共享同一套AI行为规范

项目级安装的核心不是把整个 superpowers 仓库复制进项目，而是在项目根目录放一份AGENTS.md，然后引用项目自己的技能目录和全局的技能目录。

我在 Java 服务端仓库里是这么组织的：

repo/ AGENTS.md .ai/ skills/ java-unit-test.md maven-dependency-check.md

对应的AGENTS.md里写：

This project uses AI skills located in .ai/skills. Additional general-purpose skills are available in ~/.superpowers/skills. If a task matches a project-specific skill, prefer the project skill over the global one.

这样做的好处是：团队成员 clone 仓库后，AI 的行为规范跟着代码走，不需要每个人手动去配，也不会因为某个人没安装导致 AI 行为不一致。

3.4 验证安装：让AI自己汇报技能清单

装完后的第一件事是验证。新开一个对话，直接问 AI：

你能使用哪些技能？列出名称和适用场景。

如果配置正确，AI 应该能从规则文件里找到技能目录，然后列出一批技能名，比如 brainstorming、debugging、逐行文件阅读等。如果它说“没有技能”，或者“只看到了规则文件但不知道技能在哪”，绝大多数情况是路径引用不对，或者规则文件没有被正确加载。

另一个更直接的验证方式是让 AI 执行一个技能，比如：

用 debugging 技能来排查一下这段代码为什么报 NPE。

观察 AI 的行为是否从“直接给答案”变成了“先列出排查步骤、再定位代码、再给出修复”。行为变了，说明技能系统真的在起作用。

4. 内置技能逐个拆解：哪些值得优先用

4.1 brainstorming：把模糊需求变成“问题清单”

我一开始觉得 brainstorming 这种技能很玄，需求都不清楚还怎么头脑风暴？用了几次后发现它的价值在于：AI 会强行把模糊目标拆成一系列具体问题，然后和你逐项确认，而不是自己假设需求直接开写。

比如你说“我想给应用加一个用户签到功能”，没有技能时 AI 可能直接生成一套表结构和接口。有了 brainstorming 技能，它会先问你：签到是否需要连续签到奖励？断签怎么处理？补签功能要不要？数据结构是独立表还是挂在用户表下？

这个技能适合在动手前使用，尤其是需求本身只有一句话的项目初期。它的本质是给 AI 挂上一个“先澄清，再动手”的护栏。

4.2 逐行文件浏览与 debugging：我目前最常用的组合

superpowers 里有一个“逐行阅读代码文件”的技能，名字可能因版本不同有变化，但作用我非常推荐：让 AI 把文件内容一段段读给你听，并解释每一段的作用。这听着笨，实际用起来非常有用，特别是接手陌生项目时。AI 的上下文窗口有限，一次塞太多文件反而记不住细节，逐行读反而能给出更高质量的代码评审意见。

debugging 技能则是另一个高频技能。它不再让 AI 直接给修复代码，而是要求 AI 先定位问题、给出你排查用的命令、解释代码的预期行为与实际行为差异，最后才动手改动。这个顺序非常符合真实调试流程。我以前让 AI 修 bug，它经常改完这处引出那处，就是因为跳过了“定位”这一步直接改代码。

这两个技能配合起来效果更好：先逐行读可疑模块，让 AI 建立完整的代码上下文，再用 debugging 流程去修问题。修完后还可以让它用 code review 技能复查一遍改动。

4.3 code review 与测试驱动开发技能

code review 技能会把 AI 变成“挑刺的同事”。它会主动检查边界条件、资源释放、并发安全、与项目现有风格的差异。我实测下来它给出的意见比直接说“帮我 review 代码”要系统很多，因为它有一个明确的检查清单流程。

如果你在做 Java 项目，TDD 技能也值得优先打开。它会让 AI 先写失败测试，再写实现代码让测试通过。这个流程对老手来说不难，但 AI 默认不会这么做，TDD 技能相当于把这条纪律刻进了它的工作流。下面要讲的 Java 自定义技能，其实就是这套思路的具体化。

4.4 Java场景实测：从依赖分析到测试骨架

搜索词里出现了“superpowers java”，我也专门在 Java 项目里试过。内置技能主要覆盖通用工程场景，像上面的 debugging、review，它们都不绑定语言。真正和 Java 强相关的是你自己写的技能，或者你针对具体仓库的AGENTS.md做定制。

我通常在 Java 仓库里补充的技能有两类。一类是“依赖分析”技能：让 AI 先执行mvn dependency:tree或gradle dependencies，再根据输出定位冲突。另一类是“单元测试骨架生成”技能：先读被测类的结构，再按 Given-When-Then 结构生成 JUnit 5 测试。这两类工作极其重复，内置技能覆盖不到，但用自定义技能封装后效率提升非常明显。下面第五部分我会用“单元测试骨架生成”当例子，完整走一遍自定义技能的过程。

5. 动手写一个自己的技能：以“Java单元测试生成”为例

5.1 skill.md 的规范与写法

自定义技能并不神秘。你只需要在 skills 目录里新建一个 Markdown 文件，文件名就是技能名。我们先做最小可用版本。

在~/.superpowers/skills/java-unit-test.md写入：

--- name: java-unit-test description: Generate JUnit 5 test skeletons for a given Java class, following the Given-When-Then style. --- ## When to use Use this skill when the user asks to create a unit test for a Java class. ## Steps 1. Read the Java source file and identify the class name and public methods. 2. Identify constructor parameters and dependencies. 3. For each public method, generate a JUnit 5 test skeleton. 4. Use AssertJ for assertions if the project already uses it. 5. Do not generate implementation, only test skeletons. ## Test skeleton structure ```java @Test void should_expected_behavior() { // given // when // then }

注意几点。第一，`description` 字段是给 AI 做“技能发现”用的，所以它得足够清晰，让 AI 一读到就知道这个技能适不适用于当前任务。第二，正文里的步骤必须具体到 AI 能照做，不要写“生成高质量的测试”这种不可执行的话。第三，代码示例要短，因为整个技能文档都会被 AI 读进上下文，太长等于烧 token。 ### 5.2 交互式.skill脚本：你与AI之间的“小工具” 如果只是输出文字文档，那 skills 目录就只是提示词库，价值有限。superpowers 更厉害的是支持 `.skill` 脚本，让 AI 可以在对话中执行 bash 命令。 回到 Java 测试生成的例子。我们希望 AI 能先读取类文件，再生成测试文件。那可以写一个辅助脚本 `java-unit-test.skill`，让 AI 用它来提取被测类的公共方法签名。 ```bash #!/usr/bin/env bash # Usage: java-unit-test.skill <java-file> FILE="$1" if [ ! -f "$FILE" ]; then echo "ERROR: file not found: $FILE" >&2 exit 1 fi grep -nE '^\s*(public|protected)\s+.*\(' "$FILE" | head -50

这个脚本不复杂，作用是快速提取文件名里的方法签名，避免 AI 把整个文件读进来浪费上下文。实际使用时 AI 会先运行这个脚本，拿到方法清单，再对照清单逐条生成测试骨架。

.skill脚本可以做的事远比这多：解析 JSON、调用构建工具、检查文件是否存在、读取环境变量。它相当于你为 AI 定制的专用命令，这也是 superpowers 区别于普通提示词工程的核心竞争力。

5.3 把技能放进目录并测试

写完 md 和 skill 文件后，把它们放进技能目录即可。全局技能放~/.superpowers/skills/，项目技能放项目.ai/skills/。

测试分两步。第一步不经过 AI，直接在 shell 里跑一下.skill脚本，确认它输出正常：

chmod +x ~/.superpowers/skills/java-unit-test.skill ~/.superpowers/skills/java-unit-test.skill src/main/java/com/example/OrderService.java

能看到方法签名列表就说明脚本是可用的。第二步再开 AI 对话，让 AI “使用 java-unit-test 技能给 OrderService 生成测试”，观察它是否准确调用了这个技能。

5.4 技能设计的原则：小而专、可组合

写技能时最大的误区是想让一个技能覆盖所有场景。技能越大，AI 执行时越容易遗漏步骤，维护成本也越高。我的原则是：一个技能只做一件事，但把这件事做透。

比如“java-unit-test”就专注生成测试骨架；“dependency-check”专注分析依赖冲突；“debug-guide”专注排查步骤。需要组合使用时让 AI 自己串联，而不是塞进一个巨型技能里。

此外，技能文档的“When to use”部分一定要写清楚。因为 AI 不是每次都会读完所有技能，它需要快速判断哪些技能与当前任务相关。模糊的适用范围会让它做出错误的调用。

6. 实际跑项目时的经验与避坑清单

6.1 坑1：模型不支持交互式调用，技能变成了“死文档”

症状是：AI 确实读取了技能文件，但遇到.skill脚本时不会执行，而是直接说“我无法运行脚本”，或者把它当成普通文本解读。

我遇到这种情况基本是两个原因。一个是模型本身不支持函数调用，另一个是 CLI 配置里限制了命令执行权限。解法是回到 CLI 配置里确认命令执行功能处于开启状态，并且当前模型支持工具调用。如果你用的是 Codex CLI 的某些轻量模型，或者 Claude Code 里切了非最新的模型，都会踩到这个问题。

判断技能是否“活着”有一个很简单的办法：让 AI 用某个强交互技能干活，比如 debugging。如果它只是把技能文档里的步骤复述了一遍，而没有真正运行任何命令，那大概率就是执行层出了问题。

6.2 坑2：技能目录冲突与命名混乱

全局技能和项目技能用同一个技能名时，AI 会困惑该执行哪个版本。比如我在全局放了java-unit-test.md，又在项目里放了一份优化过测试风格的版本，结果 AI 有时候读全局的，有时候读项目的，输出风格飘忽不定。

我的解决方式是：项目级技能不要覆盖全局技能，而是换名字。全局技能保持通用风格，项目技能用个性名前缀，比如order-service-test.md。另外在项目AGENTS.md里写明优先级规则：项目技能优先于全局技能。这样即使同名，AI 也知道听谁的。还有一点是技能文件名尽量用连字符小写，避免大小写问题在不同操作系统上带来麻烦。

6.3 坑3：规则文件和技能文档太长，上下文被严重占用

我第一次配置时恨不得把团队所有规范都写进AGENTS.md，再让技能文档事无巨细地描述每一步。结果发现每次对话光加载规则就要消耗大量 token，AI 的注意力也被稀释了，反而更笨。

后来我把AGENTS.md精简到了几行：技能目录在哪、项目级技能优先、执行技能前必须读对应文件。技能文档本身控制在 40 到 60 行以内，能用列表就不用长段落，能用示例代码就不用大段解释。规则文件和技能文件是给 AI 做“决策”用的，不是给人做培训用的，越精炼效果越好。

如果你在一个特别大的仓库工作，建议把技能按目录拆分，比如.ai/skills/java/、.ai/skills/frontend/，并在规则文件里让 AI 按任务类型去对应目录找技能。这样每次对话只加载部分技能描述，而不是全量扫描。

6.4 维护建议：把技能库当成代码库管理

技能文件本质上是代码资产，而且是很容易被忽略的资产。我会把项目里的.ai目录纳入版本控制，每次调整技能都写提交信息，说明为什么调整。全局的~/.superpowers用单独目录管理，偶尔用 git 拉取官方更新，但我会先看 diff，避免官方改版破坏我的自定义技能。

还有一个技巧：给技能添加“最后验证日期”之类的元信息，或者定期用一组测试任务回归一遍技能。我每个月会抽半天时间，挑几个常用技能重新跑一遍，确认它们在新版本 CLI、新模型下依然工作正常。这比到用的时候才发现坏了要省心得多。

我个人的体会是，superpowers 这类工具真正的门槛不在安装，而在于你愿不愿意花时间去把“AI 的默认行为”改成“你想要的工程标准”。安装、内置技能、自定义技能，每一步都是围绕“流程可控”这个目标展开的。如果你现在正觉得终端 AI 助手能写代码但不好配合，不妨先从这个项目的技能系统入手，给 AI 配上一套真正可执行的工作手册，效果可能比换模型更明显。