ralph-yolo

Ralph YOLO - 自主 Agent 循环（无 Amp 依赖）

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

---

使用方法

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

示例：

/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 文件路径。如果没有，查找项目根目录的 prd.json。

用户输入格式：

• /ralph-yolo tasks/prd-my-feature.md - 转换 PRD 并运行 Ralph YOLO
• /ralph-yolo prd.json - 使用现有 prd.json 运行
• /ralph-yolo - 运行（查找 prd.json）

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

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

故事排序

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

正确顺序：

1. Schema/数据库变更（migrations）
2. Server actions / 后端逻辑
3. 使用后端的 UI 组件
4. 汇总数据的 Dashboard/summary 视图