企业官网建设流程全解析

1. "superpowers"到底是什么：它不是插件，而是一套让Codex脱胎换骨的工作方法

说句实话，我最初看到"superpowers"这个词是在技术社区刷到的一条推文，配图是一段终端录屏：一个人对着Codex CLI说了句"把这个模块重构掉，保持对外接口不变"，然后AI自动拆任务、自动改代码、自动跑测试、自动修问题，前前后后折腾了二十多分钟，最后还自动写了一版PR描述。评论区一片"卧槽"，我当时的第一反应是：这肯定又是剪出来的效果。

直到我自己把整套东西跑通，才意识到问题出在哪里。过去我使用Codex也好，其他AI编码助手也好，最大的痛点并不是模型不够聪明，而是它每次只活在"这一个文件"里。你说"帮我修一下这个函数的性能问题"，它改完就完了，完全不记得项目里还有三个地方调用了这个函数，更不会想到改完之后应该去跑一下相关的测试。说白了，大部分时间它像一个"高智商但低情商"的实习生：你交代一件事，它就做一件事，其他的一概不管。

而"superpowers"这套东西，本质上就是解决这个问题的。它不是一个独立的软件，也没有安装包，而是一套围绕Codex CLI的配置方法论，核心是借助AGENTS.md这个指令文件，把AI从"单文件工具人"改造成"能理解项目全局、能自主规划、能自动验证"的虚拟老员工。社区里管这种用法叫"superpowers"，因为它确实让Codex的表现产生了质变。

它的价值主要体现在三个层面：

• 上下文连续性：通过精心设计的AGENTS.md，让AI在每次交互时都能快速加载项目的技术栈、目录结构、代码规范和常见陷阱，不用你反复解释背景。
• 任务自主性：它会把一个大的需求拆解成具体的子任务，按顺序执行，每完成一步就自动验证，形成"写代码-跑测试-修问题-再验证"的闭环。
• 输出一致性：包括代码风格、提交信息格式、PR描述模板、文档更新策略等，AI的输出不再是碎片化的，而是符合团队规范的完整交付物。

如果你现在还在用"开个对话框、贴一段代码、让它改一改"的原始方式使用AI编程工具，那这篇分享就是写给所有想让AI真正承担工程任务的人看的。下文我会从环境搭建、配置设计、实战案例和踩坑经验四个方向，完整拆解这套工作流。

2. 从零搭一套superpowers工作流：环境准备和第一份AGENTS.md

2.1 环境准备阶段容易被忽略的三个细节

在这套工作流里，Codex CLI是核心载体，所以第一步自然是把运行环境准备好。官方安装方式很简单，npm install -g @openai/codex或者用homebrew，我自己的机器是macOS，用的brew方案，几分钟就装完了。

但这里有几个细节，新手非常容易栽跟头：

第一个是Node版本。新版Codex CLI对Node的要求不低，如果本机还是Node 16以下的版本，启动的时候会报各种奇怪的错，而且错误信息并不直白。建议直接用nvm装一个长期支持版，比如20或者22，省心很多。我一开始用的是系统自带的旧版本Node，结果浪费了将近一个小时在排查环境问题上。

第二个是Shell集成。Codex CLI本质上是个终端工具，如果你用的是旧版iTerm或者Windows老式终端，渲染效果和交互体验都会打折扣。建议用较新的终端模拟器，我甚至专门配了JetBrains的MCP插件，这样可以直观地在IDE里看到Codex的修改diff，比纯终端体验好了不止一个档次。

第三个是API Key的权限范围。如果你只是本地开发调试，权限可以收紧一些；但如果你打算让Codex去调用MCP工具、操作文件系统、执行测试命令，那就需要确认API Key对应的账号有足够的模型访问权限，否则跑到一半莫名其妙断掉，排查起来很头疼。

2.2 AGENTS.md应该写什么：角色、规程、红线

环境准备好之后，重头戏来了：在项目根目录创建一份AGENTS.md。这是整个superpowers工作流的灵魂所在，它承担了"给AI立规矩"的职责。

我的建议是分四个区块来写：

第一块是角色设定。明确告诉AI它在当前项目里是什么身份。比如你可以写"你是一名拥有十年经验的Java后端工程师，负责订单模块的开发和维护"，这比空泛的"你是一个编程助手"有效得多。因为角色设定会直接影响模型的回答风格和详尽程度，角色越具体，输出越贴合工程实际。

