企业官网建设流程全解析

如果你每天都在跟代码打交道，尤其是最近开始依赖 AI 编程助手来写需求、改 Bug、做重构，那你大概率遇到过这样的场景：AI 写得头头是道，结果一跑就报错；上下文一长，它就把你最开始说的需求忘得一干二净；同一个项目的规范每个会话都要重新讲一遍，心累到想摔键盘。

最近社区里很火的 superpowers 项目，就是冲着这些问题来的。它不是某个新的编程语言，也不是一个 IDE 插件，而是一套专门给 AI 编程助手（尤其适合 Codex CLI 这类终端型 Agent）用的“技能库 + 工作流引擎”。装上它之后，AI 不再是那个“你问一句它答一句”的被动工具，而是一个会先做计划、再动手改代码、最后还会自查验证的“半自动结对程序员”。这套方案在国外开发者圈子里讨论度很高，尤其是 codex superpowers、superpowers java 这几个关键词的热度一直没下去，国内也有不少人在研究 superpowers 安装和教程。

这篇文章我就从自己实际折腾的体验出发，聊聊 superpowers 的底层思路、核心机制、安装步骤，以及我拿一个 Java Spring Boot 老项目做实战测试的完整记录。不管你是刚开始接触 AI 编程，还是已经在用 Codex 但觉得不够顺手，这篇文章应该都能给你一些能直接抄走的经验。

1. 先想清楚：superpowers 到底解决了什么问题

1.1 单用 AI 编程助手时的三个尴尬现场

先说我自己。过去一年我重度使用过好几款 AI 编程工具，最常用的就是终端里的 Codex CLI。说实话，单论“生成代码”这件事，它的水平已经很能打了——写个工具类、生成单元测试、解释一段陌生代码，基本都能给出靠谱的答案。

但你一旦把它投入到真实项目里，问题就冒出来了。

第一是上下文丢失。AI 的上下文窗口是有限的，哪怕是最新的长上下文模型，也不可能装下一个中型项目的所有细节。你让它改 A 模块，可能改着改着它就把 B 模块之前定好的接口约定抛到脑后了。你催它“我之前不是说过了吗”，它只会一脸无辜地道歉，然后继续猜。

第二是行为不稳定。同一个项目，你今天让它“按照项目现有的异常处理规范来写”，它能写得像模像样；明天新开一个会话再说同样的话，它可能给你抛出一套完全不同的错误码设计。AI 不是没有能力，而是缺少一套稳定的“行为准则”来约束它每次的输出风格。

第三是缺少流程意识。让 AI 直接改代码，它往往拎起键盘就干，改完了也是直接写进文件里，完全不管什么先看影响面、再写测试、最后跑验证这一套工程流程。结果就是它改得越快，你 review 得越心惊胆战。

当时我的想法很简单：如果能给 AI 建一套“项目说明书和操作规范”，让它每次干活之前先看说明书，再按规范一步步来，是不是就能解决大部分问题？superpowers 就是这个思路的成熟落地。

1.2 superpowers 的核心设计：给 AI 建立“肌肉记忆”

我在看 superpowers 项目文档和源码的时候，最直观的感受是：它把“教 AI 做一个合格的软件工程师”这件事拆成了三层。

第一层是技能库（Skills）。你可以把它理解成一套 markdown 格式的“专业手册”，每本手册讲清楚一个能力，比如“怎么写代码审查”“怎么拆解需求”“怎么写测试”。AI 在干活之前会先去读这些手册，按手册里的步骤来操作。

第二层是工作流（Workflows）。superpowers 约定了一套“先计划、再执行、后验证”的循环流程。AI 每次接到需求，都会先输出影响面分析和实施计划，等你确认后再开始改代码，改完之后还会主动检查有没有破坏现有功能。

第三层是记忆（Memory）。项目关键信息、当前进度、技术决策都会被记录到特定的项目文件里。AI 每次会话开始时先读取这些文件，相当于带着前一回合的记忆继续工作。

