企业官网建设流程全解析

1. 为什么Agent会“自由发挥”：先搞懂问题出在哪

先说个现象。我身边越来越多朋友开始用Claude Code、Codex这类AI编程工具跑全栈项目，但大部分人反馈惊人的一致：小需求很爽，大项目必翻车。

单个函数、单个页面，Agent基本能一次写对。可一旦需求变成“做一个带用户体系、支付回调、后台管理的完整系统”，它就开始表演了：一会儿自己“发明”一个数据库字段，一会儿跳过了异常处理，一会儿把前端样式写成了自己以为的样子，压根没按你项目的约定来。

这不是模型不够聪明，而是Agent根本没有一套可执行的“行为契约”。模型的天性是“概率续写”，你给它一个模糊指令，它就会按训练数据里最常见的方式去“自由发挥”。工程规范恰恰要求“一致、可验证、按约定执行”，这两者的冲突，就是所有AI编程翻车的根源。

对这个痛点，GitHub上最近热度很高的开源项目Superpowers，就是一套专门解决问题的答案。它不是一个IDE插件，也不是一个大模型，而是一组非常巧妙的“技能包+纪律流程”，用严格的执行步骤约束Agent：先思考、再规划、后动手、必须测试。说白了，就是给Agent装上纪律引擎，让AI从“自由发挥”切换到“工程规范”模式。

这篇文章，我会结合自己的实际体验，把Superpowers的定位、安装、核心技能、实战流程、常见坑一次性讲透。适合正在用Claude Code等Agent工具做真实项目、但经常被“烂尾代码”折磨的人。

1.1 大模型的天性与工程规范的冲突

我一直觉得，工程规范的本质是“反自由的”。它要求每个人在写代码之前，先理解上下文、遵守约定、按照既定流程执行。而大模型恰恰相反——它每一步都在“猜”最可能的答案，没有全局记忆，也没有“责任意识”。

你让Agent做一个登录功能，它大概率会写一个标准模板：用户名密码输入框、校验、调接口、存Token。它不会主动问你的项目里有没有现成的请求封装、有没有统一的错误码规范、UI组件库用的是哪套。因为问问题是“成本”，直接写是“收益”，模型天然倾向低成本的路径。

这就是“自由发挥”的真相：不是Agent笨，是它没有机制去强制自己“先了解再动手”。传统团队靠Code Review、技术方案评审来约束人，可Agent场景下，谁来约束模型？Superpowers就是来解决这个“谁约束模型”的问题的。

1.2 普通提示词工程的两大短板

很多人说：那我用提示词约束它不就行了？“你是一个严谨的工程师，先分析需求再写代码，别忘了写测试。”

听起来对，实际没用。原因有两个：

第一，提示词是“软约束”，不是“硬流程”。模型没有“执行完步骤1才能进入步骤2”的意识，它可能读完你的提示词，转头就按习惯生成代码了。提示词写得再好，也只是提高了“遵循概率”，不是100%可靠。

第二，一次性提示词没有“状态管理”。真实项目开发是分多轮对话、多阶段验证的。你需要Agent先出方案、你确认、再写代码、跑测试、修bug。普通对话里，这个流程靠人肉SDLC，一不小心就会乱。

Superpowers把这两件事补上了：它用一个个独立的技能文件，把流程拆成可重复执行的步骤；再用CLAUDE.md这类规则文件，把纪律写进Agent的“潜意识”。这不是提示词的量变，是约束机制的质变。

1.3 Superpowers的对症解法：让“纪律”变成可执行代码

我打一个比方。普通提示词是“你跟AI口头说：你要守规矩啊”；Superpowers等于“你直接给AI装了一套SOP手册+检查清单+门禁闸机”。

具体来说，它的核心设计有三层：

• 技能目录：按需加载的一组Markdown技能文件，比如“头脑风暴”“编写计划”“架构设计”“TDD实施”，每个技能都定义了标准操作流程。
• 全局纪律文件：通过项目的CLAUDE.md或Agent配置，告诉AI“动手之前必须经过哪些流程”“哪些状态不允许直接进入编码”。
• 可验证的流程节点：关键步骤设计成“先输出方案、等待人类确认、确认后再继续”，相当于在Agent的执行链路上加了一道道人工门禁。

这三层配合下来，Agent的“自由发挥空间”被压到最低——不是靠模型自觉，而是靠流程强制。我自己跑下来的感受是：第一次觉得AI编程有了“工程感”，像带了一个流程意识极强的外包工程师，而不是一个脑子灵活但不懂规矩的实习生。

2. Superpowers到底是什么：拆解这套“纪律引擎”

