企业官网建设流程全解析

Superpowers这个名字，第一眼看到的时候我以为是讲超级英雄的电影，直到在Codex社区的讨论里刷到它，才发现这是过去半年里对我编码习惯影响最大的一个开源项目。简单说，Superpowers是一套给Codex CLI的增强工作流，它把AI编程从“聊一句、改一段”的散装模式，变成一套有纪律、可复现、有记忆的专业开发流程。如果你已经被AI写代码“又爽又慌”的状态折磨过——改了一个文件，顺带破坏了三个功能；上午的对话，下午的会话全忘了——那这篇文章就是写给你看的。我会把Superpowers的原理、安装、核心机制和实际开发中的完整流程拆开讲清楚，尤其会把那些文档里不会写的踩坑经验一并整理出来，你可以直接照着用。

1. Superpowers不是魔法，是一套让AI“上规矩”的开发流程

1.1 这个项目到底是什么

Superpowers本质上是一个开源CLI工具，最初是受到Smol AI这类项目的启发，把“如何指导AI写代码”这件事，从一段随手的prompt升级成一套结构化的工程规范。它不替换Codex，不重写模型，而是做Codex的“外挂大脑”：通过一批预先定义好的技能文件（skills）、一套以测试驱动开发（TDD）为核心的执行循环、以及持久化的项目记忆机制，让Codex在工作时不再是“聪明但健忘的实习生”，而是“有工作手册、有检查清单、有项目笔记的可靠工程师”。

我第一次跑通的时候最直观的感受是：同样让Codex做一个功能，以前它像在即兴演讲，想到哪写到哪；接入Superpowers之后，它像在照着施工图干活——先拆任务、再写测试、然后才写实现，每完成一步还会主动回读项目状态。这种差别不是模型变强了，而是给模型搭了一套约束和反馈的轨道。用生活类比来说，普通AI写代码像是让你家聪明的小孩直接上手做满汉全席，他天赋是够的，但会漏步骤、加错料、忘记关火；Superpowers则是把菜谱、计时器、检查清单都摆在台面上，还要求他每做完一道菜先自己试吃再端上来。

这个项目不是给会用AI的人锦上添花，而是给那些“被AI坑过多次、开始怀疑AI编程不靠谱”的人雪中送炭。适合的人群很明确：日常用Codex或类似终端型AI编程助手的开发者，需要处理多文件、多步骤、有测试要求的真实项目，以及希望把AI产出真正纳入代码审查流程的团队。

1.2 它解决了AI编程中最痛的三件事

我过去用Codex写代码，最怕三件事：上下文丢失、局部正确全局崩溃、以及改完心里没底。Superpowers的设计目标几乎就是冲着这三个痛点去的。

先说上下文丢失。AI对话窗口有长度限制，项目大了之后，前一轮聊的架构决策，后一轮就查无此证。Superpowers的做法是建立项目级的“记忆文件”，把关键决策、用户偏好、技术债、待办事项全部落盘到.superpowers/目录下，每次新会话先读记忆再动手。相当于给AI配了一本工作日志，而不是只靠它脑子里的临时缓存。

再看局部正确全局崩溃。模型很擅长在它“看到”的代码范围内做改动，但经常看不到改动引发的连锁反应。Superpowers的核心应对手段就是强制TDD：任何功能改动，必须先写测试，测试挂了，才能写实现。测试通过后，整条链路才算完成。这样做的本质，是把“对系统的理解”从模型的大致猜测，变成“可执行、可验证的约束条件”。测试就是给AI划的牢笼，它再能折腾，跑不出去。

最后说心里没底。以前AI改完代码，我得人肉读diff、手动跑用例、再脑补边界情况，累且不靠谱。Superpowers要求每个任务拆成细粒度todos，每完成一个todo就伴随一次测试执行和结果记录，产出变得高度可审查。你不再需要信任AI“这次大概没问题”，你只需要看测试输出和改动范围，自己判断是否接受这次提交。

2. 安装与环境准备：5分钟把Superpowers跑起来

2.1 前置依赖与安装步骤

在动手之前，先把前置条件说清楚。Superpowers运行在Node.js生态上，所以第一步是确认你本机有能用的Node环境。版本上尽量新一点，实测Node 18以下会遇到一些语法兼容问题，推荐Node 20及以上。其次你需要一个可用的Codex CLI，因为Superpowers是增强Codex的，Codex本身得先装好、配置好API密钥、能正常对话，否则后面所有流程都是空中楼阁。

