beads-workflow

Beads のワークフロー — 計画から実行可能なタスクへ

基本原則：「Beads を N 回確認してから、1 回だけ実装する」——N は、できる限り多い回数です。

Beads は非常に詳細に作り込まれているため、大規模なエージェント群を機械的に投入して実装すれば、ほぼ完璧な結果が得られます。

クイックスタート

# 1. Initialize beads in project
br init

# 2. Convert plan to beads (see THE EXACT PROMPT below)

# 3. Polish iteratively
# Run polish prompt 6-9 times until steady-state

# 4. Validate
br dep cycles        # Must be empty
bv --robot-insights  # Check graph health

# 5. Begin implementation
bv --robot-next      # Get first bead

---

正確なプロンプト — 計画から Beads への変換

OK so now read ALL of [YOUR_PLAN_FILE].md; please take ALL of that and elaborate on it and use it to create a comprehensive and granular set of beads for all this with tasks, subtasks, and dependency structure overlaid, with detailed comments so that the whole thing is totally self-contained and self-documenting (including relevant background, reasoning/justification, considerations, etc.-- anything we'd want our "future self" to know about the goals and intentions and thought process and how it serves the over-arching goals of the project.). The beads should be so detailed that we never need to consult back to the original markdown plan document. Remember to ONLY use the `br` tool to create and modify the beads and add the dependencies. Use ultrathink.

短縮版

OK so please take ALL of that and elaborate on it more and then create a comprehensive and granular set of beads for all this with tasks, subtasks, and dependency structure overlaid, with detailed comments so that the whole thing is totally self-contained and self-documenting (including relevant background, reasoning/justification, considerations, etc.-- anything we'd want our "future self" to know about the goals and intentions and thought process and how it serves the over-arching goals of the project.)  Use only the `br` tool to create and modify the beads and add the dependencies. Use ultrathink.

これによって作成されるもの

• 範囲が明確なタスクとサブタスク
• 依存関係のリンク（何が何をブロックするか）
• 背景、理由、考慮事項を含む詳細な説明
• 自己完結型（元の計画を参照する必要はありません）

---

Beads の仕上げ

正確なプロンプト — 仕上げ（標準）

Reread AGENTS dot md so it's still fresh in your mind. Check over each bead super carefully-- are you sure it makes sense? Is it optimal? Could we change anything to make the system work better for users? If so, revise the beads. It's a lot easier and faster to operate in "plan space" before we start implementing these things!

DO NOT OVERSIMPLIFY THINGS! DO NOT LOSE ANY FEATURES OR FUNCTIONALITY!

Also, make sure that as part of these beads, we include comprehensive unit tests and e2e test scripts with great, detailed logging so we can be sure that everything is working perfectly after implementation. Remember to ONLY use the `br` tool to create and modify the beads and to add the dependencies to beads. Use ultrathink.

仕上げの手順

1. 仕上げ用プロンプトを実行する
2. 変更内容を確認する
3. 安定状態になるまで繰り返す（通常は 6～9 回）
4. 進展が止まったら、新しい CC セッションを開始する
5. 必要に応じて、最後の仕上げを Codex/GPT 5.5 に依頼する

---

新しいセッションを使う方法

仕上げの進展が止まったら、新しい Claude Code セッションを開始します。

正確なプロンプト — コンテキストの再確立

First read ALL of the AGENTS dot md file and README dot md file super carefully and understand ALL of both! Then use your code investigation agent mode to fully understand the code, and technical architecture and purpose of the project.  Use ultrathink.

正確なプロンプト — 続けて Beads を確認

We recently transformed a markdown plan file into a bunch of new beads. I want you to very carefully review and analyze these using `br` and `bv`.

その後、標準の仕上げ用プロンプトを実行します。

---

br コマンド

イシューのライフサイクル

br init                              # Initialize workspace
br create "Title" -t feature -p 1    # Create bead
br update <id> --status in_progress
br close <id> --reason "Done"
br reopen <id>                       # If needed

依存関係

br dep add br-child br-parent        # child depends on parent
br dep remove br-child br-parent
br dep list <id>
br dep tree <id>
br dep cycles                        # MUST be empty!

クエリ

br list                              # All beads
br ready                             # Actionable (not blocked)
br blocked                           # Blocked beads
br search "authentication"
br list --json                       # Machine-readable

Git との同期

br sync --flush-only                 # Export DB → JSONL
git add .beads/ && git commit -m "Update beads"

---

bd → br の移行（ドキュメント）

AGENTS.md またはドキュメントに従来の bd の記述がある場合に使用します。

動作上の違い（1 つのみ）：

• br sync は Git コマンドを実行しません。br sync --flush-only の後に、自分で git add .beads/ と git commit（および git push）を実行する必要があります。

変換チェックリスト（順番が重要）：

1. bd コマンド → br コマンド
2. bd sync → br sync --flush-only + git add .beads/ + git commit
3. イシュー ID を bd-* → br-* に変更する必要があると決めつけないでください — プレフィックスは設定可能です（多くの場合、bd-* のままです）。
4. デーモン／自動コミットに関する記述を削除する

確認：

grep -c '`bd ' file.md        # must be 0
grep -c 'bd sync' file.md     # must be 0
grep -c 'br sync --flush-only' file.md  # must be > 0

---

BV ロボットモード

重要： bv を引数なしで実行しないでください — 対話型 TUI が起動します。

bv --robot-triage                    # Full triage
bv --robot-next                      # Single top pick
bv --robot-plan                      # Parallel execution tracks
bv --robot-insights | jq '.Cycles'   # Check for cycles
bv --robot-insights | jq '.bottlenecks'

---

品質チェックリスト

実装の前に、各 bead について以下を確認してください。

• 自己完結している — 外部コンテキストなしで理解できる
• 範囲が明確 — 一貫した作業単位になっている
• 依存関係が明示されている — ブロックする／ブロックされる Beads へのリンクがある
• テスト可能 — 成功基準が明確である
• テストが含まれている — 範囲に単体テストと E2E テストが含まれている
• 機能が保持されている — 計画にあった内容が失われていない
• 単純化しすぎていない — 必要な複雑さが保たれている
• 循環がない — br dep cycles の結果が空である

---

Agent Mail との統合

調整用スレッドとして bead ID を使用します。

# Reserve files for bead
file_reservation_paths(..., reason="br-123")

# Announce work in thread
send_message(..., thread_id="br-123", subject="[br-123] Starting...")

# Close bead when done
br close br-123 --reason "Completed"
release_file_reservations(...)

---

Beads の準備が整った状態

以下の条件を満たしたら、Beads は実装可能な状態です。

1. 安定状態に達している — 複数回仕上げを行っても、変更が最小限にとどまる
2. 複数モデルによるレビュー済み — 少なくとも 1 つの別のモデルがレビューしている
3. 循環がない — br dep cycles の結果が空である
4. テストが含まれている — 各機能に対応するテスト用 Beads がある
5. 依存関係が整理されている — グラフが論理的に整合している

---

参考資料

トピック	参照先
すべてのプロンプト	PROMPTS.md
Bead の構造	BEAD-ANATOMY.md
トラブルシューティング	TROUBLESHOOTING.md
br コマンドのリファレンス	br --help または beads_rust README を参照
BV との統合	bv-graph-triage スキルを参照

---

トラブルシューティング

Worktree エラーの修正

failed to create worktree: 'main' is already checked out が表示された場合：

git branch beads-sync main
git push -u origin beads-sync
br config set sync-branch beads-sync

直接チェックアウトしない専用の同期ブランチを必ず使用してください。

簡易ヘルスチェック

br config list        # All settings
br dep cycles         # Must be empty
which br              # Verify br is installed

詳しい診断については、TROUBLESHOOTING.md を参照してください。

---

検証

# Check for cycles (must be empty)
br dep cycles

# Check graph health
bv --robot-insights | jq '.Cycles'

# Verify all beads have descriptions
br list --json | jq '.issues[]? | select(.description == "")'