snarktank/ralph
GitHub: snarktank/ralph
Ralph 是一个基于 AI 代理循环的自动化编码工具，将 PRD 逐步实现直至所有任务完成。
Stars: 16742 | Forks: 1654
# 拉尔夫
Ralph 是一个自主 AI 代理循环，它会重复运行 AI 编码工具（[Amp](https://ampcode.com) 或 [Claude Code](https://docs.anthropic.com/en/docs/claude-code))，直到所有 PRD 项目完成。每次迭代都是一个具有全新上下文的独立实例。记忆通过 Git 历史、`progress.txt` 和 `prd.json` 持久化。
灵感来源于 [Geoffrey Huntley 的 Ralph 模式](https://ghuntley.com/ralph/)。
[阅读我关于如何使用 Ralph 的深入文章](https://x.com/ryancarson/status/2008548371712135632)
## 前置条件
- 已安装并认证以下 AI 编码工具之一：
- [Amp CLI](https://ampcode.com)（默认）
- [Claude Code](https://docs.anthropic.com/en/docs/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 # For Amp
# 或
cp /path/to/ralph/CLAUDE.md scripts/ralph/CLAUDE.md # For 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 中输入以下指令时，技能会自动调用：
- “创建 PRD”、“为……编写 PRD”、“规划此功能”
- “转换此 PRD”、“转为 Ralph 格式”、“创建 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 工作流程的交互式可视化 |
## 流程图
[](https://snarktank.github.io/ralph/)
**[查看交互式流程图](https://snarktank.github.io/ralph/)** - 点击查看带动画的每一步。
`flowchart/` 目录包含源代码。本地运行方式：
```
cd flowchart
npm install
npm run dev
```
## 关键概念
### 每次迭代 = 全新上下文
每次迭代都会启动一个**新的 AI 实例**（Amp 或 Claude Code），上下文是干净的。迭代之间的唯一记忆包括：
- Git 历史（来自之前迭代的提交）
- `progress.txt`（学习记录和上下文）
- `prd.json`（已完成的故事）
### 小型任务
每个 PRD 项目应足够小，能够在一个上下文窗口内完成。如果任务过大，LLM 会在完成前耗尽上下文并产生低质量代码。
合适规模的故事示例：
- 添加数据库列及其迁移
- 向现有页面添加 UI 组件
- 使用新逻辑更新服务器操作
- 向列表添加筛选下拉框
过大（需要拆分）的任务：
- “构建整个仪表板”
- “添加身份验证”
- “重构 API”
### AGENTS.md 更新至关重要
每次迭代后，Ralph 会将相关学习记录更新到对应的 `AGENTS.md` 文件中。这很关键，因为 AI 编码工具会自动读取这些文件，使后续迭代以及未来的人类开发者都能受益于发现的模式、注意事项和约定。
添加到 AGENTS.md 的示例：
- 发现的模式（“此代码库使用 X 实现 Y”）
- 注意事项（“修改 W 时不要忘记更新 Z”）
- 有用上下文（“设置面板位于组件 X 中”）
### 反馈循环
Ralph 仅在存在反馈循环时才能工作：
- 类型检查捕获类型错误
- 测试验证行为
- CI 必须保持绿色（错误代码会在迭代中累积）
### 浏览器验证用于 UI 故事
前端故事必须在验收标准中包含“在浏览器中使用 dev-browser 技能验证”。Ralph 将使用 dev-browser 技能访问页面、与 UI 交互并确认更改是否生效。
### 停止条件
当所有故事的 `passes: true` 时，Ralph 会输出 `COMPLETE ` 并退出循环。
## 调试
查看当前状态：
```
# 查看已完成的故事
cat prd.json | jq '.userStories[] | {id, title, passes}'
# 查看以往迭代的学习成果
cat progress.txt
# 检查 Git 历史
git log --oneline -10
```
## 自定义提示
复制 `prompt.md`（用于 Amp）或 `CLAUDE.md`（用于 Claude Code）到你的项目后，根据需要进行自定义：
- 添加项目特定的质量检查命令
- 包含代码库约定
- 添加栈相关的常见注意事项
## 归档
当开始新特性（不同的 `branchName`）时，Ralph 会自动归档之前的运行记录，归档路径为 `archive/YYYY-MM-DD-feature-name/`。
## 参考
- [Geoffrey Huntley 的 Ralph 文章](https://ghuntley.com/ralph/)
- [Amp 文档](https://ampcode.com/manual)
- [Claude Code 文档](https://docs.anthropic.com/en/docs/claude-code)
标签：AI 代理, AI 编程, Amp CLI, Claude Code, CLI 工具, Git 记忆, MITM代理, PRD 生成, 上下文管理, 产品需求文档, 代码自动化, 应用安全, 开发效率, 循环执行, 技能插件, 提示词工程, 策略决策点, 网络可观测性, 网络安全研究, 脚本自动化, 自主代理, 自动化开发, 自动化攻击, 重复任务自动化, 项目初始化