这三层叠加起来，产生的效果不是“AI 变聪明了”，而是“AI 变得靠谱了”。它不再自由发挥，而是有一本很厚的操作手册时刻约束着它。

我第一次看到这套东西的时候，心里其实是不以为然的：这不就是写几个 markdown 提示词吗？但真正跑起来之后我才发现，难的不是写提示词，而是把提示词组织成一套可复用的、能被 AI 稳定执行的系统。superpowers 的价值恰恰在于这套“系统设计”，而不是某一个单独的技巧。

2. 核心能力拆解：技能、循环、上下文管理

2.1 技能库：给 AI 装上一摞“专业手册”

如果你用过 Anthropic 的 Agent Skills，再来看 superpowers 的 skills 目录，会觉得很亲切——超级相似的设计理念。

superpowers 把每一个技能定义成一个独立目录，里面放一个 markdown 文件。文件头部是一段 YAML 格式的元信息，声明这个技能叫什么、适合在什么场景触发、需要什么前置条件。正文部分则是详细的步骤指南，告诉 AI 应该按什么顺序做什么事。

我随便截一个我自己写的技能文件片段给你看：

--- name: plan-change description: 在开始修改代码之前，先分析影响面并输出实施计划 trigger: 用户提出新的功能需求或修改需求时自动触发 --- # 变更计划流程 1. 先阅读项目根目录下的 PROJECT.md 和 AGENTS.md，了解项目背景与规范。 2. 识别本次变更涉及的文件、模块、接口，输出影响面清单。 3. 按“新增/修改/删除”三列列出具体改动点。 4. 评估风险，标记出可能破坏现有功能的改动。 5. 在 PRD 或对话中输出计划，等待用户确认后进入执行阶段。

写技能文件本质上是在给 AI 写“操作说明书”，而且这份说明书它真的会去读。实践下来，我最大的心得是：技能文件要写得足够具体，但不能变成僵硬的教条。太笼统的话 AI 照样自由发挥，太琐碎的话 AI 会把它当成流程噪音直接忽略。

先跑起来的做法是先只配三五个核心技能，跑顺了再逐步增加。技能不是越多越好，就好比你给新人安排入职培训，不能第一天就把厚厚一整本 SOP 砸他脸上——他消化不了的。

2.2 迭代循环：强制“先想后做”

superpowers 最让我受用的，是它对 AI 工作节奏的约束。有了这套循环之后，AI 的行为模式发生了非常明显的变化。

以前我让 Codex 加一个数据库字段，它直接就开始改实体类、改 Mapper、改 Service，全程零沟通。现在它会先停一下，列出“这几张表会被影响”“这个接口的返回值会变化”“建议同步更新 API 文档”，然后问我是否按这个方案来。

说白了，superpowers 把开发任务拆成了三个阶段：

• Plan：分析需求，定义影响范围，输出执行清单。
• Build：按清单逐项实施，每完成一个子任务做一个标记。
• Verify：检查代码可编译、测试可运行、关键逻辑符合需求，整理变更摘要。

这个循环最关键的环节其实是 Verify。大多数情况下，AI 自己写出来的 Bug 它是发现不了的，但当它被强制要求“把验证过程写下来”时，它会更倾向写更保守的代码，也更愿意补测试。

我自己的实测体验是：跑了这个循环之后，AI 生成的代码第一次编译通过率可能有明显下降（因为它更谨慎了），但最终交付的代码质量、可维护性、和我 review 时需要改的东西，都显著变少了。这就跟你自己写代码多花点时间做设计是一个道理。

2.3 上下文与项目记忆：解决 AI 的“职场失忆症”

另一个让我眼前一亮的设计是项目记忆机制。superpowers 建议你在项目根目录维护几个固定文件，比如 PROJECT.md（项目背景与说明）、AGENTS.md（AI 代理规范）、PROGRESS.md（当前进度与待办）。

