企业官网建设流程全解析

“Superpowers”这个名字，听起来中二，但如果你重度使用 Claude Code，就会明白这个名字一点都不夸张。我第一次看到这个项目时，以为是某个“给 AI 加 buff”的玄学提示词合集，实际用下来才发现，它是一套相当硬核的 AI 技能管理框架——把 Claude 从一个“你问一句它答一句”的被动工具，变成一个有工作方法、有工程纪律、能按固定流程干活的“团队成员”。

这项目是 Jesse Vincent 做的（就是写 Perl 的 Dancer 框架那位老哥），核心思路一句话就能说明白：把 Claude 会做的事情拆成一个个可复用的“技能”（Skills），每个技能就是一个 Markdown 文件，里面写清楚这个技能是干什么的、什么场景用、具体怎么执行。装好之后，Claude 一进项目先读一个入口文件，然后按需加载对应技能，干活方式完全不一样了。

这篇文章我会从项目设计思路、安装流程、内置技能拆解、自定义技能写法，到我实际跑完一整个开发流程的现场记录，以及踩过的坑，一层层展开。如果你正在用或用过 Claude Code，或者想给自己的 AI 编程工作流立一套规矩，这篇文章应该对你有用。如果你还没接触过 Claude Code，也没关系，看完你会明白“给 AI 定流程”这件事到底能做到多细。

1. 先说清楚 Superpowers 到底解决什么问题

在聊安装和使用之前，得先理解一个问题：Claude Code 本身已经很强了，为什么还需要这么一层“技能框架”？

我自己用 Claude Code 写了一段时间代码，最大的感受是：能力很强，但发挥很不稳定。同样一个任务，状态好的时候它能一步到位，状态不好或者项目上下文太杂乱的时候，它可能想都不想就甩一段代码过来，逻辑漏洞一堆，甚至方向整个就跑偏。问题不在模型本身，在于没有一个机制“约束”它先想清楚再做。

Superpowers 解决的就是这个问题。它的核心设计理念是：把 AI 的执行过程从“自由发挥”变成“流程驱动”。怎么做到呢？

• Claude 每次启动时，会读取项目根目录下的CLAUDE.md文件，这是 Claude Code 的“项目记忆”入口；
• Superpowers 安装后，会在CLAUDE.md里写入一段引导指令，意思是“你是一个有 Superpowers 增强的 Claude，接到任务必须先调用 brainstorm 技能，除非用户明确说不用”；
• 真正的“技能”存放在.superpowers/skills/目录下，每个技能是一个独立的 Markdown 文件；
• 技能的 Markdown 文件头部有 YAML 格式的元信息（技能名字、描述、什么情况下使用），正文就是具体的操作指令和流程。

Claude 读到了CLAUDE.md的引导，就会在合适的时机去读取具体的技能文件，按里面的流程干活。这套设计最聪明的地方在于：所有东西都是纯文本，人和 AI 能一起读，Git 能管版本，改起来也方便。

对比一下其他做法：有的人把一大堆“角色设定+工作流”全部塞在CLAUDE.md里，结果每次对话都要吃掉大量上下文，还不灵活；有人写复杂的脚本去调 Claude API，把工作流硬编码进程序里，改一次流程要动代码。Superpowers 选了中间路线——用自然语言写流程，让模型自己判断什么时候加载哪个技能，轻量、透明、可控。

安装之后，你打开.superpowers/skills/目录，会看到一排 Markdown 文件，每个文件就是一个技能，读一遍所有技能文件，你对这套系统的工作方式就完全心里有数了。这一点我特别喜欢，它没有把任何机制包在黑盒里。

2. 安装与首次启动，五分钟跑起来

2.1 环境准备

装 Superpowers 之前，你需要确认下面几样东西就位了：

1. Node.js 环境：版本建议 18 以上。Superpowers 的安装器本身是一个 npm 包，Node 太老会有兼容问题。
2. Claude Code 命令行工具：这是基础中的基础，装好之后能在终端里直接输入claude启动对话界面。
3. 一个项目目录：建议先用一个空目录或测试项目试跑，不要一上来就在生产项目里折腾。

我自己的环境是 macOS + Node 20，Claude Code 版本在 1.0.36 以上。不同版本对插件的支持有细微差异，如果你在安装那一步报错，优先检查这两项的版本。

2.2 安装步骤

安装路径有两条，我分别说说。

路径一：通过 Claude Code 内置的插件系统安装（推荐）

在项目目录里启动 Claude，直接在对话窗口输入斜杠命令：

/plugin install superpowers

