ralph-loop-workflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ralph Loop Workflow

Ralph 循环工作流

Run a coding agent in an autonomous loop that breaks a wide prompt into tasks and builds, tests, and ships each one.

让编码Agent以自主循环模式运行，将宽泛的提示词拆解为任务，逐一完成构建、测试与交付。

Prerequisites

前置条件

Complete these setup recipes first:

AI Coding Agent Configuration
Code Health, Linting & Formatting
Testing

请先完成以下配置步骤：

AI Coding Agent 配置
代码健康、代码检查与格式化
测试

The Loop

循环机制

Ralph maximizes how long the agent runs without human intervention. The goal is not a file format — it is keeping the agent able to plan, build, and verify on its own. The durable record of intent lives in the artifacts the agent produces: tests (executable acceptance criteria), user-facing docs, and a changelog for published libraries.

input prompt
  -> preflight check (CLIs installed, linked, authenticated)
  -> agent harness managed todo list (first-principles task breakdown)
  -> code + user-facing docs + changelog + tests
  -> verification (typecheck, fmt, fallow, browser, tests, deploy, prod check)
  -> iterate

Give the agent a wide, outcome-focused prompt and let its own harness manage the todo list — there is no separate user-story file to author or check off.

If no prompt is given, STOP and ask the user: "What outcome do you want the Ralph loop to drive toward? Give me a wide, outcome-focused prompt and I'll break it into tasks." Wait for their answer before continuing.

Run the preflight check once. If anything is missing or unauthenticated, report the exact fix commands and STOP — the loop does not start until everything is green. Then each iteration:

Read the current state of the codebase and any prior progress.
Break remaining work into tasks with first-principles thinking.
Pick the highest-priority task.
Implement it through the dev workflow: write tests, build, generate and migrate DB schema if needed, format.
Verify: typecheck, build, tests, and browser interaction at
```
http://localhost:3000
```
.
Debug and fix until verification passes.
Update user-facing docs and the changelog for any published artifacts.
Commit with a descriptive message and move to the next task.

Keep the dev server running (

bun run dev

). The agent works against a test database, so it can migrate freely. The loop ends when no tasks remain and all verification passes.

Ralph的目标是最大化Agent无需人工干预的运行时长。核心并非特定文件格式，而是让Agent能够自主完成规划、构建与验证。意图的持久记录体现在Agent生成的产物中：测试用例（可执行验收标准）、面向用户的文档，以及已发布库的变更日志。

输入提示词
  -> 预检检查（CLI已安装、关联并完成身份验证）
  -> Agent管理的待办事项列表（基于第一性原理拆解任务）
  -> 代码 + 面向用户的文档 + 变更日志 + 测试用例
  -> 验证（类型检查、格式化、fallow、浏览器测试、用例执行、部署、生产环境检查）
  -> 迭代

为Agent提供宽泛的、以结果为导向的提示词，让其自身的管理机制处理待办事项——无需单独编写或核对用户故事文件。

若未提供提示词，请立即停止并询问用户：“你希望Ralph循环实现什么结果？请提供一个宽泛的、以结果为导向的提示词，我会将其拆解为任务。”等待用户回复后再继续。

预检检查仅执行一次。若存在缺失项或未完成身份验证的情况，需报告具体的修复命令并停止——所有项状态正常后方可启动循环。之后每次迭代包含以下步骤：

读取代码库当前状态及过往进度。
基于第一性原理将剩余工作拆解为任务。
选择优先级最高的任务。
通过开发工作流实现：编写测试用例、构建代码、按需生成并迁移数据库 schema、格式化代码。
验证：类型检查、构建、测试用例执行，以及在
```
http://localhost:3000
```
进行浏览器交互测试。
调试并修复问题，直至验证通过。
更新面向用户的文档及已发布产物的变更日志。
提交带有描述性信息的代码，然后进入下一个任务。

保持开发服务器运行（

bun run dev

）。Agent基于测试数据库工作，可自由执行迁移操作。当无剩余任务且所有验证均通过时，循环结束。

What the Agent Needs

Agent所需条件

Nothing Ralph-specific to install — the loop depends on three things being in place:

Context — how to work in this codebase (patterns, dev workflow, conventions), via
```
AGENTS.md
```
, configured MCP servers, and installed skills.
Tools — to provision resources, run migrations, pull logs, and inspect deployments, via the project's MCP servers and CLIs. Give the agent the same tools you use.
Verification — what extends autonomous runway. The agent must check its own work locally and in production:
- Code health —
```
bun run typecheck
```
  ,
```
bun run fmt
```
  ,
```
bun run fallow
```
- Tests —
```
bun run test
```
  against an isolated database branch (Playwright, integration, unit)
- Browser —
```
agent-browser
```
  to interact with the running app like a user
- Logs & deploys — pull deployment and runtime logs to confirm changes shipped and work in production

When verification is trustworthy and self-serve, the agent catches and fixes its own regressions without a human in the loop.

无需安装Ralph专属组件——循环依赖以下三项配置：

上下文 —— 如何在该代码库中工作（模式、开发工作流、约定），通过
```
AGENTS.md
```
、已配置的MCP服务器及已安装的技能实现。
工具 —— 用于配置资源、执行迁移、拉取日志及检查部署，通过项目的MCP服务器和CLI实现。为Agent提供与你相同的工具。
验证机制 —— 延长自主运行时长的关键。Agent必须能在本地及生产环境中自查工作成果：
- 代码健康 ——
```
bun run typecheck
```
  、
