企业官网建设流程全解析

1. superpowers到底是什么：给AI编程代理补齐短板的一组技能包

过去一年，我用Claude Code和Codex写了不少项目代码，它们确实能在一小时里干完过去一天才能写完的骨架代码。但用久了你会发现一个尴尬的现象：AI代理擅长"写代码"，却不太擅长"干活"——它经常无视你项目的既有约定，闷头追加一段逻辑完事，遇到报错就反复撞同一个墙，或者改完一个方法不去跑测试。这些问题不是模型能力不行，而是缺少一套约束和引导它的工作流程。直到我找到开源项目superpowers，这个问题才算有了一个系统的解法。

简单说，superpowers是一组专门为AI编程代理设计的技能包（skills）。它不直接给你写代码，而是把一套接近资深工程师的工作方法写成结构化指令，注入到Claude Code、Codex这类代理的工作流里。你在对话中让代理"用brainstorming技能帮我梳理这个需求"，它就会按照技能文件里定义的步骤去提问、列方案、权衡取舍，而不是拿到需求立刻动手。这个项目目前在GitHub上开源，Star涨得很快，作者是Jesse Vincent（网名obra），核心思路是把可复用的开发方法论交给代理去执行。

这个项目最适合的人群有两类：一类是被AI代理"会写但写不稳"困扰的开发者，另一类是刚上手Claude Code/Codex、想让代理从一开始就养成好习惯的新手。它解决的问题我在后面会详细拆，这里先给一个结论性的判断：superpowers的价值不是给AI加了多酷的新功能，而是给它补上了一套"职业素养"——这正是很多AI编程工具落地到真实项目时最缺的东西。

2. 安装与接入：Claude Code和Codex的配置细节

2.1 前置准备：先确认你的运行环境

在折腾技能包之前，先把基础环境理一遍。我是Mac环境，用Homebrew装的Node.js 18+，npm和git都是常规版本。Windows上如果装了WSL或者Git Bash，流程也类似，但路径处理要小心一点（后面会提到一个和路径有关的坑）。你需要先确认三样东西：

• Node.js版本不低于18（有些技能脚本依赖较新的fetch和WebSocket API）
• git可以正常执行，因为插件市场安装本质上是git clone
• Claude Code或Codex已经能跑通一个最简单的对话

如果你现在还在用旧版的Claude Code，建议先升级到最新版本，因为superpowers的安装方式在不同版本里有差异。旧版本只支持手动克隆skills目录，新版本则可以直接通过插件市场安装，体验差很多。

2.2 方式一：通过Claude Code插件市场安装（推荐）

新版本Claude Code支持/plugin命令进入插件市场，可以直接搜索到superpowers。操作路径是这样：

# 在Claude Code对话中输入 /plugin marketplace add obra/superpowers-marketplace /plugin install superpowers@superpowers-marketplace

这两条命令的作用分别是：把obra维护的插件市场地址添加到本地配置，然后从该市场安装superpowers插件。安装成功后，Claude Code会自动拉取技能文件到~/.claude/skills目录。你可以用下面的命令确认文件都到位了：

ls -la ~/.claude/skills

如果看到一堆以技能名命名的目录，比如brainstorming、planning、debugging、TDD、codebase-examination等，说明主体文件已经就位。接下来还需要验证代理是否真的读取到了这些技能。最简单的方式是直接问它：

你知道自己有哪些可用的技能吗？用一句话列出。

如果AI能准确说出brainstorming、planning这类技能名并简要说明用途，就说明加载成功。如果它说"没有技能"或者"我是通用助手"，多半是路径配置没生效，看下面的手动安装方式。

2.3 方式二：手动克隆Skill目录（通用方案）

• 不装插件市场，或者你用的是其他支持SKILL.md的AI代理工具，手动克隆是最稳妥的方案。先将仓库克隆到本地：

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

然后看你的工具需要把技能放哪：

• Claude Code：把仓库里的skills目录软链到~/.claude/skills
• Codex（OpenAI的CLI工具）：通常放在~/.codex/skills，具体以你的Codex版本配置为准
• 其他支持技能体系的代理：参考它的配置文档，一般是把技能目录路径加到配置文件的skills字段

这里有个我在Mac上遇到过的坑：直接cp -r复制目录没问题，但如果你用了软链，某些代理在遍历技能目录时会因为符号链接解析失败而静默跳过，表现为"技能装了但AI感知不到"。我最后是直接用复制而不是软链才解决的。

2.4 Codex环境的接入：不只是复制目录那么简单

