高维潜变量可扩散性：生成模型落地的关键健康指标
2026/9/28 7:59:14
最近几个月，我把团队里AI辅助编码的工作流做了一次大手术。从一个"让Claude Code随便写写、我再花一小时review"的状态，切换成现在的固定动作：brainstorm 澄清 -> 写计划 -> TDD 红绿循环 -> 代码审查。这套流程的核心驱动不是某个IDE插件，也不是再套一层Agent，而是开源项目 Superpowers 提供的一套 skills 工作流。它原本是给 Claude Code 用的，现在 Codex 和 OpenCode 也能接入，等于把同一个方法论平移到不同的 AI 终端上。
先说说背景。团队里有几条交付线都在用 Claude Code 写业务代码，省是真省，但坑也是真坑。最典型的三个场景：第一，需求一句话就开干，写完发现和预期完全不是一个东西；第二，AI 从来不主动写测试，你问它"测了吗"，它答"跑了没问题"，然后过两天线上冒出一个边界case；第三，为了修一个小bug，AI顺手改了三处无关代码，review的时候看着 diff 一脸懵。这类情况多了之后，我逐渐意识到问题不在模型能力，而在工作流的缺失。Superpowers 的价值，就是把这个缺失补上。
如果你也在用 Claude Code、Codex 或 OpenCode 写代码，被"写得快但不敢交付"折磨过，这篇文章就是给你准备的。下文会把 Superpowers 的原理、三端接入方式、从需求澄清到代码审查的完整链路，以及我踩过的坑全部讲一遍。建议按顺序读，第4章的实战复盘和第5章的问题速查表可以直接当手册用。
1. 为什么需要Superpowers：Vibe Coding的失控与Workflow的回归
1.1 Vibe Coding最让人头疼的三个场景
先说第一个场景：需求只有一句话。之前有个需求"给文件上传加个进度提示"，Claude Code 二话不说开始写，前端、后端、数据库表都动了。review 的时候发现它把上传组件整个重写了，接口路径也改了。项目里没人要求过这些改动，纯粹是模型在"自由发挥"。这就是 vibe coding 最典型的失控——你把一个模糊意图丢给AI，它敢在没人确认的情况下帮你做了所有决定。
第二个场景：测试缺失。有一次我让 Claude Code 写一个时间区间工具函数，结果它写了 80 行实现，测试一个没有。我追问"测试呢"，它才补了两个 happy path。而我担心的是跨时区、夏令时、边界值这些角度的覆盖，它压根没想过。不是说AI没有能力写测试，而是默认流程里没有"测试先行"这个环节，它就不会主动加。这事儿你靠 prompt 提醒一次管一次，工作流不管，下次照样忘。
第三个场景：回归破坏。有个内部服务，某天 Claude Code 修了一个 NullPointerException，顺带把缓存模块的默认过期时间从 300 秒改成了 60 秒。它在会话里说过这个改动，但当时我在看别的任务，没注意到。这事件让我意识到：AI 会话中的每句话你都盯，就是拿人肉审计去对抗工具效率，成本不可持续。解决方向只有一个：把工程实践固化到 AI 的执行流程里，让约束而不是人肉来兜底。
1.2 Superpowers到底是什么
Superpowers 不是 IDE 插件，也不是另一个跑在 Agent 上层的 Agent。它本质上是一个开源的"AI 编码技能包"仓库：里面是一批 Markdown 格式的 skill 文件，每个 skill 定义了一个工作流环节的规则、步骤、输出格式。AI 通过读取这些 skill 文件，就知道在某个阶段应该怎么做、产出什么、禁止做什么。
打个比方：传统用法是你给一个聪明但没经验的新人下了一句指令，"把这个支付页面写了"，然后他自由发挥。Superpowers 的用法是你给这个新人一本《团队开发军规》，要求他先读"需求澄清"章节，在动键盘之前问你五个问题；然后读"计划"章节，把任务拆到 10 分钟一个颗粒度；再读"TDD"章节，必须先写失败的测试再写实现；最后还要走"代码审查"章节，叫一个同事来对拍。
这套军规不是一个 10 万字的 prompt 塞进去的，而是按需加载的。AI 在会话开始只读一个 AGENTS.md 入口文件，里面写了"遇到XX场景就调用XX skill"。真正干活时，模型再去读取对应的 skill 文件。这样做的好处有两个：第一，省 token，上下文不会被一堆规则占满；第二，可维护，你想改某个环节的规则，只改一个文件就行，不用重写整段系统提示词。
1.3 为什么是TDD而不是"先写代码再补测试"
Superpowers 把 TDD 作为默认开发路径，这一点我有过犹豫。毕竟让 AI 写测试再写实现，看起来多了一步，时间成本更高。但实际跑下来，这条路径反而更省。原因在于：TDD 的"红灯"阶段给 AI 划定了一个明确的验收边界，模型在写实现时不是猜你要什么，而是朝着一个已经被测试定义好的行为去凑，边界条件不会轻易漏。
先写功能，AI 大概率会把主流程写完，边界 case 靠运气；但你先让它写测试，它为了测试通过，必须考虑空输入、超时、异常类型、重复调用这些细节。这是写测试这个动作本身带来的强制思考。我的类比是：先写测试相当于施工前先立承重墙的垂直度标准，而不是楼盖完了再拿尺子量。后者不是不能测，而是测出来的问题改起来代价大得多。
2. 安装与三端配置：Claude Code / Codex / OpenCode 一次配齐
2.1 获取Superpowers
安装方式不复杂。在自己电脑上建一个目录，直接从 GitHub 把项目 clone 下来。Mac/Linux 都支持。拿到手后你看到的是一堆 Markdown 和脚本，核心的东西有两个：AGENTS.md和skills/目录。AGENTS.md 是入口，skills 目录里按主题放着一批 skill。每个 skill 是一个文件夹，里面有一个SKILL.md作为该技能的主文件。
提示：不要在系统的全局目录里直接改，建议把 Superpowers 克隆成一个独立目录，然后在项目里引用。这样升级项目时不会污染你自己的全局配置，也方便团队多人共用同一份基线。
2.2 Claude Code 配置
Claude Code 原生支持 skills 机制。具体操作是把 skills 目录链接到 Claude Code 能扫描到的位置。我用的方式是在项目的.claude/skills/下面建软链接，指向 Superpowers 克隆目录里的各 skill 文件夹。再把 Superpowers 根目录里的 AGENTS.md 内容合并到项目根目录的 AGENTS.md，或者在项目 AGENTS.md 里写一句@superpowers/AGENTS.md（如果 Claude Code 支持 import 语法）——不同版本支持程度不同，最稳的办法是直接把内容复制进去。
验证是否生效：在 Claude Code 会话里输入list skills或者直接问"你有哪些 skills？"。能看到 brainstorm、writing-plans、tdd、code-review 等条目就说明加载成功。如果看不到，先检查目录结构，再重启会话。Claude Code 对技能的扫描主要发生在会话启动时，中途改了文件不重启，大概率不生效。
2.3 Codex 配置
Codex 也读 AGENTS.md，并且支持类似 skills 的目录。通常把 skills 放到~/.codex/skills/或者项目下的.codex/skills/，然后在 AGENTS.md 里声明。和 Claude Code 的差异在于：Codex 对"自我反思式"指令的响应方式略有不同。我在实测中感觉，Codex 更吃"显式步骤"，所以在 AGENTS.md 里建议把流程写得比 Claude Code 那边更死板一点：明确要求"每次开始任务前，必须读取 skills/tdd/SKILL.md"。
另外，Codex 可以配自定义模型当后端，比如通过 API 配置接 DeepSeek 或其他兼容端点来跑。这类用法适合团队统一供应模型的场景，切换时不用改代码，只改 endpoint 和 key 就行。
2.4 OpenCode 配置
OpenCode 现在分老版本（Ts 版）和新版 Opencode V2（Go 重写版）。如果你用的是 V2，配置放在opencode.json里，再在项目目录下建.opencode/skills/放 skill 文件。配置逻辑类似：在 AGENTS.md 或 opencode 的自定义指令中声明加载入口。
另一个实用技巧：cc-switch 这个开源工具可以统一管理多套 API 配置，Claude Code、Codex、OpenCode 三者的 endpoint 和 key 都可以集中维护。遇到标题里那个cc switch local proxy failed的报错时，优先检查 cc-switch 的配置项：本地服务端口是否被占用、填写的 API base URL 是否以/v1结尾、key 是否有效。这类报错 90% 都是配置拼接不一致，拆开排查很快能定位。
2.5 三端能力对比
| 工具 | skills 目录 | 入口文件 | 数据流特点 | 适合场景 |
|---|---|---|---|---|
| Claude Code | .claude/skills/ | AGENTS.md | 原生支持 skills，加载稳定 | 日常主力、长会话复杂开发 |
| Codex | .codex/skills/ | AGENTS.md | 官方支持目录，但部分版本解析较弱 | 和 OpenAI 生态打通 |
| OpenCode V2 | .opencode/skills/ | opencode.json + AGENTS.md | Go 重写后配置更灵活 | 轻量、跨提供商切换 |
这个表不是让你选一个用，而是让你理解同一套 skill 在不同环境下怎么落地。我个人的建议：如果只是个人写脚本，选你装得最熟的那个；如果是做交付项目，把 Claude Code 和 Codex 都接上，用同一套 skills，方便以后在 A 家模型忙或挂的时候切到 B 家，不中断流程。
配置陷阱再多说一句。Claude Code 在某些地区会提示 might not be available in your country，这个提示通常意味着你的账号或网络环境不在官方支持范围内。处理方式很简单：自查没有灰色通道可走，唯一正解是使用官方支持地区的账号，或者把模型调用切换到你所在地区允许使用的提供商（如通过 API 配置用 DeepSeek 等可用模型跑 Codex 命令行）。OpenCode 的 free tier 也类似，提示 only be used from within opencode，意思是免费额度只能在 OpenCode 官方应用内部使用，你想用 CLI 或外部工具调用，就必须配置自己的 provider key。没配置就报错，配置好就行。
3. 核心工作流拆解：从需求澄清到代码审查
3.1 需求澄清：把模糊想法变成可测试的行为
Superpowers 的 brainstorm skill 并不是让你和 AI 聊人生，它是一套结构化的质询流程。AI 接到需求后，第一反应不是动手，而是按 skill 里的规则向你提问。问题范围一般包括：这个功能的真正目标是什么、用户是谁、边缘场景有哪些、现有系统里有没有相似逻辑、失败时怎么办、性能和量级要求如何。这一环节可能是整个流程里最反直觉的——看起来最耽误时间，实际最能省时间。
我举一个实际任务：某天同事说"给我们服务加个带超时的重试机制"。如果按 vibe coding 走，AI 会直接写一个retry装饰器出来，参数就 timeout、retries 两个。但走 brainstorm 流程时，AI 会追着问：重试是针对网络超时还是所有异常？TimeoutError和ConnectionError要不要区分？线程安全要不要保证？重试间隔是固定还是指数退避？要不要带 jitter？失败日志打到哪里？这些问题的答案直接决定了函数签名、内部状态和测试用例，比后面改 10 版代码便宜多了。
这一环节的输出不是文档，是一个被确认过的用户故事加一张"已完成/未完成"的定义清单。比如：作为调用方，我希望重试装饰器在网络抖动时自动重试最多 3 次，并在退避间隔上做指数加抖动，且过程中不吞掉非目标异常。完成标准：目标异常重试 3 次、非目标异常立即抛出、等待时间符合退避公式、支持超时取消。
3.2 写计划：把需求拆成AI能独立执行的最小任务
需求澄清之后进入 writing-plans。AI 会把上面的用户故事切成若干任务，每个任务的粒度控制在一个"10 到 15 分钟能实现"的单元里。切分逻辑通常是：先定义数据结构或接口，再实现核心逻辑，再补异常分支，最后做文档和测试补充。每个任务包含三样东西：目标、测试用例清单、实现要点。任务之间尽量不互相依赖，这样即使 AI 在某个任务上跑了很久，也不会把整个会话卡死。
计划写完会生成一个 plan.md 文件，AI 会把它贴出来让你确认。这个确认环节是审批闸门：你必须看一遍，觉得任务拆得不对就点一下让 AI 重拆，直到你觉得"这每一步我都能验收"为止。很多人会在这儿偷懒，跳过计划直接进代码，结果就是后面 AI 经常写着写着忘了需求，又要回头澄清。花 10 分钟读计划，省 40 分钟 debug，这笔账很划算。
3.3 TDD红绿循环：核心中的核心
TDD skill 是 Superpowers 的重头戏。读了这个 skill 之后，AI 的执行顺序会被强制改成这样：
- 红灯：针对当前任务先写一个或多个测试，运行看到失败。
- 绿灯：写最小实现代码，让测试通过。
- 重构：在不改变行为的条件下优化实现，保持测试全绿。
- 重复，直到完成当前任务。
我观察到，AI 一旦被 TDD skill 约束，输出行为会发生两个明显变化。第一，它写实现之前真的会先写测试，不再跳过。第二，它的实现会"收敛"，不再自由发挥，因为测试定义好了边界和输入输出，它能扩展的空间变小了。这两个变化直接解决了前面说的"没有测试意识、实现不可控"的问题。
这里有一个值得展开的点：测试的质量。TDD 绝不是"写两个断言，能过就算绿"。Superpowers 的 skill 里要求测试必须覆盖正常路径、边界路径、异常路径，三条缺一不可。有种反面教材是 AI 写了一个只验证"函数返回了东西"的弱测试，实现返回 None 也照样通过。这等于没有测试。所以我在用的时候，会在 review 阶段专门检查测试断言强度，后面第 4 章会给出实测案例。
TDD 的时间配比我给个参考表，这是我在团队里跑了两周之后定下来的。
| 任务预计实现时长 | 写测试（红灯） | 最小实现（绿灯） | 重构优化 | 合计 |
|---|---|---|---|---|
| 10 分钟 | 3 分钟 | 4 分钟 | 3 分钟 | 10 分钟 |
| 30 分钟 | 8 分钟 | 14 分钟 | 8 分钟 | 30 分钟 |
| 1 小时 | 18 分钟 | 27 分钟 | 15 分钟 | 60 分钟 |
| 2 小时以上 | 25% 时间 | 40% 时间 | 35% 时间 | 按比例 |
注意：这个表不是算术题，它是一个注意力分配提醒。经验是：实现越"复杂"，测试投入占比应该越高；实现越"简单"，重构占比反而可以拉高，因为快速写出的代码往往有明显的可读性提升空间。
3.4 代码审查：让另一双眼睛盯着实现
代码审查环节我刚开始没太在意，后来发现这是整个流程里最能薅羊毛的部分。Superpowers 的 code-review skill 会让 AI 以"另一个角色"而不是"代码作者"的身份去读实现。怎么做到？最简单的办法是让 AI 把当前会话的 diff 和测试文件作为输入，然后按一套 checklist 去审。审查维度包括：有没有隐藏的 bug、有没有安全问题、边界条件处理是否完整、命名是否表意、测试是否真的在测试行为而非实现细节、有没有死代码或多余的依赖。
这里最微妙的一点是防止"自己审自己的盲区"。同一个 AI 写的代码，同一个 AI 再审查，很容易得出"没问题"的结论。我的破解办法是：审查阶段用不同配置跑。比如 Claude Code 主写、Codex 做审查；或者同一个 CLI 里用思考模式更强的长上下文跑一遍 review。两种方式我都试过，都能比"作者自审"多发现 2 到 3 个真实问题。这些问题的典型类别是：异常处理遗漏（比如注册了KeyboardInterrupt却漏了SystemExit）、边界条件悬空（比如负数、空列表）、并发环境下共享状态没保护。
4. 实战复盘：用Superpowers开发一个"重试装饰器"
4.1 任务背景与需求澄清过程
这个例子就是第 3 章提到的"带超时的重试装饰器"。任务背景是一个内部 Python 服务，调用外部 HTTP API 时经常因为网络抖动失败，需要加重试。我们直接走 Superpowers 流程。
第一步需求澄清，AI 没有直接写代码，而是先抛了一串问题过来：
- 重试范围：是对所有异常重试，还是只针对网络层异常（如
ConnectionError、TimeoutError）？ - 超时定义：是单个调用超时取消，还是整个重试过程中的总时长上限？
- 退避策略：固定间隔、线性、指数、指数加随机抖动？
- 调用方签名：装饰器是纯参数配置，还是要支持传入自定义判断函数？
- 日志：失败时要不要记录每条异常的类型和重试次数？
我们确认的结果是：只重试网络类异常；单个调用用timeout参数控制；总时长用total_timeout控制；退避用指数加 jitter；装饰器签名上支持retry_exc自定义异常元组。这个确认过程大约花了 6 分钟，但正是这 6 分钟避免了后面最昂贵的返工。
4.2 计划文档：任务拆解记录
AI 随后生成了 plan.md，任务拆成了 5 个：
- 定义
RetryConfig数据类，放 retries、timeout、total_timeout、退避参数。 - 实现
retry装饰器基础结构，含参数解析。 - 实现指数退避和 jitter 计算函数。
- 接入日志模块，记录重试原因和次数。
- 补全文档注释和类型标注。
每个任务下面还附了测试用例清单。比如任务 2 的测试清单包括：目标异常达到次数上限后抛出原始异常；非目标异常立即抛出；成功时不再等待；timeout 参数生效后尽快失败。这些用例如果放在一个 vibe coding 任务里，几乎不可能出现，因为它们是被计划环节"逼"出来的。
4.3 TDD循环现场记录（红灯 -> 绿灯 -> 重构）
实际跑 TDD 循环的时候，第一轮的"红灯"环节我特意盯着看。AI 先写了测试文件，运行 pytest 后报了一个ModuleNotFoundError——因为实现模块还没有建。这里有个细节：AI 会在这个阶段主动报告"测试失败，符合红灯预期"。这一步非常关键，因为它是模型理解 TDD 的证明，如果它假装红灯会说"哦，测试没过，等我改一下再跑"，那就说明 skill 没加载成功。
接着绿灯阶段，AI 写了最简实现。为了通过"成功时不再等待"这条测试，它用的是try-except里判断should_retry，成功直接 return，这对。为了过"timeout 生效"测试，它引入了signal.setitimer，后来发现这在多线程环境下有坑，重构阶段换成了轻量级的超时包装。重构阶段把_exp_backoff_with_jitter从内联公式抽成独立函数，并加了类型标注。
整个循环跑了大约 40 分钟，期间 AI 写出的测试从最初的 7 个变成 11 个，中途它自己发现了两个边界问题：一是retries=0时的行为应与"不重试"一致，二是total_timeout包含单次调用超时，且两个参数同时设置时优先谁。这些问题如果用老的方式，很可能交付之后才在线上暴露。
4.4 审查结果：发现了什么
最后走 code-review。我用 Codex 对同一份 diff 做审查，结论是整体通过，但提出 3 个需要修正的问题：
- 问题一：
KeyboardInterrupt会被当成普通网络异常捕获并重试，这会让用户在 Ctrl+C 退出时被"卡住"，应把这类系统异常排除在重试范围外。 - 问题二：日志中记录了重试次数，但没有记录单次重试等待时间，排障时无法判断退避是否符合预期。
- 问题三：
total_timeout的实现里，时间检查点放在每次调用前，但单次调用超时本身可能很长，导致总时长超限后仍有一次长时间调用无法中断。需要重新设计时间边界。
这三个问题都非常具体，而且都不是语法错误，是只有"另一双眼睛"才容易注意到的设计缺陷。修复完这些问题，整个交付才真正敢说"一次通过零报错"——这里的"一次通过"不是玄学式蒙对，而是测试、审查全链路绿灯。
5. 常见问题速查表与工程化心法
5.1 问题速查表
我整理了这段时间实际踩过或帮朋友排查过的问题，按"现象 -> 直接原因 -> 处理方式"记录下来：
| 现象 | 直接原因 | 处理方式 |
|---|---|---|
| Claude Code 加载不到 skills | skill 目录放在错误的位置，或缺少 SKILL.md 入口 | 确认目录结构是skills/<skill名>/SKILL.md，重启会话 |
| AI 拿到需求后直接写代码，没有走 brainstorm | AGENTS.md 里的流程声明写得不够强制，AI 把它当建议 | 改成显式措辞，"必须先调用 brainstorm skill，否则不进入下一步" |
| 写的测试都是"弱断言"，实现怎么改都绿 | 例如只断言返回值不是 None，没有断言具体值、类型、边界 | review 阶段要求强断言，逐条对照计划里的用例清单 |
| Codex 跑起来不按 TDD 走 | Codex 对软性流程遵守较差，倾向"效率优先" | 在 AGENTS.md 里给 Codex 单独写明更死板的步骤序列 |
| OpenCode 提示免费层只能在应用内使用 | provider key 没有配置，走了默认免费通道 | 在 opencode.json 里配置自己的 provider 和 key |
| cc-switch 报 local proxy failed | 本地服务的端口、配置路径或 endpoint 格式不一致 | 检查 cc-switch 配置：请求到目标 provider 的 base URL 是否吻合，端口是否被占用 |
| 修改了 AGENTS.md 但 AI 表现没变化 | 会话使用了缓存，或工具只在项目启动时读取该文件 | 重启会话；确认修改的文件确实在项目根目录 |
| TDD 循环里 AI 把多个任务合并实现 | 计划拆得不够细，模型觉得可以"顺便"一起做 | 把计划任务再拆小，每个任务只对应一个明确测试文件 |
5.2 让Superpowers真正跑起来的三个心法
第一，别跳过审批闸门。brainstorm 和 plan 的输出都需要你读一遍并确认。前几次会觉得很啰嗦，但它是在把需求和实现之间的信息差消掉。我在团队里观察到，跳过计划确认的人通常会回头补两次需求。
第二，让"测试先行"成为不可争辩的事实。如果 AI 试图先写实现，直接打断："现在不是绿灯阶段，先回去读 tdd skill，写测试把红灯做出来。"几次之后，AI 在整个会话里都会很自觉。这一招比重写一万字 prompt 都管用，因为打断本身就是在设定边界。
第三，审查阶段一定要换一个"人"。要么换工具（Claude Code 写、Codex 审），要么换模型（便宜模型写、强模型审），至少也要换会话。用同一个上下文做审查，AI 很容易受到自己创造过程的"隧道视角"影响，发现不了真正的问题。
5.3 把Superpowers塞进现有工程规范
Superpowers 不是要替代你现有的编码规范，它更像团队流程的"AI 侧版本"。你在 AGENTS.md 里完全可以追加自己的规则，比如禁止提交print调试代码、所有日志必须走统一 logger、函数必须带类型标注。这些规则和 Superpowers 的 skills 是并存的：AGENTS.md 定义了总规则，skills 则负责具体工作流。
建议把 AGENTS.md 和 skills 目录放进团队的模板仓库。新人入职后 clone 模板，就等于所有 AI 工具都按同一个流程运行。我实测这个做法对团队的收益非常大：AI 写的代码风格统一了，测试覆盖自动保证，review 时大家看的是逻辑而不是在讨论风格。再进一步，你还可以把 AI 生成的测试自动接到 CI 和 pre-commit hooks 里，让"AI 写的测试"和"人写的测试"一样进入流水线，从环境层面保证测试真正跑起来，而不是只在会话里往返。
我个人在实际操作中的体会是：Superpowers 不会让你的 AI 从"写不出代码"变成"写得出来"，但它会把 AI 的产出从"像实习生的稿子"变成"像有老程序员把关过的交付"。如果你也在为 AI 写得快但不敢交付发愁，这一整套流程值得你花一个下午搭起来，再用一周的项目去校准时间配比和计划粒度。最后再分享一个小技巧：方案文档、计划文件、测试日志都放在项目的 docs/ai/ 目录下，版本管理里能看到每一步决策，出问题回溯时比聊天记录好用太多。