Ralph TUI - 建立 Beads
將 PRD 轉換為 beads(史詩 + 子任務),以供 ralph-tui 自主執行。
注意: 此技能隨 ralph-tui 的 Beads 追蹤插件一同提供。未來的追蹤插件(Linear、GitHub Issues 等)將會附帶各自的任務建立技能。
工作內容
接收一份 PRD(Markdown 檔案或文字),並在 .beads/beads.jsonl 中建立 beads:
- 提取品質關卡:從 PRD 的「品質關卡」章節中提取
- 為該功能建立一個史詩(epic)bead
- 為每個使用者故事建立子 bead(並附加品質關卡)
- 設定 beads 之間的依賴關係(schema → 後端 → UI)
- 產生可供
ralph-tui run --tracker beads使用的輸出
第一步:提取品質關卡
在 PRD 中尋找「品質關卡」章節:
## 品質關卡
每個使用者故事都必須通過以下指令:
- `pnpm typecheck` - 型別檢查
- `pnpm lint` - 程式碼檢查
對於 UI 故事,也需包含:
- 使用 dev-browser 技能在瀏覽器中驗證
提取:
- 通用關卡: 適用於所有故事的指令(例如
pnpm typecheck) - UI 關卡: 僅適用於 UI 故事的指令(例如瀏覽器驗證)
如果沒有「品質關卡」章節: 詢問使用者應該通過哪些指令,或使用合理的預設值,例如 npm run typecheck。
輸出格式
Beads 使用 bd create 指令搭配 HEREDOC 語法,以安全處理特殊字元:
# 建立史詩(連結回原始 PRD)
bd create --type=epic \
--title="[功能名稱]" \
--description="$(cat <<'EOF'
[來自 PRD 的功能描述]
EOF
)" \
--external-ref="prd:./tasks/feature-name-prd.md"
# 建立子 bead(將品質關卡包含在驗收條件中)
bd create \
--parent=EPIC_ID \
--title="[故事標題]" \
--description="$(cat <<'EOF'
[包含驗收條件及品質關卡的故事描述]
EOF
)" \
--priority=[1-4]
重要: 務必使用
<<'EOF'(單引號)作為 HEREDOC 分隔符號。這可以避免 Shell 解譯描述中的反引號、$變數和()。
故事規模:第一原則
每個故事必須能在一次 ralph-tui 迭代中完成(約一個代理程式上下文視窗)。
ralph-tui 每次迭代都會產生一個全新的代理程式實例,不會記憶先前的工作。如果故事太大,代理程式會在完成前耗盡上下文。
規模適當的故事:
- 新增資料庫欄位 + 遷移
- 在現有頁面新增 UI 元件
- 更新伺服器動作並加入新邏輯
- 在清單中新增篩選下拉選單
太大的故事(請拆分):
- 「建立整個儀表板」→ 拆分成:schema、查詢、UI 元件、篩選器
- 「新增身分驗證」→ 拆分成:schema、中介軟體、登入 UI、工作階段處理
- 「重構 API」→ 依端點或模式拆分成一個故事
經驗法則: 如果你無法用 2-3 句話描述變更內容,那就表示故事太大了。
故事順序:先處理依賴關係
故事會按照依賴關係順序執行。較早的故事不能依賴較晚的故事。
正確順序:
- Schema/資料庫變更(遷移)
- 伺服器動作 / 後端邏輯
- 使用後端的 UI 元件
- 匯聚資料的儀表板/摘要畫面
錯誤順序:
- ❌ UI 元件(依賴於尚未存在的 schema)
- ❌ Schema 變更
使用 bd dep add 設定依賴關係
使用 bd dep add 指令來指定哪些 beads 必須先完成:
# 先建立 beads
bd create --parent=epic-123 --title="US-001: 新增 schema" ...
bd create --parent=epic-123 --title="US-002: 建立 API" ...
bd create --parent=epic-123 --title="US-003: 建立 UI" ...
# 然後新增依賴關係(issue depends-on blocker)
bd dep add ralph-tui-002 ralph-tui-001 # US-002 依賴 US-001
bd dep add ralph-tui-003 ralph-tui-002 # US-003 依賴 US-002
語法: bd dep add <issue> <depends-on> — issue 依賴於(被 depends-on 阻擋)。
ralph-tui 會:
- 在依賴關係完成前,將被封鎖的 beads 顯示為「blocked」
- 絕不會在依賴項仍處於開啟狀態時選取 bead 來執行
- 在處理 bead 時,於提示中包含依賴關係的上下文
正確的依賴關係順序:
- Schema/資料庫變更(無依賴關係)
- 後端邏輯(依賴 schema)
- UI 元件(依賴後端)
- 整合/打磨(依賴 UI)
驗收條件:品質關卡 + 故事專屬條件
每個 bead 的描述應包含驗收條件,其中需有:
- 故事專屬條件:來自 PRD(此故事要完成的事項)
- 品質關卡:來自 PRD 的品質關卡章節(附加在結尾)
良好的條件(可驗證):
- 「將
investorType欄位新增至 investor 資料表,預設值為 'cold'」 - 「篩選下拉選單包含選項:全部、Cold、Friend」
- 「點擊切換開關會顯示確認對話框」
不良條件(模糊):
- ❌ 「運作正常」
- ❌ 「使用者可以輕鬆進行 X」
- ❌ 「良好的使用者體驗」
- ❌ 「處理邊緣情況」
轉換規則
- 先從 PRD 中提取品質關卡
- 每個使用者故事 → 一個 bead
- 第一個故事:無依賴關係(建立基礎)
- 後續的故事:依賴於前一個故事(UI 依賴後端,以此類推)
- 優先級:根據依賴關係順序,然後是文件中的順序(0=關鍵,2=中等,4=待辦)
- 所有故事:
status: "open" - 驗收條件:故事條件 + 附加的品質關卡
- UI 故事:也需附加 UI 專屬關卡(瀏覽器驗證)
拆分大型 PRD
如果 PRD 中有大型功能,請拆分它們:
原始內容:
「新增朋友 outreach 追蹤,並包含不同的訊息功能」
拆分後:
- US-001:在資料庫中新增 investorType 欄位
- US-002:在投資者清單 UI 中新增類型切換功能
- US-003:建立朋友專屬的階段進展邏輯
- US-004:建立朋友訊息範本
- US-005:為朋友配置任務生成功能
- US-006:新增依類型篩選功能
- US-007:更新新增投資者表單
- US-008:更新儀表板計數
每個都是一個專注的變更,可以獨立完成和驗證。
範例
輸入 PRD:
# PRD:朋友 Outreach
新增將投資者標記為「朋友」以進行溫暖 outreach 的功能。
## 品質關卡
每個使用者故事都必須通過以下指令:
- `pnpm typecheck` - 型別檢查
- `pnpm lint` - 程式碼檢查
對於 UI 故事,也需包含:
- 使用 dev-browser 技能在瀏覽器中驗證
## 使用者故事
### US-001:在 investor 資料表中新增 investorType 欄位
**描述:** 身為開發者,我需要將投資者分類為 'cold' 或 'friend'。
**驗收條件:**
- [ ] 新增 investorType 欄位:'cold' | 'friend'(預設 'cold')
- [ ] 產生並成功執行遷移
### US-002:在投資者清單列中新增類型切換功能
**描述:** 身為 Ryan,我想要直接從清單中切換投資者類型。
**驗收條件:**
- [ ] 每一列都有 Cold | Friend 切換開關
- [ ] 切換時顯示確認對話框
- [ ] 確認後:更新資料庫中的類型
### US-003:依類型篩選投資者
**描述:** 身為 Ryan,我想要篩選清單,只查看朋友或冷門投資者。
**驗收條件:**
- [ ] 篩選下拉選單:全部 | Cold | Friend
- [ ] 篩選條件保留在 URL 參數中
輸出 beads:
# 建立史詩(連結回原始 PRD)
bd create --type=epic \
--title="朋友 Outreach 追蹤" \
--description="$(cat <<'EOF'
用於 Deck 回饋的溫暖 outreach
EOF
)" \
--external-ref="prd:./tasks/friends-outreach-prd.md"
# US-001:無依賴關係(第一個,建立 schema)
bd create --parent=ralph-tui-abc \
--title="US-001:在 investor 資料表中新增 investorType 欄位" \
--description="$(cat <<'EOF'
身為開發者,我需要將投資者分類為 'cold' 或 'friend'。
## 驗收條件
- [ ] 新增 investorType 欄位:'cold' | 'friend'(預設 'cold')
- [ ] 產生並成功執行遷移
- [ ] pnpm typecheck 通過
- [ ] pnpm lint 通過
EOF
)" \
--priority=1
# US-002:UI 故事(也需要瀏覽器驗證)
bd create --parent=ralph-tui-abc \
--title="US-002:在投資者清單列中新增類型切換功能" \
--description="$(cat <<'EOF'
身為 Ryan,我想要直接從清單中切換投資者類型。
## 驗收條件
- [ ] 每一列都有 Cold | Friend 切換開關
- [ ] 切換時顯示確認對話框
- [ ] 確認後:更新資料庫中的類型
- [ ] pnpm typecheck 通過
- [ ] pnpm lint 通過
- [ ] 使用 dev-browser 技能在瀏覽器中驗證
EOF
)" \
--priority=2
# 新增依賴關係:US-002 依賴 US-001
bd dep add ralph-tui-002 ralph-tui-001
# US-003:UI 故事
bd create --parent=ralph-tui-abc \
--title="US-003:依類型篩選投資者" \
--description="$(cat <<'EOF'
身為 Ryan,我想要篩選清單,只查看朋友或冷門投資者。
## 驗收條件
- [ ] 篩選下拉選單:全部 | Cold | Friend
- [ ] 篩選條件保留在 URL 參數中
- [ ] pnpm typecheck 通過
- [ ] pnpm lint 通過
- [ ] 使用 dev-browser 技能在瀏覽器中驗證
EOF
)" \
--priority=3
# 新增依賴關係:US-003 依賴 US-002
bd dep add ralph-tui-003 ralph-tui-002
輸出位置
Beads 會被寫入:.beads/beads.jsonl
建立完成後,執行 ralph-tui:
# 處理特定史詩
ralph-tui run --tracker beads --epic ralph-tui-abc
# 或讓它自動選取最佳任務
ralph-tui run --tracker beads
ralph-tui 會:
- 處理指定史詩內的 beads(或選取最佳可用任務)
- 完成時關閉每個 bead
- 所有子任務完成後關閉史詩
- 史詩完成時輸出
<promise>COMPLETE</promise>
建立 Beads 前的檢查清單
- 已從 PRD 提取品質關卡(若遺漏則已詢問使用者)
- 每個故事都能在一次迭代中完成(夠小)
- 故事已按依賴關係排序(schema → 後端 → UI)
- 每個 bead 的驗收條件都已附加品質關卡
- UI 故事已包含瀏覽器驗證(若品質關卡中有指定)
- 驗收條件是可驗證的(不模糊)
- 沒有故事依賴於較晚的故事(僅依賴較早的故事)
- 建立 beads 後已使用
bd dep add新增依賴關係