企业官网建设流程全解析

最近在AI编程助手圈子里，superpowers这个词的出镜率越来越高。它不是一个新模型，也不是传统意义上的IDE插件，而是一套给Claude Code这类agentic编程工具安装“技能系统”的开源框架。如果你也受够了AI助手只会泛泛给建议、却不会按工程规范把活干完，这篇东西值得看完。我会从它的原理讲起，把安装、实战、自定义技能、问题排查全部过一遍，最后附上我个人用下来的真实体会。

先说结论：superpowers本质上是一套“技能包集合”，它把测试驱动开发、调试、代码审查、重构、规划这些软件工程方法论，固化成AI能按步骤执行的标准流程。用上它之后，AI写代码不再是“一口气给你几百行”，而是老老实实先写失败测试、再写最小实现、最后重构。这种体验差异，用过一次就很难回去。

1. 先搞清楚superpowers是什么：它解决的其实是一个“流程”问题

1.1 为什么叫superpowers：把工程方法论变成AI的“肌肉记忆”

很多AI编程工具用起来别扭，根源不在模型能力，而在“流程缺失”。模型知道TDD是什么，但它不知道你在当前项目里想不想走TDD，也不知道你团队的代码规范长什么样。普通提示词像是口头叮嘱：“你记得写测试啊”。而superpowers做的事情，是把一套完整的、可复用的操作手册装进AI的上下文里，让它明确知道“当前任务应该按照什么步骤执行”。

这个项目出自Jesse Vincent（GitHub账号obra）之手，核心思路非常朴素：把能力拆成一个个独立的技能目录，每个技能目录里放一个SKILL.md文件，AI在需要的时候按目录加载对应手册。这种设计像极了给新员工发SOP手册，而不是指望他靠“悟性”干活。实际用下来，它解决的问题确实就是这个：让AI的行为从“自由发挥”变成“有章可循”。

所以“superpowers”这个名字起得挺准。单靠模型本身，是一个大而全但不够精的通用大脑；装上一堆技能之后，它才真正拥有了“会做TDD”“会做调试”“会做代码审查”这些专项能力。换句话说，模型是引擎，superpowers是给引擎配的一套套专业工具。

1.2 核心机制拆解：SKILL.md、斜杠命令和hooks是怎么配合的

要理解superpowers，只需要看懂三样东西：SKILL.md、斜杠命令、hooks。

SKILL.md是每个技能的核心文件，用Markdown写成。文件里通常包含一段YAML格式的frontmatter，写明技能名称、触发条件、适用场景，后面正文则详细描述执行步骤、输出格式、注意事项。AI每次加载这个技能时，实际上是把这整份Markdown作为指令注入对话上下文。为什么选择Markdown而不是JSON？因为Claude这类模型对自然语言的解析成本最低，Markdown的层级标题、列表、表格都能被模型精准理解，写起来也比JSON容易得多。

斜杠命令是触发的入口。安装superpowers之后，在Claude Code里输入斜杠，会出现一长串以superpowers开头的命令，比如/superpowers:test-driven-development、/superpowers:debugging。你不需要背技能名，输入斜杠后会有补全提示。选择某个技能后，AI会把对应SKILL.md里的流程“读进脑子”，然后开始执行。这个设计让我联想到游戏里的技能栏，想用哪个点哪个。

hooks解决的是“AI并不知道自己该用哪个技能”的问题。superpowers会在安装时注册会话启动hook，每次Claude Code新开会话，它都会主动把技能索引注入系统提示词，告诉AI“你拥有以下技能，遇到对应场景时记得主动使用”。没有这一步，AI就永远只是“被动等待用户点技能”，不够智能。

这三层配合起来，效果是这样的：新开会话时hooks告诉AI有哪些技能可用；用户遇到问题时，AI判断场景并主动建议使用某个技能；用户确认后，斜杠命令加载对应SKILL.md，AI开始按章办事。整个过程没有黑魔法，全是文件、命令和提示词。

1.3 热搜里的codex superpowers是怎么回事

最近不少人在搜“codex superpowers”，我的理解是大家想知道这套技能机制能不能用在OpenAI Codex CLI上。先说结论：superpowers原生的目标环境是Claude Code，它依赖Claude Code的skills目录和hooks机制，Codex CLI目前并没有完全等价的机制，不能直接装完就用。