确认环境之后，安装Superpowers就是一条npm命令的事。我个人的习惯是用全局安装，这样在任何项目目录下都能直接调用：

npm install -g superpowers

装完之后，先验证一下：

superpowers --version

如果能看到版本号，说明核心CLI已经就绪。接下来进入项目目录，执行初始化命令：

superpowers init

这一步会在当前项目生成Superpowers的工作区，也就是.superpowers/目录，里面会有默认的skills分类、记忆文件模板和配置项。生成完之后，注意检查一下是否被Git忽略。如果项目的.gitignore漏掉了.superpowers/，跟团队协作时这些本地记忆可能被误提交，也会污染仓库。我的做法是把.superpowers/里除skills/和templates/之外的内容加入忽略列表，保证记忆不共享、技能可共享。

2.2 配置Codex识别Superpowers的工作流

CLI装好只是第一步，让Codex真正“知道”自己该按Superpowers的方式工作，还需要把技能文件路径挂到Codex的上下文里。不同版本的Codex集成的配置方式略有差别，最新的做法是在Codex的配置文件中通过AGENTS.md或预设（preset）的方式引入Superpowers的skills目录。你可以查看Codex的配置说明，找到指向.superpowers/skills/的字段，把它加进去。

如果你不想在配置文件里折腾，也可以直接在对话中给Codex一条引导指令，让它先读取Superpowers的主入口文件。比如这样：

请先阅读 .superpowers/AGENTS.md，然后按Superpowers的流程来处理我的需求。

这种方式的好处是灵活，缺点是你每次都得多打一句引导词。我的建议是两种结合：配置文件里挂好默认入口，关键项目再在对话开头显式强调一次，双保险。

另外，务必确认你使用的Codex版本支持自定义技能文件和TDD循环所需的功能。我们实测中，早期版本存在上下文截断过长、无法可靠读取多技能文件的问题。如果你发现装完Superpowers后，AI依然在“裸奔”，先检查版本，而不是怀疑自己装错了。

2.3 验证安装成功：跑一个最小的TDD示例

环境装好之后，先别急着拿真实项目练手，用一个最小用例把整个流程跑通。我会创建一个临时目录，进去跑superpowers init，然后要求Codex“用Superpowers的规范实现一个JavaScript的加法函数，必须包含测试”。

如果一切正常，你会看到它没有急着写add函数，而是先建测试文件，然后跑一次测试——测试报错（Red阶段）——再去写实现——再跑测试直到通过（Green阶段）。看到这个循环出现，你的安装就真正成功了，后面所有项目都可以按这个节奏推进。

3. 核心机制拆解：Skills、TDD循环与记忆系统

3.1 Skills：AI的岗位技能手册

Skills是Superpowers最核心的抽象。你可以把它理解成一份份岗位技能手册，每本手册定义一个特定任务的完整执行方法：什么时候触发、按什么顺序做、哪些事绝对不能做、产物长什么样。举例来说，项目里可能有一个code-review.skill.md，里面规定了AI审查代码时先看安全问题、再看边界条件、最后看风格；还有一个database-migration.skill.md，规定了迁移脚本必须包含回滚方案。

为什么要把这些内容从对话里剥离出来，单独存成文件？我自己的经验是：同一段高质量指引，放在对话里，几轮之后就会被模型忘掉或稀释；但放在skill文件里，每一次触发都能稳定加载，效果几乎可复现。这在团队场景尤其有价值，你可以把团队的编码规范沉淀成一个skill文件，所有用Codex的同事共享同一套执行标准，而不是靠每个人在prompt里写“请遵循我们团队的编码风格”这种模糊指令。

不同的skill之间还支持相互调用。一个“实现新功能”的skill，会在内部触发“写测试”的skill，测试思路又会优先选择“调试失败用例”的skill来处理红灯。这种组合式的设计，让AI的行为模式无限接近一个有经验工程师的思维路径，而不是一个只会“吐代码”的生成器。

3.2 TDD循环：为什么AI必须先看到失败