热搜词里有"codex superpowers"，说明不少人在Codex里尝试装这个项目。如果我理解没错，你有一个Codex命令行工具，你可以把superpowers的技能文件放到Codex能识别的技能目录，然后在对话里引用。但我实测下来的经验是：Codex对SKILL.md的支持比Claude Code晚一些，格式兼容性没有Claude Code那么顺滑。如果你在Codex里发现某些技能触发了但表现不完全符合预期，大概率是技能文件里的某些字段Codex忽略掉了。

一个比较实用的做法是先把superpowers仓库完整看一遍，尤其是skills目录下各个技能文件夹里的SKILL.md，然后手动提取其中适合Codex的指令核心，写入Codex的AGENTS.md文件。虽然这样会丢失按需触发的能力，但至少能把"先规划再动手""写测试再验证"这些关键方法论注入给Codex。老实说，这算是个折中方案，我在生产环境里就是这么干的。

3. 核心技能拆解：哪些SKILL最值得深入了解

3.1 Brainstorming与Planning：把"想清楚"变成强制流程

superpowers里我最常用的是brainstorming和planning这两个技能。它们的价值在我看来就像给AI代理装上了设计评审环节。

先说brainstorming。它引导代理在做任何重要改动前，先向用户提出一系列澄清问题：这个功能的核心用户是谁？输入输出的边界在哪？有没有历史包袱？然后基于回答生成多个候选方案，列出每个方案的优缺点和成本，最后才给出推荐。实操中你会发现，这个过程把"AI闷头写代码"变成"AI先做需求分析"，省掉的返工时间非常可观。

planning则更进一步：它把需求分解成阶段性的执行步骤，每个步骤都有明确的输入和输出，还要求生成回滚预案。这一步对于改动现存代码尤其重要。我接手过一个老Spring Boot服务，希望改一个订单状态流转逻辑，单独丢给AI改，十次有八次会引入状态漏洞。换成planning技能之后，它会先把当前状态机画出来（文字形式），列出每个路径的影响面，再给出修改方案和验证步骤，最后才动代码。这套流程不是superpowers发明的，但它把它固化成代理的执行习惯后，效果非常稳定。

3.2 代码库阅读与理解：让AI先搞清楚"现状"再动手

codebase-examination这个技能，名字看起来平平无奇，实际使用频率很高。它会让AI在回答代码相关问题时，先主动定位关键文件、检查相关调用链、阅读类之间的依赖关系，而不是急着给答案。

• 遇到"帮我看看这个bug在哪"类问题，它会先追踪异常栈里涉及的类和方法，再读相关配置文件，最后才输出判断。
• 遇到"这个需求从哪改最合适"类问题，它会先扫描领域模型和Controller层入口，勾勒出数据流向，然后给出修改建议。

这个技能对我特别有用的场景是接手别人写了一半的项目。人脑判断不了全局时，AI按技能流程走一遍，相当于给项目做了次快速体检。而且它对Java这类多模块项目效果尤其好——superpowers java这个热搜词下很多讨论，其实都指向同一个结论：Java项目结构复杂、约定繁多，恰恰需要这种先摸清代码库再动手的工作流。

3.3 调试与验证：拒绝盲目试错

debugging技能的核心思想是"系统地缩小问题范围"。它的执行路径大致是：先复现问题，再提出可能的根因假设，然后设计最小化实验去验证或排除每个假设，循环往复直到定位根因。

听起来像教科书？实际跑起来确实有效。我记得一次排查一个API偶发超时的问题，让AI直接修，它连续三次都在改连接池配置——改完更糟。换成调用debugging技能之后，AI先列出问题可能出现的四个层面（网络层、应用层、数据库连接层、第三方依赖），然后用日志时间戳定位到其实是某个第三方SDK的异步回调阻塞了Netty线程，问题完全不在连接池。事后想想，它之所以之前一直在乱试，是因为缺少结构化的排查顺序。技能文件其实就是给它一个checklist，让排查不再盲人摸象。

3.4 TDD流程与Agent原生测试：写代码的前后夹击

superpowers里的TDD技能把测试驱动开发拆成了"红-绿-重构"的循环，并要求代理每一步都向用户汇报测试结果。这改变了AI默认的工作习惯：以前它写完功能可能根本不跑测试，或者跑一遍不管结果就直接说"完成"，现在它会把新增测试的失败截图和通过截图都贴出来。

test-driven-development技能里还包含一个"如何让AI自己改代码"的实操模块，它会指导代理在被bug或需求变更卡住时，主动编写一个小测试来暴露问题，然后根据测试结果决定后续动作。

