Back to Details

ralph-loop

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Ralph Wiggum Loop Mode

Ralph Wiggum循环模式

Named after the Simpsons character who "never stops despite being confused," this technique runs Claude Code in a loop where the prompt stays the same but the codebase accumulates changes. Each iteration reads previous work and continues until completion.
该模式以《辛普森一家》中“即便困惑也永不停止”的角色Ralph Wiggum命名，它会让Claude Code在循环中运行，提示语保持不变，但代码库会累积变更。每次迭代都会读取之前的工作内容并继续执行，直至任务完成。

When to Use Ralph Mode

何时使用Ralph模式

Ideal for:
  • Well-defined implementation tasks with clear completion criteria
  • Refactoring or migration work (e.g., React v16 to v19)
  • Test-driven development cycles (run until tests pass)
  • Batch processing or repetitive tasks
  • Overnight autonomous work sessions
Not ideal for:
  • Tasks requiring design decisions or human judgment
  • Exploratory work without clear end states
  • Tasks where requirements may change mid-execution
  • First-time implementations where you need to learn the code
适用场景：
  • 定义明确、具备清晰完成标准的实现任务
  • 重构或迁移工作（例如React v16升级到v19）
  • 测试驱动开发循环（运行直至测试通过）
  • 批处理或重复性任务
  • 夜间自主工作会话
不适用场景：
  • 需要设计决策或人工判断的任务
  • 无明确结束状态的探索性工作
  • 执行过程中需求可能变更的任务
  • 需要学习代码库的首次实现任务

Activation Protocol

激活流程

Step 1: Validate Task Suitability

步骤1：验证任务适用性

Before activating, confirm:
  • Task has clear, measurable completion criteria
  • Success can be verified programmatically (tests, build, specific file state)
  • The work is in a git-tracked directory
  • You understand what success looks like
激活前，请确认：
  • 任务具备清晰、可衡量的完成标准
  • 可通过编程方式验证成功（测试、构建、特定文件状态）
  • 工作目录已通过git追踪
  • 你清楚成功的具体表现

Step 2: Create State File

步骤2：创建状态文件

Create 
.claude/ralph-loop.local.md
with the following structure:
markdown
---
active: true
iteration: 0
max_iterations: 20
completion_promise: null
---
创建
.claude/ralph-loop.local.md
文件，结构如下：
markdown
---
active: true
iteration: 0
max_iterations: 20
completion_promise: null
---

Your Task Prompt Here

你的任务提示

Objective

目标

[Clear statement of what needs to be accomplished]
[清晰说明需要完成的内容]

Completion Criteria

完成标准

Complete when TODO.md shows [x] ALL_TASKS_COMPLETE
当TODO.md显示[x] ALL_TASKS_COMPLETE时即完成

Verification Commands

验证命令

Run these to check progress:
  • [test command]
  • [build command]
运行以下命令检查进度：
  • [测试命令]
  • [构建命令]

Context

上下文

  • Read [relevant files] for specifications
  • Follow [conventions file] for code style
undefined
  • 阅读[相关文件]以获取规格说明
  • 遵循[约定文件]的代码风格
undefined

Step 3: Create TODO.md (Recommended Completion Method)

步骤3：创建TODO.md（推荐的完成方式）

Create 
TODO.md
in your project root:
markdown
undefined
在项目根目录创建
TODO.md
：
markdown
undefined

Task Checklist

任务检查清单

Tasks

任务

  • Task 1
  • Task 2
  • Task 3
  • 任务1
  • 任务2
  • 任务3

Completion

完成标记

  • ALL_TASKS_COMPLETE
undefined
  • ALL_TASKS_COMPLETE
undefined

Step 4: Start the Loop

步骤4：启动循环

Simply run Claude normally. The Stop hook will detect the state file and keep the loop running until completion is detected.
bash
claude
直接正常运行Claude即可。Stop钩子会检测状态文件并保持循环运行，直至检测到任务完成。
bash
claude

Two Completion Methods

两种完成方式

Method 1: TODO.md Markers (Recommended)

方式1：TODO.md标记（推荐）

The hook checks 
TODO.md
for 
[x] ALL_TASKS_COMPLETE
. This is more reliable because:
  • It's visible in the file system
  • It can be tracked in git
  • Claude can easily update it
  • You can see progress (X/Y tasks complete)
钩子会检查
TODO.md
中是否存在
[x] ALL_TASKS_COMPLETE
。这种方式更可靠，因为：
  • 可在文件系统中直观查看
  • 可通过git追踪
  • Claude可轻松更新
  • 你能看到任务进度（已完成X/Y项任务）

Method 2: Promise Tags (Legacy)

方式2：Promise标签（旧版）

