企业官网建设流程全解析

不知道你有没有这种感觉：Claude Code、Codex CLI 这类终端 AI 编程助手，刚用的时候确实很惊艳，但用上几天之后，你很快会发现它和自己理想中的“结对程序员”还差着一大截。你让它改 bug，它改完你总得再验证一遍；你让它写测试，它象征性写两个用例就停；你让它重构，它小心翼翼地换个函数名，然后反问你这行不行。这不是模型能力不行，而是你手里只有一个会写代码的对话窗口，没有一套能让它按工程方法论去干活的工作流。superpowers 就是来解决这个问题的。

简单说，superpowers 是一套开源的“AI 技能包”集合，专门给 Claude Code、Codex CLI 这类基于终端的 AI 编程工具做能力增强。它把测试驱动开发、调试、代码审查、重构、提交信息规范这些工程实践，封装成一个个可被 AI 直接调用的技能（skills）。你用一句话触发，AI 就会按照技能里定义好的步骤去执行，而不是信马由缰地直接吐代码。这篇文章我会从安装开始，拆解核心技能，再用一个真实任务带你跑完整条链路，最后把我在实践中踩过的坑和排查方法整理成速查表。无论你是刚开始接触终端 AI 编程的新手，还是已经在日常开发里重度使用 Claude Code 或 Codex 的老手，这篇内容都可以直接当参考手册来用。

1. 先搞清楚 superpowers 是什么：给 AI 助手上“技能包”

1.1 它到底解决了什么问题

你可能已经发现，直接让 AI 写代码的时候，它默认的行为是“尽快给出答案”。你问“这个函数怎么写”，它立刻给你一版代码；你问“这个 bug 怎么修”，它张嘴就猜一个可能原因。这种模式在小任务上没问题，但一旦涉及真实项目，问题就来了：它不会先写测试再实现，不会在改动之前确认需求边界，不会在重构前先看看现有测试是不是绿灯，甚至不会在提交代码前帮你把改动的范围捋清楚。

superpowers 的核心思路，就是把这些“好的工程习惯”变成 AI 可以执行的动作。它不是在提示词层面跟你说“请你认真一点”，而是把流程固化成文件，让 AI 面对特定场景时自动切换到对应的方法论。比如 tdd 技能被触发后，AI 会先分析需求、列出测试用例、生成测试文件、运行测试确认失败，最后才写实现代码。整个过程像一位有经验的工程师在带着新手做结对编程：不是替新手把活干了，而是教新手按正确顺序干活。

作者把这个项目命名为 superpowers，意思也很直白：在原有模型能力之上，给 AI 再加一层可组合的“超能力”。你不需要每次都在对话里长篇大论地叮嘱它“先写测试”“注意边界条件”“每步都要运行验证”，只要触发对应技能，这些规则全部由技能文件接管。

1.2 底层机制没那么玄：技能文件夹 + 指令文档

很多人第一次看到 superpowers，以为它用了多复杂的模型训练或者插件系统，其实底层机制非常朴实。整个项目干了两件事：第一，提供了一批结构化的技能文件；第二，提供了一个注册入口，让 AI 在每次对话开始的时候就知道这些技能的存在。

具体来说，每个技能就是项目里 skills 目录下的一个子文件夹，里面通常有一个类似SKILL.md的文件，描述了技能的触发条件、使用步骤、输入输出要求和一些限制规则。AI 读到这个文件，就像后端工程师拿到一份接口文档——它知道什么时候该用这个能力，以及用的时候每一步应该做什么。项目根目录下的AGENTS.md或CLAUDE.md则充当索引页，把技能名称、适用场景、调用方式列出，让 AI 在接收到用户请求时，能快速判断要不要调用某个技能。

你可以把这个机制理解成入职培训里的 S.O.P. 手册。正常人入职一家公司，不会什么工作都得靠师傅手把手讲一遍；团队会给你一本手册，上面写清楚“遇到订单退款看 37 页，遇到客户投诉看 52 页”。AI 也是一样，superpowers 做的不是让 AI 变聪明，而是让 AI 在合适的场景里能找到正确的操作手册，并且严格执行。这个设计最大的优势是可扩展：你完全可以在 skills 目录里加一个自己的技能，写清楚触发词和步骤，AI 马上就能用。