这里要特别提一句：这套流程在Java项目里跑起来比其他语言更顺手。可能因为Java生态里JUnit、Maven Surefire这些工具链标准且成熟，技能文件里给出的命令几乎开箱即用。而在Python项目里，pytest的fixture和参数化组织风格差异较大，代理生成的测试有时会被自身格式绊倒。

3.5 浏览器自动化与Web应用验证：把"打开页面瞅一眼"也交给AI

如果你做Web开发，browser-operator这个技能值得关注。它让AI代理可以直接操作浏览器：打开页面、点击按钮、填写表单、截图。配合system-config里的Playwright环境，它能在代码改完之后自动做一轮冒烟测试。

不过这个技能我目前还没在生产环境里完全信任。它确实能跑，但页面选择器一变化就容易扑空，而且浏览器自动化和CI流水线的集成还比较粗糙。我的建议是：可以在本地开发时让它辅助验证，别直接扔到生产环境做E2E，该用正经测试平台的地方还是用正经测试平台。

4. 技能包背后的工作原理：为什么"给AI立规矩"比"给AI加功能"更有效

4.1 SKILL.md的格式与触发机制

superpowers每个技能的本质都是一个目录，里面放着SKILL.md主文件，有的还附带脚本、模板和参考文档。SKILL.md用Markdown写，包含三个核心部分：

• Frontmatter：YAML格式的元信息，定义了技能名称、描述、适用场景
• 触发条件：哪些类型的任务应该调用这个技能
• 执行步骤：清晰编号的操作步骤，每一步都给出具体的执行方式

触发机制上，Claude Code新版本基本是"自动语义匹配+手动调用"双轨制。如果用户在问题里表达了需求意图，模型会自己判断要不要加载相关技能；你也可以在prompt里显式点名，比如"用planning技能来处理这个需求"。

这个机制很像人的工作记忆：所有技能文件都放进"长期记忆"，但只有在相关任务出现时才加载到对话上下文。我在实际使用中感受到一个明显变化：很多泛化得很好的模型，如果不给它这些技能，它也能做规划、会写测试，但稳定性不行。激活技能相当于把模型的能力范围收窄到一套固定流程上，牺牲一点发散性，换来了可预测的执行结果。

4.2 把资深工程师的工作流固化成指令

我一直觉得superpowers最厉害的设计不是某个具体技能，而是它把"资深工程师接到任务后怎么思考"这个过程拆成了可执行的动词序列。这里以"改一个已上线接口的参数校验逻辑"为例，对比有技能和没技能的差别。

没有技能的模式下，AI看到需求直接开始改Controller里的校验代码，改完说"已完成"。有planning技能的模式下，它会先确认接口的调用方有哪些，参数校验失败时原有业务流程都依赖哪些异常信息，再给出波及面分析，最后才动手。这正是资深开发者处理需求时的自然动作：评估影响面、考虑兼容性、分步实施、留好后路。

这类经验通常散落在团队资深成员的脑子或老代码commit message里，superpowers把它文本化、可复制化了。所以它对新人特别友好——相当于给每个团队新人都搭配了一个"资深工程师的行为规范"，只不过这个行为规范的执行者是AI代理。

4.3 为什么这套方法能提升输出质量

从原理上看，AI代理的输出质量取决于"模型的先验知识+上下文中的约束条件"。superpowers的核心作用就是给上下文注入大量高质量约束条件：

• 限制AI的过早行动，强制先收集信息和确认需求
• 通过分步骤执行，迫使AI在每一步都产生中间结果，方便人及时纠偏
• 用"每步汇报测试结果"这类要求，增加了关键节点的外部监督

这些约束不会提升模型的推理能力上限，但会把模型实际输出的下界拉高一大截。换句话说，superpowers保证AI代理的最差表现不差，而不是追求最好的表现在某些时刻惊艳。对实际项目而言，稳定性比上限更重要——这也是我敢把AI代理用于半正式生产改动的原因。

5. 实测避坑：我用superpowers过程中遇到的5个坑

5.1 技能文件占用的上下文窗口比你想象的大

superpowers装完以后，每次对话都可能把相关技能的SKILL.md载入上下文。技能少的时候没感觉，一旦技能多起来或者项目大起来，上下文窗口会明显吃紧。我的做法是定期裁剪不需要的技能，保留高频的几个，太多了反而是负担。尤其是同时开着brainstorming、planning、debugging三个重型技能时，AI在简单任务上也容易"用力过猛"。

