Beads 边界指南：AI Agent 何时使用 bd 持久化 Issue 跟踪，何时使用 TodoWrite

Beads 边界指南：AI Agent 何时使用 bd 持久化 Issue 跟踪，何时使用 TodoWrite

【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads

导读

本文是 Beads 项目为编码 Agent 提供的一份操作性决策参考，核心回答一个问题：一项任务到底该交给 bd（基于 Dolt 的持久化 issue 跟踪）管理，还是放进会话内的 TodoWrite 清单？两者并非竞争关系，而是服务于不同时间尺度与复杂度的工作。读完本文，你将掌握一套可立即执行的判定启发式（2 周测试、转换信号、决策矩阵），理解 bd 与 TodoWrite 的互补集成模式，并能在真实工作流中识别"复杂性涌现"的转换时刻，避免最常见的六类误用。本文同时结合仓库源码与技能包文件，给出每条结论的实现级依据。

核心问题：你会不会在两周后回来继续？

BOUNDARIES.md 给出的判定起点是一个极其简洁的问题：

"Could I resume this work after 2 weeks away?"（离开两周后，我还能接续这项工作吗？）

• 如果 bd 能帮你恢复上下文 →用 bd
• 如果"扫一眼 Markdown 就能接上" →TodoWrite 就够了

这个启发式抓住了两者的本质差异：bd 提供跨长时间间隔依然存活的、结构化的上下文（依赖图、设计记录、验收标准、完整历史），而 TodoWrite 擅长的是即时会话内的进度跟踪。它是后面所有决策矩阵、转换信号与常见错误分析的总纲。

决策矩阵：什么工作归 bd，什么工作归 TodoWrite

用 bd 的场景（五类）

1. 跨会话工作（Multi-Session Work）

跨越多次压缩周期（compaction）或数天、需要上下文持续存活的任何工作。

典型例子：

• 需要跨多次会话调研的战略性文档开发
• 拆分在多个编码会话中的功能实现
• 需要长时间实验的 Bug 调查
• 经过多轮迭代演进的架构设计

为什么 bd 胜出：issue 捕获的上下文能挺过压缩。数周后回来，完整历史、设计决策与当前状态都在。这是 bd 作为"项目记忆"的根本价值——参见 SKILL.md 对 bd 的定义："Dolt-powered issue tracker for multi-session work with dependencies and persistent memory across conversation compaction"。

2. 复杂依赖（Complex Dependencies）

存在阻塞项（blockers）、前置条件或层级结构的工作。

典型例子：

• OAuth 集成，需要数据库搭建、端点创建、前端改动三者配合
• 有多个并行调研线索的研究项目
• 不同代码区域之间存在依赖的重构
• 需要按特定顺序执行的迁移

为什么 bd 胜出：依赖图自动展示"谁在阻塞谁"。bd ready自动暴露无阻塞的待办工作，无需人工维护。在源码层面，这一机制由 issueops/reader_ready_scope.go 中的ValidateReadyFlagScope与 issueops/readyclaimer.go 中的ReadyClaimer角色共同支撑——bd ready只列"没有被未关闭的 blocks 依赖阻塞"的 issue，且bd ready --claim将"选择 + 原子认领 + 结果水合"放进同一事务，避免多 Agent 并发抢工时拿到同一份工作。

3. 知识型工作（Knowledge Work）

边界模糊、需要探索或战略思考的任务。

典型例子：

• 需要调研框架与权衡取舍的架构决策
• 需要比较多个选项的 API 设计
• 需要测量与实验的性能优化
• 需要理解系统架构的文档编写

为什么 bd 胜出：design与acceptance_criteria字段能承载不断演化的理解，探索过程中获得的新信息可以持续修订 issue。design记录"HOW（怎么构建）"，acceptance_criteria记录"WHAT（成功长什么样）"，两者分离的设计正是为这类"边做边明晰"的工作准备的——详见 ISSUE_CREATION.md。

4. 支线任务（Side Quests）

可能打断主任务的探索性工作。

典型例子：

• 做功能时发现一个值得探索的更优模式
• 调试时注意到相关的架构问题
• 代码评审时识别出潜在改进点
• 写测试时发现需要调研的边界用例

为什么 bd 胜出：用discovered-from依赖创建 issue，可以安全暂停主线工作，两条线索的上下文都被保留，之后随时可恢复任意一条。这正是 PATTERNS.md 中"Side Quest Handling"模式的核心：发现即创建（bd create "Found: ..."）、链接溯源（bd dep add <new> <main> --type discovered-from）、评估阻断性，再决定是阻塞主线还是记入 design 字段继续主线。

5. 项目记忆（Project Memory）

经过较长时间后需要带着完整上下文恢复工作。

典型例子：

