企业官网建设流程全解析

最近 AI 编程圈的几个群里，superpowers 这个词出现的频率高得吓人。不是中二病，也不是什么漫画梗，它是一套给 AI 编程代理用的技能扩展框架，主要跑在 Claude Code、Codex 这类命令行工具上。简单说，你可以把它理解成给 AI 装上的一套标准化作业手册——原来你问一句它答一句，现在你丢一个任务，它会自己走完"先聊清楚需求、再拆计划、再写测试、再动手实现、最后重构收尾"的完整流程。

我用它大概有三周了，最大的感受是：AI 写出来的东西不再是"能跑就行"，而开始像同事手里交出来的活。如果你最近也在折腾 superpowers 安装、superpowers 使用教程，或者想在 Codex、Java 项目里把它用起来，这篇文章应该能帮你省不少时间。我会从它到底解决什么问题讲起，再给到完整的上手路径和我在实际项目中踩过的坑。

1. 项目解读：superpowers 到底在解决什么问题

1.1 一句话讲清它是什么

superpowers 是一个开源项目，由 Jesse Vincent（网名 obra）发起，本质上是给 AI 编程代理准备的一套"技能包"。

它不是 IDE 插件，也不是独立的 AI 模型，而是一堆高度结构化的 Markdown 技能文件，外加一个把它们加载进 AI 工作流的框架。每个技能文件都定义了一个完整的工作流程，AI 在对话中调用它，就相当于进入了"按套路干活"的模式。比如你想让 AI 实现一个新功能，它不会直接甩出一大段代码，而是先跟你确认验收标准，然后写计划，再按测试驱动开发的节奏把功能做出来。

打个比方：你让实习生"写个登录功能"，他大概率能写出来，但可能漏掉参数校验、密码加密、错误提示。可你要是给他一本带检查清单的《登录功能作业规范》，他至少不会漏掉该有的步骤，交上来的东西也有章法。superpowers 就是那本规范。

1.2 为什么叫 superpowers：从"回答者"到"执行者"

用过 Claude Code 或 Codex 的人应该都有类似的体验：AI 很聪明，但没耐心。你让它写一个函数，它五分钟就写完了；你让它重构一个模块，它改了三分之一就停下来等你确认下一步。这不是能力问题，是工作方法问题——模型本身缺乏一套稳定的"做事的节奏"。

superpowers 解决的就是这个问题。它把领域里被验证过的好方法，比如测试驱动开发、小步重构、计划先行、规范的提交信息，固化成 AI 的默认行为。让 AI 从"你问什么我答什么"的回答者，变成"拿到任务自己规划、自己执行、自己检查"的执行者。

我用一个真实场景对比一下。没有 superpowers 时，我让 AI "给 UserService 加一个 findByEmail 方法"，它可能直接给你一个能编译通过的实现，然后问你"还需要什么吗"。有 superpowers 时，它会先问"email 不存在时应该抛异常还是返回空？"，然后写一个失败的测试，再写实现，最后跑一遍测试确认全绿。同样是完成一个需求，后者交付的东西明显更可维护。

1.3 哪些人最该用，哪些人可以先不用

先说适合用的：

• 天天泡在终端里用 Claude Code 或 Codex 写代码的人。
• 想让 AI 输出的代码有测试、有文档、可维护的人。
• 带团队、想统一大家 AI 使用姿势的人——技能包可以放进 Git 仓库，全组共用一套标准。

再说暂时不用的：

• 偶尔用 AI 写个脚本、处理一次临时需求的人，技能包会显得重。
• 完全没有版本控制概念的新手。因为 superpowers 里的很多技能高度依赖 Git，比如它会频繁查看 diff、创建分支、用提交信息模板，如果对 Git 不熟，容易不知道自己正在被 AI 引导着干什么。

2. 核心设计：技能（Skills）机制拆解

2.1 技能 = 可复用的标准作业程序

superpowers 里最核心的概念就是 Skill。一个技能文件通常由两部分组成：开头是一段 YAML 格式的 frontmatter，写着技能名称、描述、适用场景；正文是完整的操作指引，告诉 AI 遇到这类任务应该按什么顺序执行、每一步要产出什么、有哪些要点。

这种设计本质上就是把一个资深工程师脑子里那套"遇到问题怎么做"的流程，变成一份机器能读取、模型能执行的文档。它和普通提示词最大的区别是：提示词是临时的，用完就忘；技能文件是持久的，可以反复调用，可以被其他技能引用，可以放进 Git 里做版本管理。

