Beads 多角色工作流实战：用标签、优先级与依赖编排 Architect / Implementer / Reviewer / Product 的协作

Beads 多角色工作流实战：用标签、优先级与依赖编排 Architect / Implementer / Reviewer / Product 的协作

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

复杂项目往往不是单一角色完成的——架构师做设计决策、工程师写代码、评审人把关质量、产品经理定优先级。当这些角色共享同一个任务库时，最大的挑战不是“做事”，而是“对齐”：每个人都需要看到与自己相关的视图，交接必须清晰，过程中发现的新工作要能回到正确的上下文里继续流转。

Beads（本项目代号bd）正是为这类场景设计的：它用标签（labels）表达角色与关注维度，用优先级（priority）表达轻重缓急，用依赖（dependencies）表达工作间的先后与归属关系。本文将基于仓库中的官方示例 examples/multiple-personas/README.md，完整演示如何用bd命令让架构师、工程师、评审人和产品经理在同一个 issue 库里各司其职、顺畅交接，并结合 docs/core-concepts/labels.md、docs/core-concepts/issues.md、docs/core-concepts/dependencies.md 与cmd/bd下源码，讲清每条命令背后的设计原理。

读完本文，你将掌握：一套可复制的多人角色标签体系、按角色过滤工作的查询配方、四种角色间的交接模式，以及一个贯穿三周（架构 → 实现 → 评审 → 上线）的完整演练。

一、问题：同一份工作，四个不同的视角

复杂的项目里，不同角色关注的是同一份工作的不同侧面：

每个角色都需要三样东西：

• 同一份工作的不同视图：架构师看“设计是否完成”，工程师看“哪些任务没被阻塞”，评审人看“哪些改动待审”，产品看“哪些功能在推进”；
• 角色之间清晰的交接：设计完成 → 交给实现；实现完成 → 交给评审；评审通过 → 交给产品验收；
• 把过程中发现的新工作记录在正确的上下文里：工程师写着写着发现一个架构层面的隐患，应该被架构师看到，而不是烂在自己手里。

这正是 Beads 要解决的协作问题。

二、解决思路：Labels + Priorities + Dependencies

Beads 的解法非常朴素但有效：用标签把人分组，用优先级排次序，用依赖画链条，让 issue 自己开口说话——哪个角色该看什么、哪件工作该等哪件，全部沉淀在数据模型里，而不是靠口头约定。

在深入命令之前，先理解 Beads 的三个基础模型（详见 docs/core-concepts/issues.md）：

Issue 类型（-t）：bug（坏了要修）、feature（新功能）、task（工作项：测试、文档、重构）、epic（带子任务的大型特性）、chore（维护类）。

优先级（-p）：0 = 严重（安全、数据丢失、构建崩溃）；1 = 高（主要特性、重要 bug）；2 = 中；3 = 低；4 = 积压。源码层面，bd create的-p值会经过validation.ValidatePriority校验（见 cmd/bd/create.go）。

状态（--status）：open、in_progress、blocked、closed等（bd list的-s/--status支持逗号分隔多值，见 cmd/bd/list.go）。

而标签（labels）则承载结构化字段装不下的“横切维度”。正如 docs/core-concepts/labels.md 开篇所写：状态、优先级、类型这些结构化字段表达核心工作流状态，标签表达其余一切——技术组件、领域、工作量、质量门禁、团队归属、版本追踪。多角色场景里，标签就是“角色的身份证”。

# 初始化 Beads cd my-project bd init # 启动 Dolt server 以便团队自动同步（可选） bd dolt start

bd init在当前项目创建 beads 工作区；bd dolt start则启动 Dolt 数据库服务，让所有 issue 数据（含标签）进入带版本历史的存储，并可通过bd dolt push/bd dolt pull与团队远端同步（见 docs/core-concepts/labels.md 的 “Integration with Git Workflow” 一节）。

三、角色一：Architect —— 创建史诗级设计与技术决策

架构师的产出是“高层的设计”与“技术决策”，在 Beads 里通常用一个epic作为容器，再挂上带architecture标签的子任务。

3.1 创建架构 Epic

# 主 epic bd create "Design new caching layer" -t epic -p 1 # Returns: bd-a1b2c3 # 加架构标签 bd label add bd-a1b2c3 architecture # 架构子任务 bd create "Research caching strategies (Redis vs Memcached)" -p 1 \ --deps discovered-from:bd-a1b2c3 bd label add bd-xyz architecture bd create "Write ADR: Caching layer design" -p 1 \ --deps discovered-from:bd-a1b2c3 bd label add bd-abc architecture bd create "Design cache invalidation strategy" -p 1 \ --deps discovered-from:bd-a1b2c3 bd label add bd-def architecture

这里的--deps discovered-from:bd-a1b2c3很关键。bd create的--deps接受type:id形式的依赖声明（见 cmd/bd/create.go）。discovered-from是非阻塞依赖类型：它只记录“这项工作是从哪件工作里冒出来的”，不影响 ready 队列——子任务不会被 epic 阻塞，可以随时开工，但血缘关系被完整保留（详见 docs/core-concepts/dependencies.md 的依赖类型表）。

bd label add则来自 cmd/bd/label.go，支持bd label add bd-123 label1,label2一次加多个标签（逗号分隔）。标签区分大小写，Backend和backend是两个不同的标签（docs/core-concepts/labels.md 的 Troubleshooting 一节专门提醒了这点）。

3.2 查看架构师的工作视图

# 只看架构类 issue bd list --label architecture # 看架构类且未阻塞的开放工作 bd list --label architecture --status open | grep -v blocked # 高优先级的架构决策 bd list --label architecture --priority 0 bd list --label architecture --priority 1

注意bd list的--label语义：AND（必须全部包含），而--label-any是OR（至少包含一个），两者可以混用（见 cmd/bd/list.go）。例如bd list --label backend --label-any urgent,release-blocker表示“backend 且（urgent 或 release-blocker）”。

3.3 交接给工程师

设计完成后，架构师关闭设计任务，并创建带implementation标签的实现任务，用related依赖把实现与设计关联起来：

# 关闭架构任务（必须写明原因） bd close bd-xyz --reason "Decided on Redis with write-through" bd close bd-abc --reason "ADR-007 published" # 创建实现任务并加标签 bd create "Implement Redis connection pool" -p 1 \ --deps discovered-from:bd-a1b2c3 bd label add bd-impl1 implementation bd create "Add cache middleware to API routes" -p 1 \ --deps discovered-from:bd-a1b2c3 bd label add bd-impl2 implementation # 用 related 软链接把实现关联到 ADR bd dep add bd-impl1 bd-abc --type related # Based on ADR bd dep add bd-impl2 bd-abc --type related

related是非阻塞的软关系，只做图注记；bd dep add的-t/--type若不指定，默认创建blocks（阻塞）依赖（见 cmd/bd/dep.go），这也是为什么文档示例中所有“关联”都显式写了--type related——否则会意外阻塞 ready 队列。Beads 还会在写入时检测依赖环，bd dep cycles可检查既有环（docs/core-concepts/dependencies.md）。

四、角色二：Implementer —— 基于架构决策写代码

工程师的工作以implementation标签为入口，核心诉求是“我现在能做什么”——这正好是bd ready命令的用途。

4.1 查看实现工作

# 只看实现类任务 bd list --label implementation --status open # 看哪些已经就绪（无未关闭的阻塞依赖） bd ready | grep implementation # 高优先级 bug bd list --label implementation --type bug --priority 0 bd list --label implementation --type bug --priority 1

bd ready显示所有阻塞依赖均已关闭的 issue（docs/core-concepts/dependencies.md 的 “Finding Ready Work” 一节）。它支持--priority、--label、--type等过滤参数，是工程师每天开工的第一条命令。

4.2 认领任务并实现

# 认领任务 bd update bd-impl1 --claim # 实现过程中发现新问题——挂到当前上下文下 bd create "Need connection retry logic" -t bug -p 1 \ --deps discovered-from:bd-impl1 bd label add bd-bug1 implementation bug bd create "Add metrics for cache hit rate" -p 2 \ --deps discovered-from:bd-impl1 bd label add bd-metric1 implementation observability # 完成实现 bd close bd-impl1 --reason "Redis pool working, tested locally"