5.2 多个技能同时触发时的指令冲突

有一次我让AI修复一个页面样式问题，结果它同时加载了debugging、plannning和browser-operator三个技能，行为变得很怪：一会儿按调试流程排查CSS的层叠顺序问题，一会儿又要做影响面分析，最后还尝试用浏览器自动化打开页面验证。其实这种小问题直接让AI改掉就行。

解决办法是在prompt里显式排除技能："修复这个问题，不需要用planning，直接用简单的方式改，改完贴diff。"现在我已经习惯在简单任务前加这样的限制，减少不必要的流程开销。

5.3 技能目录的路径复制问题导致的"静默失败"

前面提过的路径问题，值得拿出来单独说：用软链接方式安装技能，有些工具会静默跳过而不会报错。症状就是AI完全不认技能名，问你"skills是什么？"。这次我用的是直接把skills目录真实复制到~/.claude/skills，问题就消失了。

5.4 技能命令在Java项目里使用时的注意点

热搜词"superpowers java"相关问题的核心，是技能文件里写死的命令有时和你的项目结构不匹配。比如TDD技能里默认用的构建命令是mvn test，但你的项目如果是Gradle，它就会卡壳。我的习惯是提前在项目根目录的AGENTS.md或CLAUDE.md里写好项目专属命令，像Gradle项目的测试命令、Java版本号、依赖仓库地址、常见模块结构等。这样AI即使从技能文件拿到通用指令，也会优先参考项目说明来调整。

另外，Java多模块项目的路径问题也容易让AI犯迷糊。superpowers的codebase-examination技能在读代码时，如果项目里有大量自动生成的target目录，它会把这些也读进去，既费token又容易给出误导。我的做法是在项目说明里明确告诉AI：哪些目录不要碰，只看src/main/java和src/test/java，以及关键配置文件。

5.5 技能减少了模型的发散性，不是什么时候都该开

某次我让AI设计一个新的鉴权方案。因为习惯了开着planning，结果它输出了一套巨完整的方案，包括CASBIN权限策略、Token轮换机制、审计日志表设计……面面俱到但整页都是正确而无用的废话。后来我重来，关掉技能，让它直接给三个可行方案，反而简洁清晰得多。

这说明技能的"立规矩"效应也有副作用：会让模型过早地收敛到某个流程里，抑制它的发散思考。遇上探索性问题、开放性设计题、需要创意的场景，我建议先关掉大部分技能，用裸模式自由讨论，等方向定了再开技能进入执行模式。

6. 从工具到方法论：我建议的上手路径

6.1 先跑通最小闭环，再谈进阶玩法

如果你是第一次用superpowers，建议不要一上来就把全部技能都装好、全开着。我先推荐一个小闭环试跑路径：

1. 只保留codebase-examination和planning，卸掉其他技能
2. 在自己的小项目里让AI处理一个"新增一个小接口"或"修改一个校验逻辑"的需求
3. 观察它是否会先读现有代码、是否会提出多层级的澄清问题、是否会拆分执行步骤
4. 满意之后再加TDD技能
5. 逐步把debugging、browser-operator纳入

这样每一层都建立在前一层的正反馈上，适应成本低很多。

6.2 按需裁剪，别开"全家桶"

我的个人配置里，日常开发只开四五个核心技能：brainstorming、planning、codebase-examination、debugging、TDD。其他技能比如writing-plans、executing-plans、system-config这些，都是在特定任务时手动调用，而不是常驻。常驻技能太多确实会稀释模型对具体任务的专注度。

6.3 把你的工作约定也写成SKILL.md

用了一段时间之后，我最大的收获是开始给自己的团队定制技能。项目的代码规范、commit message格式、Code Review的检查清单、发布流程这些，过去靠人反复叮嘱，现在全部写成了自己的SKILL.md文件放在团队共享的skills目录里。新成员加入后，不需要厚厚一本新人手册，让AI代理直接按这些规则工作就行。

这一步其实是superpowers真正的价值所在：它不只是别人给你的一组技能，而是给了你一种"如何把经验编码给AI"的范式。你可以把团队踩过的坑、定下的规矩、沉淀的最佳实践，全部变成AI可执行的方法论。想到这一层的时候，会有一种"这不只是个工具，这是新的团队资产沉淀方式"的感触。我在实际使用中最大的体会就是：AI编程代理的上限不由模型参数决定，而由你用什么样的流程去约束它决定。superpowers给了一个相当好的起点，剩下的路，得靠每个人结合自己的项目去走出来。