ralph

Ralph PRD 转换器

将现有 PRD 转换为 prd.json，并为自主执行设置隔离的 git worktree。

---

工作内容

1. 获取一份 PRD（Markdown 文件或文本），并将其转换为 prd.json
2. 创建一个供 Ralph 使用的 git worktree
3. 将 prd.json 保存到 worktree 中，并初始化进度跟踪

---

输出格式

{
  "project": "[Project Name]",
  "branchName": "ralph/[feature-name-kebab-case]",
  "description": "[Feature description from PRD title/intro]",
  "userStories": [
    {
      "id": "US-001",
      "title": "[Story title]",
      "description": "As a [user], I want [feature] so that [benefit]",
      "acceptanceCriteria": [
        "Criterion 1",
        "Criterion 2",
        "Typecheck passes"
      ],
      "priority": 1,
      "passes": false,
      "notes": ""
    }
  ]
}

---

故事规模：首要规则

每个故事必须能在一次 Ralph 迭代（一个上下文窗口）中完成。

Ralph 每次迭代都会启动一个全新的 Amp 实例，且不会记住之前的工作。如果故事太大，大模型会在完成前耗尽上下文，导致生成的代码不可用。

合适规模的故事：

• 添加数据库列和迁移
• 为现有页面添加 UI 组件
• 为服务器操作添加新逻辑
• 为列表添加筛选下拉菜单

规模过大（应拆分）：

• “构建整个仪表板”——拆分为：架构、查询、UI 组件、筛选器
• “添加身份验证”——拆分为：架构、中间件、登录 UI、会话处理
• “重构 API”——按端点或模式拆分，每个故事对应一项

**经验法则：**如果无法用 2–3 句话描述变更，说明规模太大。

---

故事排序：优先处理依赖项

故事按优先级顺序执行。较早的故事不能依赖较晚的故事。

正确顺序：

1. 架构／数据库变更（迁移）
2. 服务器操作／后端逻辑
3. 使用后端的 UI 组件
4. 汇总数据的仪表板／摘要视图

错误顺序：

1. UI 组件（依赖尚不存在的架构）
2. 架构变更

---

验收标准：必须可验证

每项标准都必须是 Ralph 可以检查的内容，不能含糊不清。

好的标准（可验证）：

• “向 tasks 表添加 status 列，默认值为 'pending'”
• “筛选下拉菜单包含以下选项：All、Active、Completed”
• “点击删除时显示确认对话框”
• “类型检查通过”
• “测试通过（使用 vitest-testing 技能）”
• “使用 vitest-testing 技能编写测试”

不好的标准（含糊）：

• “运行正常”
• “用户可以轻松完成 X”
• “良好的 UX”
• “处理边缘情况”

始终将以下内容作为最后一项标准：

"Typecheck passes"

对于包含可测试逻辑的故事，还要包含：

"Tests pass (use vitest-testing skill)"

对于会更改 UI 的故事，还要包含：

"Verify in browser using dev-browser skill"

前端故事必须经过视觉验证才能算完成。Ralph 会使用 dev-browser 技能打开页面、与 UI 交互，并确认变更有效。

---

转换规则

1. 每个用户故事对应一个 JSON 条目
2. ID：按顺序编号（US-001、US-002 等）
3. 优先级：先按依赖顺序，再按文档顺序
4. 所有故事：passes: false，且 notes 为空
5. branchName：根据功能名称生成 kebab-case 名称，并加上 ralph/ 前缀
6. 始终添加：“类型检查通过”作为每个故事的验收标准

---

拆分大型 PRD

如果 PRD 包含大型功能，应将其拆分：

原始内容：

“添加用户通知系统”

拆分为：

1. US-001：向数据库添加通知表
2. US-002：创建用于发送通知的通知服务
3. US-003：在页眉中添加通知铃铛图标
4. US-004：创建通知下拉面板
5. US-005：添加标记为已读的功能
6. US-006：添加通知偏好设置页面

每个故事都是一项聚焦的变更，可独立完成和验证。

---

示例

输入 PRD：

# Task Status Feature

Add ability to mark tasks with different statuses.

## Requirements
- Toggle between pending/in-progress/done on task list
- Filter list by status
- Show status badge on each task
- Persist status in database

输出 prd.json：

{
  "project": "TaskApp",
  "branchName": "ralph/task-status",
  "description": "Task Status Feature - Track task progress with status indicators",
  "userStories": [
    {
      "id": "US-001",
      "title": "Add status field to tasks table",
      "description": "As a developer, I need to store task status in the database.",
      "acceptanceCriteria": [
        "Add status column: 'pending' | 'in_progress' | 'done' (default 'pending')",
        "Generate and run migration successfully",
        "Typecheck passes",
        "Tests pass (use vitest-testing skill)"
      ],
      "priority": 1,
      "passes": false,
      "notes": ""
    },
    {
      "id": "US-002",
      "title": "Display status badge on task cards",
      "description": "As a user, I want to see task status at a glance.",
      "acceptanceCriteria": [
        "Each task card shows colored status badge",
        "Badge colors: gray=pending, blue=in_progress, green=done",
        "Typecheck passes",
        "Verify in browser using dev-browser skill"
      ],
      "priority": 2,
      "passes": false,
      "notes": ""
    },
    {
      "id": "US-003",
      "title": "Add status toggle to task list rows",
      "description": "As a user, I want to change task status directly from the list.",
      "acceptanceCriteria": [
        "Each row has status dropdown or toggle",
        "Changing status saves immediately",
        "UI updates without page refresh",
        "Typecheck passes",
        "Verify in browser using dev-browser skill"
      ],
      "priority": 3,
      "passes": false,
      "notes": ""
    },
    {
      "id": "US-004",
      "title": "Filter tasks by status",
      "description": "As a user, I want to filter the list to see only certain statuses.",
      "acceptanceCriteria": [
        "Filter dropdown: All | Pending | In Progress | Done",
        "Filter persists in URL params",
        "Typecheck passes",
        "Verify in browser using dev-browser skill"
      ],
      "priority": 4,
      "passes": false,
      "notes": ""
    }
  ]
}

---

Worktree 设置

生成 prd.json 后，创建一个隔离的 git worktree，供 Ralph 使用。

1. 创建 worktree

# From the repo root — create worktree with a new branch from main
git worktree add .claude/worktrees/ralph/<feature-name> -b ralph/<feature-name> main

其中 <feature-name> 是 kebab-case 格式的功能名称（即 branchName 中 ralph/ 后的部分）。

2. 安装依赖并拉取环境变量

cd .claude/worktrees/ralph/<feature-name>
bun install
bun run env:pull

3. 将文件保存到 worktree 中

将 prd.json 保存到 worktree 的 ralph 目录：

.claude/worktrees/ralph/<feature-name>/scripts/ralph/prd.json

在 worktree 中初始化 progress.txt：

.claude/worktrees/ralph/<feature-name>/scripts/ralph/progress.txt

内容如下：

# Ralph Progress Log
Started: <current date>
---

4. 告知用户如何运行 Ralph

# From the main repo root
scripts/ralph/ralph-tree.sh ralph/<feature-name>

# With options
scripts/ralph/ralph-tree.sh ralph/<feature-name> --tool claude 15

---

保存前的检查清单

编写 prd.json 前，请确认：

• 每个故事都能在一次迭代内完成（规模足够小）
• 故事按依赖关系排序（从架构到后端，再到 UI）
• 每个故事都将“类型检查通过”作为验收标准
• UI 故事将“使用 dev-browser skill 在浏览器中验证”作为验收标准
• 验收标准可验证（不含模糊表述）
• 没有故事依赖后续故事
• 已在 .claude/worktrees/ralph/<feature-name>/ 创建工作树
• 已在工作树中运行 bun install 和 bun run env:pull
• 已将 prd.json 保存到工作树的 scripts/ralph/ 中
• 已在工作树中初始化 progress.txt