• 跨度数月的开源贡献
• 时间表不规律、间隔工作的兼职项目
• 跨多个 Sprint 拆分的复杂功能
• 长调研周期的研究项目

为什么 bd 胜出：Dolt 支撑的数据库可以无限期持久化，所有上下文、决策与历史在恢复时全部可用，不依赖对话回滚（scrollback）或散落的 Markdown 文件。BOUNDARIES.md 明确将"对话回滚或 markdown 文件"列为不可靠的上下文来源。

用 TodoWrite 的场景（四类）

1. 单会话任务（Single-Session Tasks）

当前对话内即可完成的工作。

典型例子：

• 基于清晰规格实现单个函数
• 修复根因已知的 Bug
• 为既有代码补充单元测试
• 更新近期改动的文档

为什么 TodoWrite 胜出：简单清单适合线性执行，无需持久化与依赖管理，会话内即可明确完成。

2. 线性执行（Linear Execution）

无分支的直白逐步任务。

典型例子：

• 有清晰顺序的数据库迁移
• 部署检查清单
• 跨文件代码风格清理
• 按升级指南进行的依赖更新

为什么 TodoWrite 胜出：步骤预定且顺序执行，没有探索、没有阻塞项、没有支线任务，自上而下执行即可。

3. 即时上下文（Immediate Context）

所有信息已经在对话里。

典型例子：

• 用户给出完整规格并要求实现
• 附带复现步骤与修复思路的 Bug 报告
• 有清晰 before/after 蓝图的重构请求
• 基于用户偏好的配置变更

为什么 TodoWrite 胜出：没有需要追踪的外部上下文，对话已包含一切，TodoWrite 只提供用户可见性。

4. 简单跟踪（Simple Tracking）

只需要一个清单向用户展示进度。

典型例子：

• 把实现拆成可见步骤
• 展示验证流程进度
• 展示系统化方法
• 让用户放心工作正在推进

为什么 TodoWrite 胜出：用户想看到思考与进度，TodoWrite 在对话中可见，而 bd 是"后台不可见的结构"。

详细对比表

维度	bd	TodoWrite
持久化	Dolt 支撑，能挺过压缩	仅会话内，对话结束即丢失
依赖	图结构，自动 ready 检测	手动，无自动跟踪
可发现性	bd ready自动暴露待办	在对话里翻找 todos
复杂度	支持嵌套 epic、阻塞项	仅扁平列表
可见性	后台结构，不在对话中	对话中对用户可见
初始化	需要项目内有.beads/目录	始终可用
最适合	复杂、多会话、探索型	简单、单会话、线型
上下文捕获	设计笔记、验收标准、链接	仅任务描述
演化	issue 可随理解持续更新、细化	写定即静止
审计轨迹	完整变更历史	仅对话中可见

关于初始化：SKILL.md 指出 bd 需要bd init初始化（由人类执行，而非 Agent），且 Git 仓库是可选前置——可用BEADS_DIR环境变量配合--stealth标志实现免 Git 运行。TodoWrite 则无需任何前置。

三种集成模式：bd 与 TodoWrite 协同作战

BOUNDARIES.md 强调：bd 与 TodoWrite 可以在同一会话中有效共存，应有策略地两者并用。

模式一：bd 管战略，TodoWrite 管战术

结构：bd 跟踪高层 issue 与依赖关系，TodoWrite 跟踪当前会话的执行步骤。

示例：

bd issue: "Implement user authentication" (epic) ├─ Child issue: "Create login endpoint" ├─ Child issue: "Add JWT token validation" ← 当前正在做 └─ Child issue: "Implement logout" TodoWrite (for JWT validation): - [ ] Install JWT library - [ ] Create token validation middleware - [ ] Add tests for token expiry - [ ] Update API documentation

适用时机：

• 有清晰实现步骤的复杂功能
• 用户想看到当前进度，但存在更大的上下文
• 多会话工作正处于单会话执行阶段

模式二：TodoWrite 作为 bd 的工作副本

结构：先从包含完整上下文的 bd issue 开始，把验收标准提取为 TodoWrite 清单，逐项完成后回写 bd。

示例：

会话开始： - 检查 bd："issue-auth-42: Add JWT token validation" 是否 ready - 把验收标准提取进 TodoWrite - 将 bd issue 标记为 in_progress - 逐项完成 TodoWrite - 边做边更新 bd design notes - TodoWrite 全部完成后，关闭 bd issue

适用时机：

• bd issue 已 ready 但执行本身是线性的
• 用户想要可见的进度跟踪
• 需要结构化方式处理较大的 issue

模式三：会话中途转换

从 TodoWrite 转到 bd（更常见）——执行中意识到工作比预期复杂：

触发信号：