“实现过程中发现的新工作”用--deps discovered-from:<当前任务>挂回上下文，再补上角色标签——这是整个多角色模型里防止工作丢失的核心动作：新任务永远有据可查、有人认领。

4.3 交接给评审人

# 标记为待评审 bd create "Code review: Redis caching layer" -p 1 bd label add bd-review1 review # 链接到实现任务 bd dep add bd-review1 bd-impl1 --type related bd dep add bd-review1 bd-impl2 --type related

五、角色三：Reviewer —— 把关质量、测试与审批

评审人以review标签为入口，除了“看”，还承担“发现问题并形成阻塞链”的职责——这正是blocks依赖发挥作用的地方。

5.1 查看评审工作

# 所有评审任务 bd list --label review --status open # 哪些已就绪可审 bd ready | grep review # 高优先级评审 bd list --label review --priority 0 bd list --label review --priority 1

5.2 执行评审

# 认领评审 bd update bd-review1 --claim # 评审中发现的问题 bd create "Add unit tests for retry logic" -t task -p 1 \ --deps discovered-from:bd-review1 bd label add bd-test1 implementation testing bd create "Fix: connection leak on timeout" -t bug -p 0 \ --deps discovered-from:bd-review1 bd label add bd-bug2 implementation bug critical bd create "Document Redis config options" -p 2 \ --deps discovered-from:bd-review1 bd label add bd-doc1 documentation # 用 blocks 依赖把评审"卡住"，直到问题修复 bd dep add bd-review1 bd-test1 --type blocks bd dep add bd-review1 bd-bug2 --type blocks

blocks是阻塞依赖：只要bd-test1、bd-bug2未关闭，bd-review1就不会出现在bd ready里（docs/core-concepts/dependencies.md：“When issue-1 is open, issue-2 won't appear inbd ready”）。这就把“评审未通过”固化成数据模型：不是靠人记着，而是靠依赖图自动体现。

5.3 通过或打回

# 问题修复后，批准 bd close bd-review1 --reason "LGTM, all tests pass" # 或者打回 bd update bd-review1 --status blocked # （阻塞它的依赖会在依赖树中显现）

六、角色四：Product Owner —— 管理优先级与需求

产品经理不关心具体实现，关心的是“现在最该做什么、什么被卡住了”。

6.1 查看产品视图

# 所有 feature bd list --type feature # 高优先级工作 bd list --priority 0 bd list --priority 1 # 进行中的工作 bd list --status in_progress # 被阻塞的工作 bd list --status blocked

6.2 调整优先级

# 根据客户反馈提升优先级 bd update bd-impl2 --priority 0 # 降低"锦上添花"项的优先级 bd update bd-metric1 --priority 3 # 加产品标签，跟踪面向客户的工作 bd label add bd-impl2 customer-facing

6.3 创建用户故事

# 用户故事 bd create "As a user, I want faster page loads" -t feature -p 1 bd label add bd-story1 user-story customer-facing # 把技术工作关联到用户故事 bd dep add bd-impl1 bd-story1 --type related bd dep add bd-impl2 bd-story1 --type related

至此，四条角色线全部建立。可以看到：角色之间没有任何特殊机制，只有标签 + 依赖 + 优先级三种原语，却完整覆盖了“分工、交接、升级、验收”的全部协作语义。

七、完整演练：三周的多角色工作流

把以上片段串成一个真实的迭代。假设团队要做“Implement rate limiting”（实现限流）：

Week 1：架构阶段（Architect）

# 创建 epic bd create "Implement rate limiting" -t epic -p 1 # bd-epic1 bd label add bd-epic1 architecture # 调研 bd create "Research rate limiting algorithms" -p 1 \ --deps discovered-from:bd-epic1 bd label add bd-research1 architecture research bd update bd-research1 --claim # ... 调研完成 ... bd close bd-research1 --reason "Chose token bucket algorithm" # 设计 bd create "Write ADR: Rate limiting design" -p 1 \ --deps discovered-from:bd-epic1 bd label add bd-adr1 architecture documentation bd close bd-adr1 --reason "ADR-012 approved"

