血沃中原肥劲草，寒凝大地发春华——鲁迅

Ralph：一只不肯下班的自治 AI 工程师循环体——直到 PRD 全部打勾才肯停

Ralph 不是一个“聊天型”工具。

Ralph 更像是你团队里那个最较真、最执拗、最愿意熬夜的工程搭子：
你把 PRD 交给他，他不问“要不要我帮你想想”，他直接开跑——一轮、一轮、再一轮——直到 PRD 上每一个条目都被标记为完成。

它的自我介绍非常直接：

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.
Memory persists via git history, progress.txt, and prd.json.

一句话翻译成工程语言：
Ralph = 一个 Bash 循环 + 一个会写代码的 AI 工具 + 一个严格的任务列表（prd.json）+ 一个不断沉淀经验的日志（progress.txt）+ Git 作为“外置大脑”。

它基于 Geoffrey Huntley 提出的 Ralph pattern（“让 agent 一轮一轮跑、每轮都清空上下文、只把记忆落到文件/提交里”），并在 snarktank/ralph 里被打磨成可以直接搬进你项目的开源实现。

Ralph 的人格设定：每一轮都是“新的人”，但它会把经验写进地面

Ralph 有一个很反直觉、但特别强的核心信条：

Each Iteration = Fresh Context

每次迭代，Ralph 都会 spawn 一个全新的 AI 实例（Amp 或 Claude Code），上下文干干净净，不背历史包袱，不带情绪，不带幻觉记忆。

那它怎么“记得住”前面做了什么？

它只相信三样东西：

  • Git history：每轮做完就提交，提交本身就是记忆
  • progress.txt：把这一轮学到的“坑、规律、约定”追加写进去
  • prd.json：PRD 被拆成可执行的 user stories，并用 passes: true/false 记录完成状态

Ralph 的记忆不是“脑内回忆”，而是“落地材料”。
它像一只在工地上跑的鹿：跑完一段就往地上钉钉子、插旗子、写路标——下一轮新来的自己一看路标，就知道怎么走。

Ralph 最擅长的战场：把大任务切成“小到一轮能做完”的故事

Ralph 对任务大小极其挑剔，甚至有点“强迫症”。

它最在意的一条规则是：

Each PRD item should be small enough to complete in one context window.
If a task is too big, the LLM runs out of context before finishing and produces poor code.

它会在你写 PRD / 转换 PRD 的时候不断提醒你：
每个 story 必须“短小精悍”，一轮就能做完。

它认可的 right-sized stories 像这样：

  • Add a database column and migration
  • Add a UI component to an existing page
  • Update a server action with new logic
  • Add a filter dropdown to a list

它不喜欢这种“史诗级一句话”：

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

Ralph 不是不想做大事——它是把大事拆成一轮轮能推进、能验证、能提交的小事来做。
它是那种会说：“别空谈大目标，给我一条条验收标准。”

先决条件：Ralph 要吃的三样“口粮”

在把 Ralph 带进你的项目之前，它会先检查你是不是把它的口粮准备好了：

  • 安装并登录至少一个 AI coding tool：
    • Amp CLI（默认）
    • Claude Code（可选，README 给了安装命令：npm install -g @anthropic-ai/claude-code）
  • 安装 jq（macOS 可用 brew install jq）
  • 你的项目本身必须是一个 git repository（因为它用 git 当“记忆载体”）

Ralph 的态度很明确：
“我要循环跑任务，你得给我工具、给我验收、给我版本控制——不然我怎么证明我做完了？”

安装/接入：把 Ralph 搬进你的项目（Option 1）

Ralph 很愿意“寄住”在你的项目里，它不强迫你改造工程，只要你把它的几份关键文件拷进去。

README 的路径级接入方式是：在你的项目里创建一个脚本目录（比如 scripts/ralph），把 Ralph 的核心文件放进去，然后给它执行权限。

它的精神状态大概是：
“我不在乎你是 Next.js 还是 Django，我只要一个地方能跑 ralph.sh。”

另一种接入方式：把 skills 全局安装（Option 2）

Ralph 自己也带了 skills：

  • skills/prd/：用来生成 PRD（最终会保存到 tasks/prd-[feature-name].md）
  • skills/ralph/：把 PRD 转成 Ralph 可执行的 prd.json

README 里给的“全局安装”思路是：把 skills 复制到你的 Amp 配置目录，让所有项目都能用。

于是 Ralph 像一个工具箱管理员一样说：
“PRD 你别手写得太随缘，我给你一个 PRD skill；
PRD 转执行格式也别靠人肉，我给你一个转换 skill。”

建议配置：Amp auto-handoff（让 Ralph 更能扛长故事）

README 还提到一个推荐配置：开启 Amp 的自动 handoff，让它在 context 快满的时候自动交接，这样 Ralph 能处理更大的 story。

（Ralph 的口吻像在说：
“你当然应该把 story 拆小，但你要真没拆好，���也愿意帮你扛——前提是你把自动交接打开。”）

Ralph 的工作流：从 PRD 到 prd.json，再到循环交付

Ralph 的整个流水线有一种“生产线”美感，步骤非常清楚：