但这不代表思路不能迁移。Codex CLI支持AGENTS.md作为项目级指令文件，你可以把superpowers里某个SKILL.md的核心步骤、输出格式精简之后写进AGENTS.md，让Codex在项目里也能拥有类似的“流程约束”。我自己试过把TDD技能的手册压缩成两页AGENTS.md指令，效果虽然不如Claude Code原生那么顺滑，但比裸用强很多。

如果你本来就在用Codex CLI，又不想放弃superpowers的思路，还有一条路：日常编码用Claude Code加superpowers，Codex作为交叉验证工具。两边各干各擅长的，这其实是不少人的实际用法。

2. 安装superpowers：两种方式，十分钟跑起来

2.1 安装前先确认三样东西

装superpowers之前，先花一分钟确认环境。第一，你得有Claude Code，并且已经能在终端里正常启动，版本不要太老，最好保持最新，因为它依赖Claude Code的skills和hooks能力，早期版本支持不完整。第二，机器上得有git，因为安装方式本质上就是从GitHub拉代码到本地。第三，正常网络环境，安装脚本要从GitHub下载仓库，这一步卡住会直接失败。

我在macOS和Linux上都装过，Windows这边建议先装好WSL，在WSL的终端里使用Claude Code和superpowers，体验会稳很多。不是Windows不能用，而是很多AI编程工具链的调试、路径处理在Linux环境下更顺畅，没必要给自己添堵。

另外提醒一句：在公司的受限网络环境下，GitHub访问不稳定的话，安装脚本很可能卡在clone那一步。遇到这种情况，网上一部分教程会教人开代理，我这边不展开这类操作，建议直接走手动安装方式，或者找一个能正常拉取代码的网络环境再装。

2.2 官方脚本安装：一条命令搞定

superpowers官方提供了脚本安装方式。命令格式大概是这样的（具体以项目仓库首页README为准，官方如果调整了安装地址，README会最先更新）：

curl -fsSL https://superpowers.obra.dev/install.sh | bash

执行后脚本会自动做几件事：检查当前环境有没有Claude Code，把superpowers仓库clone到本地的~/.claude/skills/目录，注册hooks配置，最后打印一段提示告诉你安装完成。整个过程不到一分钟。

这里有一个很多新手会犹豫的点：直接把远程脚本管道给bash执行，安全吗？我的习惯是先下载下来看一眼再执行，虽然多一步，但图个安心：

curl -fsSL https://superpowers.obra.dev/install.sh -o install_superpowers.sh less install_superpowers.sh bash install_superpowers.sh

脚本内容其实没什么玄机，无非是clone仓库、创建目录、写入配置文件。看过一遍之后，你对整个安装机制心里就有数了，后面排查问题也更容易。

2.3 手动安装：想自己掌控目录结构的选这条路

不喜欢一键脚本的话，手动安装其实也就三条命令的事。第一步，把仓库clone到Claude Code的技能目录：

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

第二步，确认目录结构是否正确。装完之后你的~/.claude/skills/下面应该长这样：

~/.claude/skills/ └── superpowers/ ├── skills/ │ ├── test-driven-development/ │ │ └── SKILL.md │ ├── debugging/ │ │ └── SKILL.md │ ├── code-review/ │ │ └── SKILL.md │ └── ... └── hooks/ └── ...

第三步，检查Claude Code的配置文件（通常是~/.claude/settings.json），确认hooks里包含superpowers的会话启动hook。脚本安装会自动写入这一步，手动安装时如果漏了，AI就感知不到技能存在。

手动安装最大的好处是路径可控。你可以把技能目录放到项目级配置里，做到不同项目用不同技能集。比如个人项目只挂TDD和debugging，团队项目额外挂code-review和planning。这种粒度控制是脚本安装默认不提供的。

2.4 安装完之后怎么验证

装完别急着写代码，先花两分钟验证。第一步，重启Claude Code。第二步，在对话框里输入斜杠/，看看补全列表里有没有superpowers相关的命令。如果有，说明技能已经被Claude Code识别到了。第三步，随便触发一个技能，比如/superpowers:test-driven-development，观察AI的回应。正常的回应应该是“我会按照TDD流程执行：先写失败测试，再写最小实现，然后重构”，接着开始和你确认需求。

