企业官网建设流程全解析

我最早意识到 AI 编程助手需要"加装"点什么，是在一个周五的下午。那会儿我用 CLI 类的编程助手写一个内部工具，它一口气给我生成了六百多行代码，功能看着都对，可一跑测试就爆雷，追问之后才发现需求理解偏了——它压根没问过我"这个导出要不要包含历史数据"。从那之后我悟出一条经验：工具本身只能解决"写代码"这最后一公里，前面的需求澄清、方案设计、测试策略、排错路径，全得有人替它补上。superpowers 这套开源技能库干的就是这个活，它把工程方法论直接"装"进 Claude Code、Codex 这类 AI 编程助手的大脑里，让它们从"你问一句我答一句"变成"先想清楚再动手"。

这篇文章会聊透 superpowers 是什么、为什么值得用、怎么安装、核心技能有哪些、一个 Java 项目的完整实操流程长什么样，以及我实际跑项目时踩过的坑。如果你已经在用 AI 写代码但总觉得产出不够稳，或者正准备从"聊天式写码"升级到"流程化交付"，这篇应该能帮你少走不少弯路。

1. 先搞清楚 superpowers 到底是什么

1.1 它不是另一个 IDE，也不是代码生成器

很多第一次听说 superpowers 的人会误以为它是一个独立的编程工具或代码生成服务，其实完全不是。superpowers 是一套以 Markdown 文件形式存在的"技能库"（Skill Library），专门给命令行形态的 AI 编程助手用的。它把资深工程师平时干活的那套流程——先分析需求、再写方案、然后测试驱动开发、遇到 bug 系统化排查、最后自审查——全部固化成结构化的技能文件。当你在对话里提出需求时，AI 助手会读取这些技能文件，按照里面定义的步骤和检查清单来执行。

打个不那么精确但很好懂的比方：默认状态下的 AI 编程助手像一个刚入职、干劲十足但没带脑子的实习生，你说"写个接口"，它立刻噼里啪啦给你生成一堆代码，质量全看运气。装完 superpowers 之后，它更像一个被严格 SQE 流程管住的资深工程师，先跟你掰扯清楚需求，再写计划，每写一段代码都先补测试，改完了还要自审。

1.2 它到底解决什么问题

superpowers 解决的核心问题是"AI 编程助手不可控"。默认行为下的 AI 助手有三大通病：

• 不问清楚就动手。需求里有一句"导出的文件要按时间分组"，它能理解成十种不同意思，然后直接选一种开始写。
• 不写计划直接改代码。面对涉及十几个文件的重构，它经常东改一块西改一块，改到一半自己都忘了已经动过哪些地方。
• 不做测试只做"看起来能跑"。它给你生成的代码经常不带测试，或者测试写得很敷衍。

superpowers 的做法是把"问清楚需求"、"写实施计划"、"先写失败测试"、"系统化排查"这些行为变成 AI 助手的默认工作流，而不是靠人每次在提示词里反复叮嘱。

1.3 适合谁用

我的判断是：如果你只是偶尔用 AI 生成一段脚本、写个正则、翻译一段代码，那 superpowers 对你来说是过度配置，没必要装。但如果你属于下面任意一类，它就非常值得试：

• 在正经项目里用 Claude Code、Codex CLI、Gemini CLI 这类工具做日常开发，且项目有测试、有多人协作、有代码评审。
• 依赖 AI 做多文件改造或重构，经常因为"它理解偏了"返工。
• 想训练自己用 TDD、计划驱动开发等工程方法，但不想每次都在提示词里写一大段"角色设定"。

2. 为什么需要它：AI 编程助手的"快"反而成了麻烦

2.1 默认行为下，响应速度是优点也是陷阱

AI 编程助手最大的卖点是快，但"快"在有复杂需求的工程任务里恰恰是主要风险源。你想想看：一个正常的工程师接到需求，第一反应是问背景、确认边界、查现有代码结构，然后在脑子里形成方案，最后才动手。而默认状态下的 AI 助手收到"帮我加一个折扣码功能"，它会直接开始生成DiscountCode.java、DiscountService.java，甚至连数据库迁移脚本都给你写好。表面上效率极高，但其中至少三分之一的设计决策是它替你拍的板，而这些决策你并没同意。