AI 每次会话开始时会自动读取这些文件，相当于一个新人入职第一天先看项目简介和团队规范。你可以把关键的架构决策、目录约定、技术选型理由都写在里面，AI 在后续生成代码的时候就会刻意遵守。

有一次我测试它是否真的会读这些文件，故意在 PROJECT.md 里写了一句“本项目禁止使用 Lombok”，然后让它生成一个新实体类。它生成的代码果然用了传统的 getter/setter。虽然不能 100% 保证每次都严格执行，但多数时候它能做到。

这个设计的本质是把 AI 从“无状态工具”变成了“有记忆的协作者”。你不需要每次都在 prompt 里重复你的技术偏好和项目约束，那些被沉淀在文件里的内容，AI 会自己去看。

3. 环境准备与安装：从零到跑通

3.1 前置依赖：需要准备哪些基础环境

开始装 superpowers 之前，先把前置环境准备好。我实测的环境是 macOS + zsh，Windows 用户建议用 WSL 或者直接用 Git Bash，整体路径逻辑差不多。

第一步是装 Node.js，注意版本要 18 以上。命令行用node -v检查，如果版本太老会直接影响后面 Codex CLI 的安装。

第二步是确保 Git 没问题，因为 superpowers 仓库是通过 Git 拉取的。git --version能输出版本号就行。

第三步是准备一个 AI 编程 CLI 工具。superpowers 目前最锦配的是 OpenAI 的 Codex CLI，安装命令很简单：

npm install -g @openai/codex

装完之后先运行一次codex并登录你的 API 账号。我这里不展开说账号层面的东西，重点是你本地至少要能正常跟 Codex CLI 对话。如果你用的是其他支持技能机制的 AI 编码 Agent，思路是一样的——后面把技能和配置文件挂到对应目录就行。

3.2 拉取 superpowers 仓库并配置技能

环境准备好之后，拉取 superpowers 本体。目前社区里比较活跃的版本来自 obra/superpowers 这个仓库，直接 clone 到本地目录：

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

拉下来之后我会先进去看一眼目录结构，重点看两个东西：skills目录和AGENTS.md文件。前者是所有技能定义，后者是被 AI 自动读取的核心行为规范。

接下来要做的是把技能目录挂到你的 Codex 配置目录下。不同机器、不同用户路径会有差异，我自己的做法是直接做软链接：