Set 
completion_promise
in the state file and output 
<promise>YOUR_TEXT</promise>
when complete.
markdown
---
active: true
iteration: 0
max_iterations: 20
completion_promise: "feature implemented"
---
When Claude outputs 
<promise>feature implemented</promise>
, the loop ends.
在状态文件中设置
completion_promise
，并在完成时输出
<promise>YOUR_TEXT</promise>
。
markdown
---
active: true
iteration: 0
max_iterations: 20
completion_promise: "feature implemented"
---
当Claude输出
<promise>feature implemented</promise>
时，循环将结束。

Configuration Options

配置选项

In 
.claude/ralph-loop.local.md
frontmatter:
OptionDefaultDescription
active
true
Set to 
false
to disable loop
iteration
0
Current iteration count (auto-incremented)
max_iterations
20
Safety cap (0 = unlimited)
completion_promise
null
Text to match for promise completion
在
.claude/ralph-loop.local.md
的前置元数据中：
选项默认值描述
active
true
设置为
false
可禁用循环
iteration
0
当前迭代次数（自动递增）
max_iterations
20
安全上限（0表示无限制）
completion_promise
null
用于匹配完成状态的文本

During Execution

执行期间

Iteration Status

迭代状态

Every iteration shows:
  • Current iteration number
  • Task progress (from TODO.md)
  • Completion criteria
  • Max iterations remaining
每次迭代都会显示：
  • 当前迭代次数
  • 任务进度（来自TODO.md）
  • 完成标准
  • 剩余最大迭代次数

Checkpoint Notifications

检查点通知

Every 5 iterations, you'll see a checkpoint reminder to:
  • Review changes: 
    git log --oneline -10
  • Verify progress is on track
  • Consider adjusting the prompt if stuck
每5次迭代，你会收到检查点提醒，需：
  • 查看变更：
    git log --oneline -10
  • 验证进度是否符合预期
  • 若陷入停滞，考虑调整提示语

Manual Intervention

人工干预

To pause the loop:
bash
undefined
暂停循环：
bash
undefined

Edit the state file

编辑状态文件

Change active: true → active: false

将active: true改为active: false


**To stop immediately:**
```bash
rm .claude/ralph-loop.local.md
To resume:
bash
undefined

**立即停止：**
```bash
rm .claude/ralph-loop.local.md
恢复运行：
bash
undefined

Re-create or edit the state file

重新创建或编辑状态文件

Set active: true

设置active: true

claude
undefined
claude
undefined

Safety Features

安全特性

  • Iteration cap: Prevents infinite loops (default: 20)
  • Git tracking: Every change is revertible
  • Checkpoint notifications: Reminders to review progress
  • Clear completion criteria: Loop only exits on explicit success
  • Cost awareness: Track iterations to estimate API costs
  • 迭代上限：防止无限循环（默认值：20）
  • Git追踪：所有变更均可回滚
  • 检查点通知：提醒你查看进度
  • 清晰的完成标准：仅在明确成功时退出循环
  • 成本意识：追踪迭代次数以估算API成本

Example: MetricFlow Phase 7-8

示例：MetricFlow第7-8阶段

markdown
---
active: true
iteration: 0
max_iterations: 25
completion_promise: null
---
markdown
---
active: true
iteration: 0
max_iterations: 25
completion_promise: null
---

MetricFlow Phase 7-8: Educator Agent

MetricFlow第7-8阶段：Educator Agent

Objective

目标

Implement the Educator Agent that uses Claude API to generate educational explanations for code metrics.
实现Educator Agent，该Agent使用Claude API为代码指标生成教学解释。

Completion Criteria

完成标准

Complete when TODO.md shows [x] ALL_TASKS_COMPLETE
当TODO.md显示[x] ALL_TASKS_COMPLETE时即完成

Verification Commands

验证命令

  • cd backend && python -m pytest tests/test_educator.py -v
  • cd backend && python -c "from app.agents.educator import EducatorAgent; print('OK')"
  • cd backend && python -m pytest tests/test_educator.py -v
  • cd backend && python -c "from app.agents.educator import EducatorAgent; print('OK')"

Context

上下文

  • Read docs/plans/MASTER_PLAN.md sections 5.3 (Educator Agent)
  • Follow CLAUDE.md for project conventions
  • Analyzer and Pattern agents already complete (use their output formats)
  • 阅读docs/plans/MASTER_PLAN.md的5.3节（Educator Agent）
  • 遵循CLAUDE.md的项目约定
  • Analyzer和Pattern Agent已完成（可参考它们的输出格式）

Instructions

说明

  1. Check TODO.md for current task list
  2. Implement next incomplete task
  3. Write tests as you go
  4. Run verification after each change
  5. Mark [x] ALL_TASKS_COMPLETE when done

And corresponding `TODO.md`:

```markdown
  1. 查看TODO.md中的当前任务列表
  2. 实现下一个未完成的任务
  3. 边开发边编写测试
  4. 每次变更后运行验证命令
  5. 完成后标记[x] ALL_TASKS_COMPLETE

对应的`TODO.md`：

```markdown

