企业官网建设流程全解析

最近在折腾 Codex CLI 的时候，我发现了一个叫 Superpowers 的开源技能框架，它解决了一个特别实际的问题：AI 编码代理能听懂你的意图，但常常记不住过程。你明明说了要先写测试，它写两行代码就急着拿结果；你告诉它项目里已经有现成的工具函数，它偏要自己重新造一个。Superpowers 的做法很朴素——把好工程师的工作习惯，包括 TDD 流程、调试顺序、代码审查清单，全部写成结构化的技能文件，让代理在开工前先完整读一遍。模型还是那个模型，但它的行为方式会稳定很多。这篇笔记记录我这段时间的实战经验，包括安装步骤、技能原理解析、一个 Java 项目的完整实操，以及常见坑的排查方法。内容比较偏实操，适合已经在用或者正准备用 Codex CLI、想进一步提高 AI 编码代理稳定性的开发者。

1. 项目整体设计与思路拆解

1.1 为什么需要“技能”，而不是单纯换个更大的模型

很多人对 AI 编码工具有一个误解：觉得效果不好，就是模型不够聪明，换个更大的模型就万事大吉。实际上，大部分翻车现场不是模型不懂代码，而是模型不知道“在这个项目里应该按什么顺序干活”。同一个模型，你给它一句“帮我实现这个功能”，它可能直接生成一大段代码；但你给它一份“先写测试、跑测试、再实现、再重构”的步骤清单，它就能按部就班地执行。Superpowers 的核心思路就在这里：把隐性的工程经验，变成显性的技能文件。

更关键的是，大模型的上下文窗口是有限的。你不可能在一个对话里把所有要求反复叮嘱一遍，哪怕你说了，二十轮对话之后它也会忘。技能文件则不同，它是持久化存在的，每次代理启动新会话时都会重新读取。它就像给一个能力很强但记性不好的实习生发了一本《员工手册》，比每次开会时口头交代有效得多。我实际测下来，启用技能集之后，代理写出来的测试覆盖、代码拆分逻辑，明显比“裸奔”状态要规范，而且很少出现改 A 坏 B 的情况。

1.2 Superpowers 的三大组成：技能目录、AGENTS.md、记忆文件

Superpowers 的结构不复杂，核心就是三块内容。第一块是 skills 目录，里面每个技能对应一个 Markdown 文件，例如 tdd.md、debugging.md、refactoring.md。每个文件会描述：这个技能在什么场景下触发、应该按什么步骤执行、每一步的验收标准是什么。第二块是 AGENTS.md，这是代理启动时的入口文件，相当于总纲。它里面写了项目的基本背景、常用命令，以及应该优先启用哪些技能。第三块是记忆文件，通常放在 .agents 或 .codex 目录下，例如 progress.md 用于记录任务进度，known_dependencies.md 用来记录项目依赖和易错点。

这三块配合起来的逻辑很清晰：AGENTS.md 负责“开门”——告诉代理你是谁、项目是什么；skills 负责“给方法”——遇到具体任务时按哪套流程走；记忆文件负责“记账”——这次改到哪一步了、哪里容易踩坑，下次接着用。我建议你在落地的时候也保持这个三件套结构，不要图省事只复制一个技能文件，那样很快会乱。

1.3 与传统提示词工程的区别

很多人会觉得，这不就是在 AGENTS.md 里多写几句提示词嘛，我自己也能做。区别在于两点。第一，Superpowers 的技能文件是经过结构化的，它不只是几句话，而是一套包含触发条件、执行步骤、退出条件、输出格式的工作流定义。你自己随手写的提示词往往只有“你要认真写测试”这种抽象要求，代理无法执行；技能文件则会把“认真”翻译成“先运行测试，确认失败，再写实现，再运行测试确认通过”这种可操作动作。

