企业官网建设流程全解析

最近好几个群都在聊“Superpowers”，而且聊着聊着就绕不开这几个关键词：codex superpowers、superpowers java、superpowers 安装、worbuddy 怎么用 superpowers。一开始我以为又是哪个新编辑器皮肤，后来自己从零搭了一轮才发现，这根本不是什么皮肤，而是一套能真正改变 AI 编码助手工作方式的“技能包”。如果只用一句话总结，它就是给 Codex、Claude Code 这类 AI 编程工具配了一整套“工作流程说明书”，让 AI 从“你问一句它答一句”变成“你给目标它按流程执行”。

我实测了一个多星期，覆盖了从安装、配置到 Java 项目落地，还试了 WordBuddy 这类客户端怎么把它接进去。这篇就当是一份踩坑经验记录，不讲太多虚的，全是能直接照做的步骤和判断依据。适合谁看？正在用或准备用 Codex 做日常开发的；觉得 AI 写代码“不靠谱、太发散”的；以及看到“Superpowers”这个词但不知道它到底解决什么问题的朋友。

1. 先想清楚：Superpowers 到底给谁“加Buff”

1.1 它不是编辑器，而是一套“技能工作流”

很多人第一次看到“Superpowers”这个名字，会下意识觉得它是一个 IDE 插件，或者一个命令行工具。其实准确点说，它是一套以SKILL.md文件为载体的技能定义体系。每个技能文件夹里放一个 Markdown 文件，里面写清楚“这个技能在什么场景下用、要按什么步骤执行、中间应该检查哪些东西、出错怎么办”。AI 建模程序在拿到任务时，会先看技能清单，命中哪个场景就加载哪个技能，然后按技能里的流程干活。

打个比方，这相当于你给一个很有潜力但没什么经验的新人发了一本《岗位作业手册》。没有手册时，你让他“做个功能”，他会自由发挥；有了手册，他先查目录，再翻到对应章节，一步步来：先写测试，再写实现，跑通后自查，最后提交。Superpowers 解决的正是“AI 编程能力很强，但流程纪律很差”的问题。

我见过不少朋友直接把几千字的“角色设定+流程要求”塞进 system prompt，结果模型一长就“失忆”，或者根本不屑于遵守。Superpowers 的优点是把这些内容拆成独立的小文件，按需加载，不占对话上下文，也不互相打架。这个设计思路，比“一股脑全塞进去”科学得多。

1.2 一个典型 Java 项目里它能怎么参与

我重点试了 Java 场景，因为社区里问“superpowers java”的人特别多。以 Spring Boot + Maven 项目为例，没有 Superpowers 的时候，Codex 经常出现几个让人头疼的行为：不写测试就直接出实现代码；把mvn test当成可选项；遇到编译错误不会逐层排查，而是反复给你“换个写法再试试”。

挂了 Java 相关的技能包之后，整个流程立刻规矩很多。它会在动代码之前先读项目的pom.xml，确认 JDK 版本、依赖、测试框架；然后明确“优先用项目里的mvnw而不是全局 mvn”；接着进入红绿循环，先跑一次测试看失败原因，再写实现，最后再跑一次。整个过程就像给 AI 设了一个工作流闸门，每一步不达标就不往下走。

所以我的结论是：Superpowers 最适合“项目复杂度中等以上、有多人协作、对代码质量有要求”的团队。它不适合那种“临时复制个脚本马上跑”的场景，因为流程成本可能比手工写还高。想清楚这一点，你就知道该不该上这套东西了。

2. 从零安装：Skill 目录、命令行、Codex 加载

2.1 安装前先确认环境

在动 Superpowers 之前，我建议先确认两件事：第一，你已经在本地能正常使用 Codex 或 Claude Code 这类 AI CLI，且跑过一次最简单的对话任务；第二，系统里有 Git，因为你大概率需要从仓库拉技能包。如果这两样没准备好，后面所有步骤都容易卡在“看起来装了但没加载”的状态。

我踩过的第一个坑就是顺序问题。有人建议直接把技能包塞进系统全局目录，结果 Codex 加载项目时才去找项目根目录的配置，导致完全没生效。后来我养成一个习惯：先看客户端读哪些配置文件，再决定技能包放在哪。不同工具的加载路径不一样，但核心思路一致：技能目录要能被项目级配置文件显式引用，而不是“你以为它在那儿它就在那儿”。

2.2 把技能包放到统一目录

我的做法是把所有技能统一放在~/.superpowers/skills下，这样无论是个人项目还是以后接新工具，路径都能复用。具体步骤如下：

