企业官网建设流程全解析

先问个问题：你现在让AI写代码，是把它当成“代码生成器”，还是当成“结对程序员”？

我用Claude Code和Codex CLI折腾了快一年，最深的感受是：AI单点的代码能力早就够了，真正拉胯的是流程纪律。需求还没聊清楚它就开写，写完才发现方向错了；该写测试的时候它嫌麻烦直接给实现；修bug的时候东试一下西试一下，运气好碰对了，运气不好把别的模块搞挂。一直到我在GitHub上刷到obra/superpowers这个项目，才意识到问题不在模型，在于“没有给AI立规矩”。

superpowers是一套面向AI编码助手的“技能包”（skills collection），不是MCP服务，也不是某个普通IDE插件，而是一堆结构化的Markdown指令文件。它通过SKILL.md把“头脑风暴”“写规格说明”“测试驱动开发”“系统性调试”这些软件工程方法论固化下来，让AI在合适的场景自动调用对应的技能。这篇文章我会把它的核心机制、安装方式（包括Codex CLI安装superpowers、Trae环境接入）、六大核心技能的实际用法，以及我踩过的坑完整过一遍，适合正在用Claude Code、Codex CLI，或者想给AI编程工具加点“工程素养”的开发者。

1. Superpowers是什么：给AI编码助手装上“流程纪律”

1.1 为什么AI写代码总差一口气

先说个场景。你让AI“帮我写一个限流中间件”，它会怎么做？大概率是直接甩给你一个实现——可能用了guava的RateLimiter，也可能自己手写了一个令牌桶。代码能跑，但你问它“为什么选令牌桶而不是漏斗桶”“限流Key怎么设计的”“超限之后是直接拒绝还是排队等待”，它往往答不上来，或者答非所问。

这不是模型笨，而是提示词太“轻”了。你在对话里给出的信息量，根本不足以支撑它做出这些关键决策。它只能基于训练数据里的“最常见做法”猜一个，猜对了算你运气好，猜错了就是一遍遍返工。

superpowers解决的就是这个信息缺口。它规定AI在写代码之前，必须先进入特定的“技能”状态：先头脑风暴把需求聊透，再写规格说明把边界定清楚，然后才允许进入编码环节。每个技能都是一段结构化的流程指令，AI读到之后会按照流程走，而不是自由发挥。

1.2 这个项目到底做了什么

superpowers的作者是Jesse Vincent（GitHub上的obra），一个老牌的Perl/硬件工程师。他把软件工程里经过了数十年验证的实践——TDD、调试方法论、代码走查、复盘——全部转译成AI能理解和执行的“技能文件”。

每个技能本质上是一个目录，里面有一个SKILL.md作为入口，再加上若干引用文件。AI通过读取SKILL.md来了解“这个技能是什么、什么时候该用、要怎么一步步执行”。所有技能合起来，就是一套“AI版本的工程师工作手册”。

它和你自己在项目里写一份AGENTS.md或者自定义指令的最大区别是：模块化和按需加载。自定指令是“一坨规则让AI全部记住”，上下文一大就容易丢或者互相冲突；superpowers则把规则拆成独立技能包，AI只有在遇到匹配场景时才会加载对应技能，互不干扰。

1.3 技能全景：装上之后AI多了哪些本事

这张表只是我日常用得比较多的部分，仓库里还有一些长期更新维护的技能。装上之后你会发现，AI的行为模式肉眼可见地变了——它开始先问问题、先写测试、先列计划，而不是上来就噼里啪啦生成代码。

2. 核心机制：SKILL.md、渐进式披露与技能编排

2.1 技能文件长什么样

要理解superpowers，必须先看懂SKILL.md。这是整个技能体系的地基。一个标准的SKILL.md长这样：

--- name: test-driven-development description: 当用户需要实现一个功能，且该功能涉及明确的行为和输入输出时使用。通过先写测试再写实现的方式，保证代码正确性。 --- # Test-Driven Development ## 为什么使用TDD - 先写测试可以明确行为边界... - 红绿重构循环能提供持续反馈... ## 实施步骤 ### 第1步：写一个失败测试 1. 列出当前功能的关键行为... 2. 为每个行为写一个最小测试... 3. 运行测试，确认它们失败（红灯）... ### 第2步：实现最少代码 ... ### 第3步：重构 ...

