企业官网建设流程全解析

如果你也试过让 AI 编程助手直接“给我写一个登录模块”，大概率会拿到一堆能跑但经不起细看的代码——没有异常处理、没有参数校验、数据库连接裸写在业务函数里。直到我换了打法，用 Superpowers 框架把 AI 编程助手按软件工程套路来管，情况才真正改观：先问需求、再拆工作包、测试先行、最后评审。这篇文章就用我的真实踩坑记录，讲讲 Superpowers 是怎么让“会写代码的 AI”变成“懂软件工程开发的 AI”，以及你在落地时最容易忽略的细节。

这个框架特别适合两类人：一是被 AI 生成的“一次性代码”坑过、想把它用在正经项目上的开发者；二是正在做软件工程课程设计、毕业设计的学生——你想想，老师最常问的就是“需求分析呢？测试呢？架构怎么设计的？”，而 Superpowers 逼着 AI 把这些“软件工程套路”全部走一遍，最后整理出来的文档就是现成的答辩素材。

1. 为什么我让AI“按套路”干活，而不是直接写需求

先说个很反直觉的结论：AI 写代码翻车，很多时候不是模型不够聪明，而是我们压根没给它一个工程化的约束环境。像我以前用 AI 干活，就是打开对话框，敲一句“帮我写一个用户中心”，它噼里啪啦一分钟生成八百行代码，我往项目里一贴——前三天爽，后三周苦。

1.1 直接写代码的AI为什么总是“只快不优”

AI 在没有流程约束时，天然会选择最短路径：你问它要功能，它就直接给你函数；你问它要模块，它就直接给一张表。它不会主动停下来问你“这个用户状态要不要存 Redis”“密码找回走邮件还是短信”“接口要不要幂等”。

我遇到过的典型翻车现场包括：AI 用一个静态数组模拟用户列表，整个“用户模块”根本连不上数据库；它在三个不同文件里各写了一份日期格式化工具函数；还有一次，它生成的删除接口没有做权限校验，任何登录用户都能删别人的数据。这些问题的根源不是它笨，而是它缺少一个“项目全局视野”和“开发规范约束”。

拿装修来类比：你请一个水平很高的工人来砸墙，但如果你不给他看户型图、不告诉他哪里是承重墙，他照样敢抡大锤。AI 也是这样，你让它“写代码”，它就只盯着代码本身，管你架构不架构、测试不测试。软件工程里的需求分析、概要设计、详细设计、编码、测试、维护这些阶段，如果你不强制它走，它一律省略。

1.2 软件工程套路到底指什么，Superpowers做了什么

我在软件工程导论课上背过经典的瀑布模型、迭代模型，当时觉得这套流程相当啰嗦。工作之后才明白，这些“套路”存在的意义不是增加文档量，而是把不可控的“一次性写对”变成可控的“分步逼近正确”。

Superpowers 这个框架本质上就是把这些软件工程阶段，翻译成了 AI 能执行的“技能（skills）”。它不让 AI 一上来就写代码，而是强制它按这个顺序来：

• 先收集需求，生成项目简报（Project Brief）
• 再识别技术约束，沉淀系统模式（System Patterns）
• 然后把需求拆成工作包（Work Package）
• 每个工作包再拆成任务清单，任务里要求先写失败测试
• 测试通过后还要做一次代码审查

你对比一下传统方式和 Superpowers 的区别，就很直观：

你可以看到，Superpowers 不是给 AI 加了什么黑魔法，而是把软件工程里本来就有的“套路”变成了 AI 的执行协议。这样一来，AI 的能力没有变，但行为模式从“拍脑袋写码”变成了“按图纸施工”。

2. Superpowers框架的基本盘：安装、技能和核心概念

我知道你关心的第一件事一定是：这东西怎么装？怎么用？我当初也是直接冲到 GitHub 上看 README，然后开始折腾。下面这部分是基于我实际操作的记录，不保证和未来版本的菜单完全一致，但大方向不会变。

2.1 安装与激活：一行命令让AI“换脑子”

Superpowers 是给 Claude Code 这类 AI 编程助手用的插件框架。安装原理大概是：它把一堆写好的“技能”灌进 AI 的工作目录，让 AI 在对话时能看到“我应该先写计划，而不是先写代码”的操作指南。

我当时是在 Claude Code 里通过插件市场安装的，大致操作是：

