1. 从“superpowers”说起这套方法论到底在解决什么问题第一次看到“superpowers”这个词很多人会以为是某个超级英雄题材的游戏或者插件。但如果你最近在折腾 Claude Code、Codex CLI 这类终端里的 AI 编程助手大概率已经在各种讨论里撞见过它。它本质上是一套agentic skills framework翻译成人话就是给 AI 编程代理装上一套“技能包”和“工作纪律”让它在真实软件项目里别乱来。我先说清楚它不是什么。它不是模型不是 API也不是某个厂商的官方产品。它更像一份约定俗成的software development methodology——一套把“AI 代理该怎么拆任务、怎么验证、怎么交付”写死的流程规范。你可以把它理解成给 AI 助手准备的一份“员工手册”什么活该接、什么活要先问、改完代码怎么自测、什么时候必须停下来汇报。那它到底解决什么问题核心痛点有三个。第一AI 代理很容易“自信地犯错”一口气改十几个文件最后跑不起来还嘴硬。第二多人协作时每个人对 AI 的用法都不一样产出质量参差不齐。第三AI 缺少“技能”的概念你让它写前端它就只会写前端遇到需要跑测试、查日志、做迁移的场景就抓瞎。superpowers 这套框架就是冲着这三点去的。适合谁来参考如果你只是偶尔用 AI 补全几行代码那这套东西对你偏重。但如果你已经把 Claude Code 或 Codex CLI 当成日常主力工具甚至团队里多个人都在用那这套方法论值得花时间吃透。它不挑语言、不挑框架前端后端、脚本工具、数据处理都能套。2. 核心思路拆解为什么是“技能”而不是“提示词”2.1 技能包和提示词的本质区别大部分人用 AI 编程助手的方式是“临时写提示词”遇到问题现编一段话丢进去。这种方式的问题是不可复用、不可验证、不可协作。你今天写了一段很妙的提示词让 AI 重构了代码明天换个同事就完全复现不出来。superpowers 的思路是把这些经验固化成“技能”skill。一个技能通常包含四部分触发条件什么时候用、输入要求需要什么上下文、执行步骤怎么做、验收标准怎么算做完。这四样东西写清楚AI 代理就能在合适的时机自动调用而不是每次靠人临场发挥。我举个具体例子。假设你有一个技能叫“新增 API 端点”。触发条件是“用户要求添加新的 HTTP 接口”。输入要求是“路由文件路径、数据模型定义、现有接口风格示例”。执行步骤是“先读现有接口、再写 handler、再补测试、最后跑一遍”。验收标准是“测试通过且 lint 无报错”。你看这就把一件模糊的事变成了可执行的流水线。2.2 为什么这套框架偏爱终端代理superpowers 和 Claude Code、Codex CLI 这类终端代理是天然搭配。原因很简单终端代理能直接读写文件、执行命令、看输出。这意味着技能里的“验收标准”可以是真的跑一遍测试而不是让 AI 自己说“我觉得没问题”。图形界面的 AI 助手往往只能给你一段代码让你自己粘贴它没法验证。终端代理不一样它能npm test、能git diff、能读报错日志。superpowers 的很多设计就是围绕“让 AI 自己验证自己”展开的。这也是为什么热词里全是 claude code、codex cli 的安装配置问题——大家装这些工具本质上是想跑通这套代理工作流。2.3 方法论层面的三个原则我把 superpowers 背后的原则归纳成三条理解了这三条后面所有操作都是自然推导。第一条是小步交付。AI 一次只做一件事做完验证验证通过再进下一步。这跟传统“一口气写完再调试”完全相反。原因是 AI 的上下文窗口有限改动越大越容易失控。第二条是显式上下文。AI 不会读心术技能里必须明确告诉它该看哪些文件、该遵守哪些约定。很多“AI 改错代码”的案例根因不是模型笨而是人没给够上下文。第三条是可回滚。每个技能执行前都应该有干净的 git 状态执行后能一键回退。这条看起来是工程常识但在 AI 场景下尤其重要因为 AI 的改动速度和范围都远超人手操作。3. 环境准备把 Claude Code 和 Codex CLI 跑起来3.1 安装前的账号与网络认知在动手之前有几个现实问题得先摆平。热词里反复出现“claude code 注册账号和不注册有啥不同”“your organization has disabled claude subscription access”这类问题说明账号体系是第一个坎。简单说Claude Code 的完整能力依赖账号订阅未登录状态下功能受限很多技能无法调用。如果你所在的组织禁用了订阅访问那就得走第三方 API 的路子。Codex CLI 相对灵活一些它可以通过配置接入不同的模型后端。热词里提到的“使用 cc switch 接入 deepseek、qwen、glm 等模型”就是这条路。cc switch 是一个模型切换工具让你在同一个 CLI 里切换不同的模型供应商。这对国内用户特别实用因为可以绕开单一供应商的可用性问题。注意无论用哪种方式都要确保你的使用方式符合所在平台的服务条款不要尝试任何违规的访问手段。3.2 各平台安装步骤实录macOS 安装 Claude Code相对最顺。官方推荐用 npm 全局安装前提是你机器上有 Node.js 18 以上版本。命令是npm install -g anthropic-ai/claude-code装完直接敲claude就能进交互界面。如果提示权限问题前面加sudo但更推荐用 nvm 管理 Node 版本避免权限坑。Ubuntu 安装 Claude Code步骤基本一致但要注意两点。一是系统自带的 Node 版本可能太老建议先用 nvm 装一个新版。二是如果遇到EACCES报错别急着sudo先检查 npm 的全局目录权限。我踩过的坑是 Ubuntu 上默认 npm prefix 指向系统目录改一下npm config set prefix ~/.npm-global再配好 PATH 就干净了。Windows 安装是最容易出问题的。热词里“claude code 由于与64位版本的 windows 不兼容”这个报错通常是因为装了 32 位的 Node 或者用了不兼容的终端。解决办法是确保装 64 位 Node并且用 Windows Terminal 或者 Git Bash 而不是老旧的 cmd。如果实在搞不定WSL2 是最省心的方案直接当 Ubuntu 用。Codex CLI 安装走的是另一条路。它通常通过 npm 或直接下载二进制安装。装完第一件事是配置模型后端编辑配置文件指定 API 端点和密钥。热词里“codex cli 命令哪些 /compact /model /resume”说明大家很关心它的交互命令这几个后面会专门讲。3.3 VS Code 集成配置很多人不满足于纯终端想把 Claude Code 接进 VS Code。热词里“claude code for vs code”“vscode接入claude code”“claude code vscode插件配置解释”都是这个需求。做法是装官方或社区的 VS Code 扩展然后在设置里填好 CLI 路径和模型配置。这里有个细节值得说VS Code 集成后AI 能看到你当前打开的文件和光标位置上下文更精准。但也要注意别让它自动改你没打开的文件容易出意外。我的习惯是集成归集成真正跑大改动还是回终端因为终端里 git diff 看得更清楚。4. 技能框架的落地从零搭一套可用的工作流4.1 目录结构与技能文件组织superpowers 这类框架落地时第一件事是定目录结构。我推荐在项目根目录建一个.agent/skills/文件夹每个技能一个 Markdown 文件。文件名用动词开头比如add-api-endpoint.md、fix-failing-test.md、refactor-module.md。这样 AI 扫描目录时一眼就能匹配到相关技能。每个技能文件内部建议固定结构一段简短的用途说明、触发条件、前置检查、执行步骤、验收命令、回滚方式。别小看这个结构它逼着你在写技能的时候就想清楚“这活到底怎么算干完”。很多团队用 AI 出问题就是因为从来没定义过“完成”的标准。4.2 一个完整技能文件的写法我拿“修复失败测试”这个高频场景举例。用途说明写“当测试套件出现失败用例时定位并修复根因”。触发条件是“用户报告测试失败或 CI 红灯”。前置检查要求“git 工作区干净能复现失败”。执行步骤分四步先跑测试拿到完整报错、再读相关源码和测试代码、再定位根因、再改代码。验收命令就是重跑那一条测试直到通过。回滚方式是git checkout相关文件。关键在于验收命令必须是可执行的不能写“确认逻辑正确”这种废话。AI 需要一条能跑的命令来自己判断成败。这是 superpowers 和普通提示词最大的区别它把“验证”变成了流程里的硬性环节而不是靠人肉检查。4.3 技能之间的组合与调用单个技能好用但真正的威力在组合。比如“新增功能”这个大任务可以拆成“新增 API 端点”“补单元测试”“更新文档”三个技能串起来。AI 代理按顺序执行每个技能跑完验收再进下一个。这样即使中间某步失败也不会污染后面的步骤。组合的时候要注意依赖关系。有些技能必须在特定技能之后跑比如“部署”必须在“测试通过”之后。我建议在技能文件里加一个depends_on字段明确声明前置技能。这样代理在调度时就不会乱序执行。5. 终端代理的日常操作与命令详解5.1 Claude Code 常用交互命令进了 Claude Code 的交互界面后有几个命令是天天要用的。/compact用来压缩对话历史当上下文快满的时候跑一下能腾出空间继续干活。/model切换模型不同任务用不同模型能省不少成本简单改动用小模型复杂重构用大模型。/resume恢复之前的会话这个在中断后继续工作时特别有用。还有一个高频需求是“claude code 如何直接执行终端命令”。答案是它本来就能执行但默认会问你确认。你可以在配置里调整权限策略让某些安全命令免确认。不过我的建议是保持确认尤其是涉及删除、覆盖的操作多按一次回车能省很多后悔。5.2 Codex CLI 的命令体系Codex CLI 的命令风格和 Claude Code 略有不同。它的/compact和/model逻辑类似但/resume的行为要看具体版本。热词里“删除codex cli指令”说明有人想清理历史或卸载卸载一般就是 npm uninstall 加删配置目录。Codex CLI 有个特色是它对“remotion”这类特定工作流的支持热词里“codex cli remotion”就是这个。如果你做视频相关的自动化可以研究一下它在这块的技能扩展。不过大部分人的日常还是写代码、跑测试、改 bug 这三件事。5.3 第三方 API 接入的配置要点想用 DeepSeek、Qwen、GLM 这些模型替代默认后端核心是改配置文件里的 base URL 和 API key。cc switch 这类工具就是帮你管理多套配置一键切换。配置的时候注意三点一是确认模型的上下文长度够不够你的项目二是确认它支持工具调用function calling否则代理没法执行命令三是注意计费和限流。提示切换模型后先拿一个小任务试跑确认工具调用正常再上大任务。不同模型对技能文件的理解能力差异很大同一个技能在 A 模型上跑得顺换 B 模型可能就卡住。6. 常见问题与排查技巧实录6.1 安装与账号类问题速查问题现象可能原因解决思路提示组织禁用了订阅访问账号权限受限改用第三方 API 后端提示所在地区不可用服务可用性限制检查官方支持列表考虑替代方案Windows 报 64 位不兼容Node 位数或终端问题换 64 位 Node用 WSL2安装后命令找不到PATH 未配置检查 npm 全局目录并加入 PATH这张表里的问题我基本都遇到过。最坑的是 PATH 问题装完了敲命令提示 not found折腾半天发现是 shell 配置文件没重载。解决办法就是source ~/.zshrc或者重开终端。6.2 运行时的典型故障AI 代理跑着跑着卡住最常见的原因是上下文塞满了。这时候/compact或者开新会话。另一个高频问题是 AI 反复改同一个文件改不对根因通常是它没读到关键上下文比如没看测试文件或者没看类型定义。这时候手动把相关文件路径喂给它比让它自己瞎找快得多。还有一种情况是 AI 执行了危险命令。虽然默认有确认机制但如果你放开了权限一定要确保 git 状态干净。我个人的铁律是任何 AI 大改动之前先 commit 一次。这样出问题一个git reset --hard就回来了比任何撤销机制都可靠。6.3 我的避坑心得用了大半年这类工具我总结出几条血泪经验。第一别让 AI 一次改超过三个文件超过就拆任务。第二技能文件里的验收命令一定要自己先手动跑通确认它真的能判断成败。第三模型切换后重新校准别指望换个模型行为完全一致。第四团队协作时把技能文件纳入版本控制让所有人的 AI 行为一致。最后分享一个提效小技巧把项目里最常做的五件事写成技能文件坚持两周你会发现 AI 的产出稳定性有明显提升。技能库这东西是越用越值钱的前期投入的时间很快就能从减少的返工里赚回来。