企业官网建设流程全解析

1. 从“superpowers”说起：这套技能框架到底在解决什么问题

第一次看到superpowers这个词，是在几个做 AI 辅助开发的群里。有人甩出一句“装完 superpowers 之后，Claude Code 才算真正能干活了”，底下立刻一堆人追问安装方法。我当时的第一反应是：又一个包装概念？但真正上手跑了两周之后，我改变了看法——它解决的恰恰是当前 AI 编程工具最要命的一个短板：模型有能力，但缺少一套稳定的、可复用的工作方法论。

superpowers本质上是一套面向 AI 编程代理（agentic coding）的技能框架（agentic skills framework），它本身不是模型，也不是 IDE 插件，而是一组结构化的“技能包”加一套软件开发的流程规范。你可以把它理解成给 Claude Code、Codex CLI 这类命令行 AI 代理装上的“职业素养培训手册”：什么任务该先做需求澄清、什么阶段该写测试、什么时候必须做代码审查、复杂改动怎么拆解成小步提交，这些原本靠人经验和自觉的东西，被固化成了可被 AI 调用的技能。

它主要面向三类人：一是已经在用 Claude Code 或 Codex CLI 但觉得“输出质量不稳定”的开发者；二是想把 AI 代理接入团队开发流程、又担心它乱改代码的技术负责人；三是刚接触 agentic 开发、想找一套成熟方法论照着走的新手。核心价值就一句话：让 AI 代理从“能写代码”进化到“会按工程规范写代码”。

我实测下来最大的感受是，装上 superpowers 之前，Claude Code 像一个聪明但随性的实习生，你让它改个功能，它可能一口气重写三个文件还不写测试；装上之后，它更像一个懂规矩的工程师，会先问你边界条件，改完主动跑测试，提交前还会自查一遍。这个差别，在稍微大一点的项目里就是“能用”和“不敢用”的分水岭。

2. 核心设计思路拆解：为什么是“技能”而不是“提示词”

2.1 技能框架和普通提示词的本质区别

很多人第一反应是：这不就是一堆精心写好的提示词（prompt）吗？我一开始也这么想，但用下来发现差别很大。普通提示词是一次性、扁平、靠上下文记忆的；而 superpowers 的技能是结构化、可组合、按需加载的。

打个比方，普通提示词像是你每次点菜都要跟厨师口头描述一遍“少油少盐不要葱”，而技能框架像是给厨师一本标准菜谱，每道菜该放什么、火候多少、摆盘什么样都写死了，厨师只需要翻到对应那页照着做。前者依赖你每次说清楚，后者依赖框架本身的完备性。

具体到实现层面，superpowers 的每个技能通常包含几个固定部分：触发条件（什么场景下该用这个技能）、执行步骤（一步步怎么做）、检查清单（做完怎么验证）、常见陷阱（容易错在哪）。这种结构让 AI 代理在调用时不是“即兴发挥”，而是“按流程执行”。

2.2 为什么选择“技能”这种抽象层级

这里有个关键的设计取舍值得说清楚。为什么不做成插件、不做成 MCP 服务、偏偏做成“技能”？我的理解是，技能是介于提示词和工具之间的最佳抽象层级。

工具（比如读写文件、执行命令）是原子能力，太底层，AI 知道怎么调用但不知道怎么组合；提示词太灵活，每次效果不稳定。技能刚好卡在中间：它描述的是“一类任务的完整做法”，比如“如何安全地重构一个函数”“如何为一个新功能写测试”，既有足够的抽象度可以复用，又有足够的细节可以落地。

而且技能是纯文本、可版本控制、可审查的。这点对团队协作极其重要——你可以把技能包提交到 Git 仓库，团队成员 review 技能内容，出问题了 diff 一下就知道改了啥。相比之下，藏在某个二进制插件里的逻辑，出了问题你根本无从查起。

2.3 与 Claude Code、Codex CLI 的协作关系

superpowers 不是要替代 Claude Code 或 Codex CLI，而是增强它们。Claude Code 和 Codex CLI 提供的是“代理运行时”——能读文件、能执行命令、能多轮对话；superpowers 提供的是“行为规范”——在什么时机做什么事。

