企业官网建设流程全解析

最近在开发者圈子里，“superpowers” 这个词被反复提起。说的不是美漫里的超能力，而是一套给 AI 编码代理做技能增强的开源工具链。我花了两周时间，把它的安装、初始化、日常任务流程完整跑了一遍，还专门拉了一个 Java 后端项目试水。这篇不打算写成复制粘贴就完事的教程，而是把它的核心机制、真实踩坑经历，以及和 Codex 这类命令行编码工具搭配使用的思路，一次讲清楚。

如果你正在用 Codex、Claude Code 这类工具，你大概率体会过一种很微妙的状态：它们有时聪明得吓人，三两句就能写出能跑的代码；更多时候却手忙脚乱，拿到需求直接开干，不测试、不问边界、不写计划。superpowers 解决的核心问题，一句话：给代理装上一套可复用的工作方法，让它们像资深工程师一样，先规划、再动手、最后复盘。

谁适合看这篇？第一类，已经在用编码代理但对结果随机性不满意的开发者；第二类，想把团队代码规范、测试策略真正落到 AI 辅助开发流程里的工程效率负责人。后面的操作细节，我会尽量兼顾两类读者的需要。

1. 先搞清楚：superpowers 到底是给谁用的

1.1 点破核心痛点：AI 编码代理缺的不是算力，是流程

我用了很长一段时间的各种 AI 编程工具，逐渐意识到一个规律：大模型的单点能力确实强，解释一段陌生代码、补一个工具函数、翻译报错信息，它干得很漂亮。可一旦你给它一个需要拆解成多个步骤的任务，它就开始飘。不是它学不会，而是缺少稳定可靠的操作流程。

举一个我实际遇到的例子。我让代理在一个 Java 项目里新增订单状态流转功能，它不到十秒就吐出一大段代码，状态机、事件、异常处理全都有。乍一看非常完整，仔细一查，问题全在流程上：没有先确认状态流转规则，直接把“已取消”和“已完成”之间也连了边；没写测试；异常路径没定义回退策略。它写出了一段语法正确、设计混乱的代码。

问题出在哪？大模型本质上是在做“最有可能的下一个 token”的续写，代码补全、注释生成是它的舒适区，但“按顺序做一件事的逐步流程”不是它的默认行为。你让它一口气实现，它就顺着惯性把代码堆出来。superpowers 的做法很朴素：把工程师的工作习惯写成技能文档，让代理在合适的场景自动加载。文档里写明触发条件、执行步骤、检查清单，代理照着走。

这就好比新员工入职。新人智商没问题，但没经验，不知道什么时候该停下来问需求、什么时候该先写测试、什么时候该重构。superpowers 就是那份入职 SOP 手册。它不是教模型变聪明，而是让模型每次都能按成熟流程办事，把结果的不确定性压下来。

1.2 核心机制拆解：skills、initializers 与系统提示词

我第一次看 superpowers 的目录结构，有点懵，文件不少。理清楚之后发现，核心机制其实只有三个：技能文件、初始化器、系统提示词注入。

技能文件是核心。它一般用 Markdown 编写，顶部带 YAML frontmatter，写清楚技能名称和适用场景描述，正文写步骤。为什么用 Markdown？因为它既给机器读，也给人读，还能放进 git 做版本管理。团队里谁改了技能内容，diff 一目了然，比口头传递规范靠谱得多。

初始化器是稍特殊的一类技能。它解决的场景是“代理第一次开工不知道怎么组织自己”。你在对话里要求初始化，它会扫描当前环境、检查技能清单、把缺失的能力补全，然后告诉你准备好了。这一步相当于给代理做了入职培训。

系统提示词注入最容易被忽略，但恰恰是最关键的一环。安装脚本会在代理配置里追加一句说明，告诉代理“你拥有以下技能，对应场景请主动使用”。没有这句话，技能文件就算堆满目录，代理也不知道何时调用。我调试过不少案例，最后都是卡在“系统提示没写好”上。

还有一个容易忽略的约束：上下文窗口是有限的。技能文件如果写得又臭又长，会挤占编码时真正需要的信息。所以 superpowers 体系里的技能，全都要求精炼、结构化、直接可执行。

2. 环境准备与安装：5 分钟跑通 superpowers

2.1 前置依赖确认：Node、Git 与终端环境