第二，传统提示词是依附于上下文的，说得再多也会被后续对话冲淡；技能文件是独立于对话框之外的项目资产，可以多项目复用，也可以团队共享。我在团队里就把常用的技能目录单独建了一个仓库，新项目直接拉过来，大家心照不宣地遵守同一套规则。相比每次都在聊天里重复交代，这种资产化的方式维护成本低得多，效果也稳定得多。

2. 安装与配置：一步一步让 Superpowers 跑起来

2.1 环境准备：先确认 Node、Git 和 Codex CLI

在安装 Superpowers 之前，你要确保机器上已经有 Node.js（推荐 18 或以上版本）、Git，以及 Codex CLI 本身。Codex CLI 是 OpenAI 提供的终端编码代理工具，Superpowers 相当于是给这个代理加载的外挂技能包，所以代理本身必须能正常工作。

node -v git --version npm install -g @openai/codex codex --version

如果 node 版本太低，后续 npm 安装流程容易报错；如果 Git 没装，clone 仓库和读取配置都会有问题。这里我建议先把 Codex CLI 的服务端配置（也就是 API 密钥或登录授权）跑通，随便在一个空目录里让它生成一个文件试试，确认代理本身没问题，再来折腾 Superpowers，否则后面报错你会分不清是代理的问题还是技能集的问题。

2.2 获取 Superpowers：clone 还是直接复制

Superpowers 的安装方式比较灵活，最常用的做法是直接从 GitHub 克隆社区维护的仓库到本地，然后把它接入 Codex 的配置目录。你在搜索框里搜 “codex superpowers” 的时候，能看到一些社区仓库，例如 obra/superpowers 或者类似命名的项目，具体以你能找到的最新版本为准。我的做法是：

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

当然，如果你不想维护一个额外仓库，也可以只把目录里的 skills 和 AGENTS.md 复制到自己项目的 .agents 或 .codex 目录下。两种方式各有好处：Clone 方式方便随时拉更新，适合长期重度使用；复制方式更轻量，适合只想在某个项目里试水。第一次用我建议先 clone，因为这样你能看到完整的技能文件，后面出问题也好排查。

2.3 激活技能集：项目级和全局级两个入口

激活的过程实际上就是把 AGENTS.md 放到代理能读到的位置。Codex CLI 有两个加载层级：全局配置目录（一般是 ~/.codex/）和当前项目根目录。如果你希望所有项目都默认启用 Superpowers，就把仓库里的 AGENTS.md 复制到全局目录；如果你只想在某个仓库里启用，就把 AGENTS.md 和 skills 目录放到当前项目的 .codex/ 下面。

mkdir -p ~/.codex cp ~/superpowers/AGENTS.md ~/.codex/AGENTS.md cp -r ~/superpowers/skills ~/.codex/skills

这里有一个非常容易踩的坑：Codex CLI 在启动时读的是一个固定的 AGENTS.md，而不是你项目里随便起的什么 agents.md。文件名大小写、路径层级都必须对，否则代理根本看不到你的技能，表现就是“明明装了，但它就是不按套路来”。我建议配置完成之后先休息一下，执行下面的验证步骤，确认加载成功再开始干活。

2.4 验证加载：让代理自己说出它有什么技能

验证的方法很简单，你直接打开 Codex CLI，在会话里问一句：“根据你刚才加载的 AGENTS.md，你会使用哪些技能？请列出技能清单。” 如果代理能准确说出 tdd、debugging、refactoring 这些技能，说明 AGENTS.md 被读到了。如果它一脸茫然，或者回答的是它自己脑补的内容，那就需要检查路径和内容格式。

我还习惯用一个更直接的验证方式：随便丢给它一个和技能相关的小任务，比如“按照 tdd 技能，给下面这个函数补一个测试”。然后观察它第一步是直接写实现，还是先写测试再跑测试。前者说明技能没生效，后者说明技能已经进入它的工作流。这个验证比单纯看它能说出多少技能名字更可靠，因为有些时候代理会“背”技能名，但执行时还是按照默认习惯走。

