1. 为什么裸用 Claude Code 写三天代码就开始失控先说一个我观察到的现象很多人第一次用 Claude Code 写一个完整功能前两小时体验极好代码干净、逻辑清晰、测试也顺手补了。但到了第二天、第三天同一个项目继续迭代问题开始冒出来——函数越来越长、边界条件处理前后不一致、某个模块悄悄改了另一个模块依赖的隐式假设最后跑起来报错你还得回头翻半天对话记录找是哪一步埋的雷。这不是模型变笨了是上下文无记忆这个根本特性在长周期开发里被放大了。Claude 每次生成代码都是当前上下文的最优解但当前上下文不等于完整需求。它不知道两周前你定过一条规则也不知道某个看起来多余的状态分支其实是处理异常支付渠道的。没有显式约束覆盖的代码区域会被后续迭代一点点侵蚀。Superpowers 这个框架要解决的正是这件事。它不是让 AI 更聪明是给 AI 一套工程纪律。截至 2026 年 5 月这个由 Jesse Vincentobra维护的框架已经积累了 204K GitHub Stars、18.2K Forks在 Anthropic 官方插件市场的安装量超过 68 万次是 Claude Code 生态里增长最快的插件之一。v5.1.0 在 2026 年 4 月 30 日发布仍在快速迭代。它的实现方式很朴素整套框架就是一堆 SKILL.md 文件每个文件是一套用 Markdown 写成的流程规范任何人打开都能读懂。没有自己的运行时不锁定模型不依赖私有 API。当前版本包含 14 个核心技能分三类——开发流程类brainstorming、writing-plans、executing-plans、subagent-driven-development、using-git-worktrees、finishing-a-development-branch、质量保证类test-driven-development、requesting-code-review、receiving-code-review、verification-before-completion、调试与元技能类systematic-debugging、writing-skills、using-superpowers、dispatching-parallel-agents。会话启动时框架通过 Claude Code 的 hook 机制注入一个小于 2000 tokens 的引导文档告诉 Claude 开始任何任务前先读取相关 Skill。这个设计让整个框架极度轻量跨 Claude Code、Cursor、Gemini CLI、GitHub Copilot CLI、Codex CLI 都能工作。但这里有个已知的取舍子 Agent 启动时不会自动继承这个上下文注入导致子 Agent 有时会跳过 TDD 这类约束直接开写。框架目前通过 SubagentStart hook 部分缓解v5.1.0 里仍是已知问题。遇到时手动触发using-superpowersskill 可以把它拉回来。这篇文章要交付的是三样东西一份可复制的 SKILL.md 骨架、子 Agent 协作边界的配置片段、以及如何通过 TaoToken 统一 Key 和 API 通道把整套流程接起来。适合已经在用 Claude Code、但被长周期迭代里的隐蔽工程隐患折磨过的开发者。2. TaoToken 前置统一 Key 与 API 通道接入 Claude Code在讲 SKILL.md 之前得先把接入通道理清楚。因为 Superpowers 本身不提供模型通道它只是流程约束层真正跑推理的还是 Claude Code 背后的模型。如果你同时用 Claude Code、Cursor、Codex CLI 好几个工具每个工具单独配 Key、单独管额度很快就会乱。TaoToken 在这里的作用是提供一个统一的 Key 和 API 通道。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 这个地址不加 UTM 参数。你可以在控制台里生成一个 Key然后在各个工具里复用同一个 Base URL 和 Key。具体到 Claude Code配置方式是通过环境变量或者 settings 文件。Claude Code 读取的是ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY这两个变量。如果你想让 Claude Code 走 TaoToken 的通道可以这样设置export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的TaoToken密钥Windows 下用 PowerShell$env:ANTHROPIC_BASE_URLhttps://taotoken.net/api $env:ANTHROPIC_API_KEYsk-你的TaoToken密钥如果你更喜欢写进配置文件而不是每次 exportClaude Code 支持在项目根目录放.claude/settings.json或者在用户目录放全局配置。项目级的 settings 片段长这样{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥 } }这里有个细节要注意Base URL 填的是https://taotoken.net/api不要在后面加/v1或者别的路径Claude Code 会自己拼接。Key 从控制台的 API Keys 页面生成生成后只显示一次记得存好。模型 ID 这块Claude Code 默认会请求claude-sonnet-4-5这类模型名。TaoToken 的通道兼容 Anthropic 的模型命名你不需要在 Claude Code 里额外指定 Model ID它会按默认的走。如果你在别的工具比如 Cline、Codex CLI里需要显式填 Model ID那就填claude-sonnet-4-5或者你实际要用的那个。配好之后验证一下通道是否通。最直接的方式是在 Claude Code 里发一条消息看它能不能正常回复。如果报 401说明 Key 不对或者没生效如果报连接超时检查 Base URL 有没有写错。这一步先跑通再往下装 Superpowers否则后面出问题你分不清是通道问题还是框架问题。关于 Coding Plan 这类长期编码场景如果你打算把 Claude Code 当成日常主力工具可以了解一下 TaoToken 的 Coding Plan它针对长时间、高频次的编码会话做了额度优化。入口在 https://taotoken.net/api-keys 旁边的套餐页面具体选哪个档位看你的日均 token 消耗。3. 可复制配置SKILL.md 骨架与子 Agent 协作边界Superpowers 的核心就是 SKILL.md 文件。每个文件定义一套流程规范Claude 在执行任务前会读取对应的 Skill。你可以直接改官方提供的 Skill也可以自己写新的。下面给一份 TDD 流程的 SKILL.md 骨架你可以直接复制到项目里用。先看目录结构。Superpowers 安装后Skill 文件通常在~/.claude/plugins/superpowers/skills/下面。如果你想自定义建议在项目根目录建一个.claude/skills/目录把自定义的 SKILL.md 放进去Claude Code 会优先读取项目级的。一份 TDD 强制流程的 SKILL.md 骨架--- name: tdd-enforcement description: 强制测试先行没有失败的测试不允许写实现代码 --- # TDD 强制执行规范 ## 核心规则 没有失败的测试就没有实现代码。这不是建议是硬性约束。 ## 执行流程 ### 第一步RED 状态 在写任何实现代码之前先写测试文件。测试必须覆盖 - 正常路径happy path - 边界条件boundary cases - 错误输入invalid input 写完测试后立即运行确认全部失败。如果测试通过了说明测试写错了重写。 ### 第二步GREEN 状态 写最小实现代码让测试通过。不要提前优化不要加测试没覆盖的功能。 运行测试确认全部通过。 ### 第三步REFACTOR 状态 在测试保护下重构。每次重构后重新运行测试确认仍然全绿。 ## 禁止行为 - 禁止在没有失败测试的情况下写实现代码 - 禁止跳过 RED 状态直接写实现 - 禁止在测试未通过时继续添加新功能 - 如果发现实现代码先于测试存在删除实现代码回到 RED 状态 ## 覆盖率要求 目标覆盖率 85%-95%。低于 80% 时第二次迭代 regression 概率显著上升高于 95% 时写测试的时间投入超过收益。这份骨架的关键在于禁止行为那一段。Superpowers 的 TDD 不是尽量先写测试是字面意义上的——如果发现子 Agent 在没有失败测试的情况下写了实现代码框架要求删掉那段代码回到测试先行的状态。RED → GREEN → REFACTOR循环不跳步。接下来是子 Agent 协作边界的配置。Superpowers 的 subagent-driven-development 技能会把每个原子任务派给一个全新的子 Agent子 Agent 只知道自己这一个任务的上下文执行完报告结果给协调 Agent。这个设计的逻辑是长时间运行的单一 Agent 上下文会腐化新鲜子 Agent 的上下文是干净的判断也是干净的。子 Agent 的配置片段通常写在 Skill 文件里定义它的职责边界。一份子 Agent 协作边界的配置骨架--- name: subagent-boundary description: 定义子 Agent 的职责范围与协作规则 --- # 子 Agent 协作边界 ## 子 Agent 职责 每个子 Agent 只负责一个原子任务任务颗粒度控制在 2-5 分钟。 子 Agent 启动时必须 1. 读取当前任务的 spec 文件 2. 确认任务的输入输出定义 3. 检查是否有对应的失败测试 4. 如果没有失败测试先写测试再写实现 ## 子 Agent 禁止行为 - 禁止修改任务范围之外的文件 - 禁止跳过 TDD 流程 - 禁止在未确认测试通过的情况下报告任务完成 - 禁止假设其他子 Agent 的上下文 ## 协调 Agent 职责 协调 Agent 负责 1. 把大任务拆解成原子任务 2. 为每个原子任务生成 spec 3. 派发子 Agent 执行 4. 收集子 Agent 的执行结果 5. 在任务之间触发 Code Review ## 上下文隔离规则 子 Agent 不继承主会话的 Superpowers 引导文档。如果子 Agent 跳过了 TDD 约束协调 Agent 需要手动触发 using-superpowers skill 把它拉回来。这份配置的核心是上下文隔离规则那一段。因为子 Agent 启动时不会自动继承主会话的引导注入这是 v5.1.0 的已知问题。你需要在协调 Agent 的逻辑里加一步每次派发子 Agent 之前确认它是否加载了 TDD 约束如果没有手动触发一次using-superpowers。如果你用的是 Cline 或者 Codex CLI配置方式略有不同。Cline 的 MCP 配置里需要填 Base URL、Key 和 Model ID 三件套{ mcpServers: { taotoken: { url: https://taotoken.net/api, apiKey: sk-你的TaoToken密钥, model: claude-sonnet-4-5 } } }Codex CLI 的auth.json配置{ base_url: https://taotoken.net/api, api_key: sk-你的TaoToken密钥, model: claude-sonnet-4-5 }这三件套——Base URL、Key、Model ID——在任何工具里都是必须的。Base URL 统一填https://taotoken.net/apiKey 从控制台生成Model ID 按你实际要用的模型填。4. 验证请求从 Brainstorming 到 Code Review 跑通完整流程配置写好了得验证它真的能跑。用一个简单但覆盖完整流程的需求来测写一个 Python 函数输入月份和日期返回对应的星座名称。这个需求够简单但涵盖了边界条件处理、错误输入验证Superpowers 工作流的每个环节都能展示。先在 Claude Code 里安装 Superpowers/plugin install superpowersclaude-plugins-official这是官方 Anthropic 插件市场的安装命令。安装完成后重启 Claude Code在新会话中输入/help能看到 Superpowers 命令列表则安装成功。如果官方市场安装不了备选方案是社区市场/plugin marketplace add obra/superpowers-marketplace /plugin install superpowerssuperpowers-marketplace安装完成后触发 Brainstorming/superpowers:brainstorming 我想写一个 Python 函数输入月份和日期返回对应的星座名称Claude 不会立刻给你写代码。它会先问一系列澄清问题比如输入格式是整数还是字符串、非法日期怎么处理、星座边界日期是否需要精确、返回值是中文还是英文。这就是 Brainstorming 的核心价值它把你的隐式假设逼出来。你回答之后Claude 有了清晰的合约。然后生成计划/superpowers:writing-plansClaude 会把实现拆成原子任务每个任务有明确的文件路径、预期改动、验证步骤。重点在新会话里执行这份计划不要在同一个会话里直接让 Claude 开始执行。打开新的 Claude Code 会话把计划粘贴进去再开始。接下来是 TDD 执行。Claude 的第一动作是写测试文件不是实现代码# test_zodiac.py 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)此时运行测试全部失败RED 状态因为zodiac.py根本不存在pytest test_zodiac.py -v # ERROR collecting test_zodiac.py # ModuleNotFoundError: No module named zodiac这是正确的状态。Superpowers 框架要求看到测试失败后才允许开始写实现代码。然后 Claude 写最小实现# zodiac.py 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 摩羯座再次运行测试全部通过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 的函数以及一份记录了所有设计决策的对话历史。验证通道是否走的是 TaoToken可以在 Claude Code 里发一条消息然后去 TaoToken 控制台的用量页面看是否有对应的请求记录。如果有记录说明通道通了。如果控制台没有记录检查环境变量是否生效或者 settings.json 里的配置有没有被覆盖。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth配置和验证过程中最容易撞上的几类报错这里逐个对照排查。401 Unauthorized。这个最常见通常是 Key 没生效或者写错了。先检查环境变量echo $ANTHROPIC_API_KEY echo $ANTHROPIC_BASE_URL如果输出为空说明 export 没生效或者你是在新的终端窗口里跑的环境变量没继承。Windows 下检查 PowerShell 的$env:ANTHROPIC_API_KEY。如果 Key 有值但还是 401去 TaoToken 控制台确认这个 Key 是否被禁用或者额度耗尽。另外注意 Key 的前缀TaoToken 的 Key 通常以sk-开头复制的时候别把前后空格带进去。local proxy failed。这个报错通常出现在你本地配了代理但代理没启动或者端口不对。Claude Code 会读取HTTP_PROXY和HTTPS_PROXY环境变量。如果你不需要代理把这两个变量清掉unset HTTP_PROXY unset HTTPS_PROXY如果你确实需要走本地代理确认代理进程在跑端口和配置一致。这个报错和 TaoToken 本身无关是本地网络环境的问题。reading choices 相关报错。这个通常出现在 API 返回格式不符合预期时。Claude Code 期望的是 Anthropic 格式的响应如果 Base URL 填错了比如填成了 OpenAI 兼容的端点返回的 JSON 结构对不上就会报 reading choices 之类的错。确认 Base URL 是https://taotoken.net/api不要填成别的路径。如果你在 Cline 里配置Cline 可能默认走 OpenAI 格式需要在设置里切换成 Anthropic 格式或者确认 TaoToken 的通道支持你要用的格式。OAuth 相关报错。Claude Code 某些版本会尝试走 OAuth 流程如果你用的是 API Key 模式可能会冲突。检查 settings.json 里有没有残留的 OAuth 配置比如oauthAccount之类的字段。如果有删掉只保留env里的 Base URL 和 Key。另外确认你用的 Claude Code 版本支持 API Key 模式太老的版本可能只支持 OAuth。子 Agent 跳过 TDD。这个不是报错是行为异常。表现是子 Agent 直接写了实现代码没有先写测试。原因是子 Agent 启动时没有继承主会话的 Superpowers 引导文档。解决办法是手动触发using-superpowersskill/superpowers:using-superpowers这个 Skill 的作用就是重新激活工程约束。触发后子 Agent 会重新读取 TDD 规范。如果频繁出现可以在协调 Agent 的逻辑里加一步每次派发子 Agent 之前先确认它是否加载了约束。测试覆盖率不达标。Superpowers 的目标覆盖率是 85%-95%。如果 Code Review 阶段发现覆盖率低于 80%说明测试写得不够。回到 RED 状态补充边界条件和错误输入的测试用例。不要为了凑覆盖率写无意义的测试测试要覆盖真实的边界场景。worktree 创建失败。Superpowers 在写代码之前会建一个干净的 worktree 分支。如果创建失败通常是 git 仓库状态有问题比如有未提交的改动或者当前不在 git 仓库里。先git status确认状态把未提交的改动处理掉再重试。排查的顺序建议是先确认通道通401 排查再确认配置对Base URL 和 Key再确认框架加载Superpowers 命令列表最后确认子 Agent 行为TDD 约束。一层一层往下查别跳步。6. 把工程纪律编码成文件而不是锁进平台Superpowers 最值得借鉴的设计决策是把工程文化编码成 Markdown 文件而不是锁进某个平台的私有配置里。你可以改任何 Skill 来适配自己团队的规范比如把 TDD 的覆盖率要求从 85% 调到 90%或者在 Brainstorming 的问题列表里加入团队特有的检查项。v5.1.0 还加入了writing-skills这个元技能帮你规范地写出新的 Skill——框架本身的扩展也要走 TDD 和 Code Review 流程保证新 Skill 的质量。如果你打算长期用 Claude Code 做开发建议把 TaoToken 的 Key 和 Base URL 配成全局环境变量这样 Claude Code、Cursor、Codex CLI 都能复用同一个通道不用每个工具单独管。控制台在 https://taotoken.net/api-keys 生成 Key 之后存到密码管理器里。接入文档在 https://taotoken.net/doc 里面有各个工具的详细配置步骤。如果你只是想先试试模型对话的效果可以从 https://taotoken.net/chat 进去发几条消息感受一下通道质量。长期编码场景的话Coding Plan 的入口在 https://taotoken.net/coding-plan 按你的日均消耗选档位。最后留一个实用判断标准这个改动如果出了问题修复成本超过 30 分钟吗是的话走 Superpowers 流程值得不是的话直接用裸 Claude Code 更快。框架是为中大型功能开发优化的不是为一行代码的快速修改。 
长河君 · 2026/9/30 23:11:11 · 阅读 1.2k 204K Star 的 Superpowers 实战：用 SKILL.md 给 Claude Code 补上 TDD 与子 Agent 的工程护栏
1. 为什么裸用 Claude Code 写三天代码就开始失控先说一个我观察到的现象很多人第一次用 Claude Code 写一个完整功能前两小时体验极好代码干净、逻辑清晰、测试也顺手补了。但到了第二天、第三天同一个项目继续迭代问题开始冒出来——函数越来越长、边界条件处理前后不一致、某个模块悄悄改了另一个模块依赖的隐式假设最后跑起来报错你还得回头翻半天对话记录找是哪一步埋的雷。这不是模型变笨了是上下文无记忆这个根本特性在长周期开发里被放大了。Claude 每次生成代码都是当前上下文的最优解但当前上下文不等于完整需求。它不知道两周前你定过一条规则也不知道某个看起来多余的状态分支其实是处理异常支付渠道的。没有显式约束覆盖的代码区域会被后续迭代一点点侵蚀。Superpowers 这个框架要解决的正是这件事。它不是让 AI 更聪明是给 AI 一套工程纪律。截至 2026 年 5 月这个由 Jesse Vincentobra维护的框架已经积累了 204K GitHub Stars、18.2K Forks在 Anthropic 官方插件市场的安装量超过 68 万次是 Claude Code 生态里增长最快的插件之一。v5.1.0 在 2026 年 4 月 30 日发布仍在快速迭代。它的实现方式很朴素整套框架就是一堆 SKILL.md 文件每个文件是一套用 Markdown 写成的流程规范任何人打开都能读懂。没有自己的运行时不锁定模型不依赖私有 API。当前版本包含 14 个核心技能分三类——开发流程类brainstorming、writing-plans、executing-plans、subagent-driven-development、using-git-worktrees、finishing-a-development-branch、质量保证类test-driven-development、requesting-code-review、receiving-code-review、verification-before-completion、调试与元技能类systematic-debugging、writing-skills、using-superpowers、dispatching-parallel-agents。会话启动时框架通过 Claude Code 的 hook 机制注入一个小于 2000 tokens 的引导文档告诉 Claude 开始任何任务前先读取相关 Skill。这个设计让整个框架极度轻量跨 Claude Code、Cursor、Gemini CLI、GitHub Copilot CLI、Codex CLI 都能工作。但这里有个已知的取舍子 Agent 启动时不会自动继承这个上下文注入导致子 Agent 有时会跳过 TDD 这类约束直接开写。框架目前通过 SubagentStart hook 部分缓解v5.1.0 里仍是已知问题。遇到时手动触发using-superpowersskill 可以把它拉回来。这篇文章要交付的是三样东西一份可复制的 SKILL.md 骨架、子 Agent 协作边界的配置片段、以及如何通过 TaoToken 统一 Key 和 API 通道把整套流程接起来。适合已经在用 Claude Code、但被长周期迭代里的隐蔽工程隐患折磨过的开发者。2. TaoToken 前置统一 Key 与 API 通道接入 Claude Code在讲 SKILL.md 之前得先把接入通道理清楚。因为 Superpowers 本身不提供模型通道它只是流程约束层真正跑推理的还是 Claude Code 背后的模型。如果你同时用 Claude Code、Cursor、Codex CLI 好几个工具每个工具单独配 Key、单独管额度很快就会乱。TaoToken 在这里的作用是提供一个统一的 Key 和 API 通道。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 这个地址不加 UTM 参数。你可以在控制台里生成一个 Key然后在各个工具里复用同一个 Base URL 和 Key。具体到 Claude Code配置方式是通过环境变量或者 settings 文件。Claude Code 读取的是ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY这两个变量。如果你想让 Claude Code 走 TaoToken 的通道可以这样设置export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的TaoToken密钥Windows 下用 PowerShell$env:ANTHROPIC_BASE_URLhttps://taotoken.net/api $env:ANTHROPIC_API_KEYsk-你的TaoToken密钥如果你更喜欢写进配置文件而不是每次 exportClaude Code 支持在项目根目录放.claude/settings.json或者在用户目录放全局配置。项目级的 settings 片段长这样{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥 } }这里有个细节要注意Base URL 填的是https://taotoken.net/api不要在后面加/v1或者别的路径Claude Code 会自己拼接。Key 从控制台的 API Keys 页面生成生成后只显示一次记得存好。模型 ID 这块Claude Code 默认会请求claude-sonnet-4-5这类模型名。TaoToken 的通道兼容 Anthropic 的模型命名你不需要在 Claude Code 里额外指定 Model ID它会按默认的走。如果你在别的工具比如 Cline、Codex CLI里需要显式填 Model ID那就填claude-sonnet-4-5或者你实际要用的那个。配好之后验证一下通道是否通。最直接的方式是在 Claude Code 里发一条消息看它能不能正常回复。如果报 401说明 Key 不对或者没生效如果报连接超时检查 Base URL 有没有写错。这一步先跑通再往下装 Superpowers否则后面出问题你分不清是通道问题还是框架问题。关于 Coding Plan 这类长期编码场景如果你打算把 Claude Code 当成日常主力工具可以了解一下 TaoToken 的 Coding Plan它针对长时间、高频次的编码会话做了额度优化。入口在 https://taotoken.net/api-keys 旁边的套餐页面具体选哪个档位看你的日均 token 消耗。3. 可复制配置SKILL.md 骨架与子 Agent 协作边界Superpowers 的核心就是 SKILL.md 文件。每个文件定义一套流程规范Claude 在执行任务前会读取对应的 Skill。你可以直接改官方提供的 Skill也可以自己写新的。下面给一份 TDD 流程的 SKILL.md 骨架你可以直接复制到项目里用。先看目录结构。Superpowers 安装后Skill 文件通常在~/.claude/plugins/superpowers/skills/下面。如果你想自定义建议在项目根目录建一个.claude/skills/目录把自定义的 SKILL.md 放进去Claude Code 会优先读取项目级的。一份 TDD 强制流程的 SKILL.md 骨架--- name: tdd-enforcement description: 强制测试先行没有失败的测试不允许写实现代码 --- # TDD 强制执行规范 ## 核心规则 没有失败的测试就没有实现代码。这不是建议是硬性约束。 ## 执行流程 ### 第一步RED 状态 在写任何实现代码之前先写测试文件。测试必须覆盖 - 正常路径happy path - 边界条件boundary cases - 错误输入invalid input 写完测试后立即运行确认全部失败。如果测试通过了说明测试写错了重写。 ### 第二步GREEN 状态 写最小实现代码让测试通过。不要提前优化不要加测试没覆盖的功能。 运行测试确认全部通过。 ### 第三步REFACTOR 状态 在测试保护下重构。每次重构后重新运行测试确认仍然全绿。 ## 禁止行为 - 禁止在没有失败测试的情况下写实现代码 - 禁止跳过 RED 状态直接写实现 - 禁止在测试未通过时继续添加新功能 - 如果发现实现代码先于测试存在删除实现代码回到 RED 状态 ## 覆盖率要求 目标覆盖率 85%-95%。低于 80% 时第二次迭代 regression 概率显著上升高于 95% 时写测试的时间投入超过收益。这份骨架的关键在于禁止行为那一段。Superpowers 的 TDD 不是尽量先写测试是字面意义上的——如果发现子 Agent 在没有失败测试的情况下写了实现代码框架要求删掉那段代码回到测试先行的状态。RED → GREEN → REFACTOR循环不跳步。接下来是子 Agent 协作边界的配置。Superpowers 的 subagent-driven-development 技能会把每个原子任务派给一个全新的子 Agent子 Agent 只知道自己这一个任务的上下文执行完报告结果给协调 Agent。这个设计的逻辑是长时间运行的单一 Agent 上下文会腐化新鲜子 Agent 的上下文是干净的判断也是干净的。子 Agent 的配置片段通常写在 Skill 文件里定义它的职责边界。一份子 Agent 协作边界的配置骨架--- name: subagent-boundary description: 定义子 Agent 的职责范围与协作规则 --- # 子 Agent 协作边界 ## 子 Agent 职责 每个子 Agent 只负责一个原子任务任务颗粒度控制在 2-5 分钟。 子 Agent 启动时必须 1. 读取当前任务的 spec 文件 2. 确认任务的输入输出定义 3. 检查是否有对应的失败测试 4. 如果没有失败测试先写测试再写实现 ## 子 Agent 禁止行为 - 禁止修改任务范围之外的文件 - 禁止跳过 TDD 流程 - 禁止在未确认测试通过的情况下报告任务完成 - 禁止假设其他子 Agent 的上下文 ## 协调 Agent 职责 协调 Agent 负责 1. 把大任务拆解成原子任务 2. 为每个原子任务生成 spec 3. 派发子 Agent 执行 4. 收集子 Agent 的执行结果 5. 在任务之间触发 Code Review ## 上下文隔离规则 子 Agent 不继承主会话的 Superpowers 引导文档。如果子 Agent 跳过了 TDD 约束协调 Agent 需要手动触发 using-superpowers skill 把它拉回来。这份配置的核心是上下文隔离规则那一段。因为子 Agent 启动时不会自动继承主会话的引导注入这是 v5.1.0 的已知问题。你需要在协调 Agent 的逻辑里加一步每次派发子 Agent 之前确认它是否加载了 TDD 约束如果没有手动触发一次using-superpowers。如果你用的是 Cline 或者 Codex CLI配置方式略有不同。Cline 的 MCP 配置里需要填 Base URL、Key 和 Model ID 三件套{ mcpServers: { taotoken: { url: https://taotoken.net/api, apiKey: sk-你的TaoToken密钥, model: claude-sonnet-4-5 } } }Codex CLI 的auth.json配置{ base_url: https://taotoken.net/api, api_key: sk-你的TaoToken密钥, model: claude-sonnet-4-5 }这三件套——Base URL、Key、Model ID——在任何工具里都是必须的。Base URL 统一填https://taotoken.net/apiKey 从控制台生成Model ID 按你实际要用的模型填。4. 验证请求从 Brainstorming 到 Code Review 跑通完整流程配置写好了得验证它真的能跑。用一个简单但覆盖完整流程的需求来测写一个 Python 函数输入月份和日期返回对应的星座名称。这个需求够简单但涵盖了边界条件处理、错误输入验证Superpowers 工作流的每个环节都能展示。先在 Claude Code 里安装 Superpowers/plugin install superpowersclaude-plugins-official这是官方 Anthropic 插件市场的安装命令。安装完成后重启 Claude Code在新会话中输入/help能看到 Superpowers 命令列表则安装成功。如果官方市场安装不了备选方案是社区市场/plugin marketplace add obra/superpowers-marketplace /plugin install superpowerssuperpowers-marketplace安装完成后触发 Brainstorming/superpowers:brainstorming 我想写一个 Python 函数输入月份和日期返回对应的星座名称Claude 不会立刻给你写代码。它会先问一系列澄清问题比如输入格式是整数还是字符串、非法日期怎么处理、星座边界日期是否需要精确、返回值是中文还是英文。这就是 Brainstorming 的核心价值它把你的隐式假设逼出来。你回答之后Claude 有了清晰的合约。然后生成计划/superpowers:writing-plansClaude 会把实现拆成原子任务每个任务有明确的文件路径、预期改动、验证步骤。重点在新会话里执行这份计划不要在同一个会话里直接让 Claude 开始执行。打开新的 Claude Code 会话把计划粘贴进去再开始。接下来是 TDD 执行。Claude 的第一动作是写测试文件不是实现代码# test_zodiac.py 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)此时运行测试全部失败RED 状态因为zodiac.py根本不存在pytest test_zodiac.py -v # ERROR collecting test_zodiac.py # ModuleNotFoundError: No module named zodiac这是正确的状态。Superpowers 框架要求看到测试失败后才允许开始写实现代码。然后 Claude 写最小实现# zodiac.py 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 摩羯座再次运行测试全部通过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 的函数以及一份记录了所有设计决策的对话历史。验证通道是否走的是 TaoToken可以在 Claude Code 里发一条消息然后去 TaoToken 控制台的用量页面看是否有对应的请求记录。如果有记录说明通道通了。如果控制台没有记录检查环境变量是否生效或者 settings.json 里的配置有没有被覆盖。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth配置和验证过程中最容易撞上的几类报错这里逐个对照排查。401 Unauthorized。这个最常见通常是 Key 没生效或者写错了。先检查环境变量echo $ANTHROPIC_API_KEY echo $ANTHROPIC_BASE_URL如果输出为空说明 export 没生效或者你是在新的终端窗口里跑的环境变量没继承。Windows 下检查 PowerShell 的$env:ANTHROPIC_API_KEY。如果 Key 有值但还是 401去 TaoToken 控制台确认这个 Key 是否被禁用或者额度耗尽。另外注意 Key 的前缀TaoToken 的 Key 通常以sk-开头复制的时候别把前后空格带进去。local proxy failed。这个报错通常出现在你本地配了代理但代理没启动或者端口不对。Claude Code 会读取HTTP_PROXY和HTTPS_PROXY环境变量。如果你不需要代理把这两个变量清掉unset HTTP_PROXY unset HTTPS_PROXY如果你确实需要走本地代理确认代理进程在跑端口和配置一致。这个报错和 TaoToken 本身无关是本地网络环境的问题。reading choices 相关报错。这个通常出现在 API 返回格式不符合预期时。Claude Code 期望的是 Anthropic 格式的响应如果 Base URL 填错了比如填成了 OpenAI 兼容的端点返回的 JSON 结构对不上就会报 reading choices 之类的错。确认 Base URL 是https://taotoken.net/api不要填成别的路径。如果你在 Cline 里配置Cline 可能默认走 OpenAI 格式需要在设置里切换成 Anthropic 格式或者确认 TaoToken 的通道支持你要用的格式。OAuth 相关报错。Claude Code 某些版本会尝试走 OAuth 流程如果你用的是 API Key 模式可能会冲突。检查 settings.json 里有没有残留的 OAuth 配置比如oauthAccount之类的字段。如果有删掉只保留env里的 Base URL 和 Key。另外确认你用的 Claude Code 版本支持 API Key 模式太老的版本可能只支持 OAuth。子 Agent 跳过 TDD。这个不是报错是行为异常。表现是子 Agent 直接写了实现代码没有先写测试。原因是子 Agent 启动时没有继承主会话的 Superpowers 引导文档。解决办法是手动触发using-superpowersskill/superpowers:using-superpowers这个 Skill 的作用就是重新激活工程约束。触发后子 Agent 会重新读取 TDD 规范。如果频繁出现可以在协调 Agent 的逻辑里加一步每次派发子 Agent 之前先确认它是否加载了约束。测试覆盖率不达标。Superpowers 的目标覆盖率是 85%-95%。如果 Code Review 阶段发现覆盖率低于 80%说明测试写得不够。回到 RED 状态补充边界条件和错误输入的测试用例。不要为了凑覆盖率写无意义的测试测试要覆盖真实的边界场景。worktree 创建失败。Superpowers 在写代码之前会建一个干净的 worktree 分支。如果创建失败通常是 git 仓库状态有问题比如有未提交的改动或者当前不在 git 仓库里。先git status确认状态把未提交的改动处理掉再重试。排查的顺序建议是先确认通道通401 排查再确认配置对Base URL 和 Key再确认框架加载Superpowers 命令列表最后确认子 Agent 行为TDD 约束。一层一层往下查别跳步。6. 把工程纪律编码成文件而不是锁进平台Superpowers 最值得借鉴的设计决策是把工程文化编码成 Markdown 文件而不是锁进某个平台的私有配置里。你可以改任何 Skill 来适配自己团队的规范比如把 TDD 的覆盖率要求从 85% 调到 90%或者在 Brainstorming 的问题列表里加入团队特有的检查项。v5.1.0 还加入了writing-skills这个元技能帮你规范地写出新的 Skill——框架本身的扩展也要走 TDD 和 Code Review 流程保证新 Skill 的质量。如果你打算长期用 Claude Code 做开发建议把 TaoToken 的 Key 和 Base URL 配成全局环境变量这样 Claude Code、Cursor、Codex CLI 都能复用同一个通道不用每个工具单独管。控制台在 https://taotoken.net/api-keys 生成 Key 之后存到密码管理器里。接入文档在 https://taotoken.net/doc 里面有各个工具的详细配置步骤。如果你只是想先试试模型对话的效果可以从 https://taotoken.net/chat 进去发几条消息感受一下通道质量。长期编码场景的话Coding Plan 的入口在 https://taotoken.net/coding-plan 按你的日均消耗选档位。最后留一个实用判断标准这个改动如果出了问题修复成本超过 30 分钟吗是的话走 Superpowers 流程值得不是的话直接用裸 Claude Code 更快。框架是为中大型功能开发优化的不是为一行代码的快速修改。