我自己就经历过一次典型翻车。让 AI 助手指给我重构一个支付模块的异常处理，它很勤快，把所有方法签名都改了，把自定义异常全换成了统一异常类型。结果编译倒是过了，但同事在 review 的时候发现它把两个语义完全不同的错误场景合并了，导致线上监控告警根本区分不出"用户余额不足"和"渠道拒付"。这就是典型的"不问需求、不做计划、直接动手"的代价，问题不在代码质量，而在决策过程缺失。

2.2 superpowers 的解决思路：流程本身就是技能

superpowers 的思路和"在提示词里写一段人设"完全不同。它不依赖 AI 的临场发挥，而是把流程固化下来。它的技能文件长这样：每个技能是一个独立目录，目录里有一个SKILL.md，文件头部有 YAML 格式的 frontmatter，包含技能名称和描述；正文部分则是具体的操作步骤、检查清单、参考示例和"何时该用本技能"。

这个结构非常重要，因为它利用的是大模型最擅长的能力——指令遵循。你不需要 AI 记住"你要先做计划再做测试"，你只需要让它在面对相应场景时读到对应技能的指令。当需求进来，AI 助手先扫描技能描述，发现"这个任务应该走 writing-plans 流程"，于是自动加载计划技能，按里面的步骤逐条执行。这就是为什么这套东西能稳定复现工程行为，而不是靠模型心情。

2.3 背后的工程理念：把不可控变成可控

我使用 superpowers 大半年，最大的感受是它把 AI 编程助手的输出从"结果可控"提升到了"过程可控"。结果可控意味着你可以 review 代码，发现 bug 再修；过程可控意味着 AI 在每一步都按工程规范走，根本不给 bug 大量出现的机会。它背后体现的工程理念很朴素：好代码不是一次生成的，而是经过计划、分解、小步验证、逐步逼近出来的。

这套理念也体现在它的技能命名上。superpowers 把技能按编号组织，从 brainstorming、writing-plans、test-driven-development，到 systematic-debugging、refactoring、reviewing-code、documenting，几乎就是一个完整软件交付流程的切片。AI 助手不再是一个随机生成器，而是一台按流程运转的工程机器。当然它不是银弹，后面我会讲到它也有明显的适用边界。

3. 安装与初始化实操

3.1 前置条件

装 superpowers 之前，你本地至少要有一个能跑的 AI 编程助手 CLI。以最常用的 Claude Code 为例，需要满足这几个条件：

• Node.js 18 以上版本（npm 全局安装 CLI 用）。
• Git 已配置好，能正常 clone 仓库。
• 已经登录并将 Claude Code 跑起来过一次，确保基本功能正常。

第一次装的时候我用的是 macOS 环境，Windows 上装了 WSL 也能跑，原理上没差别，因为这本质是往项目目录里塞文件和配规则，不涉及系统级依赖。

3.2 安装步骤

我安装时用的是官方仓库推荐的方式：先把 superpowers 仓库克隆到本地，然后进入仓库目录，直接启动 Claude Code，让它自己完成引导安装（bootstrap）。大致流程如下：

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

进入 Claude Code 交互界面后，跟它说"Install superpowers"，它会读取仓库里的安装说明，然后把技能文件复制到你需要的目标位置。默认情况下它会创建几个东西：

• 项目级的.claude/skills/目录，里面放着选中的技能。
• 一个PROJECT.md或类似的项目记忆文件，用来记录项目背景和约定。
• 对 Claude Code 的配置调整，让它在启动时能识别到这些技能。

如果你不想让它自动操作，手动复制也是可以的：把仓库里的skills/目录整个拷到你的项目.claude/skills/下即可。但我更推荐让它自己装，因为引导过程中它会根据你的项目情况挑技能，还会做一些适配性调整，比手动拷贝更贴合实际。

3.3 初始化：让 AI 帮你选技能

这套系统比较妙的一点是，初始化本身也走技能流程。它会调用 brainstorming 类技能，向你提一组问题，比如：项目是用什么语言写的、有没有测试框架、团队是否要求 TDD、你希望它多主动还是多被动。你回答完这些，它会把技能裁剪到合适范围。比如一个纯脚本项目，它会建议不装 reviewing-code 和 documenting，重点保留 test-driven-development 和 systematic-debugging；一个 Java Spring 项目，它则会建议全套技能都装上。

