企业官网建设流程全解析

1. 先说清楚：superpowers 到底是给谁用的“超能力”

如果你最近一两年开始重度使用 Claude Code、Codex CLI 这类跑在终端里的 AI 编程助手，多半会遇到一种微妙的不满足感：刚装上的头两天确实惊艳，项目里的文件它能读，代码它能写，命令它敢敲。可一旦项目复杂起来，问题就全冒出来了——同一个错误它能犯三次，你上午刚跟它交代过的编码规范下午就忘得一干二净，你让它“按项目约定改代码”，它反而开始自由发挥。

我就是在这样的循环里耗了两周，直到把superpowers这套框架接入工作流之后，整个状态才发生了质变。简单说，superpowers 不是又一个 AI 编程助手，而是套在 Claude Code / Codex 这类 CLI 编程工具外面的一层“技能与工作流增强层”。它把项目里会用到的专家知识、操作流程、命令模板、权限边界全部打包成一个个“技能包”，让 AI 在合适的场景下自动加载、按步骤执行，而不是靠你在每轮对话里重新解释需求。

这就像同样是请一个工程师进组：原生 AI 助手是个“什么都会一点但对你项目一无所知”的新人，而 superpowers 给了他一整套你团队沉淀下来的工作手册和顺手工具。本文会从安装配置、核心机制、实战工作流、技能包开发、踩坑排查五个维度，把它的价值聊透。不管你是整天泡在终端里的硬核开发者，还是在给团队搭建统一 AI 提效规范的技术负责人，这套东西都值得花一下午折腾明白。

1.1 一句话解释它解决的核心痛点

我在用原生 AI 编程工具时，最大的感受是“不稳定”。同一个任务，换一种问法，AI 的表现可能天差地别。deep dive 下来，其实问题集中在四类：

• 会话失忆：项目背景、技术选型、历史决策，每次新会话都要重新讲一遍，AI 永远是一张白纸。
• 行为漂移：同样的任务，有时候它老老实实写测试，有时候它嫌麻烦直接跳过，全靠“心情”。
• 权限模糊：它不知道该读哪些文件、不该改哪些文件，经常在错误的地方动手。
• 没有沉淀：这次踩过的坑、定过的规矩，永远不会进入下一次会话。

superpowers 的解法很直接：把“知识”和“流程”从对话里抽出来，放进文件系统。技能包就是一套预先写好的指令和脚本，AI 根据任务意图自动匹配并加载。会话失忆靠“技能包 + 项目笔记”解决，行为漂移靠标准化的技能流程约束，权限模糊靠技能包里的权限声明来控制，没有沉淀的问题则靠技能包在同项目里的反复复用——这周定下的规则，下周还能用。

1.2 和原生 Claude Code / Codex 的边界在哪里

很多人问我同一个问题：我直接用 Claude Code 不就行了？非也。原生 Claude Code 提供的是“能力底座”：能聊、能读文件、能执行命令。而 superpowers 是在这个底座之上，加了一套“业务逻辑”：

一个更直观的类比：原生 AI 是个执行力很强的实习生，但没有岗位培训。superpowers 是那套入职培训手册 + 老师傅的批注 +一把经过校准的螺丝刀。实习生还是那个实习生，但手里拿的工具和脑里的规则完全不同了。

2. 安装与启用：从零到跑通第一版环境

2.1 环境依赖清单

在开始之前，先把依赖讲清楚，免得装到一半卡住。我的建议是先用一个干净的测试目录跑通，再接入真实项目。环境上的硬性要求有三条：

• Node.js 18 及以上（推荐直接上 20 LTS，后面装依赖会省很多事）
• 一个可用的 AI CLI 工具：Claude Code 或 Codex CLI，二者选一即可
• git：技能包本身就是从仓库拉下来的，git 是刚需

版本太老的 Node 会直接在依赖安装阶段报错，这个坑我在后面踩坑部分会细说。如果机器上没有 Node，建议先用 nvm 装一个 LTS 版本，别用系统自带的旧版。

2.2 安装步骤与目录结构说明

安装过程本身不复杂，核心是拉取仓库、构建、把技能链接到 AI 工具的技能目录：

git clone https://github.com/workspaced/superpowers.git cd superpowers npm install npm run build