我刚开始以为这就是换了个方式写 prompt，用了一段时间才发现区别很大。普通 prompt 是"请按测试驱动开发来写"，模型大概率会回答"好的，我按 TDD 来"，然后依然是先写实现再补测试。技能文件不一样，它把"先写失败测试"拆成了一个不可跳过的步骤，模型在每一步都会读到"现在你在这个 Skill 的第 2 步，请先完成这一步的产出"，这样就不会蒙混过去。

2.2 内置技能盘点

superpowers 仓库里预置了不少技能，我用得比较多的是下面这几个：

这些技能不是孤立的，它们可以互相调用。比如 test-driven-development 在执行中途发现实现很糟糕，可能自动调用 refactoring 来整理结构；在所有代码改完后，又会调用 commit-message 来生成提交信息。组合起来，AI 的工作流就变成了流水线，而不是一个孤零零的问答。

2.3 为什么技能优于普通提示词

这个问题我问过自己很多遍，最终总结出三个关键点。

第一，稳定复现。模型嘴上说"我按 TDD 来"和真的按 TDD 做，是两回事。技能文件用步骤清单和检查点约束模型的行为，让它每次都能做出差不多质量的事，而不是看心情发挥。

第二，可组合嵌套。普通提示词写完之后，你很难让另一个提示词去调用它。技能文件可以把任务拆成多个技能的串联，比如"先 brainstorming 澄清需求，再 writing-plans 制定计划，然后用 TDD 分步实现"。这种组合能力让 AI 面对复杂任务时不至于乱套。

第三，集体进化。技能文件是纯文本，放在 Git 里就能做版本管理和多人维护。我自己就 fork 了一个技能，把团队内部的一些规范加了进去，比如提交信息里必须带任务单号。这样 AI 在开发时使用的就不再是互联网通用的最佳实践，而是你们团队自己的最佳实践。

2.4 技能文件长什么样

很多人对 superpowers 的印象是"一堆神秘脚本"，我拆开看之后发现其实特别朴素。一个技能文件大概长这样：

--- name: test-driven-development description: 使用测试驱动开发流程实现新功能，先写测试，再写实现，最后重构。 --- 执行本技能时： 1. 和用户确认功能的验收标准，包括正常情况和异常情况。 2. 先编写一个会失败的测试，覆盖验收标准中的关键场景。 3. 运行测试，确认它确实失败。 4. 用最小实现让测试通过。 5. 检查实现是否有重复或坏味道，有小步重构的空间就重构。 6. 重新运行全部测试，确认没有回归。

结构清楚、意图明确、没有玄学。它之所以有效，就是因为它把"写代码这事应该有什么节奏"讲得非常具体。模型读到的不只是一句"你要遵守 TDD"，而是一套可以用代码逐行解释的操作序列。这也是我建议所有想深入了解 superpowers 的人都去通读一遍技能文件的原因——你会发现，原来 AI 的"超能力"不是什么魔法，而是把好习惯写成了文档。

3. 实操：从安装到在项目里真正用起来

3.1 安装前的基础环境

先把前提条件说清楚，免得你装到一半发现缺东西。

你需要准备：

• 一个能跑 AI 编程代理的终端环境。目前主流的宿主就是 Claude Code 和 Codex CLI，至少装其中一个。
• Node.js 18 及以上版本。虽然 superpowers 本身很大程度上是 Markdown 文件，但它的加载脚本和命令工具是用 JavaScript 生态跑的，所以 Node 环境绕不开。
• Git 环境。技能文件本身要 clone 下来，而且很多技能在运行时会调用 git 来查看差异、创建提交，所以 Git 必须可用。

安装前我习惯先跑一遍版本检查，比如node --version、git --version，确认没有奇怪的报错再去装技能。一个小坑：如果你用的是公司内网环境，clone GitHub 仓库前记得先把代理配好，不然极容易卡在下载那一步。

注意：不同宿主的技能加载机制差异很大，版本更新也快，下面的步骤我以最常见的做法为准，具体细节请以项目 README 的最新说明为准。不要把这篇博文当成永远不变的官方文档。

3.2 两种常见安装方式

方式一：宿主支持插件机制（以 Claude Code 为例）。

新版 Claude Code 有插件系统，直接用命令行安装：

claude plugin install superpowers

装完之后，在对话界面里输入/应该就能看到 superpowers 相关的斜杠命令，比如/superpowers、/thinking之类。这种方式最省事，升级也方便，适合绝大多数人。

方式二：手动把技能目录挂到宿主能读到的位置。

如果你用的宿主暂时没有插件市场，或者你想自己 fork 一份技能文件来改，可以用手动安装。先把仓库 clone 下来：

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