有了前面的铺垫，你大概知道Superpowers是干什么的了。下面我们把它拆开看，弄清楚它到底包含什么、怎么运行、和你可能听过的其他工具是什么关系。

2.1 官方定位与核心组成

Superpowers由Jesse Vincent（知名开发者，也是Hackintosh项目的维护者之一）发起，GitHub仓库名叫obra/superpowers。它定位非常清晰：为Claude Code等编程Agent提供“技能增强+流程纪律”的能力层。最初是为Claude Code设计的，现在也能适配其他支持MCP或技能加载的Agent工具。

我之前搜到有人说“Superpowers skill是干嘛的”，其实“skill”就是它的灵魂。整仓库安装后，Agent的skills目录里会出现几套成体系的技能文件，每一套都是一份“带步骤的标准化作业指导书”。

我归纳一下，核心组成有三块：

这套结构非常像人类团队里的“规章制度+岗位手册”。CLAUDE.md是公司制度，skills是每类工作的SOP，commands是常用指令的快捷按钮。

2.2 从Brainstorm到Architect：核心技能解码

Superpowers最有价值的，是它内置的几个核心技能。我逐一说说它们各自管什么。

Brainstorming（头脑风暴）

这个技能负责“需求澄清”。AI拿到一个模糊需求后，不是直接写代码，而是先向你提一堆问题：这个功能面向谁？有没有边界条件？你倾向于方案A还是方案B？它通过多轮对话，把模糊的意图压成明确的需求描述。这个环节看起来“废话多”，但恰恰是最能避免后期返工的部分。

Writing Plans（编写执行计划）

需求明确后，Agent不会立刻动手，而是先把任务拆解成一份可执行的计划：要改哪些文件、新增哪些模块、先后顺序是什么、风险点在哪里。它还会主动识别出“哪些实现你可以接受，哪些不行”。这相当于技术方案评审的AI版。

TDD（测试驱动开发）

这是我个人最欣赏的部分。Superpowers把TDD的循环严格固化进Agent：先写一个失败的测试 → 运行测试确认失败 → 写最小实现代码 → 运行测试确认通过 → 重构。每一步都有明确的“验证动作”，不允许跳过。你想想，这比让AI直接甩给你一大段代码再慢慢调bug，不知道高到哪里去了。

Architect（架构设计）

当一个任务涉及多个模块、数据流、依赖关系时，这个技能会先帮Agent建立起“系统级视野”。它不会急着写具体类，而是先画出模块边界、定义接口契约、梳理数据流，最后才进入编码阶段。相当于给Agent装了一个“架构师前置检查器”。

2.3 和OpenSpec、Claude Code的关系：你该装哪些

很多人在搜“claude code+openspec+superpowers三件套”，我也被这个组合种草过。实际用下来，三者的分工是这样的：

• Claude Code：底层Agent，负责理解语言、操作文件系统、执行命令，相当于“双手”。
• OpenSpec：一个轻量级的“规格管理”工具，负责把需求变成结构化的规格文档（spec），相当于“需求翻译器”。
• Superpowers：负责“流程纪律”，约束Agent按工程规范执行，相当于“大脑的强制流程引擎”。

你可以把Superpowers单独用，也可以和OpenSpec叠加。我的建议是：如果你已经用Claude Code跑过几个小项目、被翻车折磨过，那直接上Superpowers就够；如果你在建一个需要多人协作、长期维护的复杂项目，再叠加OpenSpec做规格层管理。它们不是竞争关系，是互补关系。

3. 安装与实操：把纪律引擎装进你的Agent

好，理论说完了，下面进入动手环节。我会按我实际安装使用的顺序，逐步讲清楚每一步怎么操作、会遇到什么坑。

3.1 环境准备：你需要什么前置条件

先列一下我用的环境，供参考：

• 操作系统：macOS（Linux、Windows的WSL也支持）
• 已安装：Node.js 18+（用来跑Claude Code）
• Agent环境：Claude Code CLI（我已配置好API Key）
• 额外工具：Git

严格来说，Superpowers只是一个“技能包”，不需要编译安装，但它依赖Claude Code（或类似支持skills机制的Agent）来运行。所以你得先把Agent本体配好。

如果你还没装Claude Code，官方文档有很详细的引导，核心就两步：安装CLI工具，然后用Claude账号授权或配置API Key。这里我不展开，直接进入Superpowers的安装。

3.2 安装步骤详解：克隆仓库、配置CLAUDE.md、加载技能

官方推荐的安装方式非常简单。我把我的实际操作过程完整抄出来。

第一步：克隆技能仓库到本地

git clone https://github.com/obra/superpowers.git

注意，别把仓库克隆到系统临时目录。我建议放在一个稳定的路径，比如~/projects/superpowers。因为后面你需要用绝对路径引用它。

