企业官网建设流程全解析

1. 从“能聊天”到“能干活”：superpowers 到底补上了哪块短板

1.1 我的真实场景：Codex CLI 写代码时的“金鱼记忆”

先说个我最近经常遇到的场景。我用 Codex CLI 跑一个 Python 后端项目，任务是把用户模块的鉴权逻辑从 JWT 改成 OAuth2。第一轮对话它表现很好，刷刷刷给我列了一个改造计划，还主动提醒了 refresh token 的刷新窗口问题。但聊到第三轮，问题开始出现：它忘了项目里那个auth_service.py其实已经把 token 校验逻辑封装好了，又开始建议我“新建一个工具函数”。第六轮的时候，它居然连需求本身都记岔了，开始给我设计多租户权限模型——我根本没提过这个东西。

这不是 Codex 笨，而是它的工作记忆就那么长，上下文窗口再大，被对话历史、代码片段、报错信息一冲，早期的关键约束早就被挤到注意力边缘了。后来我试过几种补救方法：每次对话开头把需求重新粘贴一遍、用一个CONTEXT.md文件存全局约定、甚至写了个脚本把项目结构树自动灌进 prompt。有点用，但都有同一个毛病——这些信息是“死”的，模型只有在恰好 “想起来” 的时候才会去翻，而一旦它进入了“顺着惯性一路写下去”的状态，这些文件根本拦不住它跑偏。

1.2 为什么普通 prompt 指令不够用

很多人觉得，给 AI 助手讲清楚需求就等于能干活，但实际上“讲清楚需求”和“让它持续按正确方式干活”是两码事。普通 prompt 是线性的一次性指令：你说了，它听了，然后就没有然后了。真正复杂的任务是分阶段的，每个阶段有不同的目标、不同的产出物、不同的验收标准，而且阶段之间还有依赖关系。指望用一段 prompt 把这些全部规定死，既不现实，也不可持续。

我接触了superpowers这个开源项目之后，才慢慢意识到问题出在哪。我的做法一直是“给模型更多指令”，而它需要的其实是“给模型一套可调用的技能库”。指令是死的，技能是活的。技能不只是一个命令文本，它自带触发条件、执行步骤、暂停检查点、完成标准，甚至可以让模型在关键节点停下来问我要确认，而不是自顾自地往下写。

1.3 superpowers 是什么：一句话解释

superpowers是开发者社区里一个比较新的开源项目，目标很直接：把通用型 AI 编码助手（比如 Codex CLI、Claude Code 这类终端里的代理工具）变成“具备专业技能的员工”。它不是模型，不是框架，也不是什么 IDE 插件，它是一整套可以持续积累的技能文件组织方案。

你可以把它理解成给 AI 助手写的一整套岗位手册。普通做法是你每次跟它说“你是个资深 Python 工程师，请按照 PEP8 规范写代码”，superpowers 的做法是，把“资深工程师”拆成一个个具体技能，比如“从 Jira 需求生成后端代码”“在改动前先搜索所有引用点”“输出代码前先写测试用例”“遇到 API 变更时先检查调用方”……每个技能都有独立文件，模型根据当前任务自动匹配技能，并且按照技能里写的步骤来执行。

我在实际项目里跑了大概三周，最大的感受是：AI 助手还是那个 AI 助手，但它的“行为模式”变得非常有章法，该验证的时候验证，该汇报的时候汇报，项目上下文丢失的问题基本被化解了。这篇文章就把我这几周的安装、使用、自研技能、踩坑经验完整整理出来，给想入坑的朋友一个可复现的参考。

2. 技能文件的组织方式：SKILL.md、技能库和命令系统是怎么协同的

2.1 核心单元：SKILL.md 文件长什么样

如果只记住一件事，那就记住SKILL.md。这是 superpowers 体系的原子单位，每个技能就是一个目录，目录里必须有一个SKILL.md文件，外加若干辅助模板和示例文件。这个文件决定了 AI 助手在什么场景下启用该技能、按什么步骤执行、产出物是什么。

一个标准的 SKILL.md 长这样（我用一个简化示例说明）：

--- name: review_changes description: 在提交代码前审查改动，检查是否有调试残留、日志泄漏、边界条件遗漏。 when_to_use: 当一次代码修改涉及多个文件，或者被要求“检查一下改动”时 version: 1.0.0 ---

前半部分 YAML 叫 frontmatter，是给“调度系统”看的元信息；后半部分 Markdown 正文，是给模型看的执行指南。正文部分写得越具体，模型执行得就越稳定。我通常会在正文里包含几个固定段落：

