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 是后台不可见的结构。详细对比表维度bdTodoWrite持久化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。示例会话开始 - 检查 bdissue-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 testsbd 的角色无。对这种直白任务用 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 validationTodoWrite 的角色可以在逐个实现控制器更新时使用。为什么有效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 doesnt check profile permissions研究任务调查性工作Research workaround for Slides export技术 TODO实现中发现Add validation to form handler支线捕获需要跟踪的发现Issue: MCP cant 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 prioritytype 支持 bug/feature/task/epic/chore/decisionpriority 取值 0-40critical4backlog并可选择性关联依赖——见 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
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 是后台不可见的结构。详细对比表维度bdTodoWrite持久化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。示例会话开始 - 检查 bdissue-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 testsbd 的角色无。对这种直白任务用 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 validationTodoWrite 的角色可以在逐个实现控制器更新时使用。为什么有效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 doesnt check profile permissions研究任务调查性工作Research workaround for Slides export技术 TODO实现中发现Add validation to form handler支线捕获需要跟踪的发现Issue: MCP cant 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 prioritytype 支持 bug/feature/task/epic/chore/decisionpriority 取值 0-40critical4backlog并可选择性关联依赖——见 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考