1. 先搞清楚 Superpowers 到底在解决什么问题如果你用过 Claude Code 做稍微复杂一点的需求大概率遇到过这种场面你描述完需求它二话不说开始写代码写完告诉你已完成。你打开文件一看逻辑能跑但边界条件没处理、没有测试、命名风格和你项目里其它模块完全两套。你回头补一句下次先写测试它答应得很好换个新会话又忘得一干二净。这不是模型能力问题而是什么时候该做什么这件事默认不在它的执行路径里。Agent 每次任务都是全新上下文没有跨会话的肌肉记忆。你靠提示词反复叮嘱本质是在用自然语言做流程编排稳定性完全取决于模型当次的理解和上下文有没有被挤掉。Superpowers 这个技能框架Agentic Skills换了个思路把先规划、再写测试、再评审这些工程动作拆成一个个结构化的 SKILL 文件再通过一条常驻的引导指令要求 Agent 在动手前先检查有没有相关技能该触发。于是 TDD、写计划、代码评审从你求它做变成开工前的默认检查项。它适配 Claude Code、Codex、Cursor、Gemini CLI 等十多个智能体MIT 协议开源是目前 Agentic Skills 方向最主流的参考实现之一。这篇文章聚焦落地怎么在 Claude Code 里把 Superpowers 装好、配置好怎么验证它真的会触发 TDD 流程以及踩过的坑怎么排。适合已经用 Claude Code 写业务代码、想让 AI 按固定工程流程推进的开发者。如果你只是偶尔让它改个变量名这套东西的流程开销反而碍事可以先跳过。需要说明的是Superpowers 负责流程编排模型调用本身仍然走你自己的 API 通道。下面配置里我会用 TaoToken 的 API 地址作为示例 Base URL你可以替换成自己实际使用的端点重点是配置结构和验证方法。2. 前置准备Claude Code 环境与 TaoToken 接入配置在装技能框架之前先把底层通道理顺。Claude Code 需要三样东西可用的 API Base URL、API Key、以及明确的 Model ID。这三件套缺一个都会在启动时报错而且报错信息往往不直观所以先配好再谈技能。TaoToken 的控制台入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 登录后进 API Keys 页面创建密钥。创建时建议按项目命名比如claude-code-dev方便后续轮换时定位。密钥只在创建时完整显示一次复制后立刻存进本地环境变量不要写进会提交到 Git 的文件。Claude Code 读取配置的方式有两种环境变量或者项目级/用户级的 settings 文件。我建议用 settings 文件因为可复制、可版本化管理团队里其他人拉下来改个 Key 就能用。用户级配置放在~/.claude/settings.json项目级放在项目根目录的.claude/settings.json。项目级优先级更高适合给不同仓库配不同模型。一个可复制的最小配置片段如下注意 JSON 里不能有注释路径按你实际环境调整{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的密钥粘贴在这里, ANTHROPIC_MODEL: claude-sonnet-4-5-20250929, ANTHROPIC_SMALL_FAST_MODEL: claude-haiku-4-5-20251001 } }这里几个字段的作用要分清ANTHROPIC_BASE_URL指向 API 网关地址注意不要带末尾斜杠也不要拼上/v1Claude Code 会自己补路径ANTHROPIC_AUTH_TOKEN放你的密钥ANTHROPIC_MODEL是主模型负责规划和写代码ANTHROPIC_SMALL_FAST_MODEL用于标题生成、文件摘要这类轻量调用配个小模型能明显省钱。如果你更习惯环境变量等价写法是在 shell 配置文件里导出export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你的密钥 export ANTHROPIC_MODELclaude-sonnet-4-5-20250929配完先别急着装 Superpowers用一条最朴素的命令验证通道是否通claude -p 回复两个字通了如果返回通了说明 Base URL、Key、Model ID 三件套都对。如果报 401说明 Key 无效或没被读到如果报连接失败先检查 Base URL 有没有多写路径。这一步过了再进入技能安装否则后面出问题你分不清是通道问题还是技能问题。3. 安装 Superpowers 技能框架与可复制配置片段Superpowers 在 Claude Code 里有两条安装路线我建议优先走官方插件市场因为技能和引导指令一次配齐不用手动维护文件。路线 A在 Claude Code 交互界面里直接敲斜杠命令/plugin install superpowersclaude-plugins-official这条命令从 Anthropic 官方插件市场拉取装完技能目录和 bootstrap 引导指令都会就位。路线 B 是走 Superpowers 自己的市场适合你还想装它家其它关联插件的情况/plugin marketplace add obra/superpowers-marketplace /plugin install superpowerssuperpowers-marketplace装完之后技能文件会落在 Claude Code 的插件目录下通常是~/.claude/plugins/下面按插件名分的子目录。你可以用ls确认一下有没有superpowers相关目录里面应该能看到一堆.md结尾的 SKILL 文件比如brainstorming、writing-plans、test-driven-development、requesting-code-review这些。如果你所在的环境不方便用插件市场也可以手动克隆仓库再软链到插件目录但这种方式升级要自己拉代码不如插件市场省心。手动方式大致是git clone https://github.com/obra/superpowers.git ~/.claude/plugins/superpowers然后在~/.claude/settings.json里确认插件目录被扫描到。不同 Claude Code 版本对插件目录的约定略有差异装完用/plugin list看一眼有没有列出来最稳妥。关于遥测Superpowers 默认会从服务端加载一个视觉组件用于统计使用情况不含项目内容和提示词。介意的话在 settings 的 env 里加一条{ env: { SUPERPOWERS_DISABLE_TELEMETRY: 1 } }这个字段和前面的 API 配置放在同一个env对象里即可不要重复写两个env键JSON 重复键会导致后者覆盖前者这是很常见的配置事故。装完技能后还有一个容易被忽略的点引导指令bootstrap是否真的注入了会话。Superpowers 的核心机制是每次任务前检查相关技能这条规则靠常驻指令维持。如果插件装了但引导没生效技能文件躺在磁盘上也不会被触发。验证方法在下一节。4. 验证 AI 是否真的触发 TDD 流程装完不等于生效。技能框架最怕的就是悄悄失效——你以为它在跑流程其实模型根本没读技能。所以必须做行为验证而不是看安装日志。第一个验证点用一句最朴素的提示测试 brainstorming 是否自动触发Lets make a react todo list如果 Superpowers 生效Claude Code 不会立刻开始写代码而是先反问你需求数据存哪里、要不要持久化、单用户还是多用户、UI 风格偏好。这就是brainstorming技能被激活的表现。如果它直接甩给你一个App.jsx说明引导指令没生效回到上一节检查插件是否被/plugin list识别。第二个验证点专门测 TDD。给它一个带明确行为的需求比如给 utils/date.ts 加一个 formatRelative 函数输入时间戳返回3分钟前这种相对时间观察它的动作顺序。走 TDD 流程时它应该先写一个会失败的测试文件比如utils/date.test.ts运行测试看到 RED然后写最小实现让测试变 GREEN最后才提交。你可以在它执行过程中看终端输出测试命令跑了几次、第一次是不是失败这些是硬证据。第三个验证点测代码评审。在一个任务完成后看它有没有主动调用requesting-code-review技能对照计划检查改动、按严重级别列问题。如果它写完就说完成没有任何评审动作说明技能触发链路在某处断了。我实测下来最可靠的判断方式是看它有没有先问再做。Superpowers 的设计哲学是开工前先澄清所以任何直接动手写代码的行为都是反例。你可以故意给一个模糊需求比如优化一下这个接口看它是直接改还是先问清楚优化目标性能、可读性、还是错误处理。先问说明流程在跑。还有一个细节技能触发是有 token 开销的每轮都要做一次有没有相关技能的检查。所以小改动时你会感觉它话变多了这是正常现象不是配置错误。5. 常见报错排查401、local proxy failed 与技能不触发配置和验证过程中几类报错出现频率最高逐个说清楚。401 未授权。典型输出是API Error: 401 {error:{message:invalid api key}}。原因通常是三个Key 复制时带了空格或换行settings 文件里ANTHROPIC_AUTH_TOKEN拼写错了注意是 AUTH_TOKEN 不是 API_KEY或者环境变量和 settings 同时存在且值不一致后者覆盖了前者。排查顺序是先echo $ANTHROPIC_AUTH_TOKEN看环境变量再检查 settings 文件确保只有一处生效。另外确认 Base URL 是https://taotoken.net/api不要写成带/v1/messages的完整路径。local proxy failed / connection refused。这类报错说明 Claude Code 尝试连的地址根本不通。常见原因是 Base URL 末尾多了斜杠或者写成了https://taotoken.net/api/拼接后变成双斜杠路径。也可能是本地网络策略拦截了出站请求。先用curl -I https://taotoken.net/api看能不能拿到响应头能通再回来看配置。如果 curl 通但 Claude Code 不通检查是不是有全局代理环境变量HTTP_PROXY在干扰临时unset掉再试。reading choices / 响应解析失败。报错里出现reading choices或类似字段通常意味着返回体不是预期的对话格式可能是网关返回了错误页 HTML或者模型 ID 写错导致路由到了不支持的端点。核对ANTHROPIC_MODEL的值是否拼写正确以及该模型是否在你的账户权限内。换一个确定可用的模型 ID 做对照测试能快速定位是模型问题还是通道问题。OAuth 相关报错。如果你之前用官方账号登录过 Claude Code本地可能残留 OAuth 凭据和 API Key 模式冲突。表现是启动时提示认证失败或反复跳转。处理方式是清理~/.claude/下的凭据缓存文件或者在启动时明确使用 API Key 模式。具体文件名随版本变化进目录看一眼带auth或credential字样的文件即可。技能装了但不触发。这个最隐蔽。先确认/plugin list里有 superpowers再确认当前会话是新开的旧会话不会热加载新插件然后检查引导指令有没有被系统提示挤掉——超长会话在压缩上下文后bootstrap 可能失效这时新开一个会话通常就恢复了。Superpowers 自带一个诊断技能直接对它说figure out what went wrong with superpowers in this session它会读会话记录用行级证据告诉你哪一步该触发但没触发。这个自查能力是它区别于普通提示词合集的关键设计排障时优先用。6. 把工程规范固化为可复用技能下一步怎么走装好、验证通、排障有手段之后真正的价值在于把这套机制用起来而不是装完就放着。第一件事把团队约定写进项目级配置。比如你们要求所有新功能必须有测试、PR 前必须过 lint这些可以在项目根目录的.claude/settings.json里配合技能触发点固化下来。项目级配置优先级高于用户级团队成员拉下代码就继承同一套流程不用每个人口头叮嘱。第二件事学会写自己的技能。Superpowers 自带writing-skills技能教你怎么把一条团队规范写成结构化的 SKILL 文件。比如你们有一套特定的错误码规范、日志格式、或者数据库迁移流程都可以写成技能让 Agent 在对应场景自动触发。这才是工程肌肉记忆的真正含义——不是记住某一次对话而是把规范变成可复用的资产。第三件事控制流程开销。强制流程在复杂任务上收益最大在小修小补上是纯摩擦。我的做法是按任务规模切换跨多文件、涉及新逻辑的需求走完整流程改个文案、调个样式就直接说跳过流程只改这一处。技能是默认行为不是不可关闭的枷锁明确告诉它跳过是允许的。如果你还没配好底层通道先去 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 创建密钥再按第 2 节的 JSON 片段填进 settings。想先确认模型对话是否正常可以用模型对话页面发一条测试消息长期跑编码任务、需要稳定额度的话Coding Plan 更适合持续使用。接入细节和字段说明在接入文档里有完整对照遇到本文没覆盖的报错可以去查。最后给一个实用建议装完 Superpowers 的第一周刻意观察它每次任务的第一个动作。如果连续三次都是先问再做说明流程真的内化了如果又开始直接写代码就新开会话并跑一次诊断技能。这套框架的价值不在于装的那一刻而在于你能否通过验证和排障让它持续按预期运转。