企业官网建设流程全解析

1. 从“superpowers”这个词说起：它到底指什么

第一次看到“superpowers”这个标题，加上“agentic skills framework”“software development methodology”这几个关键词，我脑子里第一反应是：这不是某个具体软件的名字，而是一套给 AI 编程代理（agent）用的技能框架和方法论。换句话说，它想解决的不是“AI 能不能写代码”，而是“AI 写代码时，怎么像一支有纪律的工程团队那样干活”。

我接触过不少把 AI 塞进开发流程的尝试，绝大多数最后都卡在同一个地方：模型本身很聪明，但一到真实项目里就开始乱来——改一个函数顺手把隔壁模块重构了，跑测试失败三次之后开始瞎猜，遇到不确定的需求直接编一个看起来合理的实现。这些问题的根源不是模型能力不够，而是缺少一套约束它行为的工作方法。superpowers 这类框架的价值，就是把这套方法固化下来，让 agent 按套路出牌。

需要先说明一点：superpowers 本身不是一个能独立运行的软件，它更像是一组技能定义（skills）和工作流约定，挂载在 Claude Code、Codex CLI 这类命令行 AI 编程工具上使用。所以想真正用起来，你得先有一个能跑 agent 的宿主环境。这也是为什么相关热搜里全是“claude code 安装”“codex cli 安装”“vscode 配置 claude code”这类词——大家卡的第一步根本不是 superpowers 本身，而是宿主工具没跑通。

这篇文章我打算按真实上手顺序来写：先讲清楚 superpowers 这套方法论的内核是什么、为什么值得用；再讲宿主环境怎么选、怎么装；然后是技能框架怎么落地到日常开发；最后是我自己踩过的坑和排查思路。如果你已经在用 Claude Code 或 Codex CLI，但总觉得 agent 干活不靠谱，这篇应该能帮你把思路理顺。

2. superpowers 的内核：把工程纪律翻译成 agent 能懂的语言

2.1 为什么“让 AI 写代码”不等于“让 AI 做工程”

大部分人用 AI 编程的起点是：打开对话框，描述需求，复制代码，粘贴到项目里。这个模式在写一个独立函数、一个算法题时很好用，但一旦进入真实项目就崩了。真实项目的代码是有上下文的——命名规范、目录结构、依赖关系、测试覆盖、错误处理约定，这些东西不会写在你的需求描述里，但缺了它们代码就是不能合并。

superpowers 的核心洞察就在这里：agent 需要的不是更强的代码生成能力，而是一套“先理解再动手”的作业流程。它把资深工程师的工作习惯拆成一个个可复用的技能模块，比如“动手前先读相关文件”“改动前先确认影响范围”“写完必须跑测试”“失败后先定位再修改而不是重写”。这些听起来都是常识，但 agent 默认不会这么做，必须显式地教它。

我自己的体会是，用了这套框架之后，agent 的行为从“一个急于表现的新人”变成了“一个知道先看再做的中级工程师”。它不会一上来就给你一大段代码，而是先列出它打算改哪些文件、为什么改、改完怎么验证。这个转变对实际开发效率的影响，比模型升级一代还明显。

2.2 技能（skills）是怎么组织的

superpowers 里的“技能”不是抽象概念，而是结构化的提示词模块，每个技能通常包含几个部分：触发条件（什么时候该用这个技能）、执行步骤（具体怎么做）、检查点（做完怎么确认没跑偏）。这种结构和人类给新人写的 SOP（标准作业程序）几乎一样。

举个具体的例子。一个“安全重构”技能大概长这样：触发条件是“需要修改已有代码结构但不改变外部行为”；执行步骤是“先跑一遍现有测试确认基线是绿的 → 定位所有调用点 → 逐个修改并保持接口不变 → 每改一处跑一次相关测试”；检查点是“所有原有测试仍然通过，且没有新增未覆盖的分支”。你看，这就是一个工程师带徒弟时会说的话，只不过现在写成了 agent 能解析的格式。

这种组织方式的好处是可组合。一个复杂任务可以拆成多个技能串联：先“理解需求”，再“探索代码库”，然后“制定方案”，接着“分步实现”，最后“验证与收尾”。每个技能只负责一件事，做扎实了再交给下一个。这比让 agent 一口气完成整个任务要可靠得多，因为每一步都有明确的输入输出和验收标准。

2.3 它和普通提示词工程的区别在哪

有人可能会问：这不就是写更长的提示词吗？区别在于系统性和可维护性。普通提示词是每次对话临时写的，写完就扔，下次遇到类似场景还得重写。superpowers 的技能是沉淀下来的资产，可以版本管理、可以复用、可以针对项目定制。你今天调好了一个“处理数据库迁移”的技能，明天换个项目还能接着用，只需要微调触发条件。

