企业官网建设流程全解析

最近这几个月，我几乎每天都在和 Codex CLI 打交道，但真正让我从"会用 AI 写代码"变成"敢把 AI 写代码当日常工作流"的，反倒是这个叫 superpowers 的项目。如果你也用过 Claude Code、Codex CLI 这类工具，你大概率也遇到过同样的问题：它很聪明，但像一个记性差、还总爱自作主张的实习生——你交代需求，它一口气给你吐几百行代码，看着挺像回事，一跑就发现要么漏了边界条件，要么根本没按项目里的既有约定来。

superpowers 解决的就是这个事。它不是一个新模型，也不是一个 IDE 插件，而是一套给 AI 编程代理加的"技能增强层"：通过技能（skills）、工作流（workflow）、子代理（subagent）和记忆（memory）四个核心机制，把资深工程师的工作习惯结构化地灌进 AI 的上下文里。支持接入 Codex CLI、Claude Code 等主流命令行编程工具。无论你是 Java、Python、前端还是全栈，只要你愿意让 AI 在动手前先思考、先规划、再按纪律执行，这篇文章值得你花十分钟读完。

1. superpowers到底解决了什么问题

1.1 从"代码生成器"到"会工程的协作者"

先聊聊我自己的痛点。在接触 superpowers 之前，我对 Codex CLI 的使用方式非常简单粗暴：给它一个需求，它直接生成实现。小型任务还行，比如"写个工具函数解析这段 JSON"，但一旦遇到跨文件、多模块的中型任务，问题马上暴露。

印象最深的一次：我让它重构一个支付回调的处理方法，它直接把整个类重写了，参数列表、异常处理、日志风格全都改了。功能确实跑通了，但 code review 的时候同事直接炸毛："这代码风格跟整个项目根本不是一个路子。"更麻烦的是，它没有留下任何重构说明，我根本不知道它动了哪些调用方。

这类问题的本质是什么？是 AI 编程工具天然缺乏"工程约束"。它知道大量代码，但它不知道你这个项目的约定、不知道哪些模块是敏感地带、不知道"先写测试再写实现"这种基本流程。你指望靠提示词把这一切说清楚？每次会话都要重新说一遍，而且说多了上下文就爆了。

superpowers 的核心思路相当直白：把这些工程纪律从"你每次临时输入的提示词"变成"AI 每次自动加载的文件和流程"。它不追求让 AI 更聪明，而是让 AI 按一个有经验的人的方式工作。

1.2 四个核心机制：技能、工作流、子代理、记忆

拆开看，superpowers 的架构由四个概念组成：

• 技能（Skill）：本质是一份结构化的 Markdown 文档，通常叫 SKILL.md。里面写清楚这个技能解决什么问题、在什么场景触发、执行时遵循哪些步骤、有哪些红线不能碰。AI 在会话中会根据描述自动判断何时调用它。

• 工作流（Workflow）：多个技能的有序串联。比如"先规划、再写测试、再实现、最后审查"就是一个工作流。它们被拆成模板，AI 执行时不会跳过中间环节。

• 子代理（Subagent）：独立的、上下文隔离的小对话。比如你让主 AI 开发功能，同时派一个"代码审查子代理"去看改动，它的上下文只关注审查，不会被主任务冲淡。这在大型任务里尤其好用。

• 记忆（Memory）：跨会话的项目状态存储。AI 会把重要决策、已知问题、未完成任务写到 memory 文件里，下次开新会话自动读取。相当于给 AI 配了一个长期记忆库，不用每次从零开始。

这四个机制组合起来，就等于你给每个 AI 会话配备了一份"岗位手册 + 项目历史档案 + 工作流程模板"。

1.3 和"多写几句提示词"的差别在哪

有人可能觉得，这不就是把提示词换成文件吗？差别很大。

提示词是一次性的、碎片化的。你这次写"请先写测试再写实现"，AI 照做了，下次你不写它就忘了。而且提示词很难承载复杂流程，你很难用一段话让 AI 同时记住"先分析影响面、再定接口、写测试、重构、跑 mvn test、审查 diff"这一整套动作。

技能文件则是持久的、经过验证的。它不只是描述性文字，还包含边界条件和执行纪律。比如一个"代码审查"技能里会明确写：审查时不得修改代码、必须按严重程度输出问题清单、必须指出测试覆盖盲区。这是普通提示词很难做到的约束力。

我给个更直白的类比：提示词像是你临时口述的要求，技能像是公司里沉淀下来的 SOP 文档。口述的东西全靠对方记性和自觉，SOP 文档才是真正能稳定复现工作质量的东西。