Phase 7-8: Educator Agent

第7-8阶段：Educator Agent

Tasks

任务

  • Create EducatorAgent class skeleton in backend/app/agents/educator.py
  • Add Claude API client initialization
  • Implement explain_complexity() method
  • Implement explain_maintainability() method
  • Implement explain_code_smells() method
  • Add course concept mapping
  • Write unit tests for all methods
  • Integration test with Analyzer output
  • 在backend/app/agents/educator.py中创建EducatorAgent类骨架
  • 添加Claude API客户端初始化逻辑
  • 实现explain_complexity()方法
  • 实现explain_maintainability()方法
  • 实现explain_code_smells()方法
  • 添加课程概念映射
  • 为所有方法编写单元测试
  • 与Analyzer输出进行集成测试

Completion

完成标记

  • ALL_TASKS_COMPLETE
undefined
  • ALL_TASKS_COMPLETE
undefined

Troubleshooting

故障排除

Loop won't start:
  • Check 
    .claude/ralph-loop.local.md
    exists
  • Verify 
    active: true
    is set in frontmatter
Loop won't stop:
  • Ensure TODO.md contains exactly 
    [x] ALL_TASKS_COMPLETE
    (case-insensitive)
  • Or check 
    completion_promise
    matches your output tag
  • Check 
    max_iterations
    isn't set to 0 (unlimited)
  • Manual stop: 
    rm .claude/ralph-loop.local.md
Stuck on same error:
  • Review the error pattern
  • Adjust the prompt with more specific guidance
  • Consider breaking task into smaller subtasks
Costs too high:
  • Reduce 
    max_iterations
  • Use shorter checkpoint intervals for early review
  • Consider if task is too complex for Ralph mode
循环无法启动：
  • 检查
    .claude/ralph-loop.local.md
    是否存在
  • 确认前置元数据中设置了
    active: true
循环无法停止：
  • 确保TODO.md中包含确切的
    [x] ALL_TASKS_COMPLETE
    （不区分大小写）
  • 或检查
    completion_promise
    是否与输出标签匹配
  • 检查
    max_iterations
    是否未设置为0（无限制）
  • 手动停止：
    rm .claude/ralph-loop.local.md
卡在同一错误：
  • 分析错误模式
  • 调整提示语，提供更具体的指导
  • 考虑将任务拆分为更小的子任务
成本过高：
  • 降低
    max_iterations
    的值
  • 缩短检查点间隔以便尽早查看进度
  • 评估任务是否过于复杂，不适合使用Ralph模式

Tips for Success

成功技巧

  1. Clear prompts reduce iterations by 40-60% - be specific
  2. Start with small max_iterations (5-10) until confident
  3. Git commit after every checkpoint - easy rollback
  4. Use TODO.md completion - more reliable than promise tags
  5. Monitor first few iterations - catch bad patterns early
  6. Supervised autonomy - review at checkpoints for course projects
  1. 清晰的提示可减少40-60%的迭代次数——请尽可能具体
  2. 初始设置较小的最大迭代次数（5-10次），直至你对模式有信心
  3. 每次检查点后提交git——便于回滚
  4. 使用TODO.md完成方式——比promise标签更可靠
  5. 监控前几次迭代——尽早发现不良模式
  6. 监督式自主——针对课程项目，在检查点进行审核

Cost Estimates

成本估算

Task ComplexityIterationsEstimated Cost
Simple (single feature)5-10$5-15
Medium (multi-file changes)10-20$15-30
Complex (full phase)20-50$30-75
任务复杂度迭代次数预估成本
简单（单一功能）5-10$5-15
中等（多文件变更）10-20$15-30
复杂（完整阶段）20-50$30-75

Quick Start Template

快速启动模板

bash
undefined
bash
undefined

1. Create state file

1. 创建状态文件

mkdir -p .claude cat > .claude/ralph-loop.local.md << 'EOF'

active: true iteration: 0 max_iterations: 20 completion_promise: null

mkdir -p .claude cat > .claude/ralph-loop.local.md << 'EOF'

active: true iteration: 0 max_iterations: 20 completion_promise: null

Your Task

你的任务

Objective

目标

[What you want to accomplish]
[你想要完成的内容]

Completion

完成标记

Check TODO.md for [x] ALL_TASKS_COMPLETE EOF
检查TODO.md中的[x] ALL_TASKS_COMPLETE EOF

2. Create TODO.md

2. 创建TODO.md

cat > TODO.md << 'EOF'
cat > TODO.md << 'EOF'

Tasks

任务

  • First task
  • Second task
  • 第一项任务
  • 第二项任务

Completion

完成标记

  • ALL_TASKS_COMPLETE EOF
  • ALL_TASKS_COMPLETE EOF

3. Start Ralph loop

3. 启动Ralph循环

claude
undefined
claude
undefined