Ralph 自主 Agent 循环实战指南：用 AGENTS.md 驱动 Amp/Claude Code 完成全部 PRD 条目-育师

人工智能
AI Agent
Agent 工作流
AI 技能

【免费下载链接】ralph

Ralph is an autonomous AI agent loop that runs repeatedly until all PRD items are complete.

项目地址：https://gitcode.com/GitHub_Trending/ralph1/ralph

Ralph 是一个长时间运行的自主 AI Agent 循环（autonomous AI agent loop），它会反复启动全新的 AI 编码工具实例（Amp 或 Claude Code），直到 PRD 中的所有条目全部完成。本文以 AGENTS.md 为核心脉络，结合仓库中的 ralph.sh、prompt.md、CLAUDE.md、prd.json.example 与 flowchart 等源码与配置文件，系统讲解循环机制、命令行用法、关键文件职责、流程图可视化，以及让循环持续收敛的工程模式。读完你将能够：在任意项目里搭建并运行 Ralph，把一份 PRD 拆成可在单次上下文窗口内完成的小故事，并用 git 历史、progress.txt、prd.json三样持久化手段让每次迭代都站在上一次的肩膀上继续前进。

上图基于 flowchart 目录中 React Flow 实现的交互式可视化生成，展示 Ralph 从"编写 PRD"到"全部故事完成"的完整循环。

什么是 Ralph：一次迭代一个干净上下文的自主循环

Ralph 的核心定义（见 AGENTS.md Overview 一节）只有一句话：

Ralph is an autonomous AI agent loop that runs AI coding tools (Amp or Claude Code) repeatedly until all PRD items are complete. Each iteration is a fresh instance with clean context.

拆解这句话，可以得到三个关键设计点：

自主（autonomous）：一旦启动，Ralph 不再需要人工介入，由脚本循环驱动 AI 工具自动"读 PRD → 挑故事 → 实现 → 质检 → 提交 → 更新状态 → 记录学习"；
循环（loop）：一次迭代只完成一个用户故事，完成后自动进入下一轮，直到所有故事passes: true或达到最大迭代次数；
每次迭代都是全新实例（fresh instance with clean context）：这是与普通"长对话"式 Agent 最本质的区别——每轮迭代都从零启动一个干净的 AI 上下文，不携带上一轮的对话记忆。

由于每轮上下文都是全新的，跨迭代的"记忆"只能依靠外部持久化载体，也就是 AGENTS.md Patterns 一节明确列出的三样东西：

持久化载体	作用
git 历史（commits from previous iterations）	保存每次迭代的代码变更与提交信息
`progress.txt`	追加式的学习日志，记录模式、坑与上下文
`prd.json`	任务清单本身，记录哪些故事已完成（`passes: true`）

这一"无状态实例 + 有状态文件"的架构（详见 README.md 的 Critical Concepts 一节），是 Ralph 能够长时间可靠运行而不"跑偏"的根本原因。

命令行用法：启动与停止循环

AGENTS.md Commands 一节给出了 Ralph 的全部核心命令，可直接在仓库根目录执行：

# 运行 flowchart 开发服务器 cd flowchart && npm run dev # 构建 flowchart cd flowchart && npm run build # 用 Amp 运行 Ralph（默认工具） ./ralph.sh [max_iterations] # 用 Claude Code 运行 Ralph ./ralph.sh --tool claude [max_iterations]

其中：

[max_iterations]为可选参数，缺省时默认10 次迭代（见 ralph.sh 的MAX_ITERATIONS=10）；
--tool amp或--tool claude选择 AI 编码工具，缺省为amp（为保持向后兼容，见 ralph.sh 注释）。

参数解析与校验（源码级）

查看 ralph.sh 可以发现，脚本对参数的解析相当宽容：既支持--tool claude空格分隔写法，也支持--tool=claude等号写法；其余位置参数只要匹配^[0-9]+$就会被当作max_iterations。若--tool的值不是amp或claude，脚本会立即报错退出：

Error: Invalid tool 'xxx'. Must be 'amp' or 'claude'.

每次迭代实际执行了什么

ralph.sh 的for循环是循环体的核心实现：

打印当前迭代序号与所用工具（Ralph Iteration $i of $MAX_ITERATIONS）；
按工具分支启动全新 AI 实例：
- Amp：cat "$SCRIPT_DIR/prompt.md" | amp --dangerously-allow-all（ralph.sh）；
- Claude Code：claude --dangerously-skip-permissions --print < "$SCRIPT_DIR/CLAUDE.md"（ralph.sh），其中--print用于非交互式输出捕获；
捕获输出，检查是否包含完成信号<promise>COMPLETE</promise>（ralph.sh）；
命中完成信号则打印 "Ralph completed all tasks!" 并以exit 0正常退出（ralph.sh）；
否则sleep 2后进入下一轮迭代。

