企业官网建设流程全解析

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

第一次看到superpowers这个词，是在几个做 AI 辅助开发的群里。有人甩出一句“装完 superpowers 之后，Claude Code 才算真正能干活了”，底下立刻一堆人追问安装方法。我当时的第一反应是：又一个包装出来的概念？但真正把它跑起来、用了一段时间之后，我改变了看法——它确实解决了一个很实际的问题。

superpowers本质上是一套agentic skills framework，翻译过来就是“智能体技能框架”。它不是一个独立的软件，也不是某个模型，而是一层架在 AI 编程工具（比如 Claude Code、Codex CLI）之上的技能与工作流规范。你可以把它理解成给 AI 助手装的一套“职业培训手册”：原本 AI 只会跟你一问一答地写代码，装上 superpowers 之后，它开始懂得按软件工程的方法论去拆解任务、分步骤执行、自我检查、按规范交付。

这件事为什么重要？因为绝大多数人用 AI 写代码的痛点，从来不是“它不会写”，而是“它写得不成体系”。你让它写个函数，它写得挺好；你让它做一个完整功能，它就开始东一榔头西一棒子，改了这个忘了那个，最后交付的东西看着能跑，实际上经不起推敲。superpowers 想解决的，就是这种“单点很强、整体很乱”的问题。

这篇文章适合谁看？三类人。第一类是把 Claude Code 或 Codex CLI 当日常主力工具、但总觉得“差点意思”的开发者；第二类是刚接触 agentic 开发、想搞清楚这套方法论到底怎么落地的新手；第三类是团队里负责制定 AI 辅助开发规范的人，需要一套可复制的流程。我会从设计思路、核心机制、安装配置、实操流程到踩坑排查，完整讲一遍，尽量让不同基础的人都能照着做。

需要先说明一点：superpowers 这类框架迭代很快，具体命令和目录结构可能随版本变化。我下面讲的是基于常见实践的通用逻辑，你在实际操作时以自己装的那个版本的文档为准，但底层的思路是相通的。

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

2.1 从提示词工程到技能工程的关键转变

大部分人用 AI 编程，停留在“提示词工程”阶段：想尽办法把一句话写得又长又准，希望模型一次就给出满意答案。这个思路在小任务上有效，但一旦任务变复杂，就崩了。原因很简单——提示词是一次性的、无状态的，而真实的软件开发是多阶段的、有状态的。

superpowers 的核心洞察就在这里：与其反复优化单条提示词，不如把常见的开发动作固化成可复用的技能（skill）。每个 skill 是一段结构化的指令集合，规定了“在什么场景下、按什么步骤、产出什么结果”。这就像从“每次现场发挥”变成“照着 SOP 执行”。

我举个具体对比。没有 skill 的时候，你让 AI 重构一段代码，它可能直接给你一版新代码，你也不知道它改了什么、为什么改。有了 skill 之后，重构这个动作被拆成了固定流程：先读原代码并总结职责，再识别坏味道，再提出重构方案，再逐步实施，最后跑测试验证。每一步都有明确的输入输出，你随时可以介入。

2.2 技能框架的三层结构

我观察下来，superpowers 这类框架通常包含三层：

• 技能定义层：每个 skill 是一个独立文件（常见是 Markdown 或带 frontmatter 的文本），描述触发条件、执行步骤、注意事项。这一层是“知识”，不依赖具体模型。
• 调度执行层：由 Claude Code 或 Codex CLI 这类工具负责读取 skill、判断何时调用、按步骤执行。这一层是“引擎”。
• 项目上下文层：框架会读取你项目里的配置文件、目录结构、已有代码，让技能执行时“知道自己在哪个项目里干活”。这一层是“记忆”。

三层分开的好处是：技能可以跨项目复用，引擎可以换（今天用 Claude Code，明天换 Codex CLI），上下文跟着项目走。这种解耦设计，是它能同时适配多个工具的根本原因。

2.3 为什么选择“文件即技能”而不是插件

有人会问：为什么不直接做成插件或者 API？我的理解是，文件即技能这个选择非常务实。插件需要开发、需要审核、需要适配不同工具的插件规范，门槛高、迭代慢。而一个 Markdown 文件，任何人打开编辑器就能改，改完立刻生效，社区贡献的成本极低。

