ralph-loop

Ralph Wiggum 循环模式

该技术以《辛普森一家》中“即使困惑也永不放弃”的角色命名，让 Claude Code 在循环中运行：提示词保持不变，但代码库会不断累积更改。每次迭代都会读取之前的工作并继续，直至完成。

何时使用 Ralph 模式

适合：

• 完成标准明确、定义清晰的实现任务
• 重构或迁移工作（例如，从 React v16 升级到 v19）
• 测试驱动开发周期（持续运行，直到测试通过）
• 批处理或重复性任务
• 通宵自主工作会话

不适合：

• 需要设计决策或人工判断的任务
• 没有明确结束状态的探索性工作
• 执行过程中需求可能变化的任务
• 需要先了解代码的首次实现

激活流程

第 1 步：确认任务适用性

激活前，请确认：

• 任务有明确且可衡量的完成标准
• 可以通过程序验证是否成功（测试、构建或特定文件状态）
• 工作位于由 git 跟踪的目录中
• 你了解成功的标准

第 2 步：创建状态文件

创建 .claude/ralph-loop.local.md，内容如下：

---
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

## Verification Commands
Run these to check progress:
- `[test command]`
- `[build command]`

## Context
- Read [relevant files] for specifications
- Follow [conventions file] for code style

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

在项目根目录中创建 TODO.md：

# Task Checklist

## Tasks
- [ ] Task 1
- [ ] Task 2
- [ ] Task 3

## Completion
- [ ] ALL_TASKS_COMPLETE

第 4 步：启动循环

像往常一样运行 Claude 即可。Stop hook 会检测到状态文件，并让循环持续运行，直到检测到任务完成。

claude

两种完成方式

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

hook 会检查 TODO.md 中的 [x] ALL_TASKS_COMPLETE。这种方式更可靠，因为：

• 它在文件系统中可见
• 可以通过 git 跟踪
• Claude 可以轻松更新
• 你可以查看进度（已完成 X/Y 项任务）

方法 2：Promise 标签（旧版）

在状态文件中设置 completion_promise，并在完成时输出 <promise>YOUR_TEXT</promise>。

---
active: true
iteration: 0
max_iterations: 20
completion_promise: "feature implemented"
---

当 Claude 输出 <promise>feature implemented</promise> 时，循环结束。

配置选项

在 .claude/ralph-loop.local.md 的 frontmatter 中：

选项	默认值	说明
active	true	设置为 false 可禁用循环
iteration	0	当前迭代次数（自动递增）
max_iterations	20	安全上限（0 = 不限）
completion_promise	null	用于匹配 Promise 完成标记的文本

执行期间

迭代状态

每次迭代都会显示：

• 当前迭代次数
• 任务进度（来自 TODO.md）
• 完成标准
• 剩余最大迭代次数

检查点通知

每迭代 5 次，你会看到检查点提醒，以便：

• 查看更改：git log --oneline -10
• 确认进度符合预期
• 如果陷入停滞，可考虑调整提示词

手动干预

暂停循环：

# Edit the state file
# Change active: true → active: false

立即停止：

rm .claude/ralph-loop.local.md

恢复运行：

# Re-create or edit the state file
# Set active: true
claude

安全功能

• 迭代次数上限：防止无限循环（默认值：20）
• Git 跟踪：每项更改都可还原
• 检查点通知：提醒你检查进度
• 明确的完成标准：只有明确成功时循环才会退出
• 成本意识：跟踪迭代次数，以估算 API 成本

示例：MetricFlow 第 7–8 阶段

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

# MetricFlow Phase 7-8: Educator Agent

## Objective
Implement the Educator Agent that uses Claude API to generate educational
explanations for code metrics.

## Completion Criteria
Complete when TODO.md shows [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')"`

## 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)

## 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

以及对应的 TODO.md：

# Phase 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

## Completion
- [ ] ALL_TASKS_COMPLETE

故障排查

循环无法启动：

• 检查 .claude/ralph-loop.local.md 是否存在
• 确认 frontmatter 中设置了 active: true

循环无法停止：

• 确保 TODO.md 中的内容恰好为 [x] ALL_TASKS_COMPLETE（不区分大小写）
• 或检查 completion_promise 是否与输出标签匹配
• 检查 max_iterations 是否未设为 0（无限）
• 手动停止：rm .claude/ralph-loop.local.md

卡在同一个错误上：

• 检查错误模式
• 调整提示词，提供更具体的指导
• 考虑将任务拆分成更小的子任务

成本过高：

• 降低 max_iterations
• 缩短检查点间隔，以便尽早审查
• 考虑任务是否对 Ralph 模式来说过于复杂

成功技巧

1. 清晰的提示词可将迭代次数减少 40-60%——请具体说明
2. 先将 max_iterations 设为较小值（5-10），确认运行可靠后再调整
3. 每次检查点后都提交 Git——方便回滚
4. 使用 TODO.md 完成标记——比承诺标签更可靠
5. 监控最初几次迭代——尽早发现不良模式
6. 监督式自主运行——课程项目中应在检查点进行审查

成本估算

任务复杂度	迭代次数	预估成本
简单（单个功能）	5-10	$5-15
中等（多文件更改）	10-20	$15-30
复杂（完整阶段）	20-50	$30-75

快速入门模板

# 1. Create state file
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

# 2. Create TODO.md
cat > TODO.md << 'EOF'
# Tasks
- [ ] First task
- [ ] Second task

## Completion
- [ ] ALL_TASKS_COMPLETE
EOF

# 3. Start Ralph loop
claude