我习惯的类比是：Claude Code 是发动机，superpowers 是驾驶手册和交通规则。发动机再强，没有规则照样出事故。实测中，同一个重构任务，裸用 Claude Code 它可能直接改代码，而加载了 superpowers 的技能后，它会先输出一个改动计划、列出受影响的调用方、建议先补测试再改，整个流程专业得多。

注意：superpowers 的技能是给代理“读”的，不是给你“读”的。你不需要背下来，但建议至少通读一遍核心技能，这样你能预判代理的行为，出问题时也知道该去哪个技能里找原因。

3. 环境准备：Claude Code 与 Codex CLI 的安装踩坑实录

3.1 Claude Code 安装：不同系统的实际差异

Claude Code 的安装方式在不同系统上差异不小，我三个系统都试过，这里把实际踩到的坑说清楚。

macOS 和 Linux 上，官方推荐的方式是通过包管理器安装，命令大致是：

# macOS 使用 Homebrew brew install --cask claude-code # Linux 部分发行版可用 npm 全局安装 npm install -g @anthropic-ai/claude-code

Windows 上情况复杂一些。原生 Windows 支持是后来才完善的，早期很多人是在 WSL 里跑。我的建议是：如果你主力是 Windows，优先考虑 WSL2 环境，因为 Claude Code 的很多技能和脚本默认假设类 Unix 环境，路径分隔符、shell 命令这些在原生 Windows 上容易出幺蛾子。

安装完之后验证：

claude --version

能输出版本号就说明二进制装好了。但这里有个高频问题：装好了却提示 “claude code might not be available in your country”。这个提示的本质是服务可用性检测，不是安装失败。遇到这个先别急着重装，检查网络环境和服务配置，很多时候是配置问题而非安装问题。

3.2 Codex CLI 安装与 “unable to locate binary” 排查

Codex CLI 的安装相对直接，但报错信息比较劝退。最常见的两个错误：

第一个是unable to locate the codex cli binary or required runtime components. check...。这个报错我遇到过三次，原因各不相同：

第二个高频问题是版本更新。Codex CLI 迭代很快，旧版本可能不兼容新的技能格式。更新命令通常是：

# 通过 npm 安装的更新方式 npm update -g @openai/codex # 或者直接重装最新版 npm install -g @openai/codex@latest

实操心得：我建议把 Claude Code 和 Codex CLI 的版本号记在一个小本本上（或者项目 README 里）。因为 superpowers 的某些技能对代理版本有隐性要求，出问题时第一件事就是确认版本对不对。我踩过一次坑，折腾半天技能加载失败，最后发现是 Codex CLI 版本太旧。

3.3 国内环境下的下载与配置现实问题

热词里有一堆“claude code 国内下载”“claude code 中国下载不了”之类的搜索，说明这是普遍痛点。我的实际经验是：安装包本身通常能拿到，真正的门槛在服务连通性和账号配置。

几个务实的建议：一是优先用官方文档给出的安装渠道，不要从第三方镜像站下二进制，安全风险太高；二是如果遇到服务不可用，先确认是不是配置问题，很多时候是环境变量或配置文件没写对；三是团队使用的话，建议统一安装方式和版本，避免“你装的是 A 版本我装的是 B 版本”导致技能行为不一致。

VS Code 用户还有个额外选项：通过 VS Code 的集成来使用 Claude Code。配置方式是在 VS Code 里安装对应扩展，然后在设置里指向已安装的 CLI。这个方式的好处是能在编辑器里直接看到代理的操作，坏处是有些 CLI 专属功能在扩展里用不了。我个人的取舍是：日常小改用扩展，复杂任务回 CLI。

4. superpowers 安装与技能加载的完整实操

4.1 安装 superpowers 的几种路径

superpowers 的安装方式取决于你用的代理。核心逻辑是：把技能包放到代理能读取的目录，然后让代理加载。

对于 Claude Code，技能通常放在项目的特定目录下，或者全局配置目录里。手动安装的典型流程是：

# 进入你的项目目录 cd your-project # 克隆或下载 superpowers 技能包到指定位置 # 具体目录取决于你的 Claude Code 配置 git clone <superpowers-repo> .claude/skills/superpowers