3. 核心技能模块解析与原理

3.1 TDD 技能：把“红-绿-重构”变成代理的肌肉记忆

TDD 技能是 Superpowers 里我使用频率最高的一个，它解决的是“AI 急着出结果，不写测试”的毛病。技能文件里通常会把流程拆成五步：第一步，根据需求先写一个会失败的测试；第二步，运行测试，确认它确实失败并记录失败信息；第三步，写最小实现，让测试通过；第四步，再次运行测试，确认通过；第五步，在测试保持绿色的前提下做重构。

这一步一步看起来机械，但对 AI 代理特别有效，因为代理和初级工程师很像：你不给步骤，它就自由发挥；你给一个明确的检查清单，它会非常老实地执行。我在技能文件里会让代理“在动手写实现前，先用一句话说明下一个要写的失败测试是什么”，这一步能在很大程度上避免代理跳步。实际用下来，测试先行之后，代理写出的实现明显更收敛，不会一上来就建十几个类，也不会随手删掉已有测试。

3.2 调试技能：先定位根因，再动手修

调试技能的核心原则是“最小干预”。技能文件会要求代理：先复现问题，再阅读错误信息和堆栈，然后提出一个根因假设，最后才修改代码。很多翻车案例都是代理拿到一个报错就乱猜，比如把端口冲突当成代码逻辑问题，把类型错误当成数据库问题。有了调试技能之后，代理会被强制要求按顺序排查，并且在修改前说出自己的假设。

我用下来觉得最有价值的指令是：“在你修改任何代码之前，先写一个 50 字以内的根因分析。” 就这一句话，能让代理从“试错机器人”变成“理性排查者”。另外，调试技能一般还会要求代理检查最近改动过的文件，因为大多数 bug 都是最近改出来的，这个思维习惯对 AI 尤其重要——它自己可能都不记得上一轮生成过什么代码，让它优先排查自己最近的改动，反而更容易找到问题。

3.3 重构与代码审查技能

重构技能和 TDD 技能通常搭配使用。技能文件会强调“小步重构”：每次只提取一个方法、只改一个变量名、只删除一段重复逻辑，每做一步都要运行测试。这样做的原因很现实：AI 代理如果用一次大动作重构，涉及的文件太多，一旦出错，排查起来非常痛苦，而且大模型很容易在重构过程中悄悄改变行为的细节。小步走，每一步都验证，才能保证行为不变。

代码审查技能则适合用在提交 PR 之前。技能文件会要求代理按照清单检查：有没有安全问题、有没有边界条件遗漏、有没有命名不当、有没有明显重复代码、测试是否覆盖了关键路径。我通常会让代理先做完一轮自查，再把结果贴在 PR 描述里。这样不仅节省了 Review 的时间，也让 AI 在审查别人代码时有一个统一的基准，而不是凭感觉说“看着没问题”。

3.4 记忆系统：让代理知道“上次干到哪了”

记忆系统是我认为 Superpowers 最被低估的部分。编码任务往往不是一次会话能完成的，而 Codex 这类终端代理每次会话开始时，对之前的内容并没有主动认知。Superpowers 通过 progress.md 和 known_dependencies.md 来解决这个问题。progress.md 记录当前任务做到哪一步、下一步做什么、有哪些待验证内容；known_dependencies.md 则记录项目里已经存在但容易踩坑的东西，比如某个工具函数必须用特定方式调用、某个测试命令必须在根目录下执行。

要让记忆系统工作，关键是让代理在会话结束前主动回写。我会在技能文件里写死一条规则：“每次完成一个子任务后，更新 progress.md，说明你做了什么、测试结果如何、下一步计划。” 同时，在 AGENTS.md 里让代理开始任务前先读这些文件。初次配置时可能会觉得繁琐，但坚持两三周之后，你会明显感觉到代理的“记忆”越来越靠谱，即使是隔了几天再继续同一个功能，它也能无缝衔接。

