企业官网建设流程全解析

1. 在给 Codex 装上 superpowers 之前，我的编码代理总是“金鱼记忆”

我大概在两个月前开始频繁把日常编码任务交给 Codex、Claude Code 这类命令行编码代理。一开始感觉挺惊艳的——你给它一句“帮我在这个模块里加个缓存”，它噼里啪啦就把代码写完了。但这种惊艳撑不过一个下午。第二个任务开始，它忘了项目里已经有一个 CacheManager；第三个任务，它完全无视了团队约定好的错误码规范；到第五个任务，我发现自己不是在写代码，而是在一遍又一遍地“重新介绍项目”。每个新会话都像是第一次见面，上次所有的决策、取舍、踩过的坑，全部清零。

这种体验在我第一次接触 superpowers 这个概念时，一下就点醒了：问题不在于模型不够聪明，而在于我们只给了它一张嘴，却没给它一套可重复执行的“工作手册”。superpowers 与其说是一个具体工具，不如说是一套运行在编码代理之上的技能增强体系。它目前最流行的形态是 Claude Code 的插件生态，但同一套理念被不少 Codex 用户移植和改造成自己的技能包。核心做法并不玄学：把项目里的常见工作流——需求拆解、方案设计、计划编写、任务执行、问题排查、复盘总结——逐一固化成结构化的“技能文件”，代理启动时读到这些文件，就会按照里面写死的流程去思考、去追问、去行动，而不是靠模型当场的“灵光一现”。

这篇文章我会把这些技能文件的组织原理、安装接入步骤、真实项目里怎么用、以及哪些地方容易翻车都讲一遍。适合的人群很明确：正在用 Codex、Claude Code 这类编码代理做真实交付，但受够了“每次对话都要从头解释项目”的开发者；以及那些觉得“AI 写代码很爽但项目一大了就失控”的人。

提示：本文描述的是社区里通用度最高的一套做法。不同版本、不同代理的工具名称和路径可能略有差异，关键在于理解背后的机制，而不必死记某条命令。

2. 别让 AI 靠临时演技：技能文件如何把一次性对话变成可复制流程

要说清楚 superpowers 为什么有效，得先理解编码代理平时是怎么工作的。你给它一段话，它根据上下文里的 prompt 和项目代码生成下一段话。这个过程本质上是一次性的即兴输出，模型不会在执行中途“退一步想想”，更不会在下一次会话里主动回忆起上次的结论。

2.1 普通 prompt 为什么不稳定

大模型生成的本质是概率采样。也就是说，同一个问题换个问法、换个上下文顺序，它给出的步骤可能完全不同。写一个简单的函数时，这种随机性无伤大雅；但在多文件、多模块的项目里，一次“自由发挥”的下笔，可能就是一次没有必要的重构，或者一次对既有约定的破坏。这就像组里来了个脑子很好但完全不看文档的实习生，每次让他干活，都得从头跟他交代一遍项目规范，而且他每次还会发挥出不同的新想法。

superpowers 的核心组织单元叫技能（skill），它的实体就是一个 markdown 文件。它把“怎么做”这件事变成了一条路径固定的 SOP，降低模型临时发挥带来的方差。你不需要依赖模型“恰好记得”某个流程，而是直接把流程喂到它面前，让它照着做。

2.2 技能文件的目录结构

一个规范的技能包通常长这样：

skill-name/ ├── SKILL.md # 定义技能触发条件、执行步骤 ├── scripts/ # 可选的辅助脚本，代理可以调用 └── references/ # 附加参考文档，按需加载

如果把普通提示词比喻成“让一位新来的实习生凭感觉做一道菜”，那技能文件就是后厨贴在墙上的标准化流程卡：原材料怎么预处理、火候怎么控制、出锅前要检查哪几个点，全部写得清清楚楚。代理在合适的场景下读到这份文件，会按里面的流程逐步执行，而不是自由发挥。references 目录则是用来存放那些“不一定每次都需要、但用到时可以查”的详细资料，避免主文件过长占用上下文。

2.3 一个最小技能文件长什么样

一个典型的技能文件，从 frontmatter 到正文都有明确约定。比如一个最简单的“计划编写”技能，核心部分长这样：

