中文 | English

Ralph

Ralph 是一个自主 AI agent loop，它会反复运行 AI 编码工具（Amp 或 Claude Code），直到所有 PRD 条目都完成。每一轮迭代都是一个全新的实例，拥有干净的上下文。记忆通过 git 历史、progress.txt 和 prd.json 持久化。

它基于 Geoffrey Huntley 提出的 Ralph 模式。

阅读我关于如何使用 Ralph 的深入文章

前置条件

• 已安装并完成认证的 AI 编码工具之一
• 已安装 jq（macOS 可用 brew install jq）
• 你的项目本身是一个 git 仓库

安装

方案 1：复制到你的项目

把 Ralph 文件复制到你的项目里：

# 在项目根目录执行
mkdir -p scripts/ralph
cp /path/to/ralph/ralph.sh scripts/ralph/

# 复制你所使用 AI 工具对应的 prompt 模板：
cp /path/to/ralph/prompt.md scripts/ralph/prompt.md    # 适用于 Amp
# 或
cp /path/to/ralph/CLAUDE.md scripts/ralph/CLAUDE.md    # 适用于 Claude Code

chmod +x scripts/ralph/ralph.sh

方案 2：全局安装 skills（Amp）

把 skills 复制到你的 Amp 或 Claude 配置目录，以便所有项目都能使用：

对于 AMP：

cp -r skills/prd ~/.config/amp/skills/
cp -r skills/ralph ~/.config/amp/skills/

对于 Claude Code（手动安装）：

cp -r skills/prd ~/.claude/skills/
cp -r skills/ralph ~/.claude/skills/

方案 3：作为 Claude Code Marketplace 使用

把 Ralph marketplace 添加到 Claude Code：

/plugin marketplace add snarktank/ralph

然后安装 skills：

/plugin install ralph-skills@ralph-marketplace

安装后可用的 skills：

• /prd：生成 Product Requirements Document
• /ralph：把 PRD 转成 prd.json 格式

当你向 Claude 提出如下请求时，这些 skills 会被自动调用：

• “create a prd”、“write prd for”、“plan this feature”
• “convert this prd”、“turn into ralph format”、“create prd.json”

把下面配置加入 ~/.config/amp/settings.json：

{
  "amp.experimental.autoHandoff": { "context": 90 }
}

这会在上下文将满时启用自动 handoff，让 Ralph 能处理超出单一上下文窗口的大型 story。

工作流

1. 创建 PRD

使用 PRD skill 生成详细需求文档：

Load the prd skill and create a PRD for [your feature description]

回答澄清问题后，skill 会把输出保存到 tasks/prd-[feature-name].md。

2. 把 PRD 转成 Ralph 格式

使用 Ralph skill 把 markdown PRD 转成 JSON：

Load the ralph skill and convert tasks/prd-[feature-name].md to prd.json

这会创建 prd.json，其中的 user stories 结构适合自主执行。

3. 运行 Ralph

# 使用 Amp（默认）
./scripts/ralph/ralph.sh [max_iterations]

# 使用 Claude Code
./scripts/ralph/ralph.sh --tool claude [max_iterations]

默认是 10 轮迭代。使用 --tool amp 或 --tool claude 选择 AI 编码工具。

Ralph 会：

1. 创建 feature branch（来自 PRD 中的 branchName）
2. 选出优先级最高且 passes: false 的 story
3. 只实现这一条 story
4. 运行质量检查（typecheck、tests）
5. 如果检查通过则提交
6. 更新 prd.json，把该 story 标记为 passes: true
7. 将学习结果追加到 progress.txt
8. 重复执行，直到所有 story 通过，或达到最大迭代次数

关键文件

文件	作用
ralph.sh	启动全新 AI 实例的 bash 循环（支持 --tool amp 或 --tool claude）
prompt.md	Amp 使用的 prompt 模板
CLAUDE.md	Claude Code 使用的 prompt 模板
prd.json	带有 passes 状态的 user stories（任务列表）
prd.json.example	供参考的 PRD 格式样例
progress.txt	追加式学习记录，供后续迭代读取
skills/prd/	生成 PRD 的 skill（Amp 和 Claude Code 都可用）
skills/ralph/	把 PRD 转成 JSON 的 skill（Amp 和 Claude Code 都可用）
.claude-plugin/	供 Claude Code marketplace 发现的插件 manifest
flowchart/	Ralph 工作方式的交互式可视化

Flowchart

查看交互式流程图 - 可点击查看每一步及其动画演示。

flowchart/ 目录包含源代码。要在本地运行：

cd flowchart
npm install
npm run dev

关键概念

每一轮迭代 = 全新上下文

每一轮迭代都会启动一个新的 AI 实例（Amp 或 Claude Code），并拥有干净上下文。各轮之间仅通过以下内容保留记忆：

• Git 历史（前一轮迭代的提交）
• progress.txt（学习结果与上下文）
• prd.json（哪些 story 已完成）

小任务

每个 PRD 条目都应足够小，能在一个上下文窗口内完成。如果任务太大，LLM 会在完成前耗尽上下文，导致代码质量变差。

合适大小的 story：

• 添加一个数据库字段和对应 migration
• 在已有页面上加一个 UI 组件
• 更新一个 server action 的逻辑
• 给列表增加一个过滤下拉框

太大的任务（需要拆分）：

• “Build the entire dashboard”
• “Add authentication”
• “Refactor the API”

更新 AGENTS.md 很关键

每轮迭代之后，Ralph 都会把新学习到的内容更新到相关 AGENTS.md 文件里。这一点很关键，因为 AI 编码工具会自动读取这些文件，所以后续迭代（以及未来的人类开发者）都能继承新发现的模式、坑点和约定。

适合写入 AGENTS.md 的内容示例：

• 新发现的模式（“这个代码库在 Y 场景下使用 X”）
• 坑点（“改 W 时不要忘记同步更新 Z”）
• 有用上下文（“settings panel 位于组件 X 中”）

反馈回路

只有在存在反馈回路时，Ralph 才真正有效：

• Typecheck 能捕获类型错误
• Tests 能验证行为
• CI 必须保持绿色（坏代码会在迭代中不断累积）

针对 UI story 的浏览器验证

前端 story 必须在验收标准里包含 “Verify in browser using dev-browser skill”。这样 Ralph 会使用 dev-browser skill 访问页面、操作 UI，并确认修改确实生效。

停止条件

当所有 story 都满足 passes: true 时，Ralph 会输出 <promise>COMPLETE</promise>，循环随即退出。

调试

查看当前状态：

# 查看哪些 story 已完成
cat prd.json | jq '.userStories[] | {id, title, passes}'

# 查看前几轮迭代留下的学习记录
cat progress.txt

# 查看 git 历史
git log --oneline -10

自定义 Prompt

把 prompt.md（Amp）或 CLAUDE.md（Claude Code）复制到你的项目后，可以按项目需要自行调整：

• 加入项目专用的质量检查命令
• 写入代码库约定
• 补充你技术栈里的常见坑点

归档

当你启动一个新 feature（即 branchName 变化）时，Ralph 会自动归档先前运行结果。归档会保存在 archive/YYYY-MM-DD-feature-name/。

参考资料

• Geoffrey Huntley 的 Ralph 文章
• Amp 文档
• Claude Code 文档