Claude Code：Ralph Loop 全天候运行

(Updated: )
AI

系列导航

  1. 安装与配置
  2. 入门使用
  3. 高级功能
  4. 旁门左道
  5. 高效编写 CLAUDE.md
  6. 自定义命令
  7. Hooks
  8. Agents（子代理）
  9. MCP
  10. Plan 模式
  11. Skills
  12. 头脑风暴（Superpowers）
  13. Ralph Loop 全天候运行（本文）

1. 什么是 Ralph Loop

想象一下：你写好一个需求，然后去睡觉，第二天醒来代码就写好了 —— 这就是 Ralph Loop 的魅力！

Ralph Loop 是一种让 Claude Code 自主迭代运行的技术。它的名字来源于《辛普森一家》中的 Ralph Wiggum 角色，寓意着”不断尝试，永不放弃”的精神。

2A9CEL

1.1 核心原理

Ralph 本质上是一个 Bash 循环，通过 while true 不断地向 Claude 喂入提示词文件，实现自我迭代改进。

它创建了一个自引用反馈循环：

  • 提示词在每次迭代中保持不变
  • Claude 之前的工作成果保留在文件中
  • 每次迭代都能看到修改后的文件和 git 历史
  • Claude 通过读取自己过去的工作来自主改进
1
2
3
4
5
6
7
8
9
┌─────────────────────────────────────────────────┐
│                  Ralph Loop                      │
│  ┌─────────┐    ┌─────────┐    ┌─────────┐      │
│  │ 第1轮   │ -> │ 第2轮   │ -> │ 第3轮   │ ...  │
│  │ 写代码  │    │ 跑测试  │    │ 修bug   │      │
│  └─────────┘    └─────────┘    └─────────┘      │
│       ↑                                ↓        │
│       └────────── 持续迭代 ────────────┘        │
└─────────────────────────────────────────────────┘

2. 快速开始

2.1 启动 Ralph Loop

使用 /ralph-loop 命令启动一个循环：

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

Claude 会自动：

  1. 逐步实现 API
  2. 运行测试并查看失败
  3. 根据测试输出修复 bug
  4. 持续迭代直到所有需求完成
  5. 完成后输出完成标记

2.2 取消 Ralph Loop

如果需要中途停止，使用：

1
/cancel-ralph

3. 命令详解

3.1 /ralph-loop

启动一个 Ralph 循环。

语法：

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

参数说明：

参数 说明 默认值
<prompt> 任务提示词（必填） -
--max-iterations 最大迭代次数 无限制
--completion-promise 完成标记词 -

3.2 /cancel-ralph

取消当前正在运行的 Ralph 循环。

1
/cancel-ralph

4. Prompt 编写技巧

写好 Prompt 是 Ralph Loop 成功的关键。下面是一些最佳实践：

4.1 明确完成标准

让 Claude 知道什么时候算”完成”。

反面示例：

1
Build a todo API and make it good.

正确示例：

1
2
3
4
5
6
7
8
Build a REST API for todos.

When complete:
- All CRUD endpoints working
- Input validation in place
- Tests passing (coverage > 80%)
- README with API docs
- Output: <promise>COMPLETE</promise>

4.2 分阶段目标

把大任务拆分成小阶段，让 Claude 有清晰的执行路径。

反面示例：

1
Create a complete e-commerce platform.

正确示例：

1
2
3
4
5
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 all phases done.

4.3 引导自我纠错

告诉 Claude 如何处理错误和失败。

反面示例：

1
Write code for feature X.

正确示例：

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

4.4 设置安全边界

始终使用 --max-iterations 作为安全网：

1
2
# 推荐：始终设置合理的迭代上限
/ralph-loop "Try to implement feature X" --max-iterations 20

在 prompt 中也可以加入卡住时的处理方案：

1
2
3
4
After 15 iterations, if not complete:
- Document what's blocking progress
- List what was attempted
- Suggest alternative approaches

5. 适用场景

5.1 适合使用 Ralph Loop

场景 说明
有明确成功标准的任务 如”所有测试通过”、”编译成功”
需要迭代优化的任务 如让测试通过、修复 lint 错误
新项目开发 可以放手让 Claude 自己干
有自动验证机制的任务 测试、linter、类型检查等

5.2 不适合使用 Ralph Loop

场景 说明
需要人工判断的任务 如设计决策、用户体验评估
一次性操作 如简单的文件修改
成功标准不明确的任务 如”让代码更好”
生产环境调试 风险太高，建议人工介入

6. 实战案例

6.1 案例一：全栈应用开发

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
/ralph-loop "
构建一个全栈待办事项应用：

## 技术要求
- 后端：Node.js + Express + SQLite
- 前端：React + Tailwind CSS
- 功能：增删改查、用户认证、任务分类

## 完成标准
- npm run build 构建通过
- npm run test 测试通过，覆盖率 > 80%
- 应用在 localhost:3000 正常运行

满足所有标准后输出 <promise>COMPLETE</promise>
" --max-iterations 100 --completion-promise "COMPLETE"

6.2 案例二：代码重构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
/ralph-loop "
重构遗留的认证模块：

## 当前状态
- 单文件超过 2000 行
- 没有测试
- 职责混乱

## 目标状态
- 拆分为独立模块（auth、session、user）
- 每个模块都有单元测试
- 职责清晰分离

## 执行流程
1. 为当前行为编写测试
2. 确保测试通过
3. 逐个重构模块
4. 每次修改后运行测试
5. 持续直到所有模块重构完成

重构完成且所有测试通过后输出 <promise>COMPLETE</promise>
" --max-iterations 50 --completion-promise "COMPLETE"

6.3 案例三：Bug 修复

1
2
3
4
5
6
7
8
9
10
11
/ralph-loop "
修复项目中所有的 TypeScript 类型错误：

## 执行步骤
1. 运行 'npm run typecheck'
2. 逐个修复报告的错误
3. 重新运行类型检查
4. 重复直到没有错误

当 'npm run typecheck' 返回 0 个错误时输出 <promise>COMPLETE</promise>
" --max-iterations 30 --completion-promise "COMPLETE"

7. 核心理念

  • 7.1 迭代优于完美
    不要期望第一次就完美。让循环去打磨，每一轮都会更好一点。

  • 7.2 失败是数据
    “确定性的糟糕”意味着失败是可预测的、有信息量的。利用失败来调整 prompt。

  • 7.3 操作者技能很重要
    成功取决于写好 prompt，而不仅仅是有好的模型。

  • 7.4 坚持就是胜利
    持续尝试直到成功。循环会自动处理重试逻辑。