关键在于文件头部的name和description字段。AI在聊天时会不断评估当前场景是否与某个技能的description匹配，一旦匹配，它就会加载对应的SKILL.md正文，然后按照里面的步骤执行。

所以description写得越精准，技能被正确触发的概率越高。这也是很多人自定义技能后半天不生效的原因——description太笼统，AI根本不知道什么时候该用它。

2.2 渐进式披露：像地图App一样按需加载

superpowers在设计上最巧妙的一点是“渐进式披露”（Progressive Disclosure）。简单说，SKILL.md顶层只放摘要和步骤概述，细节拆到子文件里，AI只有在进行到某一步需要更多细节时，才会读取子文件。

这就好比地图App——你打开只看到城市概览，放大之后才看到街道和店铺，继续点进去才有评价和营业时间。如果一开始就把所有细节塞给AI，上下文窗口很快就爆了，而且真正重要的指令会被淹没。

我在使用中观察到，superpowers的SKILL.md对这种披露做了很细致的控制：主文件通常控制在几十行，子文件单独存放，AI每一步都知道“下一步该读哪个文件”。这套设计对于上下文预算紧张的场景价值巨大，也让流程可以支持更复杂的分支操作。

2.3 技能之间不是孤立的：一条完整的工作流链

技能真正的威力在于编排。比如一个“从零开发一个功能”的任务，理想的技能链是这样的：

1. brainstorming —— 把模糊想法聊成明确需求
2. writing-specs —— 把需求固化成规格文档
3. writing-plans —— 拆解开发计划
4. test-driven-development —— 按计划实施编码
5. post-implementation-review —— 交付后复盘

AI在执行过程中会自动判断当前处于哪个阶段，然后加载对应的技能。这就像给AI脑中装了一张流程路线图，它不再跳步骤，而是按部就班地推进。我实际用下来的感觉是：整个交付过程可预测了很多，中途的“惊喜”少了一大半。

3. 安装与接入：Claude Code、Codex CLI、Trae一网打尽

3.1 不同工具的安装思路

superpowers是纯Markdown文件，理论上任何能读文件、能按指令执行的AI编程工具都能接入。区别只在于“怎么把技能目录暴露给AI”。目前主流的接入方式有三种：插件市场安装、克隆仓库后手动复制技能目录、在IDE里配置自定义技能路径。下面逐个说。

3.2 Claude Code插件市场安装（最省事）

Claude Code对superpowers有最完善的支持，因为它有插件市场机制。在Claude Code会话里敲入这两条命令：

/plugin marketplace add obra/superpowers-marketplace /plugin install superpowers@superpowers-marketplace

安装完成后，重启一下Claude Code会话，然后输入/plugin确认superpowers已启用。之后你可以直接使用/brainstorm、/tdd这类斜杠命令唤起对应技能，也可以什么都不做，让AI在对话中自动按场景加载。

这个方式最省心的地方是后续更新——仓库有新版本时，重新执行一遍安装命令就能同步，不用手动维护文件。

3.3 Codex CLI安装superpowers

Codex CLI目前没有像Claude Code那样的插件市场入口，通用的做法是把技能目录复制到Codex的技能目录下。参考社区里大量“codex cli 安装superpowers”的讨论，操作基本是这样：

git clone https://github.com/obra/superpowers.git ~/superpowers mkdir -p ~/.codex/skills cp -r ~/superpowers/skills/* ~/.codex/skills/

复制完之后，在Codex CLI里新开一个会话，先问一句“你会哪些技能？”，如果AI能正确列出来，说明加载成功。之后在对话里把需求描述清楚，AI会在合适的节点主动调用相应技能。

这里有个使用习惯需要调整：Codex CLI对技能的触发更依赖“显式指令”。我试过直接说“请用系统性调试流程帮我查这个bug”，效果比“这个bug怎么修”好得多。如果你发现技能没被自动触发，不妨把技能名直接写进prompt里。

3.4 Trae及国内版IDE的接入

“trae work cn 安装 superpowers skill”最近在热搜上挂了一阵，说明很多人想在Trae这类国内可用的IDE里用上superpowers。Trae本身支持自定义技能/工作流，但不同版本入口位置不太一样，我这里说一个通用思路，你对照自己IDE的文档操作即可：