然后把 skills 目录链接到宿主的技能加载位置。Claude Code 默认会读~/.claude/skills，所以可以这样：

ln -s "$(pwd)/superpowers/skills" ~/.claude/skills

如果你希望只在某个项目里启用，就把技能目录放进项目的.claude/skills目录，这样不同项目可以用不同版本的技能。

手动安装的核心逻辑是：搞清楚"你的宿主从哪个目录读取技能文件"，然后让 superpowers 的 skills 目录出现在那里。理解了这一点，你就不会因为换了个宿主就手足无措。

3.3 验证安装是否成功

装完之后别急着开干，先花两分钟验证。

在对话里直接输入/superpowers，正常会列出可用的技能列表。如果宿主没有斜杠命令机制，你直接问一句"你现在能使用哪些技能？请列出文件名和适用场景"，模型应该能报出一串名字。

我更推荐用一个真实的小任务来验证。比如丢给它一个空模块，说"帮这个模块补一个测试"，然后观察它的行为。如果它会先跟你确认测试目标、再写失败用例、再跑测试，那基本可以确定技能已经被加载并生效了。如果它直接开始噼里啪啦写实现，说明技能文件没被正确加载，回到 3.2 检查目录路径。

3.4 Codex 里怎么用 superpowers

热词里 codex superpowers 被问得很多，因为 Codex CLI 没有 Claude Code 那样完整的插件市场，很多人在这一步卡住。

Codex 的约定是读项目里的 AGENTS.md 文件，这个文件相当于给 AI 的"项目工作手册"。你可以这样操作：

第一步，把 superpowers/skills 目录放进项目的某个路径，比如.claude/skills或docs/skills，路径本身不重要，重要的是在 AGENTS.md 里写清楚位置。

第二步，在 AGENTS.md 里加上一段：

本项目启用 superpowers 技能框架。技能文件位于 .claude/skills 目录。 所有开发和修改任务，先阅读技能列表，然后按对应技能的步骤执行。

第三步，重启 Codex 会话，让它重新读取 AGENTS.md。然后随便丢一个任务测试，看它是否会先去翻技能文件。

Codex 的加载方式不像插件那么自动化，但反而更透明——你能清楚地看到 AI 是怎么理解你给它的规则手册的。如果你发现它不遵守，多半是 AGENTS.md 里的描述不够强硬，可以改成"你必须先读取 xxx skill，不得跳过其中任何步骤"。

3.5 Java 项目实战：给 Spring Boot 服务加一个查询接口

热搜词里有 superpowers java，我特意用 Java 场景演示一遍，因为 Java 项目往往对工程规范要求更高，也更适合体现技能框架的价值。

我本地有一个 Spring Boot 项目，核心服务类长这样：