当达到最大迭代次数仍未完成时，脚本以exit 1退出并提示检查progress.txt查看状态（ralph.sh）。

分支切换与自动归档

ralph.sh还内置了运行管理逻辑（ralph.sh）：

通过jq -r '.branchName // empty'读取当前prd.json中的branchName，并与.last-branch文件比对；
若分支发生变化，会把上一次运行的prd.json与progress.txt归档到archive/YYYY-MM-DD-feature-name/（其中ralph/前缀会被剥除以作为目录名），并重置progress.txt；
若progress.txt不存在则自动初始化带时间戳的头部。

注意前置条件：脚本依赖jq解析 JSON（macOS 可用brew install jq安装，见 README.md Prerequisites）。

关键文件：循环的"大脑"与"账本"

AGENTS.md Key Files 一节给出了每个文件在整个循环中的角色：

文件	角色
ralph.sh	bash 循环脚本，负责每次生成全新 AI 实例（支持`--tool amp`或`--tool claude`）
prompt.md	交给每个 Amp 实例的指令
CLAUDE.md	交给每个 Claude Code 实例的指令
prd.json.example	示例 PRD 格式
flowchart	用 React Flow 制作的交互式图解，说明 Ralph 的工作原理

prompt.md与CLAUDE.md本质上是同一套"迭代内任务清单"的两个方言版本，核心流程完全一致（详见 prompt.md 与 CLAUDE.md）：

读取prd.json（与指令文件同目录）；
读取progress.txt，先看## Codebase Patterns部分；
校验当前分支是否等于 PRD 的branchName，不符则从main检出或创建；
挑选priority 最高且passes: false的用户故事；
只实现这一个故事；
运行项目质量检查（typecheck、lint、test 等）；
若发现可复用模式，更新 AGENTS.md / CLAUDE.md；
检查通过后，以feat: [Story ID] - [Story Title]格式提交所有变更；
更新prd.json，将该故事passes置为true；
将进度追加到progress.txt。

prd.json：循环的任务清单

prd.json.example 展示了标准格式：顶层包含project、branchName（如ralph/task-priority）、description和userStories数组。每个用户故事含id（US-001 风格）、title、description（"As a ... I want ... so that ..." 格式）、acceptanceCriteria（可验证的验收清单）、priority（数值，越小越优先）、passes（布尔，初始为false）与notes。

在示例中，四个故事从"数据库加字段"（US-001）到"展示优先级徽章"（US-002）再到"编辑时改优先级"（US-003）最后到"按优先级过滤"（US-004），呈现典型的"数据层 → 展示层 → 交互层"依赖顺序，且每个故事的验收标准都包含"Typecheck passes"，UI 故事额外包含"Verify in browser using dev-browser skill"。

progress.txt：追加式学习账本

迭代内指令要求进度报告只能追加、绝不替换（见 CLAUDE.md 的 Progress Report Format），格式为：

## [Date/Time] - [Story ID] - What was implemented - Files changed - **Learnings for future iterations:** - Patterns discovered (e.g., "this codebase uses X for Y") - Gotchas encountered (e.g., "don't forget to update Z when changing W") - Useful context (e.g., "the evaluation panel is in component X") ---

其中 Learnings 部分被明确标注为"critical"——它帮助未来的迭代避免重复犯错并更快理解代码库。此外，一旦发现通用可复用的模式，应将其合并进progress.txt顶部的## Codebase Patterns区块（不存在则创建）；只有通用且可复用的模式才够格进入该区块，故事专属的细节不应写入（CLAUDE.md）。

AGENTS.md / CLAUDE.md：迭代间的"模式传播"

每次提交前，AI 需要检查被修改的目录及其父目录是否存在 AGENTS.md（或 CLAUDE.md），并将真正可复用的知识写入：

该模块的 API 模式或约定；
坑或非显而易见的需求；
文件之间的依赖关系；
该区域的测试方法；
配置或环境要求。

CLAUDE.md 明确给出好例子（"修改 X 时也要同步修改 Y"、"该模块所有 API 调用使用模式 Z"、"测试需要 dev server 运行在 PORT 3000"）与禁止项（故事专属细节、临时调试笔记、progress.txt里已有的信息）。这正是 AGENTS.md Patterns 一节中"Always update AGENTS.md with discovered patterns"的含义：因为 AI 编码工具会自动读取这些文件，未来迭代（乃至未来的人类开发者）都能从中受益。

停止条件：循环何时收敛

迭代内指令在完成任务后必须判断是否还有剩余故事（见 CLAUDE.md Stop Condition）：

若所有故事均passes: true，回复<promise>COMPLETE</promise>——ralph.sh 通过 grep 检测到该信号后打印完成信息并exit 0；
若仍有passes: false的故事，则正常结束本轮回复，由下一轮迭代接手下一个故事。