我第一次初始化的时候选了全套，后来在一个小脚本项目里又装了一遍，只保留三个核心技能，效果反而更好。技能不是越多越好，每个技能都意味着额外的上下文读取和 token 消耗，按需裁剪是长期使用必须学会的一件事。

3.4 装完之后怎么验证

验证装没装成功很简单，在对话里问它"你现在有什么技能？"或者直接看目录结构。正常情况下你的项目.claude/skills/下应该能看到类似这样的结构：

.claude/skills/ ├── 01-brainstorming/ │ └── SKILL.md ├── 02-writing-plans/ │ └── SKILL.md ├── 03-test-driven-development/ │ └── SKILL.md ├── 04-systematic-debugging/ │ └── SKILL.md ├── 05-refactoring/ │ └── SKILL.md └── 06-reviewing-code/ └── SKILL.md

注意：如果你的 AI 助手是 Codex CLI，安装方式略有不同。Codex 主要读取AGENTS.md来获取项目指导，所以社区通行的做法是把技能内容整合进AGENTS.md，或者用~/.codex/下的全局规则文件让它在所有项目里都带上这些技能。这一步没有 Claude Code 那么自动化，通常需要你手动把技能的要点写进规则文件，并用注释说明每个技能的触发条件。从实际效果看，Codex 对这类技能的遵循度比 Claude Code 稍弱一些，但核心的计划和测试流程还是能跑起来的。

4. 核心技能库拆解

4.1 先想后做：brainstorming 与 writing-plans

我几乎每次接一个像样的需求，第一个被触发的都是 brainstorming。它的作用不是让你和 AI 头脑风暴想法，而是让 AI 在动手前把需求边界、约束条件、可能的实现方案、风险和备选方案全部摆出来。它通常会引导你确认这样几类信息：

• 这个需求的真正目标是什么，衡量标准是什么。
• 涉及哪些现有模块，改动范围有多大。
• 有没有明确的约束（性能、兼容性、安全要求）。
• 如果某个方案代价太高，是否有可接受的降级方案。

这些信息确认完，AI 会进入 writing-plans 技能。这个技能要做的事是把上面的讨论落成一份"实施计划"：拆成阶段、明确每个阶段改哪些文件、写哪些测试、用什么命令验证。计划会以文档形式写在项目里（常见是plans/目录或直接在对话里给出），后续每一步实现都对照这份计划执行，避免跑偏。

我个人的实操建议是，任何一个预计耗时超过半小时的任务，都值得走一遍这两个流程。它的直接好处是：你在写第一行业务代码之前，就已经知道 AI 打算怎么改了，想纠正还来得及，成本极低。

4.2 测试先行：test-driven-development

test-driven-development 技能是整个 superpowers 里含金量最高的一个。它把经典的 TDD 循环固化成 AI 助手的执行协议：先写一个会失败的测试，跑一次确认失败，再写最少量的代码让测试通过，然后重构，再跑全部测试确保没破坏别的功能。对 AI 助手来说，这套流程还有一个隐藏价值：跑测试是它获取真实反馈的主要途径。默认状态下 AI 经常"盲目自信"，测试一跑就露馅，而 TDD 流程迫使它用真实结果校准自己的每一步。

实际操作中，这个技能会指导 AI 把测试拆得很小。比如给购物车加折扣码功能，它不会上来就写一个覆盖所有场景的巨型测试，而是先测"折扣码有效时金额正确"这个最小行为，跑挂了，再写实现，再跑绿，然后追加"折扣码过期时忽略"的测试。每轮循环都在两到三分钟内完成，一个小功能可能要做五六轮这样的循环。

4.3 排查不再是玄学：systematic-debugging

这个技能我在生产环境救过不止一次。它的流程严格遵循科学排查法：读取报错信息，形成假设，写最小复现，对照假设做实验，确认根因，修复，最后补一个防回归测试。听起来平淡无奇，但默认 AI 助手的行为根本不是这样——你一贴报错，它就开始猜测并直接改代码，经常越改越乱。systematic-debugging 强制它先复现、再定位、最后才动手。

一个印象很深的例子：线上有个定时任务偶发死锁，报错日志指向数据库连接池。按默认习惯，AI 十有八九会去调连接池参数。但走 debugging 流程后，它先构造了并发场景复现，发现死锁发生在事务里嵌套查询同一张表，根因是锁顺序不一致，跟连接池八竿子打不着。这就是"先复现再修"的价值。