• 执行步骤：按顺序列出要做的事，比如先git diff看改动，再搜索调试残留，再核对测试；
• 停止条件：什么情况下必须停下来询问人类，而不是自作主张继续；
• 验收标准：做完后拿什么清单自查，每条都打勾才算完成；
• 反例清单：明确列出禁止做的事，比如“不要在审查过程中直接修改代码”。

这个设计之所以有效，是因为它对模型的认知负担很友好。模型不需要靠“推断”理解你的工作习惯，它只需要按图索骥执行步骤，这种“显式胜过隐式”的思路在 AI 编码场景下价值极高。

2.2 技能库的目录结构：从仓库到本地

superpowers 仓库本身维护了一个庞大的技能库，我 clone 下来之后发现它的目录结构很有意思：

superpowers/ ├── SKILL.md # 元技能：教模型如何使用技能库 ├── skills/ # 所有内置技能 │ ├── boot/ # 任务前期准备类 │ ├── planning/ # 计划与拆解类 │ ├── implementation/ # 编码实施类 │ ├── testing/ # 测试与验证类 │ ├── review/ # 审查与复盘类 │ └── project_management/# 项目管理类 ├── agents/ # 子代理定义 ├── scripts/ # 安装/同步脚本 └── templates/ # 新技能的模板

安装脚本会把整个 skills 目录同步到你的全局技能目录（比如 Claude Code 的~/.claude/skills）或者项目局部目录（.claude/skills），具体取决于你的使用方式。这样做的好处是，技能库跟项目代码是解耦的，你在 A 项目里积累的技能可以无缝带到 B 项目。

2.3 触发机制与驱动命令：技能不是“查找表”，是“事件驱动”

我一开始犯过一个错误：以为技能就是给模型的多余背景知识，塞进去让它读就行。其实不是。superpowers 里的技能是按需触发的，模型先读 frontmatter 的when_to_use描述，判断当前任务是否命中某个技能，命中才读正文。这意味着技能的 description 相当于一个“路由表”，写得好不好，直接决定模型能不能在正确的时候想起用它。

除此之外，superpowers 还引入了“驱动命令”的概念。它不是传统聊天界面里的斜杠命令，而是要求模型在执行关键节点时主动做一次状态汇报的机制。举个我常用的例子：技能里会写“每完成一个子任务后，执行一次项目健康检查，确认当前改动没有破坏已有测试”。模型执行到这一步，就会暂停下来运行测试、汇总结果，然后告诉我“当前状态如何，是否继续”。这个机制让我从一个全程盯梢的监工，变成了只在关键节点把关的负责人。

提示：如果你对“AI 编程”的理解还停留在“一次性聊天生成代码”，那 superpowers 的思维方式会有点颠覆。它不是让你问得更好，而是让 AI 在干活过程中有自己的 SOP。

3. 环境准备与首次安装：从 clone 仓库到跑通第一个技能

3.1 支持哪些助手，先确认你的版本

动手之前先确认一个事：你用的 AI 编码助手支持技能文件机制吗？superpowers 目前主要面向两类终端环境：Claude Code 和 Codex CLI。Claude Code 原生支持SKILL.md技能目录，安装最简单；Codex CLI 相对新一点，需要通过 AGENTS.md 把技能入口挂载进去。

我自己的主力环境是 Codex CLI（配合 GPT-5 系列模型），所以下面以这个为主线讲，同时会带上 Claude Code 的差异点。

虽然官方一直在更新支持矩阵，但我的建议很简单：不管用哪个助手，先跑通安装脚本，再用一个最小技能验证效果，再上真实项目。

3.2 安装脚本到底干了什么

安装过程非常顺，基本三步：

git clone https://github.com/obra/superpowers.git cd superpowers ./install.sh

脚本会做这几件事：

• 检测你机器上已安装的 AI 助手类型（Claude Code、Codex CLI、Android Studio 等）；
• 把整个skills/目录复制到对应助手的全局技能目录；
• 在全局配置里写入一条“启动引导技能”的规则，意思是每次新对话开始，模型会自动加载 superpowers 的元技能，从这一步开始它就知道“这套技能库存在，且可以随时调用”；
• 如果是 Codex CLI，还会额外生成一份AGENTS.md引用文件。

安装完成后，你可以自己验证一下：启动 Codex CLI，随便输入一句“你有技能库吗”，如果模型回复里提到了 superpowers 或者 SKILL.md，说明引导生效了。

3.3 Codex CLI 下的挂载细节