4. Java 项目实战：从需求到提交的完整流程

4.1 准备一个最小的 Java 工程

听到“superpowers java”这个热搜词的时候，我就知道很多人是想把技能集用在 Java 后端项目上。Java 项目因为编译、测试链路长，AI 代理如果没有技能约束，很容易在“生成代码”这一步就放飞自我，从来不跑测试。我这里用一个最小的 Maven 项目做演示，目标是实现一个简单的 Calculator 类，包含 add 和 divide 两个方法，并且要让代理严格按照 TDD 流程完成。

先创建项目骨架：

mvn archetype:generate -DgroupId=com.example -DartifactId=calc -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

进入项目目录，确保mvn test能跑通初始状态。这一步很重要，因为 TDD 的起点是“测试能跑、且能看到失败信息”，如果初始测试框架本身就是坏的，后面代理很容易把环境问题误判成业务问题。

4.2 在 Codex 中触发 TDD 技能

项目准备好之后，我在 Codex 会话里输入：

@tdd 请在 Calculator 类中实现 add 方法，要求先写失败测试，运行测试确认失败，再写最小实现，最后确认测试通过。每一步都要给出你在做什么、以及测试结果。

注意，我特意在指令里写了“@tdd”这个触发词，这对应技能文件中的触发条件。实际上，Superpowers 并不是一个已经装好在 Codex 里的插件，它的本质是“让代理按照 AGENTS.md 中描述的 tdd 技能去执行”，所以你在提示中显式点名技能名，能提高命中率。如果代理还是没反应，我会补一句：“你可以在你的技能列表里找到 tdd 技能的定义，按照里面的步骤来。”

4.3 会话执行实录：步骤拆解与产物说明

实际执行时，代理的第一步是生成测试文件。它创建了 CalculatorTest，里面先写了 add 方法的测试用例：断言 Calculator.add(2, 3) 等于 5。然后它运行mvn test，测试结果是失败的——因为 Calculator 类还没有 add 方法，编译都过不了。这一步很关键，它确认了“红”的状态。

接下来代理进入实现阶段，它给 Calculator 增加了 add 方法，仅仅一行return a + b;。再运行mvn test，测试通过。到这里，一个最简 TDD 循环就闭环了。整个过程比我预想的要干净，没有出现代理直接甩出一个带 main 方法、甚至带命令行交互的完整程序这种无聊行为。这正是技能文件对步数的约束起的作用：它知道“最小实现”意味着最小，而不是“给你一个能跑的全部代码”。

4.4 Java 实战中的心得与注意事项

第一次跑通流程后，我又让它用同样的方式实现了 divide 方法。这次代理自动考虑了除零异常，在实现里抛出 IllegalArgumentException。我后来翻了它的 progress.md，发现它把“除法需要考虑除零”写进了 known_dependencies.md 里，这个细节让我觉得记忆文件确实在起作用。

但是有一个坑我得提醒你：Maven 项目的测试报告输出在 target/surefire-reports 目录下，迭代快的时候 target 目录会很大。我建议在项目的 .gitignore 里把 target 写进去，同时不要让代理去读 target 目录里的临时文件，而是统一通过mvn test的标准输出判断结果。否则代理可能在 target 目录里乱翻，浪费大量上下文，还容易被过期的测试报告误导。

4.5 技能组合：从 TDD 到重构再到终态提交

如果你觉得单个 TDD 流程太基础，可以把几个技能串起来用。我在做一个小模块时，会让代理遵循这样一个完整链路：先用 tdd 技能把功能点逐个实现；然后触发 refactoring 技能，把重复的逻辑提取成私有方法；再触发 code-review 技能，让它站在审查者角度检查自己的代码；最后把 progress.md 更新到“功能已完成，等待提交”。这一个流程走完，从代码质量到过程记录都齐了，最后一个 commit 基本不用我再大改。