```
bun run fmt
```
  、
```
bun run fallow
```
- 测试 —— 在隔离的数据库分支上执行
```
bun run test
```
  （Playwright、集成测试、单元测试）
- 浏览器 ——
```
agent-browser
```
  ，模拟用户与运行中应用交互
- 日志与部署 —— 拉取部署及运行时日志，确认变更已交付并在生产环境正常工作

当验证机制可靠且可自助使用时，Agent无需人工介入即可发现并修复自身的回归问题。

Preflight Check

预检检查

Confirm the agent has everything before the first iteration, rather than discovering a missing credential halfway through. Don't assume a fixed list — infer the active infrastructure from the codebase, then check each tool:

Discover the infra in use. Read the MCP config (
```
.cursor/mcp.json
```
), the
```
better-env
```
```
configSchema
```
declarations, and
```
package.json
```
scripts. Each configured service implies a CLI or token: Neon (
```
DATABASE_URL
```
), Vercel, Resend, Sentry, GitHub, Better Auth, etc.
For each tool, verify install + link + auth with a non-destructive command.
Report a checklist with a fix command for every red item.

Example checks (run only the ones the codebase uses):

bash

agent-browser -v                                      # browser automation
vercel --version && vercel whoami && vercel project ls # installed + linked + auth
neonctl me                                            # Neon CLI authenticated
sentry-cli info                                       # token present and valid
gh auth status                                        # GitHub CLI for PRs, logs
bun run env:validate                                  # env vars match the schema

Stop if anything is red:

Preflight check
  [ok]   agent-browser            v1.4.2
  [ok]   vercel                   linked to acme/app, logged in as andre
  [fail] neon                     not authenticated
  [fail] DATABASE_URL             not set in .env.local
  [ok]   gh                       authenticated

2 issues block the loop. Run these, then re-run /ralph:

  neonctl auth                      # opens browser for OAuth
  bun run env:pull                  # pull DATABASE_URL from Vercel

For interactive OAuth (Vercel, Neon, GitHub), give the user the exact command to run themselves — don't attempt a browser login on their behalf. For anything fixable non-interactively (pulling env vars, setting a token), offer to run it. Start the loop only once every item is green.

在首次迭代前确认Agent已具备所有必要条件，避免在运行中途发现缺失凭证的问题。不要假设固定的检查列表——从代码库中推断当前使用的基础设施，再逐一检查每个工具：

发现当前使用的基础设施。读取MCP配置（
```
.cursor/mcp.json
```
）、
```
better-env
```
的
```
configSchema
```
声明及
```
package.json
```
脚本。每个已配置的服务都对应一个CLI或令牌：Neon（
```
DATABASE_URL
```
）、Vercel、Resend、Sentry、GitHub、Better Auth等。
针对每个工具，验证安装、关联及身份验证状态，使用非破坏性命令。
生成检查清单，为每个异常项提供修复命令。

示例检查（仅运行代码库实际使用的项）：

bash

agent-browser -v                                      # 浏览器自动化
vercel --version && vercel whoami && vercel project ls # 已安装 + 已关联 + 已验证身份
neonctl me                                            # Neon CLI已完成身份验证
sentry-cli info                                       # 令牌存在且有效
gh auth status                                        # 用于PR、日志的GitHub CLI
bun run env:validate                                  # 环境变量匹配schema

若存在异常项则停止：

预检检查
  [ok]   agent-browser            v1.4.2
  [ok]   vercel                   已关联至acme/app，当前登录用户为andre
  [fail] neon                     未完成身份验证
  [fail] DATABASE_URL             未在.env.local中设置
  [ok]   gh                       已完成身份验证

有2个问题阻碍循环运行。执行以下命令后重新运行/ralph：

  neonctl auth                      # 打开浏览器进行OAuth验证
  bun run env:pull                  # 从Vercel拉取DATABASE_URL

对于交互式OAuth（Vercel、Neon、GitHub），需告知用户具体的执行命令——不要尝试代其完成浏览器登录。对于可非交互式修复的项（拉取环境变量、设置令牌），可主动提出代为执行。仅当所有项状态正常时方可启动循环。

Steering the Loop

循环引导

Keep the prompt wide and outcome-focused, then let the agent decompose it. Add direction by sharpening inputs, not micromanaging steps:

Sharper prompt — state the outcome and constraints, not the steps.
Stronger tests — failing tests are the most reliable signal that more work remains.
Better tools — when the agent keeps getting stuck, it usually lacks a tool (an MCP server, CLI, or log access), not instructions.

保持提示词宽泛且以结果为导向，让Agent自行拆解任务。通过优化输入而非微管理步骤来调整方向：

更精准的提示词 —— 明确结果与约束，而非具体步骤。
更严格的测试用例 —— 失败的测试用例是剩余工作最可靠的信号。
更完善的工具 —— 当Agent频繁受阻时，通常是缺少工具（MCP服务器、CLI或日志访问权限），而非指令不足。

Background & References

背景与参考资料

Ralph - Geoffrey Huntley - Original concept and implementation
Effective Harnesses for Long-Running Agents - Anthropic - Engineering patterns for agent loops
Matt Pocock on Ralph - Video walkthrough

Ralph - Geoffrey Huntley - 原始概念与实现
Effective Harnesses for Long-Running Agents - Anthropic - Agent循环的工程模式
Matt Pocock on Ralph - 视频演示