第二块是项目认知。把项目的技术栈、目录结构、构建工具、测试框架全部写清楚。比如这是一个Maven管理的Spring Boot项目，核心模块在order-service和fulfillment-service下，测试用的是JUnit5 + Mockito，构建命令是mvn -pl order-service -am package -DskipTests。这些信息看起来琐碎，但它们是AI不瞎搞的基础。没有这些，AI可能用Gradle命令去构建Maven项目，或者把测试文件放错模块。

第三块是工作规程。这是最关键的部分，它定义了AI拿到需求之后应该怎么干活。我的做法是给AI设定一套标准动作序列：

• 先读相关源码，梳理调用链，不要上来就改
• 每次修改前先说明计划和影响面
• 改完之后必须运行相关测试
• 测试挂了要自己看日志定位问题，不能把错误抛给用户就完事

第四块是红线。明确什么不能做。比如：不允许修改pom.xml的依赖版本除非用户明确要求；不允许删除数据库迁移脚本；不允许在没有测试覆盖的情况下重构核心业务逻辑。红线的作用是给AI一个"刹车机制"，防止它在自由度太高的时候做出破坏性操作。

2.3 一份可以直接抄的AGENTS.md骨架

下面我贴一份适用于Java Spring Boot项目的AGENTS.md骨架，你可以在此基础上加内容：

# 项目角色 你是一名资深Java后端工程师，负责订单与履约模块的开发维护。 # 技术栈 - JDK 17, Spring Boot 3.x - Maven多模块工程，核心模块：order-service, fulfillment-service - 数据库：PostgreSQL 15 - ORM：Spring Data JPA - 测试：JUnit 5 + Mockito + Testcontainers - 构建命令：mvn -pl order-service -am package -DskipTests - 测试命令：mvn -pl order-service test # 工作规程 1. 在修改任何代码前，先阅读相关文件，梳理调用链和依赖关系。 2. 每次实施修改前，用3-5句话说明修改计划、影响范围和风险点。 3. 修改完成后，立即运行相关模块的测试。 4. 测试失败时，自行分析错误日志并修复，禁止把未经验证的代码直接交付。 5. 涉及公共接口变更时，必须同步更新调用方代码和相关文档。 # 红线 - 未经明确指示，禁止修改pom.xml中的依赖版本。 - 禁止删除或修改数据库迁移脚本。 - 禁止跳过测试直接交付代码。 - 禁止在未创建分支的情况下直接修改主分支代码。 # 提交规范 - 提交信息格式：<type>(<scope>): <subject>，例如 fix(order): 修复超时异常处理 - type类型：feat / fix / refactor / test / docs / chore

这份配置虽然简短，但你实际用下来就会发现，Codex的行为方式和之前完全是两个样子。它不会上来就改，而是会先告诉你"我打算这么做，影响面是这些"，这在多人协作或者维护老项目时特别有价值。

3. 让Codex真正"动手"：任务分解与自动执行循环

3.1 为什么一次对话搞不定复杂需求

很多人在使用AI编码工具时有个错觉：只要我描述得足够清楚，AI就应该一次性把所有事情搞定。但现实是，对于涉及多个文件、多个模块的复杂需求，一次长对话的执行效果远不如"短任务循环"。

打个比方：你让一个实习生独立完成"给系统加一个缓存层"，他大概率会先花很久研究你口中的"缓存层"到底是什么意思，然后动手写，写错了也不知道，最后交给你一个爱因斯坦不认的东西。但如果你让他"先画个方案，确认了再动手，每改完一个文件就编译一次，测试挂了就停下来问你"，虽然他每个动作都显得笨拙，但完成质量和可控性会高很多。

superpowers工作流的核心机制，就是把这个"分步走"的过程自动化。它通过让AI自己拆解任务、自己逐步执行、自己验证结果，来避免"一步到位"带来的不可控性。

3.2 在AGENTS.md中定义自动执行循环

具体的实现方式，还是在AGENTS.md里做文章。我会在配置里加上下面这段"任务执行循环"的规程：

# 任务执行循环 当你接收到一个复合型开发任务时，按以下循环执行： 1. 拆解：将任务拆成不超过6个子任务，每个子任务必须可独立验证。 2. 排序：按依赖关系排列执行顺序，明确标记可并行部分。 3. 执行：每次只处理一个子任务，完成后立即验证。 4. 验证：运行编译、测试、lint等检查，确认无回归。 5. 汇报：每完成一个子任务，用简短的进度摘要告知用户。 6. 复盘：全部完成后，列出修改的文件清单、测试结果和潜在风险。