2. 环境准备与安装：三大主流代理配置一次说清

2.1 前置依赖到底需要什么

superpowers 本身是一个开源项目，理论上你只需要三个东西：

• Node.js（建议 18 以上，安装脚本和部分 CLI 工具依赖它）
• Git（用于从仓库拉取代码和后续更新）
• 你常用的 AI 编程 CLI 工具之一，比如 Codex CLI、Claude Code

我测试时用的是 Node 20、Codex CLI 的最新稳定版和 Claude Code 1.x，跑下来没遇到兼容性问题。如果你本机还没装 Node，先去官网下载 LTS 版本装上，这一步不用赘述。

多说一句：不要用 sudo 把 superpowers 装到全局目录。它本质是往你的用户目录写配置和技能文件，装到全局反而容易出现权限混乱，更新时还要反复输密码。老老实实装在用户目录即可。

2.2 拉取仓库并执行安装

我当时用的安装方式大致是这样：

git clone https://github.com/obra/superpowers.git cd superpowers npm install node bin/install.js

安装脚本跑完之后，它会在你的用户目录下创建几个关键路径：

• ~/.superpowers/：主目录，技能库和配置都在这
• ~/.superpowers/skills/：所有技能的存放位置，每个技能一个子目录
• ~/.superpowers/config.json：全局配置，决定哪些代理启用了哪些技能

不同版本路径可能略有差异，但大差不差。如果你在安装时想自定义技能存放目录，可以在执行脚本前设置环境变量指向自己的目录，我建议保持默认，少折腾。

2.3 接入 Codex CLI：AGENTS.md 是那把钥匙

Codex CLI 本身有一套项目指令机制：它会读取当前工作目录下的AGENTS.md文件，把它作为项目级的系统提示。superpowers 接入 Codex 的关键，就是把技能索引写进这个文件。

我当时的做法是在项目根目录的AGENTS.md里加上这样一段：

## Available Skills You have access to the following skills. Read the corresponding skill file before using them: - Planning: ~/.superpowers/skills/planning/SKILL.md - TDD: ~/.superpowers/skills/tdd/SKILL.md - Code Review: ~/.superpowers/skills/code-review/SKILL.md - Debugging: ~/.superpowers/skills/debugging/SKILL.md

注意，这里写的是绝对路径。如果你希望多个项目共用同一套技能，可以把这个文件放在你的全局配置里；如果你只想让个别项目使用，放在项目根目录的 AGENTS.md 里最合适。

2.4 接入 Claude Code：插件配置方式

如果你用的是 Claude Code，接入方式类似但入口不同。Claude Code 支持在~/.claude/目录下配置插件和技能引用。你可以在设置里声明技能目录，或者在会话中通过/plugin命令导入。

我目前同时接入了 Codex 和 Claude，平时主力是 Codex，遇到需要更长上下文、更复杂对话的任务会切到 Claude Code。两边读的技能文件是同一套，维护成本没有增加。

安装完后怎么验证？最简单的办法：开一个新会话，直接问 AI："你现在加载了哪些技能？分别的作用是什么？"如果它能准确列出 planning、tdd、code-review 这些技能并且说清楚触发条件，说明接好了。如果它答不上来或者只说"我没看到任何技能文件"，那十有八九是路径或文件名对不上，回到上一步检查。

3. 别急着写代码：superpowers 的核心使用姿势

3.1 用一句话触发完整工作流

工具装好只是开始，真正改变我使用习惯的是它"先规划后动手"的工作方式。以前我遇到需求，第一反应是直接甩给 AI"实现一个 XX 功能"。现在我会说：

"用 planning 工作流处理这个需求：先分析影响面，输出 PLAN.md，等我确认后再进入实现。"

这句话一出来，AI 的行为模式立刻不一样。它不会急着生成代码，而是先读取相关模块、梳理依赖关系、列出任务清单、标注风险点。我花两分钟看计划，确认方向没问题，再让它进入下一步。

这种模式本质上是在 AI 和你之间加了一道"设计评审"的关口。好处非常明显：大部分方向性错误在动手前就被拦截了，而不是等代码写完了再推翻重来。

3.2 常用技能清单：什么时候该用哪个

用了一段时间之后，我结合自己的项目类型沉淀下来一张技能选择表：

选择技能的时候我有个原则：同一时间只挂载必要的技能，不要全量加载。关于这点后面踩雷录里会专门展开。

3.3 记忆机制：让 AI 记住项目的前因后果

