小团队多代理编程工作流：Worktree、任务分工与合并验收

小团队使用多个编程代理，可以从一个负责人、两个有明确边界的任务、各自独立的 worktree、一个串行合并入口开始。先确定共同接口和完成标准，让实现者交付可审查的提交；再把要保留的变更合到同一个候选版本，验证合并后的整体，最后由负责人决定是否进入主干。

如果任务还要一起设计接口、反复修改同一个文件，先让一个代理顺序完成。另一个代理可以调查问题或准备验收用例，等实现固定后再验证。多开一个聊天窗口并不自动产生独立工作区；在同一目录里换分支，也不能让两个代理同时独立修改文件。

下面以一个虚构的会议室预约项目说明操作：代理 A 补齐“已满时不可预约”的状态处理，代理 B 更新预约帮助说明。示例用于讲清任务、Git 操作和验收关系，不代表真实代理性能测试，也不承诺提速比例。

先判断任务能否拆分，再选协作方式

适合并行的任务，应当能在不等待对方半成品的情况下完成。判断时不要只看“前端”和“后端”这种职位标签，要看实际文件、行为和依赖。

会议室项目已有 available、full 两种状态，以及固定的显示文案。A 只改状态处理模块及其测试；B 只改帮助文本及其测试。两者都使用既有状态定义，因此可以拆开。若 A 发现必须新增 maintenance 状态，就先停止这次拆分，由负责人确定接口及受影响的调用方，再重新分配。

同样是“补测试”，含义也可能不同。检查既定行为可以独立开展；测试如果必须猜测尚未决定的接口，就会产生返工。负责人应先给出预期行为和失败条件，而不是让两个代理通过互相猜测来达成一致。

角色只需说明谁做决定、谁交付结果

小团队可以由同一个人兼任负责人和最终审查者，不必给每个环节再开一个代理。先保留三种职责：负责人定范围和合并次序，实现者完成一份变更，验证者针对固定版本检查结果。需要独立调查或专门知识时，再增加相应任务。

“验证者只读”“A 只改这个目录”首先是协作约定。能否实际限制写文件、执行命令或访问网络，要看运行环境的工具权限和沙箱。给代理一个角色名，不会凭空收回它已拥有的能力。

验证者发现问题后，可以把具体失败交回实现者；也可以由负责人明确重新分配修复任务。关键是让修复产生新的提交，再针对新版本检查，而不是继续引用旧版本的通过记录。

任务说明要让代理知道何时完成、何时停下

任务说明应当足以让一个没有读过前面聊天的人继续工作。可以保存在 issue、任务文件或团队已有的记录中。以下是会议室项目给 A 的示例，不是某个客户端的配置文件。

任务：会议室已满时禁止提交预约
负责人：项目维护者
工作目录：../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 官方说明，各 worktree 分别维护工作文件、索引和 HEAD，但共享对象库及多数引用，默认还共享仓库配置。因此，独立分支加独立目录才是本例的工作区安排；只有另一个分支名而仍在同一文件夹里，不够。

以下命令在演示仓库根目录执行，假定本地 main 已是负责人确认的起点，工作目录干净，目标目录和新分支名都未被使用。先处理自己的未提交改动，别为了继续示例清空他人的工作。

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 的分支和创建规则说明了这些条件。

独立工作区还需要哪些环境安排？

工作文件分开后，进程仍可能争用同一个端口、数据库、输出目录或共享服务。开始前把这些资源写进任务说明：

Git worktree 不是操作系统沙箱，也不会隔离账号、网络、主目录或密钥。若任务的真正障碍是文件在哪台电脑、代理在哪里执行、如何获得所需权限，先处理 本地文件与 Codex、Claude Code 的权限入口，再安排并行。

交接要固定提交，让检查能复现

A 完成后，不只说“测试过了”，而应交付能定位结果的记录。下面的 <完整 SHA> 需要换成实际值；命令和结果只能填真实执行过的内容。

任务：会议室已满时禁止提交预约
基线：<完整 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 是待接收的目标。整个整合期间，由负责人协调其他写入者暂停推进这个目标分支。

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，确认两份任务的范围和共同接口没有漂移。

本例假定项目已准备好三个测试入口，分别验证状态处理、帮助文本和两者组合的预约行为。依赖就绪后，在候选目录运行：

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 快进到这个已验证提交：

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 不能涵盖所有未跟踪或忽略文件，补丁也不是完整备份。