4.4 打磨质量：refactoring、reviewing-code、documenting

除了上面三个核心技能，还有三个偏"质量层"的技能值得了解：

• refactoring：限定在"行为不变"的前提下改内部结构，每改一小步就跑一次测试，防止重构把功能改坏。
• reviewing-code：让 AI 以审查者视角重新读自己生成的代码，找边界条件漏洞、资源泄漏、安全隐患、可读性问题。
• documenting：维护项目记忆文件和关键模块说明，让下一次对话的 AI 助手能快速理解项目上下文。

这三个技能的价值不像 TDD 那么立竿见影，但长期下来差别极大。refactoring 让代码不会在快速迭代中烂掉，reviewing-code 相当于给你加了一道免费的自审关卡，documenting 则解决 AI 每次对话都要重新理解项目的问题。

5. 完整实操流程演示：一个 Java 项目加功能

5.1 场景设定

为了让你看清楚这套流程怎么串起来，我拿一个真实的例子走一遍全过程。项目是一个 Spring Boot 的购物车服务，技术栈是 Java 17、Maven、JUnit 5，我要求 AI 用 superpowers 流程来实现"购物车支持折扣码"这个功能。

启动 Claude Code 后，我的第一句话是："给购物车加折扣码功能，走 superpowers 流程。"这句话很关键，它让 AI 明确知道要按照技能库流程来，而不是直接开写。

5.2 第一轮：需求澄清与方案设计

收到指令后，AI 先进入了 brainstorming。它没有写任何代码，而是抛了一串问题过来：

• 折扣码是前端传参还是由服务端校验？
• 折扣是百分比还是固定金额？是否允许叠加？
• 折扣码是否需要支持过期时间、单次使用限制？
• 购物车金额为 0 或折扣后为负数怎么处理？
• 是否需要记录使用日志，方便后续对账？

我逐条回答之后，它给出了两个方案：方案 A 是只在计算总价时应用折扣，改动最小但无法防止同一个码被重复使用；方案 B 是引入独立的DiscountService并加上使用记录表，改动稍大但满足后续对账需求。它还提醒我，方案 B 涉及数据库变更，需要额外评估。我选了方案 B，它就进入 writing-plans 生成了实施计划，计划里明确列出了要新增的实体类、Repository、Service 接口与实现、两个 Controller 方法的修改点，以及对应的测试文件清单。

5.3 第二轮：TDD 逐段实现

计划确认后，AI 开始按 test-driven-development 技能逐阶段实现。它没有直接写DiscountServiceImpl，而是先给DiscountServiceTest加了第一个用例："使用有效折扣码时，订单总价正确减免"。我先让它跑了一次mvn test，这个用例如预期失败——因为 Service 类还不存在。然后它才创建接口和实现类，用最简代码让测试通过，再跑一次，绿了。接着加第二个用例："折扣码过期时，订单总价不变"，同样的节奏：先红、再绿。

这个阶段最值得说的一个细节是，AI 在写测试时遵循了命名规范和断言风格，也就是先看了项目里已有的测试文件，模仿了你的写法，而不是凭空生成一套风格迥异的测试。这个行为在没装 superpowers 之前我很少见到。

第三轮跑到一个用例时测试挂了，报错是NullPointerException，原因是“优惠价格计算时涉及的商品列表为空”。整个过程非常真实，也让我有机会观察它的 debugging 流程：先看报错栈，找到是DiscountCalculator.calculate里遍历商品列表时空指针，再定位到我在测试里没初始化购物车商品，属于测试数据问题，不是实现 bug。它修好测试数据后重新跑步，全部通过。不会出现"情况不明先改实现代码"的乱操作。

5.4 第四轮：重构、自审与收尾

所有用例通过后，AI 提出做一轮 refactoring，理由是DiscountServiceImpl里有一段判断折扣码有效期的逻辑和CouponService里的逻辑重复，可以抽成一个公共方法。这一步它没有直接改，而是先说明要抽哪个方法、影响哪些调用方，得到我确认后才动手，每抽一次就重跑一次全量测试。然后它调用 reviewing-code 技能，自己检查了一遍生成的代码，发现一个隐患：折扣码查询没有加锁，高并发下同一个码可能被同时使用两次。它主动建议在DiscountService里加一个基于数据库唯一约束的防重机制，而不是只靠应用层判断。这个发现要是等代码合并后再暴露，代价就大多了。

