Ralph TUI - 建立 JSON 任務
將 PRD 轉換為 prd.json 格式,以供 ralph-tui 自主執行。
注意: 此技能與 ralph-tui 的 JSON 追蹤器外掛程式捆綁。未來的追蹤器外掛程式(Linear、GitHub Issues 等)將會捆綁它們自己的任務建立技能。
⚠️ 重要: 輸出必須是頂層的扁平 JSON 物件,包含 "name" 和 "userStories" 欄位。請勿將內容包裝在 "prd" 物件中,或使用 "tasks" 陣列。請參閱下方的「結構反模式」章節。
任務
接受一個 PRD(Markdown 檔案或文字),並建立一個 prd.json 檔案:
- 提取品質門檻: 來自 PRD 的「品質門檻」章節
- 解析使用者故事: 來自 PRD
- 將品質門檻附加至每個故事的驗收條件
- 設定故事之間的相依關係
- 輸出準備給
ralph-tui run --prd <路徑>使用
步驟 1:提取品質門檻
在 PRD 中尋找「品質門檻」章節:
## 品質門檻
以下命令必須為每個使用者故事通過:
- `pnpm typecheck` - 型別檢查
- `pnpm lint` - 程式碼檢查
對於 UI 故事,也需包含:
- 使用 dev-browser 技能在瀏覽器中驗證
提取:
- 通用門檻: 適用於所有故事的命令(例如
pnpm typecheck) - UI 門檻: 僅適用於 UI 故事的命令(例如瀏覽器驗證)
如果沒有「品質門檻」章節: 詢問使用者哪些命令應該通過,或使用合理的預設值,例如 npm run typecheck。
輸出格式
JSON 檔案必須是頂層的扁平物件:
{
"name": "[來自 PRD 或目錄的專案名稱]",
"branchName": "ralph/[功能名稱-串接式命名]",
"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、 session 處理
- 「重構 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:從功能名稱推導,使用串接式命名,加上
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 故事具有瀏覽器驗證(如果在品質門檻中有指定)
- 驗收條件可驗證(不模糊)
- 沒有循環相依性