这条命令会从 GitHub 上拉取obra/superpowers仓库（对，就是那个“史上最强程序员”作者的仓库），自动安装到当前项目里。装完之后，Claude 会提示你重启会话，或者输入/plugin查看已安装的插件列表确认状态。

路径二：手动 clone 仓库

如果你不想用插件系统，也可以直接把项目克隆下来，手动把必要的文件放进.superpowers/目录：

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

然后把 clone 下来的skills/目录和CLAUDE.md文件复制到你的项目根目录，再在CLAUDE.md里确认引导指令已经存在。这个方法适合你想 fork 一份自己魔改的情况。

我建议大多数人走路径一，因为插件系统后续升级、卸载都干净。手动复制容易留垃圾文件，而且版本更新要自己重新拉。

2.3 首次启动，看看它干了什么

安装完成，重新启动 Claude Code。你会在项目根目录看到多出来的文件：

CLAUDE.md .superpowers/ skills/ brainstorm.md test-driven-development.md debugging.md systematic-approach.md walkthroughs.md ...

打开根目录的CLAUDE.md，里面会有一段引导指令，大意是告诉 Claude：你现在处于 Superpowers 增强模式，收到任务的第一步是判断是否需要使用brainstorm技能进行需求梳理，然后再动手。这一步非常关键——它相当于给模型装了一个“踩刹车”的动作，逼着它先想后做。

我第一次安装后，随便输入一个任务“帮我写一个计算斐波那契数列的函数”，Claude 没有像以前那样噼里啪啦直接把代码甩出来，而是先问了我一串问题：目标是什么？输入范围多大？需要缓存优化吗？要不要错误处理？我当时心里第一反应是“你怎么变啰嗦了”，但跑完整个流程之后才意识到，这个“啰嗦”其实是在给后面的工作省返工的钱。

2.4 目录结构代表了什么

记住一个核心点：Superpowers 不靠“魔法”，靠的是约定。

• CLAUDE.md是入口，负责告诉 Claude “你有技能可用，并且有对应的使用规矩”；
• .superpowers/skills/是技能仓库，每个.md文件代表一个技能；
• 技能文件的前几行 YAML 头部，是给 Claude 看的“索引”，告诉它这个技能管什么用；
• 能力之外的部分，是具体的执行指令，Claude 会跟着一步步做。

这种架构的可扩展性很强。你不需要改 Claude Code 本身的代码，也不需要装什么复杂框架，加一个技能就是新建一个 Markdown 文件，删一个技能就是删一个文件，规则全在文本里。搞过几年工程的人应该明白，这种“约定优于配置”的设计，维护成本低到什么程度。

3. 内置技能逐个拆解，每个都是工程实践沉淀

Superpowers 内置了一批技能，可以说是 Jesse Vincent 自己多年编程习惯的 AI 化。每个技能对应一种高频场景，我把重点几个逐个说一下，包括它的触发逻辑、工作流程和我的实际体验。

3.1 brainstorm：先聊清楚，再写代码

这是 Superpowers 的第一个杀招，也是 Claude 每次接到任务最先触发的技能。它的触发条件是“任何没有被明确直接执行的任务”——翻译成人话就是，只要用户没明说“别再问了直接干”，Claude 就会先进入头脑风暴模式。

整个流程是这样的：

1. Claude 会先向你提问，把模糊的需求逐步澄清：目标用户是谁？成功标准是什么？有没有边界条件？是否需要考虑性能或可维护性？
2. 它会在对话中逐步整理出设计要点，然后输出一份结构化的计划（Plan），包括你对需求的确认、可能的方案取舍、技术选型建议。
3. 得到你确认后，它才会进入执行阶段。

我实际跑下来，brainstorm 最有价值的地方不在于“多问几句”，而是它会基于你的回答生成一份可审阅的设计文档。有一次我让它写一个日志轮转脚本，它在任务开始前主动问我：日志文件命名规则是什么、保留几个文件、要不要考虑日志被占用时 Windows 和 Linux 的差异。这些问题确实是我自己写脚本时容易忽略的。

对比我以前的模式：直接扔给 Claude “写个日志轮转脚本”，它可能三分钟就给我一段代码，字面功能没问题，但细节全是坑。用了 brainstorm 之后，代码质量高了一截，很少出现“运行起来才发现需求没对齐”的情况。

3.2 test-driven-development：强迫症级别的测试纪律

如果说 brainstorm 是“想清楚再做”，那 TDD 技能就是“没测试不写码”。这个技能是我认为整个 Superpowers 里最硬核、最值钱的一个。

它把开发流程严格切成四步循环：