• 发现了阻塞项或依赖
• 意识到本会话无法完成
• 遇到支线任务或相关问题
• 需要暂停并在以后恢复

转换步骤：

1. 用当前 TodoWrite 内容创建 bd issue 2. 备注："Discovered this is multi-session work during implementation" 3. 边发现边补充依赖 4. 保留 TodoWrite 供当前会话使用 5. 会话结束前更新 bd issue 6. 下一会话：从 bd 恢复，需要时新建 TodoWrite

从 bd 转到 TodoWrite（较少见）——bd issue 实际比预期简单：

触发信号：

• 所有上下文已清晰
• 未发现依赖
• 会话内可完成
• 用户想要执行可见性

转换步骤：

1. 保留 bd issue 作为历史记录 2. 从 issue 描述创建 TodoWrite 3. 用 TodoWrite 执行 4. 完成后关闭 bd issue 5. 备注："Completed in single session, simpler than expected"

真实案例剖析

案例一：数据库迁移规划（用 bd）

场景：为生产应用规划从 MySQL 迁移到 PostgreSQL。

为什么用 bd：

• 跨数天/数周的会话工作
• 边界模糊——范围随调研浮现
• 支线任务——发现 schema 不兼容需要重构
• 依赖——schema 验证通过前无法迁移数据
• 项目记忆——中断后需要恢复

bd 结构：

db-epic: "Migrate production database to PostgreSQL" ├─ db-1: "Audit current MySQL schema and queries" ├─ db-2: "Research PostgreSQL equivalents for MySQL features" (blocks schema design) ├─ db-3: "Design PostgreSQL schema with type mappings" └─ db-4: "Create migration scripts and test data integrity" (blocked by db-3)

TodoWrite 的角色：最初不需要。迁移脚本就绪后，单会话测试冲刺阶段才可能用到。

案例二：简单功能实现（用 TodoWrite）

场景：基于清晰规格给现有端点添加日志。

为什么用 TodoWrite：单会话、线性执行（加 import、调 logger、加测试）、所有上下文在用户消息里、对话内即可完成。

TodoWrite：

- [ ] Import logging library - [ ] Add log statements to endpoint - [ ] Add test for log output - [ ] Run tests

bd 的角色：无。对这种直白任务用 bd 属于杀鸡用牛刀。

案例三：Bug 调查（先 TodoWrite，后转 bd）

初始评估：看似简单，先用 TodoWrite。

TodoWrite：

- [ ] Reproduce bug - [ ] Identify root cause - [ ] Implement fix - [ ] Add regression test

实际发生的事：复现发现是间歇性 Bug，根因调查暴露出多个潜在问题，需要时间调查。

转换到 bd：

创建 bd issue: "Fix intermittent auth failure in production" - 描述：起初看似简单，复现表明是复杂竞态条件 - 设计：识别出三个潜在原因，需要逐一测试 - 为每个假设创建带 discovered-from 依赖的 issue 暂停一天，下一会话从 bd 上下文恢复

案例四：带依赖的重构（用 bd）

场景：从三个控制器提取公共验证逻辑。

为什么用 bd：

• 依赖——必须先提取，才能修改调用方
• 多文件改动需要协调
• 潜在支线任务——提取过程中可能发现更好的模式
• 需要跟踪哪些控制器已更新

bd 结构：

refactor-1: "Create shared validation module" → blocks refactor-2, refactor-3, refactor-4 refactor-2: "Update auth controller to use shared validation" refactor-3: "Update user controller to use shared validation" refactor-4: "Update payment controller to use shared validation"

TodoWrite 的角色：可以在逐个实现控制器更新时使用。

为什么有效：bd 确保你不会漏掉某个控制器。bd ready显示下一项可做工作，blocks 依赖防止提取完成前就启动控制器更新。

六类常见错误与对策

错误一：把多会话工作交给 TodoWrite

后果：下一会话忘记已做内容、翻对话历史重建上下文、丢失实现期间做出的设计决策、推倒重来或重复劳动。对策：改用 bd issue，让上下文跨会话持久化。

错误二：用 bd 处理简单线性任务

后果：创建 issue 的开销不划算、用户看不到对话内进度、无谓的工具调用。对策：用 TodoWrite，它正是为此设计的。

错误三：复杂性涌现时不转换

后果：用 TodoWrite 开始"简单"任务、中途发现阻塞项与依赖、明知不合适仍坚持用 TodoWrite、对话结束时丢失上下文。对策：出现复杂度信号就转换到 bd。会话中途转换不算晚。

错误四：创建过多 bd issue

后果：每件小事都建 issue、数据库被琐碎条目塞满、bd ready里难以找到真正有意义的工作。对策：只为真正受益于持久化的建 issue，使用"2 周测试"——两周后 bd 能否帮你恢复？不能就跳过。