这带来一个隐性好处：技能是可读、可审计、可版本控制的。你可以把团队的技能文件放进 Git，谁改了什么一目了然。对于需要合规审查的团队来说，这一点比“黑盒插件”强太多。我在实际项目里就遇到过这种情况——客户要求所有 AI 辅助开发的规则必须可追溯，文件化的技能正好满足。

2.4 与软件工程方法论的对应关系

superpowers 号称是 software development methodology，这不是空话。它把经典工程实践映射成了 AI 可执行的技能：

这张表是我自己用下来总结的，不一定和官方分类完全一致，但能帮你理解它的定位：它不是让 AI 更聪明，而是让 AI 更守规矩。

3. 环境准备：Claude Code 与 Codex CLI 的安装配置

3.1 先搞清楚你要用哪个引擎

superpowers 本身不挑引擎，但你需要先有一个能跑 skill 的宿主工具。目前主流是两个：Claude Code和Codex CLI。两者定位略有不同，我列个对比帮你选：

我的建议是：如果你刚开始，先用 Claude Code，它的交互更友好，skill 生态也更成熟。等你熟悉了技能框架的逻辑，再考虑 Codex CLI 做自动化。

3.2 Claude Code 安装的实操路径

安装 Claude Code 的常见方式是通过包管理器。以 macOS 和 Linux 为例，通常用 npm 全局安装：

npm install -g @anthropic-ai/claude-code

Windows 用户建议在 WSL 或者 Git Bash 里操作，原生 PowerShell 有时会有路径问题。装完之后验证：

claude --version

能打印版本号就说明装好了。第一次运行claude会引导你完成登录和初始化配置。

这里有个实操心得：很多人卡在“claude code might not be available in your country”这类提示上。这通常和网络环境、账号区域有关，不是安装本身的问题。我的建议是先把基础环境理顺，确认账号能正常登录，再往下走。安装包本身是没问题的。

关于存储位置，Claude Code 的配置一般放在用户主目录下的隐藏文件夹里（比如~/.claude），技能文件、会话记录、配置都在那。知道这个位置很重要，后面手动装 skill 的时候要用到。

3.3 Codex CLI 安装与常见报错

Codex CLI 的安装同样走包管理器：

npm install -g @openai/codex

装完验证：

codex --version

如果你看到unable to locate the codex cli binary or required runtime components这个报错，别慌，这是最常见的坑之一。原因通常是三种：一是 npm 全局 bin 目录没加进 PATH；二是 Node 版本太低；三是安装过程被中断导致二进制文件不完整。

排查顺序我建议这样：先node -v看版本（建议 18 以上），再npm bin -g看全局目录在不在 PATH 里，最后实在不行就卸载重装：

npm uninstall -g @openai/codex npm install -g @openai/codex

Windows 用户如果反复失败，可以试试用npx直接跑，绕过全局安装：

npx @openai/codex --version

更新 Codex CLI 也很简单，重新跑一遍安装命令即可，npm 会覆盖旧版本。

3.4 编辑器侧的配合配置

如果你习惯在 VS Code 里工作，可以装对应的扩展，让 Claude Code 或 Codex CLI 和编辑器联动。配置的核心是让编辑器知道 CLI 的路径，以及把项目根目录作为工作区。Ubuntu 下安装 Claude Code 的流程和 macOS 基本一致，主要注意权限问题——全局安装可能需要sudo，但我不建议用 sudo 装 npm 包，容易搞乱权限，更好的做法是配置 npm 的用户级全局目录。

提示：无论装哪个工具，都建议先在一个空项目里跑通“读取文件、修改文件、执行命令”这三个基本动作，确认引擎正常，再去装 superpowers。否则出了问题你分不清是引擎的锅还是框架的锅。

4. superpowers 安装与技能体系落地

4.1 安装 superpowers 的两种方式

superpowers 的安装，常见有两种路径。

第一种是通过宿主工具的 skill 机制安装。Claude Code 支持从 GitHub 仓库直接拉取 skill，你只需要把 superpowers 的仓库地址配置进去，它会自动同步技能文件到本地技能目录。这种方式最省心，更新也方便。

第二种是手动安装。这也是很多人搜“claude code 怎么手动装 github 上的 skills”的原因。手动装的核心就三步：找到本地技能目录（通常在~/.claude/skills或项目内的.claude/skills），把 superpowers 的技能文件复制进去，然后重启宿主工具让它重新扫描。

手动装的好处是可控——你可以只挑自己需要的技能，不用全量拉进来。坏处是更新要自己来。我的做法是：核心技能手动装并纳入 Git 管理，实验性技能用自动同步。