Codex CLI 原生不读~/.claude/skills，所以需要手工打通。官方脚本会自动处理，但我还是建议你理解背后的原理，因为后续排查问题会用到。

原理是这样的：Codex CLI 在工作目录下读取AGENTS.md文件作为项目级指令，superpowers 的安装流程会在AGENTS.md里追加一段话，大意是“项目内存在技能库，当你需要完成复杂任务时，先读取~/.claude/skills/boot/SKILL.md并按技能库规则执行”。

这一步很关键。如果你在某个子目录启动 Codex CLI，而AGENTS.md只在仓库根目录，那技能库就不会被自动加载。我建议你做一个软链接，把AGENTS.md放到~/全局，或者在项目的.codex/目录下再放一份引用。实测下来，这种“双保险”能避免很多“明明装了却感觉没用”的困惑。

3.4 第一次运行：让模型自己跑一个完整流程

安装完成不是终点，得让它真正用起来。我第一次的测试任务是“用 superpowers 调研当前项目的测试覆盖率并生成改进计划”，然后观察模型的思路变化。

第一个明显变化是：它没有直接回答“我建议做以下改进”，而是先调用了一个research技能，列出要检查的文件清单，然后用planning技能把任务拆成了“现状调研→问题清单→改进建议→实施顺序”四个阶段，每个阶段末尾问我“是否继续”。整个过程非常有节奏感，像是被一个资深项目助理带着走。从我的角度看，这是一种完全不同的 AI 协作体验——从“问一句答一句”变成“按流程推进，关键节点汇报”。

4. 深度使用实测：Codex CLI 场景下的效果与调优心得

4.1 实测一：生成完整业务模块，从需求到测试

我在一个真实需求上做了对比测试。需求描述是：给订单系统新增一个“批量退款”接口，要求支持部分金额退款、重复退款拦截、操作审计日志。

第一组测试用最朴素的对话方式：直接把需求粘贴给 Codex CLI，让它“实现这个功能”。结果它生成得挺快，但有两个问题：一是直接在一个新文件里写了全部逻辑，完全没有复用项目里已有的RefundValidator和AuditLogger；二是没考虑并发场景下的幂等性问题，重复请求会把一笔订单退两次。

第二组测试走 superpowers 的技能流程：我自己新建了一个batch_refund的临时技能目录，里面写了“先搜索项目内已有的退款相关类→复用现有组件→生成代码→检查幂等→写单元测试→汇总改动清单”这几步。执行结果对比明显，复用现有组件这点它记住了，幂等控制也主动用了数据库唯一索引来做。

两组测试的差异不在于模型聪明与否，而在于流程约束带来的稳定性。第一组的模型是“自由发挥模式”，第二组的模型是“按 SOP 作业模式”。对生产代码来说，我更愿意要稳定，哪怕慢一点。

4.2 实测二：重构旧代码时，技能链如何防止跑偏

另一个让我印象很深的场景是重构一个遗留的 Java 服务。这个服务有 8000 多行，散布着大量重复代码，很难一次看清全貌。以往这种重构最怕的就是模型改了 A 处逻辑，漏了 B 处依赖，然后编译器跳出来一堆错误。

superpowers 的refactoring技能给出的思路是“先画依赖地图再动手”。技能正文里要求模型在动手改代码之前，先执行三步：

1. 搜索所有引用目标方法的位置，列成清单；
2. 标注哪些是读写路径、哪些是事务边界；
3. 制定“安全重构顺序”，从底层方法开始改，而非从入口方法开始。

实测结果让我很惊喜，整个重构过程虽然比人工慢，但几乎没有出现“改爆依赖”的情况。每次改完一批方法，技能里的检查点会触发一次编译和测试，有问题当场回滚，而不是积累到最后一次爆掉。这种“小步快跑 + 频繁验证”的模式，是纯对话式 AI 很难自发做到的。

4.3 调优心得：给技能写 description 的技巧

跑了几个场景之后，我最大的感受是“技能好不好用，一半取决于 description 写得好不好”。description 决定了模型什么时候“想起”这个技能，如果写得过于泛化，模型会在不该用的时候调用它，浪费上下文；如果写得太窄，模型又会在该用的时候漏掉它。

我的经验有三个：

• 用触发场景描述，不要用功能描述。比如“当用户要求批量操作时”比“处理批量操作”更准确，前者是触发场景，后者是功能标签；
• 适当写反例。比如在写短信发送技能的 description 时，我加了“当用户只是想查看短信模板时不使用本技能”，这一步能显著降低误触发率；
• 保持 50~100 字左右，太短模型抓不住意图，太长模型注意力会被稀释。