如果输入斜杠后什么都看不到，优先检查两个地方：路径是不是~/.claude/skills/superpowers，hooks配置是不是写对了。这两个问题占了八成以上“装完没反应”的情况，具体排查思路我在第五章展开。

还有一个很容易被忽略的点：Claude Code如果需要登录会话，重启后要确认会话是正常状态。我遇到过好几次技能列表拉不出来，结果只是登录态过期了，重新登录就一切正常。

3. 实战推演：在Java项目里用TDD技能写一段真实代码

3.1 为什么Java场景是最典型的用例

热词里有个“superpowers java”，说明不少人在Java项目里用这个工具，这其实非常合理。Java项目的工程化程度高，Maven/Gradle的构建生命周期严格，JUnit、AssertJ、Mockito这些测试框架成熟，特别适合套用TDD这类流程化技能。

打个比方，Java项目的结构像一条流水线：依赖管理、编译、测试、打包、部署，每一步都有明确规范。AI在这种环境里最怕的就是“乱来”，比如不写测试直接甩一个类出来，或者测试跑不过就顺手删掉测试。superpowers的TDD技能恰恰是治这个毛病的。

另外，Java类型系统严格，重构起来有编译器兜底，AI走“写测试→最小实现→重构”这条路径时，每一步都能得到快速反馈。我自己维护的几个服务端模块，配合superpowers的TDD流程后，review压力小了很多，因为AI会主动把测试的RED-GREEN-REFACTOR循环跑完整。

3.2 触发TDD技能后的完整流程

现在假设我们有一个需求：写一个订单价格计算器，订单金额大于等于1000元时打9折，小于1000元不打折。启动Claude Code后输入/superpowers:test-driven-development，AI会接管流程，第一步通常是让你用自然语言描述这个需求。

描述完之后，AI不会直接写实现类，而是先创建测试文件。它会在项目的src/test/java目录下新建测试类，并生成类似这样的测试代码：

import org.junit.jupiter.api.Test; import static org.junit.jupiter.api.Assertions.assertEquals; class PriceCalculatorTest { @Test void shouldApplyTenPercentDiscountWhenAmountIsGreaterThanOrEqualTo1000() { PriceCalculator calculator = new PriceCalculator(); assertEquals(100.0, calculator.calculateDiscount(1000.0)); } @Test void shouldNotApplyDiscountWhenAmountIsLessThan1000() { PriceCalculator calculator = new PriceCalculator(); assertEquals(0.0, calculator.calculateDiscount(999.0)); } }

注意这里AI做了一件很关键的事：先写测试，再等测试失败。它甚至会主动运行mvn test让你确认测试是红的。这一步看着简单，实际上拦住了无数“AI写完发现编译不了”的尴尬——因为编译都没过，AI根本不会继续往下走。

测试确认失败之后，AI才会写最小实现。这里的最小实现指的是“刚好让测试变绿”的代码，不多加一点额外逻辑：

class PriceCalculator { public double calculateDiscount(double amount) { if (amount >= 1000.0) { return amount * 0.1; } return 0.0; } }

然后再次运行测试，确认变绿。最后AI会进入重构阶段，检查有没有可以消除的重复代码、有没有更清晰的命名。这个过程看起来机械，但恰恰是TDD的精髓：小步快跑，永远不直接写一个“大而全”的类。

如果你的项目是Maven工程，记得确认pom.xml里配好了JUnit 5依赖，否则测试代码写得再漂亮也跑不起来：

<dependency> <groupId>org.junit.jupiter</groupId> <artifactId>junit-jupiter</artifactId> <version>5.10.2</version> <scope>test</scope> </dependency>

3.3 更高阶的玩法：把planning、debugging、code-review串起来

单一技能用顺之后，可以尝试组合使用。我目前比较顺手的组合是：planning排计划，TDD写代码，debugging救火，code-review兜底。

具体来说，接到一个稍微复杂一点的需求时，先触发/superpowers:planning，让AI把需求拆成任务清单，标出依赖关系和风险点。这个阶段输出的计划可以直接贴在项目文档里当开发计划。开始编码后，切到TDD技能，按照前面的流程一个任务一个任务推进。推进过程中如果测试挂得莫名其妙，不要自己瞎猜，触发/superpowers:debugging，AI会引导你走二分定位、日志补全、最小复现的排查路径。