Superpowers对TDD的坚持是近乎偏执的。我刚开始觉得这是“为了仪式感”，但用了两个星期之后彻底服了。对于模型而言，“写一个能通过的测试”和“写一段实现代码”的难度完全不在一个量级。测试本质上是对需求的精确化表达，它逼着模型在动手前把输入输出、异常分支、边界条件都想清楚。如果没有测试这道紧箍咒，模型极易产生“代码写得爽、逻辑全漏光”的结果。

标准的三步循环是Red-Green-Refactor。Red阶段：AI只写测试，然后运行，预期结果是失败。这个失败是有价值的，它证明了测试真的在约束行为，不是摆设。Green阶段：AI写最小实现，直到测试通过。Refactor阶段：在不改变行为的前提下优化代码结构。整个过程每个阶段都伴随测试执行和输出记录，因此整个开发历史有据可查。我们用TDD本来是为了约束自己，现在拿来约束AI，逻辑是通用的：先定验收标准，再谈实现。

实际执行中，我会要求AI“每完成一个todo，都必须给出对应的测试输出”。这不仅是给AI看的，也是给我看的。我扫一眼测试结果，就能判断这次改动是真正完成还是假装完成。模型有时候会表面上说“测试通过”，实际上根本没跑，所以我会在审查时特别留意AI贴出的测试输出，如果格式奇怪、没有时间戳、没有具体运行命令，就会要求它重跑一遍并把原始输出原样贴出来。

3.3 记忆系统：让AI跨会话“记得你”

Superpowers的记忆机制，最初是我不太在意、后来真香的功能。它把记忆分成几类：项目决策记录（ADR风格）、用户偏好（比如“本项目的错误信息必须包含错误码”）、技术债清单、以及一份当前任务的todos。

每次会话开始，AI会先读取.superpowers/memory/目录下的相关文件，把上次的进度、决策、未完成事项全部装载进上下文。这意味着你今天没写完的功能，明天开个新会话，它不用你重新解释需求，直接接着干。我实测过一个跨了三天、换了四个会话窗口的小需求，每次新会话只需一句话“继续”，AI就能准确接上进度，这种体验在纯粹用Codex时基本不可能实现。

记忆文件还有个好处，就是可审查。AI的工作记忆对你透明，你可以随时打开.superpowers/memory/查看它理解了哪些约束、记录了哪些决策。如果发现它理解偏了，直接编辑记忆文件纠正，比在对话里反复解释高效得多。这个习惯我强烈建议你从第一天就养成：把记忆文件当项目文档维护，而不是当黑盒日志。

4. 实操全过程：用Superpowers做一个“用户注册接口”

4.1 需求拆解：让AI先把todos列出来

前面讲了这么多机制，这一节咱们实际操作一遍。假设我有一个Express写的API项目，现在要做“用户注册接口”，需求包括：接收用户名和密码、密码需要加密存储、用户名不能重复、参数校验失败要返回400、成功要返回201。我先在对话中把需求丢给Codex，并加上一句“按Superpowers流程拆分todos，不要直接写代码”。

它给出的todos大致是这样：

- [ ] 分析现有项目结构，确认数据库和数据访问方式 - [ ] 设计用户表结构和密码加密方案 - [ ] 编写注册接口的参数校验测试（空值、格式错误） - [ ] 编写用户名唯一性冲突测试 - [ ] 编写注册成功测试 - [ ] 实现参数校验中间件 - [ ] 实现路由与控制器 - [ ] 运行全量测试，确认绿灯 - [ ] 更新memory文件，记录本次架构决策

这份清单里有两个我特别欣赏的点：一是它把“分析现有项目结构”放在第一位，而不是一上来就写路由，这说明skill流程在起作用；二是它在最后安排了“更新记忆”，保证下次会话还能接上。拿到这份todos后，我不会一股脑全放行，而是要求它“先完成第一个todo，展示结果后再继续”。这样每一步都可控，不会出现它闷头干了半小时、给你一坨无法审查的巨型diff。

4.2 观察Red-Green循环如何约束AI写代码

第一个todo执行完，AI贴出了项目结构分析，确认了项目用的是Sequelize ORM，数据库是SQLite。我放行第二个todo，让它设计方案并写测试。它先写了三个测试文件：参数校验测试、用户名冲突测试、成功注册测试。我让它跑测试，结果必然是红灯，因为路由和控制器都还没写。

