怎么搭建和使用 Ralph 循环

Ralph 就是一个让 AI "自己干活直到做完"的循环机制，特别适合复杂的编程任务，解放人力。这里介绍具体怎么搭建和使用 Ralph 循环。

📋 前置准备

你需要准备以下内容：

🛠️ 搭建步骤

方法一：使用 Claude Code 插件（推荐）

Step 1: 安装 Claude Code

# 安装 Claude Code CLI
npm install -g @anthropic-ai/claude-code

Step 2: 初始化项目

mkdir my-ralph-project
cd my-ralph-project
claude init

Step 3: 添加插件市场

claude plugins add-marketplace

Step 4: 安装 Ralph Wiggum 插件

claude plugins install ralph-wiggum

Step 5: 配置 Stop Hook
在 .claude/hooks/ 目录下创建 stop-hook.json：

{
  "hook_type": "stop",
  "decision": "block",
  "conditions": {
    "check_tests": true,
    "check_type_errors": true,
    "check_git_changes": true
  },
  "max_iterations": 20,
  "prompt": "任务未完成，请继续迭代修复问题"
}

方法二：手动搭建（完全控制）

Step 1: 创建项目结构

my-ralph-project/
├── .claude/
│   ├── hooks/
│   │   └── stop-hook.sh
│   ├── skills/
│   │   └── ralph-loop.json
│   └── config.json
├── prd/
│   └── requirements.json
└── workspace/

Step 2: 配置核心文件

config.json - 核心配置

{
  "max_iterations": 15,
  "auto_commit": true,
  "run_tests_after_each_iteration": true,
  "stop_conditions": {
    "all_tests_pass": true,
    "no_type_errors": true,
    "prd_completed": true
  }
}

skills/ralph-loop.json - 技能定义

{
  "name": "ralph-loop",
  "description": "自主迭代循环实现 PRD 任务",
  "trigger": "when_task_incomplete",
  "actions": [
    "analyze_current_state",
    "identify_blockers",
    "fix_issues",
    "run_tests",
    "commit_if_passing"
  ]
}

hooks/stop-hook.sh - Stop Hook 脚本

#!/bin/bash

# 检查测试是否通过
TESTS_PASS=$(npm test 2>&1 | grep -c "passed")

# 检查是否有类型错误
TYPE_ERRORS=$(npx tsc --noEmit 2>&1 | grep -c "error")

# 检查 PRD 是否完成
PRD_COMPLETE=$(node check-prd.js)

if [ "$TESTS_PASS" -eq 0 ] || [ "$TYPE_ERRORS" -gt 0 ] || [ "$PRD_COMPLETE" = "false" ]; then
  echo "BLOCK: 任务未完成，继续迭代"
  exit 1
else
  echo "ALLOW: 任务已完成"
  exit 0
fi

Step 3: 准备 PRD 文件

prd/requirements.json

{
  "project_name": "My Feature",
  "tasks": [
    {
      "id": 1,
      "description": "创建用户登录页面",
      "criteria": ["表单验证正常", "API 调用成功", "错误处理完善"],
      "status": "pending"
    },
    {
      "id": 2,
      "description": "实现用户注册功能",
      "criteria": ["邮箱验证", "密码强度检查", "重复密码确认"],
      "status": "pending"
    }
  ]
}

🚀 使用方法

启动 RALPH 循环

# 方法一：插件方式
claude run --skill ralph-loop --prd ./prd/requirements.json

# 方法二：Docker 隔离环境
docker run -it \
  -v $(pwd):/workspace \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  claude-ralph:latest

监控循环状态

# 查看当前迭代次数
cat .ralph/iteration_count

# 查看任务完成状态
cat .ralph/task_status.json

# 查看日志
tail -f .ralph/loop.log

🔧 高级配置

1. 自定义 Stop Hook 规则

{
  "stop_conditions": {
    "all_tests_pass": {
      "enabled": true,
      "command": "npm test",
      "success_pattern": "all tests passed"
    },
    "no_lint_errors": {
      "enabled": true,
      "command": "npm run lint",
      "success_pattern": "no problems"
    },
    "coverage_threshold": {
      "enabled": true,
      "threshold": 80
    }
  }
}

2. 添加代码审查步骤

{
  "after_each_iteration": [
    "run_tests",
    "run_linter",
    "code_review",
    "commit_if_passing"
  ],
  "code_review_prompt": "审查代码质量、安全性、性能问题"
}

3. 设置成本控制

{
  "cost_limits": {
    "max_tokens_per_iteration": 50000,
    "max_total_cost": 50,
    "alert_at_cost": 30
  }
}

📊 典型工作流程

┌─────────────────────────────────────────────┐
│         1. Claude 读取 PRD 任务列表           │
└─────────────────┬───────────────────────────┘
                  ↓
┌─────────────────────────────────────────────┐
│         2. 选择下一个待完成任务               │
└─────────────────┬───────────────────────────┘
                  ↓
┌─────────────────────────────────────────────┐
│         3. 实现代码、编写测试                 │
└─────────────────┬───────────────────────────┘
                  ↓
┌─────────────────────────────────────────────┐
│         4. 运行测试套件                       │
└─────────────────┬───────────────────────────┘
                  ↓
┌─────────────────────────────────────────────┐
│         5. Stop Hook 检查是否完成             │
│    • 测试通过？                              │
│    • 无类型错误？                            │
│    • PRD 要求满足？                          │
└─────────────────┬───────────────────────────┘
                  ↓
         ┌───────┴───────┐
         ↓               ↓
      未完成            完成
         ↓               ↓
  返回步骤 2          结束循环

💡 最佳实践

⚠️ 注意事项

1. 成本控制：每次迭代消耗 tokens，长时间运行成本较高
2. 质量检查：AI 可能"认为"完成但实际有 bug，需要严格测试
3. 安全边界：在沙盒环境运行，避免 AI 误删重要文件
4. 人工介入：复杂任务仍需人工审查结果