Ralph TUI - 创建 JSON 任务
将 PRD 转换为 prd.json 格式,供 ralph-tui 自主执行。
注意: 此技能已与 ralph-tui 的 JSON 追踪器插件捆绑。未来的追踪器插件(Linear、GitHub Issues 等)将捆绑它们自己的任务创建技能。
⚠️ 关键: 输出必须是一个扁平的 JSON 对象,并在根层级包含 "name" 和 "userStories"。不要将内容包裹在 "prd" 对象或使用 "tasks" 数组中。(参见下文“模式反模式”部分。)
任务描述
接收一个 PRD(markdown 文件或文本),并创建 prd.json 文件:
- 提取质量门(Quality Gates):来自 PRD 的“质量门”部分
- 解析用户故事:来自 PRD
- 将质量门附加到每个故事的验收标准中
- 设置故事之间的依赖关系
- 输出结果,准备用于
ralph-tui run --prd <path>命令
第 1 步:提取质量门
查找 PRD 中的“质量门”(Quality Gates)部分:
## 质量门
这些命令必须为每个用户故事通过:
- `pnpm typecheck` - 类型检查
- `pnpm lint` - 代码检查
对于 UI 故事,还包括:
- 使用 dev-browser 技能在浏览器中验证
提取:
- 通用门: 适用于所有故事的命令(例如
pnpm typecheck) - UI 门: 仅适用于 UI 故事的命令(例如浏览器验证)
如果不存在质量门部分: 询问用户哪些命令应该通过,或者使用合理的默认值(例如 npm run typecheck)。
输出格式
JSON 文件必须在根层级是扁平对象:
{
"name": "[来自 PRD 或目录的项目名称]",
"branchName": "ralph/[功能名称-kebab-case]",
"description": "[来自 PRD 的功能描述]",
"userStories": [
{
"id": "US-001",
"title": "[故事标题]",
"description": "作为[用户],我想要[功能],以便[收益]",
"acceptanceCriteria": [
"来自 PRD 的标准 1",
"来自 PRD 的标准 2",
"pnpm typecheck 通过",
"pnpm lint 通过"
],
"priority": 1,
"passes": false,
"notes": "",
"dependsOn": []
},
{
"id": "US-002",
"title": "[依赖 US-001 的 UI 故事]",
"description": "...",
"acceptanceCriteria": [
"...",
"pnpm typecheck 通过",
"pnpm lint 通过",
"使用 dev-browser 技能在浏览器中验证"
],
"priority": 2,
"passes": false,
"notes": "",
"dependsOn": ["US-001"]
}
]
}
关键:模式反模式(请勿使用)
以下模式无效,将导致验证错误:
❌ 错误:包装对象
{
"prd": {
"name": "...",
"userStories": [...]
}
}
这会将所有内容包装在 "prd" 对象中。不要这样做。 "name" 和 "userStories" 字段必须在根层级。
❌ 错误:使用 "tasks" 替代 "userStories"
{
"name": "...",
"tasks": [...]
}
该数组应命名为 "userStories",而不是 "tasks"。
❌ 错误:复杂的嵌套结构
{
"metadata": {...},
"overview": {...},
"migration_strategy": {
"phases": [...]
}
}
即使 PRD 描述了阶段/里程碑/冲刺,你也必须将这些扁平化为一个单一的 "userStories" 数组。
❌ 错误:使用 "status" 替代 "passes"
{
"userStories": [{
"id": "US-001",
"status": "open" // 错误!
}]
}
对未完成的故事使用 "passes": false,已完成的使用 "passes": true。
✅ 正确:根层级的扁平结构
{
"name": "Android Kotlin 迁移",
"branchName": "ralph/kotlin-migration",
"userStories": [
{"id": "US-001", "title": "创建 Scraper 接口", "passes": false, "dependsOn": []},
{"id": "US-002", "title": "实现 WeebCentralScraper", "passes": false, "dependsOn": ["US-001"]}
]
}
故事大小:第一条规则
每个故事必须能在一次 ralph-tui 迭代中完成(大约一个代理上下文窗口)。
Ralph-tui 每次迭代都会生成一个全新的代理实例,且对之前的工作没有记忆。如果故事太大,代理在完成前就会耗尽上下文。
大小合适的故事:
- 添加数据库列 + 迁移
- 向现有页面添加 UI 组件
- 用新逻辑更新服务器操作
- 向列表添加筛选下拉框
太大(需要拆分):
- "构建整个仪表板" → 拆分为:模式、查询、UI 组件、过滤器
- "添加认证" → 拆分为:模式、中间件、登录 UI、会话处理
- "重构 API" → 拆分为每个端点或模式一个故事
经验法则: 如果你不能用 2-3 句话描述这个变更,那它就太大了。
使用 dependsOn 管理依赖关系
使用 dependsOn 数组指定哪些故事必须首先完成:
{
"id": "US-002",
"title": "创建 API 端点",
"dependsOn": ["US-001"], // 直到 US-001 通过才会被选中
...
}
Ralph-tui 将会:
- 在 US-001 完成前,将 US-002 显示为“已阻塞”
- 当 US-001 仍处于开放状态时,绝不会选择 US-002 进行执行
- 在处理 US-002 时,在提示中包含“先决条件:US-001”
正确的依赖顺序:
- 模式/数据库变更(无依赖)
- 后端逻辑(依赖模式)
- UI 组件(依赖后端)
- 集成/打磨(依赖 UI)
验收标准:质量门 + 故事特定标准
每个故事的验收标准应包括:
- 来自 PRD 的故事特定标准(该故事完成的内容)
- 来自 PRD 质量门部分的质量门(附加在末尾)
好的标准(可验证):
- "向 tasks 表添加
status列,默认值为 'open'" - "筛选下拉框包含选项:全部、打开、已关闭"
- "点击删除显示确认对话框"
坏的标准(模糊):
- ❌ "正常工作"
- ❌ "用户可以轻松地做 X"
- ❌ "良好的用户体验"
- ❌ "处理边缘情况"
转换规则
- 首先提取质量门:来自 PRD
- 每个用户故事 → 一个 JSON 条目
- ID:顺序编号(US-001, US-002 等)
- 优先级:基于依赖顺序(1 = 最高)
- dependsOn:此故事所需的故事 ID 数组
- 所有故事:
passes: false和空的notes - branchName:从功能名称派生,kebab-case,以
ralph/为前缀 - 验收标准:故事标准 + 附加的质量门
- UI 故事:同时附加 UI 特定的门(浏览器验证)
输出位置
默认位置:./tasks/prd.json(与 PRD markdown 文件同一目录)
这将所有 PRD 相关文件保存在 tasks/ 目录中。
或者指定不同的路径——ralph-tui 将使用它:
ralph-tui run --prd ./path/to/prd.json
示例
输入 PRD:
# PRD:任务优先级系统
为任务添加优先级级别。
## 质量门
以下命令必须为每个用户故事通过:
- `pnpm typecheck` - 类型检查
- `pnpm lint` - 代码检查
对于 UI 故事,还包括:
- 使用 dev-browser 技能在浏览器中验证
## 用户故事
### US-001:向数据库添加优先级字段
**描述:** 作为开发者,我需要存储任务优先级。
**验收标准:**
- [ ] 添加优先级列:1-4(默认 2)
- [ ] 迁移运行成功
### US-002:在任务卡片上显示优先级徽章
**描述:** 作为用户,我希望一眼就能看到任务优先级。
**验收标准:**
- [ ] 徽章显示 P1/P2/P3/P4,带有颜色
- [ ] 无需悬停即可看到徽章
### US-003:添加优先级筛选下拉框
**描述:** 作为用户,我想按优先级筛选任务。
**验收标准:**
- [ ] 筛选下拉框:全部、P1、P2、P3、P4
- [ ] 筛选条件保存在 URL 中
输出 prd.json:
{
"project": "my-app",
"branchName": "ralph/task-priority",
"description": "为任务添加优先级级别",
"userStories": [
{
"id": "US-001",
"title": "向数据库添加优先级字段",
"description": "作为开发者,我需要存储任务优先级。",
"acceptanceCriteria": [
"添加优先级列:1-4(默认 2)",
"迁移运行成功",
"pnpm typecheck 通过",
"pnpm lint 通过"
],
"priority": 1,
"passes": false,
"notes": "",
"dependsOn": []
},
{
"id": "US-002",
"title": "在任务卡片上显示优先级徽章",
"description": "作为用户,我希望一眼就能看到任务优先级。",
"acceptanceCriteria": [
"徽章显示 P1/P2/P3/P4,带有颜色",
"无需悬停即可看到徽章",
"pnpm typecheck 通过",
"pnpm lint 通过",
"使用 dev-browser 技能在浏览器中验证"
],
"priority": 2,
"passes": false,
"notes": "",
"dependsOn": ["US-001"]
},
{
"id": "US-003",
"title": "添加优先级筛选下拉框",
"description": "作为用户,我想按优先级筛选任务。",
"acceptanceCriteria": [
"筛选下拉框:全部、P1、P2、P3、P4",
"筛选条件保存在 URL 中",
"pnpm typecheck 通过",
"pnpm lint 通过",
"使用 dev-browser 技能在浏览器中验证"
],
"priority": 3,
"passes": false,
"notes": "",
"dependsOn": ["US-002"]
}
]
}
使用 ralph-tui 运行
创建 prd.json 后:
ralph-tui run --prd ./tasks/prd.json
Ralph-tui 将会:
- 从 prd.json 加载故事
- 选择优先级最高且
passes: false且没有阻塞依赖的故事 - 生成包含故事详情 + 验收标准的提示
- 运行代理来实现该故事
- 完成时标记
passes: true - 重复直到所有故事全部通过
保存前检查清单
- 已从 PRD 提取质量门(如果缺失则询问用户)
- 每个故事可在一次迭代中完成
- 故事按依赖顺序排列(模式 → 后端 → UI)
- 每个故事的
dependsOn设置正确 - 质量门已附加到每个故事的验收标准
- UI 故事包含浏览器验证(如果质量门中指定)
- 验收标准是可验证的(不模糊)
- 没有循环依赖