Ralph Wiggum 插件详解:Claude Code 自循环开发方法,自动迭代到测试全绿

Ralph Wiggum 是一种把 AI 编程从“一次性生成”推进到“可持续迭代交付”的方法论。

它的核心思路很朴素：用一个循环把同一份任务提示反复喂给智能体，让它在同一会话里持续尝试、持续修正，直到满足明确的完成标准。

由于每一轮迭代都会看到自己在文件中的产出、测试结果与版本历史，失败会变成可利用的反馈信号，进而推动下一轮更接近正确答案。

对工程实践而言，这种机制尤其适合带有客观验收条件的工作，例如测试全绿、lint 通过、接口满足契约、README 完整等。

下文内容为 Ralph Wiggum Plugin 官方介绍的中文翻译，尽量保留原有结构、术语与示例格式，便于对照阅读与直接上手实践。

以下为官方正文介绍：

在 Claude Code 中，实现基于拉尔夫·威格姆法的迭代式自引用人工智能开发循环。

什么是拉尔夫法？

拉尔夫法是一种基于人工智能智能体持续循环的开发方法论。正如杰弗里·亨特利所描述的：“拉尔夫法本质是一个 Bash 循环” —— 它通过一个简单的 while true 循环结构，持续向人工智能智能体输入提示文件，使其能够迭代优化工作内容，直至任务完成。

该方法得名自动画《辛普森一家》中的角色拉尔夫·威格姆，蕴含着“纵使遭遇挫折，仍要持续迭代”的核心理念。

核心原理

本插件通过终止钩子函数拦截 Claude 的退出指令，以此实现拉尔夫法的运行逻辑：

# 你只需执行一次：
/ralph-loop "你的任务描述内容" --completion-promise "DONE"

# 之后 Claude Code 会自动执行以下流程：
# 1. 开展任务相关工作
# 2. 尝试退出当前会话
# 3. 终止钩子函数阻止退出操作
# 4. 终止钩子函数重新输入相同的提示内容
# 5. 重复上述步骤直至任务完成

整个循环过程在当前会话内完成，无需依赖外部的 Bash 循环脚本。hooks/stop-hook.sh 路径下的终止钩子函数，通过拦截会话的正常退出动作，构建出一个自引用的反馈循环。

由此形成的自引用反馈循环具备以下特点：

• 每次迭代过程中，提示内容保持不变
• Claude 上一轮的工作成果会保存在文件中
• 每一轮迭代都能获取到已修改的文件内容和 Git 提交记录
• Claude 通过读取自身过往写入文件的工作内容，自主完成优化迭代

快速开始

/ralph-loop "开发一个待办事项的 REST API 接口。需求包括：实现增删改查（CRUD）操作、输入数据校验、编写测试用例。完成后输出 COMPLETE。" --completion-promise "COMPLETE" --max-iterations 50

执行该命令后，Claude 会自动执行以下操作：

1. 迭代式完成 API 接口的开发工作
2. 运行测试用例并定位执行失败的问题
3. 根据测试输出的结果修复代码缺陷
4. 持续迭代直至满足所有需求
5. 任务完成后输出预设的完成标识

命令说明

/ralph-loop

在当前会话中启动拉尔夫循环。

使用方法：

/ralph-loop "<提示内容>" --max-iterations <迭代次数上限> --completion-promise "<完成标识文本>"

可选参数说明：

• --max-iterations <迭代次数上限>
  
   – 当迭代次数达到设定值时自动停止（默认无次数限制）
• --completion-promise <完成标识文本>
  
   – 用于标记任务完成的特定文本内容

/cancel-ralph

终止当前正在运行的拉尔夫循环。

使用方法：

/cancel-ralph

提示词编写最佳实践

1. 明确任务完成标准

❌ 反面示例：“开发一个待办事项 API 接口，并且要做得好用。”

✅ 正面示例：

开发一个待办事项的 REST API 接口。