交互式流程图：用 React Flow 讲清循环

flowchart 是一个基于 React Flow 构建的交互式可视化，专为演示设计——点击逐步骤展开并带动画（见 AGENTS.md Flowchart 一节）。本地运行方式：

cd flowchart npm install npm run dev

从源码结构看（flowchart/src/App.tsx），整个流程被建模为四个阶段（Phase类型：setup/loop/decision/done），用不同颜色区分（见 App.tsx）：

setup 准备阶段：You write a PRD → Convert to prd.json → Run ralph.sh；
loop 循环阶段：AI picks a story（找下一个passes: false）→ Implements it（写代码、跑测试）→ Commits changes（测试通过才提交）→ Updates prd.json（置passes: true）→ Logs to progress.txt（保存学习，同时更新 AGENTS.md）；
decision 决策节点："More stories?"——Yes 则回到"AI picks a story"，No 则进入完成节点；
done 完成节点：Done!（所有故事完成）。

每个节点渲染为自定义组件（CustomNode，见 App.tsx），带四向 Handle 支持连线，边带箭头标记（MarkerType.ArrowClosed）与动画；附注节点（NoteNode）会在特定步骤出现，例如在"Convert to prd.json"旁展示一条真实的用户故事 JSON 示例，在"Logs to progress.txt"旁说明"也会更新 AGENTS.md 以便未来迭代从中学习"（App.tsx）。交互上支持 Previous / Next / Reset 逐步展示（App.tsx），这也是演示场景的核心体验。

让循环可靠收敛的工程模式

AGENTS.md Patterns 一节浓缩了 Ralph 能长期稳定工作的四条模式，每一条都能在上游源码中找到对应机制：

1. 每次迭代生成全新 AI 实例、上下文干净由 ralph.sh 的工具分支直接保证；相应地，跨迭代记忆完全依赖 git 历史、progress.txt与prd.json三样载体（README.md Critical Concepts）。

2. 故事要小到能在一个上下文窗口内完成skills/ralph/SKILL.md 给出判断标准："每个故事必须能在一次 Ralph 迭代（一个上下文窗口）内完成"，经验法则是一句话能描述清楚的改动才够小；如果无法用 2-3 句话描述，就说明太大了。合理的粒度包括：给表加一列并写迁移、给既有页面加一个 UI 组件、给服务端 action 更新一段逻辑、给列表加一个过滤下拉框。

3. AGENTS.md 更新是循环收敛的关键每次迭代后把发现的模式、坑与约定写回 AGENTS.md（CLAUDE.md），由于 AI 编码工具会自动读取这些文件，后续迭代和人类开发者都能受益（README.md Critical Concepts 的 "AGENTS.md Updates Are Critical"）。

4. 必须有反馈闭环typecheck 捕获类型错误、测试验证行为、CI 保持绿色——"破损的代码会跨迭代累积"（broken code compounds across iterations），因此 Ralph 只有在存在这些反馈信号时才可靠（README.md Critical Concepts 的 "Feedback Loops"）。

另外两条针对 UI 故事的补充模式：验收标准必须包含"Verify in browser using dev-browser skill"，前端故事在浏览器验证通过之前不算完成（见 prompt.md 的 Browser Testing 一节）；以及调试时可以随时用cat prd.json | jq '.userStories[] | {id, title, passes}'查看哪些故事已完成、cat progress.txt查看过往学习、git log --oneline -10查看提交历史（README.md Debugging）。

在你的项目中启用 Ralph

仓库 README.md Setup 提供了三种接入方式，可任选其一：

方式一：复制到你的项目——把ralph.sh、prompt.md（Amp 用）或CLAUDE.md（Claude Code 用）拷入scripts/ralph/，并chmod +x；
方式二：全局安装 skills（Amp/Claude）——将skills/prd与skills/ralph复制到~/.config/amp/skills/或~/.claude/skills/，从而在任何项目里直接调用/prd生成 PRD、/ralph把 PRD 转换为prd.json；
方式三：Claude Code Marketplace 插件——通过/plugin marketplace add snarktank/ralph与/plugin install ralph-skills@ralph-marketplace安装技能。

启动前建议按 README.md 的 "Configure Amp auto-handoff (recommended)" 为 Amp 开启自动交接：

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

这允许上下文填满时自动交接，使 Ralph 也能承载超出单个上下文窗口的大故事。整个工作流（README.md Workflow）可概括为三步：先用 prd skill 生成 PRD 到tasks/prd-[feature-name].md，再用 ralph skill 转换为prd.json，最后运行./ralph.sh（或./ralph.sh --tool claude）让循环自主推进。需要针对项目定制时，还可以在复制后修改prompt.md/CLAUDE.md，加入项目专属的质量检查命令、代码库约定与常见坑（README.md Customizing the Prompt）。