1. 红灯：先写一个会失败的测试用例（甚至先定义接口），运行测试确认它是失败的；
2. 绿灯：写最简实现，让测试通过；
3. 重构：在测试保护下优化代码结构；
4. 重复：进入下一个功能点。

Claude Code 本身能直接执行终端命令，所以 TDD 技能会让它自动运行测试、读取失败信息、再改代码。它甚至会催促你：“先写测试，不要急着写实现。”

我第一次体验这个流程的时候，让 Claude 用 Python 写一个带异常处理的时间格式化函数。它先问我“用什么测试框架”，我说 pytest，然后它就在项目里建了tests/目录，写好test_format_time.py，运行提示FAILED，接着才动手写实现，写完自动跑测试直到绿。全程我几乎没怎么干涉，它自己把红-绿-重构的循环走完了。

这套流程对一个老手来说“效率看起来低了”，因为多写了好几步，但它带来的好处是实打实的——你的项目天然带着测试，后续改代码敢下手，回归问题少一大半。

3.3 debugging：把排查 Bug 从玄学变成流程

很多人可能觉得“调试”这种事，机器跑一遍报错，看看堆栈不就行了？实际工作中哪有那么简单，尤其是那种偶发出现的、跨模块的、环境相关的问题，纯粹靠直觉定位会让你崩溃。

Superpowers 的debugging技能提供了一套系统化排查流程：

1. 确认现象：先复现，搞清楚问题到底在什么条件下触发；
2. 形成假设：列出所有可能的原因，不要只盯着最明显的那一个；
3. 最小化验证：写一个最小复现用例，或者用二分法缩小范围；
4. 修复+回归：修复后一定要跑一遍相关功能的全量测试，防止修一个坑引出两个新坑。

我有一次处理一个 Node.js 项目的内存泄漏问题。以前我的习惯是“看代码猜”，猜半天改两行，然后等线上报错。用 debugging 技能后，Claude 主动建议我先加一行内存快照日志，跑到一定条件后对比不同对象数量，最后发现是全局缓存数组没清理——问题比我预想的深一层，但流程走下来，定位速度反而比“瞎猜”快了。

3.4 其他值得关注的技能

除了上面三个主力，还有一些常用技能值得提一嘴：

• systematic-approach：把复杂任务拆成小步骤，逐个完成后打勾。适合那种“目标明确但步骤多”的开发任务，Claude 会自己列个清单，一项项做完。
• walkthroughs：这个技能有点反客为主的意味。它不是让你用 Claude，而是让 Claude 反过来给你讲解某个代码库或某个功能是怎么工作的，甚至能生成一份交互式的学习教程。新接手项目时，这个技能能让你快速了解项目全貌。
• code-review：让 Claude 以审查者的身份重新读一遍代码，检查潜在 bug、坏味道、边界情况。
• commit：规范化的 Git 提交流程，Claude 会帮你分析变更内容，生成符合 Conventional Commits 风格的提交信息。

这里额外说一句：你不用记住每一个技能是干什么的。它的设计是——Claude 根据任务内容和自己CLAUDE.md里的引导，自主选择合适的技能组合。你只需要观察它选了哪些技能，跟你的预期是否一致，不一致就用对话修正它。

4. 自定义技能，把个人工作流固化下来

Superpowers 最值钱的能力，不是那十几个内置技能，而是“你能写自己的技能”。我把话说在前面：如果你打算长期用 AI 辅助编程，花半小时学一下自定义技能写法，回报率极高。

4.1 怎么创建一个技能

最简单的方式，是在 Claude Code 里运行/superpowers斜杠命令，它会打开一个技能管理菜单，里面有 create new skill 的选项。选完后它会自动生成一个技能模板文件，放在.superpowers/skills/目录下。

模板长这样：

--- name: skill-name description: 一句话说明这个技能是干什么的、适合什么场景 when-to-use: 什么时候触发这个技能 --- # 技能名称 ## 执行流程 1. 第一步要做什么 2. 第二步要做什么 ## 注意事项 - 这里写关键提醒

别小看这几行 YAML 头。name是唯一标识；description很重要，Claude 靠它来判断什么时候加载这个技能；when-to-use是更细的触发条件提示，相当于给语义匹配打辅助。description写得越具体，技能被发现和调用的准确率越高。

4.2 我写一个真实技能做示例

假设我经常需要一个技能：给 Python 项目写一个规范化的 README 文件。

我不会上来就写“帮我写 README”，而是把这个需求写成一个技能，内容大概是：