加上这段之后，你再给Codex下达一个复杂指令，它会输出类似这样的工作节奏：

已收到需求。我将任务拆解为5个子任务：

1. 在OrderService中定义缓存接口（依赖：无）
2. 实现RedisCacheProvider（依赖：1）
3. 在查询方法上接入缓存（依赖：2）
4. 补充缓存命中率的测试用例（依赖：3）
5. 运行order-service全部测试并修复回归（依赖：4）
   现在开始执行子任务1...

这种明确的进度汇报，对使用者来说意义很大。你不再需要隔三差五去"盯一眼"AI在干什么，而是可以在它汇报每一步时同步审视有没有跑偏。如果某个子任务拆得不对，你可以立即打断纠正，而不是等它全做完才发现方向错了。

3.3 质量门禁：让AI自己给自己把关

真正让这套工作流"靠谱"的关键，是质量门禁的设计。在AGENTS.md里我专门加了一节：

# 质量门禁 - 任何代码变更必须通过：编译、相关测试、代码风格检查。 - 新增业务逻辑必须有对应测试用例，否则视为未完成。 - 测试覆盖率低于80%的模块，需要说明原因并补充缺失用例。 - 禁止使用 @SuppressWarnings 掩盖警告，需要注明理由。

这相当于给AI装了一个"自我质检"的流程。它不再是写完就交差，而是写完必须自己跑一遍测试、自己看覆盖率报告、自己决定要不要补测试。刚开始配置这些门禁的时候，你可能会觉得麻烦，但用一段时间后会发现收益极大——你收到的代码，比你亲自review几遍的质量还稳。

有一次我临时有事离开工位，回来发现Codex已经把订单模块的缓存改造做完了，自己跑了全部单测，还额外补了两条边界条件的测试用例，PR描述也写好了。这就是质量门禁起的作用：它把"做完"的标准从"能编译"提升到了"可交付"。

4. Java项目实测：superpowers在重构场景下的表现

4.1 一个真实的重构任务

理论说了这么多，拿一个真实的Java场景来检验一下。

我的一个老项目里有个OrderService，历史包袱很重：一个类快1500行了，方法职责混乱，条件嵌套七八层，每次改动都提心吊胆。领导终于批了重构预算，但要求"对外接口不变、现有测试全绿、不允许大爆炸式重写"。

我决定把这个任务交给配置好superpowers工作流的Codex来干。我的指令很简单：

重构OrderService，拆分职责，保持对外接口签名不变，所有现有测试必须通过，运行mvn -pl order-service test验证。

在AGENTS.md里，我已经提前写清楚了项目结构、构建命令和测试要求，所以Codex没有追问任何背景信息，直接开始了任务拆解。

它的执行过程大致是：

• 先扫描了OrderService的全部方法，梳理出四类职责：订单状态流转、价格计算、库存校验、事件发布。
• 提出拆分方案：分别抽OrderStateMachine、PriceCalculator、InventoryValidator、OrderEventPublisher四个类，OrderService只做门面。
• 每抽出一个类，先建文件，再移动方法，再编译，再跑测试。中途有一个方法的依赖注入没处理好，测试挂了，它自己看了日志，补了一个构造参数，下一轮就绿了。
• 最后补了一份重构说明文档，列出行为等价性验证的方式和风险点。

4.2 30分钟完成重构：实测数据

整个重构过程，从开始到最终全部测试跑通，耗时大约30分钟。如果在人工状态下，这种规模的重构，一个经验丰富的工程师至少需要大半天，且容易引入隐蔽的回归问题。

我特别关注了Codex在以下几种情况下的表现：

其中让我印象深刻的是行为等价性保障。Codex在拆分过程中始终没有改动过OrderService的对外方法签名，也没有改变事务注解的位置和传播行为。这得益于我在AGENTS.md里写了一条明确的红线：重构不允许改变对外可观察行为。如果没有这条约束，AI很可能会自作主张把某个事务方法改成非事务的，然后自以为"优化"了性能——那是灾难。

4.3 Java场景的配置要点

如果你也打算在Java项目上跑这套工作流，有几个配置要点值得注意：

第一，测试命令必须写精确。多模块Maven项目里，如果直接写mvn test，可能会在几十个模块上来回折腾，既慢又容易误报。我建议写成mvn -pl 具体模块 -am test，只测跟当前改动有关联的模块。

第二，把checkstyle或spotbugs的规则路径写进AGENTS.md。Java项目通常有严格的代码规范，如果不告诉AI规范文件在哪，它写出来的代码风格很可能跟团队现有风格不一致。我遇到过它把封装类写成了Java 8风格，而项目已经全面切换到Java 17的record。

