Ralph Wiggum 自主循环插件
Ralph Wiggum 是 Claude Code 官方插件，实现了自主迭代开发循环（Autonomous Development Loops）。它让 Claude 能够在无人干预的情况下持续工作，直到任务真正完成。
概述
Ralph Wiggum 插件实现了一种称为"自我参照循环"（Self-Referential Loop）的开发模式。在这种模式下：
- 用户只需运行一次
/ralph-loop命令 - Claude 开始工作，修改文件、运行测试
- 当 Claude 尝试退出时，Stop Hook 拦截退出
- 同样的提示词被重新注入给 Claude
- Claude 看到之前的文件修改和 git 历史，继续迭代
- 循环持续直到满足完成条件或达到最大迭代次数
典型使用场景
| 场景 | 说明 | 示例 |
|---|---|---|
| 框架迁移 | 大规模代码迁移和依赖升级 | React 15 升级到 React 18 |
| 批量操作 | 文档生成、工单分类 | 自动生成 API 文档 |
| 测试扩展 | 提升测试覆盖率 | 为所有函数添加单元测试 |
| 绿地项目 | 新项目脚手架搭建 | 从零构建 REST API |
快速示例
/ralph-loop "构建一个 Todo REST API。要求：CRUD 操作、输入验证、完整测试。当所有测试通过时，输出 <promise>COMPLETE</promise>" --completion-promise "COMPLETE" --max-iterations 50这个命令会让 Claude 持续工作直到：
- 输出
<promise>COMPLETE</promise>（表示任务完成） - 或达到 50 次迭代上限
行业背景：AI Coding 的 9 级地震
"作为一名程序员，从未如此强烈地感到落后。" — Andrej Karpathy
2026 年初，OpenAI 前 AI 总监 Andrej Karpathy 发表推文引发硅谷震动，宣告 AI 编程领域正在经历"9 级地震"级别的职业变局。他指出，若能正确运用 AI 工具，开发者的能力本可提升十倍——但这些"外星工具被抛到人间，没有附上说明书"。
硅谷大佬的集体转向
| 人物 | 身份 | 观点 |
|---|---|---|
| Linus Torvalds | Linux & Git 创始人 | "AI 写出来的代码比我手写的还好" |
| DHH | Ruby on Rails 创始人 | "不用 AI 写代码的程序员，就像拒绝用电脑的打字员" |
| Theo | t3.gg 创始人 | "70-90% 的代码现由 AI 生成" |
编程能力的指数级跃迁
| 年份 | AI 能力 | 人工操作 |
|---|---|---|
| 2023 | AI 写函数 | 需检查和修改 |
| 2024 | AI 写模块 | 需整合和调试 |
| 2025 | AI 写整个功能 | 需审查和优化 |
| 2026 | AI 自主迭代开发 | 设定目标、验收结果 |
为什么 Ralph Wiggum 重要？
在这个背景下，自主循环开发（Autonomous Development Loops）代表了 AI 编程的最新范式：
- 从写代码到指挥 Agent — 开发者角色从"代码工匠"转变为"AI Agent 指挥家"
- 从单次调用到持续迭代 — AI 不再是一次性工具，而是能持续工作直到任务完成
- 从人工验证到自动验收 — 通过测试和完成信号实现自动化验收
"软件工程领域已达永久性拐点，编程领域率先抵达 AGI 奇点。" — Theo
Google DeepMind 联合创始人 Shane Legg 从物理学角度解释了这一趋势的必然性：
神经元放电频率：100-200Hz（平均 0.1-2Hz）
硅芯片时钟速度：60 亿 Hz
硅速度 ≈ 碳速度 × 60,000这意味着在纯逻辑领域（如代码），硅基智能具有绝对的速度优势。Ralph Wiggum 正是利用这一优势，让 AI 在人类睡觉时持续迭代开发。
为什么叫 Ralph Wiggum？
这个名字来源于美国动画《辛普森一家》（The Simpsons）中的角色 Ralph Wiggum。Ralph 是一个天真、单纯的孩子，经常重复做同样的事情。
这个插件的核心机制就是"重复"：不断将同样的提示词注入给 Claude，让它在每次迭代中看到自己之前的工作成果，就像 Ralph 一样反复做同一件事，但每次都在之前的基础上进步。
起源故事：5 行代码逼疯硅谷
"默认第一次写不对。" — Geoffrey Huntley
澳洲放羊大叔 Geoffrey Huntley，Ralph Wiggum 技术的创始人
从农场到硅谷
Geoffrey Huntley 是一位澳大利亚的农场主兼开发者。2025 年底，他在自己的农场里写下了这 5 行震动硅谷的代码：
while :; do cat PROMPT.md | claude-code ; done
就是这 5 行代码，开启了 AI 自主编程的新纪元
这段看似简单的代码蕴含了深刻的设计哲学：
while :;— 无限循环cat PROMPT.md— 读取任务描述| claude-code— 管道传递给 Claude Code 执行- 循环往复 — 直到任务完成
核心哲学："默认第一次写不对"
Huntley 的核心洞见是：AI 写代码就像人类一样，第一次往往写不对。但与其期望一次性成功，不如：
- 指定任务和测试条件
- 让 AI 执行并查看测试结果
- 测试失败则继续循环
- 允许 AI 看到错误信息，自行修正
- 无限重试直至成功
这与传统的"一次性生成"思维截然不同：
| 传统思维 | Ralph Wiggum 思维 |
|---|---|
| 期望 AI 一次写对 | 默认 AI 会犯错 |
| 失败后人工干预 | 失败后自动重试 |
| 单次调用 | 循环迭代 |
| 人工验证 | 测试驱动验证 |
Anthropic 的官方认可
Boris Cherny，Anthropic Claude Code 负责人
Anthropic 官方高度认可这一技术，并将其整合为官方插件。Boris Cherny（Claude Code 负责人）更是身体力行：
| 指标 | 数据 |
|---|---|
| 统计周期 | 30 天 |
| 提交的 PR 数 | 259 个 |
| 代码提交次数 | 497 次 |
| 代码变更行数 | 约 40,000 行 |
| AI 生成比例 | 100% |
这意味着 Anthropic 自己的工程师也在用 Ralph Wiggum 循环来开发 Claude Code 本身——这是一种"自举"（Bootstrap）式的递归进化。
核心原则
"一个中等模型配优秀流程，远强于顶级模型配混乱流程。"
这句话道出了 Ralph Wiggum 成功的秘诀：流程比模型更重要。
| 组合 | 效果 |
|---|---|
| 顶级模型 + 混乱流程 | ❌ 效果差 |
| 中等模型 + 优秀流程 | ✅ 效果好 |
| 顶级模型 + 优秀流程 | ✅✅ 效果最佳 |
Ralph Wiggum 提供的正是这个"优秀流程"：
- 明确的任务定义
- 自动化的验证机制
- 持续的迭代改进
- 清晰的完成标志
工作原理
核心机制：Stop Hook
Ralph Wiggum 的核心是一个 Stop Hook（停止钩子）。当 Claude 尝试结束会话时，这个钩子会：
- 拦截退出 - 阻止 Claude 正常退出
- 检查完成条件 - 查看 Claude 是否输出了完成信号
- 重新注入提示 - 如果未完成，将原始提示词再次发送给 Claude
- 更新迭代计数 - 记录当前是第几次迭代
架构图
graph TD
A[用户运行 /ralph-loop] --> B[创建状态文件]
B --> C[Claude 开始工作]
C --> D[Claude 尝试退出]
D --> E{Stop Hook 拦截}
E --> F{检查完成条件}
F -->|发现 promise 标签| G[✅ 任务完成]
F -->|达到最大迭代| H[⏹️ 达到上限]
F -->|未完成| I[更新迭代计数]
I --> J[重新注入原始提示]
J --> C
G --> K[删除状态文件]
H --> K
K --> L[会话结束]
style A fill:#e1f5fe
style G fill:#c8e6c9
style H fill:#fff3e0
style L fill:#f5f5f5自我参照的含义
"自我参照"是这个技术的精髓：
- Claude 并不是直接接收自己上一轮的输出
- 而是通过 文件系统 和 git 历史 看到之前的工作成果
- 每次迭代时，Claude 可以：
- 查看已修改的代码文件
- 运行测试并看到结果
- 检查 git log 了解变更历史
sequenceDiagram
participant U as 用户
participant R as Ralph Plugin
participant C as Claude
participant F as 文件系统
participant G as Git
U->>R: /ralph-loop "构建 API"
R->>R: 创建 .claude/ralph-loop.local.md
loop 迭代循环
R->>C: 注入提示词
C->>F: 读取/修改文件
C->>G: 查看 git 历史
C->>C: 编写代码、运行测试
C->>R: 尝试退出
R->>R: Stop Hook 拦截
alt 发现 <promise>COMPLETE</promise>
R->>U: 任务完成
else 未发现完成信号
R->>R: 迭代计数 +1
R->>C: 重新注入同一提示词
end
end完成检测机制
Ralph 使用 <promise> 标签检测任务是否完成：
<promise>COMPLETE</promise>关键规则：
- 只在真正完成时输出 - Claude 被指示只有当声明完全、毫无疑问地为真时才输出 promise
- 诚实原则 - 不能为了退出循环而撒谎
- 自动验证 - 可以配合测试结果自动判断
安装与配置
插件安装
# 安装 Ralph Wiggum 插件
/plugin install ralph-wiggum@claude-code-plugins目录结构
安装后，插件的结构如下：
plugins/ralph-wiggum/
├── .claude-plugin/
│ └── plugin.json # 插件元数据
├── commands/
│ ├── ralph-loop.md # 主循环命令
│ ├── cancel-ralph.md # 取消命令
│ └── help.md # 帮助文档
├── hooks/
│ └── stop-hook.sh # 核心 Stop Hook
├── scripts/
│ └── setup-ralph-loop.sh # 初始化脚本
└── README.md配置文件 (plugin.json)
{
"name": "ralph-wiggum",
"version": "1.0.0",
"description": "Implementation of the Ralph Wiggum technique - continuous self-referential AI loops for interactive iterative development.",
"author": {
"name": "Daisy Hollman",
"email": "daisy@anthropic.com"
}
}状态文件
循环运行时会创建状态文件 .claude/ralph-loop.local.md：
---
iteration: 1
max_iterations: 50
completion_promise: "COMPLETE"
---
构建一个 Todo REST API。要求：CRUD 操作、输入验证、完整测试。
当所有测试通过时，输出 <promise>COMPLETE</promise>核心命令
/ralph-loop
启动自主迭代循环的主命令。
语法：
/ralph-loop "<提示词>" [选项]参数说明：
| 参数 | 说明 | 示例 |
|---|---|---|
<提示词> | 要重复执行的任务描述 | "构建 REST API" |
--max-iterations <n> | 最大迭代次数（0 = 无限） | --max-iterations 50 |
--completion-promise <text> | 完成信号文本 | --completion-promise "DONE" |
完整示例：
# 基础用法
/ralph-loop "重构 utils.js，添加类型注解和单元测试" --max-iterations 20
# 带完成信号
/ralph-loop "迁移所有组件从 class 到 hooks。完成后输出 <promise>MIGRATED</promise>" \
--completion-promise "MIGRATED" \
--max-iterations 100
# 测试覆盖率任务
/ralph-loop "为 src/ 目录下所有函数添加单元测试。目标覆盖率 80%。达到目标后输出 <promise>COVERED</promise>" \
--completion-promise "COVERED" \
--max-iterations 30/cancel-ralph
取消正在运行的 Ralph 循环。
语法：
/cancel-ralph行为：
- 检查是否存在活动的循环
- 如果存在，删除状态文件并报告已取消
- 如果不存在，提示没有活动的循环
示例输出：
✅ Ralph loop cancelled at iteration 12.实战示例
示例 1：构建 REST API
任务： 从零构建一个完整的 Todo REST API
/ralph-loop "
构建一个 Todo REST API 项目。
要求：
1. 使用 Node.js + Express
2. 实现 CRUD 操作（Create, Read, Update, Delete）
3. 添加输入验证（使用 Joi 或 Zod）
4. 编写完整的单元测试和集成测试
5. 所有测试必须通过
工作流程：
- 第一次迭代：设置项目结构和依赖
- 后续迭代：实现功能、编写测试、修复问题
当所有测试通过且覆盖率 > 80% 时，输出 <promise>API_COMPLETE</promise>
" --completion-promise "API_COMPLETE" --max-iterations 50预期流程：
| 迭代 | Claude 的工作 |
|---|---|
| 1 | 初始化 npm 项目，安装依赖 |
| 2 | 创建基础 Express 服务器 |
| 3-5 | 实现 CRUD 端点 |
| 6-8 | 添加输入验证 |
| 9-12 | 编写测试 |
| 13-15 | 修复测试失败的问题 |
| 16 | 输出 <promise>API_COMPLETE</promise> |
示例 2：测试覆盖率扩展
任务： 提升现有项目的测试覆盖率
/ralph-loop "
提升项目测试覆盖率。
当前状态：
- 运行 npm test -- --coverage 查看当前覆盖率
- 目标：所有文件覆盖率 > 80%
策略：
1. 首先分析覆盖率报告，找出未覆盖的代码
2. 优先为关键业务逻辑添加测试
3. 每次迭代后运行测试验证
每次迭代结束时检查覆盖率。当达到 80% 目标时，输出 <promise>COVERAGE_GOAL</promise>
" --completion-promise "COVERAGE_GOAL" --max-iterations 40示例 3：框架迁移
任务： 将 React 类组件迁移到函数组件 + Hooks
/ralph-loop "
将所有 React 类组件迁移到函数组件。
规则：
1. 查找所有 extends React.Component 的类
2. 转换为函数组件 + Hooks
3. 替换 lifecycle 方法：
- componentDidMount -> useEffect
- componentWillUnmount -> useEffect cleanup
- this.state -> useState
4. 保持功能不变
5. 运行测试确保没有回归
每次迭代处理 2-3 个组件。当所有组件迁移完成且测试通过时，输出 <promise>MIGRATION_DONE</promise>
" --completion-promise "MIGRATION_DONE" --max-iterations 100示例 4：文档生成
任务： 为所有公开 API 生成文档
/ralph-loop "
为项目中所有公开 API 生成 JSDoc 文档。
步骤：
1. 扫描 src/ 目录下所有导出的函数和类
2. 分析代码理解功能
3. 添加 JSDoc 注释：@param, @returns, @example
4. 验证文档格式正确
当所有导出函数都有完整文档时，输出 <promise>DOCUMENTED</promise>
" --completion-promise "DOCUMENTED" --max-iterations 30最佳实践
适用场景
Ralph Wiggum 最适合具有以下特征的任务：
| 特征 | 说明 | 示例 |
|---|---|---|
| 明确的完成标准 | 可以客观判断是否完成 | 测试全部通过、覆盖率达标 |
| 可自动验证 | 有测试、lint 等自动化工具 | npm test、eslint |
| 渐进式改进 | 每次迭代都能有进展 | 逐个添加测试用例 |
| 批量操作 | 需要处理大量相似任务 | 迁移 100 个组件 |
不适用场景
避免在以下场景使用 Ralph：
| 场景 | 原因 | 替代方案 |
|---|---|---|
| 模糊需求 | 没有明确的成功标准 | 先明确需求再执行 |
| 架构决策 | 需要人类判断和权衡 | 人工设计后再实现 |
| 安全敏感 | 认证、支付等关键代码 | 人工审查 |
| 探索性工作 | 需要创造力和直觉 | 交互式对话 |
Prompt 编写技巧
1. 明确完成条件
❌ 不好的写法
"优化这个项目的性能"
✅ 好的写法
"优化 API 响应时间。目标：所有端点 < 200ms。
运行 npm run benchmark 验证。达标后输出 <promise>OPTIMIZED</promise>"2. 包含自我纠正指令
"如果测试失败，分析错误原因并修复。
不要跳过失败的测试，不要降低测试标准。"3. 设置安全边界
"只修改 src/ 目录下的文件。
不要修改 package.json 的核心依赖。
不要删除现有功能。"4. 分阶段执行
"分阶段完成：
1. 第 1-5 次迭代：分析现有代码
2. 第 6-15 次迭代：实现核心功能
3. 第 16-25 次迭代：编写测试
4. 第 26-30 次迭代：优化和文档"成本考虑
Token 消耗
自主循环会消耗大量 tokens。估算公式：
总成本 ≈ 每次迭代的 tokens × 迭代次数 × token 单价典型成本范例：
| 任务规模 | 迭代次数 | 估算成本 |
|---|---|---|
| 小型（单文件） | 5-10 | $2-5 |
| 中型（多文件） | 20-30 | $10-30 |
| 大型（整个项目） | 50-100 | $50-150 |
安全限制
建议设置：
- 迭代上限 - 始终设置
--max-iterations - 保守起步 - 先用小的迭代次数测试
- 监控进度 - 观察前几次迭代的行为
# 保守的设置
/ralph-loop "任务描述" --max-iterations 10
# 确认可行后再放开
/ralph-loop "任务描述" --max-iterations 50真实案例
来自社区的真实成果：
| 案例 | 耗时 | 成本 | 成果 |
|---|---|---|---|
| Cursed 编程语言 | 连续 3 个月 | 未公开 | 完整的函数式编程语言 + 编译器 |
| Y Combinator 黑客马拉松 | 一晚上 | ~$297 | 6 个完整代码仓库 |
| Bloomberg 终端简化版 | 2 小时 | 未公开 | Michael Arnaldi 开发 |
| $50,000 合同项目 | 未公开 | $297 | 用 API 成本完成传统 5 万美元合同 |
| 测试优化 | 约 50 次迭代 | ~$50 | 测试时间从 4 分钟降到 2 秒 |
Y Combinator 黑客马拉松案例详解：
在这个案例中，开发者仅用一个晚上和 $297 的 API 成本，就生成了 6 个完整的代码仓库。这展示了 Ralph Wiggum 循环在高强度、短时间内完成大量工作的能力。
$297 vs $50,000 的经济学：
传统外包一个中型项目可能需要 $50,000。而使用 Ralph Wiggum 循环，相同的工作量仅需 $297 的 API 成本——这是 168 倍的成本优势。
Stop Hook 工作原理
核心逻辑
Stop Hook 是一个 Bash 脚本，执行以下逻辑：
flowchart TD
A[Claude 尝试退出] --> B{状态文件存在?}
B -->|否| C[允许退出]
B -->|是| D[读取状态]
D --> E{达到最大迭代?}
E -->|是| F[清理并退出]
E -->|否| G[读取最后输出]
G --> H{包含完成信号?}
H -->|是| I[任务完成]
I --> F
H -->|否| J[更新迭代计数]
J --> K[返回 block 决策]
K --> L[重新注入提示词]
style C fill:#c8e6c9
style F fill:#c8e6c9
style I fill:#c8e6c9
style K fill:#fff3e0关键步骤
- 检查状态文件 - 查看
.claude/ralph-loop.local.md是否存在 - 解析 YAML 前置内容 - 读取迭代次数、最大迭代、完成信号
- 验证迭代限制 - 检查是否超过最大迭代次数
- 读取转录文件 - 获取 Claude 最后的输出
- 检查完成信号 - 在输出中搜索
<promise>...</promise> - 返回决策 - 输出 JSON 告诉 Claude Code 如何处理
返回格式
当需要继续循环时，Hook 返回：
{
"decision": "block",
"reason": "原始提示词内容",
"systemMessage": "🔄 Ralph iteration 5 | To stop: output <promise>COMPLETE</promise>"
}常见问题
Q: 循环卡住了怎么办？
A: 使用 /cancel-ralph 命令手动停止循环。
Q: 如何查看当前迭代次数？
A: 检查状态文件：
cat .claude/ralph-loop.local.mdQ: Claude 输出了 promise 但没有停止？
A: 确保 promise 文本与 --completion-promise 参数完全匹配，区分大小写。
Q: 迭代太多成本太高怎么办？
A:
- 设置较小的
--max-iterations - 使用更具体的完成条件
- 先用 5-10 次迭代测试效果
总结
Ralph Wiggum 是一个强大的自动化工具，让 Claude 能够持续工作直到任务真正完成。核心原则是：
- 明确的目标 - 使用可验证的完成条件
- 安全的边界 - 设置迭代上限
- 渐进式工作 - 每次迭代都能看到进展
- 诚实原则 - 只在真正完成时宣布完成
"宁可可预测地失败，也不要不可预测地成功。" — Geoffrey Huntley
参考资源
- GitHub 源码 - 官方插件仓库
- Paddo.dev 博客 - 详细技术解析
- Claude Code 文档 - 官方文档
- Plugins 系统 - 插件开发指南
- 36氪：再见，程序员！硅谷全员投身 AI Coding - AI 编程行业背景
- 36氪：5行代码逼疯硅谷，澳洲放羊大叔捅开AI编程奇点 - Ralph Wiggum 起源故事
本文档基于 Ralph Wiggum 插件 v1.0.0 编写