• 先把仓库克隆到本地，比如git clone https://github.com/obra/superpowers.git
• 在IDE的设置里找到“技能管理”或“Skills”相关入口
• 添加技能目录时，直接指向刚才克隆目录下的skills文件夹
• 如果IDE不支持全局技能目录，也可以把skills文件夹放到工作区根目录下，并在AI配置里声明技能路径

需要注意，Trae这类IDE往往对技能文件的目录结构有自己的一套要求。如果直接指向仓库目录不生效，可能需要参考IDE文档把SKILL.md转成它要求的格式。这个转换过程不复杂，核心是把name和description保留下，正文结构改成IDE认识的字段即可。

3.5 装完怎么验证它真的生效了

安装只是第一步，验证才是关键。我的验证分三步：

1. 直接问AI：“你加载了哪些技能？在什么场景下会用它们？”能清晰列出来说明目录加载成功。
2. 给一个刻意模糊的需求，比如“帮我想想怎么做一个分享功能”，看AI是不是开始提问而不是直接给方案。如果它开始用brainstorming的方式跟你确认需求，说明技能链路真的在走。
3. 看看会话日志或调试面板里有没有读取SKILL.md的记录。这一步能确认技能是在“实际执行”而不是“装样子”。

我见过很多人装完之后没重启会话，或者复制错了目录层级，导致技能根本没加载。遇到这种情况先把这三步走一遍，基本能定位问题。

4. 核心技能逐个拆解：什么时候用、怎么用

4.1 Brainstorming：把“大概想要”变成“明确需求”

很多人忽略brainstorming这个技能，觉得“我需求已经够明确了”。但根据我的经验，越是复杂的任务，前期的brainstorming越值钱。

这个技能的用法是：当AI检测到你的需求存在多个未定义的维度时，它会停下来，像产品经理一样接连提问。比如你让它“做一个文件上传功能”，它会问：文件大小上限是多少？支持哪些格式？要不要断点续传？上传到本地还是OSS？是否需要进度条？并发上传几个？

这些问题看起来很基础，但每一个都是后续开发的决策点。我在实际项目中统计过，跑完一轮brainstorming之后，后续写代码的返工率至少降了一半。很多“AI写出来的代码不符合预期”的抱怨，本质都是前期的需求熵太高，而AI只能选择其中一种解释。

你也可以主动调用它，直接对AI说“用brainstorming技能和我把需求理一遍”，效果更稳定。

4.2 TDD红绿重构：让测试先行成为默认动作

TDD技能是superpowers里含金量最高的一个。它把“先写测试、再写实现、最后重构”的节奏拆成了明确的步骤，AI会严格按照红-绿-重构的循环执行。

在没有这个技能的时候，让AI写测试通常要靠你反复强调：“先写测试”“不对，是先写失败测试”。而且它写出来的测试往往是“为了通过而通过”的假测试，断言弱、覆盖少。有了TDD技能之后，AI会先列出关键行为清单，再针对每个行为写失败测试，运行确认红灯之后才开始写实现，最后还会主动跑一遍完整测试集确认没有回归。

我自己最直观的感受是：用TDD技能产出的代码，测试质量完全是另一个量级的。它不是为了凑覆盖率，而是真的在驱动实现。

这里提醒一句：TDD技能适合“有明确输入输出”的功能，不适合“探索性代码”或“一次性脚本”。遇到后两种情况，建议关掉TDD，直接用对话模式。

4.3 系统性调试：告别“东改一下西试一下”

调试是我认为AI被浪费最严重的能力。普通人用AI调试，通常是“把这个报错发给它，让它猜原因”。superpowers的systematic-debugging技能把调试变成了一个严谨的排查过程：

• 先复现：构造最小复现路径，确认触发条件
• 再定位：在关键路径上加日志或逐步推理，缩小嫌疑范围
• 找根因：区分“表象原因”和“根本原因”
• 修复：基于根因给修复方案，而不是修表象
• 回归：修复之后跑相关测试，确认没有引入新问题