构建完成后，需要把技能包发布到 AI 助手能够识别的位置。以 Claude Code 为例，技能目录一般在~/.claude/skills；Codex CLI 则使用自己的插件目录。你可以直接把superpowers/skills下的子目录软链过去，或者用项目自带的安装脚本一键完成。

装完之后建议看一眼目录结构，理解每个部分的作用：

superpowers/ ├── skills/ # 核心资产：一个个可被 AI 自动加载的技能包 │ ├── generate-code/ # 代码生成技能：按项目规范产出代码 │ ├── test-driven-development/ # TDD 技能：先写测试再写实现 │ ├── system-prompt/ # 系统提示词技能：注入项目级指令 │ ├── review/ # 代码审查技能：让 AI 用审查者视角读 diff │ └── ci/ # 持续集成辅助技能 ├── agents/ # 子代理定义：把大任务拆给多个“分身” ├── presets/ # 预设：角色、场景、指令模板 └── notes/ # 项目笔记：AI 会把沉淀写入这里

这里的skills目录是灵魂。每一个子文件夹都是一个独立技能包，里面既有描述文件（告诉 AI 什么时候该用），也有可执行脚本（真正干活的工具）。理解了这层结构，后面所有玩法都顺理成章。

2.3 首次启用与功能自检：如何确认装好了

安装完成后别急着写业务代码，先做三件事自检，确定框架真的在生效：

第一，查看技能加载状态。在 Claude Code 会话里输入：

/技能列表

或者直接问一句“你现在能使用哪些技能”。如果 superpowers 加载成功，AI 会列出它可用的技能包名称，而不是茫然回答“我没有技能”。

第二，触发一个核心技能。找一个简单需求，比如：

请使用 test-driven-development 技能，为下面这个函数编写第一个失败的测试：实现订单金额计算。

观察 AI 的反应。如果技能生效，它不会直接甩给你一段实现代码，而是先遵循 TDD 流程写测试，并明确告诉你“按照 TDD 技能的第一步，我先写一个失败测试”。

第三，检查系统提示词注入。技能框架通常会向会话上下文注入一段增强提示词，描述 AI 的角色和能力边界。你可以在会话开头让 AI “复述你的系统提示词中关于技能使用规则的部分”。如果它答得上来，说明注入链路是通的；如果它答非所问，基本可以判断加载出了问题。

我自己的经验是：这三个自检里，第二个最准确。因为技能包的核心价值在于“改变 AI 的行为”，光看加载列表不够，要让它在实际操作里展示出不同的流程，才算真正生效。

3. 核心机制拆解：技能、权限与记忆是怎么串起来的

3.1 技能系统：从“一问一答”变成“场景化工作流”

技能系统是整个 superpowers 的地基。要理解它，先理解没有它的时候 AI 是怎么工作的：你提问，AI 直接回答，所有步骤都靠上下文中的只言片语组织。如果你没提测试，它就默认不写测试；如果你没提代码规范，它就按自己的偏好排版。

技能包则把这个过程从“即兴发挥”变成了“按剧本演出”。每个技能包的目录结构是固定的：

my-skill/ ├── SKILL.md # 技能描述：告诉 AI 这个技能做什么、何时触发 ├── scripts/ # 可执行脚本：真正的自动化工具 └── assets/ # 辅助资料：模板、参考文档、项目规范

其中SKILL.md是最关键的。它通常包含三部分：

• 元信息：技能名称、版本、作者
• 触发条件：什么样的问题应该启用这个技能
• 执行步骤：一旦启用，AI 必须遵循的流程清单

触发条件的写法很有讲究。写得精确，AI 才能在合适的场景自动选中技能；写得模糊，它就会乱触发，比如写个简单的工具函数都要跑一遍完整测试流程。我见过很多人的技能包“失灵”，八成原因就是触发条件描述得太宽泛。

3.2 技能包的自动匹配：AI 是怎么选中正确技能的

有读者一定会问：技能包这么多，AI 怎么知道该用哪个？答案是“语义匹配”。在每次会话中，框架会把所有技能包的描述注入上下文，AI 根据用户请求的语义，自主判断哪个技能最匹配。这个过程用户是无感的。