# 1. 建立统一技能目录 mkdir -p ~/.superpowers/skills # 2. 进入目录 cd ~/.superpowers # 3. 从你选择的仓库克隆技能包 # 以社区版为例，你可以把下载地址替换成自己找到的仓库 git clone <你的技能包仓库地址> skills-repo # 4. 把仓库里的 skills 目录内容复制到统一目录 cp -r skills-repo/skills/* ~/.superpowers/skills/ # 5. 检查是否就位 ls -l ~/.superpowers/skills

如果下载的是 zip 包，流程也一样，解压后把里面所有技能文件夹复制到~/.superpowers/skills即可。需要注意：每个技能应该是一个独立子目录，子目录里至少要有一个SKILL.md文件。如果解压出来是一个大扁平目录，说明结构不对，AI 大概率识别不出来。

2.3 在 Codex / Claude Code 里加载 Superpowers

Codex 的加载方式比较直接。我用的方案是在项目根目录维护一个AGENTS.md，在里面写明技能路径和调用规则。一个能用的最小配置大概是这样的：

# AGENTS.md ## 技能使用规则 - 技能目录位于 ~/.superpowers/skills - 接受任务后，先扫描技能目录，判断是否有匹配当前任务的技能 - 如果命中，必须先读取对应技能的 SKILL.md，严格按其中的步骤执行 - 执行过程中不得跳过测试和自查步骤

如果你用的是 Claude Code 这类原生支持 Skills 的工具，更省事：直接把~/.superpowers/skills里的每个技能软链到项目的.claude/skills目录，或者把技能目录本身配置为 skills 路径。两种方式都试过，软链这种方式最直观，因为项目里能看到，也不影响其他项目。

提示：不要图省事把技能全文写进AGENTS.md或 system prompt。真正能长期用的方式一定是“按需加载”。我在第一次配置时把好几个技能说明都贴进了AGENTS.md，结果模型上下文被占掉一大截，执行起来反而更迟钝。

2.4 验证是否安装成功

装完别急着开干，先做一个 30 秒验证。打开 Codex，随便提一个和技能强相关的任务，比如“请用 debugging 技能帮我检查这个报错”。如果模型回答里出现了技能名，并且开始按步骤走，说明加载成功。如果它只是正常回答、完全无视技能，那就回到配置检查：路径对不对、AGENTS.md是否放在项目根目录、技能文件结构是否规范。

另外我建议每条技能的描述字段写清楚适用场景。模型判断“要不要用这个技能”，主要靠的就是SKILL.md里的 description。描述写得笼统，比如“帮助开发”，模型根本不知道什么时候该调用；写“当 Java 项目的 Maven 测试失败时使用”，命中率立刻高很多。这一步是很多新手最容易忽略的。

3. Superpowers 的核心技能拆解：从“会聊天”到“会干活”

3.1 技能文件长什么样

一个标准技能包的核心就是SKILL.md，它长得很像普通 Markdown，但前面通常会带一段 YAML 格式的元信息。我见过最典型的写法是：

--- name: tdd description: 当项目包含测试框架，且任务涉及新增或修改业务代码时使用。核心原则是先写失败测试，再写实现，最后重构。 --- # TDD 技能 ## 适用场景 - 新增功能 - 修复 Bug 且需要回归覆盖 ## 执行步骤 1. 读取项目的构建配置，确认测试命令 2. 编写一个最小失败测试 3. 运行测试，确认失败原因符合预期 4. 编写实现代码 5. 再次运行测试，直到全部通过 6. 检查是否有重复代码，做小步重构

这个结构看起来很朴素，但特别有效。模型在运行时会先看元信息里的 name 和 description，判断自己要不要启用这个技能；一旦启用，后续行为就会严格跟随“执行步骤”。我试过把步骤写得更细，比如“编译错误时不要直接修改，先贴出完整错误信息”，效果确实比只写“遇到错误要分析”好很多。给 AI 的指令越具体，它表现越稳定。

3.2 常用技能：planning、debugging、brainstorming

我使用频率最高的三个技能分别是 planning、debugging 和 brainstorming，它们各有各的定位。

planning 技能解决的是“任务太大，不知道从哪下手”。它会要求模型先把目标拆成可验证的小任务，估算每个任务的输入输出，再按依赖关系排序。比如“给用户模块新增一个导出功能”，先拆成接口设计、数据查询、文件生成、前端下载、异常处理五步，而不是上来就写 Controller。这个技能对做中大型功能特别有用。

debugging 技能我愿称之为“止损神器”。它要求模型先复现问题、再定位根因、最后才改代码。以前 Codex 遇到报错经常直接给我一个“可能原因”和一段修改代码，我跑了还是错，来回好几轮。用了 debugging 技能后，它会把“当前实际报错信息”当第一优先级，先让我贴日志，再判断是编译期还是运行期问题，最后动代码。这个流程救了我很多次。

