Ralph Wiggum — Anthropic Official Autonomous Loop Plugin

Ralph Wiggum 插件是什么

Ralph Wiggum 插件是 Anthropic 官方维护的 Claude Code 扩展，把一段普通的交互式编码会话变成自主自迭代循环。运行 /plugins install ralph-wiggum 之后，你就有了两个 slash 命令：/ralph-loop 启动无人值守的运行，/cancel-ralph 中止它。插件来自 Anthropic 的 claude-plugins-official marketplace，所以安装不需要注册 marketplace、不需要额外配置。新装的 Claude Code 上整套上手时间不到 60 秒。

这个技术名字取自《辛普森一家》里的 Ralph Wiggum，体现「屡败屡战」式的持续迭代精神。这也是 Boris Cherny —— Claude Code 创始人 —— 在他个人页面 howborisusesclaudecode.com 上推荐的「超长任务」首选方式。Ralph 循环本质上是一个 while true，每轮把 prompt 和完成判据重新喂给 Claude，累积上下文并自我纠错，直到显式的完成哨兵触发或 --max-iterations 上限到达。

如果你想要的是「单条命令一气呵成」的体验而不是循环，可以参考相邻条目 commit-push-pr 一键提交推送 PR slash 命令。

Ralph 循环底层怎么工作

一个 Ralph 循环有三个结构件：prompt 文件、completion-promise 哨兵字符串、迭代次数上限。每一轮 tick，插件用同样的 prompt 重跑 Claude Code，让模型编辑、测试、推理，然后检查模型的输出里是否出现哨兵。哨兵匹配则 Ralph 干净退出。如果先到达 --max-iterations N，Ralph 以非成功状态退出，你可以检查部分结果。

这套架构对两件事很重要。第一，循环在多轮之间累积上下文，让模型在测试失败后能自我纠错而不丢状态。第二，显式哨兵把「完成」跟启发式猜测解耦 —— 模型只在自己的验证步骤（比如 npm test 退出码为 0）通过后才发出承诺。Boris Cherny 在 howborisusesclaudecode.com 上是这样形容这个模式的：

「对很长的任务，我要么 prompt Claude 用后台 agent 验证自己的工作，要么用 agent-stop hook，要么用 Ralph Wiggin 插件做自主循环。」

插件目前支持 Claude Code 1.x 及以上版本。它跟 hook 调度器配合得很好；如果你还需要本地定时任务调度，可以搭配 loop —— Boris 风格本地定时任务调度器。

Ralph Wiggum 安装的 Slash 命令

插件在任何 Claude Code 会话里只注册两个命令，下面是汇总。两个都按会话隔离，所以多个终端互不干扰。

官方 skill 模板的完整规范调用是：

/ralph-loop "Build a REST API for todos. Requirements: CRUD ops, input validation, tests. Output <promise>COMPLETE</promise> when done." --completion-promise "COMPLETE" --max-iterations 50

注意 prompt 里的 <promise>COMPLETE</promise> 包装。这是一份契约 —— Claude 只有在自我验证通过后才发出这个包装，Ralph 只在输出里出现字面字符串 COMPLETE 时才匹配。两端都得对齐，这是安全自主循环的最重要习惯。

Ralph 适合什么场景（和不适合什么）

Ralph 是大杀器，不是默认选项。官方 skill 列出四个高匹配场景和两个反匹配场景。

适合 Ralph 的场景：

1. 需要多次「编辑—测试」往返的多文件重构（比如「把所有 class 组件转成 React hook」）。
2. 退出条件清晰的测试驱动开发（「让所有测试通过，然后输出 COMPLETE」）。
3. 跨几十个文件的长迁移 —— 守着模型纯属浪费墙钟时间。
4. 可重复的 codemod 风格变换，配确定性验证器，比如 eslint --max-warnings 0 或 pytest -x。

不适合 Ralph 的场景：

1. 开放式探索。Ralph 会一直跑到上限，所以模糊的「探索一下方案」prompt 会烧 token 没有出口。
2. 验证难以表达成单一哨兵字符串的任务。如果你写不出一行检查，先写一个子 agent；可以参考 build-validator —— CI 验证子代理 里的哨兵友好验证器模式。

成本纪律：放任 Ralph 就会烧 token