另外一个小技巧：升级了模型大版本之后，最好重新检查一遍关键技能的描述。不同代际的模型对自然语言的理解偏好是有差异的，我遇到过同一个 description 在老模型上触发率 80%，新模型上触发率只有 40% 的情况，微调后恢复正常。

5. 动手编写自己的技能：从一个“周报聚合”技能看完整套路

5.1 需求拆解：这个技能要解决什么问题

前面讲了不少理论，这里来一次完整的自研技能实操。我的场景是团队代码项目的周报汇总工作：每周五要收集各个同事在 Git 提交记录、任务评论里留下的工作碎片，整理成一份有结构的周报。以前这是纯手工活，耗时二十分钟到半小时，而且容易漏东西。我决定用 superpowers 做一个“周报生成器”技能。

先拆解需求：技能输入来源是 Git 提交记录和项目里的一种轻量级任务追踪文件；输出是一份按“本周完成 / 进行中 / 阻塞项 / 下周计划”分类的结构化周报。关键难点在于“判断提交属于哪个分类”，这需要给模型一定的业务上下文。

5.2 frontmatter 怎么写：把触发条件写对

新建技能目录weekly_report/，里面放SKILL.md。frontmatter 我写成这样：

--- name: generate_weekly_report description: 当用户要求生成周报、汇总本周工作或整理项目进展时使用 when_to_use: 用户提到“周报/本周进展/汇总本周”等关键词，且当前目录是一个 Git 仓库 version: 1.0.0 ---

注意when_to_use我用了“关键词 + 场景”双重限定，这样既不会在普通闲聊时误触发，也不会在“帮我整理这周都干了啥”这种模糊请求下漏掉。如果你管理的仓库有固定命名规律（比如提交信息带feat:、fix:前缀），建议也在描述里写上，模型会把前缀映射到周报分类。

5.3 正文怎么组织：步骤、检查点、完成标准

SKILL.md 的正文部分，我分成了四个小节，每一节对应一个执行阶段：

阶段一：收集

按时间范围运行git log --since=... --author=... --oneline，把所有提交记录汇总成列表。如果存在任务追踪文件，则解析出更新记录。

阶段二：分类

按提交前缀或关键词，把条目归入“功能开发”“缺陷修复”“重构优化”“文档与杂务”四个桶。分类依据写在技能正文里，比如“以 fix、bug、hotfix 开头归为缺陷修复类”。

阶段三：生成

基于分类结果生成周报 Markdown 文本，按模板格式输出。模板直接写在技能正文里，用块引用标出，模型会严格套用。

阶段四：确认

生成完成后，把周报以文件形式写到docs/weekly/YYYY-WW.md，然后提示我确认。最关键的是这里有一条硬性检查点：如果收集到的原始提交记录少于 5 条，必须停下来问我“是否扩大时间范围”，而不是自动生成一份空空如也的周报。

## 执行指南 ### 收集 - 运行 git log 获取过去 7 天的提交记录 - 检查 ./tasks 目录下的任务文件，提取 completed 字段为 done 的条目 ### 分类 - feat/feature → 功能开发 - fix/bug/hotfix → 缺陷修复 - refactor/chore/style → 重构与杂务 - docs/test → 文档与测试 ### 生成 按照模板输出： #### 本周完成 - ... #### 进行中 - ... #### 阻塞项 - ... #### 下周计划 - ... ### 检查点 - 如果提交记录少于 5 条，停止生成，询问用户是否扩大时间范围

写完之后，我自己测试了三轮：第一轮发现它把两个 fix 前缀的 commit 错分到“功能开发”了，原因是这两个提交的标题里带“增加”两个字，模型被标题语义带偏了。我随手在技能正文里加了一条反例：“注意：分类以提交前缀为准，不要根据标题中是否包含‘增加/优化’等词进行二次推断”，问题立刻消失。

5.4 测试与迭代：如何验证技能真的有效

技能写完不能直接扔进实战，我的做法是先准备一个测试仓库，造一批固定提交记录，然后用同一个技能跑三次，检查输出是否稳定。如果三次结果一致，再扔到真实项目里。真实项目跑一周之后，回头检查这一周的周报有没有漏项，漏了说明收集步骤不完整，补丁就好；分类错了说明分类规则不够明确，微调一下分类段落。

这个过程其实是把“调教 AI”变成了一种类似写自动化测试的工作流：技能就是函数，测试数据集就是用例集，每次优化技能都跑一遍回归测试，保证修好 A 场景时不破坏 B 场景。这种开发方式，是我觉得 superpowers 最值钱的地方。

