1. 为什么裸用 Claude Code 写中大型功能会翻车先说结论Superpowers 是一套用 SKILL.md 写成的工程约束层它给 Claude Code 补上了 TDD 强制流程和子 Agent 隔离执行。适合谁适合那些用 Claude Code 写三个月后还要维护的代码、但发现迭代到第三小时质量就开始下滑的人。它不锁定模型不依赖私有运行时本质上是把工程方法论编码成 Markdown 文件通过 hook 注入到会话里。我试过裸用 Claude Code 写一个订单状态流转模块前两周跑得好好的第三周加退款逻辑时它顺手重构了状态机把一个处理异常支付渠道的边界状态合并掉了——那个状态生产上有 0.3% 概率触发没有测试覆盖悄悄坏掉上线后客服系统才报警。这不是模型的 bug是上下文无记忆的 AI 在长周期迭代中天然会侵蚀没有显式约束覆盖的代码区域。Superpowers 解决的就是这个隐蔽隐患。它的全部实现就是一套 SKILL.md 文件当前版本包含 14 个核心技能分开发流程、质量保证、调试与元技能三类。会话启动时框架通过 hook 注入一个小于 2000 tokens 的引导文档告诉 Claude 开始任何任务前先读取相关 Skill。这个设计让整个框架极度轻量跨 Claude Code、Cursor、Gemini CLI、Codex CLI 都能工作。下面我把 SKILL.md 骨架、settings.json 配置片段、TDD 流程约束和子 Agent 协作配置拆开讲每一步都能在本地复现。2. 前置准备TaoToken 接入与 Claude Code 环境在动手写 SKILL.md 之前得先把模型调用链路打通。Claude Code 需要一个稳定的 API 入口我用的是 TaoToken 的 API 服务它兼容 Anthropic 的接口格式配置起来不用改代码。先去官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册账号然后在控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里创建一个 API Key。创建完记得复制保存页面刷新后就看不到了。拿到 Key 之后在 Claude Code 里配置环境变量。Claude Code 读取的是ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY这两个变量export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的key如果你用的是 Claude Code 的 settings.json 配置文件可以写进~/.claude/settings.json{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的key } }这里有个坑要注意ANTHROPIC_BASE_URL后面不要加/v1Claude Code 会自己拼接路径。加了/v1会变成/v1/v1/messages直接 404。配置完可以用模型对话页面 https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 先验证一下 Key 能不能正常调用确认没问题再往下走。3. 可复制配置SKILL.md 骨架与 settings.jsonSuperpowers 的核心是 SKILL.md 文件。每个 SKILL.md 就是一套流程规范用 Markdown 写成任何人打开都能读懂。下面是一个 TDD 强制技能的骨架你可以直接复制到项目根目录的.claude/skills/tdd/SKILL.md--- name: test-driven-development description: 强制 TDD 流程没有失败的测试就不允许写实现代码 --- # TDD 强制执行 ## 核心规则 没有失败的测试就没有实现代码。这不是尽量先写测试 是字面意义上的约束。 ## 执行流程 ### RED 阶段 1. 先写测试文件覆盖正常路径和边界条件 2. 运行测试确认全部失败 3. 如果测试没有失败说明测试写错了回到第 1 步 ### GREEN 阶段 1. 写最小实现让测试通过 2. 不要提前优化不要加测试没覆盖的功能 3. 运行测试确认全部通过 ### REFACTOR 阶段 1. 在测试保护下重构 2. 每次重构后重新运行测试 3. 测试覆盖率目标 85-95% ## 违规处理 如果发现实现代码先于测试存在删除实现代码回到 RED 阶段。然后是子 Agent 协作配置。Superpowers 通过 SubagentStart hook 给子 Agent 注入上下文但 v5.1.0 里子 Agent 启动时不会自动继承主会话的引导文档这是已知问题。你可以在 settings.json 里手动配置 hook 来缓解{ hooks: { SubagentStart: [ { matcher: *, hooks: [ { type: command, command: cat .claude/skills/using-superpowers/SKILL.md } ] } ] } }这个配置的作用是每次子 Agent 启动时把using-superpowers这个激活恢复技能的内容注入进去提醒子 Agent 先读取相关 Skill 再动手。实测下来能减少子 Agent 跳过 TDD 直接开写的概率但不能完全消除遇到时手动触发using-superpowersskill 可以把它拉回来。子 Agent 的调度逻辑写在dispatching-parallel-agents这个技能里。核心思路是每个原子任务派一个全新的子 Agent子 Agent 只知道自己这一个任务的上下文执行完报告结果给协调 Agent。这样做的原因是长时间运行的单一 Agent 上下文会腐化新鲜子 Agent 的判断更干净。4. 验证请求跑一遍完整 TDD 流程配置写完了得验证 Claude Code 是不是真的按预期执行。用一个简单需求写一个 Python 函数输入月份和日期返回对应的星座名称。先在 Claude Code 里触发 brainstorming 技能/superpowers:brainstorming 我想写一个 Python 函数输入月份和日期返回对应的星座名称Claude 不会立刻写代码它会先问澄清问题输入格式是整数还是字符串非法日期怎么处理星座边界日期用固定日期还是精确分界点返回值中文还是英文这些问题就是在逼出你的隐式假设。回答完之后触发 writing-plans/superpowers:writing-plansClaude 会把实现拆成原子任务每个任务 2-5 分钟有明确的文件路径、预期改动、验证步骤。重点来了在新会话里执行这份计划不要在同一个会话里直接让 Claude 开始执行。写计划时累积的上下文会污染执行阶段的判断。新开会话后触发 TDD 技能/superpowers:test-driven-developmentClaude 的第一动作是写测试文件不是实现代码。测试文件长这样import pytest from zodiac import get_zodiac class TestGetZodiac: def test_aries(self): assert get_zodiac(4, 1) 白羊座 def test_boundary_capricorn_to_aquarius(self): assert get_zodiac(1, 19) 摩羯座 assert get_zodiac(1, 20) 水瓶座 def test_invalid_month_zero(self): with pytest.raises(ValueError): get_zodiac(0, 1)此时运行测试全部失败因为zodiac.py根本不存在pytest test_zodiac.py -v # ModuleNotFoundError: No module named zodiac这是正确的 RED 状态。Superpowers 要求看到测试失败后才允许写实现代码。然后 Claude 写最小实现ZODIAC_DATES [ (1, 20, 水瓶座), (2, 19, 双鱼座), (3, 21, 白羊座), # ... 省略其余星座 ] def get_zodiac(month: int, day: int) - str: if not (1 month 12): raise ValueError(f月份必须在 1-12 之间收到: {month}) if not (1 day 31): raise ValueError(f日期必须在 1-31 之间收到: {day}) for cutoff_month, cutoff_day, zodiac_name in ZODIAC_DATES: if month cutoff_month or (month cutoff_month and day cutoff_day): return zodiac_name return 摩羯座再次运行测试pytest test_zodiac.py -v # 18 passed in 0.12s全部通过GREEN 状态。最后触发 code review/superpowers:requesting-code-reviewClaude 会按 critical/warning/info 三个级别评审。典型输出会指出 day 验证只检查 1-31但 2 月没有 29-31 日4/6/9/11 月没有 31 日。如果业务不关心这个精度在 docstring 里注明即可。没有 critical 问题就可以继续。整个流程走下来大约 25-30 分钟你得到的不只是一个能跑的函数而是有 18 个测试用例覆盖、清晰文档、通过 Code Review 的函数。5. 本篇常见错排查配置和流程跑下来最容易卡在几个地方。报错一ANTHROPIC_BASE_URL配置后仍然 401先检查 Key 有没有多余空格再确认ANTHROPIC_BASE_URL后面没有加/v1。如果还不行去 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 重新生成一个 Key 试试有时候是复制时漏了字符。报错二子 Agent 跳过 TDD 直接写实现这是 v5.1.0 的已知问题子 Agent 启动时不会自动继承主会话的引导文档。先确认 settings.json 里的 SubagentStart hook 配置生效了然后在子 Agent 会话里手动触发using-superpowersskill。如果还是不行检查 SKILL.md 文件的路径是不是写对了hook 命令里的相对路径是相对于项目根目录的。报错三/plugin install命令找不到官方市场安装不了的话用社区市场/plugin marketplace add obra/superpowers-marketplace /plugin install superpowerssuperpowers-marketplace安装完重启 Claude Code在新会话里输入/help能看到 Superpowers 命令列表就说明成功了。报错四测试覆盖率上不去Superpowers 把测试覆盖目标设在 85-95%低于 80% 在第二次迭代时 regression 概率会显著上升。如果覆盖率卡在 70% 左右检查是不是只测了正常路径边界条件和错误输入没覆盖。TDD 流程要求先写测试再写实现如果实现代码先于测试存在框架要求删掉实现代码重来。报错五Brainstorming 阶段 Claude 不提问直接写代码说明引导文档没有注入成功。检查.claude/skills/目录下有没有using-superpowers这个技能文件以及 settings.json 里的 hook 配置有没有语法错误。JSON 格式错误会导致整个 hook 静默失效。6. 长期编码与 Agent 协作的配置建议如果你打算把 Superpowers 用在跨天的长任务上有几个配置建议。第一把 TDD 的覆盖率要求写进 SKILL.md 里不要依赖默认值。团队如果有特殊规范比如所有函数必须有 type hints直接加一条检查规则进去。框架把工程文化编码成文件而不是锁进平台这是刻意的设计决策。第二子 Agent 的任务颗粒度控制在 2-5 分钟。任务太大子 Agent 的上下文还是会腐化任务太小调度开销超过收益。writing-plans 技能会自动帮你拆但你可以 review 计划文档把不合理的颗粒度调一下。第三长任务用 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 的额度更划算。Superpowers 的 7 阶段流程会消耗比裸用更多的 token前期 Brainstorming 和 Writing Plans 大约多花 10-20 分钟但产出的代码有 85% 测试覆盖后续需求变更时的修改成本大幅降低。第四接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里有完整的 API 参数说明遇到请求格式问题可以先查文档。Claude Code 的接入配置在文档里有专门一节包括 settings.json 的完整字段说明。一个实用的判断标准这个改动如果出了问题修复成本超过 30 分钟吗是的话走 Superpowers 流程值得。单行 bug fix 或者不打算长期维护的 quick prototype直接用裸 Claude Code 更合适。框架是为中大型功能开发优化的不是为快速修改优化的。