Superpowers 实现原理深度解析：如何把工程纪律变成 Agent 的默认行为-平芜编程栈

1. 为什么你的 Agent 总是“知道却做不到”

如果你用过 Cline、Claude Code 或者 CC Switch 这类编码 Agent，大概率遇到过这种场景：你明明在项目说明里写了“先写测试再实现”，Agent 也点头表示理解，结果它转头就开始改业务代码，测试留到最后补一个“验证现有行为”的用例。你追问它，它还会很诚恳地道歉，然后下一次继续犯。

这不是模型笨，而是工程纪律在自然语言里太容易被“合理化”绕过。模型知道 TDD、知道先澄清需求、知道要跑验证命令，但在长上下文、时间压力或者“这个改动很简单”的自我暗示下，它会跳过这些步骤。Superpowers 这个项目想解决的就是这件事：它不增强模型的代码知识，而是把工程纪律封装成可加载、可执行、可验证的 Skill 协议，让 Agent 的默认行为顺序从“先写代码”变成“先选流程、再做事情”。

我试过把这套思路落到 Cline 和 CC Switch 的配置里，核心就两件事：用配置骨架把规则注入到会话起点，用统一的 API 通道保证 Skill 加载和子代理派发不会因为 Key 切换而中断。下面我会把可复制的settings.json、config.toml片段和验证动作都摊开讲，你可以直接照着改。

2. 前置准备：TaoToken 统一 Key 与 API 通道

Superpowers 的运行链路里有一个容易被忽略的依赖：它会在任务起点做 Skill 检查、派发子代理、生成 review package，这些动作都会产生模型调用。如果你的 Cline 用一套 Key、CC Switch 里的 Claude Code 用另一套 Key，子代理派发时很容易因为通道不一致而失败，或者出现“主会话能跑、子代理 401”的诡异现象。

所以第一步是把模型调用收敛到一个统一入口。TaoToken 提供的就是这样一个兼容多模型的 API 通道，你只需要维护一份 Key，Cline、CC Switch、Claude Code 都指向同一个 base URL。

2.1 获取 Key 与确认接入地址

登录后在控制台创建 API Key，建议按用途分环境命名，比如superpowers-dev、superpowers-agent，方便后续在配置里区分。接入地址统一用：

https://taotoken.net/api

注意这个地址不带任何查询参数，直接作为 OpenAI 兼容协议的 base URL 使用。如果你用的是 Anthropic 协议的工具（比如 Claude Code），走的是同一套 Key，只是路径和请求头不同，后面配置片段里会分别给出。

2.2 为什么要在 Superpowers 场景下统一通道

Superpowers 的subagent-driven-development会为每个任务派发独立的 Implementer 和 Reviewer。如果这些子代理走的是不同 Key 或不同通道，会出现三个问题：一是计费和限流分散，排查困难；二是某个通道不支持长上下文时，review package 读取会截断；三是 bootstrap 注入的规则在子代理里可能因为通道差异而丢失。统一到 TaoToken 后，主会话和子代理共享同一份配额和模型列表，行为一致性明显更好。

3. 可复制配置：把工程纪律写进 settings.json 与 config.toml

这一节是全文的核心。Superpowers 的“实现原理”落到操作层面，就是在宿主启动时注入总入口规则，并在工具配置里声明 Skill 发现路径和模型通道。下面分 Cline 和 CC Switch 两个场景给配置。

3.1 Cline 的 settings.json 配置骨架

Cline 的配置通常放在用户目录下的settings.json，或者项目根目录的.cline/settings.json。关键字段是模型提供方、base URL、API Key，以及自定义指令注入。

{ "cline.apiProvider": "openai", "cline.openAiBaseUrl": "https://taotoken.net/api", "cline.openAiApiKey": "sk-your-taotoken-key", "cline.openAiModelId": "claude-sonnet-4-20250514", "cline.customInstructions": "You have Superpowers skills available. Before ANY action, check skills/using-superpowers/SKILL.md. If a skill has even 1% chance of applying, load it first. Never write production code without a failing test first.", "cline.skillsPath": "./skills", "cline.autoLoadSkills": true }

