用途
Ralph Wiggum Mode 是一个自主 AI 编码循环，使 Claude Code 能够在无需人工干预的情况下持续处理任务，让 Claude 在你睡觉时进行“夜班”工作。它适用于：通宵功能开发、缺陷批量修复（bug bashes）、测试覆盖率提升、大型代码库重构、文档生成，以及任何你希望在离开期间完成的多步骤任务。
核心原则
进度保存在文件和 git 中，而不是 LLM 的上下文窗口里。当上下文填满时，循环会以全新上下文重启 Claude。新实例从文件系统状态（你的代码、git 历史以及任务跟踪文件）继续工作。
安全模型
关键：Ralph 需要沙箱环境。
Ralph 使用 --dangerously-skip-permissions，这可能：
- 未经确认删除文件
- 读取凭据（~/.ssh、~/.aws）
- 发起网络请求
- 运行任意命令
除非检测到以下条件，否则 Ralph 将拒绝启动：
- 容器环境（Docker/Kubernetes）
- 网络隔离（无法访问互联网）
- 非 root 用户
- 无法访问敏感路径
快速开始
1. 在项目中初始化 Ralph
运行初始化脚本以搭建 Ralph 文件：
./ralph-init.sh
这会创建：
- RALPH_PROMPT.md - 每次迭代提供给 Claude 的提示
- IMPLEMENTATION_PLAN.md - 任务跟踪文件
- ralph.sh - 主循环脚本
- ralph-sandbox.sh - Docker 包装脚本
- Dockerfile.ralph - 沙箱容器定义
2. 定义你的工作
创建 specs 目录用于存放需求：
mkdir -p specs
编写需求：
cat > specs/my-feature.md << 'EOF'
## Feature: User Dashboard
### Requirements
- Show user's recent activity
- Display usage statistics
- Allow date range filtering
EOF
更新实施计划：
cat > IMPLEMENTATION_PLAN.md << 'EOF'
## Tasks
- [ ] Create Dashboard component
- [ ] Add activity feed API endpoint
- [ ] Implement date range picker
- [ ] Write tests for dashboard
EOF
3. 在沙箱中运行 Ralph
推荐使用 Docker 包装脚本：
./ralph-sandbox.sh
带迭代次数限制：
./ralph-sandbox.sh . 20
从另一个终端检查进度：
tail -f ralph.log
git log --oneline -10
4. 审查结果
查看 Ralph 做了什么：
git log --oneline
检查任务完成情况：
cat IMPLEMENTATION_PLAN.md
验证测试通过：
pytest
工作原理
外部 Bash 循环不断运行：
- Claude 会话读取 RALPH_PROMPT.md
- 检查 IMPLEMENTATION_PLAN.md
- 选择一个任务并实现它
- 运行测试、提交更改
- 上下文填满 → 会话结束
随后 Git 提交保存进度，循环以全新上下文重启。
文件参考
RALPH_PROMPT.md
每次迭代加载的提示。可根据用例自定义：
# Ralph Mode Instructions
You are operating in autonomous Ralph mode.
## Each Iteration
1. Read IMPLEMENTATION_PLAN.md and git log
2. Pick ONE pending task, mark it in-progress
3. Implement fully with tests
4. Mark complete, commit changes
## Rules
- Never skip tests
- Commit after each meaningful change
- If blocked, document why and continue
IMPLEMENTATION_PLAN.md
持久化任务跟踪（在上下文重置后依然存在）：
## Tasks
- [x] Task 1 (completed in iteration 1)
- [x] Task 2 (completed in iteration 2)
- [ ] Task 3 (in progress)
- [ ] Task 4 (pending)
ralph.sh
带沙箱强制检查的主循环。主要特性：
- 拒绝在沙箱外运行
- 可配置的迭代限制
- 每次迭代后执行 Git 提交
- 优雅的关闭处理
ralph-sandbox.sh
Docker 包装脚本，它会：
- 按需构建沙箱镜像
- 仅挂载项目目录
- 禁用网络（--network none）
- 设置资源限制（内存、CPU、PIDs）
- 丢弃所有 capabilities
配置
环境变量
| 变量 | 默认值 | 说明 |
|---|---|---|
| RALPH_MAX_ITERATIONS | 0（无限制） | 在 N 次迭代后停止 |
| RALPH_MODEL | sonnet | 使用的 Claude 模型 |
| RALPH_COST_LIMIT | 50.00 | 最大花费（美元，配合成本监控钩子） |
| ANTHROPIC_API_KEY | 可选 | API 密钥（使用 Claude Code 订阅时不需要） |
沙箱覆盖（危险）
仅用于你已验证的自定义沙箱环境：
RALPH_I_KNOW_WHAT_IM_DOING=sandboxed ./ralph.sh
最佳实践
提示工程
- 具体明确 - 告诉 Claude 每次迭代确切要做什么
- 单一任务聚焦 - “Pick ONE task”可防止上下文膨胀
- 要求测试 - 在提示中包含测试
- 跟踪进度 - 使用 IMPLEMENTATION_PLAN.md 作为共享状态
任务分解
将大任务拆分为小的原子片段：
不好的做法：
- [ ] Implement user authentication
好的做法：
- [ ] Create User model with email, password_hash
- [ ] Add POST /api/register endpoint
- [ ] Add POST /api/login endpoint
- [ ] Add password reset flow
- [ ] Add JWT middleware
- [ ] Write auth tests
监控
实时查看迭代：
tail -f ralph.log
检查提交：
watch -n 5 'git log --oneline -10'
监控资源使用：
docker stats
安全钩子（推荐）
安装这些钩子以获得额外安全性：
# Block dangerous operations
skillz hooks install ralph-safety-check
# Track API costs
skillz hooks install ralph-cost-monitor
故障排除
Ralph 无法启动
检查沙箱检测输出。你需要至少 3 项检查通过：
- 检测到容器
- 网络已隔离
- 非 root 用户
- 无敏感路径访问
Ralph 卡在某个任务上
- 检查 ralph.log 中的错误
- 更新 IMPLEMENTATION_PLAN.md 以解除阻塞
- 在 RALPH_PROMPT.md 中添加澄清说明
迭代失控
设置 MAX_ITERATIONS 或使用成本监控钩子：
./ralph-sandbox.sh . 20 # Stop after 20 iterations
参考
- Original Ralph Wiggum Technique
- Geoffrey Huntley's Blog
- VentureBeat Coverage