6. 常见坑与绕行方案：我在使用中踩过的六个问题

6.1 技能太多导致上下文爆炸

这个坑我踩得很实在。技能库初次同步后，全局技能目录里有几十个技能，每个 SKILL.md 都不算短，如果模型在单次对话中把多个技能都读进去了，上下文占用会非常严重，还没开始写代码呢，先吃掉两三万 token。

绕行方案分两层。第一层，在启动引导里明确告诉模型“只有在任务命中when_to_use时才读取技能正文”，这一步官方文档有写，但需要验证你的模型严格遵循。第二层，自己裁剪技能库：把不常用的技能从全局目录移到一个archive_skills/文件夹里，让模型看不到，真需要时再手动放回来。我最后留下的常驻技能不超过 15 个，上下文压力小了很多。

6.2 旧版模型不认 frontmatter

我用过一个比较早期的模型，它对 YAML frontmatter 完全不敏感，把name、description直接当普通文本处理了，技能触发率奇低。排查了半天才发现是这个原因。

解决办法很简单，升级模型或换个新模型。如果你因为某种原因不能升级，那就在技能正文开头用自然语言写一句“当用户提到 XXX 时，你应该使用本技能来指导你的工作”，模型把它当正文读，触发率会有所回升。不过这只是权宜之计，长期用还是建议升级模型。

6.3 技能目录的加载顺序冲突

superpowers 默认会把技能安装到全局目录，但很多项目自己也有.claude/skills或.codex/skills的局部目录。两边都在的时候，有些助手优先读局部、有些读全局，还有的会两遍都读但局部覆盖全局。我遇到的情况是，我自定义了一个技能跟全局内置技能同名，结果模型总是加载全局版本，我的改动一直不生效。

处理方法很笨但很有效：把全局技能里同名的那一个改名或删除，确保只有一个匹配。如果你在多个项目间切换，建议给不同项目配不同的局部技能集，避免同名冲突。

6.4 技能递归调用自己

有个技能我在正文里写了“如果任务超出范围，可以调用本技能的进阶模式”——听起来高端，实际上模型走到这个分支后，会反复把“进阶模式”当成一个新需求，重新加载同一个技能，形成循环。最严重的一次，它在一个问题上连续跑了五轮，输出毫无进展，只消耗 token。

后来我在所有技能的结尾统一加了一句话：“本技能没有进阶模式，如果遇到无法处理的情况，请直接告知用户并停止。”这相当于给技能逻辑加了一个递归终止条件，非常管用。

6.5 中文环境下 description 的匹配问题

大部分内置技能的 description 是英文，而我在对话中习惯用中文提需求，这导致模型在“语义匹配”阶段经常判断失误：用户说“帮我把代码整理一下”，技能库里的描述写的是“Organize code files”，语义距离较远，模型可能就跳过技能直接自由发挥了。

我解决的办法是把我常用的十几个技能的 description 都补上了中文别名，比如在英文描述后面加“或当用户要求整理、重构、梳理代码时使用”。小改动，效果立竿见影。

6.6 版本升级后的格式变化

superpowers 迭代速度不算慢，有一次我拉新版本后发现技能目录结构变了，原来的一些技能名换了新名字，我自定义技能里引用的旧技能路径全部失效。这个坑没法完全避免，我的经验是：不要直接覆盖安装，先备份自定义技能目录，升级完跑一遍回归测试用例，确认核心技能输出效果没变，再删除旧版本。

另外，注意看官方仓库的 release notes，他们会在升级说明里标注破坏性变更，花五分钟扫一眼，能少踩很多坑。

最后再分享一个小技巧

如果你只能用一句话向别人介绍这套东西，我会说：superpowers 不是让 AI 变得更聪明，而是让它干活的方式变得有章法。我在实际使用中最受益的并不是开箱自带的那几十个技能，而是它教会了我一种“把 AI 当新同事来培训”的思路——每个技能就是一份入职培训文档，写清楚了，AI 就能稳定地按你的预期干活。

我最近在做的项目，已经把团队里几年积累的“隐性开发规范”逐个变成技能文件，比如“新功能必须带灰度开关”“改动数据库表结构前必须评估全量数据迁移”“发布前检查依赖安全公告”等等。这个积累过程很慢，但每写下一个技能，就相当于把团队的工程经验固化了一份，换了新人（或者 AI 换了模型）都能直接用。这种扩展方向，比单纯追求“写代码更快”可能更有长期价值。