这里有几个点值得展开。cline.customInstructions承担的是 bootstrap 的角色，它会在每次会话启动时注入到系统提示里，相当于把using-superpowers的总入口规则常驻。cline.skillsPath指向你 clone 下来的 Superpowers 仓库里的skills/目录，Cline 会扫描每个子目录下的SKILL.md，读取 frontmatter 里的name和description作为技能索引。

注意autoLoadSkills这个字段，它的作用是让 Cline 在会话开始时只加载技能的元数据，而不是全文。这正好对应 Superpowers 的渐进式加载设计：第一层name + description用于召回，第二层完整SKILL.md在命中后才加载，第三层参考文档和脚本在执行到具体步骤时再读。这样 14 个 Skill 不会一次性占满上下文。

3.2 CC Switch 的 config.toml 配置骨架

CC Switch 用来在多个 Claude Code 配置之间切换，它的配置文件一般是config.toml。我们要做的是把 TaoToken 作为一个 provider 写进去，同时把 Superpowers 的 hook 路径挂上。

[[providers]] name = "taotoken" base_url = "https://taotoken.net/api" api_key = "sk-your-taotoken-key" protocol = "anthropic" default_model = "claude-sonnet-4-20250514" [superpowers] enabled = true skills_dir = "./skills" bootstrap_hook = "./hooks/session-start" inject_on_start = true dedup_marker = ".superpowers/.bootstrap-injected" [superpowers.gates] require_tdd = true require_plan_before_code = true require_verification_before_done = true

protocol = "anthropic"这个字段告诉 CC Switch 用 Anthropic 的消息格式去请求 TaoToken，这样 Claude Code 原生的工具调用和 Skill 发现机制可以正常工作。bootstrap_hook指向 Superpowers 仓库里的hooks/session-start脚本，它会在会话启动时读取skills/using-superpowers/SKILL.md的完整内容，组装成额外上下文注入。

dedup_marker是防止重复注入的关键。Superpowers 的 bootstrap 机制要处理三个稳定性问题：不能重复叠加、会话重建后要能恢复、上下文压缩后要保留关键规则。用一个 marker 文件记录注入状态，就能避免同一段规则在会话里出现多份，减少注意力噪音。

3.3 规则注入的时机为什么重要

不管是 Cline 的customInstructions还是 CC Switch 的bootstrap_hook，核心都是注入必须发生在 Agent 第一次行动之前。如果等模型已经开始“先看一下文件”，再补规则就晚了，因为“先了解一点情况”本身就是直接实现的入口。Superpowers 的using-superpowers明确规定，Skill 检查要先于任何动作，包括回答、澄清、探索代码库和检查文件。

4. 验证请求：确认 Agent 默认行为已被约束

配置写完不代表生效，得用几个可观察的动作验证。下面是我实测下来比较有效的三个验证场景。

4.1 验证 Skill 索引是否被正确加载

在 Cline 里新建一个会话，输入一句模糊需求，比如“给现有系统增加通知功能”。观察 Agent 的第一反应。如果配置生效，它不应该直接搜索代码或选库，而应该先输出类似“我先检查适用的 Skill”的动作，然后加载brainstorming，开始一次只问一个澄清问题。

你可以用一个更直接的探测请求：

curl https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer sk-your-taotoken-key" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-4-20250514", "messages": [ {"role": "system", "content": "You have Superpowers skills. Before any action, check using-superpowers."}, {"role": "user", "content": "修复偶发认证失败"} ] }'

如果通道和规则都正常，返回内容里应该能看到模型主动提到systematic-debugging，而不是直接给补丁建议。这一步验证的是模型编排层：宿主注册了技能，模型根据 description 判断命中。

4.2 验证 TDD 门禁是否生效

