Ralph YOLO - Autonomous Agent Loop (No Amp Required)

Ralph YOLO 是 Ralph 的轻量版本，直接使用 Claude Code 的 Task tool 管理子 agent 完成任务，无需依赖 Amp CLI。

与原 Ralph 的区别

特性 原 Ralph Ralph YOLO

依赖 Amp CLI Claude Code Task Tool

执行方式 bash 脚本循环 前台子 agent 管理

Agent 实例 外部 Amp 进程 Claude Code Task 子 agent

状态跟踪 文件读写 前台实时更新

上下文 每次全新 主会话保持完整上下文

使用方法

/ralph-yolo [path-to-prd.md]

如果未提供 PRD 路径，会查找项目根目录的 prd.json 并直接执行。

示例：

/ralph-yolo tasks/prd-my-feature.md # 从 PRD 转换并执行 /ralph-yolo prd.json # 使用现有 prd.json 执行 /ralph-yolo # 自动查找 prd.json

工作流程

Phase 1: PRD 转换（如果提供了 markdown PRD）

Step 1: 读取 PRD 文件

读取用户提供的 markdown PRD 文件。

Step 2: 归档旧运行（如需要）

检查是否存在 prd.json 且 branchName 不同。如果是：

• 读取当前 prd.json 提取 branchName

• 比较新功能的分支名

• 如果不同且 prd-progress.txt 有内容：

• 创建归档文件夹：.claude/archive/YYYY-MM-DD-[feature-name]/

• 复制当前 prd.json 和 prd-progress.txt 到归档

• 重置 prd-progress.txt 为新的头部信息

Step 3: 转换为 prd.json

解析 PRD 并生成项目根目录的 prd.json ：

{ "project": "[从 PRD 提取或自动检测的项目名]", "branchName": "ralph/[feature-name-kebab-case]", "description": "[从 PRD 提取的功能描述]", "userStories": [ { "id": "US-001", "title": "[故事标题]", "description": "As a [用户], I want [功能] so that [收益]", "acceptanceCriteria": [ "标准 1", "标准 2", "Typecheck passes" ], "priority": 1, "passes": false, "notes": "" } ] }

转换规则

• 每个用户故事成为一个 JSON 条目

• ID：顺序编号（US-001, US-002 等）

• Priority：基于依赖顺序（schema → backend → UI）

• 所有故事：初始 passes: false ，notes 为空

• branchName：从功能名派生，kebab-case，前缀 ralph/

• 始终添加："Typecheck passes" 到每个故事

• UI 故事：添加 "Verify in browser"

故事大小关键原则

每个故事必须在一个上下文窗口内完成。

合适大小：

• 添加数据库列和迁移

• 向现有页面添加 UI 组件

• 更新服务器操作

• 添加过滤下拉菜单

太大（需拆分）：

• "构建整个仪表板" → 拆分为：schema, queries, UI 组件, filters

• "添加认证" → 拆分为：schema, middleware, 登录 UI, session handling

经验法则： 如果不能用 2-3 句话描述变更，就太大了。

故事排序

故事按 priority 顺序执行。前面的故事不能依赖后面的。

正确顺序：

• Schema/数据库变更（migrations）

• Server actions / 后端逻辑

• 使用后端的 UI 组件

• 汇总数据的 Dashboard/summary 视图

Phase 2: Ralph YOLO 执行

Step 1: 预检

验证以下条件：

Git 工作区干净

git status --porcelain

如果不干净，要求用户提交或暂存更改

prd.json 存在且有效

cat prd.json | jq .

如果无效，显示错误并退出

Step 2: 创建或检出功能分支

读取 prd.json 中的 branchName ：

jq -r '.branchName' prd.json

如果分支不存在，从 main 创建：

git checkout -b $(jq -r '.branchName' prd.json)

如果分支存在，检出它：

git checkout $(jq -r '.branchName' prd.json)

Step 3: 初始化进度文件

如果 prd-progress.txt 不存在，创建它：

echo "# Ralph YOLO Progress Log" > prd-progress.txt echo "Started: $(date)" >> prd-progress.txt echo "---" >> prd-progress.txt

Step 4: 顺序执行用户故事

这是 Ralph YOLO 的核心工作流程：

// 伪代码示意 while (有未完成的用户故事) {

1. 读取 prd.json
2. 找到最高 priority 且 passes=false 的故事
3. 如果没有未完成故事，退出循环
4. 创建子 agent 处理该故事
5. 等待子 agent 完成
6. 验证完成情况
7. 更新 prd.json (passes=true)
8. 追加进度到 prd-progress.txt
9. 继续下一个故事 }

Step 4 详细流程

4.1 选择下一个故事

读取 prd.json ，找到：

