JeecgBoot AI专题研究 | Claude Code 自动化迭代插件 Ralph Loop 深度解析与实战指南
为什么 Claude Code 总是"差不多就行"？
用过 Claude Code 的开发者多少都遭遇过这个场景：把一个需求丢给 Claude，它忙活一阵，输出了一堆代码，然后——停了。
测试跑不过？它可能只是把报错结果附上来，等你进一步下指令。逻辑没完全实现？它交差了，声称"已经完成"。
这不是 Claude 能力不够强，而是它的运行模式决定的：单轮执行。Claude 做完一轮推理就认为任务结束，不会主动回头检查自己的输出、跑一遍测试、再改进一遍。
这个问题有了一个解法，叫做 Ralph Loop。
Ralph Loop 是什么？从辛普森一家说起
Ralph Loop 是一个 Claude Code 插件，名字来源于《辛普森一家》里的 Ralph Wiggum——那个永远在犯蠢、不断失败、但就是不放弃的角色。
用这个名字，意思再明确不过：让 Claude 像 Ralph 一样，不管失败多少次，都坚持重试，直到真正成功为止。
插件的核心逻辑极其简单——一个 bash while 循环：
while :; do cat PROMPT.md | claude; done
当然，真正的实现远不止这一行。Ralph Loop 通过 Claude Code 的 停止钩子（Stop Hook）机制，在 Claude 每次尝试退出时拦截它，把同样的提示词反馈回去，让它接着做。
循环是如何运转的？
一次 Ralph Loop 的完整流程如下：
- 你提供任务提示词 + 一个完成承诺（比如
DONE或COMPLETE） - Claude 开始处理任务，完成后尝试退出
- 停止钩子拦截退出信号，检查输出中是否包含完成承诺
- 未找到完成承诺 → 把原始提示词重新喂给 Claude
- Claude 查看上一轮产出，发现问题，继续改进
- 重复上述过程，直到 Claude 输出
<promise>DONE</promise>标签
整个循环状态保存在 .claude/.ralph-loop.local.md 文件中。Claude 每次重新启动时都能读取之前的工作进度，知道哪里做完了、哪里还差。
这个机制把 Claude Code 从"一次性助手"变成了"持续工作的工程师"。
真实战绩：297 美元完成 5 万美元的项目
光讲原理不够有说服力。Ralph Loop 在实际场景中的表现远超预期：
在 Y Combinator 举办的一次黑客马拉松中，有团队用 Ralph Loop 一夜完成了 6 个不同代码库的开发。其中一项任务是把 browser-use 的 Python 代码完整重写为 TypeScript 版本——这类重构工作在正常工程流程里往往需要数周时间。
更惊人的一个案例：一个通常估价 5 万美元的项目，用 Ralph Loop 只花了 297 美元的 API 成本完成了开发、测试和评审全流程。
甚至有人用它创造了一门名为 CURSED 的全新编程语言，Claude 自主运行约 30 小时，把所有语言组件从头构建完毕。
这些结果有一个共同点：任务定义清晰，提示词写得好。这一点后面会重点讲。
安装与快速上手
前置条件：Claude Code 版本 2.0.76 或以上（需要支持 /plugins 命令）。
npm install -g @anthropic-ai/claude-code
# 检查版本，需要 2.0.76+
claude --version
# 第一步：添加插件 marketplace
/plugin marketplace add anthropics/claude-code
# 第二步：安装 Ralph Wiggum 插件
/plugin install ralph-wiggum@claude-code-plugins
# 第三步：重载插件使其生效
/reload-plugins
# 确认安装成功（注意是 /plugins 复数）
/plugins
安装成功后，你会拥有两个核心命令：
/ralph-wiggum:ralph-loop：在当前会话启动 Ralph 循环/ralph-wiggum:cancel-ralph：取消正在执行的循环
命令格式详解
基础调用格式如下：
/ralph-wiggum:ralph-loop "<任务描述>" --completion-promise "DONE" --max-iterations 10
三个核心参数：
"<任务描述>"— 你希望 Claude 完成的工作，越具体越好--completion-promise— Claude 完成后必须输出的关键词，循环靠这个判断是否结束--max-iterations— 最大迭代次数，这是成本控制的安全阀，不要省略
没有 --max-iterations 的循环就像没有终点的马拉松，一旦提示词模糊，Claude 可能无休止地猜测"完成"的样子，直到耗尽你的 token 配额。
运行第一个 Ralph 循环，从简单任务开始感受一下：
/ralph-wiggum:ralph-loop "Create a simple Python function that validates email
addresses. Include edge case handling and write 3 test cases.
Output DONE when complete." --completion-promise "DONE" --max-iterations 5
你会注意到每次迭代的输出质量在提升——第一轮可能只是基础实现，后几轮会加入边界处理、优化错误提示、补全测试覆盖。
如果中途想叫停：
/ralph-wiggum:cancel-ralph
写出高质量提示词：Ralph 的真正门槛
关于 Ralph Loop 有一个必须面对的现实：插件本身不神奇，你的提示词才是关键。它会把你输入的一切放大——清晰的要求产生惊人效果，模糊的要求制造无限循环。
明确的完成标准
最常见的失败是对"完成"定义含糊：
# 差的提示——Claude 不知道什么叫"好"
Build a todo API and make it good.
# 好的提示——Claude 有明确的完成清单
Build a REST API for todos.
When complete:
- All CRUD endpoints working
- Input validation in place
- Tests passing with coverage above 80%
- README with API documentation
Output <promise>COMPLETE</promise> when all criteria are met.
阶段性拆解大任务
面对复杂项目，把它切分成可验证的阶段：
Build an e-commerce platform in phases:
Phase 1: User authentication with JWT and tests
Phase 2: Product catalog with list and search functionality
Phase 3: Shopping cart with add and remove features
Complete each phase before moving to the next.
Output <promise>COMPLETE</promise> when all phases are done.
内嵌自我纠错逻辑
在提示词里直接定义迭代规则：
Implement feature X using TDD:
1. Write failing tests first
2. Implement the feature
3. Run the tests
4. If any tests fail, debug and fix
5. Refactor if needed
6. Repeat until all tests pass
Output <promise>DONE</promise> when all tests are green.
这种模式把测试结果变成循环的"燃料"——每次失败都让下一轮更精准。
处理"卡住"的情况
If after 10 iterations you cannot complete the task:
- Document what's blocking progress
- List approaches you've tried
- Suggest alternative solutions
Output <promise>DONE</promise> when complete or <promise>STUCK</promise> if blocked.
即使循环失败，至少能拿到一份诊断报告，而不是白耗 token。
适用场景与使用边界
适合使用 Ralph Loop 的场景：
- 成功标准可量化的任务（测试通过、构建成功、接口跑通）
- 需要反复迭代验证的开发任务（写代码 → 跑测试 → 修 bug 的循环）
- 全新项目从零搭建，Claude 可以增量推进
- 可以挂在后台、睡前启动、醒来看结果的长任务
不适合使用 Ralph Loop 的场景：
- 需要主观判断的决策（UI 设计、架构取舍）
- 简单的一次性任务，没必要套循环
- 成功标准本身不明确，无法用关键词触发结束
- 生产环境调试——这类场景更需要定向排查
成本控制的几个原则
Ralph Loop 节省的钱和烧掉的钱，差别主要在提示词质量上。
具体来说：
--max-iterations是必填的安全保障，大多数任务 10-20 次足够，复杂项目可以到 30-50 次- 提示词写得越模糊，Claude 猜测的时间越长，消耗越多
- 简单任务可以选用成本较低的模型配置
- 开始时用小迭代上限试运行，验证提示词逻辑后再加大
那个 297 美元案例之所以能做到这个成本，核心是任务定义极为清晰——Claude 每一轮都在有效推进，没有陷入"猜你想要什么"的内耗。
总结
Ralph Loop 解决的是一个根本性问题：AI 不应该只做一轮就停。
在编程这件事上，"差不多"和"真的完成"之间往往隔着好几次测试、好几个 bug 修复、好几轮细节完善。单轮执行模式让 Claude 在这个关键阶段缺席了。
Ralph Loop 把这段距离填上了。它不改变 Claude 的推理能力，而是改变了 Claude 的工作模式——从"给一个答案"变成"直到做对为止"。
技术本身并不复杂，但它带来的效果是实质性的。前提只有一个：你得会写清楚提示词。
本文为 JeecgBoot AI 专题研究系列文章。