1.3 项目结构长什么样，为什么值得用

一个典型的 superpowers 项目仓库，结构大概是这样：

• skills/：所有技能的定义文件，每个技能一个子目录。
• AGENTS.md：给通用 AI 助手看的注册信息，Codex 这类工具靠它发现技能。
• CLAUDE.md：给 Claude Code 用的注册信息，Claude 靠它发现技能。
• install.sh：把技能目录安装到本机~/.claude/skills、~/.codex/skills等位置的脚本。
• 一些辅助脚本和文档。

为什么这种“技能文件 + 注册文档”的设计比写一个大提示词更值得用？原因很简单：模块化。单一提示词的长度有限，而且你没法按项目裁剪。今天想给 AI 增强测试能力，明天想加代码审查能力，全都堆在一个提示词里，上下文会越来越臃肿，AI 反而抓不住重点。技能包的思路是每个能力独立成文件，安装哪个用哪个，甚至同一个项目里可以只启用部分技能，想撤随时撤。

说白了，superpowers 很适合那些已经开始依赖 AI 编程工具、但又不满足于“AI 只给结果不给过程”的开发者。它让你重新拿回对 AI 工作方式的控制权，而不是被动接受模型随机的发挥。

2. 安装与初始化：从拉仓库到跑通第一个技能

2.1 安装前的准备工作

先别急着复制命令，花两分钟检查一下环境。superpowers 本质是一堆 Markdown 文件和少量辅助脚本，所以对环境要求并不高，但下面这几项是必须的：

• Git：用来克隆仓库和后续更新技能。
• 终端 AI 工具：至少装了 Claude Code 或 Codex CLI 其中一个，两者都装也没问题。
• 基本运行环境：很多技能会调用本机命令来跑测试、搜代码，比如 Python、Node.js、rg、jq这些。不需要全部装齐，但如果你做 Python 项目，python3和pytest最好得有；做前端就保证 Node 和包管理器可用。

我个人的建议是把 superpowers 仓库放在用户目录下的固定位置，比如~/superpowers，而不是放进某个正在开发的项目里。因为技能包是给所有项目公用的，放在全局位置，无论你在哪个目录打开 AI 工具，都能通过用户级配置访问到它。如果你把整个仓库塞进项目里，很容易在提交代码时把一坨技能文件误带上，而且跨项目复用还得重新配置，很麻烦。

2.2 安装到 Claude Code：自动脚本和手动方式都要会

superpowers 仓库里自带了一个install.sh，大多数情况下你直接跑它就行。以 macOS 和 Linux 为例：

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

脚本运行起来之后，一般会询问你要往哪个工具里安装，按提示选 Claude Code，它会把skills目录软链接到本机的用户配置目录，同时把CLAUDE.md里的技能注册信息合并到对应的配置文件。整个过程很快，基本几十秒搞定。

不过我还是建议你了解一下手动安装的逻辑，因为脚本不一定永远适配新版本工具，而且遇到问题时你知道去哪里改。手动装到 Claude Code 的精髓就两个字：路径。

• 把skills目录放到~/.claude/skills。
• 把仓库根目录的CLAUDE.md中关于 superpowers 的注册说明，合并到你的用户级~/.claude/CLAUDE.md，或者项目根目录的CLAUDE.md。

如果你在 Windows 上操作，软链接经常会有权限问题，我的建议是别折腾链接了，直接用复制命令把skills目录复制过去。功能上完全没区别，只是后续更新时稍微麻烦一点，更新脚本会告诉你如何覆盖。

2.3 安装到 Codex CLI：路径和文件名要调整

很多人在搜索里会用 “codex superpowers” 这个关键词，说明大家确实想让 OpenAI Codex 也用上这套技能。Codex CLI 和 Claude Code 的配置机制不太一样，Claude 认CLAUDE.md，而 Codex 这类工具更通用的是认AGENTS.md，配置目录默认在~/.codex。

安装到 Codex 的手动方式如下：

• 把skills目录放到~/.codex/skills。
• 把AGENTS.md中关于 superpowers 的注册部分，复制到你的~/.codex/AGENTS.md，或者当前项目的AGENTS.md。