当然，技能组合需要写好触发顺序和边界条件。在 AGENTS.md 里我加了一段类似的话：“当用户提出完整功能需求时，默认启动工作流：需求理解→tdd→重构→review→更新记忆。” 代理看到这个全局规则后，处理任务的思路就会明显结构化。如果有些任务不需要全流程，我会在指令中明确写“跳过特定技能”，它也能够正确响应。

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

5.1 技能没加载：代理不认 AGENTS.md

这个是最常见的问题，表现是技能文件明明已经复制过去了，但代理就是不按照文件里的步骤执行。我通常按这个顺序排查：先确认 AGENTS.md 是不是放在 Codex CLI 实际读取的路径上，而不是放在你心里以为的路径上；再确认文件名大小写完全一致；然后重启 Codex 会话，因为有些版本在会话开始时才加载配置，中途追加的 AGENTS.md 不会被重新读取。如果都不行，就在提示里显式写“请先读取 AGENTS.md”，强制触发。

5.2 代理不读记忆文件：每次会话都像失忆

Superpowers 的记忆文件是静态的，代理不会自动去读，除非 AGENTS.md 里有明确指令。我的解法是在 AGENTS.md 开头写一条硬性规则：“每次会话开始，先读取 .codex/progress.md 和 .codex/known_dependencies.md，如果存在，用它们作为上下文背景。” 同时，在对话里可以直接说“根据 progress.md 继续”，代理一般就能正确加载。如果还是不行，说明你用的 Codex CLI 版本可能没有把自定义指令注入权限放开，需要检查配置。

5.3 代理陷入无限循环或越权操作

AI 代理在 TDD 循环里偶尔会陷入“测试不过-改代码-再测试-再改”的无限循环，浪费大量上下文。技能文件里一定要设置退出条件，比如“同一处修改尝试三次仍未通过测试，停下来向用户报告”。我更推荐在 AGENTS.md 里加一句“在执行任何可能影响大量文件的步骤之前，先列出改动清单，让用户确认”。这样虽然多了一次交互，但能避免代理在无人看管时把项目改得面目全非。

如果代理已经陷入死循环，最快的紧急停止方式是 Ctrl+C 中断会话，再重新开一个会话，并让它先读取 progress.md，从最近一次确认过的节点继续。永远不要在一个已经乱掉的会话里嗑到底，上下文污染会让错误不断放大。

5.4 版本兼容与依赖冲突问题速查

我把这段时间遇到的环境类问题整理成了一个小表格，方便你们排查：

这张表看起来简单，但每一条都来自真实的翻车经历。最让我印象深刻的是第二次配置时，代理能说出全部技能名，但执行时全部忽略，最后发现是因为我同时放了全局和项目两个 AGENTS.md，项目级的定义把全局的覆盖掉了，而且写入的内容格式还是旧版。所以如果你用全局配置，建议在项目里就不要放同名的 AGENTS.md，或者明确让项目级文件只做增量补充。

最后再分享一个小建议：无论你怎么折腾 Superpowers，都不要把它当成“装完就完事”的插件。真正重要的是那些技能文件里写的内容，它们本质上是一份份工程思维模板。我一般会根据自己团队的项目类型，把 tdd.md 里“运行测试”的具体命令从 mvn test 改成项目实际的命令，把 debugging.md 里的日志路径也改成真实路径。技能和项目贴合得越紧，代理的表现就越接近一个靠谱的同事。

我个人使用下来最大的体会是：Superpowers 不是一个魔法开关，而是一套让你和 AI 代理对齐工作方式的“协议”。每次让它动手之前，多问一句“你打算按哪套技能、先从哪一步开始”，比任何模型参数都管用。这套流程我用了三周，代码合入速度明显提升，Review 时的争论也少了很多。希望这篇实战笔记能帮你少踩几个我已经踩过的坑。