1. 在 Claude Code 会话中输入/plugin marketplace add添加 Superpowers 仓库；
2. 然后用/plugin install superpowers安装插件（如果你的版本支持，也可以直接运行/install-superpowers来初始化技能目录）；
3. 安装完成后，项目.claude/skills目录下会出现大量技能文件夹，例如work_package_plan、work_package、task_list、tdd、code_review等。

装完那一刻我有点傻眼：好家伙，它往项目里塞了二十多个技能文档。后来我才知道，这些文档就是 AI 的“操作手册”，正常情况下 AI 会自己根据当前任务选择合适的技能来读，不需要你手动去翻。

2.2 项目简报与系统模式：AI的“需求说明书”和“架构规范”

先聊 Project Brief。它相当于软件工程里的《需求规格说明书》，里面必须写清楚项目目标、用户故事、功能范围、非功能需求、技术栈、API 设计等。Superpowers 的流程里，AI 在动手前会主动问你一系列问题，然后由它生成一份结构化的project_brief.md。

我特别想强调的是 System Patterns，也就是系统模式。一开始我觉得这东西很虚，直到它帮我避免了一次大返工。比如我在系统模式里写下“所有数据库访问必须通过 Repository 层，禁止在 Controller 里直接写 SQL”，后面 AI 生成的代码就会严格遵守。如果你不在最初把这个约束写死，AI 就会按它自己的“偏好”去写，第二次生成又变成另一种风格，代码跟拼盘一样。

系统模式的本质，是把软件工程里的“架构设计原则”沉淀成 AI 可查阅的规则库。它不仅能写“禁止直连数据库”，还可以写“错误码统一用XXX_BUSINESS_ERROR格式”“所有外部请求必须做参数校验”“日志必须包含 requestId”。这些规则一旦进入 AI 的上下文，它写出来的代码就会自动贴合团队规范。

2.3 工作包：把大需求拆成“一下午能做完”的小模块

Superpowers 里最核心的单元不是任务，而是 Work Package（工作包）。我把一个工作包理解为：一个可以独立交付、独立测试、包含明确边界的小功能块，大概就是一个人一个下午能完成的工作量。

AI 会先根据项目简报生成一份work_package_plan.md，把整个系统拆成多个工作包。比如我之前做一个带鉴权的待办 API，它拆成了：

• Work Package 1：项目脚手架 + 基础配置
• Work Package 2：用户注册
• Work Package 3：用户登录与 JWT 签发
• Work Package 4：待办事项 CRUD
• Work Package 5：越权访问防护与权限测试

每个工作包里，AI 都会给出目标、变更文件、验收标准、依赖关系、风险点。这个结构让我特别有安全感，因为它像极了敏捷开发里的迭代计划——我不用再担心 AI 跳到一个没有边界的状态里疯狂改文件。

下面是一份简化版的工作包计划，你能直观看到它的信息密度：

# Work Package 3：用户登录与JWT签发 ## 目标 实现邮箱+密码登录，校验通过后签发 JWT，并写入 Authorization 要求。 ## 变更范围 - src/auth/login.ts（新增） - src/auth/login.test.ts（新增） - src/repositories/user_repository.ts（修改：增加按邮箱查询） ## 完成定义（Definition of Done） - 登录接口 POST /auth/login 返回 200 和 token - 密码错误返回 401，不返回任何 token - 字段缺失返回 400 和错误消息 - 测试覆盖成功、密码错误、字段缺失三条路径 ## 外部依赖 - Work Package 2 提供的用户表结构和密码加密工具 ## 风险 - JWT 密钥管理需要提前在环境变量中配置，不能硬编码

有了计划文档，AI 每写一个模块都知道自己“为什么存在”“边界在哪里”，而不是凭感觉堆代码。

3. 实例演练：我用 Superpowers 从零搭一个带鉴权的待办API

讲概念容易，看实战才有体感。下面是我一个周末拿 Superpowers 做小型项目时完整记录下来的流程，你可以跟着这个思路复现。

3.1 项目启动：AI 先“审问”你，而不是先写码

我在会话里敲下/start-project之类的命令后，AI 并没有直接问我“要什么技术栈”，而是弹出一连串问题，我印象很深的有这几个：

1. 这个产品的核心目标是什么？用户是谁？
2. 是否已有指定的技术栈、数据库、部署平台？
3. 需要哪些用户角色？是否包含权限系统？
4. 认证方式有偏好吗？Session 还是 JWT？
5. 项目有哪些明确不做的功能？

当时我有点不耐烦，心想“你直接开写不就完了”。但实践证明，这一步极其关键。因为 AI 一旦在没确认“不做什么”的情况下开写，它就会把“忘记密码”“邮箱验证”“第三方登录”这些需求全给你脑补出来，直接把你项目撑爆。