因为 Codex CLI 的版本更新挺频繁，不同版本的配置路径可能略有出入，如果你用的是较新版本，最好在仓库里看看 README 或者 install 脚本是否已经增加了 Codex 支持。只要记住“技能目录放配置目录下、注册文档里写清楚技能索引”这个核心逻辑，路径变了也能自己摸出来。

2.4 怎么确认安装成功

装完之后不要急着直接开干，先验证一下 AI 是否真的感知到了这些技能。最简单的方式：新开一个对话，问它：“你现在加载了哪些技能？请直接列出可用的技能名。”

正常情况下，AI 会从注册文档里提取出技能列表，向你汇报。它会提到类似 brainstorm、tdd、debugging、code-review 这样的名称。如果它说“我不知道你在说什么”，九成是注册文档没生效，路径或者文件名的位置有问题。此时你手动去终端里看一眼：

ls ~/.claude/skills # 或 ls ~/.codex/skills

能看到技能目录并且里面有内容，说明文件是正常存在的，问题多半出在 AI 没有读取到注册信息，继续检查CLAUDE.md或AGENTS.md的合并情况。

这里要特别提醒一点：安装完成之后，一定要新开一个对话再验证。AI 的配置读取一般发生在对话初始化阶段，如果是在当前对话里装的技能，它认不出来很正常，别急着怀疑安装失败了。

3. 核心技能拆解：最值得优先启用的 5 类技能

3.1 测试驱动（tdd）：让 AI 学会“先证明错误再写代码”

tdd 是 superpowers 里最受关注、也最能改变人机协作习惯的一个技能。触发它之后，AI 不会再上来就写实现代码，而是严格按“红灯 - 绿灯 - 重构”的节奏来走。

实际使用中，你会发现这个技能最大的价值不是“让 AI 写测试”，而是强制它在动手之前把自己的理解固化下来。有一次我让它给一个计算折扣的函数补逻辑，它生成的测试覆盖了普通会员折扣、VIP 折扣，唯独漏掉了价格为零这种情况。我补充了一句“价格是 0 的时候应该怎么算”，它立刻意识到边界没覆盖，然后主动补用例，最后才动函数实现。这个过程比它直接给我一版代码要慢几分钟，但得到的代码质量明显高一个档次，因为测试已经把行为固定住了。

如果你在用 superpowers，我强烈建议把 tdd 作为第一个跑熟的核心技能。就算你平时自己不写测试，让 AI 用 tdd 流程写出来的代码，也会比它顺手瞎写稳定得多。

3.2 调试技能（debugging）：先复现，再定位，最后修

调试这件事，AI 最容易犯的毛病是一上来就瞎猜。你给它一段报错日志，它立刻说“可能是这里空指针了”“可能是这里数组越界了”，然后直接给你改代码。superpowers 里的 debugging 技能要解决的就是这个。

这个技能的核心约束是“复现优先”。技能文件里会要求 AI 先和你确认：这个 bug 出现的复现步骤是什么？预期行为是什么？实际行为是什么？错误堆栈完整不完整？然后它会尝试把问题场景化，甚至建议你创建一个最小复现用例（Minimal Reproduction Example），把无关因素剥掉，只留下能稳定触发问题的最短代码路径。

个人经验是，这个技能对“偶发 bug”特别管用。有些 bug 时好时坏，AI 如果只看一次堆栈就开改，越改越乱。调试技能逼着 AI 把触发条件写清楚，在这个过程里你经常能发现，真正的原因跟你最开始猜的根本不是一回事。等有了稳定复现路径之后，AI 再用测试保护行为，然后定位代码块修掉，最后跑回归。这一套下来，修 bug 不再是一场赌局。

3.3 代码审查（code-review）与重构技能（refactoring）

code-review 技能会引导 AI 按检查清单走流程，而不是泛泛地看一遍代码说“还不错”。它会关注安全边界、异常处理、可读性、命名、重复代码、测试覆盖度这些问题，并且输出结构化的审查意见。你给一段函数或者一个模块，它会输出问题列表和修改建议，每个问题都会标出严重程度。