--- name: planning description: 在开始写代码之前，把目标拆解成可执行的步骤，并生成计划文档 --- ## 触发条件 当用户提出一个需要多步操作才能完成的功能需求时，使用本技能。 ## 执行步骤 1. 向用户确认最终目标和不做什么（明确边界） 2. 把目标拆成 3~8 个可独立验证的子任务 3. 为每个子任务标注输入、输出、验证方式 4. 将完整计划写入 plan.md，并提交一次 git commit 5. 等待用户确认后再进入执行

看起来平平无奇，但它带来的改变是根本性的：代理不再凭模型权重里“大概像那么回事”的经验直接写代码，而是先完成了一个显式的规划动作。这个动作本身就会消耗一些 token，却极大地提高了最终代码的稳定性。我见过很多开发者觉得“让 AI 写个计划多此一举”，实际跑过两个大需求之后，你就会发现，省下的是后期推倒重来的时间。

2.4 为什么流程比模型更可靠

我自己的理解是：模型的智力水平是波动的，平均水平可能很高，但具体到某一次调用，它会受上下文长度、任务复杂度、甚至是上一段输出格式的影响。而技能文件是一种外部记忆和外部约束，它把“怎么做”从模型的即兴发挥里抽离出来，变成了确定性的流程。

这和航空业里的检查清单逻辑是一样的。再厉害的飞行员也不能保证自己在高压下记得所有步骤，但一张 checklist 能保证。编码代理再聪明，也没有理由不用同样的方法保证交付质量。实际用下来，装了 superpowers 技能包之后，代理问问题的数量明显变多，但是后期返工量下降了，整体效率反而是提升的。这种“先慢后快”的节奏，恰好是真实工程里最健康的交付节奏。

3. 两种主流接入方式：Claude Code 插件路径与 Codex 技能目录路径

很多人问我在 Codex 里怎么装 superpowers。这个问题的答案其实取决于你用的是哪个代理。这里我把最常见的两种环境分别说一下。

3.1 在 Claude Code 里安装插件版本

如果你是 Claude Code 用户，最省事的办法是直接装插件。CLI 里执行：

/plugin install superpowers

或者手动把仓库 clone 到本地：

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

装完之后，在对话里输入/plugin就能看到已加载的技能列表。需要注意的是，插件和技能文件是两层概念：插件负责分发和更新，技能文件才是真正被代理读取和执行的内容。它们默认放在：

~/.claude/skills/

如果没找到这个目录，可能是版本比较新，路径变成了~/.config/claude/skills/。两者只需要有一个存在。插件的好处是后续更新方便，但如果你只想在某个特定项目里用，直接在项目里维护技能目录反而更灵活。

3.2 在 Codex 里复用同一套技能文件

OpenAI Codex 目前没有完全等价的“插件市场”，但社区里最常见的做法是直接复用量技能文件。你只需要把技能目录放到 Codex 能读到的地方，通常是项目根目录下的.claude/skills/或~/.codex/skills/，并在系统提示词里加一句话：“项目根目录下的技能文件是标准操作流程，执行任务前先阅读相关技能。”

我没有用“完全等价”这个词，因为两边对技能文件的加载机制确实有细微差别——比如某些代理认 frontmatter，某些只认一级标题。动手配置之前建议先在一个临时目录里放一个最小技能文件，让代理复述出来，确认它真的读到了，再大规模铺开。我见过不少人在 Codex 里折腾半天没生效，最后发现是文件路径里多了个不必要的嵌套目录。

3.3 装完后的三分钟自检

装完别急着开干，跑一遍自检能省下后面很多排查时间：

# 列出当前已安装的技能 claude plugin list # 查看技能目录结构 find ~/.claude/skills -maxdepth 2 -name SKILL.md

然后用一个最小任务验证代理是否真的按技能行事，比如问它“请用 planning 技能帮我规划一个登录功能”。如果它开始追问需求边界、生成计划文档，说明技能链路已经生效；如果它直接开始写代码，那就要检查技能文件是否放在正确的位置，或者系统提示词里有没有明确要求它去读取技能。这一步十分钟不到，却能避免后面“用了一个星期才发现代理根本没加载技能”的尴尬。

4. 三十分钟手写一个小技能：从零给代理加一种“超能力”