第三，数据库相关的改动必须明确"禁止自动执行迁移"。我的红线里有一条就是：不允许AI直接修改数据库迁移脚本。因为自动生成的Flyway或Liquibase脚本在顺序上很容易出错，一旦错位，生产环境就炸了。让AI只生成SQL片段、由人来确认，是更稳妥的做法。

5. 踩过的坑和调优心得

5.1 最容易翻车的三个场景

这套工作流虽然香，但绝对不是零门槛。我自己用下来的体感，有三个坑特别容易踩。

第一个坑是AGENTS.md写得太长太细，导致AI的行为变得僵化。有一次我给一个老项目写了几乎覆盖所有细节的规则，结果Codex每做一个动作都要先跟自己的规则核对一遍，效率低到令人发指。后来我学乖了：规则要有优先级，长指令不如精指令。只保留真正影响交付质量的规则，其余一律删除。

第二个坑是并行任务过深。AGENTS.md里如果允许AI自行决定并行子任务的数量，它有时候会尝试同时改四五个文件，然后编译错误像雪崩一样涌过来，修复成本反而更高。我后来明确要求"串行为主、并行为辅"，并且限制同一时间最多并行两个子任务。

第三个坑是无限循环自嗨。有时候一个测试挂了，AI会反复修改、反复测试，始终修不好，但也不停下来问你，就这么无限循环下去。后来我在规程里加了一条：同一个子任务如果连续失败三次，必须停下来并把问题完整描述给用户，由人来决策。这条规则救了我很多次。

5.2 从"能用"到"好用"的三个调优建议

如果你们团队也打算把这套工作流沉淀为日常开发的一部分，我有三个建议：

第一，按项目类型维护不同的AGENTS.md模板。我现在维护着一套"Java后端"模板、一套"Python数据"模板和一套"前端React"模板，每套模板的构建命令、测试框架、代码规范都不一样。新项目初始化的时候直接复制模板再微调，非常高效。

第二，定期复盘AI的错误模式。用这套工作流一个月之后，你会发现AI犯的错误高度集中：可能是时间处理、可能是事务边界、可能是对某类API的误用。把这些错误模式直接写进红线和注意事项里，它能帮你省掉大量重复的排查时间。

第三，善用会话上下文裁剪。Codex CLI虽然能处理长对话，但太长的会话上下文会导致响应变慢、质量下降。我习惯每个子任务跑完之后，用/compact之类的指令精简上下文，只保留决策摘要和待办事项，这样后续子任务的执行精度会高很多。

5.3 我总结的一条心得

在这套工作流里，真正难的从来不是配置，而是你对自己项目的理解深度。AGENTS.md里的每一条规则，本质上都是你对项目最关键约束的具象化。你越是清楚哪些约束不能丢、哪些环节容易出错、哪些红线必须守住，AI的表现就越好。反过来说，如果连你自己都说不清楚项目的边界在哪里，AI就算有了superpowers，也只能在模糊的地图上乱跑。

6. 再往下走：从单项目superpowers到团队级沉淀

最后聊一点我最近正在尝试的扩展方向。目前我已经不满足于在单个项目里用这套工作流了，而是开始把它沉淀成团队级别的资产。

具体的做法是，把我们团队的AGENTS.md做成三层结构：最里层是通用工程准则，比如"不允许删除测试""修改公共API必须同步文档"；中间层是团队技术栈约束，比如"后端统一使用Spring Boot 3.3""禁止新增非必要的Lombok用法"；最外层才是具体项目特有的规则。这样新成员入职的时候，只要把三层模板拷贝到对应项目里，再按实际情况增删，就能快速获得一套靠谱的AI协作基线。

另外，我还在尝试把"superpowers"和CI/CD做联动：让Codex在本地完成开发后，自动把分支推到远端并触发流水线，然后根据流水线的结果决定是否继续修改。这套链路目前还没有完全跑通，主要卡在流水线安全和权限控制的环节上。但方向我很确定——AI的"超能力"如果止步于本地开发，那它只能算个人效率工具；只有当它内嵌到整个研发流程里，它才真正具备"超级工作流"的威力。

如果你也在摸索Codex的使用姿势，强烈建议从一份精简的AGENTS.md开始，先跑通一个模块，再迭代到全项目。相信我，等你习惯了它自主拆任务、自己验证、自动汇报的节奏之后，你就再也回不到以前那种"贴代码、等回答"的原始模式了。