beads-workflow

Beads 工作流——从计划到可执行任务

核心原则：“检查 Beads N 次，实施一次”——N 次越多越好，只要你还能忍受。

Beads 的细节和打磨程度都很高，因此可以用机械化方式让大量 Agent 全面实施，最终结果几乎完美。

快速入门

# 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 引用，请使用此流程。

行为差异（仅此一项）：

• 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
• 可测试——成功标准明确
• 包含测试——范围内包含单元测试和端到端测试
• 保留功能——计划中的内容没有遗漏
• 没有过度简化——必要时保留复杂性
• 无循环依赖——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. 经过跨模型审查——至少由一个其他模型审查过
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 == "")'