让 Agent 实现一个小功能，比如“给用户列表加一个按注册时间排序的按钮”。如果require_tdd = true生效，它应该先写一个会失败的测试，运行并确认失败原因是功能缺失，而不是语法错误，然后再写最小实现。你可以检查它的输出顺序：

1. 创建 test_user_sort.py，断言排序结果 2. 运行 pytest，确认 FAILED（功能缺失） 3. 实现排序逻辑 4. 再次运行 pytest，确认 PASSED 5. 重构，保持绿灯

如果它跳过第 2 步直接写实现，说明customInstructions或bootstrap_hook没有真正注入，或者被其他更强势的指令覆盖了。

4.3 验证子代理派发与统一通道

Superpowers 的subagent-driven-development会为每个任务派发独立子代理。你可以在 CC Switch 里跑一个多任务计划，观察日志里子代理的请求是否都走了https://taotoken.net/api。如果某个子代理报 401 或超时，大概率是它读了另一份配置里的旧 Key。统一通道后，主会话和子代理的模型列表、配额、限流策略都一致，review package 的读取也不会因为通道差异而截断。

5. 本篇常见错排查

配置过程中有几个坑我踩过，列出来帮你省时间。

第一个坑：Skill 目录路径写错。cline.skillsPath和superpowers.skills_dir必须指向包含 14 个 Skill 子目录的父目录，而不是某个具体 Skill 目录。如果路径写成了./skills/using-superpowers，Cline 只会发现一个技能，其他 13 个全部丢失。验证方法是看会话启动日志里扫描到的技能数量。

第二个坑：bootstrap 重复注入。如果你同时用了 Cline 的customInstructions和 CC Switch 的bootstrap_hook，同一段规则可能被注入两次。表现是模型反复强调“我要先检查 Skill”，浪费上下文。解决办法是只保留一个注入点，或者用dedup_marker做去重。

第三个坑：协议不匹配导致工具调用失败。TaoToken 同时支持 OpenAI 和 Anthropic 两种协议，但 Cline 默认走 OpenAI 格式，Claude Code 走 Anthropic 格式。如果你在 CC Switch 里把protocol写成了openai，Claude Code 的工具调用会解析失败，表现为 Skill 加载了但无法执行。对照配置片段里的protocol = "anthropic"检查。

第四个坑：上下文压缩后规则丢失。长会话里，模型最容易丢的不是局部实现细节，而是最上层的行为纪律。Superpowers 的做法是把 bootstrap 放在会话启动钩子上，让宿主生命周期负责恢复入口规则。如果你发现 Agent 在长会话后半段开始跳过 TDD，检查一下inject_on_start是否被关掉了，以及宿主是否支持 compact 后重新注入。

第五个坑：子代理递归编排。using-superpowers规定，如果当前 Agent 是为边界明确的任务派发的 subagent，就跳过入口检查。如果你发现子代理又开始 brainstorm 或重新规划，说明它没有正确识别自己的角色。检查 task brief 里是否明确写了“你是 Implementer，只完成局部任务”。

6. 把纪律变成默认行为的下一步

配置骨架和验证动作都跑通之后，你会发现 Agent 的行为顺序确实变了：它不再从自然语言直接跳到代码，而是先经过设计、计划、隔离实现、测试、评审、验证和交付。这套东西的价值不在于某一段提示词写得多强硬，而在于规则在正确时点被注入、技能按需加载、证据由工具确认。

如果你想把这条链路继续用起来，建议按用途分流：日常排障和接入配置，直接看 API Keys 和接入文档，把 Key 和 base URL 管好；想验证某个模型在 Superpowers 流程下的表现，用模型对话快速试；如果是长期编码或者要跑 Agent 工作流，Coding Plan 更适合，配额和模型列表都更稳定。

先把settings.json或config.toml改好，跑一遍第 4 节的三个验证请求，确认 Agent 的第一反应从“先写代码”变成了“先检查 Skill”。这一步过了，后面的 TDD 门禁、子代理派发、review package 交接才有意义。