--- name: write-python-readme description: 为 Python 项目生成结构化 README，包含项目简介、安装方式、使用示例、测试命令和许可证。适合新项目初始化时使用。 when-to-use: 用户要求写 README、项目初始化、或者 README 内容缺失时 --- # 写 Python 项目 README ## 执行流程 1. 先读取项目内的 setup.py 或 pyproject.toml，提取项目名、版本、依赖和入口脚本信息 2. 读取 src/ 或项目主目录下的模块文件，了解主要函数和类 3. 按以下结构输出 README.md： - 项目名称和一句话简介 - 安装步骤（pip install 方式） - 快速开始示例（调出主函数的代码示例） - 测试方式（pytest 命令） 4. 不要虚构不存在的功能，所有示例必须基于实际代码 ## 注意事项 - 如果项目没有 pyproject.toml，跳过依赖信息部分 - 安装方式一律用虚拟环境 + pip，不用 conda

把它保存为write-python-readme.md，放进.superpowers/skills/。下次你跟 Claude 说“给这个项目写个 README”，它有较大概率会命中这个技能，按我定义的流程去干活——先分析项目再动笔，不编造功能。

这个技能看起来简单，但它的意义在于：你把自己的工程规范“翻译”成了 AI 能读懂的指令。你团队里新来的实习生要学 20 分钟才能掌握的规范，AI 几秒钟就学会了，而且每一次都执行得一模一样。

4.3 写技能文件的三条经验

第一，一个技能只干一件事。别写一个“万能技能”包含写 README、写测试、写部署脚本三件事。技能越聚焦，Claude 的调用判断越准，执行质量也越高。本质上跟写函数是一个道理——单一职责。

第二，给足上下文，但别啰嗦。技能文件是会被塞进对话上下文的，写太长等于白烧 token。描述部分尽量一句话讲清楚，执行步骤控制在 5~10 步，关键约束写在注意事项里就行。

第三，把“范例”写进去。Claude 这类大模型最擅长“模仿”。如果某个步骤涉及到具体输出格式，直接给一个简短示例比写一大段说明文字管用得多。比如你要 AI 生成某类结构化报告，直接给个模板示例，它就懂你要的版式了。

4.4 技能文件的加载机制，得理解这一层

Claude 并不会一次性把所有技能文件全部塞进上下文——那样项目技能一多，上下文就爆炸了。它的加载方式是按需读取：根据用户当前的任务描述、结合每个技能description里的语义匹配度，决定读出哪几个技能文件。

实际操作中，你可以看到 Claude 在回答过程中说“我将使用 xxx 技能来处理”，并输出技能文件的摘要。如果你觉得它选错了技能，直接纠正“用另一个方案”就行，它会重新评估。

明白了这个机制，你就知道为什么description那么重要了——它是技能的“门面”，写得好，你的技能才会在正确的时间被正确的人（模型）选中。

5. 一次完整的实战流程记录

讲了这么多理论，下面直接展示一次完整的实战过程。我挑一个非常常见的任务场景：给一个已有的 Python 脚本新增一个“命令行参数解析”功能。这个任务足够简单，容易看清整个流程的每一步。

5.1 原始任务，和以前不一样

我启动 Claude Code，输入：

给 scripts/analyze_log.py 增加命令行参数，支持 --level 和 --output 两个选项。

如果是以前，Claude 大概率立刻开始改代码——加个argparse，定义两个参数，改main()函数，然后直接输出 diff。看起来没问题，但很多情况下它不知道--level的合法取值是什么、--output应该写到什么格式的文件里、是否要与现有配置逻辑冲突。

这次因为装好了 Superpowers，Claude 的回应是：这是一个需要走 brainstorm 流程的任务，它先列出了几个确认问题：

--level 的取值有哪些？比如 debug/info/warning/error？ --output 是希望输出为纯文本还是 JSON？ 分析脚本本身有没有配置文件需要读到这里的新参数？ 新增参数后，默认行为是否要保持原样？

这些问题都答完，它才输出了一份简短计划，包括：修改入口函数、定义参数解析器、增加日志过滤逻辑、更新 README 的使用说明。计划确认后，它才进入编码环节。

这里最大的变化是：多了一个“确认点”。改代码是一个不可逆的成本投入，先花 3 分钟对齐需求，后面省下的可能不止 30 分钟。

5.2 TDD 环节现场再现

确认计划后，我让它继续，Claude 并没有立刻改主脚本，而是先问：“项目是否已有测试配置？如果没有，我建议先用 pytest 搭一个测试骨架。”

我同意后，它开始做以下事情：