先说结论：superpowers 对运行环境的要求不高。它本质上是一组 Markdown 文件和装配脚本，不需要单独启动服务，也没有数据库，装完就像往抽屉里放进一份员工手册。你只要准备几样基础工具就行。

Git 是必须的，因为安装目前还是要从仓库拉代码。终端环境建议用 bash 或 zsh，Windows 下推荐 WSL 或 Git Bash，纯 CMD 环境我不太建议折腾，脚本行为不确定。如果你要接 Codex CLI 或 Claude Code，那对应的 CLI 要先装好能跑起来。Node 不一定硬性需要，但有些辅助脚本可能会用到，装一个 LTS 版本不吃亏。

我在实际操作前有个习惯，先在一个临时目录里验证环境没问题，再往主配置目录里写东西。你可以在终端敲git --version和curl --version，能正常输出版本号，前置就算过了。这一步花三十秒，能省掉后面一堆“为什么装一半报错”的烦恼。

2.2 安装脚本实操与目录结构说明

我的安装过程是直接从官方仓库拉代码，然后执行 setup 脚本。流程如下，你可以直接抄：

git clone https://github.com/obra/superpowers.git cd superpowers ./scripts/setup.sh

执行完以后，安装脚本会把技能文件复制到当前用户的代理配置目录下。我这边装好之后的目录结构大致是：

~/.claude/ ├── CLAUDE.md └── skills/ ├── brainstorming.md ├── writing-plans.md ├── test-driven-development.md ├── debugging.md └── code-review.md

如果你用的是 Codex 这类支持 AGENTS.md 的 CLI，配置目录可能是~/.codex/或项目根目录下的.codex/。这里有个高频踩坑点：不同代理读取技能文件的根目录不一样。安装脚本默认按自己的约定装，你要根据自己的工具做调整。为了接 Codex，我当时手动把技能文件复制到了 Codex 的配置目录，并改了配置内容。

注意：项目更新后，目录结构可能调整。安装前建议快速扫一眼仓库 README 的最新说明。我当初就是拿着旧文章里的路径去对，结果对不上，白折腾了十分钟。

Windows 用户如果遇到Permission denied，先检查脚本有没有执行权限，用ls -l scripts/setup.sh看权限位，没有 x 就补一下：chmod +x scripts/setup.sh。这个坑在 WSL 里特别常见。

2.3 验证是否安装成功：三项检查

装完不要急着关终端，做三个检查就能确认状态。

第一，看技能文件有没有落盘：ls ~/.claude/skills/或者你对应的配置目录，能看到一堆 .md 文件就算成功。如果文件一个都没有，优先怀疑脚本没完整执行，或者执行路径不对。

第二，看配置文件有没有写入说明：打开 CLAUDE.md 或系统提示文件，里面应该有一句类似“当你需要制定计划时，使用 writing-plans 技能”的描述。没有这段说明，后续代理不会主动调技能。

第三，启动代理问一句：“你现在有哪些技能？” 如果它能列出 brainstorming、TDD、code-review 这些名字，说明技能已经进了上下文。这一步是性价比最高的验证，因为很多问题最后都出在“文件装了但代理不知道”。

3. 核心实操：初始化能力并驱动 Codex 干活

3.1 用初始化器给代理装“吃饭的本事”

安装完只是第一步。真正让代理“学会”这套技能体系，还要跑一次初始化。我最初犯的毛病就是装完就觉得完事了，结果一问三不知，折腾半天才发现少了初始化这步。

初始化操作很自然，在对话框里直接说：“请使用 superpowers 初始化你的工作流。” 或者简单一点：“你有 superpowers 技能吗？有的话请初始化。”

代理收到指令后，会读取系统提示里关于 superpowers 的说明，然后按初始化器的步骤走一遍。它会检查当前环境、确认技能清单、补全缺失能力，最后告诉你准备好了。这个过程会消耗一些对话轮次，因为代理需要把技能文件内容加载进上下文完成自我装配，属于正常现象。

我强烈建议初始化完成后，让代理把当前可用技能列个清单给你，自己留一份底。后面调试“某个技能为什么没触发”时，这就是排查基准。没有这个基线，你会陷入“到底是我指令不对，还是它没装上”的混沌状态。

初始化还有个作用：它会纠正代理对自身能力的错误认知。有一次我初始化前问代理“你会不会 TDD”，它答得模棱两可；初始化之后再问，它能直接给出 TDD 的标准循环：红-绿-重构。这个变化让我确信，初始化不是形式主义，而是真正把代理拉进了正确的工作轨道。