第二步：把技能复制进项目的skills目录

这里有一个关键点：Superpowers的技能是“按项目加载”的。你需要在每一个要用它的项目目录下，把技能文件放进去。

cd ~/your-project mkdir -p .claude/skills cp -r ~/projects/superpowers/skills/* .claude/skills/

如果你用的是Claude Code，它会自动读取.claude目录下的技能配置。这一步做完，Agent就“看到”了这些技能。

第三步：配置CLAUDE.md，注入纪律规则

Superpowers仓库里自带了CLAUDE.md的模板，你需要在项目根目录创建一份（或合并进已有的CLAUDE.md）。

cp ~/projects/superpowers/CLAUDE.md ./CLAUDE.md

我有一次图省事，直接跳过了这步，结果Agent虽然加载了技能文件，但完全没按照“先计划再执行”的流程走。原因就在于CLAUDE.md才是“纪律”的入口，技能文件只是工具，缺了纪律文件等于光有工具没人管理。

第四步：重启Agent会话，验证加载

配置完成后，关掉当前Claude Code会话，重新启动。然后输入一条命令确认技能是否被识别：

/help

如果配置成功，帮助信息里会列出superpowers相关的技能条目。看到它们，就说明安装成功了。

3.3 第一次实战：从头脑风暴到任务拆解

安装只是热身，真正让我觉得“这玩意儿值”的，是第一次完整跑通流程。

我拿一个很典型的Demo来演示。假设你走进Agent，说：“帮我给博客加一个评论功能。”

换成平常，Agent马上就开始建表、写接口、画前端了。但装了Superpowers之后，它会先进入思考模式，然后紧接着触发Brainstorming技能。它不会急着写代码，而是先问你：

• “评论功能目前的设计范围是什么？只有登录用户才能评论，还是允许匿名？”
• “是否需要嵌套回复？还是只做平铺列表？”
• “数据存储有没有现成的表结构，还是需要我新建？”
• “前端样式有没有设计要求？还是先用默认样式？”

这个阶段其实就是在帮你把需求从“一句话”细化成“一段明确的规格”。等你逐条回答完，它才会生成一份执行计划，列出具体操作步骤。整个过程非常像一个靠谱的产品经理在跟你确认需求。

我建议新手用第一次就跑一遍这个流程，别嫌它“多话”——后面省下的返工时间，是这几分钟问问题的十倍以上。

4. 核心环节实录：用Superpowers跑通一个全栈小功能

这一节我拿自己最近做的一个内部工具页面来举例，完整展示它是怎么把“需求-计划-实现-测试”串起来的。为了方便理解，我把过程压缩成三部分：需求定义、实施执行、验收复盘。

4.1 从一句话需求到完整方案：Brainstorming+Planning的联动

我的需求很具体：“给后台管理页面加一个用户列表，支持按邮箱搜索，展示最近登录时间。”

以前我直接把它丢给Agent，它大概10秒就开始写代码。这次，在Superpowers的“监督”下，它先进入Brainstorming，反复确认了几个关键点：

• 用户字段到底包含哪些？（光“最近登录时间”就追问了是数据库里的last_login_at还是需要从别的服务拉取）
• 搜索是基于前端过滤还是后端接口查询？（这决定了要不要新写接口）
• 分页要不要做？最多展示多少条？
• 现有项目有没有统一的Table组件？样式风格用哪套？

这些问题一个一个问下来，我当时差点有点不耐烦，但事后看，每一个问题都恰好卡在“会导致后期返工”的决策点上。确认完之后，它生成了一份结构化的plan.md，包含：要新增的组件、要改的接口、要建的数据库索引、以及测试覆盖范围。这份文档直接在项目里生成，我可以随时review。

这个环节给我的最大启发是：Superpowers不是让AI变得“更聪明”，而是让AI变得“更认怂”——承认需求有歧义、主动确认而不是瞎猜。这恰恰是所有资深工程师最该有的习惯。

4.2 测试驱动实施的完整链路：红-绿-重构循环

方案确认后，进入代码实施阶段。Superpowers默认走的是TDD流程，整个过程让我印象很深。

第一步，它先写一个测试文件。比如对于“按邮箱搜索”这个功能，它先定义好测试用例：传入一个邮箱关键词，返回匹配的用户列表；传入空关键词，返回全量列表；传入不存在的邮箱，返回空列表。跑完测试，结果当然是失败——因为功能还没写。

第二步，它才去写最小实现代码。把接口逻辑补上、查询语句写好，然后再次运行测试，直到全部通过。

第三步，它进入重构阶段，检查代码风格、抽离重复逻辑、补充异常处理。

整个过程中，每一段代码都先有测试“背书”。这基本上杜绝了“Agent自己写完就跑，一堆隐藏bug”的情况。我以前跑普通AI编程，最怕的就是它自信满满输出300行代码后说“完成了”，一跑全是问题。现在它跑完会主动说：“测试已经通过，但我在重构时发现email字段存在把空字符串当成有效值的问题，已自动处理并补了一条测试。”这种“自主补测试再修复”的行为，是真的有工程素养了。

4.3 流程中的关键节点：哪些步骤不建议跳过

如果你自己上手跑，有四个节点我强烈建议你别偷懒跳过：

• 不要跳过Brainstorming环节。哪怕你的需求已经很明确，也要让Agent至少列一遍它理解的约束。很多坑就是在“我以为是A，它以为是B”中埋下的。
• 不要直接批准它一次性写完所有功能。Superpowers允许你分步走，比如先做数据层、再做接口、最后做前端。你完全可以每一步结束都“检查一下再继续”。只有重要里程碑才需要你介入，细节速度不用太担心。
• 不要忽略它的“测试失败”日志。如果它主动说“这个测试挂了”，先别急着让它“修好就行”，可以追问一句“挂掉的深层原因是什么”。很多时候，Agent会自己发现额外的边界问题。
• 不要在计划阶段随意打断它。计划生成过程中，Agent会按模板列出文件清单、任务依赖。这个阶段你只需要看，不需要频繁插话。

我自己总结的一个小经验：越是看起来“多此一举”的步骤，越可能在后期帮你挡下大坑。Superpowers的设计者把大量工程最佳实践塞进了流程，你只管顺着走就行。

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

最后整理几个我在使用中遇到过的典型问题和排查方法。如果你是刚入手，这份速查表能帮你少走不少弯路。

5.1 安装与配置阶段的坑

问题1：我克隆了仓库、复制了skills，但Agent就是不按流程走，直接开始写代码。

排查思路：大概率是CLAUDE.md没生效。确认一下项目根目录有没有CLAUDE.md文件，以及文件里是否包含always think then act这类关键纪律声明。另外，Agent有时需要重启会话才能重新加载配置。

问题2：技能文件复制过去了，但/help里看不到。

排查思路：确认复制路径是否准确。是.claude/skills/，不是skills/也不是.claude/skill/。我有次打错了单词，弄了半天才发现。

问题3：技能加载了，但Agent执行起来很“啰嗦”，一直在提问，效率变低了。

排查思路：这其实不是故障，是特性。但如果觉得过度，可以在CLAUDE.md里调整“确认次数”。比如为低风险任务设置“默认可直接执行，无需额外确认”。灵活调整纪律强度是合法的，毕竟不同项目容错度不一样。

5.2 使用过程中的运行问题

问题4：执行到一半，Agent卡住了，没有继续下一步。

排查思路：多数情况是它在你没有注意到的位置等待确认。看看终端输出里有没有“[]”或者“等待你的意见”之类的提示。有时候是因为网络波动或工具链超时，直接输入“继续”即可。

问题5：测试全过了，但我手动一测，发现功能还是不符合预期。

排查思路：大概率是需求理解偏差，不是代码逻辑错误。回到Brainstorming环节，把你真实想要的场景重新描述一遍，然后重新生成计划。这种情况在传统开发里叫“需求变更”，很正常，Superpowers的优势是变更起来很快——有测试兜底，改动不用担心连锁反应。

问题6：在团队项目里，其他人不相信AI生成的代码，怎么办？

排查思路：把TDD测试记录留下。我现在的做法是，Agent每完成一部分，就保留对应的测试文件和运行日志。这样不管是自己还是同事review，都能直观看到“这段代码有测试证明”。这是最有力的说服材料。

5.3 最后的几条独家建议

• 建议给每个项目都单独安装一套Superpowers，不要搞成全局一次性配置。每个项目的工程约定不一样，独立的技能包隔离性更好。
• 除了编码，也可以让它用Superpowers的流程做重构。有一次我让它梳理一个老项目的混乱模块，它同样走了“分析现状-写计划-小步重构-测试验证”的路径，体验很好。
• 关注仓库的更新。Superpowers迭代很快，新技能和流程优化经常出现。保持仓库最新，能持续吃到工程规范方面的改进红利。

把Superpowers调顺之后，我个人最大的体会是：AI编程的瓶颈，从来不是模型能力，而是流程缺失。模型再聪明，没有一个强制的纪律框架，它依然是个聪明但不受控的实习生。而一旦纪律装上，它的产出质量会迅速向“资深工程师”靠拢。这个转变，就是Superpowers这类工具存在的最大价值。如果你也在用Agent做项目，真心建议花一个晚上装上它、跑一遍流程，相信你会回来感谢我的推荐。