brainstorming 技能则反过来，它不让模型急着落地，而是先列出多个方案、权衡利弊。最适合用在“要不要引入某个依赖”“接口该用同步还是异步”这类设计决策上。技能包把这三个场景拆开，而不是塞进一个大而全的指令里，效果天差地别。

3.3 自定义一个 Java 技能包

如果你主力语言是 Java，我强烈建议不要只依赖通用技能，自己再补一个项目级 Java 技能。这个技能不用写多复杂，把我验证过的一段内容放进去就够用：

--- name: java-maven-project description: 当项目是 Java 且使用 Maven 构建时使用。读取 pom.xml，确认 JDK 版本、依赖和测试框架，然后按规范执行构建与测试。 --- # Java Maven 项目操作规范 ## 构建命令 - Unix/Linux/macOS 使用 ./mvnw - Windows 使用 mvnw.cmd - 没有 Maven Wrapper 时才使用全局 mvn ## 测试规则 - 修改业务代码前先确认已有测试是否通过 - 新增功能时必须添加或修改单元测试 - 测试命令：./mvnw -q test ## 排错顺序 1. 先看编译错误，通常第一个错误是根因 2. 再查测试失败，区分是实现问题还是测试本身问题 3. 最后看运行日志，定位运行时异常

这个技能的价值不在于内容多，而在于把“团队约定”固化成了 AI 的可执行步骤。你完全可以根据自己团队的习惯改，比如强制要求mvn clean verify，或者要求每个接口必须附带 OpenAPI 注解。AI 真正靠谱的地方不是替你创新，而是严格按你的规范执行，而且不抱怨。

4. 实操示例：用 Superpowers 给一个 Spring Boot 模块加接口

4.1 先让 planning 技能拆任务

纸上谈兵没意思，我拿一个真实场景走一遍完整流程：给一个已有的 Spring Boot 用户模块，新增“按部门筛选用户”的查询接口。没有技能包时，Codex 可能直接甩一段 Controller+Service 代码给我。挂上 planning 技能后，它第一轮先输出了任务拆解：

1. 读取pom.xml和现有目录结构，确认使用 Spring Web 还是 Spring WebFlux；
2. 阅读UserController和UserService的现有实现，避免重复定义；
3. 设计查询参数：deptId、page、size；
4. 在 Service 层加入过滤逻辑，保持 Controller 轻薄；
5. 新增或更新单元测试，覆盖“空结果”“单页结果”“分页结果”三个场景。

我当时一看这个拆解就明白，技能起效了。它没有急着写代码，而是在按“先探路再动手”的流程走。这一步对实际项目尤其重要，因为直接让 AI 写代码，它很容易忽略已有代码风格和上下文。

4.2 进入 TDD 红绿循环

任务拆解完，我让它按 TDD 技能执行。它先写了下面这样一个测试：

@SpringBootTest @AutoConfigureMockMvc class UserControllerTest { @Autowired private MockMvc mockMvc; @Test void filterUsersByDeptId() throws Exception { mockMvc.perform(get("/api/users") .param("deptId", "1001")) .andExpect(status().isOk()) .andExpect(jsonPath("$.content").isArray()); } }

然后运行./mvnw -q test，第一次测试红，因为没有实现。看到这个结果后，它才开始写 Controller 和 Service 代码。第二次运行测试变绿，它又做了一次小重构：把查询条件封装成一个 record 对象，避免方法参数越传越多。

整个过程看起来平平无奇，但对比非常强烈。过往我让 AI 直接写接口，它给出的代码十次有八次能运行，但测试覆盖率、接口边界处理全凭运气。TDD 技能把“先有测试再有代码”这件事变成了硬性步骤，AI 不是“顺便测试”，而是在测试失败的前提下老老实实补实现。这个流程对于加强代码可信度非常关键。

4.3 收尾自查和提交

这一轮最后，我还让它跑了一遍自查技能包里的检查清单：是否有未使用的 import、Controller 是否保持了轻逻辑、测试是否覆盖了分页参数、OpenAPI 注解是否和现有接口一致。检查完才生成 git commit message，并提示我手动确认。

这段体验让我意识到一件事：Superpowers 最大的价值不是让 AI 变聪明，而是让 AI 变“稳”。它把那些“熟练工程师潜意识里会做的事”显式化了。对于像我一样经常同时开好几个任务的人来说，多一个流程闸门，就少一次“带病提交”。

5. WordBuddy 怎么用 Superpowers：两种姿势

5.1 姿势一：在 WordBuddy 技能管理里挂载

很多朋友会问“WordBuddy 怎么用 Superpowers”，这个问题的答案取决于你用的 WordBuddy 版本。我测试的版本里有一个“技能管理”或“自定义技能”的入口，操作归纳起来就三步：