3.2 Java 场景实战：让 superpowers 辅助写一个模块

很多人搜“superpowers java”，应该是想知道它在 Java 项目里怎么落地。我拿一个订单折扣计算模块的实际过程给你完整还原一遍，你就能看出它的工作方式。

第一步，需求澄清。我在对话框输入：

“请使用 brainstorming 技能，帮我梳理订单折扣计算模块的需求边界。重点讨论输入参数、折扣叠加规则、异常情况。”

代理进入澄清模式，不写代码，先反问。它问的是：折扣是否可以叠加？满减和折扣券是否同时生效？折扣率是否可能大于 1？这些全是以前容易漏掉的细节。聊完之后，需求边界被压缩到几句话：输入是订单金额和折扣配置，输出是实付金额，规则是满减和折扣券不可同时使用，异常输入抛出参数异常。

第二步，制定计划。我接着说：

“请使用 writing-plans 技能，基于刚才讨论的需求，输出一份实现计划，包含模块划分、接口定义、测试策略。”

代理产出了一份结构化计划，测试策略拆到了方法级别。比如“金额小于等于 0 时抛异常”“满减阈值边界值测试”“折扣率等于 0 时跳过计算”。这一步的价值是给后续编码装上轨道，代理不容易跑偏。

第三步，TDD 实现。这一步是整个流程的重头戏，我会给出明确指令，让代理严格遵守先测试、后实现的节奏：

“按 TDD 流程实现这个模块。先写失败测试，再写实现，最后跑通测试。”

代理创建一个 JUnit 测试类，先写一个失败的测试，比如“原价 120 元，满 100 减 20，实付应为 100 元”，然后补实现代码，跑mvn test让它转绿。我特意在测试里加了一个例子：原价 120、满 100 减 20、再打 9 折，如果先满减后打折是 90 元，如果先打折后满减是 88 元。代理在澄清阶段就把“先满减后打折”定成了规则，所以实现时直接按这个顺序写。如果没有流程约束，代理很可能会随手选一种，将来上线才发现跟运营预期不一致。

第四步，自检复盘。测试跑通后，我要求：

“请使用 code-review 技能，审查刚才的代码，指出潜在问题。”

它会从并发、异常、可读性过一遍，还真揪出过一个边界问题：折扣率为 0 时要不要跳过计算逻辑。这个问题不是它编的，是真实存在的，我之前还真没注意。

整个流程下来，最大的感受是代理不再是想到哪写到哪，每一步都有产出物，而且过程可回放。这套流程不绑定 Java，换成 Python、Go、前端，节奏完全一致，只是测试命令不同。

3.3 组合拳：Codex 配置与 superpowers 的协作要点

再说“codex superpowers”这个组合。Codex CLI 本身的对话能力很强，但要跟 superpowers 结合，需要一点配置。

核心思路是让 Codex 知道技能文件在哪、什么时候用。我手头版本的典型做法，是把技能目录复制到 Codex 能读取的配置路径下，然后在说明文件里写上技能清单。具体路径版本之间差异挺大，有的读项目根目录的 AGENTS.md，有的读用户主目录下的全局配置。我建议先用codex --help或者直接翻官方 README，确认它的配置路径，再决定复制到哪。

如果你不想折腾目录映射，还有另一个更稳的玩法：直接把技能内容粘贴进对话。比如我遇到复杂需求，就把 writing-plans 的步骤贴给代理，要求它按流程执行。这种方式不优雅，但存在感极强，代理想忽略都难。适合临时用一次的场景。

还有一点提醒：Codex 的上下文窗口不是无限的。把十几个技能一股脑塞进去，会挤占写代码时真正需要的信息。我的处理方式是按任务类型动态喂，这轮写测试就喂 TDD，下轮重构再喂 code-review。上下文利用率高了，代理的输出也稳定很多。

4. 常见问题排查：真实踩坑实录

4.1 命令找不到 / 权限不足

先说最基础的：跑完 setup 后，执行命令报command not found: superpowers。大概率是脚本没有生成可执行文件，或者生成了但没进 PATH。解法有两个：一是找到安装目录，做软链接到/usr/local/bin；二是干脆不依赖全局命令，直接用绝对路径执行。问题不大，但特别容易吓到第一次接触的人。

权限问题也很典型，尤其从 Windows 切到 WSL 或 macOS，脚本没有执行权限时，报错是Permission denied。处理方式就是补权限：chmod +x scripts/setup.sh，再跑一次。这类问题属于环境问题，不是工具本身的问题，排查方向别搞反。

4.2 技能文件存在但代理不认

更隐蔽的问题是：文件明明在 skills 目录里，代理就是不加载。我踩过一次，原因是系统提示文件里没有提到这些技能。代理默认不会主动扫描技能目录，它只按上下文里写明的规则行动。所以系统提示里的描述要写清楚触发条件，比如“当用户要求制定实现计划时，使用 writing-plans 技能”。

还有一种情况是技能文件放到了代理根本不会读的目录。这种最坑，表面看文件都在，实际代理看不见。我的排查经验是直接问代理“你有哪几个技能”，如果它一个都说不出来，大概率是路径问题，而不是技能内容写错了。别在技能正文上反复改，先确认路径和系统提示。

4.3 自定义技能的正确写法与调试方法

掌握了别人的技能，你大概率会想写自己的。自定义技能核心是 Markdown 格式，我这儿给你一个通用模板：

--- name: api-design-review description: 当用户要求设计或审查 REST API 时使用 --- # API 设计审查 ## 步骤 1. 列出接口路径、方法、请求响应结构 2. 检查命名规范与 RESTful 风格 3. 确认鉴权、限流、幂等性设计 4. 输出问题清单和改进建议

写完放进技能目录，再在系统提示里追加一句“当用户要求设计或审查 API 时，使用 api-design-review 技能”。调试时直接在对话里触发场景，观察代理有没有调用。没调用，就检查 frontmatter 拼写，检查 description 是否容易被检索到。这个小循环相当于给技能做单元测试，我建议正式用之前先在测试目录里跑一遍。

下面是一个常见问题速查表，方便你遇到问题时快速定位：

5. 个人心得与后续扩展

5.1 让我效率提升最明显的三个习惯

两周体验下来，我逐渐认同一个观点：superpowers 不是那种装上就能变强十倍的神器，它是那种逼着你和代理都变得有章法的工具。让我效率提升最明显的，其实是三个习惯。

第一个习惯，强制先写计划再动手。以前让代理写模块，它经常直接把代码糊上来，现在我会先调 brainstorming 和 writing-plans，把需求边界和测试策略聊透。表面看多花几分钟，返工却少了一大截。这个算账方式，值得每个团队算一遍。

第二个习惯，把团队规范沉淀成技能文件。我们团队有一份代码风格约定和发布检查清单，以前靠人肉记，现在写成技能放进共享仓库。谁用代理干活，代理就会自动带上规范。这东西的价值，比让代理多会几个技巧大得多，因为它把团队经验变成了基础设施。

第三个习惯，给代理写负向提示。技能文件里除了“要做什么”，我还写了一节“不要做什么”，比如不要跳过测试直接写实现、不要在异常处理没确认前声称完成。负向约束比正向流程更能压低随机性，这个我实测下来很稳。

5.2 从 superpowers 出发的扩展玩法

最后说说扩展。superpowers 的底层载体是 Markdown 和提示词，这意味着它不绑定特定代理、不绑定特定语言。你只要找到一个支持自定义系统提示的工具，就能沿用这套思路。

我目前在做两个方向：一是把技能仓库做成团队内部共享，配合 CI 流程，让代理自动生成变更记录、PR 描述，甚至自动做初步代码审查；二是把同一套技能文件用到本地小模型上。小模型推理能力弱，但有了明确步骤，输出质量提升非常明显。这个方向我认为比单纯追新模型更值得投入，因为流程稳定性是模型能力之外的独立杠杆。

最后分享一个小技巧：不要一次性把全部技能都告诉代理。我会在项目开始时只暴露跟当前任务相关的三四个技能，把上下文空间留给真正重要的代码信息。这个做法，让我在长会话里的表现稳定了不少。

说到底，superpowers 这类工具真正的价值，不是让代理多会几个技巧，而是把工程经验从人脑转移到了可复用的文档里。你越是用它，越会发现，所谓超级能力，不过是一群良好习惯的组合。如果你也在用编码代理，建议先跑一遍初始化，拿一个非核心模块试试这套流程，再决定要不要深入。