可以在每个待清理工作区分别查看以下列表，再决定哪些文件要保存：

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 的清理说明，prune 清理的是已不存在工作目录的残留管理信息，并不替代正常移除流程。移除报错时先查看原因和文件，保留现场；不把 --force 当作常规收尾。

Codex 和 Claude Code 能怎样承接这套流程？

先确认当前客户端实际提供的能力，再把任务分配给它。下列条件依据 2026 年 10 月 7 日读取的官方文档；独立上下文、独立工作区和运行权限是三个分别要确认的问题。

Codex：当前子代理文档说明，本地版本默认启用子代理能力，在用户明确要求或适用的 AGENTS.md、skill 要求时委派。子代理默认继承当前沙箱；父会话的实时权限覆盖可能优先于自定义角色默认值，所以“只读角色”不能单凭名称视为有效限制。子代理也不自动等于独立 worktree。需要独立工作目录时，按 Codex worktree 流程确认起点与路径；应用托管工作区默认使用 detached HEAD，之后可创建分支或通过 Handoff 移动工作。

Claude Code：Agent teams目前仍是默认关闭的实验功能，成员通过任务列表和消息协调。领取任务的文件锁不等于锁住源码或共享服务。普通 subagents可以选择 worktree 隔离；该模式默认从仓库默认分支开始，不能假定就是父会话当前提交。交互式 fork 从 v2.1.232 起默认开启，fork 会继承会话上下文，因此也不能把所有子代理一概描述成全新上下文。

采用任一工具，都先确认代理收到正确任务、实际位于正确目录、结果落到可追溯的提交，并能给出检查输出。普通手动 worktree、产品托管工作区和角色配置各有自己的规则，不应复制旧教程中的通用配置后就假定全部生效。

试行是否值得继续，看接受结果和人工投入

可以先选几个范围相近、已有测试的低风险任务：先记录单代理顺序完成的表现，再尝试一条实现加验证的流程；只有任务真正独立时，才增加第二个实现者。这是工程试行建议，不是固定代理数量上限或已经证明的最佳方案。

例如，同样完成一个小功能，如果两个代理更早写完，但负责人花了更多时间统一接口和修复组合失败，就应缩小拆分。反过来，独立调查提前发现问题、验收用例更清楚、最终结果更快被接受，就有理由保留这条协作方式。

费用按实际使用入口核算。API-key 费用与账号套餐额度不是同一种口径，需要估算长任务的 API 支出时，可参考 Codex CLI Token 成本估算。不要把增加代理必然提速、必然省钱或固定节省某个比例当作试行前提。

出现持续等待对方未完成代码、同一文件反复冲突、验证者不得不重写实现、负责人无暇审查时，就暂停增加任务。先把共同接口确定下来，让一个实现者完成当前步骤并验收，再从新的基线继续。

FAQ

两个人的小团队，最少需要几个编程代理？

先让一个代理实现，由另一名成员或验证代理检查固定结果即可。两个实现者并行只适合能独立完成的任务。代理数量按任务与验收能力决定，没有从本文示例推出的“安全最大值”。

可以让两个代理在同一目录使用不同分支吗？

不适合同时编辑。同一个工作目录只有一套当前文件和索引，切换分支会改变双方看到的内容。需要同时写代码时，用不同目录的 worktree 或独立 checkout；worktree 的共享与独立范围见 Git 官方文档。

给验证代理写“只读”，就不能改文件了吗？

不能只凭这句话判断。角色说明是任务约定，实际能力取决于运行权限和可用工具；Codex 当前文档还说明，父会话的实时权限覆盖会重新应用到子代理。应确认实际权限，而不是把角色名称当作沙箱。

每个分支测试都通过，为什么还要验证合并结果？

各分支验证的是各自版本，组合后的代码可能出现接口或行为冲突。应把准备接收的变更放到同一个候选版本上检查；目标分支后来变化时，重新组合并验证，不继续引用旧结果。

两个代理给了两个修复方案，应该都合进去吗？

先比较并选择。针对同一问题的候选方案通常是在竞争，不是两项独立任务。选定方案或明确选取部分变更后，再检查最终结果；两边各自通过不构成全部接收的理由。

检查失败后，能先删除 worktree 再重做吗？

先保存可恢复的状态和失败记录。提交、补丁、未跟踪文件与忽略文件的覆盖范围不同，需要分别处理。确认材料保存完整、工作区不再需要后再正常移除；遇到清理失败先看原因，保留现场。