• passes: false

• 最低 priority 值（最高优先级）

• 按 priority 升序排序

4.2 创建子 agent

根据故事类型选择合适的子 agent：

前端故事（涉及 UI）：

使用 Task tool 创建 ui-ux-designer 子 agent（如需要设计） 然后创建 Full-stack-developer 子 agent 实施开发

后端/全栈故事：

使用 Task tool 创建 Full-stack-developer 子 agent

复杂多步骤任务：

使用 Task tool 创建 general-purpose 子 agent

子 Agent 提示词模板：

你是一个独立的开发 agent，正在完成一个用户故事。

用户故事

ID: {story.id} 标题: {story.title} 描述: {story.description}

验收标准

{逐条列出 acceptanceCriteria}

上下文信息

• 项目: {prd.project}
• 功能分支: {prd.branchName}
• 功能描述: {prd.description}

你需要做的事情

1. 阅读并理解该用户故事
2. 阅读项目的现有代码，了解代码结构
3. 实现该用户故事
4. 运行质量检查（typecheck, lint, test 等）
5. 如果检查通过，提交代码：
   • 提交信息格式: feat: {story.id} - {story.title}
   • 使用 Co-Authored-By: Claude <noreply@anthropic.com>
6. 如果检查失败，修复问题直到通过
7. 确保所有验收标准都满足

重要约束

• 只工作于这一个用户故事
• 不要修改其他无关代码
• 遵循项目现有的代码模式和约定
• 提交前确保所有检查通过

完成后，请明确报告：

• 实现了什么
• 修改了哪些文件
• 是否成功提交
• 遇到的任何问题或学习点

4.3 等待子 agent 完成

使用 Task tool 的 阻塞模式（默认），等待子 agent 完全完成后再继续。

不要使用 run_in_background 参数，确保顺序执行。

4.4 验证完成情况

子 agent 完成后，验证：

检查 Git 状态

git log --oneline -1

应该看到新的提交，提交信息匹配故事 ID 和标题

检查工作区

git status --porcelain

应该是干净的（所有更改已提交）

运行质量检查

根据项目配置运行

npm run typecheck # 或等效命令 npm run lint # 或等效命令 npm test # 或等效命令

4.5 更新 prd.json

如果验证成功：

• 读取当前 prd.json

• 将该故事的 passes 设置为 true

• 保持其他字段不变

• 写回 prd.json

4.6 追加进度日志

追加到 prd-progress.txt ：

[Date/Time] - [Story ID]

• Story: [Story Title]
• Agent: [子 agent 类型]
• What was implemented: [实现内容]
• Files changed: [变更文件列表]
• Learnings:
  • [发现的模式]
  • [遇到的问题]
  • [有用的上下文]

4.7 继续下一个故事

返回到 Step 4.1，选择下一个未完成的故事。

Step 5: 完成检测

当所有用户故事的 passes 都为 true 时：

输出完成信号：

<promise>COMPLETE</promise>

显示完成摘要：

═══════════════════════════════════════════════════════ Ralph YOLO 完成所有任务！ ═══════════════════════════════════════════════════════ 总计完成: X 个用户故事 进度文件: prd-progress.txt Git 提交: git log --oneline

退出循环

子 Agent 管理

Agent 类型选择

任务类型 Agent 类型 说明

UI 设计需求 ui-ux-designer

设计界面和用户体验

一般开发 Full-stack-developer

日常全栈开发任务

复杂任务 general-purpose

多步骤复杂任务

创建子 Agent

使用 Claude Code 的 Task tool：

Task({ subagent_type: "Full-stack-developer", description: "实现 US-001 用户故事", prompt: [详细的任务指令] })

等待完成

不使用 run_in_background ，确保同步执行：

// 正确 ✓ Task({ subagent_type: "...", prompt: "..." })

// 错误 ✗（会异步执行） Task({ subagent_type: "...", prompt: "...", run_in_background: true })

进度监控

在执行过程中，定期向用户报告进度：

每个 Agent 完成后

✓ 完成 US-001: Add priority field to database

• Agent: Full-stack-developer
• 提交: abc1234
• 文件: src/db/schema.sql, migrations/001_add_priority.sql

进度: 1/4 (25%) 剩余故事:

• US-002: Display priority indicator (priority: 2)
• US-003: Add priority selector (priority: 3)
• US-004: Filter by priority (priority: 4)

正在启动下一个 agent...

每 N 个故事后

每完成 2-3 个故事，显示详细摘要：

──────────────────────────────────────────────────────────── Ralph YOLO 进度报告 ──────────────────────────────────────────────────────────── 已完成: 3/10 (30%) 当前分支: ralph/task-priority 最近提交:

• abc1234 feat: US-001 - Add priority field
• def5678 feat: US-002 - Display priority indicator
• ghi9012 feat: US-003 - Add priority selector

下一步: US-004 - Filter by priority ────────────────────────────────────────────────────────────

错误处理

子 Agent 失败

如果子 agent 报告失败或无法完成任务：

记录失败信息

• 将错误信息添加到故事的 notes 字段

• 在 prd-progress.txt 中记录详细错误

询问用户

❌ 子 agent 无法完成 US-001

错误信息: [具体错误] 建议: [如何修复]

选项: A. 跳过此故事，继续下一个 B. 手动修复后重试此故事 C. 暂停执行，让用户介入

请选择 (A/B/C):

根据用户选择处理

• A: 标记 notes ，继续下一个故事

• B: 暂停，等待用户手动修复后再继续

• C: 完全停止，保存当前状态

质量检查失败

如果子 agent 完成但质量检查失败：

不更新 prd.json

• passes 保持 false

• 添加失败原因到 notes

创建新的 agent 重试

⚠️ US-001 质量检查失败

失败的检查:

• typecheck: 找到 3 个类型错误

正在创建新的 agent 尝试修复...

最多重试 2 次

• 如果 2 次重试后仍失败，询问用户是否跳过

关键文件

文件 用途

prd.json

用户故事及其 passes 状态（任务清单）

prd-progress.txt

追踪学习进度的追加日志

.claude/archive/

旧运行的存档

提示

• 保持故事小 - 每个必须在一个上下文窗口内完成

• 按依赖排序 - schema 在前，然后是后端，然后是 UI

• 可验证的标准 - "Typecheck passes" 而不是 "工作正常"

• 干净的 git 状态 - 从干净的工作区开始

• 监控进度 - 定期检查 prd-progress.txt 和 git log

示例会话

User: /ralph-yolo tasks/prd-task-priority.md

Ralph YOLO: ✓ 正在转换 PRD 到 prd.json... ✓ 已创建包含 4 个用户故事的 prd.json ✓ 检查前置条件... ✓ Git 工作区干净 ✓ 创建分支 ralph/task-priority...

══════════════════════════════════════════════════════ Ralph YOLO - 自主 Agent 循环 ══════════════════════════════════════════════════════ 找到 4 个用户故事 开始执行...

──────────────────────────────────────────────────────────── [Agent 1/4] Full-stack-developer 任务: US-001 - Add priority field to database ────────────────────────────────────────────────────────────

[子 agent 执行中...]

✓ 完成 US-001: Add priority field to database

• Agent: Full-stack-developer
• 提交: abc1234
• 文件: src/db/schema.sql, migrations/001_add_priority.sql

进度: 1/4 (25%) 正在启动下一个 agent...

──────────────────────────────────────────────────────────── [Agent 2/4] Full-stack-developer 任务: US-002 - Display priority indicator on task cards ────────────────────────────────────────────────────────────

[继续执行...]

进度报告 ──────────────────────────────────────────────────────────── 已完成: 3/4 (75%) 当前分支: ralph/task-priority

✓ 完成 US-001 - Add priority field to database ✓ 完成 US-002 - Display priority indicator on task cards ✓ 完成 US-003 - Add priority selector to task edit

下一步: US-004 - Filter tasks by priority

────────────────────────────────────────────────────────────

[最后的故事执行...]

══════════════════════════════════════════════════════ Ralph YOLO 完成所有任务！ ══════════════════════════════════════════════════════ 总计完成: 4 个用户故事 分支: ralph/task-priority

查看详情: cat prd-progress.txt git log --oneline

<promise>COMPLETE</promise>

故障排除

执行中断

如果 Ralph YOLO 被中断（Ctrl+C 或错误）：

查看当前状态

cat prd.json | jq '.userStories[] | select(.passes == false) | {id, title, priority}'

查看进度日志

cat prd-progress.txt | tail -20

重新运行 Ralph YOLO（会继续未完成的故事）

/ralph-yolo

故事失败

如果某个故事反复失败：

• 检查 prd.json 中该故事的 notes 字段

• 检查 prd-progress.txt 了解错误详情

• 可能需要：

• 手动修复代码

• 调整故事范围（拆分得更小）

• 更新依赖项

Git 冲突

如果在创建分支时遇到冲突：

查看当前分支

git branch

如果分支已存在，可以选择：

1. 继续使用现有分支

git checkout ralph/feature-name

2. 删除并重新创建（谨慎！）

git branch -D ralph/feature-name git checkout -b ralph/feature-name

准备好运行 Ralph YOLO 了喵～ 提供 PRD 路径进行转换，或者浮浮酱会使用现有的 prd.json φ(≧ω≦*)♪