1. 为什么你的 Claude Code 需要 Superpowers如果你已经在用 Claude Code 写代码大概率遇到过这种场面你刚描述完需求它立刻开始输出大段实现目录结构、依赖、命名全凭当场发挥等你 review 时才发现它压根没问过你“这个模块边界怎么划”“异常路径要不要重试”。更麻烦的是换个会话它就像失忆一样上次定好的接口约定、错误码规范全部归零同一个坑你得踩第二遍。Superpowers 就是冲着这个毛病来的。它本质上是给 Claude Code 装了一套强制性的工程化工作流在写代码之前先逼着 Agent 完成需求澄清、方案设计、任务拆解然后才进入 TDD 循环和代码审查。它把“先想清楚再动手”从一句口号变成了硬门禁——头脑风暴、计划拆解、TDD 执行、代码审查四道关卡任何一道没过都进不到下一步。但这里有个容易被忽略的前提Superpowers 的工作流会频繁调用模型会话轮次比裸用 Claude Code 多出好几倍。如果你还在用零散的临时 Key或者每个项目配一套不同的接入方式很快就会遇到额度分散、切换麻烦、团队里每个人配置都不一样的问题。所以这篇指南的路线是先用 TaoToken 把 Key 和 API 通道统一起来再在这个基础上接入 Superpowers让整套工程化流程真正可复现。适合谁看已经在用 Claude Code 但产出质量不稳定的开发者想把 AI 编程从“能跑就行”升级到“可维护、可交接”的团队以及准备在项目里落地 TDD 但缺一套自动化触发机制的人。2. 前置准备用 TaoToken 统一 Key 与 API 通道Superpowers 本身是 Claude Code 的插件它不关心你的 Key 从哪来只要求 Claude Code 能正常调用模型。所以统一入口这件事落在 Claude Code 的配置层。TaoToken 在这里扮演的角色是给你一个稳定的 API 地址和一把 KeyClaude Code、Codex、Cursor 这些工具都指向同一个通道省得每个工具单独维护一套凭证。先拿到凭证。打开 https://taotoken.net/api-keys 创建一个 API Key复制出来存好。这个 Key 后面会同时写进 Claude Code 的 settings.json 和 Codex 的 config.toml是整套流程的公共入口。关于接入地址记住两个官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 基址https://taotoken.net/api 这个不加 UTM配置里直接写注意API 基址不要带查询参数配置文件里多一个字符都可能导致请求 404。Key 只放在本地配置文件或环境变量里别提交到 Git。如果你还没决定用哪种方式管理 Key我的建议是个人开发用环境变量团队协作用配置文件加 .gitignore。下面两节分别给出骨架。3. 可复制配置settings.json 与 config.toml 骨架Claude Code 的配置走 settings.jsonCodex 走 config.toml。两个文件我都给一份最小可用骨架你按自己的路径改。3.1 Claude Code 的 settings.jsonClaude Code 读取配置的位置通常在用户目录下的.claude/settings.json项目级可以放.claude/settings.json在仓库根目录。核心是把 API 基址和 Key 指到 TaoToken。{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥 }, permissions: { allow: [ Bash(git status), Bash(git diff:*), Bash(npm test:*), Bash(pytest:*) ] } }这里有两个点值得说。第一ANTHROPIC_BASE_URL指向 TaoToken 的 API 基址Claude Code 会把所有模型请求发到这里你不需要改任何插件代码。第二permissions.allow里我预置了几条常用命令Superpowers 的 TDD 流程会频繁跑测试和看 diff提前放行能减少每步的确认弹窗。你可以按项目实际测试命令增删比如用go test就换成Bash(go test:*)。3.2 Codex 的 config.toml如果你同时用 Codex 跑一些辅助任务config.toml 的骨架如下位置一般在~/.codex/config.tomlmodel claude-sonnet-4-20250514 model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY [profiles.default] model_provider taotokenenv_key指向环境变量名你在 shell 里 export 一次就行export TAOTOKEN_API_KEYsk-你的TaoToken密钥这样 Codex 和 Claude Code 共用同一把 Key、同一个基址切换工具时不用重新配。团队里如果有人用 Cursor也可以在它的模型设置里填同样的 base_url 和 Key保持通道一致。3.3 安装 Superpowers 插件配置好通道后装插件。Claude Code 官方市场是最省事的方式在会话里直接输入/plugin install superpowersclaude-plugins-official装完必须重启 Claude Code插件不是热加载的。重启后输入/help如果能看到superpowers:brainstorm这类命令说明装上了。也可以直接对 Agent 说一句 “Tell me about your superpowers” 验证。如果你用的是 Superpowers 自有市场命令是/plugin marketplace add obra/superpowers-marketplace /plugin install superpowerssuperpowers-marketplace其他平台的安装方式差异较大Cursor 在 Agent 对话里输入/add-plugin superpowersCopilot CLI 用copilot plugin marketplace add加copilot plugin install。这里不展开重点还是回到 Claude Code 这条主线。4. 验证请求从一次 TDD 触发看通道是否打通配置写完别急着上大项目。先用一个小任务验证整条链路TaoToken 通道是否通、Superpowers 是否激活、TDD 是否真的被强制执行。4.1 发一个带测试要求的需求在 Claude Code 会话里输入类似这样的需求用 Python 写一个函数 parse_duration(s)把 1h30m 解析成 5400 秒。 要求先写测试再写实现测试要覆盖空字符串、纯数字、带单位三种情况。如果 Superpowers 正常工作你不会立刻看到实现代码。它会先触发 brainstorming一次只问一个问题比如“空字符串你希望抛异常还是返回 0”。你回答后它继续追问直到需求边界清晰然后输出设计文档再进入 writing-plans 拆任务最后才派子代理按 TDD 执行。4.2 观察请求是否走通判断通道是否打通看两个信号。第一会话没有报 401 或连接超时说明 Key 和 base_url 正确。第二Agent 的回复里出现了设计文档和任务清单说明 Superpowers 的技能被调用了。如果它直接开始写代码多半是插件没加载回去检查是否重启过。你也可以在另一个终端跑一条最小请求单独验证 TaoToken 通道curl -s https://taotoken.net/api/v1/messages \ -H x-api-key: $TAOTOKEN_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d {model:claude-sonnet-4-20250514,max_tokens:64,messages:[{role:user,content:reply with ok}]}返回里有正常内容就说明通道没问题剩下的都是插件层的事。4.3 确认 TDD 真的在跑任务执行阶段留意子代理的动作顺序先出现一个失败的测试文件跑测试报红然后才写实现再跑测试转绿最后提交。这个红-绿-重构的节奏是 Superpowers 的硬性要求。如果你看到它跳过测试直接写实现检查一下项目里有没有 CLAUDE.md 明确写了“不使用 TDD”——用户指令优先级最高会覆盖插件默认行为。5. 本篇常见错排查配置和验证过程中下面几个问题出现频率最高我按现象、原因、处理列出来。现象一会话报 401 或 invalid api key。多半是 Key 复制时带了空格或者 settings.json 里写成了ANTHROPIC_API_KEY以外的变量名。检查 Key 字符串首尾确认变量名和 Claude Code 期望的一致。如果用的是环境变量方式确认当前 shell 真的 export 了。现象二请求 404提示路径不存在。常见原因是 base_url 写成了https://taotoken.net/api/带尾斜杠或者误加了 UTM 参数。配置里只写https://taotoken.net/api不要带任何查询字符串。现象三插件装了但命令不出现。九成是没重启 Claude Code。插件不是热加载装完必须退出会话重进。如果重启后还是没有检查安装时市场名是否拼错claude-plugins-official和superpowers-marketplace是两个不同的市场。现象四Superpowers 不触发Agent 直接写代码。先确认任务描述里有没有明确的开发意图太模糊的指令可能不触发工作流。其次检查项目根目录的 CLAUDE.md如果里面有覆盖性指令插件会遵从用户设置。最后确认插件版本旧版本可能技能名不同。现象五TDD 跑到一半卡住测试一直红。这通常不是通道问题而是任务拆解粒度不够细。回到 writing-plans 阶段把任务拆到 2-5 分钟能完成的大小。Superpowers 的设计目标就是让每个子任务足够小小到能独立验证。现象六会话中断后不知道从哪继续。Superpowers 用任务复选框作为恢复依据。中断后重开会话让它读取计划文件里已勾选的任务从下一个未勾选项继续。所以别手动删计划文件里的复选框状态。提示环境类问题比如 macOS 和 Linux 的命令差异不在 Superpowers 工作流覆盖范围内遇到这类问题先跳出流程手动修修完再回到工作流继续。6. 把工程化流程固定下来走到这里你应该已经跑通了一次完整的 Superpowers 流程TaoToken 提供统一通道settings.json 和 config.toml 固定接入方式插件负责把需求澄清、计划拆解、TDD、审查串成一条可复现的链路。接下来值得做的是把这套配置沉淀成团队资产。把 settings.json 里的 permissions 按项目测试命令补全把 CLAUDE.md 里的项目约定写清楚让每个新成员 clone 下来就能用同一套流程。需要长期跑编码任务或 Agent 工作流的可以了解下 Coding Plan 这类方案把额度管理也统一起来https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 遇到配置细节可以对照查。想先直观感受模型对话效果的从 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 进去试一轮。最后说个我自己的习惯每次开新项目先花十分钟把 settings.json 和 CLAUDE.md 写好再让 Superpowers 接手。规划阶段多花的时间会在 review 阶段成倍省回来。