第一步，先写了测试文件tests/test_analyze_log.py，里面覆盖了预期的参数行为：

def test_default_level_filter(): # 给定默认参数，程序应保持原有输出 result = run_cli([]) assert "INFO" in result def test_invalid_level_raises(): # 给定非法 level 取值，应抛出明确错误 with pytest.raises(SystemExit): run_cli(["--level", "verbose"])

第二步，运行测试。

pytest tests/test_analyze_log.py

测试结果符合期望——失败，因为analyze_log.py还没实现参数逻辑。

第三步，才动手修改脚本主体。改完再跑一遍测试，全部通过。最后它还会做一次快速重构，把重复的参数校验逻辑抽成一个小工具函数。

整个过程是有节奏感的：红灯、绿灯、重构，一步都不少。即使任务本身不大，它也严格执行了这一套流程。说实话，我自己手写代码的时候都没这么自律。

5.3 输出结果和“不用这套”对比

最终它的输出包含：analyze_log.py的完整 diff、新增的测试文件、README 的更新片段，以及一段简短的总结说明。

我把它和没装 Superpowers 之前的体验对比了一下：

当然，这里得说句公道话——如果你的任务是一行改动，比如“把这个变量的名字改成count”，走 brainstorm 和 TDD 流程就太重了。Superpowers 自己也知道这点，所以CLAUDE.md引导里会强调“如果用户要求直接完成，就不必走完整流程”。你完全可以打断它，说“别走流程了，直接改”。

6. 常见问题与避坑实录

这里整理我在重度使用一段时间后踩过的坑和检索到的高频问题，按实战角度来写，每条都是真金白银换来的教训。

6.1 CLAUDE.md 被覆盖了

这是最容易忽略的问题。如果项目本身已经有一个CLAUDE.md，在安装 Superpowers 时，安装器可能会尝试把引导指令合并进去，或者直接覆盖。我有个项目里的CLAUDE.md记录了大量业务上下文，装完 Superpowers 之后发现那些内容全没了。

建议：安装之前先把原有的CLAUDE.md备份一份。装完之后检查内容——如果被覆盖，就把原有内容手动加回来，Superpowers 的引导指令会告诉你怎么跟原有内容共存。

6.2 技能文件“串台”

有时候两个技能的description写得太接近，Claude 会搞混。比如我写了一个“代码审查”技能，又写了一个“提交信息生成”技能，结果让它跑代码审查，它先调了提交信息技能，检查了一堆格式问题。

解决办法很简单：调整description的写法，把触发场景写得更具体，拉开两个技能之间的语义距离。

6.3 上下文太长，token 烧得飞快

技能文件是按需加载的，但如果你CLAUDE.md里写的是“每次任务必须加载全部技能”，那上下文就会爆炸。打开对话几秒钟，几千个 token 已经吃掉了。

正确做法：保持技能文件的精炼，同时在CLAUDE.md引导指令里写清楚“仅在需要时调用技能，不默认全部加载”。如果你项目里技能数量上了两位数，建议给技能分组，或者按目录建立子索引。

6.4 不使用 Claude Code 的人群，有必要关注吗

说实话，Superpowers 目前和 Claude Code 绑定得很紧，如果你不用 Claude Code，直接用这个包的意义不大。但它背后的设计思路是通用的：你完全可以借鉴它的技能文件写法，把同样的结构用到其他支持自定义指令的 AI 工具上。只要你用的工具能读取 Markdown 格式的项目说明文件，这套“引导文件 + 按需加载技能”的模式就能复制。

6.5 版本更新快，老技能可能失效

Superpowers 迭代很快，某些内置技能文件的写法会调整。如果你自定义了一些技能，在升级之后可能会遇到格式不兼容的情况。我的经验是：升级前先读 changelog，升级后跑一下最简单的任务，确认核心流程没变，再恢复日常使用。

写在最后的一个体会

AI 编程工具发展到今天，单纯比“谁生成的代码多”已经没有太大意义了。真正拉开差距的是：你能不能把工程上的最佳实践，稳定地让 AI 每次都执行出来。Superpowers 用一套极其朴素的做法（Markdown 文件 + 引导指令）解决了这个问题，这一点让我这个老工程人非常佩服。

如果你决定试一下，我的建议是——装好之后别急着让 AI 干活，花半小时把它默认自带的几个技能文件全部读一遍。那些文件本身就是极好的工程文档，甚至可以说，读完它们，比你让 AI 帮你写一百行代码更有收获。然后照着你自己最头疼的场景，写第一个自定义技能，跑通，迭代，慢慢你就有了一套真正属于自己的“超能力集合”。