重构技能的思路更偏“保守治疗”。它要求 AI 在动手改代码之前先跑一遍现有测试，保证重构前的基线是绿绿绿，然后小步修改：每一小步改完都要重新跑测试，保证绿灯没有被破坏。这一点太重要了，因为 AI 如果一次性给你一个长达一百行的改动，你根本没法 review，出了问题也不知道是哪一步引起的。有了重构技能，它会像真人工程师一样，每一步告诉你改了哪里、为什么改、测试结果如何。

我把这两个技能配合着用：先让 code-review 找出问题，再让 refactoring 按小步方式修改，每一轮修改后让 AI 汇报测试状态。效果比让 AI 全自动重写代码靠谱得多。

3.4 Java 专项技能：JVM 项目也能跑同一套方法论

搜索里很多人会查 “superpowers java”，可能是觉得这套技能偏 Python 和 JavaScript 生态，Java 项目用不上。其实这是个误解。superpowers 的技能机制是语言无关的，它主要靠外部的测试命令来完成验证闭环，你只要让 AI 知道这个项目用 Maven 还是 Gradle，tdd 和 debugging 技能完全能在 Java 项目里跑起来。

比如你在一个 Maven 项目里，想让 AI 给OrderService.calculateTotal这个方法补 JUnit 测试再实现，可以直接这么跟它说：

使用 tdd 技能，给OrderService.calculateTotal方法补 JUnit 测试。项目使用 Maven，测试命令是mvn test，依赖用的是 JUnit 5 和 Mockito。

AI 会生成对应的测试类，运行mvn test看到失败，再补实现，再跑一次确认通过。整个过程和在 Python 项目里用 pytest 一样。不同点在于 Java 编译和测试启动确实更慢，所以你会发现 AI 在跑测试之前的“思考时间”会长一点。遇到这种情况不用催它，让它跑完就好，拿到清晰的测试结果比求快重要得多。

3.5 把团队规范变成自定义技能：这才是 superpowers 的进阶玩法

用别人类技能只是入门，真正让 superpowers 项目产生飞轮的，是定义你自己的工程规范。你完全可以在skills目录下新建一个子目录，比如skills/my-commit，在里面写一个SKILL.md文件，内容类似：

技能名称：my-commit 触发场景：当用户要求生成 git 提交信息，或者提到“提交信息规范”时使用。 执行步骤： 1. 运行 git diff --stat 查看改动范围 2. 运行 git diff 查看具体改动内容 3. 按照 Conventional Commits 格式生成提交信息 4. 提交信息必须包含改动类型、影响范围、简短描述

写完之后，在CLAUDE.md或AGENTS.md的注册列表里加上对my-commit技能的索引。然后重新打开一个对话，你再让 AI 帮你生成提交信息，它就会严格按这个流程走。

这里有一个容易被忽略的关键点：技能的 description 不要写得太空，也不要写太窄。太窄了 AI 在合适场景下想不起来调用，太宽了它可能逮着机会就乱触发。你最好写清楚“什么情况用”和“用的时候第一步做什么”，这样 AI 在阅读你的请求时，能够相对准确地完成匹配。

4. 实操过程：一个 20 分钟的真实任务完整记录

4.1 场景设定

为了让你直观看到 superpowers 到底改变了什么，我拿一个真实的小项目片段走一遍。假设现在有一个 Python 项目，里面有个utils.py，包含一个计算折扣价的函数：

def calculate_discount(price, level): if level == "normal": return price elif level == "vip": return price * 0.8 elif level == "vvip": return price * 0.7 else: return price

这个函数没有测试，逻辑也埋了不少隐患：负数价格、零价格、未知等级、非数字输入、vip 比 vvip 折扣低？总之这看起来就是那种你不想手写测试但又怕 AI 乱改的代码。任务目标是：补全测试、重构逻辑、生成规范提交信息。

4.2 实操步骤记录

我直接在项目目录里启动 Claude Code，然后输入第一个请求：

启动 tdd 技能，给 utils.py 里的 calculate_discount 函数补测试。规则：先把测试写完并运行，看到失败后你再改实现代码。

AI 这次的表现和我预期一样：它没有直接输出一版新函数，而是先创建了一个tests/test_utils.py，然后告诉我它列出了哪些测试用例。它覆盖了普通用户返回原价、VIP 打八折、VVIP 打七折、未知等级返回原价这几个场景。我看它列出的用例，发现没有覆盖价格为零的情况，于是补充了一句：“价格是 0 的时候呢？负数呢？”它接着把这两个边界用例补进了测试文件。

接下来它运行了pytest，测试如预期失败，因为函数实现还没有更新。它把失败结果贴在对话里，然后才开始修改utils.py。第一版实现比较朴素，就是加了一些 if-else 判断，测试通过。此时我没有直接收工，又追加了第二个请求：

继续，但这次用重构技能，把 if-elif 结构改成映射表或更清晰的策略写法，保持测试全部通过。

它先去跑了现有测试确认基线是绿的，然后把函数改成类似字典映射加默认函数的方式。每次改完，它都会停下来跑一次pytest，我能在对话里看到12 passed。整个过程像在和一个谨慎的同事配合，而不是面对一个急着输出的生成器。

最后我让它提交代码：

用提交信息规范生成一个 commit message，风格用 Conventional Commits。

它先git diff看了改动，再git diff --stat确认涉及文件，然后给出提交信息：test: add boundary test cases for calculate_discount和refactor: replace if-elif with discount mapping。这个提交信息比我自己瞎写的规范多了，里面包含了类型和影响范围。

整个流程算下来不到二十分钟。如果是我手动来：写测试用例要查需求边界，跑测试要修各种误判，重构还要保证行为不变，一个小时打底。当然，这不代表 AI 每次都能全自动跑完，但它在流程框定下基本不用你拽着走，你只需要在关键节点上做判断。

4.3 关键收获与实操心得

这次任务给我最大的启发是：superpowers 的价值不体现在 AI 单次输出的代码量上，而是体现在工作节奏的可控性上。没有技能的时候，AI 是在所有请求上平均用力；有了技能，AI 会在复杂任务上自动拆出阶段，每个阶段都有一个明确产物：测试文件、失败结果、实现代码、重构步骤、提交信息。

另外一个意外的收获是，AI 在 tdd 流程里会主动暴露它对需求的理解盲区。它列出测试用例的时候，我一眼就能看出它漏了哪些场景，比看它写一百行代码然后 review 要高效得多。这其实就是“测试先行”对人类认知的帮助：你通过输入和预期输出，快速对齐双方对需求的理解。

4.4 顺带回应 WorBuddy 这类工具的接入问题

搜索热词里有一个问法很常见：“worBuddy 怎么用 superpowers”。这里我多说一句。WorBuddy 这类工作流管理工具，本质上是在 AI 命令之上再做一层“工作流模板”封装，把固定的提示词、步骤、检查项固化成可复用流程。它和 superpowers 的定位并不冲突，反而很像：superpowers 提供技能，WorBuddy 提供编排。

如果你想让这类工具和 superpowers 配合，核心还是那两条：第一，把 superpowers 的skills目录安装到工具能读取的全局技能路径；第二，确认工具向模型注入的是AGENTS.md还是CLAUDE.md体系，把注册信息合并进对应文件。只要这个前提成立，你在 WorBuddy 的工作流步骤里，直接写“使用 tdd 技能处理这个任务”这样明确的指令，底层的模型就能识别并执行。

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

5.1 技能完全没有生效：AI 说“不知道 superpowers”

这是安装后最容易遇到的情况。常见原因有三个：路径放错、注册文档没合、对话没重启。

排查步骤如下：

1. 先在终端里确认技能目录真的存在。运行ls ~/.claude/skills或者ls ~/.codex/skills，看看里面有没有技能子目录。
2. 再看注册文档。打开~/.claude/CLAUDE.md或~/.codex/AGENTS.md，搜一下是否包含 superpowers 相关段落。如果没看到，说明注册信息没有合并成功。
3. 新开一个对话再问一遍。AI 在对话开始时读配置，当前对话里装完技能，它自己不一定能立刻发现。
4. 检查你是不是用了系统级路径和项目级路径混搭。全局配置没生效，项目配置又覆盖了它，这种情况很容易让人误以为安装失败。