错误五：因为熟悉 TodoWrite 而从不使用 bd

后果：多会话项目变成 Markdown 沼泽、丢失依赖与阻塞项跟踪、无法有效恢复工作、留下烂尾的半成品计划。对策：强制自己在下一个多会话项目上用 bd，体会组织性与可恢复性的差别。

错误六：创建 issue 前总是询问（或从不询问）

可直接创建（无需问用户）：

• Bug 报告：范围清晰、问题具体（"Found: auth doesn't check profile permissions"）
• 研究任务：调查性工作（"Research workaround for Slides export"）
• 技术 TODO：实现中发现（"Add validation to form handler"）
• 支线捕获：需要跟踪的发现（"Issue: MCP can't read Shared Drive files"）

为什么可直接创建：询问会拖慢发现捕获的节奏，用户期望对清晰问题主动创建 issue。

应先询问用户：

• 战略工作：边界模糊、存在多种可行方案（"Should we implement X or Y pattern?"）
• 潜在重复：可能与现有工作重叠
• 大型 epic：多方案、范围不清（"Plan migration strategy"）
• 重大范围变更：改变现有 issue 的方向

为什么先询问：确保模糊工作方向一致、防止重复劳动、投入前澄清范围。

经验法则：能一句话写出清晰具体的 issue 标题与描述 → 直接创建；需要用户输入才能澄清 → 先问。

示例：

• ✅ 直接创建："workspace MCP: Google Doc → .docx export fails with UTF-8 encoding error"
• ✅ 直接创建："Research: Workarounds for reading Google Slides from Shared Drives"
• ❓ 先询问："Should we refactor the auth system now or later?"（战略决策）
• ❓ 先询问："I found several data validation issues, should I file them all?"（可能过多）

转换点：识别"复杂性涌现"的瞬间

大多数工作从一个隐含的心理模型开始：

"这看起来很简单"→ TodoWrite

随着工作推进：

✅依旧简单→ 继续 TodoWrite，会话内完成

⚠️复杂性涌现→ 转换到 bd，保存上下文

这门手艺的关键在于识别转换点，典型的转换信号：

• "这比预期耗时更长"
• "我发现了一个阻塞项"
• "这需要更多调研"
• "我应该先暂停这个，去调查 X"
• "用户今天可能无法继续"
• "做这件事时我发现了三个相关问题"

一旦注意到这些信号：立即创建 bd issue、保存上下文、从结构化基础继续工作。

总结启发式：快速决策指南

时间尺度：

• 同一会话 → TodoWrite
• 多个会话 → bd

依赖结构：

• 线性步骤 → TodoWrite
• 有阻塞项/前置条件 → bd

范围清晰度：

• 定义明确 → TodoWrite
• 探索型 → bd

上下文复杂度：

• 对话里应有尽有 → TodoWrite
• 需要外部上下文 → bd

用户交互：

• 用户盯着进度 → TodoWrite（对话中可见）
• 后台工作 → bd（不可见的结构）

恢复难度：

• 扫 Markdown 就能接上 → TodoWrite
• 需要结构化历史 → bd

不确定时：用2 周测试。如果离开两周后没有 bd 你就难以接续，就用 bd。

实践落地：把启发式接入真实会话

BOUNDARIES.md 是 bd 技能包（位于 plugins/beads/skills/beads/）的决策层，与技能包中的操作层配套使用：

• 工作发现：bd ready找出无阻塞的待办，向用户呈现 issue ID、标题、优先级与类型——命令语义见 ready.md；无 ready 任务时建议查看blockedissue 或用create新建。
• 问题创建：bd create "<title>" -t <type> -p <priority>，type 支持 bug/feature/task/epic/chore/decision，priority 取值 0-4（0=critical，4=backlog），并可选择性关联依赖——见 create.md。
• 依赖建模：bd dep add <from> <to> --type blocks|related|parent-child|discovered-from，其中只有blocks影响bd ready的结果——四种依赖类型的完整语义与决策树见 DEPENDENCIES.md。
• 上下文保鲜：把可工作的代码、API 响应样例、输出格式示例与调研背景写进 notes 字段（IMPLEMENTATION GUIDE 模式），让两周后的自己或全新 Agent 实例无需重新发现一切——模板见 RESUMABILITY.md。
• 会话恢复：压缩后先用bd list --status in_progress --json找回在途工作，再bd show <id> --long取全量上下文（见 SKILL.md 的 Session Protocol）。

简而言之：TodoWrite 负责"此刻正在做什么"，bd 负责"这件事从何而来、被什么阻塞、两周后如何接续"。把边界画清楚，Agent 的长时程工作才能既对用户透明，又对压缩免疫。

【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads