🚀Claude Code自动化开发必备神器！Ralph for Claude Code实战演示，导入PRD文档秒变任务清单，AI通宵帮你写代码！安装配置+权限设置+PRD导入+效果展示一站式教学
一、项目概述
Ralph for Claude Code 是一个自主 AI 开发循环系统，名字来源于 Geoffrey Huntley 以《辛普森一家》中的 Ralph Wiggum 命名的技术。它能让 Claude Code 持续自主地迭代改进你的项目，直到完成，同时内置了防止无限循环和 API 过度使用的保护机制。
🚀本篇笔记所对应的视频：
- 👉👉👉 通过哔哩哔哩观看
- 👉👉👉 通过YouTube观看
- 👉👉👉 Subagents视频
- 👉👉👉 Gemini CLI视频
- 👉👉👉 Context Engineering视频
- 👉👉👉 SuperClaude视频
- 👉👉👉 Claudia视频
- 👉👉👉 Task Master视频
- 👉👉👉 Zen MCP编程视频
- 👉👉👉 Augment编程视频
- 👉👉👉 Serena MCP视频
- 👉👉👉 我的开源项目
- 👉👉👉 请我喝咖啡
- 👉👉👉 我的微信：stoeng
- 👉👉👉 承接大模型微调、RAG、AI智能体、AI相关应用开发等项目。
核心理念是：安装一次，到处使用 — Ralph 成为全局命令，可在任何目录中使用。
核心理念是：安装一次，到处使用 — Ralph 成为全局命令，可在任何目录中使用。
二、核心架构
项目由四个主要脚本和一个模块化库系统组成：
主要脚本
ralph_loop.sh— 主循环，反复执行 Claude Coderalph_monitor.sh— 实时监控仪表板setup.sh— 项目初始化脚本ralph_import.sh— PRD/需求文档导入工具
库组件 (lib/)
circuit_breaker.sh— 断路器模式，防止失控循环response_analyzer.sh— 智能响应分析器date_utils.sh— 跨平台日期工具
三、从零开始使用指南
第一阶段：全局安装（只需一次）
# 1. 克隆仓库
git clone https://github.com/frankbria/ralph-claude-code.git
cd ralph-claude-code
# 2. 运行安装脚本
./install.sh
安装后，你将获得以下全局命令：
ralph— 启动自主开发循环ralph-monitor— 启动监控仪表板ralph-setup— 创建新项目ralph-import— 导入现有需求文档
第二阶段：初始化项目（每个项目）
方式 A：导入现有 PRD/需求文档（推荐）
# 将现有需求文档转换为 Ralph 格式
ralph-import my-requirements.md my-project
cd my-project
# 查看生成的文件：
# - PROMPT.md (Ralph 指令)
# - @fix_plan.md (任务优先级)
# - specs/requirements.md (技术规格)
# 启动自主开发
ralph --monitor
方式 B：手动创建项目
# 创建空白项目
ralph-setup my-awesome-project
cd my-awesome-project
# 编辑配置文件
# 1. 编辑 PROMPT.md 设置项目目标
# 2. 编辑 specs/ 添加详细规格
# 3. 编辑 @fix_plan.md 设置初始优先级
# 启动自主开发
ralph --monitor
第三阶段：日常使用
# 导航到任何 Ralph 项目并运行：
ralph --monitor # 带集成 tmux 监控（推荐）
# 或使用分离的终端：
ralph # 终端 1：Ralph 循环
ralph-monitor # 终端 2：实时监控
四、工作原理
Ralph 基于简单但强大的循环运行：
┌─────────────────────────────────────────────────────┐
│ 1. 读取指令 — 加载 PROMPT.md 中的项目需求 │
│ ↓ │
│ 2. 执行 Claude Code — 运行 Claude 处理当前任务 │
│ ↓ │
│ 3. 追踪进度 — 更新任务列表和日志 │
│ ↓ │
│ 4. 评估完成度 — 检查退出条件 │
│ ↓ │
│ 5. 重复 — 继续直到完成或达到限制 │
└─────────────────────────────────────────────────────┘
智能退出检测
Ralph 使用双重条件检查防止过早退出：
退出需要同时满足两个条件：
completion_indicators >= 2（从自然语言模式启发式检测）- Claude 的显式
EXIT_SIGNAL: true（在 RALPH_STATUS 块中）
五、关键配置文件详解
1. PROMPT.md — 开发指令文件
这是 Ralph 每次循环的核心指令。关键部分包括：
# Ralph Development Instructions
## Context
你是 Ralph，一个自主 AI 开发代理，正在处理 [项目名称] 项目。
## Key Principles
- 每次循环专注一个任务
- 搜索代码库后再假设某功能未实现
- 实现后运行测试
- 更新 @fix_plan.md
## 🎯 Status Reporting (CRITICAL)
在响应末尾**必须**包含状态块：
---RALPH_STATUS---
STATUS: IN_PROGRESS | COMPLETE | BLOCKED
EXIT_SIGNAL: false | true
RECOMMENDATION: <下一步建议>
---END_RALPH_STATUS---
2. @fix_plan.md — 任务优先级列表
# Ralph Fix Plan
## High Priority
- [ ] 设置基本项目结构
- [ ] 定义核心数据结构
- [ ] 实现基本输入/输出处理
## Medium Priority
- [ ] 添加错误处理
- [ ] 实现核心业务逻辑
## Completed
- [x] 项目初始化
3. @AGENT.md — 构建和运行指令
包含项目的构建命令、测试方法等技术细节。
六、实际案例：构建一个任务管理应用
让我用一个完整的实际案例来演示：
案例：从 PRD 构建 Todo 应用
步骤 1：准备需求文档 todo-prd.md
# Todo 应用 - 产品需求文档
## 概述
构建一个简单的命令行 Todo 应用。
## 核心功能
- 添加任务：`todo add "买牛奶"`
- 列出任务：`todo list`
- 完成任务：`todo done 1`
- 删除任务：`todo delete 1`
## 技术要求
- 语言：Python
- 数据存储：JSON 文件
- 测试：pytest
## 成功标准
- 所有 CRUD 操作正常工作
- 数据持久化
- 测试覆盖率 > 80%
步骤 2：导入并启动开发
# 导入 PRD
ralph-import todo-prd.md todo-app
cd todo-app
# 查看生成的文件
cat PROMPT.md # 查看 Ralph 指令
cat @fix_plan.md # 查看任务列表
ls specs/ # 查看规格文件
# 启动自主开发
ralph --monitor
步骤 3：Ralph 开始工作
Ralph 会自动：
- 读取
@fix_plan.md中的高优先级任务 - 创建项目结构 (
src/,tests/等) - 实现核心功能（add, list, done, delete）
- 编写测试
- 运行测试并修复问题
- 更新
@fix_plan.md标记完成的任务 - 在
RALPH_STATUS中报告进度 - 当所有任务完成时，设置
EXIT_SIGNAL: true并退出
步骤 4：监控进度
在 tmux 会话中，你可以看到：
- 当前循环次数
- API 调用使用情况
- 最近的日志条目
- 速率限制倒计时
tmux 控制：
Ctrl+B然后D— 分离会话（Ralph 继续运行）tmux attach -t <session>— 重新连接
七、高级配置
速率限制和断路器
# 限制每小时 API 调用次数（默认 100）
ralph --calls 50
# 带监控
ralph --monitor --calls 50
# 检查状态
ralph --status
执行超时
# 设置 Claude Code 执行超时（默认 15 分钟）
ralph --timeout 30 # 30 分钟超时
# 复杂任务使用更长超时
ralph --monitor --timeout 60
会话管理
# 默认启用会话连续性
ralph --monitor
# 不使用会话连续性（隔离迭代）
ralph --no-continue
# 手动重置会话
ralph --reset-session
断路器管理
# 重置断路器
ralph --reset-circuit
# 查看断路器状态
ralph --circuit-status
全局配置位置
编辑 ~/.ralph/ralph_loop.sh：
# 每小时调用上限
MAX_CALLS_PER_HOUR=100
# 单次 Claude 超时（分钟）
CLAUDE_TIMEOUT_MINUTES=15
# 允许使用的工具
CLAUDE_ALLOWED_TOOLS="Write,Bash,Read,Edit"
# 会话连续性（是否使用 --continue）
CLAUDE_USE_CONTINUE=true
# 输出格式
CLAUDE_OUTPUT_FORMAT="json"
八、退出阈值配置
可以在 ~/.ralph/ralph_loop.sh 中修改：
# 退出检测阈值
MAX_CONSECUTIVE_TEST_LOOPS=3 # 3 次仅测试循环后退出
MAX_CONSECUTIVE_DONE_SIGNALS=2 # 2 次"完成"信号后退出
TEST_PERCENTAGE_THRESHOLD=30 # 30%+ 循环是测试时标记
# 断路器阈值
CB_NO_PROGRESS_THRESHOLD=3 # 3 次无文件变更后开启断路器
CB_SAME_ERROR_THRESHOLD=5 # 5 次相同错误后开启断路器
九、项目结构
使用 Ralph 创建的项目遵循标准结构：
my-project/
├── PROMPT.md # 主开发指令
├── @fix_plan.md # 优先级任务列表
├── @AGENT.md # 构建/运行指令
├── specs/ # 项目规格
│ └── stdlib/ # 标准库规格
├── src/ # 源代码
├── examples/ # 使用示例
├── logs/ # Ralph 执行日志
└── docs/generated/ # 自动生成的文档
十、卸载
# 运行卸载脚本
./uninstall.sh
# 或如果已删除仓库：
curl -sL https://raw.githubusercontent.com/frankbria/ralph-claude-code/main/uninstall.sh | bash
十一、常见问题排查
问题解决方案速率限制Ralph 自动等待并显示倒计时5 小时 API 限制Ralph 检测并提示选择等待或退出卡住循环检查 @fix_plan.md 是否有不清晰的任务过早退出调整退出阈值过早退出（新版）检查 Claude 是否设置 EXIT_SIGNAL: false执行超时增加 --timeout 值tmux 会话丢失tmux list-sessions 和 tmux attach 重连
总结
Ralph 是一个强大的自主开发工具，让 Claude Code 能够持续迭代你的项目。关键要点：
- 一次安装，多次使用 — 全局安装后可在任何项目中使用
- 双重退出检测 — 防止过早退出或无限循环
- 速率限制保护 — 自动管理 API 使用
- 实时监控 — tmux 集成提供可视化进度
- 智能导入 — 可从现有 PRD 快速启动项目
现在你可以开始用 Ralph 让 AI 自主构建你的项目了！🚀
Comments