5.2 AI 知道技能存在，但执行不稳定

有的技能列表能说出来，但让它实际跑流程的时候，它走两步就跳到常规模式，直接写代码。这种情况通常跟三件事有关：模型本身的遵循能力、技能文件的描述质量、当前对话里的其他指令冲突。

个人经验是，先把技能 description 写得更可操作。比如不要光写“在需要调试的时候使用”，而是写“当用户提供错误堆栈、测试失败信息、或者提到‘帮我查 bug’、‘程序崩了’这类字眼时，先确认复现步骤，再尝试创建最小复现用例，最后才给出修复建议”。触发条件越具体，AI 越容易在正确时机调用。

另外，不同模型对结构化指令的敏感性差异很大。同一个技能，在强推理模型上执行得很稳，换到轻量快速模型上可能就会偷懒。如果你发现某个模型总是无视技能约束，别硬扛，换一个更强调遵循指令的模型节点，或者把技能中的关键步骤用更强制性的语言写出来，比如“必须”“禁止”“在没有运行测试之前，绝对不要修改实现代码”。

5.3 多项目配置打架：全局和项目级同时生效

有人会在~/.claude/CLAUDE.md里注册了技能，又在某个具体项目里也复制了一份 superpowers 说明。结果 AI 读取到两份配置，行为会出现奇怪的组合：既执行了技能流程，又因为项目级的旧指令而绕路。原因是 AI 在启动时会同时加载全局配置和项目配置，内容冲突时，后加载的参数会覆盖前面的。

我的建议是：全局配置只放“技能包注册”这类通用信息，项目级配置只放那个项目特有的规则。如果项目级配置里也必须引用 superpowers，那就不要在全局重复注册技能，避免两份描述互相干扰。另外，如果你在skills目录里自定义了和官方同名或者近似的技能，命名空间冲突会非常隐蔽。用文件名查重这种老办法，反而比让 AI 自查更可靠。

5.4 技能脚本执行失败：权限和依赖问题

部分技能可能会调用辅助脚本，比如分析 git 变更、搜索代码、处理输出。它们对系统命令有依赖，一旦依赖缺失，表现就是技能“进行到一半突然停下来”，或者直接报 command not found。这类问题排查起来也有套路：

which python3 which node which rg which jq

rg是 ripgrep 的缩写，很多代码搜索技能会用到；jq用来处理 JSON，调试和日志分析技能经常调用。如果你的机器上没装，用对应包管理器装一下就好。还有一类是权限问题，技能目录里的脚本文件如果没有执行权限，AI 怎么调都会失败。直接改成可执行：

chmod +x skills/*/scripts/*.sh

装完后记得新开对话再测，不然脚本权限更新了，但 AI 当前上下文里可能仍然缓存着旧的失败状态。

6. 几个我实操后的真实感受

用 superpowers 两周之后，我发现最大的变化不是 AI 写出来的代码量变多了，而是它给方案的时候明显变谨慎了。遇到复杂需求，它不会直接甩代码过来，而是会先调用 brainstorm 这类技能，把几个可行方案列出来说明利弊，再问我选哪条路。这个动作对于长期依赖 AI 写代码的人非常重要，因为方案选择是工程判断，代码生成只是体力活。技能框架把这两者分开之后，我反而更有参与感了。

另外，我开始把团队规范一点一点沉淀进自定义技能里。以前让新人遵守提交信息规范、接口设计规范，靠的是 code review 时一遍一遍唠叨；现在我把这些规则写进技能文件，让 AI 在相关工作流里自动触发。维护这套技能目录，本质上是在维护团队的工程文化，比反复强调有效得多。

最后分享一个小技巧：在技能的 description 里，不要只写“当用户提到某关键词时触发”，试着多写半句“先检查什么条件，再做什么”。比如调试技能里加上“先检查是否已有最小复现用例，如果没有，先用 brainstorm 列出复现步骤”。就这么半句话，AI 的技能触发准确率和执行连贯性能明显上一个台阶。superpowers 这类工具的门槛并不高，难的是你愿不愿意在技能文件上花心思打磨，让 AI 真正按照你的工程标准来工作。