对于 Codex CLI，路径和加载机制略有不同，需要参考对应文档。这里要强调一个热词里频繁出现的操作：“claude code 怎么手动装 github 上的 skills”。手动装的关键是搞清楚两件事：技能文件放哪、代理怎么发现它们。

我的经验是，先找到代理的配置目录（通常在用户主目录下的隐藏文件夹，或者项目根目录的特定文件夹），把技能包放进去，然后重启代理或执行重新加载命令。放错目录是最常见的失败原因——技能文件明明在，代理就是看不见。

4.2 验证技能是否加载成功

装完不代表成功，必须验证。验证方法有几个层次：

第一层，看代理启动时有没有报技能加载相关的错误。第二层，直接问代理“你现在有哪些技能可用”，看它能不能列出来。第三层，也是最靠谱的，给一个应该触发技能的任务，看代理的行为是否符合技能描述。

比如 superpowers 里如果有“测试先行”的技能，你就让它改一个小功能，观察它是不是先写测试再改代码。如果它直接改代码，说明技能没生效。

注意：技能加载失败最常见的原因是格式问题。技能文件通常是特定格式的文本（比如带 frontmatter 的 Markdown），少一个字段、缩进错了都可能导致加载失败。装完先拿一个技能做最小验证，别一次性全塞进去。

4.3 技能目录的组织与版本管理

技能多了之后，组织方式很重要。我推荐按领域分目录，而不是按来源分。比如：

skills/ superpowers/ testing/ refactoring/ code-review/ planning/

这样做的理由是，当你需要某个能力时，你是按“我要做测试”去找，而不是按“这是哪个包里的”去找。另外，强烈建议把技能目录纳入 Git 管理，每次升级技能包都走一次 review 流程。我见过团队因为技能包被误改导致代理行为异常，排查了一整天才发现是技能文件被人手滑改了。

5. 把 superpowers 用起来：典型工作流与技能组合

5.1 需求澄清阶段的技能应用

superpowers 最让我惊喜的是它在需求澄清阶段的作用。裸用 AI 代理时，你给一个模糊需求，它往往直接开干，结果做出来的东西跟你想的差十万八千里。加载技能后，代理会先执行“需求澄清”技能：列出它理解的边界条件、问你不确定的地方、给出几种实现方案的取舍。

这个阶段我通常会让代理输出一份简短的“需求理解确认”，包含：要做什么、不做什么、验收标准是什么。这份确认不需要长，但能挡掉后面 80% 的返工。实测中，多花五分钟澄清，能省下半小时的来回修改。

5.2 编码与测试的协同流程

进入编码阶段，superpowers 的技能组合开始体现威力。典型流程是：先规划、再写测试、再实现、最后自查。

规划技能会让代理把大任务拆成小步骤，每步都是可验证的。测试技能会强制代理在实现前先写测试（或者至少先想清楚怎么测）。实现技能会约束代理的改动范围，避免它“顺手”重构无关代码。自查技能会让代理在提交前过一遍检查清单。

我拿一个真实例子说明：让代理给一个函数加参数校验。裸用代理，它可能直接改函数体加几行 if。用 superpowers 后，它的流程是：先确认校验规则和错误处理方式，写测试覆盖各种非法输入，实现校验逻辑，跑测试，最后检查有没有影响调用方。整个过程慢一点，但改完基本不用返工。

5.3 代码审查与提交前的自查

superpowers 里我评价最高的技能是提交前自查。它让代理在说“我改完了”之前，自己先过一遍：改动是否最小、是否有遗漏的边界、测试是否覆盖、有没有引入新的依赖、提交信息是否清晰。

这个技能的价值在于，它把“人类资深工程师的提交习惯”固化下来了。我团队里有个新人，用 AI 代理写代码总是漏测试，自从加载了自查技能，代理会主动提醒“这个改动没有对应测试”，他慢慢也养成了习惯。

实操心得：自查技能不是万能的，它只能检查它“知道要检查”的东西。建议你根据自己项目的实际情况，往自查清单里补充项目特有的检查项，比如“是否更新了 API 文档”“是否加了数据库迁移脚本”。技能是可以定制的，别只用默认的。

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

6.1 技能不生效的排查思路

