企业官网建设流程全解析

最近我在带团队用 Codex 和 Claude Code 跑一个中型的业务系统重构，发现了一个很现实的问题：AI 编程代理写代码确实猛，但一旦离开局部上下文，整个流程就容易乱套。你让它写一个接口，它能马上给你一套完整的 API；可你让它从需求梳理开始、自己拆任务、自己写测试、自己重构，最后再产出一份像样的变更文档，它十有八九会在中途跑偏。直到试了 Superpowers，情况才明显好转。

Superpowers 不是一个新的语言模型，也不是某个 IDE 插件，而是一套围绕 AI 编程代理设计的完整软件开发工作流。它把“技能”（skills）这件事做成了体系：从需求分析、任务拆解、TDD 实践、代码审查到文档沉淀，每个环节都有对应的技能包，引导代理像一位真正的软件开发工程师那样思考和工作。这篇文章就是我的使用记录和踩坑总结，适合那些已经在用 Codex、Claude Code、Cursor 等 AI 编程代理、但总感觉效果不稳定的团队和个人开发者。

1. Superpowers 到底在解决什么问题

1.1 AI 编程代理的“偏科”困境

过去我们使用 AI 编程代理的方式，基本等于“提示词—代码”的直给模式：我提一个需求，它给一段代码。这个模式在处理局部函数、单个接口、单元测试时效率确实很高，但把它放到一个完整项目或者一个跨模块的需求里，问题就来了——它往往只能看到眼前的一小段代码，缺少全局视角，更不会主动分解任务。就像一个只会写一行行代码的工程师，却没有人告诉他整个模块要完成什么，也不知道下一步该做什么。

我在实际项目里最大的感受是，模型本身的能力已经够了，缺的是“流程约束”。让它写一个函数，它很出色；让它管理一组任务列表，它却会飘。Superpowers 的做法就是把“怎么做一个软件项目”的隐性经验显式化，写成一组可加载的 skill 文件，让代理在切换任务时按照这些流程走，而不是每次从零开始自由发挥。这相当于给 AI 装了一套“工作方法”，而不是简单增加代码量。

1.2 从“代码助手”到“软件开发工程师”的转变

所谓“软件开发工作流”，并不仅仅指写代码的顺序，还包括需求澄清、任务规划、测试先行、重构、代码审查、文档同步等等。Superpowers 把这些环节抽象为一个个独立的“技能”，每个技能里既包含提示词模板，也包含操作规则和决策树。当代理拿到一个任务时，它会先加载对应的技能包，然后按照技能包定义的工作流去执行。

这带来的直接变化是：代理不再是一个单点工具，而是可以被“编排”的执行者。你可以告诉它“使用 TDD 技能完成登录功能”，它会先写失败测试、然后实现、再重构；你也可以告诉它“使用计划技能梳理这个迭代”，它会主动列出任务、识别风险、给出时间估算。对团队来说，AI 编程代理从“快速补代码”变成了“可预期的开发成员”，而不是一个随缘出结果的暗盒。

1.3 技能驱动的核心设计思路

Superpowers 的设计思路，本质上是在模型能力之上加了一层“工作流抽象层”。它把项目开发中反复用到的最佳实践，比如测试驱动开发、重复代码消除、文档即代码，编码成结构化的技能描述。这些描述通常包含：适用场景、执行步骤、产物要求、以及常见的“不要做什么”。

我觉得这个思路很高明的一点是，它没有试图用一套固定的流程把代理限制死，而是把技能拆成可以被选择和组合的模块。有些技能是分析类的（比如需求澄清），有些是实践类的（比如 TDD），有些是治理类的（比如代码审查）。代理在特定阶段加载特定技能，就像我们人类工程师在不同阶段切换思维模式一样。这种做法既保留了模型的灵活性，又给它提供了明确的操作路径，比单纯丢给代理一个巨大的 system prompt 要可控得多。

2. 核心技能拆解：一套完整的工作流

2.1 需求澄清与目标设定

一个靠谱的开发工作流，起点绝不是动手写代码，而是需求澄清。Superpowers 的“需求澄清”技能会引导代理向用户提问：这个功能要解决什么核心问题？目标用户是谁？有哪些边界条件？验收标准是什么？这些问题不是一次问完，而是根据上下文逐步追问，直到能生成一份可执行的需求说明。

我在使用中特别感受到，这一步能帮我挡住很多“伪需求”。以前我给代理一个很含糊的描述，它往往会先假设一个解决方案，然后埋头实现，最后发现根本不是我要的东西。现在让代理先加载需求澄清技能，它会在设计前先输出假设，再让我确认。这种“先确认，再动手”的机制，能省下大量返工时间。尤其是涉及多方协作的项目，需求澄清技能产出的“问题清单”，可以直接作为需求评审的输入，帮助团队把遗漏点提前暴露出来。

2.2 测试驱动开发（TDD）流程

TDD 是 Superpowers 最核心的技能之一。技能包会规定严格的执行顺序：先写测试，运行测试确认它失败；然后写最小实现让测试通过；最后重构代码并保证测试仍然是绿的。代理在执行时会把测试结果作为强反馈，而不是仅凭“感觉”认为代码没问题。

以 Java 项目为例，代理会根据需求先写出 JUnit 测试用例，再运行 Maven 或 Gradle 命令，等测试失败后补上实现，再次运行测试，直到全绿。这个过程听起来机械，但实际使用中它带来的收益非常明显：代码覆盖率会显著提高，重构时也不容易破坏已有功能。最值得一提的是，Superpowers 的 TDD 技能还包含一个很实用的细节——如果实现过程中出现意外失败，它会建议回退到最近一次全绿状态，而不是强行“修修补补”。这个习惯对保持代码库稳定非常关键，尤其适合多人同时修改同一代码库的团队。

2.3 任务拆解与进度管理

除了写代码，Superpowers 的“任务拆解”技能可以把一个大需求拆成可执行的小任务列表，并标注依赖关系和验收标准。这样代理在执行过程中，可以自己决定先做什么、后做什么，同时把进度记录在工作目录里的一个 Markdown 文件里。

这个功能在多人协作或长期迭代中格外有用。因为代理的上下文窗口有限，它不可能一直记住所有任务；通过把任务列表外置到文件中，每次重新加载上下文时，代理只需要读取进度文件，就能快速“回忆”起当前状态。我在实践中经常把它当作 AI 代理的“备份记忆”，即使会话意外中断，恢复后也能无缝接续。如果你正在负责一个跨月的迭代，建议每天让代理更新这个进度文件，长期下来它就成了一份非常自然的项目周报素材。

2.4 重构与代码审查

重构技能的目标是减少重复代码、改善类设计、优化 API 边界。它不会大刀阔斧地改动，而是遵循小步重构的原则：每次只改一小块，跑测试确认没有破坏，再继续下一步。配合 TDD 流程，重构会变得非常安全。我在一个老项目里试过让代理对一张大而全的 Service 做拆分，它通过一次只提取一个方法的方式，用了大约十轮小步重构，最后把原本 800 行的类拆成了四个职责清晰的类，期间所有测试一路绿灯。

代码审查技能则像一位资深工程师在做 Code Review。它会从代码可读性、测试缺失、潜在 Bug、性能隐患等角度给出评论，并给出修改建议。最让我惊喜的是，审查技能输出的是人类可读的评论，而不是那种“代码有 bug，请修改”的笼统提示。它会明确指出具体文件和行号，并附带修改前后的对比示例，直接发给团队成员使用也完全没有问题。这比很多商业代码扫描工具更贴近工程师的交流习惯。

2.5 文档与知识管理

Superpowers 的文档技能分成两部分：一部分是生成项目级文档（比如 README、架构说明），另一部分是把开发过程中的决策记录下来（比如 ADR，架构决策记录）。它甚至会要求代理同步更新任务进度和变更日志，形成一种“开发与文档同步演进”的节奏。

以前我不太喜欢让 AI 写文档，因为写出来的东西经常太“浮”，说了半天没有具体的操作说明，读完还是不知道怎么做。但 Superpowers 的文档技能通过结构化管理，要求每个文档里必须有“示例”“执行步骤”“注意事项”这些章节，所以产出的文档更接近“操作手册”，而不是“宣传稿”。如果你维护的是一个对外使用的开源项目，这个能力会特别有价值。我的习惯是每次完成一个模块，就让代理顺手生成一份简短的决策记录，解释为什么选择这个方案，对后续接手的人帮助很大。

3. 安装与配置实操（以 Codex / Claude Code 为例）

3.1 环境准备

Superpowers 本身不是一个独立运行的进程，而是运行在 AI 编程代理之上的技能管理方案，所以第一步是保证你有一个可用的代理环境。我自己实测过 Codex 和 Claude Code，两者都能正常工作。如果你是命令行重度用户，推荐优先用 Claude Code，因为它的 CLI 交互更成熟；如果团队统一用 OpenAI，Codex 也完全没问题。

需要准备的东西包括：一个可用的 AI 编程代理命令行工具、Git（用来拉取和更新技能库）、Node.js（部分脚本依赖），以及基本的开发环境（比如 Java 项目就需要 JDK 和 Maven/Gradle）。我踩过的一个坑是刚开始没装 Node.js，结果技能包里的“脚本执行器”一直报错，所以建议提前装好 Node.js，版本最好在 18 以上。如果是在 Docker 环境里使用，也不要忘记把代理可执行文件的路径和 Node 路径都映射进去，否则启动时容易相互找不到。

3.2 安装 Superpowers

安装分两步：第一步是把项目克隆到本地，第二步是让代理加载初始化配置。常见的安装方式如下：

git clone https://github.com/your-scene/superpowers.git ~/.superpowers cd ~/.superpowers ./install.sh

install 脚本会做两件事：把技能库索引写入代理的配置目录，并在当前用户目录生成一个.superpowersrc配置文件。如果你的技能库目录不在默认位置，可以通过环境变量SUPERPOWERS_HOME来指定。

需要说明的是，不同版本的项目安装细节可能有差异，以上是基于我使用时的安装过程，作为一个常见实践的参考。安装完成后，进入代理交互界面输入/skills，如果能列出技能列表，就说明安装成功。如果列表为空，多半是脚本没有正确找到代理的配置目录，可以检查一下.superpowersrc里的路径是否真实存在。

3.3 配置你的第一套技能

技能有两种使用方式：一种是在对话中直接调用，比如/skill tdd start；另一种是在项目根目录放一个superpowers.yml，通过这个文件指定当前项目要启用的技能集。我建议团队项目优先用配置文件，因为这样可以统一成员之间的工作流，减少同一代码库内出现“每个开发者一种做法”的混乱。

下面是一个简化版的示例：

project: user-service skills: - requirement-clarify - tdd - task-split - code-review - docs-generate

这样设置后，代理每次在项目中启动时都会自动加载这些技能。如果某个需求不需要某一技能，也可以在对话中临时关闭，非常灵活。你也可以通过skill-order字段指定加载顺序，比如先加载需求澄清，再加载任务拆解，最后加载 TDD，这样代理的思考路径会更符合人类工程师的习惯。

3.4 让 Superpowers 接管一个真实项目（Java 示例）

为了演示，我用一个真实的 Java 业务模块来说明：假设需求是“添加一个用户注册接口，包含邮箱唯一性校验”。传统 AI 代理很可能直接生成 Controller、Service、Repository 代码就完事了；而 Superpowers 驱动的代理会按照技能流程执行。

先加载需求澄清技能，它会追问：注册是否需要邮箱验证码？密码规则是什么？是否需要手机号？确认后生成任务清单。接着加载 TDD 技能，代理会在src/test/java下生成失败测试，运行mvn test确认失败；然后补全实现代码，再运行测试；最后进行重构并更新任务列表。整个过程下来，最终产出不仅有代码，还包括测试报告、任务进度和变更说明。我可以随时在对话中查看中间产物，发现问题就及时叫停，而不是等它全部跑完才发现方向错了。

如果你实际使用后发现生成的任务清单只存在于对话里，没有写到本地文件，多半是任务拆解技能没有正确加载，可以检查superpowers.yml里是否包含了task-split技能。这里有一个我强烈建议的小技巧：把进度文件也纳入版本控制，每天提交一次，这样即使模型重写对话，项目的“记忆”也不会丢，相当于把 AI 代理的短时记忆变成了项目级的持久记忆。

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