记忆机制是我认为 superpowers 最被低估的功能。长期用 Codex 的人都有这种体验：新开一个会话，AI 完全不记得昨天讨论过的方案和踩过的坑，所有上下文都要重新交代一遍。

superpowers 的记忆机制改变了这一点。它会在每次会话结束时，把关键信息写入记忆文件：

• 本次做了什么决策，为什么做这个决策
• 哪些任务还没完成，下一步要做什么
• 遇到了什么坑，后续需要规避什么

下次新会话开始时，AI 自动读取这些记忆，直接进入状态。我经常早上开工，第一句就是"加载昨天的记忆，我们继续那个支付模块的重构"。它真的能接上，这种连续性是原生工具给不了的。

3.4 手把手创建你自己的技能

工具自带的技能是通用的，真正好用的是你自己沉淀的。我自己写了个"数据库迁移检查"的技能，每次让 AI 改动数据库相关代码时自动触发，检查有没有给大表加索引、有没有破坏已有外键关系、有没有考虑数据回滚。

创建步骤很简单：

1. 在~/.superpowers/skills/下新建目录，比如db-migration-check/
2. 目录里新建SKILL.md文件
3. 文件用 frontmatter 格式声明技能信息，正文写执行步骤和检查清单

一个最小示例：

--- name: db-migration-check description: 审查所有涉及数据库结构变更的改动，在提交前调用。重点关注索引、外键、回滚。 when_to_use: 当 diff 中包含 migration 文件、DDL 语句或 ORM 实体变更时 --- ## 执行步骤 1. 提取本次改动涉及的表和字段 2. 检查变更是否需要新增索引，评估现有数据量 3. 检查外键关联是否被破坏 4. 确认回滚脚本存在且可执行 5. 输出审查结论，包括风险和修改建议 ## 红线 - 禁止直接在生产环境执行任何 DDL - 禁止在未评估数据量的情况下建议加锁

写完这个文件后，AI 会在遇到数据库变更时自动读取并执行检查。关键在description字段，写得越具体，AI 越容易判断什么时候该用这个技能。

4. 当技能遇上 Java：一次真实的重构复盘

4.1 为什么 Java 项目特别吃这套

Java 项目大概是所有语言里"潜规则"最多的那一类：Maven 还是 Gradle、Lombok 用不用、Controller 层应该多薄、异常是抛还是吞、Checkstyle 规则怎么配。这些约定很少写进文档，全靠团队口头传承。原生 AI 写 Java 代码，功能对，但风格经常和团队不一致，review 成本极高。

superpowers 的切入点正好卡在这。你可以把团队所有的编码规范写成一个"Java 编码约束"技能，AI 每次生成代码前自动加载。它的代码风格会稳定很多，因为约束不再靠运气，而是每次都在上下文中。

4.2 一次 Spring Boot 支付模块的重构全过程

我拿最近一次实践做例子。项目是一个 Spring Boot 的支付服务，核心的OrderService类膨胀到了 1200 多行，里面塞了支付宝、微信、银行卡三种支付渠道的 switch-case 逻辑。三个渠道逻辑互相纠缠，只要改一处，另外两处就可能坏。没人敢动。

我当时的操作分四步：

第一步，让 AI 用 code-review 技能分析现状。它输出的问题清单有 6 类，包括：switch-case 分支过多、渠道参数校验缺失、重复的订单状态流转代码、异常处理不统一、测试覆盖严重不足、类职责混乱。这个清单基本和团队一致。

第二步，执行 planning 技能，拆出重构阶段：设计渠道策略接口、编写现有行为的特征测试、分渠道实现策略类、最后回归。计划产出后我确认了优先级。

第三步，按 tdd 技能进入实现。先为三个渠道分别写测试用例，边界情况包括退款、部分退款、金额不一致。这些测试把"现有功能不能改坏"这个底线锁死。

第四步，改造完成后跑 code-review 复查 diff。

结果：OrderService从 1200 行降到 400 行左右，三个支付渠道变成独立的策略类，旧测试全部通过，新增了 20 多个特征测试。整个过程大约用了一个工作日，换作以前纯人工来动这块代码，没两三天我不敢让人上。

4.3 Java 团队可以复用的技能组合

基于这次经验，我给 Java 团队一个可以直接抄的技能组合建议，触发顺序很重要：

1. planning：先拆任务，定义接口和改动边界
2. Java 约束检查：加载团队规范，确保生成代码风格统一
3. tdd：先写测试，锁定行为
4. 实现与重构：只允许改动与本次任务相关的代码
5. code-review：以审查子代理身份自查 diff