我遇到过很多次，AI在我没说清楚触发现场的情况下就斩钉截铁地给出“原因”，结果改了几轮都不对。有了这个技能之后，AI会先问我“复现步骤是什么”“哪个版本开始出现”“有没有日志”，信息齐了才开始动手。这个习惯本身，就比“瞎猜”靠谱得多。

4.4 计划与规格说明：大改动之前先写文档

writing-plans和writing-specs这两个技能我放在一起说，因为它们解决的是同一个问题的两个阶段：先“定行为”，再“排步骤”。

writing-specs适合在动手前明确接口的行为边界。比如你要设计一个API，技能会引导AI列出：输入参数、输出结构、异常情况、权限要求、性能预期。这些内容以文档形式固化下来，既是给AI自己后面写代码用的依据，也是你检查AI工作是否跑偏的标尺。

writing-plans则是在规格确定之后，把任务拆解成有序步骤。每个步骤有明确的产出物和验证方式。我之前做一个跨模块的重构，AI列出的计划有二十多步，每一步都有对应的测试或检查点。中途虽然也有小偏差，但整体路线图一直在，不会走一步看一步最后迷路。

4.5 代码审查与Walkthrough：让AI学会读代码

大部分让AI处理陌生代码库的方式是“把这几个文件发给你，帮我看看”。结果AI东看一眼西看一眼，给出的一大堆建议根本不在点子上。walkthrough技能不一样，它要求AI按模块、按调用链逐层读代码，并解释自己读到的内容。

我常用的姿势是：把代码文件丢给AI，然后说“用walkthrough技能带我把这个模块过一遍”。AI会按逻辑顺序梳理：入口函数、数据流、关键分支、潜在问题。这个过程有几个额外好处：第一，我能快速理解那段遗留代码；第二，AI梳理过程中会发现一些我自己都没注意的问题；第三，它输出的代码地图可以直接作为后续修改的上下文，不用每次重新读代码。

4.6 事后复盘与根因分析：把每次交付变成经验沉淀

post-implementation-review这个技能一开始我觉得有点“虚”，用了几次才发现是真有用。功能开发完后，AI会对照之前的规格说明，逐项检查：声明的功能都实现了吗？测试覆盖到了吗？有没有临时写死的部分？边界情况处理了吗？这样复盘一遍，很多“当时图省事”留下的隐患能及时暴露。

root-cause-analysis则是针对线上故障的深度复盘工具。它的用法是让AI基于时间线梳理事件，找“触发条件”背后的“根本原因”，并给出防止复发的具体措施。这两兄弟配合，相当于给团队加了一个“每次交付都自动做质检和复盘”的流程。

5. 一个完整实战案例：给内部工具加一个接口限流

5.1 场景设定

为了让你直观感受装上superpowers前后的差异，我拿一个真实项目片段举例：给内部的一个数据查询接口加上限流，每用户每分钟最多60次。

在没有技能的“裸奔”状态下，我给Codex CLI直接说“给这个接口加限流”，它的反应是：立刻在Controller里加了个计数器代码，甚至用了ConcurrentHashMap。问题很多——多实例部署就失效，没有考虑限流维度，也没有测试。

在装了superpowers之后，整个流程变成了这样。

5.2 第一轮：Brainstorming把决策点聊清楚

我给AI下指令“用brainstorming技能帮我把这个限流需求理一下”。它没有直接写代码，而是连续问了我好几个问题：

• 限流维度是用户ID、IP还是AppKey？
• 超过限制之后，直接返回429还是排队等待？
• 单实例部署还是多实例？多实例的话要不要用中心化存储？
• 限流窗口是固定窗口、滑动窗口还是令牌桶？
• 对性能的容忍度如何，能不能接受Redis这种额外依赖？

这些问题我一个一个回答，过程中发现有两个点我自己之前都没想清楚。比如多实例部署这一点，直接决定了技术选型——单实例用内存计数器就行，多实例就得考虑Redis+Lua脚本。

一轮聊完，需求和边界基本清楚。对比裸奔场景，这一步就省下了后面至少两轮返工。

5.3 第二轮：TDD驱动实现

需求清晰后，我让AI“用TDD技能实现”。它先写了一个测试，验证同一用户第61次请求会被拒绝；然后又写了第二个测试，验证不同用户之间互不影响；第三个测试验证限流窗口在60秒后重置。测试跑完变红，它才开始写实现。