技能不生效是最常见的问题，排查顺序建议是：

1. 确认技能文件位置正确：代理的配置目录对不对，技能包有没有放进去。
2. 确认技能格式正确：用官方给的示例技能对比，看字段、缩进、编码有没有问题。
3. 确认代理版本兼容：旧版本代理可能不支持新格式的技能。
4. 确认加载日志：代理启动时的日志里通常有技能加载记录，看有没有报错。
5. 最小验证：拿一个最简单的技能单独测试，排除是技能之间互相干扰。

我踩过最坑的一次是技能文件编码问题——文件是 UTF-8 with BOM，代理读的时候把 BOM 当成了内容的一部分，导致解析失败。改成纯 UTF-8 就好了。这种问题不看日志根本想不到。

6.2 代理行为异常的常见原因

代理行为异常，比如该走技能流程却直接开干，通常有几个原因：

这里重点说“技能冲突”。如果你装了很多技能，可能出现两个技能都觉得自己该管这个任务的情况，代理就会行为混乱。解决办法是给技能设定清晰的边界和优先级，比如“重构类任务优先用重构技能，不要用通用编码技能”。

6.3 版本升级与技能兼容性

superpowers 和代理本身都在快速迭代，升级时最容易出兼容性问题。我的做法是：升级前先备份当前可用的技能目录和代理配置，升级后跑一遍核心任务的回归测试，确认行为没变再正式用。

如果升级后出问题，回滚要快。所以技能目录用 Git 管理特别重要，git checkout一下就能回到上一个可用版本。我见过有人升级出问题后手动一个个文件改回去，那效率太低了。

7. 进阶玩法：定制技能与团队协作

7.1 根据项目特点定制技能

默认技能包是通用的，但每个项目都有自己的规矩。superpowers 的技能是可定制的，这是它比封闭插件强的地方。你可以基于默认技能，加上项目特有的检查项、编码规范、目录结构约定。

比如你们项目要求所有数据库操作必须走 repository 层，那就在编码技能里加一条“禁止在 service 层直接调用 ORM”。这种项目特有的约束，通用技能包不可能覆盖，必须自己补。

定制技能时有个原则：描述要具体到可执行。“注意代码质量”这种描述没用，“函数不超过 50 行、圈复杂度不超过 10”才有用。代理需要的是可判断的标准，不是模糊的要求。

7.2 团队共享技能包的实践

团队用 superpowers，最大的价值在于统一行为。大家用同一套技能包，代理的行为就一致，代码风格、测试要求、提交流程都能对齐。

实践上，我建议把技能包作为团队基础设施来维护：有专人负责 review 技能改动，有版本号，有变更日志。新成员入职时，装好代理和技能包，行为基线就对齐了，省下大量“你这边 AI 怎么这么写”的沟通成本。

7.3 与现有开发流程的整合

superpowers 不是要推翻现有流程，而是嵌入进去。我的做法是：把技能触发点对应到现有流程节点上。比如需求评审后触发“需求澄清”技能，编码前触发“测试规划”技能，提交前触发“自查”技能。

这样做的结果是，AI 代理成了流程的执行者而不是破坏者。团队原有的 code review、CI 检查这些环节照常，代理只是让提交质量更高、返工更少。

8. 我个人的使用体会与几个实用建议

用了这段时间，我最大的体会是：superpowers 的价值不在“让 AI 更聪明”，而在“让 AI 更靠谱”。聪明是模型的事，靠谱是方法论的事。模型再强，没有规范约束，在大项目里就是不可控因素。

几个实用建议给准备上手的人：第一，别一上来就装一堆技能，先装核心的几个（规划、测试、自查），跑顺了再加。第二，技能包一定要纳入版本管理，这是你出问题时的救命稻草。第三，定期回顾代理的行为，发现它老在某个环节出问题，就去改对应的技能，技能是活的，不是装完就不管了。

最后分享一个小技巧：我会在项目根目录放一个AGENTS.md或者类似的说明文件，把项目特有的约定写进去，代理每次启动都会读。这样即使技能包是通用的，代理也能知道“这个项目有什么特殊规矩”。这个文件和 superpowers 配合使用，效果比单用任何一个都好。