代码全部写完之后，最后跑一遍/superpowers:code-review。它会站在审查者的角度逐文件过一遍，找出现有测试没覆盖的分支、可能出现的空指针、命名不一致等问题。很多问题在此之前我根本没意识到。

这几套技能串起来之后，整个开发节奏会变得非常“有仪式感”。AI不再是单打独斗的代码生成器，而是一个严格遵守开发流程的结对程序员。我个人体会是，流程感这个东西一旦建立起来，团队的代码质量和review效率都会明显提升。

4. 打造自己的超级技能：团队规范也能变成SKILL.md

4.1 写一个技能的四步法

superpowers的真正魅力在于可扩展。团队里那些反复强调的规范，与其靠AI“记住”，不如直接写成技能。写一个技能的步骤很固定，就四步。

第一步，在~/.claude/skills/superpowers/skills/下面新建一个目录，名字取个一看就懂的英文短句，比如conventional-commit。第二步，在目录里创建SKILL.md，用frontmatter写上技能名称、描述、触发场景，然后正文写清楚执行步骤。第三步，重启Claude Code或者让hooks重新加载技能索引。第四步，输入斜杠命令测试，看AI能不能正确读取并按步骤执行。

这个四步流程里，最重要的是frontmatter里的description。它决定了AI什么时候主动想起这个技能。描述写得太泛，AI会在不合适的场景里乱调用；写得太窄，AI该用的时候根本想不起来。我的经验是：description里明确列出触发条件，宁可多写几个典型场景，也不要只写一句模糊的话。

4.2 示例：把Git提交规范固化成技能

拿我团队的一个实际例子来说。我们要求所有Git提交信息必须符合Conventional Commits规范，格式是<type>(<scope>): <subject>，而且subject必须用祈使句、不超过50个字符。之前每次让AI生成提交信息，都要在提示词里重新写一遍要求，麻烦且容易漏。

现在我把这套要求写成一个技能，SKILL.md内容如下：

--- name: conventional-commit description: 当用户要求生成Git提交信息、创建commit、或准备提交代码时，使用该技能 when_to_use: 用户输入中包含“提交”“commit”“提交信息”等关键词 --- # Conventional Commit 技能 1. 提交信息格式必须为 `<type>(<scope>): <subject>` 2. type 枚举范围：feat, fix, refactor, docs, style, test, chore 3. scope 填写受影响模块名，不影响全局时省略 4. subject 使用祈使句，首字母小写，不超过50个字符 5. 正文部分按需补充，描述变更原因和影响

写完之后我在Claude Code里输入/superpowers:conventional-commit，再把改动文件路径告诉它。AI生成的提交信息就严格符合团队规范了。后续代码review时，因为提交信息不再需要人工纠正，省了一堆事。

这个例子说明一个道理：superpowers里的技能不一定要高深，把重复性规则固化下来反而是最实在的用法。编码规范、目录结构约定、接口设计约束，都可以做成技能。

4.3 几个容易翻车的点

自定义技能最容易翻车的点有三个。第一，正文太长。SKILL.md一旦超过两三屏，AI在上下文里读它的成本很高，而且重要信息容易被淹没。我的建议是一条技能只专注一件事，正文控制在200行以内，用步骤列表和示例说话。第二，命名冲突。如果你自己写的技能目录名和superpowers内置技能重名，可能导致加载时互相覆盖。命名前先看一眼现有技能列表。第三，忘记了“技能是针对流程的”这个本质。不要试图把某个具体业务逻辑塞进技能里，技能应该描述“怎么做”，而不是“做什么”。

还有一个深层一点的坑：技能之间的组合顺序。比如你定义了TDD技能，又定义了代码生成技能，两个技能同时被加载时AI可能分不清该先跑哪个。解决办法是在SKILL.md里写清楚“当本技能与其他技能冲突时，优先级如何”。这种元规则看起来不起眼，实际能避免大量行为混乱。

5. 常见问题与避坑实录：装了跑不起来，多半是这几种情况

5.1 安装脚本执行失败，先别急着重装

我见过最多的安装失败，就是curl管道执行到一半报错，常见原因有三个。第一个，网络问题导致clone不下来仓库。第二个，权限不足，安装脚本没有权限写入~/.claude/skills/目录。第三个，Claude Code版本太老，安装脚本检测到不兼容就直接退出。

遇到报错，第一反应不是反复重跑，而是先看错误信息卡在哪一步。如果是clone超时，检查git能否正常访问GitHub。如果是权限问题，看一下~/.claude/目录是不是root所有，有时候你用sudo装了Claude Code，后面普通用户就没法写入，这个问题在云服务器上特别常见。

网络这块我多说一句：不要在受限网络环境下反复硬试，换个思路，把人家的安装脚本下载到本地看一遍，依赖哪些仓库、写到哪些路径，然后手动执行，成功率会高很多。

5.2 技能列表里看不到superpowers

装完之后打开Claude Code，斜杠列表里看不到superpowers相关命令，这个问题的排查顺序非常固定。先确认路径：ls ~/.claude/skills/superpowers，如果目录不存在，说明clone位置错了。再确认hooks配置：打开~/.claude/settings.json，看hooks字段里有没有指向superpowers的启动hook。最后确认是不是当前项目级配置覆盖了用户级配置：有些项目根目录有自己的.claude/settings.json，里面的配置会叠加甚至覆盖用户级配置，导致hooks没生效。

还有一个小概率情况：Claude Code的skills功能本身没有在实验特性里打开。如果你用的是较老版本，需要在环境变量或者设置里手动开启Agent Skills相关开关。这个问题在新版本里基本不存在，但如果你的版本比较旧，就得注意。

5.3 为什么AI还是“不听指挥”：用法误区

有朋友反馈，装了superpowers之后AI该乱写还是乱写。这情况我基本能猜到原因：他根本没有触发技能，只是把superpowers当成一个“全局增强Buff”挂在那里。

hooks确实会把技能索引注入系统提示词，但它只是让AI“知道有这些技能”，不会自动强制每个任务都用技能。想让流程真正生效，要么你主动用斜杠命令触发，要么在对话里明确说“请使用test-driven-development技能来完成这个任务”。AI在上下文里看到技能清单，但它无法判断当前任务你想不想走流程，这时候你的明确指令就是开关。

另一个常见误区是把所有技能一次性都加载出来。技能加载得越多，上下文占得越大，AI反而容易抓不住重点。我的做法是：日常会话只让索引提示词存在，不主动加载；等到要专项干活时，再精准加载那一个技能。这就像工具箱里的工具，需要用扳手的时候拿扳手，没必要把整个工具箱倒在地上。

5.4 哪些任务千万别用superpowers

最后说一个很多人没注意到的点：superpowers不是所有任务都合适。它的核心价值在于“流程”，而那些追求快速探索、一次成型的任务，用它反而拖节奏。

我用下来，适合用superpowers的场景包括：新模块开发、Bug修复、代码重构、代码审查、技术方案规划。不适合的场景包括：临时调试一段一次性脚本、快速验证某个API能不能用、脑暴一个思路。这类任务的核心是“快”和“灵活”，硬套TDD流程会显得很笨重。

还有一类场景需要特别小心：性能调优。superpowers里的debugging技能擅长逻辑错误排查，但性能瓶颈往往涉及复杂的运行时行为，不是简单走个流程就能定位的。这时候更需要的是profiler和经验判断，把流程技能硬往上套很可能南辕北辙。

下面用一张表总结我个人的技能使用策略：

我个人在实际使用中的体会是：superpowers最大的价值不在于某一个技能有多神奇，而在于它让“AI按规范干活”这件事变得可复用、可传播。过去团队沉淀的工程实践都留在文档里、人脑子里，现在可以固化成一个技能文件，跟着仓库走。新成员加入、新项目启动，拉下来就能用。

最后再分享一个扩展思路：可以把你自己最常用的几个技能整合成一份精简的Cheat Sheet，放到项目根目录的CLAUDE.md里。这样即使某个队友没有安装superpowers，AI也能通过CLAUDE.md获得最核心的流程约束。算是一套渐进式的落地方式——先让尝鲜的人用全量技能，再让整个团队通过轻量级提示词跟上节奏。