我把我对上面问题的回答发过去之后，AI 生成了一份项目简报。里面除了功能列表，还专门有一节“非目标”，写着“不支持第三方登录、不支持邮件验证、不支持找回密码”。这就是需求边界，有了它，后面 AI 就不会在登录模块里顺手写一个邮件服务。

3.2 从工作包到任务清单：TDD被写进了每个任务

选定一个工作包之后，Superpowers 会把工作包展开成任务清单。最让我惊喜的是，每个任务里都内置了“先写失败测试→跑测试→写实现→再跑测试”的循环。比如它生成的 Work Package 3 任务清单长这样：

Task 1：搭建登录接口的测试骨架 - 创建 login.test.ts - 准备测试用数据库 fixtures - 先断言 POST /auth/login 返回 400（缺字段） - 运行测试，确认失败 Task 2：实现登录接口字段校验 - 实现 login.ts 的入参校验逻辑 - 运行测试，确认通过 Task 3：实现密码校验与JWT签发 - 编写查询用户 + 比对密码哈希的代码 - 在测试中注入错误密码，断言 401 - 运行测试，确认通过

我发现这个任务清单的精妙之处在于，它把“测试驱动开发”的节奏拆成了最小指令。AI 执行 Task 1 时，真的会先写一个测试文件，然后运行一次测试，把失败结果发给我看，再继续写实现。它不再是一个“写完所有代码再告诉你好消息”的黑盒子，而是像一个实习生在做 TDD 练习，每一步都有验证。

不过这里有个小坑：AI 生成的测试往往只覆盖“快乐路径”，像“密码错误”“字段缺失”这种边界用例，它通常只在任务清单里写，实际测试代码未必写全。所以我建议你在让它执行 TDD 任务时，明确要求“把任务清单里的负面用例也写成测试”，宁可在测试上啰嗦一点，也别放过边界。

3.3 实现后的代码审查：AI自己给自己当reviewer

一个工作包实现完，Superpowers 会进入代码审查阶段。它会检查目标是否达成、变更是否在工作包边界内、测试是否覆盖关键路径，并给出一个审查结论。我印象里它审查出来的问题很实际，比如“JWT 密钥从环境变量读取的代码没有做启动时校验”“删除待办的接口只验证了登录，没有验证资源归属”。

这个阶段的体验很像团队里有人帮你过代码，虽然 AI 的自审不可能替代真人评审，但它能做两件很实在的事：一是找出前后逻辑不自洽的地方，二是把“完成定义”里每条验收标准逐项核实。

有一次它发现，我在测试里用了真实数据库，而工作包计划里写的是“使用内存数据库”，于是它停下来提醒我“测试数据会污染开发库”。这种细节，以前让 AI 直接写代码时根本不会有人提醒我。

4. 让 Superpowers 真正好用的几个配置习惯

用了一段时间之后，我总结出一些“非官方”但非常有效的配置习惯。这些细节文档里不一定写得清楚，但它们决定你是被框架带着走，还是你带着框架跑。

4.1 把团队规范写进 CLAUDE.md，AI才能“懂规矩”

Superpowers 虽然提供了技能框架，但它决定不了你的代码风格。你需要把团队的硬性规范写进项目根目录的CLAUDE.md，AI 每次启动都会读它，等于是你的“永久记忆”。

我在 CLAUDE.md 里写的东西大致是这样：

# 项目工程规范 - 语言：TypeScript，严格模式 - 目录：src/api、src/repository、src/service、src/utils - 禁止在 Controller 中直接操作数据库 - 所有接口统一返回 { code, data, message } 结构 - 时间统一使用 UTC 存储，字符串格式 ISO 8601 - 新增依赖前必须说明理由

把这段配置加进去之后，AI 生成的代码风格立刻“驯化”了很多。之前它写文件喜欢全部塞在根目录，之后就知道按分层结构放了。所以说，Superpowers 管“流程”，CLAUDE.md 管“规范”，两者缺一不可。

4.2 明确项目的“当前阶段”，让AI切换合适技能

Superpowers 的技能很多，但 AI 有时候不知道当前应该用哪个。比如你还在做详细设计，它却想直接跳到 TDD 写测试。这时候你需要在对话里明确告知当前阶段，或者写在工作包计划里。

我习惯在项目简报里加一个“当前阶段”字段，比如：