为了帮助 AI 更精准地匹配，我习惯在技能描述里写“使用场景 + 反例”。比如 TDD 技能的描述可以写成：

当用户要求编写具有明确输入输出逻辑的函数或模块时使用。 如果用户只是在讨论思路、尚未确定需求，则不要使用。

这种写法显著降低了误触发概率。最初我的技能描述只写了“用于测试驱动开发”，结果 AI 只要看到“测试”两个字就会触发，后来加了反例说明，行为才稳定下来。

3.3 子代理编排与审批链：什么时候放权，什么时候拦人

除了技能系统，superpowers 还有一个实用设计：子代理编排。简单说，它允许 AI 把一个大任务拆成几个子任务，分别交给不同“角色”的代理执行。比如开发一个新接口时，它可以这样分工：

• 编码代理：负责按需求写实现代码
• 审查代理：负责 review 代码 diff，找逻辑漏洞
• 测试代理：负责运行测试并汇报失败原因

这个机制的价值在于让 AI 摆脱“既当运动员又当裁判”的尴尬。在原生模式下，AI 写完代码通常不愿意自己挑毛病；但在子代理模式下，审查代理的定位就是挑毛病，它甚至会用更挑剔的语气指出问题。

用户可以在agents/目录里定义自己的子代理：

# 审查代理配置示例 name: strict-reviewer role: 你是一名资深代码审查者，专门负责挑错，绝不放过任何潜在问题。 permissions: allowed: [read] denied: [write]

这里有个关键点：审查代理默认没有写权限。也就是说，它可以读代码、提意见，但不能直接改代码。这个权限隔离设计让我很受用——它保证了审查的独立性，也避免了 AI 自己改完自己审的滑稽局面。

权限审批链同样重要。框架会给不同类型操作设定不同的触发级别：读文件直接放行，写文件要看技能包声明，执行git push、删除文件这类高危险操作则必须经过你确认。第一次用的时候可能会觉得繁琐，但习惯之后会发现，这套机制防住了很多次 AI “自信满满地破坏性操作”。

4. 把代码生成变成流水线：我在实际项目里的工作流

4.1 需求拆解时的标准提示词格式

有了 superpowers 之后，最先应该改变的是你的提问方式。原生对话时代，提问越短越好，因为 AI 没有基建能力处理复杂约束；但在技能框架下，提问应该结构化，让技能包有足够的输入来执行。

我在项目里用的标准提示词模板长这样：

目标：实现订单状态机，支持待支付、已支付、已发货、已完成、已取消五种状态。 背景： - 项目采用 Spring Boot + MyBatis，数据库是 MySQL 8.0 - 状态变更需要记录操作日志 - 订单取消需要校验是否为待支付状态 约束： - 遵循项目现有的 Controller-Service-Mapper 分层 - 状态枚举类放在 domain/enums 下 - 必须包含单元测试，测试用例覆盖非法状态流转 请先按 generate-code 技能拆解任务，再按 test-driven-development 技能逐步实现。

注意最后一句：我显式指定了技能。这么做的好处是让 AI 明确走流程，而不是自由发挥。等用顺手之后，连这句都可以省掉，AI 会根据任务内容自动选择技能。

4.2 自动化测试回环：写完码立刻验

在原生 AI 编程工具里，最常见的挫败感是：AI 生成了一大段代码，看着很合理，一跑测试全红。superpowers 对这个问题给出了一个流程化的解：TDD 技能 + 自动化命令回环。

TDD 技能的核心步骤是这样的：

1. 理解需求，列出测试用例清单
2. 先写一个失败的测试，运行确认它失败（且是预期原因）
3. 编写最小实现代码，让测试通过
4. 继续下一个测试用例，循环迭代
5. 全部通过后，运行完整测试套件，确保无回归

用代码来看这个循环会非常直观。假设 AI 被要求实现一个calculateDiscount方法，它会先写这样的测试：

@Test void should_return_zero_discount_when_amount_is_null() { assertThat(orderService.calculateDiscount(null)).isEqualTo(BigDecimal.ZERO); }

然后运行：

./mvnw test -Dtest=OrderServiceTest

看到测试失败（空指针），再写实现让测试变绿。这个过程看着慢，实际比一次性写几十行然后疯狂 debug 要快得多，因为每一步都有清晰反馈。