@Service public class UserService { private final UserRepository userRepository; public UserService(UserRepository userRepository) { this.userRepository = userRepository; } // 需要一个按邮箱精确查找用户的方法 }

我直接在对话里说："用 superpowers 的 TDD 技能，给 UserService 加一个 findByEmail 方法，邮箱不存在时抛 UserNotFoundException。"

随后 AI 开始按技能流程走。它先是跟我确认验收标准："邮箱存在时返回用户对象；邮箱不存在时抛 UserNotFoundException；参数为空时抛 IllegalArgumentException。" 确认完，它先写了测试：

@Test void findByEmail_shouldReturnUser_whenUserExists() { User user = new User("alice@example.com", "Alice"); userRepository.save(user); User found = userService.findByEmail("alice@example.com"); assertThat(found.getEmail()).isEqualTo("alice@example.com"); } @Test void findByEmail_shouldThrowException_whenUserNotExists() { assertThatThrownBy(() -> userService.findByEmail("nobody@example.com")) .isInstanceOf(UserNotFoundException.class); }

然后跑测试确认它失败，再写最小实现：

public User findByEmail(String email) { if (email == null || email.isBlank()) { throw new IllegalArgumentException("email must not be blank"); } return userRepository.findByEmail(email) .orElseThrow(() -> new UserNotFoundException(email)); }

最后再跑一遍测试，全部通过。整个过程和没有技能时的差别很明显：AI 不会跳步骤，它从头到尾都知道自己要干什么，也没出现那种"写到一半开始自由发挥"的毛病。Java 项目尤其适合这套玩法，因为测试文化本来就是 Java 工程里绕不开的一环，AI 主动帮你把测试补上，后续合并代码时省很多沟通成本。

3.6 如果宿主是 WordBuddy 这类集成工具

也有朋友问，worbuddy 怎么用 superpowers，或者 WordBuddy 这类集成工具能不能用。这类工具本质上是把多个 AI 能力包了一层入口，superpowers 对它们来说就是"一套可挂载的技能集合"。

我的建议是先去工具设置里找"技能目录"或"外部 Skills"之类的配置入口，然后把 superpowers/skills 的路径指过去。如果没有这个入口，再看它支持不支持自定义指令（通常在设置里叫 Custom Instructions 或 System Prompt），把技能文件的加载规则写进去，让模型每次启动时先读取技能列表。

不过说实话，如果你用的是这类工具，说明你更看重"开箱即用"，那 superpowers 的收益会被打一些折扣。它的优势是裸奔在终端里时带来的完全控制感，集成工具层层封装反而会让技能的加载过程变得不可见，出问题时不好排查。

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

4.1 装了技能，但 AI 完全不按流程走

这是最常见的坑。现象是技能明明装了，但让它做任务时，它还是老一套——直接给实现、跳过测试、也不问验收标准。

优先检查这三件事：

• 看宿主工具版本。Claude Code 的技能机制是后面才加的，如果你的版本太老，斜杠命令可能根本不存在。
• 看技能是否被加载。在对话里输入命令列出技能，如果列表是空的，说明目录没接上。
• 看模型版本。太弱的模型即使读到了技能文件，也可能执行不好，建议使用 Claude 3.5 Sonnet 以上的模型或同等能力的模型。

还有一个土办法：直接把技能文件全文贴给 AI，告诉它"现在按这个技能的步骤执行我这个任务"。如果这样它还不遵守，那就是模型能力或版本问题；如果这样能遵守，说明是加载环节出了问题，回 3.2 检查目录路径。

4.2 技能目录加载失败

手动安装最常见的问题是符号链接坏了，或者路径写不对。clone 完之后先自己看一眼目录结构：

ls -la ~/.claude/skills

如果发现是空的，多半是软链没建成功。还有朋友 clone 到一半网络断了，导致 skills 目录里缺文件，也会表现为加载失败。这种情况重跑一次git clone或者git pull就好。

Windows 下还要注意：ln -s可能需要管理员权限，或者改用 mklink。如果是在 Git Bash 里操作，直接用ln -s通常没有大问题，但在 CMD 或 PowerShell 里就得用不同的命令。

4.3 多个项目之间技能版本打架

如果你同时维护多个项目，全局只放一份技能文件可能会出问题。比如 A 项目用 v1.0 的技能，B 项目需要 v1.2 的新规则，全局目录一更新，所有项目跟着变。

我的做法是：全局目录只放最通用的技能，项目目录放和当前项目强相关的技能，然后在项目里锁版本。具体可以用 Git submodule 或者直接在项目里用单独的目录放一份 fork 出来的技能文件。

这样做的成本是多一份文件，收益是可控性。尤其团队协作时，大家统一用项目里的技能版本，才不会出现"我的机器上 AI 会写测试，你的机器上 AI 不写测试"这种事。

4.4 AI 生成的测试质量太差

技能框架能保证流程，但保证不了质量。如果 AI 写的测试都是"为了通过而通过"的写法，比如断言一个函数返回了某个固定值，但没有真正覆盖行为，问题往往出在两处：一是模型对业务理解不够，二是技能里的验收标准不够具体。

我的经验是：在任务描述里把边界情况写清楚，比如"邮箱为空时是什么行为""不存在时是什么行为"“大小写敏感不敏感”。验收标准越明确，AI 写的测试就越有针对性。别指望技能文件替你理解业务，它是流程外套，不是领域专家。

4.5 常见问题速查表

我的建议是：每次升级 superpowers 之前，先把你 fork 出来的技能文件 diff 一下，看看官方改了什么。不要盲目合并，因为新规则很可能和你团队的现有流程冲突，看清楚再动。

我在自己项目里用得最多的其实是 brainstorming 和 TDD 两个技能。刚开始也会怀疑：无非是一堆 Markdown，凭什么让 AI 变强？直到有一天，我让 AI 为一个前端组件补测试，它老老实实先写了一个"渲染后出现错误提示"的失败用例，然后才写实现——那一刻我意识到，模型缺的从来不是知识，而是一套工作方法。superpowers 就是把老工程师脑子里的那套标准流程固化给 AI 的黏合剂。工具迭代很快，功能边界一直在变，但思路是通的。建议你装好之后，别急着投入生产，先把两三个技能文件从头到尾读一遍，你会比 AI 更了解它自己。