用途：ralph-loop 为 Claude Code 提供自主迭代循环模式，让同一提示词反复执行、代码库逐轮累积改动，直到任务完成。适合有明确完成标准、可程序化验证（测试、构建、文件状态）且位于 git 仓库中的任务，如明确定义的实现、重构或迁移（示例为 React v16 到 v19）、测试驱动开发、批处理与重复任务、隔夜自动作业。不适合需要设计判断、无明确终点的探索性工作、需求可能中途变化、或首次接触代码库的学习型实现。
主要能力与用法：先验证任务适合性，再创建状态文件 .claude/ralph-loop.local.md，其 frontmatter 含 active、iteration、max_iterations（默认 20，0 为不限）、completion_promise（默认 null）。推荐同时创建 TODO.md，通过标记 [x] ALL_TASKS_COMPLETE 判定完成；旧方式为在状态文件设置 completion_promise 并输出 <promise>文本</promise>。随后正常运行 claude 即可，Stop 钩子会读取状态文件维持循环。执行中每轮显示迭代数、TODO 进度与剩余上限，每 5 轮给出检查点提醒（如 git log --oneline -10）。暂停可把 active 改为 false，立即停止可执行 rm .claude/ralph-loop.local.md，恢复需重建或编辑状态文件并设 active: true 后再次运行 claude。
安全与限制：默认 20 次迭代上限防死循环，依赖 git 使改动可回退，通过检查点提示审查进度；卡在同一错误时应调整提示或拆分任务；成本过高时降低 max_iterations。资料给出成本估算：简单任务 5–10 轮约 $5–15，中等 10–20 轮约 $15–30，复杂 20–50 轮约 $30–75。使用建议包括提示具体、初期 max_iterations 设 5–10、每个检查点提交 git、优先用 TODO.md 完成判定、监视前几轮。其他细节暂未提供。