ralph-loop-workflow

Ralph 循环工作流

让编码 Agent 在自主循环中运行，将宽泛的提示词拆解为任务，并逐一构建、测试和交付。

前置条件

请先完成以下设置步骤：

• AI 编码 Agent 配置
• 代码健康、Lint 与格式化
• 测试

循环

Ralph 的目标是尽可能延长 Agent 无需人工干预的运行时间。目标不是某种文件格式，而是让 Agent 能够自行规划、构建和验证。意图的持久记录保存在 Agent 生成的产物中：测试（可执行的验收标准）、面向用户的文档，以及已发布库的变更日志。

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

给 Agent 一个宽泛、聚焦结果的提示词，并让它自己的执行框架管理待办列表——无需另外编写或勾选用户故事文件。

如果没有提供提示词，请停止并询问用户：“你希望 Ralph 循环达成什么结果？请给我一个宽泛、聚焦结果的提示词，我会将其拆解为任务。”等待用户回答后再继续。

只运行一次预检。如果有任何内容缺失或未通过身份验证，请报告准确的修复命令并停止——只有全部检查通过后，循环才会启动。然后，每次迭代执行以下步骤：

1. 读取代码库的当前状态和之前的进展。
2. 运用第一性原理思维，将剩余工作拆解为任务。
3. 选择优先级最高的任务。
4. 按开发工作流实现任务：编写测试、构建、按需生成并迁移数据库架构、格式化。
5. 验证：类型检查、构建、测试，以及在 http://localhost:3000 上进行浏览器交互。
6. 调试并修复，直到验证通过。
7. 更新面向用户的文档，以及已发布产物的变更日志。
8. 使用描述性消息提交，然后继续处理下一个任务。

让开发服务器持续运行（bun run dev）。Agent 使用测试数据库，因此可以自由迁移。当没有剩余任务且所有验证均通过时，循环结束。

Agent 所需条件

无需安装任何 Ralph 专用组件——该循环依赖于以下三项准备工作：

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

当验证可靠且可自行完成时，Agent 就能在没有人工介入的情况下发现并修复自身的回归问题。

预检

在首次迭代前确认 Agent 已准备好所需的一切，避免中途才发现缺少凭据。不要假设有固定清单——应根据代码库推断当前使用的基础设施，然后逐项检查工具：

1. 发现正在使用的基础设施。 查看 MCP 配置（.cursor/mcp.json）、better-env 的 configSchema 声明，以及 package.json 脚本。每个已配置的服务都意味着需要相应的 CLI 或令牌：Neon（DATABASE_URL）、Vercel、Resend、Sentry、GitHub、Better Auth 等。
2. 使用不会造成更改的命令，逐项验证工具是否已安装、已连接并通过身份验证。
3. 报告检查清单，并为每个未通过的项目提供修复命令。

检查示例（只运行代码库实际使用的工具）：

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

如果有任何项目未通过，请停止：

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

对于交互式 OAuth（Vercel、Neon、GitHub），请提供准确的命令，让用户自行运行——不要代替用户尝试通过浏览器登录。对于可以通过非交互方式修复的问题（拉取环境变量、设置令牌），请主动提出代为处理。只有所有项目都通过后，才开始循环。

引导循环

保持提示词开放并聚焦于结果，然后让 Agent 自行拆解任务。通过改进输入来明确方向，而不是事无巨细地规定步骤：

• 更明确的提示词——说明目标和约束，而不是步骤。
• 更有力的测试——失败的测试是判断是否仍有工作要做的最可靠信号。
• 更好的工具——当 Agent 一再受阻时，通常是缺少工具（MCP 服务、CLI 或日志访问权限），而不是缺少指示。

背景与参考资料

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