这里有个很关键的细节：因为brainstorming阶段已经确认了“用Redis+固定窗口”方案，AI在写测试时直接Mock了Redis客户端，实现也严格按固定窗口的逻辑写，没有出现“为了省事改成内存实现”这种自作主张的行为。

整个过程中，我只做了一件事：审测试用例合不合理。实现的部分几乎没有干预，因为它走得很稳。

5.4 第三轮：Systematic Debugging处理一个真实bug

测试跑到一半，出现了一个诡异的失败：单测环境下第二个测试用例偶发失败。如果按我以前的做法，直接把报错丢给AI猜，它多半会说“可能是并发问题”然后让我加锁。

这次我让AI用systematic-debugging技能排查。它先要求我提供失败时的测试输出和运行环境，然后开始推理：固定窗口实现里，取窗口起始时间的逻辑有边界误差，跨秒时可能出现窗口错位。它给出了复现条件，并写了个可以稳定复现的循环测试，确认根因之后，再修改时间窗口的计算逻辑，最后把三个测试全部跑绿。

整个过程有条有理，最让我满意的是它没有乱改代码，每一步都有据可依。

5.5 对比感受

同样一个需求，裸奔场景下AI给我的是“一个看起来能用的实现 + 一堆遗留问题”；在superpowers的流程下，它给我的是“一次清晰的需求梳理 + 一套完整的测试 + 一个被验证过的实现 + 一份复盘清单”。

这不是模型变聪明了，而是流程把模型身上原本就有的能力，引导到了正确的地方。

6. 踩坑记录与个性化调优

6.1 三个高频坑

技能不生效。这是最常见的坑，大概率是会话没重启、技能目录放错层级、或者description写得不够具体导致AI没识别到场景。排查方法我之前说过，先问AI“你会哪些技能”，再看日志，十有八九能定位。

上下文被撑爆。我给AI喂了一整个项目让它分析，结果把输出长度顶到了上限。后来才意识到，superpowers的设计前提是“按需读取”，你应该让它先列计划，再按计划分步读取文件，而不是把一堆文件一次性塞给它。

模型本身的能力下限。superpowers再强，它也只是流程约束，不改变模型的下限。小模型经常出现“走了流程但步骤执行得糊弄”的情况，比如测试写了但断言很弱、复盘流于形式。我实测下来，至少得用当前第一梯队的模型，这套技能的优势才能完全发挥出来。

6.2 根据团队习惯裁剪技能

每个团队的开发流程不一样，不需要把仓库里所有技能都挂上。我目前的日常工作只保留了六个技能：brainstorming、writing-plans、test-driven-development、systematic-debugging、post-implementation-review、walkthrough。其余的安全审查、依赖管理这些，只在特定项目里临时开。

裁剪的方式很简单：在技能目录里把不需要的技能文件夹移除即可。不要怕删错，仓库随时可以重新克隆回来。技能不在于数量多，而在于AI“分得清什么时候该用哪个”。

6.3 自己写一个简单Skill

如果想要更好的定制，superpowers带来了一个我强烈推荐的附加技能：creating-skills。它能引导AI按照项目自己的规范帮你生成新的SKILL.md。

我的经验是，当你发现某类任务AI反复做不好的时候，就是一个值得沉淀成技能的信号。比如我们团队经常写数据库迁移脚本，一次我让AI把团队约定固化成一个技能，它生成了一个数据库迁移的SKILL.md，里面规定了：建索引的命名规则、回滚脚本必须同步写、线上执行前必须MR评审。从那之后，AI写迁移脚本的质量直接上了一个台阶。

写技能的核心就一条：把“你希望AI在某个场景下遵守的操作步骤”写清楚，description写精准。其余交给流程就好。

最后分享一点我个人的体会。我刚开始用superpowers的时候，总觉得“给AI上这么多流程会不会拖慢速度”，用久了才明白：慢就是快。少走一次方向性错误、少修一次返工的bug，节省的时间远超流程本身的开销。如果你之前总觉得“AI写代码不稳”，不妨先别急着换模型，试试给现有的AI装上这套“超级能力”，把流程纪律立起来，效果可能比换一个更强的模型还明显。