安装现成的技能包只是第一步。真正让 superpowers 产生巨大价值的，是你能根据自己项目的特殊性，手写技能文件。这个过程不复杂，我通常在三十分钟内搞定一个基础技能。

4.1 先定触发场景，再写正文

写技能文件最重要的不是格式，而是先回答三个问题：

• 这个技能解决什么场景下的什么问题？
• 代理在什么时机应该读取它？
• 执行完需要产出什么可验证的结果？

比如我想让代理在修改数据库表结构时，自动检查是否需要同步更新迁移脚本。这个需求的触发场景非常明确：“当任务涉及 DDL 或 schema 变更时”。产出也很明确：“迁移脚本更新 + 变更说明”。有了这两点，技能文件的主体框架就出来了。很多初学者习惯一上来就堆细节，结果写出来的技能文件又长又没重点，代理根本不知道什么时候该用它。

4.2 编写 SKILL.md 的实操细节

一个手动编写的技能文件，正文结构我建议按“触发条件 - 前置检查 - 执行步骤 - 产出验证”四段来写。下面是一个真实的简化版本：

--- name: schema-change-check description: 涉及数据库结构变更时，检查并更新迁移脚本 --- ## 触发条件 用户要求修改 entity、mapper、DDL 文件，或明确提出变更数据库结构。 ## 前置检查 1. 定位项目中迁移脚本所在目录（如 db/migration/） 2. 确认当前最新迁移脚本的版本号 ## 执行步骤 1. 对比修改前后的表结构差异 2. 生成新的迁移脚本，版本号按递增规则命名 3. 在迁移脚本中注明变更原因，并关联需求编号 4. 更新 README 中的 schema 版本说明 ## 产出验证 - 新迁移脚本所在的目录列表已更新 - 本地执行迁移命令可通过 - 如果未修改任何 schema，明确告知用户“本次变更不需要迁移脚本”

这段文字没有任何玄机，它本质上就是把一个熟练开发者的检查习惯写成了代理能读的“职务说明书”。注意这里的关键是“产出验证”段落——代理是概率模型，如果没有明确的验证标准，它很容易自己说服自己“差不多完成了”。

4.3 scripts 目录与辅助脚本

如果技能需要执行一些固定的验证逻辑，可以在scripts/目录下放一段可执行脚本。比如上面这个数据库技能，我可以放一个check_migration.sh，让代理在执行迁移前先跑脚本校验版本号连续性：

#!/bin/bash # 检查迁移脚本版本号是否连续 last=0 for f in db/migration/V*.sql; do v=$(basename "$f" | sed -E 's/V([0-9]+)_.*/\1/') if [ "$((v - last))" -ne 1 ]; then echo "警告：迁移版本 $v 与前一个版本 $last 不连续" exit 1 fi last=$v done echo "迁移版本号连续，检查通过"

脚本不需要写得多精巧，它的目的是把“代理不擅长但 shell 擅长”的确定性工作交给 shell，把“需要判断但代理擅长”的决策工作留给模型。脚本越多，代理的自由度越低，但同时出错率也越低。我一般是把关键校验逻辑尽量下沉到脚本里，这样即使代理某次发挥失常，脚本也能把它拦回来。

4.4 测试技能：用一页纸用例验证行为

技能写完不是结束，我习惯用三个测试用例去验证：

1. 触发场景：让代理执行一个明确触发该技能的任务，看它是否读取了 SKILL.md。
2. 边缘场景：让代理执行一个不应触发该技能的任务，看它是否会误用。
3. 破坏性验证：删除技能文件或改错路径，确认代理没有按旧行为继续。

这三个用例跑一遍，基本能确定这个技能不会被误触发，也不会形同虚设。测试的时候最好把代理的输出日志打开，观察它是在哪一步读到了技能文件，哪一步开始偏离，方便定位问题。

5. 真正值钱的工作流闭环：brainstorm → plan → execute

技能本身的价值是放在流程里体现的。我建议所有刚接触 superpowers 的人，先跑通一套最基础的闭环：头脑风暴（brainstorming）、计划（planning）、执行（executing）。这三个技能几乎覆盖了 80% 的日常开发场景。

5.1 Brainstorming：先发散后收敛，而不是让 AI 直接给答案

