Ralph Wiggum Plugin - Claude Code 迭代式 AI 开发循环插件

什么是 Ralph?

Ralph 是一种基于持续 AI Agent 循环的开发方法论，由 Geoffrey Huntley 提出

核心理念

正如 Geoffrey Huntley 所描述的："Ralph 就是一个 Bash 循环" - 一个简单的 while true，反复向 AI Agent 提供提示文件，让它迭代改进工作直到完成。

这个技术以《辛普森一家》中的 Ralph Wiggum 命名，体现了尽管遇到挫折也要坚持迭代的哲学。

工作原理

本插件使用 Stop Hook 拦截 Claude 的退出尝试，在当前会话内创建自参照反馈循环：

提示词在迭代之间保持不变
Claude 之前的工作保存在文件中
每次迭代都能看到修改后的文件和 git 历史
Claude 通过读取自己过去的工作自主改进

ralph-loop.sh

# 只需运行一次:
/ralph-loop "Your task description" \
  --completion-promise "DONE"

# Claude Code 自动执行:
# 1. 处理任务
# 2. 尝试退出
# 3. Stop Hook 阻止退出
# 4. Stop Hook 再次传入相同的提示
# 5. 重复直到完成

核心特性

Ralph Wiggum 插件的强大功能

🔄

自参照循环

在当前会话内创建反馈循环，无需外部 Bash 脚本。Claude 可以看到自己之前的工作并持续改进。

🎯

完成承诺机制

通过 completion-promise 参数设置完成条件，Claude 只有在任务真正完成时才会输出承诺语句退出循环。

🛡

安全迭代限制

可设置最大迭代次数作为安全网，防止在不可能完成的任务上无限循环。

📝

状态持久化

循环状态保存在 .claude/ralph-loop.local.md 文件中，支持监控当前迭代进度。

⚡

Stop Hook 技术

利用 Claude Code 的 Stop Hook API 拦截退出，实现无缝的迭代控制。

🔍

自动验证

适合与测试、Linter 等自动验证工具配合使用，通过测试结果驱动迭代改进。

Stop Hook 工作原理

设计哲学

Ralph 背后的核心原则

命令参考

插件提供的 Slash 命令

/ralph-wiggum:ralph-loop

在当前会话中启动 Ralph 循环

/ralph-wiggum:ralph-loop "<prompt>" --max-iterations <n> --completion-promise "<text>"

可用选项

--max-iterations <n> 在 N 次迭代后停止（默认：无限制）

--completion-promise <text> 表示完成的承诺短语

-h, --help 显示帮助信息

/ralph-wiggum:cancel-ralph

取消当前活动的 Ralph 循环

/ralph-wiggum:cancel-ralph

删除 .claude/ralph-loop.local.md 状态文件，停止当前循环。

提示词最佳实践

编写有效 Ralph 提示词的技巧

🎯 明确完成标准

❌ 不好的示例

"Build a todo API and make it good."

✅ 好的示例

Build a REST API for todos. When complete: - All CRUD endpoints working - Input validation in place - Tests passing (coverage > 80%) - Output: <promise>COMPLETE</promise>

📊 增量目标

❌ 不好的示例

"Create a complete e-commerce platform."

✅ 好的示例

Phase 1: User authentication (JWT, tests) Phase 2: Product catalog (list/search, tests) Phase 3: Shopping cart (add/remove, tests) Output <promise>COMPLETE</promise> when done.

🔁 自我纠错

❌ 不好的示例

"Write code for feature X."

✅ 好的示例

Implement feature X following TDD: 1. Write failing tests 2. Implement feature 3. Run tests 4. If any fail, debug and fix 5. Repeat until all green 6. Output: <promise>COMPLETE</promise>

🚪 设置逃生出口

✅ 推荐做法

# 始终设置合理的迭代限制 /ralph-loop "Try to implement X" \ --max-iterations 20 # 在提示词中说明卡住时怎么办: "After 15 iterations, if not complete: - Document what's blocking progress - List what was attempted - Suggest alternative approaches"

适用场景

什么时候使用 Ralph，什么时候不使用

✅

适合使用

有明确成功标准的定义良好的任务
需要迭代和改进的任务（如让测试通过）
可以放手不管的全新项目
有自动验证的任务（测试、Linter）
需要反复尝试直到成功的重复性工作

❌

不适合使用

需要人工判断或设计决策的任务
一次性操作
成功标准不明确的任务
生产环境调试（使用针对性调试代替）
需要频繁人工介入的交互式开发

实战成果

Ralph 技术的真实应用案例

6

在 Y Combinator 黑客松测试中
一夜生成的代码仓库数量

$297

完成价值 $50,000 合同
所花费的 API 成本

3月

使用此方法创建
完整编程语言的时间

安装指南

快速开始使用 Ralph Wiggum 插件

1

启动 Claude Code

以跳过权限检查模式启动（用于自动化循环）

claude --dangerously-skip-permissions

2

安装插件

从 Marketplace 添加并安装 Ralph Wiggum 插件

# 添加官方插件源 /plugin marketplace add anthropics/claude-code # 安装 ralph-wiggum 插件 /plugin install ralph-wiggum@claude-code-plugins

3

基础用法

启动一个带迭代限制的 Ralph 循环

# 最多迭代 N 次 /ralph-wiggum:ralph-loop "<prompt>" --max-iterations N # 示例：改进应用 /ralph-wiggum:ralph-loop "Make the app better" --max-iterations 20

4

带完成承诺的用法

设置完成条件，当输出指定文本时才退出循环

/ralph-wiggum:ralph-loop "<prompt>" --max-iterations N --completion-promise "TEXT"

5

实战示例

优化 UI/UX 的完整提示词示例

/ralph-wiggum:ralph-loop "把这个项目的 UI/UX 做得更像一款精致的、移动端优先的语言学习 App（基于 Chakra UI）：统一间距与留白、建立清晰的字体层级（标题/正文/辅助信息）、统一卡片/列表等组件样式，并为核心模块添加底部导航（例如：主页/Home、学习/Learn、测验/Quiz、进度/Progress、设置/Settings）。整体改动要保持一致性、克制且可维护。确保最终可以成功 build。完成后只输出：__RALPH_DONE__" --max-iterations 15 --completion-promise "__RALPH_DONE__"

6

取消循环

随时强制停止正在运行的 Ralph 循环

/ralph-wiggum:cancel-ralph