另一个区别是约束的强制性。普通提示词里写“请先读代码再改”，agent 可能读也可能不读，取决于它当时怎么理解。而技能框架通常会和宿主工具的机制结合，比如在特定阶段强制注入某个技能的内容，或者用检查点机制卡住流程，不通过就不让继续。这种“流程上的硬约束”才是它真正区别于随手写提示词的地方。

3. 宿主环境怎么选：Claude Code 与 Codex CLI 的实际差异

3.1 两个工具解决的是同一类问题，但路子不同

superpowers 要跑起来，得有个宿主。目前主流选择就是 Claude Code 和 Codex CLI，两者都是命令行形态的 AI 编程代理，都能读写文件、执行命令、跑测试。但用下来感觉它们的性格不太一样。

Claude Code 更像一个深度集成的结对程序员。它对项目上下文的理解比较细腻，会主动去读相关文件、理解目录结构，交互上偏向“边聊边做”。它的技能挂载机制也比较成熟，superpowers 这类框架在它上面跑得比较顺。缺点是它对账号和网络环境有一定要求，热搜里那句“your organization has disabled claude subscription access”就是典型的企业策略限制问题。

Codex CLI 更像一个轻量级的任务执行器。它的命令集比较精简，像/compact、/model、/resume这几个是高频使用的——/compact压缩上下文省 token，/model切换模型，/resume恢复之前的会话。它对接第三方模型和本地模型相对灵活，热搜里“codex cli remotion”“codex cli 命令哪些”说明不少人在研究它的具体用法。如果你手头有本地模型或者第三方 API，Codex CLI 的接入门槛会低一些。

3.2 选型时我实际会看的几个维度

我的建议是：如果你追求“开箱即用的工程体验”，并且环境允许，优先 Claude Code；如果你需要接本地模型、或者想精细控制每一步的模型调用，Codex CLI 更合适。两者不冲突，我自己的机器上是都装了的，简单任务用 Codex CLI 快速跑，复杂重构用 Claude Code 慢慢磨。

3.3 安装前必须想清楚的一件事

热搜里大量“claude code 安装”“ubuntu 配置 claude code”“mac 安装 claude code”的问题，说明安装本身就是一道坎。这里我不展开具体命令（各平台差异大且更新快），但有一个原则必须强调：先把宿主工具单独跑通，再考虑挂 superpowers。很多人一上来就想把框架和工具一起配好，结果出问题时根本分不清是哪一层的问题。正确的顺序是：装好宿主 → 跑一个最简单的“读文件并总结”任务 → 确认能正常读写和执行 → 再挂技能框架。

4. 把 superpowers 落到日常开发：一套可复用的作业流程

4.1 任务开始前的“三问”技能

我现在让 agent 干活，第一步永远是让它回答三个问题：这个任务要改哪些文件？这些文件之间是什么关系？改完之后怎么验证？这三个问题对应 superpowers 里“理解与探索”阶段的技能。别小看这一步，它能挡掉至少一半的返工。

举个真实例子。有次我让 agent 给一个接口加参数校验，它直接就开始改 controller。我拦住它，让它先回答三问。结果它一探索发现，这个接口的参数其实在中间件层已经被处理过一次了，controller 里再加校验是重复的，而且会覆盖掉中间件的默认值逻辑。如果它直接改，就是一个隐蔽的 bug。这就是“先理解再动手”的价值——agent 不缺写代码的能力，缺的是动手前的那几秒犹豫。

4.2 分步实现与检查点设置

superpowers 强调把大任务拆成小步，每步都有检查点。我通常会把一个功能拆成“数据层 → 逻辑层 → 接口层 → 测试”四步，每步做完让 agent 停下来，我确认后再继续。这个节奏看起来慢，但实际比“一口气生成然后大改”快得多。

检查点具体检查什么？我的清单是：这一步的改动是否只涉及预期文件？是否有未使用的导入或变量？相关测试是否通过？有没有引入新的依赖？这四条过一遍，基本能拦住大部分低级问题。特别是“只涉及预期文件”这条，能有效防止 agent 顺手重构——它经常觉得“既然改到这里了，不如把隔壁也优化一下”，这种“热心”在真实项目里是灾难。

4.3 失败后的处理技能：定位而非重写

agent 跑测试失败时的默认反应是“重写一遍”，这是最危险的行为。superpowers 里有个专门的技能处理这种情况：失败后先读错误信息，定位到具体行，分析原因，再决定是改这一行还是改设计。我要求 agent 在修改前必须用一句话说清楚“失败的根本原因是什么”，说不清楚就不许改。

这个约束救过我很多次。有一次测试报了一个类型错误，agent 第一反应是把类型断言加上去强行通过。我让它先解释原因，它读了一圈发现是上游数据结构变了但下游没同步。如果直接加断言，问题就被掩盖了，上线后会在运行时炸掉。让 agent 解释原因，本质上是在逼它做真正的调试，而不是做表面修补。