没有 brainstorming 技能时，我问代理“这个功能怎么做”，它会立刻给我一个方案，一副非常笃定的样子。但实际上它没有评估过别的可能性，也没有追问过我真正的约束。这就像一个刚入职的同事，从没问过这个模块的历史包袱、性能要求、兼容性约束，就直接拍脑袋说“用 Redis 缓存吧”。

有了 brainstorming 技能之后，对话模式变成了这样：代理提出几个候选方案，会让你说出环境约束、性能期待、未来可能的扩展方向，最后才收敛到推荐方案。这个过程看着“啰嗦”，却让后续的 plan 和执行建立在真实约束上，而不是模型脑补的沙地上。我现在已经习惯了这种“被追问”的感觉，甚至会主动把约束条件提前抛给它，节省来回轮次。

5.2 Planning：把目标转成可验证的任务序列

Brainstorm 之后进入 planning。这个技能的作用是把模糊的目标翻译成一份可执行、可验证的步骤清单。我的习惯是要求代理把计划写进docs/plan.md，每个任务都带上一句话描述“怎么算做完”。比如：

## 任务 2：实现 Token 缓存 - 输入：Redis 连接配置 - 动作：新增 CacheManager，提供 get/set 接口 - 验证：运行 `mvn test -Dtest=CacheManagerTest` 通过 - 提交：完成后创建 commit，消息前缀 feat(cache)

这么做的好处是，任何一个后续会话都可以通过阅读docs/plan.md恢复上下文。项目团队里哪怕换个人来接着做，也能看懂进度。我把这个文件当成整个工作流的“地面 truth”，一旦代理在执行阶段产生分歧，就回到这个文件来对账。

5.3 Executing：按计划推进，而不是想到哪写到哪

执行阶段是 superpowers 真正展现威力的地方。它会把计划里的任务逐个取出来，完成一个打一个勾，并且每完成一个里程碑就做一次 git commit。这相当于把代理的整个工作过程变成了可回放、可回滚的状态机。

我遇到过一次很典型的状况：代理在执行到第三个任务时，突然产生了一个“更好的想法”，想要绕开计划重写方案。如果是在没有技能约束的情况下，它大概率就直接动手了。但因为 executing 技能里写着“发现新方案时，先回到 planning 重新制定计划，获得用户的确认后再继续”，它停下来了，并且主动跟我说明偏离计划的原因。那一刻我确实觉得，它像是一个有职业素养的工程师，而不是一个灵感型写手。

5.4 把检查点当成安全网，让 git 成为代理的记忆存档

在整个闭环里，我强烈建议把 git commit 当作不可省略的一环。代理每完成一个可验证的里程碑，就提交一次。这个习惯最直接的价值是：当你发现代理在某一步偏离了方向，可以干净利落地回退到上一个检查点，而不是在一堆未提交的改动里手工还原文件。

同时，commit message 也建议按约定写清楚上下文，比如feat(cache): 完成 Token 缓存接口，这样即使过了几天，回看 git log 也能明白代理当时做了什么，这比让代理用自然语言汇报更可靠。git log 就是代理行动的“审计日志”，出了问题翻起来非常直观。

6. Java 与大型工程里的实战：上下文预算、验证策略与 session log

superpowers 在小项目里是“锦上添花”，在 Java 这类大型工程里才是真的“雪中送炭”。因为没有外部流程约束时，代理很容易在庞大的代码库里迷失：它会忘记接口规范、找不到配置文件、执行缓慢的测试却不自知。

6.1 针对 Java 工程调整验证策略

Java 项目的构建通常比脚本语言慢得多，一次mvn package可能要几分钟。默认的执行类技能里如果写着“每次改动后运行测试”，在 Java 项目里就会变得异常痛苦。我的做法是调整技能文件，把验证方式改成：

验证策略: - 修改单个类后: 运行 `mvn -q compile` - 修改接口或重构时: 运行 `mvn test -DskipTests=false -Dtest=涉及模块` - 完整回归: 仅在计划阶段明确要求时执行

这个细节看起来很小，但直接影响代理是否愿意频繁自检。验证步骤越轻量，代理越倾向于每改一步就验证一步，出错成本越低。如果每次改动都要求跑完整套测试，代理为了省时间就会少跑测试，最终反而是整体质量下降。

6.2 限制上下文，而不是无限堆技能