最大的失败模式是无界 token 消耗。Ralph 每轮都重新喂完整对话，所以 token 成本随迭代次数超线性增长。插件文档给的官方安全模式是：

1. 永远显式设 --max-iterations。第一次跑别依赖默认值。小任务从 10 到 30 开始，等观察到典型迭代次数再放大。
2. 让 completion-promise 可验证。把它锁在真实检查上，比如只有 npm test && npm run lint 都返回 0 之后才发出 <promise>RALPH_COMPLETE</promise>。
3. 先在小任务上验证。在 2 个文件改动上跑，再放它去搞 200 文件迁移；这样能廉价地发现哨兵拼错和 prompt 歧义。
4. 配合 token telemetry 看着。用 ccusage —— Claude Code 实时 token 成本追踪 监控实时花费，预算失控前 /cancel-ralph。

按 Anthropic 自己的价格页：Claude Sonnet 输入 $3/百万 token、输出 $15/百万 token；中等规模重构的 50 轮 Ralph 循环很容易吃掉几百万 token，所以哪怕迭代次数降 10% 都有实质收益。

第一次跑 Ralph 的分步流程

直接取自 skill 模板的规范第一次运行只有三步。这是经过验证、不掺水的流程：

1. 在任何 Claude Code 会话里运行：

```

/plugins install ralph-wiggum

```

1. 启动一个 Ralph 循环，自动迭代直到哨兵触发：

```

/ralph-loop "Build a REST API for todos. Requirements: CRUD ops, input validation, tests. Output <promise>COMPLETE</promise> when done." --completion-promise "COMPLETE" --max-iterations 50

```

1. 必要时中途取消：

```

/cancel-ralph

```

更贴近真实 TDD 的场景：插件文档给了 parseDuration 例子，prompt 强制 npm test 和 npm run lint 作为哨兵触发前的门：

/ralph-loop "
Implement a TypeScript function 'parseDuration(input: string): number' that
parses strings like '2h30m', '1d', '45s' into milliseconds.

Requirements:
1. Run npm test after each iteration
2. Fix all failing tests
3. When all tests pass AND npm run lint is clean, output:
   <promise>RALPH_COMPLETE</promise>
" --completion-promise "RALPH_COMPLETE" --max-iterations 30

这是「agentic TDD」的基础模式 —— 模型被迫一直保持循环，直到验证器产出绿色构建，然后必须显式发出哨兵。完成无法伪造，因为哨兵字符串被绑定在你可以在 transcript 里审计的 tool 输出后面。

Ralph 跟 Anthropic 其他自主模式对比

Ralph 是 Anthropic 三种长跑模式之一，每种 trade-off 不一样。

要看跑多个并行 agent 而不是单个自迭代 agent 的更宏观编排，参考 claude-flow 多 agent 编排。要看带内置验证和精简通道的一键 PR 工作流，看 go-verify-simplify 一键命令。

编码之外：非编码用例

插件是任务无关的。任何有可验证完成判据的任务都能驱动 Ralph 循环。社区变体如 ralph-wiggum-marketer 把循环模式用到文案迭代上，反复生成 headline 直到通过 checklist 哨兵。官方插件是通用 primitive；成功在于写一个「不达成目标就不可能发出」的 completion-promise。

实战模式：让 Claude 写一行 bash 检查，让它通过 tool call 跑这个检查，只在检查退出 0 时才发哨兵。只要哨兵在 transcript 里可观察、检查是真的，自主模式就安全。

来源、出处与致谢

Ralph Wiggum 由 Anthropic 构建并维护，是官方 claude-plugins-official marketplace 的一部分。插件源码托管在 anthropics/claude-code GitHub 组织下。命名和核心技术受 Geoffrey Huntley 早期「Ralph」循环文章启发；Anthropic 把它打包成第一方插件，让用户不必维护自定义循环脚本。Boris Cherny 在他个人 Claude Code 页面上把「超长任务」工作流的功劳归给了这个插件。

想继续在 Anthropic 官方面上搭建的 TokRepo 读者，两个相邻资产搭得好：code-simplifier —— Anthropic 官方精简子代理 和 SuperClaude —— Claude Code 工作流框架。配上 Ralph，它们构成紧凑的「循环—精简—验证」栈，可以在每次 PR 之前跑。