Week 2：实现阶段（Implementer），架构师按需介入

# 工程师：看哪些已就绪 bd ready | grep implementation # 基于架构创建实现任务 bd create "Implement token bucket algorithm" -p 1 \ --deps discovered-from:bd-epic1 bd label add bd-impl1 implementation bd dep add bd-impl1 bd-adr1 --type related bd create "Add rate limit middleware" -p 1 \ --deps discovered-from:bd-epic1 bd label add bd-impl2 implementation # 认领开工 bd update bd-impl1 --claim # 发现新问题 bd create "Need distributed rate limiting (Redis)" -t bug -p 1 \ --deps discovered-from:bd-impl1 bd label add bd-bug1 implementation bug

工程师发现的问题超出了实现范畴，于是升级给架构师：

# 架构师：查看被升级的 issue 并决策 bd show bd-bug1 bd update bd-bug1 --priority 0 # 升级为严重 bd label add bd-bug1 architecture # 架构师接手 # 做出设计决策 bd create "Design: Distributed rate limiting" -p 0 \ --deps discovered-from:bd-bug1 bd label add bd-design1 architecture bd close bd-design1 --reason "Use Redis with sliding window"

工程师根据架构决策继续实现：

bd create "Add Redis sliding window for rate limits" -p 0 \ --deps discovered-from:bd-design1 bd label add bd-impl3 implementation bd close bd-impl1 --reason "Token bucket working" bd close bd-impl3 --reason "Redis rate limiting working"

注意这里的升级路径：实现（implementation）→ 架构（architecture）只需要改标签和补一个discovered-from依赖，问题就自动进入架构师的视图。

Week 3：评审阶段（Reviewer），修复与验收

# 评审人：创建评审任务并关联实现 bd list --label review bd create "Code review: Rate limiting" -p 1 bd label add bd-review1 review bd dep add bd-review1 bd-impl1 --type related bd dep add bd-review1 bd-impl3 --type related bd update bd-review1 --claim # 发现的问题 bd create "Add integration tests for Redis" -t task -p 1 \ --deps discovered-from:bd-review1 bd label add bd-test1 testing implementation bd create "Missing error handling for Redis down" -t bug -p 0 \ --deps discovered-from:bd-review1 bd label add bd-bug2 implementation bug critical # 阻塞评审 bd dep add bd-review1 bd-test1 --type blocks bd dep add bd-review1 bd-bug2 --type blocks

工程师修复评审发现的问题：

bd update bd-bug2 --claim bd close bd-bug2 --reason "Added circuit breaker for Redis" bd update bd-test1 --claim bd close bd-test1 --reason "Integration tests passing"

评审解阻塞，批准；产品关闭 epic，功能上线：

bd close bd-review1 --reason "Approved, merging PR" # 产品经理：功能上线！ bd close bd-epic1 --reason "Rate limiting in production"

至此，一个完整的“epic 从创建到上线”走完了闭环。整个过程中没有一次角色间的口头交接，全部通过标签、依赖、优先级在数据里流转。

八、标签组织：建立团队共识的词汇表

多角色场景能跑通的前提是标签有约定。官方示例给出了推荐的分层标签体系：

# 角色标签 architecture, implementation, review, product # 类型标签 bug, feature, task, chore, documentation # 状态标签 critical, blocked, waiting-feedback, needs-design # 领域标签 frontend, backend, infrastructure, database # 质量标签 testing, security, performance, accessibility # 客户标签 customer-facing, user-story, feedback

8.1 按标签组合过滤

标签的组合过滤是这套体系最有威力的部分——一条命令就能回答一个角色的问题：

# 工程师的严重 bug bd list --label implementation --label bug --label critical # 需要评审的架构 issue bd list --label architecture --label review # 面向客户的 feature bd list --label customer-facing --type feature # 后端开放的实现工作 bd list --label backend --label implementation --status open

⚠️ 标签定义时的注意点（docs/core-concepts/labels.md 有完整说明）：