4.2 技能目录结构长什么样

装好之后，你会看到一个技能目录，里面每个子目录或文件对应一个技能。典型结构大致是这样：

skills/ task-breakdown/ SKILL.md code-review/ SKILL.md test-first/ SKILL.md ...

每个SKILL.md里通常包含 frontmatter（描述技能名、触发条件）和正文（执行步骤）。理解这个结构，你就能自己写技能了。我后面会讲怎么写。

4.3 验证安装是否成功

装完别急着用，先验证。方法是在宿主工具里问一句类似“你有哪些可用的技能”或者直接触发一个技能场景，看它会不会按技能流程走。如果它还是老样子一问一答，说明技能没被加载。

排查方向：技能目录路径对不对、文件格式对不对（frontmatter 有没有写错）、宿主工具版本支不支持 skill。这三个是最常见的失败点。

4.4 技能与项目上下文的绑定

superpowers 真正好用的地方，是技能能读到项目上下文。比如一个“代码审查”技能，它会先读你项目的代码规范文件（如果有的话），再按规范去审。所以建议在项目根目录放一个约定文件，写明这个项目的技术栈、代码风格、测试要求。技能执行时会参考它，产出就更贴合你的项目。

这一步很多人忽略，导致技能“通用但不对味”。花十分钟写清楚项目约定，后面省的时间是十倍。

5. 实操流程：用 superpowers 跑一个完整开发任务

5.1 任务拆解：把“做个功能”变成可执行清单

假设我要给一个项目加“用户登录”功能。没有框架的时候，我可能直接说“帮我写个登录功能”，然后 AI 给一堆代码，我还得自己拼。用 superpowers 的拆解技能，流程变成：

1. 先让技能读取现有项目结构，搞清楚用的是哪个框架、有没有现成的用户模型。
2. 技能输出一份任务清单：数据模型、接口、密码加密、会话管理、错误处理、测试。
3. 我确认清单，删掉不需要的，补充遗漏的。
4. 技能按清单逐项执行，每完成一项打个勾。

这个流程的价值在于你始终掌握主动权。AI 不是闷头写完给你一个惊喜（或者惊吓），而是先跟你对齐再动手。

5.2 测试先行：让 AI 先写测试再写实现

这是我觉得 superpowers 最有价值的部分之一。测试先行技能会强制 AI 先写测试用例，再写实现代码。为什么这招对 AI 特别有效？因为 AI 很容易写出“看起来对但边界没处理”的代码。先写测试，等于先把验收标准定死，AI 写实现的时候就有了明确目标。

实操中我会这样用：让技能针对登录功能先写测试，覆盖正常登录、密码错误、账号不存在、多次失败锁定这几个场景。测试写完先跑一遍，确认全红（因为还没实现）。然后让技能写实现，再跑测试，直到全绿。

这个过程里，AI 偶尔会“为了让测试通过而改测试”，这是要警惕的。所以测试写完你要 review 一遍，确认测试本身是合理的。

5.3 代码审查技能的实际效果

实现写完后，触发代码审查技能。它会按清单检查：命名规范、错误处理、安全漏洞（比如密码有没有明文存储）、性能隐患、可读性。我实测下来，它抓出的问题里，安全类的最有价值——比如提醒我密码哈希要用带盐的算法，会话 token 要设过期时间。这些细节人手写很容易忘。

审查技能的输出通常是一份问题列表，按严重程度分级。你可以让它逐条修复，也可以自己改。我一般让它修高危的，低危的自己顺手改。

5.4 文档与提交：收尾环节的自动化

功能做完，还有收尾：更新 README、写变更说明、整理提交信息。这些琐事最烦人，但 superpowers 有对应技能。文档技能会读代码变更，自动生成或更新相关文档段落。提交技能会按约定格式生成 commit message。

我踩过的一个坑是：文档技能有时会“过度生成”，把简单改动写成一大段。所以我会在项目约定里写明“文档保持简洁，只写用法和注意事项”，技能就会收敛。

5.5 一个完整任务的耗时对比

我拿同一个登录功能做过对比。纯手动 + 普通 AI 对话，大概两小时，中间反复来回改。用 superpowers 走完整流程，大概五十分钟，而且代码质量更稳，测试覆盖更全。省下的时间主要来自“不用反复解释上下文”和“不用自己记着还有哪些没做”。

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

