Ralph 入门指南

Ralph 是一种让 AI 编码智能体循环运行的技术。你反复运行同一提示词，AI 从 PRD 中自行选择任务，每完成一个功能就提交代码，稍后回来时就能看到可运行的代码。

本指南会带你构建第一个 Ralph 循环。我们将使用 Claude Code and Docker Desktop.

本文假设使用 Linux，但可以让 AI 根据你的操作系统或 AI Coding CLI 翻译调整步骤。

想了解更多发挥 Ralph 价值的技巧，请查看我的使用 Ralph 进行 AI 编码的 11 条技巧.

1. 安装 Claude Code

Claude Code 是 Anthropic 用于智能体编码的 CLI。使用原生二进制文件安装：

curl -fsSL https://claude.ai/install.sh | bash

如果安装后出现“command not found: claude”，请把安装位置加入 PATH：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

也可以通过以下方式安装 npm:

npm i -g @anthropic-ai/claude-code

运行 claude ，使用 Anthropic 账户完成身份验证。

深入学习：加入 AI Coding for Real Engineers 候补名单

2. 安装 Docker Desktop

Docker Desktop 让你在隔离环境中运行 Claude Code：沙箱中运行 Claude Code。AI 可以执行命令、安装包和修改文件，而不会触碰本地机器。

安装 Docker Desktop 4.50+，然后运行：

docker sandbox run claude

首次运行时，需要向 Anthropic 完成身份验证。凭据会存储在 Docker volume 中。

沙箱的主要优势：

工作目录会以相同路径挂载到容器内
Git 配置会自动注入，确保提交归属正确
每个工作区一个沙箱，状态会在运行之间持久化

请查看 Docker Sandboxes 文档了解更多。

3. 创建计划文件

Ralph 需要从 PRD（产品需求文档）中选择任务。可以手动编写，但使用 Claude 的 Plan Mode.

运行 Claude：

claude

然后按 shift-tab 以进入 Plan Mode。你可以持续迭代计划，直到满意为止。

对计划满意后，让 Claude 把它保存到 PRD.md.

同时创建一个空的进度文件：

touch progress.txt

PRD 定义最终状态，进度文件记录已完成内容。Claude 每次循环都会读取二者，找到下一个未勾选项目、实现它并更新进度。

PRD 可以采用任何格式：Markdown 清单、JSON 或普通文字。重要的是范围清晰，智能体能够提取独立任务。有关编写优秀 PRD 的技巧，请查看我的使用 Ralph 进行 AI 编码的 11 条技巧.

4. 创建你的 `ralph-once.sh` 脚本

在完全自动化之前 AFK，先从 human-in-the-loop Ralph 开始。运行脚本、观察行为，然后再次运行，以建立对循环工作方式的直觉。

创建 ralph-once.sh:

#!/bin/bash

claude --permission-mode acceptEdits "@PRD.md @progress.txt \
1. Read the PRD and progress file. \
2. Find the next incomplete task and implement it. \
3. Commit your changes. \
4. Update progress.txt with what you did. \
ONLY DO ONE TASK AT A TIME."

关键元素：

元素	用途
`--permission-mode acceptEdits`	自动接受文件编辑，避免循环停滞
`@PRD.md`	让 Claude 指向需求文档
`@progress.txt`	在多次运行之间记录已完成工作
`ONLY DO ONE TASK`	强制进行小而渐进的提交

赋予它执行权限：

chmod +x ralph-once.sh

使用以下方式运行： ./ralph-once.sh。观察 Claude 的行为，检查提交，然后再次运行。

5. 创建你的 `afk-ralph.sh` 脚本

熟悉 human-in-the-loop Ralph 后，再把它包装进循环：

#!/bin/bash
set -e

if [ -z "$1" ]; then
  echo "Usage: $0 <iterations>"
  exit 1
fi

for ((i=1; i<=$1; i++)); do
  result=$(docker sandbox run claude --permission-mode acceptEdits -p "@PRD.md @progress.txt \
  1. Find the highest-priority task and implement it. \
  2. Run your tests and type checks. \
  3. Update the PRD with what was done. \
  4. Append your progress to progress.txt. \
  5. Commit your changes. \
  ONLY WORK ON A SINGLE TASK. \
  If the PRD is complete, output <promise>COMPLETE</promise>.")

  echo "$result"

  if [[ "$result" == *"<promise>COMPLETE</promise>"* ]]; then
    echo "PRD complete after $i iterations."
    exit 0
  fi
done

这个 -p 标志会让 Claude 以 Print 模式运行：非交互式执行，并输出到 stdout。这样就能捕获结果并检查完成标记。

./afk-ralph.sh 20

去泡杯咖啡吧，回来时就能看到提交。

元素	用途
`set -e`	发生任何错误时退出
`$1` （迭代次数）	之前限制循环次数，防止成本失控
`-p`	Print 模式——非交互式输出
`<promise>COMPLETE</promise>`	完成后由 Claude 输出完成标记

AI Hero · 技能系统

Ralph 是循环，Skills 是循环内部的内容。

每次启动 Ralph 循环时，我都会在其中运行的斜杠命令和 Hook。

查看技能集

6. 按需定制

Ralph 只是一个循环，正是这种简单让它可以无限定制。

可以替换任务来源：不使用本地 PRD，而是从 GitHub Issues 获取任务， Linear，或者 beads。智能体仍会自行选择工作内容，你只是改变了任务列表的存放位置。

可以改变输出方式。每次迭代不必提交到 main，而可以创建分支并打开 PR，这对待办 issue 分诊很有用。

还可以运行完全不同的循环类型：

循环类型	作用
测试覆盖率	找出未覆盖代码行，持续编写测试直到达到目标覆盖率
Lint 检查	逐个修复 lint 错误
重复代码	接入 jscpd，把重复实现重构为共享工具函数
代码熵	扫描并清理代码异味

任何符合“查看仓库、改进某些内容、提交代码”的任务，都适合使用 Ralph。

有关反馈循环、任务拆分、优先级等更深入的指导，请阅读我的使用 Ralph 进行 AI 编码的 11 条技巧.

想进一步学习自主 AI 编码？加入我的 newsletter ，在新文章发布时获得通知。