• 逗号分隔，或重复 flag：-l auth,backend与-l auth -l backend等价；空格不是分隔符，-l 'good first issue'会存成单个带空格的标签（bd会告警提示，可用--quiet静默）；
• 大小写敏感：Backend≠backend，用bd label list-all查看实际存储的标签名；
• 标签用于分类，不是全文搜索：backend、auth是好标签，fix-the-login-bug不是。

8.2 按角色预设视图

把高频查询沉淀为每个角色的“每日视图”：

# 架构师 bd list --label architecture --status open # 我的工作 bd list --label architecture --label needs-design # 待做的设计决策 bd list --label architecture --priority 0 # 高优先级架构 bd list --label architecture --priority 1 # 工程师 bd list --label implementation --status open # 我的工作 bd ready | grep implementation # 可开工的 bd list --label implementation --type bug --priority 0 # 严重 bug bd list --label implementation --type bug --priority 1 bd list --label implementation --status blocked # 被卡住的 # 评审人 bd list --label review --status open # 待评审 bd list --label review --priority 0 # 严重评审 bd list --label review --status blocked # 被阻塞的评审 # 产品经理 bd list --label customer-facing # 面向客户的工作 bd list --type feature --status in_progress # 进行中的 feature bd list --status blocked # 需要关注 bd list --priority 0 # 全局最优先

九、交接模式：角色之间的四种标准动作

官方示例总结了三种标准交接，加上升级，一共四种可复用的模式。

9.1 架构 → 实现

# 架构师创建规格 bd create "Design: New payment API" -p 1 bd label add bd-design1 architecture documentation # 完成后创建实现任务 bd create "Implement Stripe integration" -p 1 bd label add bd-impl1 implementation bd dep add bd-impl1 bd-design1 --type related bd close bd-design1 --reason "Spec complete, ready for implementation"

要点：关闭设计任务时必须写明原因，并指向后续任务——这既是审计记录，也是给下一个角色（人类或 Agent）的上下文。

9.2 实现 → 评审

# 工程师完成 bd close bd-impl1 --reason "Stripe working, PR ready" # 创建评审任务 bd create "Code review: Stripe integration" -p 1 bd label add bd-review1 review bd dep add bd-review1 bd-impl1 --type related

9.3 评审 → 产品（UAT 验收）

# 评审通过 bd close bd-review1 --reason "Approved, deployed to staging" # 产品在 staging 做 UAT bd create "UAT: Test Stripe in staging" -p 1 bd label add bd-uat1 product testing bd dep add bd-uat1 bd-review1 --type related # 产品批准上线 bd close bd-uat1 --reason "UAT passed, deploying to prod"

9.4 升级（Escalation）

# 工程师发现架构层面问题 bd create "Current design doesn't handle edge case X" -t bug -p 0 bd label add bd-issue architecture # 打给架构师 bd label add bd-issue needs-design # 标记需要设计

升级的本质是改标签 + 提优先级，无需任何特殊流程。

十、最佳实践：让多角色协作长期健康

1. 标签使用要一致

# 好：角色清晰分离 bd label add bd-123 architecture bd label add bd-456 implementation bd label add bd-789 review # 坏：角色混用（同一 issue 不应同时是 architecture 和 implementation）

2. 关联相关工作

# 实现永远关联到架构 bd dep add bd-impl bd-arch --type related # bug 关联到 feature bd dep add bd-bug bd-feature --type discovered-from

3. 交接要写明原因

# 好：说明为什么关闭、后续做什么 bd close bd-arch --reason "Design complete, created bd-impl1 and bd-impl2 for implementation" # 不好："done"（太含糊，无法回溯）

4. 该升级时就升级

bd create "Current design doesn't handle edge case X" -t bug -p 0 bd label add bd-issue architecture # 打给架构师 bd label add bd-issue needs-design # 标记为待设计

5. 定期同步

# 每日：各角色各查各的 bd list --label architecture --status open # Architect bd list --label implementation --status open # Implementer bd list --label review --status open # Reviewer # 每周：团队一起过 bd stats # 整体进度 bd list --status blocked # 什么被卡住了？ bd ready # 什么可以开工？

