# 小团队多代理编程工作流：Worktree、任务分工与合并验收
> 先拆清任务，再让代理并行：每个实现者用独立目录，交付固定提交和检查记录；负责人把变更逐个合到候选版本，在合并后的整体上验证。角色分工与 Git 隔离不能代替运行权限控制。
- URL: https://blog.laozhang.ai/zh/posts/multi-agent-coding-workflow-small-team
- Published: 2026-05-24
- Updated: 2026-10-07
- Author: LaoZhang AI Team (https://blog.laozhang.ai/zh/about)
- Topic: 开发工具与智能体
- Tags: AI 编程代理, 多代理工作流, Codex, Claude Code, Git Worktree
---
小团队使用多个编程代理，可以从一个负责人、两个有明确边界的任务、各自独立的 worktree、一个串行合并入口开始。先确定共同接口和完成标准，让实现者交付可审查的提交；再把要保留的变更合到同一个候选版本，验证合并后的整体，最后由负责人决定是否进入主干。
如果任务还要一起设计接口、反复修改同一个文件，先让一个代理顺序完成。另一个代理可以调查问题或准备验收用例，等实现固定后再验证。多开一个聊天窗口并不自动产生独立工作区；在同一目录里换分支，也不能让两个代理同时独立修改文件。
下面以一个虚构的会议室预约项目说明操作：代理 A 补齐“已满时不可预约”的状态处理，代理 B 更新预约帮助说明。示例用于讲清任务、Git 操作和验收关系，不代表真实代理性能测试，也不承诺提速比例。
## 先判断任务能否拆分，再选协作方式
适合并行的任务，应当能在不等待对方半成品的情况下完成。判断时不要只看“前端”和“后端”这种职位标签，要看实际文件、行为和依赖。
| 本次任务的关系 | 建议怎么做 | 交付时怎么处理 |
| --- | --- | --- |
| 两个模块独立，共同接口已确定 | 两个实现者各用独立工作区 | 两份变更逐个合并，验证组合结果 |
| 一个实现，另一个检查相同需求 | 实现先固定提交，验证者随后检查；前期可并行准备用例 | 验证报告对应明确提交，不边审边改同一目录 |
| 两个代理分别尝试同一个问题的不同方案 | 各用独立工作区，作为候选比较 | 选一个方案，或明确选择哪些部分；不默认全部合并 |
| 接口未定、共享文件频繁变动、改动强耦合 | 一个实现者顺序推进 | 每一步验收后，从新的基线开展下一步 |
会议室项目已有 `available`、`full` 两种状态，以及固定的显示文案。A 只改状态处理模块及其测试；B 只改帮助文本及其测试。两者都使用既有状态定义，因此可以拆开。若 A 发现必须新增 `maintenance` 状态，就先停止这次拆分，由负责人确定接口及受影响的调用方，再重新分配。
同样是“补测试”，含义也可能不同。检查既定行为可以独立开展；测试如果必须猜测尚未决定的接口，就会产生返工。负责人应先给出预期行为和失败条件，而不是让两个代理通过互相猜测来达成一致。
## 角色只需说明谁做决定、谁交付结果
小团队可以由同一个人兼任负责人和最终审查者，不必给每个环节再开一个代理。先保留三种职责：负责人定范围和合并次序，实现者完成一份变更，验证者针对固定版本检查结果。需要独立调查或专门知识时，再增加相应任务。
| 职责 | 应当交付什么 | 不应自行承担什么 |
| --- | --- | --- |
| 负责人 | 任务说明、共同接口、完成标准、合并选择 | 不让各实现者分别决定共同接口 |
| 实现者 | 明确提交、实际变更文件、自检结果、未解决问题 | 不顺手改其他人的范围或发布结果 |
| 验证者 | 对指定提交的检查结果、复现步骤、需修复的问题 | 不用一句“通过”代替结果，也不在同一工作区偷偷续写实现 |
| 最终审查者 | 理解产品行为，判断风险和是否接收 | 不把代理报告当成自动合并授权 |
“验证者只读”“A 只改这个目录”首先是协作约定。能否实际限制写文件、执行命令或访问网络，要看运行环境的工具权限和沙箱。给代理一个角色名，不会凭空收回它已拥有的能力。
验证者发现问题后，可以把具体失败交回实现者；也可以由负责人明确重新分配修复任务。关键是让修复产生新的提交，再针对新版本检查，而不是继续引用旧版本的通过记录。
## 任务说明要让代理知道何时完成、何时停下
任务说明应当足以让一个没有读过前面聊天的人继续工作。可以保存在 issue、任务文件或团队已有的记录中。以下是会议室项目给 A 的示例，不是某个客户端的配置文件。
~~~text
任务：会议室已满时禁止提交预约
负责人：项目维护者
工作目录：../reservation-wt/availability
分支：codex/availability
起点：填写本次确认的完整基线 SHA
目标：
- full 状态显示“已满”，提交按钮不可用。
- available 状态保留现有提交行为。
可修改：
- src/availability.mjs
- tests/availability.test.mjs
共同约定：
- 继续使用 available、full 两种状态。
- 不修改状态定义、依赖文件和其他模块。
- 需要新增状态或扩大范围时，先报告原因并停止该部分实现。
自检：
- node --test tests/availability.test.mjs
- 给出 full、available 两种输入的实际检查结果。
交付：
- 完整提交 SHA、实际变更文件、检查命令及退出结果。
- 未解决问题、需重点审查的逻辑。
- 不合并主干、不发布、不修改共享服务。
~~~
B 则拿到另一份任务：工作目录是 `../reservation-wt/help-copy`，只改 `docs/reservation-help.md` 和 `tests/help-copy.test.mjs`，解释预约状态与现有操作。B 应读到相同的状态约定，但无需接收 A 尚未完成的正文、实现草稿或整段聊天。
任务说明中的路径需要与仓库实际结构一致。示例里的测试文件是假定该演示项目已有的检查入口；应用到你的项目时，要换成已经存在、能验证相应行为的命令，并注明依赖安装和测试数据前提。禁止范围也应与任务有关：依赖锁、路由、共享类型或数据库迁移一旦需要变更，必须有明确负责人和顺序。
## 用独立目录创建 worktree，固定共同起点
手动 Git worktree 适合让多个实现者各有一份工作文件。根据 [Git 官方说明](https://git-scm.com/docs/git-worktree)，各 worktree 分别维护工作文件、索引和 `HEAD`，但共享对象库及多数引用，默认还共享仓库配置。因此，独立分支加独立目录才是本例的工作区安排；只有另一个分支名而仍在同一文件夹里，不够。
以下命令在演示仓库根目录执行，假定本地 `main` 已是负责人确认的起点，工作目录干净，目标目录和新分支名都未被使用。先处理自己的未提交改动，别为了继续示例清空他人的工作。
~~~bash
repo=$(pwd -P)
base=$(git rev-parse 'main^{commit}')
wt_root="$(dirname "$repo")/reservation-wt"
git status --short
mkdir -p "$wt_root"
git worktree add -b codex/availability "$wt_root/availability" "$base"
git worktree add -b codex/help-copy "$wt_root/help-copy" "$base"
git worktree list
~~~
检查列表中的路径、分支和起点，然后让每个代理确认自己的当前目录及 `HEAD`。两份任务说明都记录同一个完整 `$base` 值，避免一个从旧 `main` 开始、另一个从负责人尚未完成的功能分支开始。每个工作区按项目要求准备自己的依赖与可写构建目录，不把另一工作区的半成品输出当作输入。
正常情况下，Git 会阻止同一分支同时在两个 worktree 中检出。遇到分支已占用或目录冲突，先查看 `git worktree list` 并确认现有工作的归属；不要用强制选项把保护绕过去。[Git 的分支和创建规则](https://git-scm.com/docs/git-worktree#_options)说明了这些条件。
### 独立工作区还需要哪些环境安排？
工作文件分开后，进程仍可能争用同一个端口、数据库、输出目录或共享服务。开始前把这些资源写进任务说明：
| 资源 | 本例怎样安排 |
| --- | --- |
| 测试数据 | 使用虚构 fixture，各任务不修改共享数据库 |
| 服务端口 | 各自分配；不需要起服务的任务不占端口 |
| 构建输出与可写缓存 | 放在自己的工作区或独立临时目录 |
| 共享接口与依赖变更 | 一个负责人决定，必要时顺序推进 |
| 仓库引用和配置 | 不让各代理随意改共同分支或仓库级设置 |
Git worktree 不是操作系统沙箱，也不会隔离账号、网络、主目录或密钥。若任务的真正障碍是文件在哪台电脑、代理在哪里执行、如何获得所需权限，先处理 [本地文件与 Codex、Claude Code 的权限入口](https://blog.laozhang.ai/zh/posts/chatgpt-agent-local-files-claude-code-codex-permissions)，再安排并行。
## 交接要固定提交，让检查能复现
A 完成后，不只说“测试过了”，而应交付能定位结果的记录。下面的 `<完整 SHA>` 需要换成实际值；命令和结果只能填真实执行过的内容。
~~~text
任务：会议室已满时禁止提交预约
基线：<完整 SHA>
交付提交：<完整 SHA>
工作区：../reservation-wt/availability
变更：src/availability.mjs、tests/availability.test.mjs
已执行：node --test tests/availability.test.mjs
结果：填写退出码、通过或失败数量及日志位置
未执行：尚未与帮助文案变更一起做整体检查
审查重点：full 禁用提交；available 不改变原行为
未解决问题：填写实际问题，没有则明确写无
下一步：负责人选择接收后，进入候选版本验证
~~~
验证者从这个固定提交检查任务范围、预期行为和失败路径，记录所用版本。若有未跟踪文件是交付所需的实现或测试，应先确认是否纳入任务提交；如果只是临时日志，应单独保存并说明用途。不能用“分支在这里”掩盖实际产物仍留在工作目录的问题。
AI 可以帮助解释差异、找遗漏和运行检查。最终审查仍需要有人理解实际行为，例如禁用按钮是否足够、服务端是否已有对应拒绝逻辑、帮助文案有没有向用户承诺不存在的能力。责任应在团队流程中明确，不由聊天中的自信程度决定。
## 串行合并，在最终组合版本上验收
两个分支各自通过测试，不能证明合在一起仍然能工作。即使没有 Git 冲突，也可能出现行为不一致。负责人先判断两份结果是否互补；如果是相互竞争的方案，先选方案，再决定要合哪些提交。
本例接收 A 和 B 的互补变更，由一个负责人使用候选工作区顺序合并。下面是一个本地流程示例：在创建工作区时保存的同一终端中继续，两个实现分支已经提交且暂停修改，本地 `main` 是待接收的目标。整个整合期间，由负责人协调其他写入者暂停推进这个目标分支。
~~~bash
target=$(git -C "$repo" rev-parse 'main^{commit}')
a=$(git -C "$repo" rev-parse 'codex/availability^{commit}')
b=$(git -C "$repo" rev-parse 'codex/help-copy^{commit}')
candidate="$wt_root/integration"
git -C "$repo" worktree add -b codex/integrate-reservation "$candidate" "$target"
git -C "$candidate" merge --no-ff --no-edit "$a"
git -C "$candidate" merge --no-ff --no-edit "$b"
git -C "$candidate" diff --name-status "$target" HEAD
git -C "$candidate" diff --check "$target" HEAD
~~~
合并失败时停在失败位置，不继续执行后面的合并。负责人可以解决冲突，或把问题交回实现者；修复后的候选版本需要重新检查。`git diff --check` 只检查空白等差异问题，不能证明功能正确。还应读取实际 diff，确认两份任务的范围和共同接口没有漂移。
本例假定项目已准备好三个测试入口，分别验证状态处理、帮助文本和两者组合的预约行为。依赖就绪后，在候选目录运行：
~~~bash
cd "$candidate"
node --test tests/availability.test.mjs tests/help-copy.test.mjs tests/reservation-flow.test.mjs
git status --short
verified=$(git rev-parse HEAD)
~~~
保存测试输出、退出结果及 `$verified` 的完整值。测试失败、结果无法复现，或者测试期间改了代码，都不能交付原来的通过结论。候选目录要保持干净；构建生成的忽略文件也应确认不会替代待提交源码。你的项目若需要编译、端到端测试或其他既有检查，应在这个包含所有待接收变更的版本上执行。
### 测试后主干又变了，怎么办？
重新生成候选版本并验证。旧候选对应旧目标，不能把通过记录直接套到新目标上。人工串行整合或能够验证最新组合版本的合并队列，都可以承担这个职责。
本例在负责人持续独占目标分支写入的前提下，先检查目标仍等于 `$target`、候选仍等于 `$verified`，再让 `main` 快进到这个已验证提交：
~~~bash
cd "$repo"
git switch main
test -z "$(git status --porcelain)"
test "$(git rev-parse HEAD)" = "$target"
test "$(git -C "$candidate" rev-parse HEAD)" = "$verified"
git merge --ff-only "$verified"
test "$(git rev-parse HEAD)" = "$verified"
node --test tests/availability.test.mjs tests/help-copy.test.mjs tests/reservation-flow.test.mjs
~~~
这是一组按顺序执行并检查结果的命令，不是遇到失败仍可继续粘贴的自动脚本。任何一条失败都应停止。SHA 比较本身不是原子锁；如果其他人可以在比较之后同时推进 `main`，仅靠这几行无法消除竞争。团队必须保持串行入口，或使用适合当前托管平台的合并队列与分支保护。
最终记录应能回答：接收了哪些提交、合到了哪个提交、对这个最终结果执行了哪些检查、谁决定接受。合并和测试通过也不等于发布；发布动作按团队已有流程单独进行。
## 失败先保留现场，收口后再清理工作区
失败时，优先保留分支、固定提交、失败命令和输出。如果问题在两份结果的组合上，保留候选工作区，下一位接手者才能看见同样的状态。不要为了让目录干净而丢掉复现所需材料。
清理前至少确认三件事：需要保留的提交已经进入最终接收结果；未提交、未跟踪和忽略的文件已逐项处理；检查记录保存在不会随工作区删除的位置。普通 `git diff` 不能涵盖所有未跟踪或忽略文件，补丁也不是完整备份。
可以在每个待清理工作区分别查看以下列表，再决定哪些文件要保存：
~~~bash
git status --short
git ls-files --others --exclude-standard
git ls-files --others --ignored --exclude-standard
~~~
对本例的实现提交，可在主仓库检查 `git merge-base --is-ancestor "$a" main` 和 B 的同类结果；返回成功才说明提交可从 `main` 到达。若团队采用 squash 等方式接收，原提交未必是祖先，应核对实际接收记录和变更，不能套用这个判断。
确定没有要保留的目录内材料后，用普通 `git worktree remove` 删除本次 worktree。根据 [Git 的清理说明](https://git-scm.com/docs/git-worktree#_commands)，`prune` 清理的是已不存在工作目录的残留管理信息，并不替代正常移除流程。移除报错时先查看原因和文件，保留现场；不把 `--force` 当作常规收尾。
## Codex 和 Claude Code 能怎样承接这套流程？
先确认当前客户端实际提供的能力，再把任务分配给它。下列条件依据 2026 年 10 月 7 日读取的官方文档；独立上下文、独立工作区和运行权限是三个分别要确认的问题。
Codex：[当前子代理文档](https://learn.chatgpt.com/docs/agent-configuration/subagents)说明，本地版本默认启用子代理能力，在用户明确要求或适用的 `AGENTS.md`、skill 要求时委派。子代理默认继承当前沙箱；父会话的实时权限覆盖可能优先于自定义角色默认值，所以“只读角色”不能单凭名称视为有效限制。子代理也不自动等于独立 worktree。需要独立工作目录时，按 [Codex worktree 流程](https://learn.chatgpt.com/docs/environments/git-worktrees)确认起点与路径；应用托管工作区默认使用 detached HEAD，之后可创建分支或通过 Handoff 移动工作。
Claude Code：[Agent teams](https://code.claude.com/docs/en/agent-teams)目前仍是默认关闭的实验功能，成员通过任务列表和消息协调。领取任务的文件锁不等于锁住源码或共享服务。普通 [subagents](https://code.claude.com/docs/en/sub-agents)可以选择 worktree 隔离；该模式默认从仓库默认分支开始，不能假定就是父会话当前提交。交互式 fork 从 v2.1.232 起默认开启，fork 会继承会话上下文，因此也不能把所有子代理一概描述成全新上下文。
采用任一工具，都先确认代理收到正确任务、实际位于正确目录、结果落到可追溯的提交，并能给出检查输出。普通手动 worktree、产品托管工作区和角色配置各有自己的规则，不应复制旧教程中的通用配置后就假定全部生效。
## 试行是否值得继续，看接受结果和人工投入
可以先选几个范围相近、已有测试的低风险任务：先记录单代理顺序完成的表现，再尝试一条实现加验证的流程；只有任务真正独立时，才增加第二个实现者。这是工程试行建议，不是固定代理数量上限或已经证明的最佳方案。
| 要记录的量 | 用来判断什么 |
| --- | --- |
| 实际验收的任务与完成范围 | 产出是否满足同样的需求，避免用 commit 数冒充完成量 |
| 人工审查、协调和修复时间 | 并行节约的时间有没有被交接和返工吃掉 |
| 等待检查或合并的时间 | 瓶颈是否已转移到验收与队列 |
| 重复工作与冲突原因 | 任务边界和共同接口是否需要重新划分 |
| 用量与费用 | 更多代理是否带来值得接受的资源投入 |
例如，同样完成一个小功能，如果两个代理更早写完，但负责人花了更多时间统一接口和修复组合失败，就应缩小拆分。反过来，独立调查提前发现问题、验收用例更清楚、最终结果更快被接受，就有理由保留这条协作方式。
费用按实际使用入口核算。API-key 费用与账号套餐额度不是同一种口径，需要估算长任务的 API 支出时，可参考 [Codex CLI Token 成本估算](https://blog.laozhang.ai/zh/posts/codex-cli-token-cost-estimate)。不要把增加代理必然提速、必然省钱或固定节省某个比例当作试行前提。
出现持续等待对方未完成代码、同一文件反复冲突、验证者不得不重写实现、负责人无暇审查时，就暂停增加任务。先把共同接口确定下来，让一个实现者完成当前步骤并验收，再从新的基线继续。
## FAQ
### 两个人的小团队，最少需要几个编程代理？
先让一个代理实现，由另一名成员或验证代理检查固定结果即可。两个实现者并行只适合能独立完成的任务。代理数量按任务与验收能力决定，没有从本文示例推出的“安全最大值”。
### 可以让两个代理在同一目录使用不同分支吗？
不适合同时编辑。同一个工作目录只有一套当前文件和索引，切换分支会改变双方看到的内容。需要同时写代码时，用不同目录的 worktree 或独立 checkout；worktree 的共享与独立范围见 [Git 官方文档](https://git-scm.com/docs/git-worktree)。
### 给验证代理写“只读”，就不能改文件了吗？
不能只凭这句话判断。角色说明是任务约定，实际能力取决于运行权限和可用工具；[Codex 当前文档](https://learn.chatgpt.com/docs/agent-configuration/subagents)还说明，父会话的实时权限覆盖会重新应用到子代理。应确认实际权限，而不是把角色名称当作沙箱。
### 每个分支测试都通过，为什么还要验证合并结果？
各分支验证的是各自版本，组合后的代码可能出现接口或行为冲突。应把准备接收的变更放到同一个候选版本上检查；目标分支后来变化时，重新组合并验证，不继续引用旧结果。
### 两个代理给了两个修复方案，应该都合进去吗？
先比较并选择。针对同一问题的候选方案通常是在竞争，不是两项独立任务。选定方案或明确选取部分变更后，再检查最终结果；两边各自通过不构成全部接收的理由。
### 检查失败后，能先删除 worktree 再重做吗？
先保存可恢复的状态和失败记录。提交、补丁、未跟踪文件与忽略文件的覆盖范围不同，需要分别处理。确认材料保存完整、工作区不再需要后再正常移除；遇到清理失败先看原因，保留现场。
## 参考来源
本文引用的外部页面，按正文出现顺序排列。最后更新于 2026-10-07。
- [Git 官方说明](https://git-scm.com/docs/git-worktree) (git-scm.com)
- [当前子代理文档](https://learn.chatgpt.com/docs/agent-configuration/subagents) (learn.chatgpt.com)
- [Codex worktree 流程](https://learn.chatgpt.com/docs/environments/git-worktrees) (learn.chatgpt.com)
- [Agent teams](https://code.claude.com/docs/en/agent-teams) (code.claude.com)
- [subagents](https://code.claude.com/docs/en/sub-agents) (code.claude.com)