任务完成标准：
- 所有增删改查（CRUD）接口功能正常
- 已实现输入数据校验逻辑
- 测试用例全部通过（代码覆盖率 > 80%）
- 编写包含 API 文档的 README 文件
- 完成后输出：<promise>COMPLETE</promise>

2. 拆解为阶段性目标

❌ 反面示例：“开发一个完整的电子商务平台。”

✅ 正面示例：

第一阶段：实现用户认证功能（基于 JWT 技术，配套编写测试用例）
第二阶段：开发商品目录模块（支持列表展示和搜索功能，配套编写测试用例）
第三阶段：开发购物车功能（支持添加和移除商品，配套编写测试用例）

所有阶段完成后，输出 <promise>COMPLETE</promise>。

3. 嵌入自我修正逻辑

❌ 反面示例：“为功能 X 编写对应的代码。”

✅ 正面示例：

遵循测试驱动开发（TDD）流程实现功能 X：
1.  编写会执行失败的测试用例
2.  开发实现功能 X 的代码
3.  运行测试用例
4.  若存在测试失败的情况，调试并修复问题
5.  根据需要进行代码重构
6.  重复上述步骤直至所有测试用例通过
7.  完成后输出：<promise>COMPLETE</promise>

4. 设置容错机制

在执行命令时，建议始终使用 --max-iterations 参数作为安全兜底，避免因任务无法完成导致无限循环：

# 推荐用法：始终设置合理的迭代次数上限
/ralph-loop "尝试实现功能 X" --max-iterations 20

# 同时在提示词中写明遇到阻碍时的处理方案：
# "当迭代次数达到 15 次仍未完成任务时：
#  1.  记录当前阻碍任务推进的具体问题
#  2.  列出已经尝试过的解决方案
#  3.  提出可行的替代实现方案"

注意：--completion-promise 参数采用精确字符串匹配的方式判定任务完成状态，因此无法同时设置多个完成条件（例如同时识别“SUCCESS”和“BLOCKED”两种状态）。请始终将 --max-iterations 作为主要的安全控制机制。

方法论理念

拉尔夫法的核心思想包含以下几项关键原则：

1. 迭代优先，胜于追求一蹴而就

不必苛求第一次就做出完美成果，让循环机制逐步优化工作质量。

2. 失败是可利用的有效数据

“可预判的失败”意味着这些失败案例具备规律性和参考价值，可以据此优化提示词的编写思路。

3. 操作者的能力是成功关键

任务能否成功完成，关键在于能否编写高质量的提示词，而非单纯依赖性能强大的人工智能模型。

4. 坚持就是胜利

持续尝试直至任务成功，循环机制会自动处理重试逻辑，无需人工干预。

适用场景

适合使用拉尔夫法的场景：

• 任务目标明确、成功标准清晰的工作
• 需要反复迭代和优化的任务（例如，调试测试用例直至全部通过）
• 可以完全交由程序自主完成的全新项目开发
• 具备自动化验证手段的任务（例如，有测试用例、代码检查工具支持的开发工作）

不适合使用拉尔夫法的场景：

• 需要人工主观判断或设计决策的任务
• 只需一次性执行的操作
• 成功标准模糊不清的任务
• 生产环境的故障排查工作（此类场景建议使用针对性的调试手段）

实际应用成效

• 在 Y Combinator 黑客马拉松测试中，成功在夜间自动生成 6 个代码仓库
• 仅花费 297 美元的 API 调用成本，就完成了一个价值 5 万美元的合同项目
• 采用该方法，历时 3 个月成功开发出一门全新的编程语言（名为“cursed”）

拓展学习资源

• 方法起源：https://ghuntley.com/ralph/
• 拉尔夫任务调度器：https://github.com/mikeyobrien/ralph-orchestrator

获取帮助

在 Claude Code 中运行 /help 命令，即可查看详细的命令说明和使用示例。