1）生成 PRD（prd skill）

你让 PRD skill 根据你的功能描述生成一个清晰可执行的需求文档。

它会先问你 3–5 个关键澄清问题（通常带选项），把不确定性消掉，然后输出一份结构化 PRD，并保存到：

  • tasks/prd-[feature-name].md

2）把 PRD 转成 Ralph 执行格式（ralph skill）

你再让 ralph skill 把这份 markdown PRD 转成 prd.json（Ralph 的任务清单）。

prd.json 的结构大概像这样（核心字段）：

  • branchName：Ralph 将用它创建 feature branch
  • userStories[]：每个 story 一个条目
    • id（US-001…）
    • priority（越小越先做）
    • acceptanceCriteria（必须清晰、可验证；并且通常包含 “Typecheck passes”）
    • passes：默认 false，Ralph 做完会改成 true
    • notes：提示/经验

3）启动 Ralph：开始“直到完成才停”的循环

当你把 prd.json 放好，Ralph 就可以开跑了：

1
./scripts/ralph/ralph.sh [max_iterations]

默认是 10 轮迭代。

Ralph 每一轮都会按固定节奏做事（像一个遵守 SOP 的工头）：

  1. 从 PRD 的 branchName 创建 feature branch
  2. 找到 passes: false 且优先级最高的 story
  3. 只实现这一条 story（一轮只做一件事）
  4. 跑质量检查（typecheck、tests）
  5. 通过就 commit
  6. 更新 prd.json：把这条 story 标记为 passes: true
  7. 把这一轮学到的东西追加写进 progress.txt
  8. 进入下一轮，直到全部 passes: true 或达到最大轮次

当所有 story 都完成时，它会吐出一个非常“程序化”的胜利宣言：

  • <promise>COMPLETE</promise>

像在说：
“我不口头说‘搞定了’，我用一个可机器识别的信号告诉你：真的完成了。”

Ralph 的关键文件们：它们像五个性格不同的队友

Ralph 的目录里，最重要的文件构成了它的“人格系统”：

  • ralph.sh：循环本体，负责一轮轮 spawn 新实例
  • prompt.md：给 Amp 的指令（每轮新的 Amp 实例都会读它）
  • CLAUDE.md：给 Claude Code 的指令（如果用 Claude Code）
  • prd.json：任务清单与完成状态（Ralph 的作业本）
  • progress.txt：每轮追加经验（Ralph 的“工地日志”）
  • AGENTS.md：Ralph 强调它很关键，属于“长期知识库”（工具会自动读取，下一轮/下一位开发者也能继承）

其中 AGENTS.md 的地位非常像“项目中的永久经验墙”：
这轮发现了什么模式、什么坑、什么约���，就贴上去——后面来的新实例一打开就能看到。

Flowchart：Ralph 还给自己画了一张“我怎么工作的动画说明书”

Ralph 不仅会干活，它还会解释自己怎么干活，而且是用一个可交互的流���图（React Flow）做成“演示级”的动画讲解。

README 里给了在线入口（Interactive Flowchart）。

如果你要在本地跑 flowchart：

1
2
3
cd flowchart
npm install
npm run dev

Ralph 看着这张 flowchart 的时候，大概会很骄傲：
“看见了吗？我不是玄学，我每一步都能画出来。”

Debugging：当你想知道 Ralph 现在跑到哪了

Ralph 也不介意你盯着它干活，它甚至很鼓励你把状态看清楚。

比如查看哪些 story 已完成：

1
cat prd.json | jq '.userStories[] | {id, title, passes}'

查看之前每轮沉淀的经验：

1
cat progress.txt

查看最近提交（也就是它的“记忆轨迹”）：

1
git log --oneline -10

Ralph 的精神状态非常健康：
“我不怕审计，我的每一步都写在文件里、写在提交里。”

Ralph 的真正力量：反���回路（Feedback Loops）必须存在

Ralph 不是靠“多跑几轮就会成功”的迷信维持运转的，它靠的是反馈回路：

  • typecheck 抓类型错误
  • tests 验证行为
  • CI 必须保持 green（坏代码会在下一轮越滚越大）

它像一个严格的教练：
“你可以迭代，但你必须每轮都有真实反馈，不然你只是反复自我感动。”

前端故事的硬要求：必须写“用 dev-browser 验证”

Ralph 对 UI story 的验收更苛刻：
前端故事必须在 acceptance criteria 里包含：

  • “Verify in browser using dev-browser skill”

因为它会真的去用浏览器验证 UI。

它不接受“我看着应该行”。
它的语气像：“你别猜，你给我验。”

结语：Ralph 像什么？

Ralph 像一台“自治交付机器”，但它又非常“像人”——

  • 它每轮都会失忆，但会写笔记
  • 它不争辩，但坚持验收
  • 它不承诺空话，只输出 <promise>COMPLETE</promise>
  • 它不靠灵感推进，靠拆解、优先级、反馈回路推进

当你把一个 PRD 交给它，它就像戴上安全帽、拎起工具箱、打开终端：

“行，别催。
我一轮一轮跑，直到所有 checkbox 都被我打上勾。”