Ralph TUI - ビーズ作成 (beads-rust) は何をしますか?
PRD を Ralph TUI の自律実行用ビーズ(エピック+子タスク)に変換します。beads-rust (br CLI) を使用します。
注: このスキルは beads-rust の
brコマンドを使用します。代わりに元の beads (bd) がインストールされている場合は、ralph-tui-create-beadsスキルを使用してください。
ジョブ
PRD(マークダウンファイルまたはテキスト)を取得し、br コマンドを使用してビーズを作成します。
- PRD の「品質ゲート」セクションから品質ゲートを抽出します。
- 機能のエピックビーズを作成します。
- 各ユーザーストーリーの子ビーズを作成します(品質ゲートを追加します)。
- ビーズ間の依存関係を設定します(スキーマ → バックエンド → UI)。
ralph-tui run --tracker beads-rustで実行可能な出力を生成します。
ステップ1: 品質ゲートの抽出
PRD 内の「品質ゲート」セクションを探します。
## 品質ゲート
すべてのユーザーストーリーで成功しなければならないコマンド:
- `pnpm typecheck` - 型チェック
- `pnpm lint` - リンター
UI ストーリーの場合は、以下も含めます:
- dev-browser スキルを使用してブラウザで確認
抽出:
- 共通ゲート: すべてのストーリーに適用されるコマンド(例:
pnpm typecheck) - UI ゲート: UI ストーリーのみに適用されるコマンド(例: ブラウザ確認)
品質ゲートセクションが存在しない場合: ユーザーに成功すべきコマンドを確認するか、npm run typecheck などの適切なデフォルト値を使用します。
出力形式
ビーズは HEREDOC 構文を使用した br create コマンドで作成し、特殊文字を安全に処理します。
# エピックの作成(元の PRD にリンク)
br create --type=epic \
--title="[機能名]" \
--description="$(cat <<'EOF'
[PRD からの機能説明]
EOF
)" \
--external-ref="prd:./tasks/feature-name-prd.md"
# 子ビーズの作成(品質ゲートを受け入れ基準に含める)
br create \
--parent=EPIC_ID \
--title="[ストーリー名]" \
--description="$(cat <<'EOF'
[ストーリーの説明。品質ゲートを含む受け入れ基準]
EOF
)" \
--priority=[1-4]
重要: HEREDOC 区切り文字には常に
<<'EOF'(シングルクォート)を使用してください。これにより、シェルが説明内のバッククォート、$変数、()を解釈するのを防ぎます。
ストーリーサイズ: 最も重要なルール
各ストーリーは、1回の ralph-tui イテレーション(約1エージェントコンテキストウィンドウ)で完了可能である必要があります。
ralph-tui はイテレーションごとに新しいエージェントインスタンスを起動し、以前の作業のメモリは保持しません。ストーリーが大きすぎると、エージェントは完了前にコンテキストを使い果たします。
適切なサイズのストーリー:
- データベースカラムの追加とマイグレーション
- 既存ページへの UI コンポーネントの追加
- 新しいロジックによるサーバーアクションの更新
- リストへのフィルタードロップダウンの追加
大きすぎる(分割すべき)ストーリー:
- 「ダッシュボード全体を構築」 → 分割: スキーマ、クエリ、UI コンポーネント、フィルター
- 「認証を追加」 → 分割: スキーマ、ミドルウェア、ログイン UI、セッション処理
- 「API をリファクタリング」 → エンドポイントまたはパターンごとに1ストーリーに分割
経験則: 変更内容を2〜3文で説明できない場合は、大きすぎます。
ストーリーの順序: 依存関係を優先
ストーリーは依存関係の順序で実行されます。前のストーリーが後のストーリーに依存してはいけません。
正しい順序:
- スキーマ/データベース変更(マイグレーション)
- サーバーアクション/バックエンドロジック
- バックエンドを使用する UI コンポーネント
- データを集約するダッシュボード/サマリービュー
誤った順序:
- ❌ UI コンポーネント(まだ存在しないスキーマに依存)
- ❌ スキーマ変更
br dep add による依存関係
br dep add コマンドを使用して、どのビーズが先に完了する必要があるかを指定します。
# まずビーズを作成
br create --parent=epic-123 --title="US-001: スキーマを追加" ...
br create --parent=epic-123 --title="US-002: API を作成" ...
br create --parent=epic-123 --title="US-003: UI を構築" ...
# 次に依存関係を追加(issue は depends-on に依存)
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 は depends-on に依存(ブロック)されます。
ralph-tui は:
- 依存関係が完了するまで、ブロックされたビーズを「blocked」として表示します
- 依存関係が未完了の間は、そのビーズを実行対象として選択しません
- ビーズの作業時に依存関係のコンテキストをプロンプトに含めます
正しい依存関係の順序:
- スキーマ/データベース変更(依存関係なし)
- バックエンドロジック(スキーマに依存)
- UI コンポーネント(バックエンドに依存)
- 統合/調整(UI に依存)
受け入れ基準: 品質ゲート + ストーリー固有
各ビーズの説明には、次の受け入れ基準を含める必要があります。
- PRD からのストーリー固有の基準(このストーリーが達成すること)
- PRD の品質ゲートセクションからの品質ゲート(最後に追加)
良い基準(検証可能):
- 「
investorTypeカラムを investor テーブルに追加、デフォルトは 'cold'」 - 「フィルタードロップダウンにオプション: All, Cold, Friend」
- 「トグルをクリックすると確認ダイアログが表示される」
悪い基準(曖昧):
- ❌ 「正しく動作する」
- ❌ 「ユーザーが X を簡単に実行できる」
- ❌ 「優れた UX」
- ❌ 「エッジケースを処理する」
変換ルール
- PRD から品質ゲートを抽出します
- 各ユーザーストーリー → 1つのビーズ
- 最初のストーリー: 依存関係なし(基盤を作成)
- 後続のストーリー: 前のストーリーに依存(UI はバックエンドに依存など)
- 優先度: 依存関係の順序に基づき、次にドキュメントの順序(0=重要, 2=中程度, 4=バックログ)
- すべてのストーリー:
status: "open" - 受け入れ基準: ストーリー基準 + 品質ゲートを追加
- UI ストーリー: UI 固有のゲートも追加(ブラウザ確認)
大きな PRD の分割
PRD に大きな機能がある場合は、分割します。
元の PRD:
「異なるメッセージングで友達紹介トラックを追加」
分割結果:
- US-001: investorType フィールドをデータベースに追加
- US-002: 投資家リスト UI にタイプ切り替えを追加
- US-003: 友達固有のフェーズ進行ロジックを作成
- US-004: 友達メッセージテンプレートを作成
- US-005: 友達向けタスク生成を配線
- US-006: タイプによるフィルターを追加
- US-007: 新規投資家フォームを更新
- US-008: ダッシュボードのカウントを更新
それぞれが1つの焦点を絞った変更であり、独立して完了および検証できます。
例
入力 PRD:
# PRD: 友達紹介
ウォーム紹介のために投資家を「友達」としてマークする機能を追加します。
## 品質ゲート
すべてのユーザーストーリーで成功しなければならないコマンド:
- `pnpm typecheck` - 型チェック
- `pnpm lint` - リンター
UI ストーリーの場合は、以下も含めます:
- dev-browser スキルを使用してブラウザで確認
## ユーザーストーリー
### US-001: investorType フィールドを investor テーブルに追加
**説明:** 開発者として、投資家を 'cold' または 'friend' に分類できる必要があります。
**受け入れ基準:**
- [ ] investorType カラムを追加: 'cold' | 'friend'(デフォルト 'cold')
- [ ] マイグレーションを生成して正常に実行する
### US-002: 投資家リスト行にタイプ切り替えを追加
**説明:** Ryan として、リストから直接投資家のタイプを切り替えたい。
**受け入れ基準:**
- [ ] 各行に Cold | Friend 切り替えがある
- [ ] 切り替えると確認ダイアログが表示される
- [ ] 確認時にデータベースのタイプを更新する
### US-003: タイプで投資家をフィルター
**説明:** Ryan として、友達または cold だけを表示するようにリストをフィルターしたい。
**受け入れ基準:**
- [ ] フィルタードロップダウン: All | Cold | Friend
- [ ] フィルターが URL パラメータに保持される
出力ビーズ:
# エピックを作成(元の PRD にリンク)
br create --type=epic \
--title="友達紹介トラック" \
--description="$(cat <<'EOF'
デッキフィードバックのためのウォーム紹介
EOF
)" \
--external-ref="prd:./tasks/friends-outreach-prd.md"
# US-001: 依存関係なし(最初 - スキーマを作成)
br create --parent=ralph-tui-abc \
--title="US-001: investorType フィールドを investor テーブルに追加" \
--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 だけを表示するようにリストをフィルターしたい。
## 受け入れ基準
- [ ] フィルタードロップダウン: All | 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
変更の同期
ビーズを作成した後、同期して JSONL にエクスポートします(Git 追跡用)。
br sync --flush-only
これにより、SQLite データベースがバージョン管理用に .beads/issues.jsonl にエクスポートされます。
出力場所
ビーズは .beads/ ディレクトリに保存されます(SQLite DB + JSONL エクスポート)。
作成後、ralph-tui を実行します。
# 特定のエピックで作業
ralph-tui run --tracker beads-rust --epic ralph-tui-abc
# または最適なタスクを自動的に選択させる
ralph-tui run --tracker beads-rust
ralph-tui は:
- 指定されたエピック内のビーズで作業する(または利用可能な最適なタスクを選択する)
- 各ビーズが完了したらクローズする
- すべての子が完了したらエピックをクローズする
- エピックが完了したら
<promise>COMPLETE</promise>を出力する
ビーズ作成前のチェックリスト
- PRD から品質ゲートを抽出した(存在しない場合はユーザーに確認した)
- 各ストーリーが1イテレーションで完了可能(十分に小さい)
- ストーリーが依存関係の順序で並んでいる(スキーマ → バックエンド → UI)
- すべてのビーズの受け入れ基準に品質ゲートが追加されている
- UI ストーリーにブラウザ確認が含まれている(品質ゲートで指定されている場合)
- 受け入れ基準が検証可能(曖昧ではない)
- どのストーリーも後のストーリーに依存していない(前のストーリーのみ)
- ビーズ作成後に
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 エクスポート |