Ralph TUI - 建立 Beads (beads-rust) 是做什麼的?
將 PRD 轉換為 beads(epic + 子任務),供 beads-rust(br CLI)在 ralph-tui 中自主執行。
注意: 此技能使用 beads-rust 的
br指令。如果你安裝的是原始 beads(bd),請改用ralph-tui-create-beads技能。
任務
取得 PRD(Markdown 檔案或文字),並使用 br 指令建立 beads:
- 從 PRD 的「品質閘門」章節提取品質閘門
- 為該功能建立一個 epic bead
- 為每個使用者故事建立 子 beads(並附加品質閘門)
- 設定 beads 之間的 依賴關係(schema → 後端 → UI)
- 輸出供
ralph-tui run --tracker beads-rust使用
第一步:提取品質閘門
在 PRD 中尋找「品質閘門」章節:
## 品質閘門
每個使用者故事都必須通過以下指令:
- `pnpm typecheck` - 型別檢查
- `pnpm lint` - 程式碼風格檢查
對於 UI 故事,也需包含:
- 使用 dev-browser 技能在瀏覽器中驗證
提取:
- 通用閘門: 適用於所有故事的指令(例如
pnpm typecheck) - UI 閘門: 僅適用於 UI 故事的指令(例如瀏覽器驗證)
如果沒有品質閘門章節: 詢問使用者應該通過哪些指令,或使用合理的預設值,例如 npm run typecheck。
輸出格式
Beads 使用 br create 指令搭配 HEREDOC 語法,以安全處理特殊字元:
# 建立 epic(連結回原始 PRD)
br create --type=epic \
--title="[功能名稱]" \
--description="$(cat <<'EOF'
[來自 PRD 的功能描述]
EOF
)" \
--external-ref="prd:./tasks/feature-name-prd.md"
# 建立子 bead(驗收標準中包含品質閘門)
br create \
--parent=EPIC_ID \
--title="[故事標題]" \
--description="$(cat <<'EOF'
[故事描述,驗收標準 INCLUDING 品質閘門]
EOF
)" \
--priority=[1-4]
關鍵: 務必使用
<<'EOF'(單引號)作為 HEREDOC 分隔符。這可以防止 shell 將描述中的反引號、$variables和()解譯。
故事大小:首要規則
每個故事必須能在單一 ralph-tui 迭代中完成(約一個 agent 上下文視窗的大小)。
ralph-tui 每次迭代會產生全新的 agent 實例,且不保留先前工作的記憶。如果故事太大,agent 會在完成前就用完上下文。
大小合適的故事:
- 新增資料庫欄位 + 遷移
- 在現有頁面新增 UI 元件
- 使用新邏輯更新 server action
- 在清單中新增篩選下拉選單
太大的故事(請拆分):
- 「建立整個儀表板」→ 拆分為:schema、查詢、UI 元件、篩選器
- 「新增驗證功能」→ 拆分為:schema、中介軟體、登入 UI、session 處理
- 「重構 API」→ 拆分為每個端點或模式一個故事
經驗法則: 如果你無法用 2-3 句話描述變更,那就是太大了。
故事排序:依賴優先
故事會依照依賴順序執行。較早的故事不應依賴較晚的故事。
正確順序:
- Schema/資料庫變更(遷移)
- Server actions / 後端邏輯
- 使用後端的 UI 元件
- 彙總資料的儀表板/摘要檢視
錯誤順序:
- ❌ UI 元件(依賴尚不存在的 schema)
- ❌ Schema 變更
使用 br dep add 設定依賴關係
使用 br dep add 指令指定哪些 beads 必須先完成:
# 先建立 beads
br create --parent=epic-123 --title="US-001:新增 schema" ...
br create --parent=epic-123 --title="US-002:建立 API" ...
br create --parent=epic-123 --title="US-003:建置 UI" ...
# 然後新增依賴關係(issue depends-on blocker)
br dep add ralph-tui-002 ralph-tui-001 # US-002 依賴 US-001
br dep add ralph-tui-003 ralph-tui-002 # US-003 依賴 US-002
語法: br dep add <issue> <depends-on> — issue 依賴於(被 blocked by)depends-on。
ralph-tui 會:
- 將被阻擋的 beads 顯示為「blocked」,直到依賴項完成
- 在依賴項仍為開啟狀態時,絕不選取該 bead 執行
- 在處理 bead 的提示中包含依賴上下文
正確的依賴順序:
- Schema/資料庫變更(無依賴)
- 後端邏輯(依賴 schema)
- UI 元件(依賴後端)
- 整合/打磨(依賴 UI)
驗收標準:品質閘門 + 故事特定
每個 bead 的描述應包含驗收標準,包括:
- 來自 PRD 的故事特定標準(此故事完成的事項)
- 來自 PRD 品質閘門章節的品質閘門(附加在結尾)
良好的標準(可驗證):
- 「在 investor 資料表中新增
investorType欄位,預設值為 'cold'」 - 「篩選下拉選單具有選項:全部、Cold、Friend」
- 「點擊切換開關會顯示確認對話框」
不良的標準(模糊):
- ❌「正常運作」
- ❌「使用者可以輕鬆地執行 X」
- ❌「良好的使用者體驗」
- ❌「處理邊界情況」
轉換規則
- 先從 PRD 提取品質閘門
- 每個使用者故事 → 一個 bead
- 第一個故事:無依賴關係(建立基礎)
- 後續故事:依賴於前一個故事(UI 依賴後端,以此類推)
- 優先權:基於依賴順序,然後是文件順序(0=關鍵,2=中等,4=待辦)
- 所有故事:
status: "open" - 驗收標準:故事標準 + 附加品質閘門
- UI 故事:也附加 UI 特定的閘門(瀏覽器驗證)
拆分大型 PRD
如果 PRD 包含大型功能,請將其拆分:
原始:
「新增好友推廣追蹤,包含不同的訊息」
拆分為:
- US-001:在資料庫中新增 investorType 欄位
- US-002:在投資者清單 UI 中新增類型切換開關
- US-003:建立好友特定的階段推進邏輯
- US-004:建立好友訊息範本
- US-005:為好友接線任務生成
- US-006:按類型新增篩選
- US-007:更新新增投資者表單
- US-008:更新儀表板計數
每個都是一個聚焦的變更,可以獨立完成並驗證。
範例
輸入 PRD:
# PRD:好友推廣
新增將投資者標記為「好友」以進行溫暖推廣的功能。
## 品質閘門
每個使用者故事都必須通過以下指令:
- `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 的投資者。
**驗收標準:**
- [ ] 篩選下拉選單:全部 | Cold | Friend
- [ ] 篩選條件保留在 URL 參數中
輸出的 beads:
# 建立 epic(連結回原始 PRD)
br create --type=epic \
--title="好友推廣追蹤" \
--description="$(cat <<'EOF'
為 Deck 回饋進行溫暖推廣
EOF
)" \
--external-ref="prd:./tasks/friends-outreach-prd.md"
# US-001:無依賴(第一個 - 建立 schema)
br 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 故事(也包含瀏覽器驗證)
br 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
br dep add ralph-tui-002 ralph-tui-001
# US-003:UI 故事
br create --parent=ralph-tui-abc \
--title="US-003:按類型篩選投資者" \
--description="$(cat <<'EOF'
作為 Ryan,我想篩選清單,只查看好友或 cold 的投資者。
## 驗收標準
- [ ] 篩選下拉選單:全部 | Cold | Friend
- [ ] 篩選條件保留在 URL 參數中
- [ ] pnpm typecheck 通過
- [ ] pnpm lint 通過
- [ ] 使用 dev-browser 技能在瀏覽器中驗證
EOF
)" \
--priority=3
# 新增依賴關係:US-003 依賴 US-002
br dep add ralph-tui-003 ralph-tui-002
同步變更
建立 beads 後,進行同步以匯出為 JSONL(用於 git 追蹤):
br sync --flush-only
這會將 SQLite 資料庫匯出到 .beads/issues.jsonl 以進行版本控制。
輸出位置
Beads 儲存在:.beads/ 目錄(SQLite 資料庫 + JSONL 匯出)
建立完成後,執行 ralph-tui:
# 處理特定 epic
ralph-tui run --tracker beads-rust --epic ralph-tui-abc
# 或讓它自動選取最佳任務
ralph-tui run --tracker beads-rust
ralph-tui 會:
- 處理指定 epic 中的 beads(或選取最佳可用任務)
- 完成時關閉每個 bead
- 所有子任務完成時關閉 epic
- 輸出
<promise>COMPLETE</promise>表示 epic 已完成
建立 Beads 前的檢查清單
- 已從 PRD 提取品質閘門(如果缺少則已詢問使用者)
- 每個故事可在一次迭代中完成(夠小)
- 故事已按依賴順序排序(schema → 後端 → UI)
- 品質閘門已附加到每個 bead 的驗收標準中
- UI 故事已包含瀏覽器驗證(如果品質閘門中有指定)
- 驗收標準是可驗證的(不模糊)
- 沒有故事依賴於較晚的故事(僅依賴較早的故事)
- 建立 beads 後已使用
br dep add新增依賴關係 - 已執行
br sync --flush-only以匯出供 git 追蹤
與 beads(Go 版本)的差異
| 指令 | beads (bd) | beads-rust (br) |
|---|---|---|
| 建立 | bd create | br create |
| 依賴關係 | bd dep add | br dep add |
| 同步 | bd sync | br sync --flush-only |
| 關閉 | bd close | br close |
| 儲存 | .beads/beads.jsonl | .beads/*.db + JSONL 匯出 |