4.3 Java 项目实测：superpowers 在真实代码库里的表现

我拿一个 Spring Boot 项目做实测，让 superpowers 帮我在现有OrderService里新增一个“按用户查询订单分页”的接口。接入技能框架前后，AI 的表现差异非常明显：

接入前：AI 直接写了一个findByUserId方法，没有分页，没加事务，没考虑 MySQL 索引，甚至没写测试。我需要反复补充建议，它才慢慢改对。

接入后：AI 先读取了项目现有的OrderMapper.xml，发现项目里所有查询都用了PageHelper做分页，然后自动匹配了 generate-code 技能中的“项目规范”模块，新代码严格遵循了现有风格：

public PageInfo<OrderVO> findOrdersByUser(Long userId, int pageNum, int pageSize) { PageHelper.startPage(pageNum, pageSize); List<OrderDO> list = orderMapper.selectByUserId(userId); return new PageInfo<>(list); }

测试也同步生成，用的还是项目里已有的OrderServiceTest基类。整个过程中我只在最后 review 参数校验逻辑时提了一条意见，其他全部由技能包驱动完成。

这个实测案例最有说服力的，不是“AI 写出来了”，而是“AI 按项目的方式写出来了”。没有技能包的时候，AI 是一个能力不错但不懂规矩的新人；有技能包之后，它像是被项目老员工带过一星期之后的状态。

5. 自己动手写一个技能包：从想法到可复用脚本

5.1 技能包的最小结构：别急着写复杂逻辑

很多人在学会使用现成技能包之后，会动心思写自己的。这个方向非常值得。先在skills/目录下建一个最小结构：

code-quality-guard/ ├── SKILL.md # 技能说明 ├── scripts/ │ └── check.sh # 质量检查脚本 └── assets/ └── checklist.md # 检查清单

关键是SKILL.md的写法。它决定了 AI 什么时候该用这个技能，以及用了之后要做什么。

5.2 一个“重构安全检查”技能的完整示例

我自己写过一个refactor-guard技能，作用是在 AI 准备重构代码之前，先做一轮风险检查。它的SKILL.md长这样：

--- name: refactor-guard version: 1.0.0 description: 在用户要求重构现有代码时使用。该技能会先检查测试覆盖情况、识别高风险依赖、输出重构风险评估，再决定是否进行重构。 triggers: - 用户提到"重构"、"refactor"、"优化现有代码" - 用户要求修改已有函数的内部实现，但行为必须保持不变 not_trigger: - 用户只是新增功能，不改现有逻辑 permissions: allowed: [read, run_script] denied: [write] workflow: 1. 识别目标文件，检查是否存在对应测试文件 2. 如果测试覆盖不足，先建议补充关键测试用例 3. 运行项目测试套件，确认重构前基线为绿色 4. 输出重构方案，标注高风险点 5. 用户确认后再进入 구현阶段 --- # refactor-guard 技能说明 本技能的核心价值：重构前不踩雷。

配套的scripts/check.sh是一个简单的覆盖度提醒脚本：

#!/bin/bash # 检查目标文件是否有对应测试文件 TARGET_FILE=$1 TEST_FILE=$(echo $TARGET_FILE | sed 's/src\/main/src\/test/' | sed 's/\.java$/Test.java/') if [ -f "$TEST_FILE" ]; then echo "测试文件存在: $TEST_FILE" else echo "警告: 未找到对应测试文件 $TEST_FILE" fi

写完这个技能包之后，我在一次真实重构里立刻受益了。AI 准备把一个老旧的OrderController里的逻辑抽取到 Service 层时，这个技能主动拦了一步：先检查了OrderControllerTest是否覆盖了当前接口行为，结果发现覆盖率为零。AI 在重构前提出先补测试，避免了“重构完发现行为变了却没人知道”的坑。

5.3 调试技能包时的常见问题

自己写技能包，大概率会遇到三个问题：

第一，技能没有被触发。排查方法：在会话里明确要求 AI “列出你当前可用的技能”，然后看你的技能是否在列表中。如果在，但任务没有触发，多半是triggers写得太窄，扩大触发词范围即可。