mkdir -p ~/.codex/skills ln -s ~/superpowers/skills/* ~/.codex/skills/

如果你不想全局生效，只想在某个项目里用，那就在项目根目录下建.codex/skills目录，再把技能文件复制或软链过去。我建议新手先全局装，跑通之后再按项目隔离。

最后，把 superpowers 仓库里的AGENTS.md复制到你的项目根目录。这份文件会约束 AI 的工作方式，最核心的是写明要遵循的技能调用流程。你也可以基于自己的团队规范改写它，这是整个系统里最值得花时间定制的一份文件。

3.3 第一次跑通验证：怎么确定安装成功

装完之后先别急着上复杂需求，跑一个最小测试确认系统是通的。

随便新建一个临时目录，复制一份 AGENTS.md 进去，然后启动 Codex CLI，在对话里输入：

请按照 superpowers 的工作流程，帮我对这个目录做一个项目结构分析，并输出一份简单的 PROGRESS.md。

如果一切正常，你会看到 AI 先生成一个计划（也许它会调用 plan-change 技能），然后检查当前目录的文件结构，最后生成一个简洁的进度文件。这个过程中如果它输出了一些“遵循 AGENTS.md 中的流程”之类的话，基本可以判断技能文件已经被读取了。

这里有个容易踩的坑：很多人在 Codex 的某个会话里测试，发现 AI 完全不按 superpowers 来，原因是 Codex CLI 启动时并没有读取新的 AGENTS.md。解决方案是退出当前会话重新启动，因为 AGENTS.md 是在会话初始化时加载的，中途改配置不会热生效。

4. 实战记录：给一个 Java 老项目加上 CSV 导出功能

4.1 项目背景与目标

为了验证 superpowers 在真实项目里的表现，我拿一个自己维护的 Spring Boot 订单系统做了个实验。这个项目有完整的 Controller / Service / Mapper 分层，用的是 MySQL 数据库，订单表已经有一万多条测试数据。

需求是按查询条件导出订单 CSV 文件，要求包含订单号、用户手机号、商品名称、下单时间、订单金额、订单状态这几个字段，并且金额要保留两位小数。这个功能说大不大，说小不小，但涉及的改动点不算少：数据库查询、DTO、导出工具、Controller 接口、接口文档，还有一个隐藏问题——手机号要在导出时做脱敏。

放在以前我直接让 AI 写，它会唰唰给你生成一遍代码，但大概率漏掉脱敏需求，也不会去关心分页和大数据量导出的问题。

4.2 提示词怎么写给 AI 最有效

我最终的提示词大概是这样的格式：

项目：order-service，Spring Boot 3 + MyBatis-Plus + MySQL。 需求：新增一个订单 CSV 导出接口 /api/orders/export，支持按时间范围、订单状态查询后导出。 约束： 1. 手机号必须做脱敏，导出文件里只能看到前 3 后 4 位，中间以 * 代替。 2. 金额字段保留两位小数，避免科学计数法。 3. 数据量上限 10 万条，超出时直接返回错误信息。 4. 导出文件名格式为 orders_yyyyMMddHHmmss.csv。 验收标准： - 本地启动项目后，调用接口能生成合法 CSV 文件。 - 涉及到的 Service / Controller / 工具类都应该有对应的单元测试。 请先分析影响面，再开始实施。

相比我以往“帮我写个导出功能”这种含糊指令，这版提示词多了两个关键部分：约束和验收标准。没有约束，AI 会按自己默认的偏好来写，可能挺好但不适配你的业务；没有验收标准，AI 就会“改完就跑”，根本不会主动验证。

我特意没有在提示词里提到技能文件，想看看它能不能自己判断。实测结果：Codex 读完项目结构和 AGENTS.md 之后，主动调用了 plan-change 技能，输出了影响面清单，然后才开始动手。

4.3 观察 superpowers 风格的执行过程

第一个阶段是 Plan。AI 输出了这样一份计划：

• 新建 OrderExportDTO，用于承载导出字段；
• 新建 CsvExportUtil 工具类，负责字段映射与格式化；
• 修改 OrderService 新增导出查询方法，注意处理 10 万条上限；
• 修改 OrderController 新增导出接口，设置响应头；
• 补 OrderServiceTest 和 CsvExportUtilTest 单元测试。

这份计划和我想的改动点基本一致，但它额外标注了两个风险点：手机号脱敏需要在导出层做而不是查询层做，避免影响原有查询接口；大数量导出要用流式写法而不是把所有数据查出来放进内存，防止 OOM。后者我确实没想到，它连代码都没开始写就先把这个坑标出来了。

第二阶段是 Build。它开始逐个文件地创建和修改。比较让我意外的是，AI 每写完一个文件都会在 PROGRESS.md 里追加记录：改了哪个文件、改了什么、是否引入新的依赖。整个过程像是有个人在一边写代码一边跟你说“我现在在改哪个文件，改了什么，下一步准备做什么”。

第三阶段是 Verify。它没有直接跑整个项目（因为本地数据库环境不一定完整），但主动检查了几件事：XML Mapper 里有没有对应的结果映射、新增工具类是否能被 Spring 容器管理、Controller 的路径和方法是否和已有路由冲突。最后它还跑了一遍它能跑的两个单元测试。

最终导出的 CSV 文件我手动验证了一下：手机号确实被脱敏成类似138****1234的格式，金额也保留了两位小数，文件编码是 UTF-8 开头带 BOM，Excel 直接打开不乱码。

4.4 实战中踩过的坑

这次实验整体顺利，但不代表 superpowers 就没问题。我在前前后后的一周测试里踩过几个坑，逐一讲一下。

第一个坑：技能目录路径写错导致 AI 读不到技能。有一次我把 skills 软链接到了错误目录，结果是 AI 完全不按流程来，直接自由发挥。排查下来发现是 Codex 读取技能的路径不是我以为的那个目录。解决方案很简单，在 AGENTS.md 里加了一行说明，把技能文件的绝对路径写清楚，让 AI 找不到就去那里找。

第二个坑：PROGRESS.md 被 AI 自己覆盖。有一次测试新技能时，AI 误把 PROGRESS.md 里我手写的“技术债务记录”部分用它的生成内容覆盖掉了。不能说它恶意，但它对一个“进度记录文件”的理解和我想要的不完全一样。解决办法是后续在 AGENTS.md 里增加了说明：PROGRESS.md 的“手动维护区域”不允许 AI 未经询问直接修改。

第三个坑：一次性配了太多技能，反而让 AI 变得“行动迟缓”。我刚开始图新鲜，把仓库里几乎所有技能都挂上了，结果 AI 每次做一个极小的改动都要先跑一遍写计划、拆任务、做验证的完整流程，并且它会在多个技能之间来回横跳。后来我把技能精简到五个核心项，终于恢复了正常节奏。这个跟现实里的团队管理一个道理：流程是为了兜底，不是为了束缚手脚。

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

5.1 问题速查表

我整理了自己和群里几位朋友遇到的典型问题，做成一张速查表，方便你直接对照排查：

5.2 三个容易被忽略的配置细节

除了上面这些故障，还有三个细节我建议你一开始就留意。

第一，技能文件的命名和描述里要包含明确的触发场景。比如“当用户要求修改代码前，调用此技能进行影响面分析”。如果描述写得模棱两可，AI 可能根本不知道什么时候该用它。

第二，superpowers 的流程设计是配合 Git 工作流使用的。我个人的建议是不要把 superpowers 当成“自动执行机”，而是把它当成你的“结对编程搭档”。每次你确认它的计划之后，让它在一个功能分支上干活，这样你随时可以用 git diff 审视改动，出问题了也能干干净净地回滚。

第三，多关注 AGENTS.md 的迭代而非一次性定稿。我自己的 AGENTS.md 已经改了三轮，从最初的通用版本逐渐变成真正适配我开发习惯的专属配置，每跑一个项目就把新的教训补进去。这就像调自己的编辑器配置，没有标准答案，只有不断打磨。

写在最后

我自己的体会是，superpowers 这套东西最打动人的地方，不在于某个惊艳的单点技巧，而在于它把 AI 从一个“你问它答的问答机器”变成了“一个有基本职业素养的开发协作者”。以前我花很多时间在 prompt 里反复交代背景、强调规范、提醒它不要犯低级错误；现在这些约束被固化在技能文件和项目记忆里，AI 每次开工前自己就会去读、去遵守。

我知道有些人会觉得这套配置工作量太大，懒得折腾。但从我实测下来的收益看，前期花半小时配置，后面每次开发都能省下大量“重复调教 AI”的时间，这个投入是很划算的。你也不需要一上来就全套照搬，可以先装好基本技能，跑几次小任务找感觉，再把项目特有的规范慢慢沉淀进 AGENTS.md 和 PROGRESS.md。

最后再分享一个小技巧：每次跑完一个重要任务，我都习惯性地让 AI 用几句话总结一下“这次踩了什么坑、下次要避免什么”。把这些沉淀到项目记忆里，你会发现 AI 在你的项目上会越来越“懂事”。这大概就是 superpowers 的题中之义——不是给 AI 装上什么黑科技超能力，而是给它一套能持续积累、不断演进的工作方法。