最后它补了 documenting，更新了PROJECT.md里关于购物车模块的说明和这次新增的折扣码接口文档。整个功能从开始到结束大约四十分钟，大部分时间花在需求澄清和测试循环上，实际产出代码量不大，但每一行都有测试兜底。

6. 常见问题与避坑实录

6.1 安装之后技能不生效

这是被问得最多的一个问题。症状是装完之后，你正常提需求，AI 还是老一套直接开写，完全看不出技能的存在。原因通常有三个：

• 技能目录放错了位置。Claude Code 的项目级技能一定要放在项目根目录的.claude/skills/下，放错目录不会被扫描到。
• 你没在对话里明确走流程。superpowers 的技能大多是被动触发或由命令触发的，你如果直接丢一个"帮我写个 xx 接口"，它可能不调用技能就直接写了。正确的打开方式是带上触发词，比如"用 TDD 流程""先做个 plan"。
• 多个规则文件冲突。如果你项目里既有.claude/skills又有其他插件或规则，偶尔会出现加载冲突，表现为技能文件存在但行为不变。解决办法是把项目根目录的 CLAUDE 相关配置里多余的指令清理掉，保留 superpowers 的标准配置。

6.2 Token 消耗明显变多

这是所有长期用户都会遇到的痛点。因为技能驱动的小步循环、反复跑测试、计划文档读取，都意味着更多上下文和 token 消耗。拿上面的购物车例子来说，一个本来可能 30 分钟搞定的功能，走了 TDD 流程后 token 消耗大概是原来的三到四倍。

我的应对策略是：

• 按项目裁剪技能，不用的一律不装。
• 大改动拆成多次对话，每次只处理计划里的一个阶段，而不是让一次对话背着上千行上下文从头跑到尾。
• 对很简单的改动（一行配置、一个字段名），直接让它别用流程，手动快速改。

别为了"仪式感"让所有改动都走全流程，那是对资源的浪费。技能的定位应该是"复杂任务自动启用的安全网"，不是所有任务的必经之路。

6.3 Codex 上遵循度不稳定

如果你主要在 Codex CLI 上用 superpowers，我提前打个预防针：体验和 Claude Code 有一定差距。原因在于 Codex 对技能文件的感知主要依赖AGENTS.md这类指令文件，而 superpowers 的设计本来就是围绕 Claude Code 类工具的开源 Agent Skills 格式做的，二者在读取机制上并不完全兼容。

社区常见的做法是把每个技能的核心指令精简成几段话，写进AGENTS.md，并加上"遇到此类任务必须按以下流程"的强约束语句。实际用下来，计划和测试相关技能遵循得还行，但 debugging 和 reviewing 这类需要多轮判断的技能表现不够稳定。如果你想获得超完整的体验，建议主力工具还是选和 superpowers 原生兼容的那类。

6.4 项目记忆文件膨胀

PROJECT.md 这个文件随着项目推进会越来越大，因为它不断被追加新的模块说明、修改记录和约定。文件太大之后，AI 每次启动都要读一大段上下文，既费 token 又可能让它抓不住重点。我现在的习惯是每隔一两个月手动清理一次，把已经稳定的模块说明压缩成两三行摘要，把过期的信息删掉。这个文件应该像一本精简的项目手册，而不是流水账日志。

7. 我的几点真实体会

用 superpowers 小半年，它对我的工作方式改变最大的不是"代码写得更多了"，而是"返工变少了"。以前让 AI 写一个功能，我要花大量时间 review 它自作主张的设计决策；现在这些决策在计划阶段就摆到台面上，我看到不对的地方直接改计划，而不是等代码生成完再推翻。

如果你准备上手，我的建议是别一上来就上最重的流程。先挑一个小项目，装三个核心技能（brainstorming、writing-plans、test-driven-development），跑两三个需求找找感觉，再逐步加 debugging 和 refactoring。等你对它的行为模式足够熟悉之后，再在主力项目里铺开。另外，记住一个原则：技能库给的是流程和纪律，但它不会替你理解业务。需求本身讲不清楚，再强的流程也救不回来——好的工具配好的需求描述，才是这套东西发挥最大威力的前提。