4.1 代理“失控”：技能执行偏离轨道

我遇到最多的现象是，代理加载了技能包，但执行到一半开始“自由发挥”。比如 TDD 顺序变成了先写实现再补测试，或者任务清单越列越乱，甚至开始改无关代码。大部分时候原因不是模型能力不够，也不是 Superpowers 框架失效，而是技能上下文不够强。

常见解决方案是，在项目根目录放一个superpowers.yml，把要遵循的技能明确列出来，并在对话开始时点名当前阶段，比如“现在进入 TDD 阶段，请先写测试，不要先写实现”。如果还是跑偏，就用/skill reset重置技能状态，再重新加载对应技能包。我在实践中发现，只要在关键节点上多“点名”几次，代理的纪律性会明显提高。

4.2 环境变量与依赖缺失

运行 Java 项目时，Superpowers 调用 Maven 或 Gradle 需要正确的环境变量。最常见的问题是JAVA_HOME没设置，或者代理运行时的 PATH 和你的 shell 环境不一致，导致它执行mvn test时提示命令找不到。

我建议把所有环境变量写入代理的启动脚本，或者在superpowers.yml里声明env字段。另外，如果某个技能依赖命令（比如tree、jq），在安装时最好把这些基础工具先装好，避免执行到一半才发现工具缺失。踩过几次坑后，我的做法是在安装完 Superpowers 后先跑一次/skill doctor，它会帮你检查常见依赖是否齐全，能省掉很多后续排查时间。

4.3 模型上下文窗口不够用

Superpowers 的技能文件较多，如果项目很大，技能描述加进度文件很容易把上下文撑满。我的经验是：不要在同一会话里启动全部技能。比如把项目分为“开发阶段”和“审查阶段”，在superpowers.yml中用注释临时关掉不需要的技能，让代理聚焦在当前阶段。

另外，任务进度文件要写得精简，只保留待办、完成状态和关键决策，不要把大段讨论记录全部塞进去。模型把宝贵上下文窗口用在读代码和写代码上，效果会远远好于去读一堆历史聊天记录。我甚至会给进度文件设置一个最大行数，一旦超过就让代理归类压缩一次，保持文件始终“小而可读”。

4.4 与现有 CI/CD 的衔接

如果你的代码库已经接入了 GitHub Actions 或 GitLab CI，最理想的情况是让 Superpowers 的技能复用现有 CI 命令。比如 TDD 技能的测试命令，不要在技能里写死成mvn test，而是建议从项目配置中读取。我的做法是在superpowers.yml里设置test-command字段，让代理使用的命令和 CI 里的命令保持一致。

否则很容易出现本地测试通过、CI 却失败的情况，往往就是因为两边调用的测试命令不一致。例如 CI 里用的是mvn verify，但本地代理用的是mvn test，后者不会运行集成测试，等推到远程才发现问题，返工成本会高很多。这是一个很隐秘但影响很大的配置项，值得在项目初始化时就设定好。

4.5 避坑清单与经验

整理一个我在真实项目里反复用到的速查表，方便对照排查：

这里最想强调的一点是：Superpowers 并不是银弹，它不会让 AI 编程代理瞬间变成 100 分的工程师，但它确实能降低很多不确定性。我个人的体会是，与其纠结模型的能力边界，不如先给代理搭好一个稳定的工作流骨架。只要“发现目标—拆解任务—执行测试—审查重构—沉淀文档”这个闭环能稳定跑起来，开发效率的提升是肉眼可见的。尤其对团队来说，统一的工作流意味着每个人从代理身上得到的结果质量更接近，Code Review 的标准也更容易对齐。

最后再分享一个我一直坚持的小技巧：每次让 Superpowers 完成一个里程碑，我都会让它用“变更日志”技能把这段经历总结成一篇简短的 Markdown 文档提交到仓库里。几个月下来，这些文档就成了团队最宝贵的知识库，新成员接手项目时只要翻一遍记录，就能少走很多弯路。如果你的团队也在用 AI 编程代理，不妨从今天开始给它们配上一套完整的工作流，Superpowers 是一个相当合适的起点。