6.1 技能不生效怎么办

这是最高频的问题。排查顺序：

• 确认技能文件在正确的目录，且文件名、扩展名符合要求。
• 确认 frontmatter 格式正确，YAML 对缩进敏感，多一个空格都可能解析失败。
• 重启宿主工具，很多工具只在启动时扫描技能目录。
• 看宿主工具的日志，通常会提示哪个技能加载失败、为什么。

我遇到过一次，折腾半天发现是文件编码问题——技能文件存成了带 BOM 的 UTF-8，解析器读 frontmatter 时多了个不可见字符。改成无 BOM 就好了。这种坑不踩一次根本想不到。

6.2 引擎找不到二进制文件

前面提过的unable to locate the codex cli binary属于这类。除了 PATH 和 Node 版本，还有一个隐蔽原因：多个 Node 版本管理器（nvm、fnm 等）混用，导致全局包装到了 A 版本下，但你当前用的是 B 版本。解决办法是确认which node和which npm指向同一个版本，再重装。

6.3 技能执行到一半卡住

有时技能跑到某一步就不动了。常见原因是那一步需要执行命令或访问网络，但环境不允许。比如技能想跑测试，但项目没装测试依赖。这时候看它卡在哪一步，手动把前置条件补齐，再重跑。

6.4 常见问题速查表

6.5 几个独家避坑技巧

第一，技能不要贪多。装几十个技能，触发条件互相打架，AI 反而不知道该用哪个。我建议核心技能控制在十个以内，其余按需临时启用。

第二，给技能写“反例”。在技能文件里明确写“不要做什么”，比只写“要做什么”更有效。比如审查技能里写“不要建议引入新依赖，除非确实必要”，能省掉很多无谓的改动建议。

第三，定期清理会话上下文。长会话里 AI 会积累大量历史，技能执行时可能被旧信息干扰。做新任务时开新会话，效果更稳。

第四，把技能纳入版本控制。团队协作时，技能文件就是你们的开发规范。谁改了技能，等于改了团队规范，走 code review 流程，避免有人偷偷改规则。

7. 技能自定义：写出适合自己团队的技能

7.1 一个最小可用技能的结构

自己写技能没想象中难。一个最小技能大概长这样：

--- name: api-review description: 审查 API 接口设计，检查命名、参数、错误码 trigger: 当用户要求审查 API 或接口设计时 --- ## 步骤 1. 读取接口定义文件 2. 检查命名是否符合 RESTful 约定 3. 检查参数是否有类型和范围说明 4. 检查错误码是否覆盖常见异常 5. 输出问题列表，按严重程度排序

关键是把“触发条件”和“执行步骤”写清楚。触发条件写得好，技能才会在该用的时候被调用。

7.2 从团队痛点反推技能

写技能的正确姿势，不是“看别人有什么我也写一个”，而是从团队反复出现的问题出发。比如你们团队老是忘记写单元测试，那就写一个“提交前检查测试覆盖”的技能。老是接口命名不统一，就写“接口命名审查”技能。

我帮一个团队梳理过，他们最痛的是“新人写的代码风格不统一”。我们就写了一个风格检查技能，把团队的风格约定固化进去。新人一提交，技能自动按约定检查，比人肉 review 高效多了。

7.3 技能迭代的节奏

技能不是写完就完事。用一段时间后，你会发现某些步骤多余、某些场景没覆盖。我的做法是每次技能“表现不好”就记一笔，攒够几条就改一版。改的时候注意保持向后兼容，别把团队已经习惯的流程打乱。

8. 关于这套框架，我的一些真实体会

用 superpowers 这类框架大半年，最大的感受是：它改变的不是 AI 的能力上限，而是 AI 的稳定性下限。以前用 AI 写代码，好的时候惊艳，差的时候离谱，方差极大。有了技能框架约束，输出质量的下限被抬高了，你敢于把更重要的任务交给它。

另一个体会是，这套东西逼着我把很多“只可意会”的开发经验显性化。以前我觉得“代码要写好”是常识，写技能的时候才发现，什么叫“好”得一条条说清楚。这个过程本身对团队就是价值。

至于它适不适合你，我的判断标准很简单：如果你用 AI 写代码的频率已经高到“反复解释上下文”成为负担，那就值得上框架；如果只是偶尔问几个问题，那普通对话就够了，别为了框架而框架。工具是拿来解决问题的，不是拿来供着的。