4.4 收尾阶段的清理技能

任务做完不等于结束。superpowers 的收尾技能包括：删除调试代码、检查是否有遗留的 console.log、确认没有注释掉的大段代码、更新相关文档。这些琐事人类工程师也经常忘，交给 agent 按清单过一遍反而更可靠。

我还会加一条自己的习惯：让 agent 用一段话总结这次改动，包括改了什么、为什么这么改、有什么遗留问题。这段话我直接拿来当 commit message 或者 PR 描述，省了不少事。而且写总结的过程本身也是一种自检——如果它总结得含糊其辞，说明它自己也没完全搞清楚改了什么。

5. 踩坑实录：那些让我停下来重新思考的瞬间

5.1 上下文膨胀导致的“失忆”

用了一段时间之后我发现一个规律：会话越长，agent 越容易忘事。前面确认过的约定，聊到后面它就不记得了，开始按自己的理解来。这不是模型的问题，是上下文窗口的物理限制。热搜里 Codex CLI 的/compact命令就是干这个的——压缩历史上下文，保留关键信息。

我的应对策略是主动分段。一个任务如果预计超过一定轮次，我会在关键节点手动总结当前状态，开一个新会话继续。总结内容包括：已完成的部分、当前的文件状态、下一步要做什么、有哪些约定不能忘。这个总结我让 agent 自己写，我审核。这样新会话开始时，它拿到的是一个干净的、聚焦的上下文，而不是一堆历史对话的残渣。

5.2 技能冲突与优先级问题

当多个技能同时被触发时，会出现冲突。比如“快速实现”技能和“充分测试”技能在某些场景下是矛盾的——前者想尽快出结果，后者要求每步都验证。如果框架没有明确的优先级，agent 就会摇摆，行为变得不可预测。

我的处理办法是给技能排优先级，并且显式告诉 agent。在项目配置里写明：正确性 > 可维护性 > 速度。这样当技能冲突时，agent 知道该听谁的。这个优先级不是一成不变的，赶进度的时候我会临时调整，但调整必须显式说出来，不能让它自己猜。

5.3 本地模型接入后的能力落差

热搜里“claude code 调用 lmstudio 的本地模型”“使用 cc switch 接入 deepseek、qwen、glm 等模型”说明很多人想用本地或第三方模型替代官方模型。这条路能走通，但要有心理准备：不同模型对技能框架的遵循程度差异很大。有些模型能很好地理解结构化技能，有些则会把技能内容当成普通文本忽略掉。

我实测下来的经验是：技能框架越复杂，对模型能力的要求越高。如果你的本地模型规模较小，建议先用简化版的技能——只保留最核心的“先读后写”和“失败先定位”两条，跑顺了再逐步加。一上来就挂全套技能，小模型会直接懵掉，表现反而不如不用框架。

5.4 环境配置的隐蔽陷阱

安装配置阶段的坑特别多，而且往往报错信息不明确。我遇到过的情况包括：路径里有空格导致命令解析失败、权限不足导致无法写入配置目录、系统版本与工具要求不匹配。热搜里“claude code 由于与 64 位版本的 windows 不兼容”就是典型的平台兼容问题。

排查这类问题的通用思路是：从最简环境开始，逐步加变量。先确认基础命令能跑，再加配置，再加技能，每加一层测一次。出问题时，最近加的那一层就是嫌疑最大的。另外，养成看日志的习惯——大部分工具都会把详细错误写到日志文件里，比终端上显示的那一行有用得多。

6. 我对这套方法论的真实看法

用了一段时间 superpowers 这类框架之后，我最大的感受是：它改变的不是 AI 的能力上限，而是 AI 的可靠性下限。模型再聪明，如果没有约束，在真实项目里的表现就是不可预测的；有了这套作业流程，它的输出变得可预期、可审查、可复现。对个人开发者来说，这意味着你可以放心地把更多任务交给它；对团队来说，这意味着 AI 生成的代码有了进入代码库的基本质量保证。

但它不是银弹。框架本身需要维护，技能需要根据项目调整，模型能力仍然是天花板。我见过有人把 superpowers 当成“装上就变强”的插件，结果发现 agent 还是该犯错犯错——因为框架只是给了方法，执行方法还需要你盯着。真正有效的用法是把它当成一个给 agent 看的工程规范文档，你写规范，它照着做，你验收。

最后分享一个我自己的小习惯：每次 agent 干完活，我会问它一句“这次哪里做得不够好”。它的回答经常能指出一些我没注意到的流程漏洞，比如某个检查点设得太晚、某个技能触发条件写得太宽。把这些反馈攒起来，定期更新技能配置，这套框架才会越用越顺手。工具是死的，方法是活的，真正让 superpowers 发挥作用的，还是用它的人愿不愿意持续打磨。