ralph-yolo

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 不同。如果是：

1. 读取当前 prd.json 提取 branchName
2. 比较新功能的分支名
3. 如果不同且 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": ""
    }
  ]
}

转换规则

1. 每个用户故事成为一个 JSON 条目
2. ID：顺序编号（US-001, US-002 等）
3. Priority：基于依赖顺序（schema → backend → UI）
4. 所有故事：初始 passes: false，notes 为空
5. branchName：从功能名派生，kebab-case，前缀 ralph/
6. 始终添加："Typecheck passes" 到每个故事
7. UI 故事：添加 "Verify in browser"

故事大小关键原则

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

合适大小：

• 添加数据库列和迁移
• 向现有页面添加 UI 组件
• 更新服务器操作
• 添加过滤下拉菜单

太大（需拆分）：

• "构建整个仪表板" → 拆分为：schema, queries, UI 组件, filters
• "添加认证" → 拆分为：schema, middleware, 登录 UI, session handling