此外，docs/core-concepts/labels.md 还补充了标签治理建议：控制在 5–10 个核心技术标签、每个项目 3–5 个领域标签；定期用bd label list-all清理废弃标签；把标签约定写进 README 或 CONTRIBUTING；用--no-inherit-labels阻止子任务继承父任务的尺寸标签（例如 epic 的large标签会污染bd list -l large的统计）。

十一、常见模式：三个可直接套用的模板

11.1 Spike 先行，再实现

# 架构师创建调研 spike bd create "Spike: Evaluate GraphQL vs REST" -p 1 bd label add bd-spike1 architecture research bd close bd-spike1 --reason "Chose GraphQL, created implementation tasks" # 实现跟进 bd create "Implement GraphQL API" -p 1 bd label add bd-impl1 implementation bd dep add bd-impl1 bd-spike1 --type related

11.2 Bug 分级处置（Bug Triage）

# 收到 bug 报告 bd create "App crashes on large files" -t bug -p 1 # 工程师调查 bd update bd-bug1 --label implementation bd update bd-bug1 --claim # 发现架构层面根因 bd create "Need streaming uploads, not buffering" -t bug -p 0 bd label add bd-arch1 architecture bd dep add bd-arch1 bd-bug1 --type discovered-from # 架构师设计解法 bd update bd-arch1 --label architecture bd close bd-arch1 --reason "Designed streaming upload flow" # 工程师修复 bd update bd-bug1 --claim bd close bd-bug1 --reason "Implemented streaming uploads"

11.3 功能开发全流程（Feature Development）

# 产品创建用户故事 bd create "Users want bulk import" -t feature -p 1 bd label add bd-story1 user-story product # 架构师设计 bd create "Design: Bulk import system" -p 1 bd label add bd-design1 architecture bd dep add bd-design1 bd-story1 --type related # 实现任务 bd create "Implement CSV parser" -p 1 bd label add bd-impl1 implementation bd dep add bd-impl1 bd-design1 --type related bd create "Implement batch processor" -p 1 bd label add bd-impl2 implementation bd dep add bd-impl2 bd-design1 --type related # 评审（注意这里用 blocks：实现完成才能评审） bd create "Code review: Bulk import" -p 1 bd label add bd-review1 review bd dep add bd-review1 bd-impl1 --type blocks bd dep add bd-review1 bd-impl2 --type blocks # 产品 UAT bd create "UAT: Bulk import" -p 1 bd label add bd-uat1 product testing bd dep add bd-uat1 bd-review1 --type blocks

注意 11.3 与 9.1–9.3 的区别：这里评审/ UAT 任务用了blocks（严格的先后顺序），而交接中的“关联”用related（只是信息链接）。何时阻塞、何时只关联，是多角色依赖建模的核心判断——阻塞表达“必须等”，关联表达“别忘了看”。

十二、面向 Agent：为什么这套模型对 AI 编码代理特别友好

这个示例仓库本身就是 Beads 面向AI coding agent 内存升级场景的一部分。多角色工作流对 Agent 而言有三层价值：

1. 视图即上下文：Agent 启动时只需bd list --label <role> --status open就能拿到属于自己的全部工作，不需要人肉翻整个 issue 库；
2. 交接即提示：bd close ... --reason里写清楚的原因，就是下一个 Agent 的交接文档；discovered-from依赖保证“为什么会有这个任务”随时可回溯；
3. 阻塞即决策依据：bd ready直接输出“无阻塞依赖的活”，Agent 可以放心开工，不必自行判断前置条件。

标签还可以作为状态缓存使用（<dimension>:<value>约定，如patrol:muted、mode:degraded），事件是真相、标签是缓存，实现 O(1) 状态查询（详见 docs/core-concepts/labels.md 的 “Labels as State Cache” 一节）。对于需要持续监控自身运行状态的多 Agent 系统，这是天然的状态机载体。

十三、延伸阅读

• Multi-Phase Development —— 按阶段组织工作
• Team Workflow —— 跨角色协作
• Contributor Workflow —— 外部贡献者流程
• Labels Documentation —— 标签管理完整指南
• Issues & Dependencies —— issue 模型与优先级定义
• Dependencies and Gates —— 依赖类型与 ready 队列语义
• CLI Reference ——bd全部命令参考

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