这个顺序的核心逻辑是：先定边界再动手，比让 AI 一口气写完重要得多。顺序反了，AI 很容易陷入"边写边改边推翻"的无序状态。

4.4 省时间的真相：性价比体现在返工减少

说到收益量化，我做一个不算严谨但很直观的对比：

我最真实的感受：AI + superpowers 在简单任务上并不比原生 AI 快多少，但中型以上任务，省下的不是"写代码时间"，而是"返工和 review 时间"。方向对了，代码风格对了，测试兜住了，后面所有环节都顺了。

5. 踩雷录：新手最容易翻车的五个地方

5.1 装了跟没装一样：技能加载不上

这是反馈最多的问题，我自己也踩过。症状是：明明在技能目录里看到了文件，AI 会话里却完全无感，该直接写代码还是直接写。

排查链路按这个顺序来：

1. 检查 AGENTS.md 里的路径是否真实存在，~是否被正确展开
2. 检查文件名是否和引用一致——注意大小写，SKILL.md和skill.md在某些文件系统下是不同的
3. 确认文件编码是 UTF-8，不要有 BOM 头
4. 新开会话再试，因为技能是在会话启动时加载的，中途改文件不会热更新

95% 的情况是路径写错或者文件名不匹配，剩下的就是忘了开新会话。

5.2 技能挂载太多：AI 反而变笨了

这是另一个极端。有人觉得技能越多越好，把十几份 SKILL.md 全写进配置。结果 AI 的上下文被技能说明占掉一大块，真正留给业务代码的空间就变小了，而且技能之间还会互相打架。

一个典型表现：AI 同时看到"代码审查技能"和"重构技能"，搞不清楚当前该走哪个流程，输出变得犹豫不决。

我的建议是常驻 3-5 个核心技能，其余技能通过"按需触发"来调用，也就是在对话中需要时再让 AI 读取对应文件，而不是一开始全塞进去。

5.3 记忆文件越写越长：AI 在故纸堆里打转

记忆机制用久了会面临一个新问题：文件里堆了几百条历史记录，AI 每次加载时都要读一遍，反而降低了响应质量和速度。

我的解决办法是给记忆文件做结构化分层：

• MEMORY.md：索引层，只保留当前最重要的决策和状态，一两屏能读完
• memory/archive/：归档层，按周或按月归档的历史记录，不被 AI 主动加载，需要时再查

每周末花十分钟整理一次记忆文件，把不再相关的记录归档。这样 AI 的记忆永远是"清爽的"，不会变成一团乱麻。

5.4 过度造技能：维护成本反超收益

我见过最离谱的是有人给"写一个简单的 REST 接口"都专门造了个技能。技能确实能造，但每造一个都要维护，内容过时了还可能误导 AI。

我给自己立了个标准：同一个问题被连续卡住三次以上，才值得为此写一个技能。一次两次偶发的问题，直接在对话里说清楚就好。技能是要跟随你很久的资产，宁缺毋滥。

5.5 权限和子代理边界：别让 AI 自己审自己

最后一个坑是关于子代理的权限问题。我早期配置子代理时，给它终端执行权限，然后让它同时负责写代码和审查。结果等于让运动员当裁判，审查流于形式，什么问题都没发现。

正确做法是把角色和权限分开：写代码的主代理拥有文件写入和执行权限，审查子代理只读代码、跑测试、输出报告，不允许修改文件。这个边界一旦模糊，审查环节就形同虚设。

6. 最后分享几个我自己的小习惯

文章到这里，核心内容基本都讲完了。最后说几个我实际操作中沉淀下来的小习惯，不一定适合所有人，但可以参考：

每天早上开工，我第一句永远是让 AI 加载项目记忆，然后走一遍 planning 流程，把当天要做的改动整理成计划再动手。新项目初始化时，我会先让 AI 用 planning 技能生成一份 PLAN.md，结合项目结构和团队规范确认后再开始写代码。每个季度我会 review 一遍技能列表，删掉超过一个月没用过的技能，保持技能库的"新陈代谢"。

还有一个收益最大的习惯：把整个 superpowers 配置和技能文件提交到团队 Git 仓库里。新人入职 clone 项目后，内置的 AGENTS.md 和技能文件会自动生效，团队所有成员等于共用一份持续更新的"AI 工作手册"。

说到底，superpowers 没有让 AI 变得更聪明，它只是让 AI 用上了更有纪律的工作方式。我自己的体会是，换模型带来的提升是线性的，而改变工作流带来的提升是复利式的。只要你肯花一点时间建立自己的技能库，这笔投入会一直滚下去。