superpowers 虽然好用，但每个技能文件在被加载时都会占用上下文。我在一个中型 Spring Boot 项目里装过十多个技能，结果发现代理经常“读不完卡”、“读了后面的忘了前面的”，整体表现反而下降。后来我把技能精简到五个核心项：brainstorming、planning、executing、debugging、retrospective，项目表现立刻稳定下来。

经验数值是：技能文件总大小尽量控制在 30KB 以内，且单个技能文件的正文不要超过 200 行。技能是 SOP，不是百科全书；太长的技能文件最终会被代理的上下文窗口吞掉。如果你确实有很多规范要写，把它拆成多个小技能，按场景触发，而不是堆在一个大文件里。

6.3 运行记录：让下一次会话知道上一次发生了什么

对于需要多天完成的大型任务，运行记录（session log）几乎是必需品。我会在项目的docs/session_logs/目录下维护一个简单的日志文件，约定代理每次会话结束时追加一段：

## 2025-03-12 会话记录 - 当前任务：实现订单导出功能 - 已完成：Excel 工具类、接口定义 - 阻塞项：等待产品确认导出字段 - 下一步：实现异步导出任务

这个文件比任何记忆机制都可靠。下次启动会话时，只要让代理先读docs/session_logs/里最新的日志，它就能无缝接续上下文。这个做法的本质是用文件系统模拟“长期记忆”，在真实工程里比任何模型内记忆都扎实。哪怕你换了代理工具，换了个模型，只要这个文件还在，项目上下文就能无损迁移。

7. 我踩过的坑、适用边界和最终取舍

经过几个项目的折腾，我的态度从最初的“神器”变成了“很有用的工程习惯”。这里把最常踩的坑和适用边界摊开来讲。

7.1 最典型的坑：代理假装读了技能，但实际没按流程走

有两种典型表现：一种是技能文件放置路径不对，代理根本没读到，但因为你的提问里带有“planning”之类的关键词，它会顺着话头表演出“我按流程在做”；另一种是技能文件太长，代理读了一半就忘了后半段。排查方法很简单：在技能文件第一行加一句“如果你真的读到了这个文件，请在第一轮回复里说你准备好了”，然后观察代理是否照做。这个办法非常原始，但比任何复杂的日志分析都直接。

7.2 技能冲突：多个技能都想管同一件事

我之前同时装了通用执行技能和专门针对 Java 的验证技能，两个文件都写着“如何验证代码”。结果代理有时候执行这个，有时候执行那个，行为不可预测。后来养成了一个习惯：每个“领域”只保留一份技能文件，并且把冲突内容做合并，而不是叠加。技能文件之间也要有清晰的触发条件，避免职责重叠。现在我会在写新技能之前，先全局搜索一下有没有已有技能覆盖了相似场景。

7.3 使用过程中常见的故障与排查速查表

这里我把实践里见过的问题整理成一张表，方便你遇到现象时直接对照排查：

这张表是我自己排查问题时的起点。大多数问题最终都回到同一个根源：技能文件没有用流程约束住模型的即兴行为。

7.4 什么时候不该用 superpowers

坦白说，有些场景不适合用这套流程。比如一次性脚本、临时 debug 一个简单 bug、或者只是快速验证某个 API 能不能用。这些场景下，多轮的 brainstorming 和 planning 反而会拖慢速度。价值的核心在于“可复用、可追溯、需要稳定交付”的任务；纯粹的即兴探索，直接对话反而更高效。

我自己现在的使用原则是：探索用裸对话，交付用 superpowers。探索阶段让代理自由发挥，跑通了再切到 superpowers 流程，把方案固化、计划化、执行化。这套分工方式让我既享受了 AI 的创造力，又保住了工程交付需要的确定性。

7.5 顺着这个思路继续扩展

技能文件不是什么神秘格式，它本质上就是 markdown。所以它天然支持你自定义。我看到有些团队把代码评审规范、数据库迁移流程、发布检查单都写成了技能文件，让代理在对应环节自动加载。这个玩法没有上限，但它依然遵循同一个底层逻辑：先想清楚你希望代理以什么样的标准做这件事，再把标准写成文件，最后让代理去读文件、执行文件。不是代理有了超能力，是你把超能力变成了文字。