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 将会：

创建一个功能分支（基于 PRD 中的 branchName）
选取 passes: false 的最高优先级故事
实现该故事
运行质量检查（类型检查、测试）
如果检查通过则提交代码
更新 prd.json，将该故事标记为 passes: true
将学习心得追加到 progress.txt
重复上述步骤，直到所有故事通过或达到最大迭代次数

核心文件

文件	用途
`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（哪些故事已完成）

小任务

（此处原文缺失内容，建议拆分复杂任务以获得最佳效果。）