Ralph

Ralph 是一个自主 AI Agent 循环，它会不断运行 AI 编码工具（Amp 或 Claude Code），直到所有 PRD（产品需求文档）项完成为止。每次迭代都是一个具备干净上下文的全新实例。内存通过 git 提交历史、progress.txt 和 prd.json 进行持久化存储。

基于 Geoffrey Huntley 的 Ralph 模式。

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

前置要求

• 安装并验证了以下 AI 编码工具之一：
  • Amp CLI (默认)
  • Claude Code (npm install -g @anthropic-ai/claude-code)
• 安装了 jq (macOS 下执行 brew install jq)
• 一个用于项目的 git 仓库

设置

方案 1：复制到你的项目中

将 ralph 文件复制到你的项目中：

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

# 复制你选择的 AI 工具的提示词模板：
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：全局安装技能 (Amp)

将技能复制到你的 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 插件使用

将 Ralph 市场插件添加到 Claude Code：

/plugin marketplace add snarktank/ralph

然后安装技能：

/plugin install ralph-skills@ralph-marketplace

安装后可用的技能：

• /prd - 生成产品需求文档
• /ralph - 将 PRD 转换为 prd.json 格式

当你要求 Claude 执行以下操作时，技能会自动触发：

• "create a prd", "write prd for", "plan this feature"
• "convert this prd", "turn into ralph format", "create prd.json"

配置 Amp 自动交接 (推荐)

在 ~/.config/amp/settings.json 中添加：

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

这可以在上下文填满时启用自动交接，允许 Ralph 处理超出单个上下文窗口的大型需求。

工作流程

1. 创建 PRD

使用 PRD 技能生成详细的需求文档：

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

回答澄清性问题。该技能会将输出保存到 tasks/prd-[feature-name].md。

2. 将 PRD 转换为 Ralph 格式

使用 Ralph 技能将 Markdown 格式的 PRD 转换为 JSON：

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

这会创建一个包含结构化用户故事的 prd.json，用于自主执行。

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. 创建功能分支（来自 PRD 中的 branchName）
2. 选取 passes: false 的优先级最高的故事
3. 实现该单个故事
4. 运行质量检查（类型检查、测试）
5. 如果检查通过则提交代码
6. 更新 prd.json 将故事标记为 passes: true
7. 将学习到的内容追加到 progress.txt
8. 重复上述步骤，直到所有故事通过或达到最大迭代次数

关键文件

文件	用途
ralph.sh	启动全新 AI 实例的 bash 循环（支持 --tool amp 或 --tool claude）
prompt.md	Amp 的提示词模板
CLAUDE.md	Claude Code 的提示词模板
prd.json	带有 passes 状态的用户故事列表（任务清单）
prd.json.example	供参考的 PRD 格式示例
progress.txt	只追加的学习心得，用于后续迭代
skills/prd/	用于生成 PRD 的技能（适用于 Amp 和 Claude Code）
skills/ralph/	用于将 PRD 转换为 JSON 的技能（适用于 Amp 和 Claude Code）
.claude-plugin/	Claude Code 市场发现的插件清单
flowchart/	Ralph 工作流程的交互式可视化

流程图

查看交互式流程图 - 点击查看带有动画的每一步流程。

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

cd flowchart
npm install
npm run dev

核心概念

每次迭代 = 全新上下文

每次迭代都会启动一个带有干净上下文的 新 AI 实例（Amp 或 Claude Code）。迭代之间仅保留以下内存：

• Git 历史（之前迭代的提交）
• progress.txt（学习心得和上下文）
• prd.json（哪些故事已完成）

小任务