和 Agent 团队一起工作
你的 Coding Agent 可以自己完成改动，也可以把具体工作交给其他 Agent。Agent 团队（agent team） 由 lead 和它分派的 worker 组成，处理一次范围明确的执行：一个任务，或一批固定的任务，配上约定好的检查。 你留在主会话里，由 lead 准备任务、收集结果，并把需要你决定的问题带回来。
本页以给 GET /orders 加分页为例，假设设计和任务已经敲定。前面的规划步骤见工作流程。
谁负责什么
| 角色 | 职责 |
|---|---|
| 你 | 批准验收和成功标准，处理需要人决定的问题，授权交付，并决定是否合并。 |
| Lead | 你的主 Agent 会话。选定范围内的任务，分配工作，安排审阅，集成结果，运行检查，维护执行记录。 |
| Assignee | 在 Beads 中持有任务认领的 Agent。从实现到审阅修复，任务都由它负责。 |
| Worker | 接收具体任务的 Agent。可以修改代码，也可以只做研究、审阅或验证。 |
Lead 也可以同时是 assignee，自己完成改动，这就是只有一个成员的团队。把改动交给一个 worker， 仍然是同一时间只有一个 Agent 在修改代码。
分派出去的 worker 运行时，只有 lead 维护工作图和 active 设计。Worker 把新发现带回来，不自行改计划。 返回的结果只是候选改动；lead 还要拿到审阅和验证证据，才能验收。
两个独立的选择
按你想怎样参与来选工作流，按哪些任务能安全地同时开展来选执行模式。
| 工作流 | 顺序执行 | 并行执行 |
|---|---|---|
| HITL（Human-in-the-Loop） | Agent 完成一次范围明确的执行后回到你这里。同一时间只有一个 Agent 修改代码。 | Lead 把独立任务分给多个 worker，完成后把这一批的结果交给你。 |
| Handoff | Agent 按批准的设计持续推进，一次处理一个任务。 | Agent 持续推进设计，在安全的前提下同时处理独立任务。 |
只读的研究、审阅和验证不会改变执行模式。一个 worker 修复任务时，reviewer 同时读取另一个任务，仍然算顺序执行。
默认设置
默认使用 HITL 工作流和顺序执行，不用在提示词里指定。 如果你没有指定上限，lead 会根据运行时容量、资源隔离和既有约束，公布一个有限的同时写入人数上限， 并为 lead、审阅和验证预留容量。授权的任务总数和同时写入的上限是两回事。
每次执行后由你接着指挥
run-execution 负责这次范围明确的工作。Lead 在第一次执行时提出专用分支，检查结果后回到你这里。 后续执行可以继续用同一个分支。推送或开 PR 前，它会先问你；合并始终由你决定。
Lead 在分派前列出任务、行为职责、已知的文件重叠和集成分支，你可以调整拆分。执行范围只限于约定的这一批。
交接一个 active 设计
iterate-design 必须显式调用。设计必须处于 active 状态，有机械化检查和明确的停止条件。实现前，lead 会提出 范围、分支和基线、检查与审阅安排、worker 上限、需要人决定的问题，以及 PR 交付约定。 它还会确认托管平台、认证、独立的 Agent 身份和所需的分支规则。
你的 GO 授权约定范围内的实现和交付：推送专用分支，首次推送时创建 draft PR，每组改动完成审阅、组合检查和验收后再次推送， 最后在验证和审阅通过后把 PR 标为 ready、请求你审阅。它不授权合并、部署、发布、依赖变更，或调整范围和成功标准。
什么时候可以并行
订单分页的查询实现和客户端 SDK 更新，可能是两个独立任务。只有 API 合同已经敲定、双方都不依赖对方尚未完成的代码， 而且可变资源已经隔离或安排独占使用时，才能一起做。可分开的改动可以在不同 worktree 中修改同一个文件。 如果两边都要修改尚未敲定的响应 schema，就先完成这个前置任务。
Lead 在分派前会检查：
- 范围内至少有两个任务同时就绪，没有未完成的前置任务。
- 每个 worker 都有明确的行为职责，文件重叠已知，共享接口已经敲定。
- 可变的构建产物、数据库和端口各自隔离，或安排独占使用。
- 每个 worker 都能使用自己的 worktree，以及独立的 Beads actor 来认领任务和记录证据。
不同的 worktree 隔离的是文件改动，不是数据库访问或文件系统权限。无法安全并行时，如果并行只是可选项， lead 会说明原因，改为一次处理一个任务。缺少必需的能力，则停止工作。
固定范围可以包含尚在等待的依赖任务。前置任务验收并关闭、人工门槛解决，再确认任务已进入 ready frontier， 才能分派；有空位不代表可以加入无关任务。Lead 从固定范围内的就绪任务中填满可用名额，worker 返回后继续补位； 集成、检查或共享资源成为瓶颈时降低并发。 返回候选结果只会腾出写入名额，不代表任务已验收，也不会释放认领。
两种工作流都使用专用的交付分支，始终保留最近一次已验收的版本。每组候选改动从该版本创建隔离的候选分支， 串行集成。通过 worker 检查的改动可以先暂时集成，再安排审阅；任务仍保持打开，依赖任务不能启动。 改动不直接进入 main。 项目没有 PR 托管平台时，通过分支 diff 审阅。直接在本地合入，需要你的明确指令。
内置 Subagent
插件提供四个职责明确的角色。技能规定流程，subagent 执行具体任务。 在分页功能的例子中，它们分别参与不同阶段：
| 角色 | 怎样参与团队工作 |
|---|---|
researcher | 实现前结合项目上下文和外部证据比较分页方案，把发现交给 lead 用来做决策。 |
worker | 实现分配的查询或 SDK 改动并提交候选结果，交给 lead 安排审阅和集成。不推送、不合并、不关闭任务。 |
reviewer | 独立检查候选结果中的分页错误、权限漏洞、兼容性和缺失的测试。必须修复的问题交回原 worker。 |
verifier | 针对集成后的分支运行约定检查，返回对应版本的结果。失败交给 lead，不由 verifier 自动修复。 |
摸清代码时，工作流会在可用的情况下使用 Coding Agent 自带的 explorer；它不是 dotbrain 内置角色。 主 Agent 自己做更直接时，不必分派给其他 Agent。
Lead 准备完整的任务说明：checkout 和分支、文件归属、需要时提供的任务 ID 和 actor、验收标准、 检查项，以及要返回的证据。Worker 如果发现自己在默认分支上，会停下，除非任务说明记录了你明确要求本地合入的指令。 审阅任务还要注明 reviewer 身份、审阅轮次、准确的 base/head、包含的任务及其验收标准。
Coding Agent 怎么运行它们
Claude Code 从插件获得这些角色。run-execution 按角色名分派任务，dotbrain:worker 在后台运行， 同时修改代码时使用 worktree 隔离。内置角色接收自己的任务说明，不从 lead 的对话分叉。
Codex 在每个已连接的 checkout 中获得生成的 Agent 定义。当前工作流进行隔离实现时，先创建并连接 worktree， 再启动独立的 Codex CLI 会话，任务说明指向内置 worker 定义。CLI 会话不能直接选择自定义 Agent。 Codex 原生 subagent 可以接收具体任务，但仅给它指定目录，并不能构成 worktree 隔离。
Coding Agent 的运行时负责启动、等待和恢复 Agent。Dotbrain 提供上下文、角色、连接和工作流规则， Beads 保存认领和执行状态。运行时能力和权限必须支持所需操作。 分发和自定义方式见会话上下文。
角色名和可以直接发送的请求，见示例提示词。
只提供任务需要的上下文
Lead 提供任务需要的约束和具体文档章节，不复制整段对话。Codex 的分派工具支持控制历史记录时， 范围明确的任务不继承主会话的对话历史；运行时无法限制历史时，lead 会说明这个限制。 任务说明保留项目规则、验收标准、文件归属、权限边界、必需的技能，以及针对当前任务覆盖的默认规则。 省略角色说明已有的默认规则和 lead 的 Beads actor，但保留 worker 自己的 actor。 Agent 默认继承已配置的模型，只有你明确指定其他模型时才切换；内置角色保留各自的 effort 设置，不固定模型。 独立的 Codex CLI 写入会话在启动和恢复时显式设置 medium effort，因为读取 worker 定义并不会应用其中的 TOML 配置。 你明确指定了模型时，恢复会话也使用同一模型。
对于 CLI worker，lead 检查进程退出状态、会话和轮次结果、错误事件、嵌套进程是否停止，以及所需产物， 然后读取最终回复。只有这些信号显示需要诊断的失败时，才读取对话正文和工具输出。
Worker 返回候选版本和分支，每项检查用一行报告；有额外发现、阻塞或设计影响时才列出。 检查失败时保留失败测试名称和错误文本；认领状态由 lead 直接查询 Beads。 Reviewer 返回完整的结构化报告，不写工作图评论。报告包含 base/head、任务范围、验收覆盖、各任务判定， 以及稳定的问题 ID、受影响任务、严重程度、位置、具体问题和重要限制。 Lead 在发送修复任务前，把 reviewer 身份、版本、原文、严重程度和判定原样记录到成员任务。 跨任务问题只指定一个负责的 worker，完整记录保存在它的任务中，其他受影响任务引用该评论和问题 ID。 归属和协调说明注明是 lead 补充的；有争议时交回 reviewer 或你决定。 直接审阅返回发现；没有发现时返回 APPROVE，仅在证据或审阅范围存在重要限制时附上简短说明。简化审阅仍只返回发现，不给判定。
没有运行任何检查命令时，verifier 返回 not run、原因和运行所需条件，并附上可取得的版本与环境信息， 不输出空记录表或 PR-ready block。检查只运行了一部分或失败时，保留已观察到的结果和原样的失败证据。 完成检查后仍提供完整记录和可公开使用的 Verification block，通过的日志只保留摘要。
从任务分配到验收
- 准备。 Lead 固定任务范围、分支、检查项和归属。分派出去的 worker 用自己的 Beads actor 认领任务， 并在整个审阅修复过程中保留认领。
- 实现。 Worker 完成改动，运行检查，提交候选结果，返回版本、检查结果、新发现和阻塞原因。
- 暂时集成。 Lead 从已验收的交付版本创建隔离的集成组候选分支，串行集成通过检查的改动。 任务保持打开，认领不变，依赖任务等待；交付分支仍保留已验收版本。
- 审阅和检查。 独立 reviewer 针对准确的集成版本审阅一组相关改动，包括未修改的调用方和相互影响。 组合检查覆盖每个成员任务的验收标准。前置任务验收后能解锁后续工作时，及时审阅；分组依据已完成的功能、 接口和可独立验证的结果，不必等整批分派或整个 epic 完成。
- 验收和记录。 验收标准满足、需要人决定的问题解决后，lead 用 fast-forward 将交付分支推进到准确的 已审阅、已检查候选版本，记录证据并按规则关闭任务。如果交付版本已前进，先基于新的已验收版本 rebase 或重建候选分支，再更新审阅和组合检查证据。 分派出去的任务以 assignee 的 actor 关闭，在原因中注明 lead；worker 不自行关闭任务，也不交回认领。
审阅修复循环
Lead 把集成后的相关改动交给独立 reviewer。验收标准未满足，或改动引起 blocker/high 回归时，给出 CHANGES， 即使问题出现在未修改的调用方。无关的既有缺陷作为新发现记录，medium/low 问题仍不阻塞验收。 安全性结论需要证据、具体调用路径或小范围检查；证据不足就报告缺口。 如果 reviewer 给出 CHANGES，lead 先记录报告，再把持久化的问题引用交回原来负责的 worker。 Worker 在同一个 checkout 中修复，重新运行检查并提交修复，然后 lead 再请同一个 reviewer 复查。 同一个 reviewer 复查修复和受影响的交互；worker 检查通过并不代表审阅问题已解决。 连续三次得到 CHANGES，则保留这组改动，等你决定。成员记录保留版本范围、任务覆盖、审阅来源、检查证据和问题引用。 补丁或集成环境变化影响验收或审阅覆盖时，要更新证据。必需审阅、组合检查、验收和人工门槛都通过后， 才能关闭任务并释放依赖；后续任务必须从包含已验收前置改动的基线开始。
Worker 自己的测试是过程中的检查证据，不是独立验收。Lead 通常自己运行集成后的单任务检查；handoff 把 verifier 留给最终的循环内验证。同一时间只运行一个 verifier。
代码、测试、构建/CI 配置和 Agent 指令的改动，都需要独立审阅；只改文字说明则不需要。 HITL 中，lead 可以提出小改动的审阅豁免建议，问你是否同意。包含多个任务的分支，交付前需要独立的全分支代码审阅。 最后一次集成审阅只有明确覆盖最终版本的整个分支 diff、所有范围内任务、交互和 active 设计，才能兼作最终代码审阅。 只批准最后一组改动不够。Reviewer 必须没有编写任何被审阅的改动，但不必换新人；覆盖不全时另做全分支审阅。 机械检查、最终人工审阅记录和你的合并门槛保持不变。 只有一个任务的分支，也只有在单任务审阅覆盖最终完整 diff 时才能复用；否则仍需全分支审阅。 Handoff 在有独立 reviewer 可用时还会做一轮不阻塞交付的简化审阅，建议由你决定如何处理。
工作停下时
同一个检查点连续三次检查失败、单任务审阅连续三次给出 CHANGES，或需要人来决定时，这个任务会停下。 Lead 保留尝试记录，说明需要你做什么决定。增加尝试次数或改变标准，只能由你授权。
两种工作流中，失败的集成组和依赖任务都先等待，范围内真正独立的任务可以继续。Lead 保留被搁置的版本、问题、 认领和尝试次数，并证明继续的工作与失败组隔离。独立工作从已验收的基线开始，使用隔离的集成候选结果， 保留失败的改动和无关的已验收改动。无法证明隔离时，报告阻塞原因，停止受影响工作。 被搁置的候选分支与交付分支分开保留，其他组验收后可以进入交付分支，不会带入失败组的改动。 恢复时不 reset 或改写交付分支。 把失败组拆成更小的组时，必须明确新的审阅边界并取得新证据，之前的单任务判定不能直接验收改变后的组。 没有可继续的任务时，handoff 才以阻塞状态结束；只要范围内还有任务被阻塞，PR 就保持 draft。
缺少必需能力、共享状态受损、需要执行超出约定的操作、范围或安全问题无法解决、标准无法满足时，整个 handoff 立即停止。 连续两个循环没有进展，或你要求取消时，也会停止。
取消会保留未完成的文件、分支、worktree 和证据。只有确认原 worker 已停止后，替代 worker 才能接手认领； 收到结果或认领租约过期，都不能证明它已经停止。恢复时保留原范围、检查项和尝试记录。
先调查，再提问
遇到未知问题，先检查可观察的事实；需要了解原因时，查找历史记录，不能从当前代码推断当时的意图。 报告区分证据、推断和未解决的缺口，说明成本最低的下一步，以及是否阻塞当前决定；暂缓处理时给出理由。 小实验只在已有范围和限制内进行。范围内可撤回的实现默认值可以自行选择；偏好、权限、验收标准变更、 影响重大的取舍，以及证据无法解决的问题，带着证据和建议交给你决定。 find-unknowns 保持只读；active 设计维护本次工作的未知问题，Beads 维护执行状态，既有工作流负责持久化 canon。 设计和任务拆分沿具体接口或功能边界展开，每个结果可独立验证，并注明验证边界、接口前置条件和资源依赖。