到这里，我观察到它本能地想“顺便把实现写了”，但Superpowers的流程要求它停止。它就停在测试失败的地方，把失败输出贴出来，等我下指令。这种“刹车”行为，是流程带来的最大价值。以前用Codex，它会一条龙写完所有东西；现在它会按我的节奏来，测试不过就不写实现。你可能会觉得这样“效率变低了”，但实际算下来，返工率大降，总体进度反而更快。

接下来我让它进入Green阶段，写最小实现。它创建了迁移脚本和用户模型，补上了加密逻辑，然后重新跑测试，这次全绿。然后它自己进入重构阶段，把参数校验从controller里抽成了独立中间件，再次跑测试确认结果不变。整个过程没有一步是“改完不确定对错”的状态，每次变化都有测试兜底。

4.3 审查AI的diff：应该在哪些地方多留一个心眼

AI跑完全绿，不代表可以直接合并。我会把改动文件逐一看一遍，重点检查三类问题。

第一是安全性。看密码加密是否用了成熟的库（比如bcrypt），有没有自己发明加密算法；用户名比对是否区分大小写、是否做了trim；返回的错误信息是否泄露了内部结构。第二是测试质量。检查测试是不是“假绿”——比如测试覆盖的是错误的函数、或者断言写得太宽松。我要求AI把断言写成“精确值对比”，而不是“只要不抛异常就算通过”。第三是隐含变更。AI有时会在改动途中顺手改掉一些无关代码，diff里会看到与需求无关的格式化或重命名，这类改动要严格控制，否则代码审查就是灾难。

审查通过后，我把这次的架构决策追加到memory文件里：密码使用bcrypt加密、用户名字段加了唯一索引和trim处理、API返回格式统一为{ code, message, data }。下次再开发登录接口、忘记密码这些功能时，它会自动遵守这些约定，而不是重新发明一套。

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

5.1 安装与启动阶段的问题

我把这段时间遇到频率最高的问题整理成一个速查表，你可以直接对照排查。

5.2 流程执行中的典型坑

第一个坑，AI会在测试没写的情况下强行“实现”，然后告诉你“我先写完再补测试”。遇到这种情况，我会坚定拒绝：照Superpowers的流程来，先测试、见红灯、再实现。不要怕显得死板，这个流程就是靠死板才能保证质量。

第二个坑，AI反复尝试同一种失败的方案。比如某个测试一直不通过，它会在同一个思路里打转。我处理的方法是，打断它，要求先检查测试的断言和前置数据是不是错的。很多时候测试失败不是实现的问题，而是需求定义本身已经错了，这时候写再多实现都是白费。

第三个坑，上下文被无关内容污染。Codex在长对话中可能会把之前讨论的无关话题混进来。我的习惯是当SDK在会话中表现“混乱”时，不再继续对话，而是直接开一个新会话，让它读取记忆文件和todos，重新开始。不要指望在一条已经混乱的上下文里把它“聊”回来，那只会消耗你的耐心。

5.3 团队落地时的额外建议

如果你想把Superpowers引入团队，我有几条实操心得。先选一个明星项目试点，不要一开始就全团队推广。让最熟悉AI编程的同事先用两周，沉淀出适合团队的一批skill文件，再逐步铺开。其次，定期更新记忆文件里的技术债清单，这会让AI越来越契合项目的真实状态。最后，把superpowers init生成的模板纳入新项目初始化流程，这样每个新项目从第一天起就有AI工作流，而不是等项目写烂了再补课。

最后分享一组我的个人配置习惯

上面这些内容基本覆盖了Superpowers从装到用的完整链路。最后分享三个我私藏的配置习惯，你在落地时可以直接抄作业。第一个，在skill文件里显式声明“不要修改测试文件中的断言来让测试通过”，这看起来是废话，但AI在没有这个约束时真的会改断言造假，加上后省心很多。第二个，把memory文件设置为每日自动备份到本地Git分支，万一被AI的某次操作覆盖掉，还能恢复。第三个，每个重要功能的开发我都要求AI保留一份测试输出存档在项目的docs/test-logs/下，这不仅方便我审查，以后的回归测试也有底可查。希望你用上这套工作流之后，能体验到那种“AI终于靠谱了”的感觉。