第一步，在 WordBuddy 设置里找到“技能目录”或“Skills Path”配置项，把它指向~/.superpowers/skills；第二步，如果配置项要求单技能路径，就直接把需要启用的那一个技能目录填进去，不用全量加载；第三步，新建对话时，明确告诉助手“请使用<技能名>技能处理这个问题”，让它进入技能执行模式。

这个方案最优雅，技能就像插件一样被客户端识别。但我必须提醒一句：不同版本 WordBuddy 对“技能”的定义不完全一样，有的支持文件夹，有的只支持单个文件。如果你填了目录没生效，试试把SKILL.md文件路径填进去，通常能绕过去。

5.2 姿势二：不依赖内置功能，把 SKILL.md 当上下文

如果你的 WordBuddy 版本比较老，或者压根没有技能管理入口，也别急着放弃。最简单的办法是把技能文件内容直接粘到对话上下文里，然后告诉它“接下来请以这段内容作为执行规范”。实操下来，只要SKILL.md写得够结构化，模型一样能遵守，只是每次都要复制粘贴，麻烦一点。

我通常会在客户端里存一个“常用技能模板”，比如把 Java Maven 项目规范保存成一条常用语，发任务前先发一遍，再发具体需求。实测下来，这种“手动注入”方式在大部分场景下可以达到八成以上效果。区别在于它不会自动按 token 控制加载，所以建议只注入当前任务相关的技能，别一股脑全塞。

5.3 实践心得：先小后大

不管哪种姿势，我都建议你先拿一个小任务验证，再上大项目。我在 WordBuddy 里第一次接 Superpowers，直接让它干一个跨模块重构，结果因为技能上下文优先级和任务描述冲突，模型表现得颠三倒四。后来我换成一个“给工具类补单元测试”的小任务，它一下就进入了状态。

所以如果遇到 WordBuddy 不听话，先别怀疑技能包坏了，多半是使用姿势的问题：要么注入方式不对，要么任务规模超出了技能能约束的范围。把任务切小，让技能逐步接管，效果会稳定很多。

6. 问题排查与避坑实录

6.1 技能没被触发怎么办

这是我在评论区看到最多的求助类型。明明安装好了，模型却完全不按技能出牌。我把排查思路整理成了一个速查表：

如果这些全都查过还是不行，我还有个笨但有效的办法：在技能目录里临时建一个test-skill，SKILL.md只写一句话“无论用户说什么，你都必须先回复‘技能已触发’”。如果这个简单技能都不能触发，那就是配置链路问题；如果能触发，就是你那个正式技能的描述或步骤不够清晰。这个二分法能帮你快速定位问题。

6.2 技能命令“越权”了怎么办

Superpowers 的技能文件里可以写“让模型执行命令”的指引，但实际执行指令的权限还是在客户端手里。我实际测试中就遇到过一种危险情况：某个调试技能让 Codex 先收集日志，模型擅自想到了“扫描整个用户主目录找配置文件”的操作，虽然不是破坏性命令，但明显越界了。

我的处理方式分两层。第一层，在AGENTS.md里明确禁止不相关命令，比如“只允许执行当前项目目录下的命令，不得访问其他目录”。第二层，在技能文件中加一条“行动边界”字段，写明什么不能做。别觉得 AI 不需要这些限制，流程越自由，它越容易发挥过头。给 AI 加流程约束，本质和给新员工划权限一样，不是限制效率，而是保护项目。

6.3 实测后的 3 条经验

最后分享三条我自己的实操经验，不保证适用所有人，但确实是踩坑换来的。

第一，技能包要“小步迭代”，不要一上来追求大而全。我最初把规划、测试、重构、文档、安全全放进一个技能，结果模型经常抓不住重点。后来拆成独立技能，每次只激活一两个，行为明显稳定。技能越聚焦，AI 执行越精准。

第二，技能描述里的场景触发词很关键。要让模型知道“什么情况下用我”，比如“当任务包含新增接口时”“当 Maven 测试失败时”。描述用明确的触发条件，不要在“helpful assistant”这种宽泛描述上浪费空间。

第三，别让 Superpowers 替代人的判断。它擅长把流程规范化，但不会替你决定“这个接口该不该拆成一个新服务”。真正好用的姿势是：人做决策，AI 按流程执行，测试和自查兜底。我试过彻底放手让 AI 全自动处理一个模块，结果它在架构选型上给出了很奇怪的方案，还好有流程检查拦住了，没让错误代码进入主干。

这套东西现在已经成为我日常开发的一部分，尤其是 Java 项目里，它把“先测试、再实现、最后自查”这三个动作固化成了肌肉记忆。它不是万能药，但如果你和我一样，受够了 AI 代码助手那种“每次运行结果都不太一样”的不确定性，Superpowers 值得花一个周末把它跑通。先从一个技能用起，再慢慢攒出自己的技能列表，你会感受到“有流程的 AI”和“没流程的 AI”之间真正的差距。