当前阶段：Work Package 3 已开始，处于编码实现阶段 允许使用的技能：tdd、code_review 暂缓使用的技能：work_package_plan、frontend_generation

这个小习惯能显著减少 AI 的“自我发挥”。它知道自己现在是一个执行者，而不是规划者，就不会频繁打断你要不要改需求了。

4.3 一次只跑一个工作包：别让上下文窗口被撑爆

这是我在实际使用中踩得最深的一个坑。有一回我图省事，让 AI 一口气把 5 个工作包全跑了。一开始还好，到第三个工作包的时候，它已经开始忘记 System Patterns 里“禁止在 Controller 里直连数据库”的规则了，生成的代码又开始出现裸 SQL。

原因很简单：上下文窗口是有限的，前面塞了太多工作包计划、测试输出、审查报告，后面的对话自然会丢信息。后来我改成“一个工作包一个会话”的策略：执行完当前工作包，人工确认完成后，用/compact压缩上下文，再进行下一个。这样做之后，AI 的行为稳定性明显提高。

注意：如果你的项目比较大，还可以在完成一个工作包后，让 AI 先总结一行“已完成内容”再清空上下文。这样下一个会话里你只需要把这行总结和新的工作包计划丢给它即可。

5. 踩坑与边界：Superpowers 不是万灵药

说了一堆好话，也得讲讲它让人抓狂的地方。毕竟这是来自真实使用中的教训，比官方文档更值得参考。

5.1 流程过重：小改动也会被“仪式化”

最让我头疼的，是改一个小 bug 也要走完整流程。有一次线上有个按钮颜色错了，我想让 AI 顺手改一下 CSS，结果它开始问我“这个需求的项目目标是什么？涉及哪些用户故事？”我当场血压就上来了。

后来我学乖了：像这种单点修改，直接绕过 Superpowers 技能，用普通对话让 AI 改，或者在工作包计划里明确标注“Hotfix 不需要完整流程”。框架是用来管大需求的，不是用来束缚小手脚的。

5.2 AI生成的测试质量参差不齐，别全信

Superpowers 强制 TDD，这本身是好事，但它逼出来的是“有测试”，不一定等于“好测试”。AI 写的测试往往偏向验证正常流程，对异常输入、并发冲突、数据隔离这类深层问题覆盖不足。

比如它给登录接口写测试，可能只测了“正确密码返回 token”和“错误密码返回 401”，但不会主动测“连续输错五次是否锁定账号”“token 过期后刷新机制是否正常”。这些测试用例你得自己心里有数，并手动写进任务清单，再让 AI 去执行。相信我，把它当“流程执行者”而不是“测试专家”，你会省心很多。

5.3 适合的土壤与不适合的场景

结合我的实践，我总结了一下 Superpowers 的适用边界：

适合的场景：

• 从零开始的新项目，尤其是刚起步、还没有历史包袱的业务系统
• 需要长期维护的模块，代码质量和测试覆盖很重要
• 软件工程课程设计、毕业设计这类需要完整过程文档的项目
• 多人协作项目中需要 AI 遵守统一架构规范

不适合的场景：

• 快速概念验证（POC），只需要“跑起来看效果”
• 临时脚本、工具函数，不值得走一遍流程
• 在庞大且混乱的旧代码仓库中做小改动，AI 很难建模全局依赖关系
• 团队没有明确架构规范时，用 Superpowers 可能会生成一套“看起来规范但和你团队水土不服”的代码

我在最后一个场景上吃过亏。一个老项目的代码风格本身就飘忽不定，我又让 Superpowers 一通计划，结果它生成的代码虽然符合它自己规划的“系统模式”，却和现有代码结构完全不一致，最后花了一晚上重构。

写在最后的个人体会

如果你问我，用了 Superpowers 之后最大的变化是什么？我不会说“代码质量瞬间暴涨”这种鬼话。我更愿意说：它让 AI 终于有了工程自觉，会停下来问问题、会写计划、会先写测试、会做自审。这种流程感，是单纯靠换更大参数的模型换不来的。

我现在的工作习惯是：新项目一律让 Superpowers 先跑一遍项目简报和工作包计划；执行阶段一个工作包一个工作包推进；遇到热修复就手动跳过流程。最后再分享一个小技巧——当你卡在一个复杂需求不知道该怎么拆时，直接把这个“不会拆”的困境丢给 AI，让它用 Superpowers 的工作包格式帮你拆。拆完之后你往往发现，原本焦虑的大问题，不过是一堆可以逐个击破的小任务而已。