第二，脚本报错但 AI 不汇报细节。这通常是因为脚本执行结果被 AI 简化了。建议在脚本里加set -x，让执行日志更详细；同时要求技能在执行步骤里明确写“必须汇报脚本输出中的错误信息”。

第三，技能权限声明与实际不符。如果技能需要写文件，但permissions里没有声明 write，AI 会卡在权限审批环节。这种情况反而是好事——它在提醒你把权限边界想清楚。我的原则是：技能包默认只读，只有明确需要修改文件的技能才声明写权限。

6. 踩坑实录：安装失败、误判核验与升级兼容

6.1 安装阶段常见的三个坑

我前前后后帮三个人装过 superpowers，几乎每次都踩到同样的坑，这里集中列一下。

坑一：Node.js 版本过旧。如果你用系统自带的 Node 14 或更旧版本，npm install会在某个依赖的编译环节直接崩掉，报错信息五花八门，什么node-gyp失败、gyp ERR之类的。解决方案只有一个：升级到 Node 20 LTS，然后再装。

坑二：技能目录不存在。很多新手在配置软链时才发现~/.claude/skills这个目录根本不存在。原因是 Claude Code 只会在首次使用时创建部分目录，技能目录往往需要手动建立：

mkdir -p ~/.claude/skills ln -s /path/to/superpowers/skills/* ~/.claude/skills/

坑三：升级导致旧配置失效。superpowers 的版本迭代速度不算慢，升级后可能会出现某个旧技能包不再被识别的情况。我在踩过一次坑之后学乖了：升级前先把notes/目录和自定义技能包做好备份，升级后重点检查自定义技能包的SKILL.md格式是否符合新版本规范。

6.2 权限误判与触发过度

技能系统的自动匹配是双刃剑：匹配准了是真·智能，匹配错了就是灾难。我遇到过最头疼的一次，是generate-code技能的触发描述写得太宽，导致我让 AI “帮忙看看这个函数的性能问题”时，它也触发了代码生成流程，直接给我改了一版代码出来，而我只想要一个分析结论。

解决方式是在技能描述里增加not_trigger区块（如上文所示），明确写“当用户只是询问分析、不要求修改时，不要触发”。从那以后，误触发率明显下降。

权限方面也吃过亏。最初我图省事，给所有自定义技能都开了 write 权限，结果 AI 在一次执行中顺手改了配置文件。后来我把每个技能的权限收敛到最小，规则是：能读就不写，能跑脚本就不改文件，能局部改就不全量改。

6.3 升级版本后的行为变化与兼容策略

框架升级带来的行为变化是个很微妙的问题。有一次我从旧版本升到新版本，发现 AI 处理所有新代码请求时都会优先走 TDD 流程，哪怕我只是让它写一个临时脚本。这个变化本身没毛病，但它改变了我习惯的工作节奏，导致好几次任务完成时间变长。

排查下来发现是新版把 TDD 技能设为默认启用了。我的处理方式是：新建一个轻量级的quick-script技能，覆盖临时脚本场景；同时保留 TDD 技能给正式业务代码。这样既享受了新版的改进，又保住了自己的快捷路径。

给后来者的建议是：每次升级后，不要急着验收功能，先用一两天跑真实任务，观察 AI 的行为和以前有什么不同。技能框架升级改变的往往不是单一功能，而是整套默认流程的优先级。

最后再分享一点个人习惯

把 superpowers 用进日常三个月之后的感受是：它并没有让 AI 变得“无所不能”，而是让 AI 变得“稳定可靠”。稳定的价值被很多人低估了——在真正的项目里，一个偶尔惊艳但经常不靠谱的助手，远不如一个每次都能按流程走完、结果可预期的助手有价值。

如果你准备入坑，我的建议是先别急着自定义太多技能。把官方技能包用熟，理解每个技能的触发逻辑和设计意图，再动手改。技能包不在于多，而在于每一条都能在合适的时机发力。

另外一个小诀窍：把项目里你经常需要重复交代的事，比如接口返回值格式、日志打印规范、异常处理方式，整理成一个project-rules技能包。这一步的收益会远超你的预期，因为 AI 一旦稳定遵循项目内部规范，review 的成本会肉眼可见地降下来。