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

只有在下一个改动能被拆成独立范围、接口已经稳定、每个代理都有隔离工作区，并且团队有足够 review 能力时，小团队才应该同时使用多个编码代理。如果两个代理必须改同一批文件、接口还在变，或者没有人能审查两个 diff，就让一个代理顺序完成。

最安全的默认形态不是“代理团队全自动开工”，而是一个人工负责人、一个隔离的实现代理、一个验证代理。每个任务都要有 owner、worktree 或分支、allowed files、forbidden files、handoff、验证命令和 merge gate。

先把路线板、任务 brief、worktree 隔离、handoff、验证门禁、merge 顺序和 review-hour 指标跑通，再考虑增加更多代理。

先选路线，不先数代理

多代理编程工作流的价值来自可分离的所有权。把“前端代理”和“后端代理”同时放出去并不一定安全，如果双方还在一起发明 API，最后得到的只是两个互相猜测的实现。“修 bug”和“补测试”也不一定能并行，如果测试代理必须猜测修复逻辑，它就不是独立验证者，而是第二个实现者。

小团队先看四条路线。单代理适合强耦合 bug、敏感文件、迁移和全局重构。双代理流水线适合一个实现者加一个验证者。三代理拆分适合接口已冻结、前后端或两个模块能各自推进。更大的代理团队只适合已有 CI、合并队列和 review 余力的场景。

路线不是永久决定。一周内可以从双代理流水线开始，观察是否真的产出更清晰的 diff。只有当第一个拆分能被 reviewer 快速理解，才增加第二个实现代理。过早增加 agent 数量，通常只会把瓶颈从编码转移到冲突处理。

多个编码代理什么时候真的有用

多个代理最适合横向、边界清楚的工作。例如一个代理实现 UI 状态，另一个代理补集成测试；一个代理调查失败路径，另一个代理检查回归覆盖；两个代理在共享类型已经确定后分别改两个模块。这里的关键不是“并行”，而是每个代理能在不等待对方半成品的情况下完成任务。

使用多个编码代理前，先确认五件事。第一，任务能用一两组 fileset 描述，而不是“改完整应用”。第二，接口或行为合同已经稳定。第三，每个代理有独立工作区或分支。第四，人工 reviewer 能看 diff，而不是只能相信聊天记录。第五，CI 和 reviewer 能力足够支撑顺序合并。

第五点最容易被忽略。两个代理写代码的速度可能比一个 reviewer 看代码的速度快很多。如果 lead 变成全天候冲突协调员，流程没有变快，只是把工作从写代码移到了修补边界。

什么时候单代理更好

强耦合任务应该交给一个受监督的代理。数据库迁移还在设计、public API 还没稳定、测试很弱、账单或权限链路风险高、auth middleware 需要改、全仓重构需要统一判断，这些都不适合并行。一个代理加一个人工决策者，反而能保持上下文完整。

实用的 stop rule 很简单：如果一个代理必须等另一个代理的未完成代码才能知道下一步，就不要并行。顺序推进：人工 lead 先写合同，一个代理实现第一步，验证者或人工确认 diff，再从更新后的 main 开始下一步。看起来慢，但后续每一步都有真实 base，不需要猜接口。

这个规则对小团队尤其重要。小团队最稀缺的不是生成代码的速度，而是决定哪些代码可以进入主线的注意力。单代理让审查面保持窄，失败时也更容易回滚。

第一天就能跑的工作流

第一周不要重做全部研发流程。用一个低风险 issue 跑通最小闭环。人工 lead 写 issue brief，选择一条路线；实现代理在单独分支或 worktree 中工作；验证代理只读 brief、changed files 和 handoff；人工 reviewer 看语义 diff 和合并风险；主分支一次只合并一个分支；剩余 worktree 在继续前更新 main。

不要把整个 backlog 交给每个代理。每个代理只拿一个能完成、能解释、能交接的任务。最终交付物应该是一条分支加一份记录，而不是一个堆满未说明编辑的目录。

小团队可以把这套流程写成固定 checklist：本次任务为什么可拆、谁拥有共享接口、哪些文件禁止触碰、验证命令是什么、失败时回到谁手里、合并后哪个 worktree 需要 rebase。只要这些问题答不出来，就说明任务还没准备好并行。

用任务 brief 阻止重叠

任务 brief 是工作流里最重要的对象。它让两个代理不会静悄悄地解决两个不同问题，也让 reviewer 不必从聊天历史里还原真实约束。

md
Agent Task Brief

owner: agent-a
workspace: ../agent-a
branch: agent/a-checkout-state
goal: 在订单摘要组件里增加 checkout state 展示。
non_goals:
- 不修改支付 provider 代码。
- 不修改数据库 schema。
allowed_files:
- src/features/checkout/**
- tests/checkout/**
forbidden_files:
- src/lib/payments/**
- db/migrations/**
- package-lock.json
interface_contract:
- 使用现有 OrderStatus。
- 如果需要新增 status，停止并询问人工 lead。
shared_state:
- 不做本地数据库迁移。
- 只使用测试 fixtures。
required_checks:
- pnpm lint
- pnpm test tests/checkout
handoff_required:
- changed files
- commands run
- proof or failing output
- known risks
- review focus
done_means:
- verifier 能复现检查并解释 diff。

forbidden files 不是形式主义。它保护全局 schema、依赖锁、路由表、共享配置和 API 合同不被多个代理同时改坏。如果任务 brief 写不出禁止范围，任务本身通常还太大，不适合并行。

用 worktree 或分支隔离工作

Git worktree 的价值不是新奇，而是让同一个仓库拥有多个独立工作树。一个代理可以跑测试和改文件，不会污染另一个代理的 checkout。官方 git worktree 文档解释了机制，小团队要关注的是操作边界：每个代理在哪个目录、用哪个分支、能运行哪些命令。

bash
git switch main
git pull --ff-only
git worktree add ../agent-a -b agent/a-checkout-state
git worktree add ../agent-b -b agent/b-profile-copy
git worktree add ../verify -b verify/checkout-state
git worktree list

worktree 只隔离源码文件，不隔离所有状态。数据库 schema、端口、本地服务、密钥、依赖锁、CI 队列、feature flag、public API 都需要单独 owner。一个代理能在自己的目录里编辑，并不代表它可以独占外部资源。

如果环境不能用 worktree，用干净 checkout 或分支也可以。真正要求是每个代理有可见工作边界和合并计划。

handoff 必须能脱离聊天记录

聊天摘要不是 handoff。验证代理和人工 reviewer 需要一个能留在 PR、issue comment 或 branch 文件里的记录。它不需要很长，但必须说明改了什么、跑了什么、哪里有风险、review 该看哪里。

md
Agent Handoff

task: checkout state in order summary
owner: agent-a
branch: agent/a-checkout-state
changed_files:
- src/features/checkout/OrderSummary.tsx
- tests/checkout/order-summary.test.ts
commands_run:
- pnpm lint
- pnpm test tests/checkout
proof:
- checkout tests pass locally
known_risks:
- empty order state still uses existing fallback copy
review_focus:
- confirm OrderStatus mapping is complete
next_owner:
- verifier

验证代理默认不继续实现。它先确认实现代理是否遵守 brief：allowed files、测试、接口合同、风险说明。如果验证代理必须重写同一批 feature files，把它视为任务 brief 失败，而不是第二个代理很勤奋。

只在能减负时增加角色

小团队不需要复杂角色谱系。四个角色足够起步：人工 lead 负责范围、合同、merge 顺序和风险；实现代理产出受限 diff；验证代理测试或挑战 diff；人工 reviewer 做语义 review 和合并决策。specialist 只有在文档、测试、迁移或调查能独立完成时才加入。

lead 不必写每一行代码，但必须拥有合同。如果没有人拥有合同，代理会各自发明合同，后面每个发明都会变成 merge conflict。

验证门禁和合并队列

并行工作只有进入 merge queue 时才变成产品工作。分支要顺序合并、重新跑检查、合并后更新剩余 worktree。不要让两个代理同时把半成品推向 main。

bash
git switch main
git pull --ff-only
git merge --no-ff agent/a-checkout-state
pnpm lint
pnpm test
git push

cd ../agent-b
git fetch origin
git rebase origin/main

验证门禁至少检查五件事：diff 只改 allowed files；必需测试或检查已运行并记录；接口合同没有被破坏；handoff 写清风险和 review focus；人工理解语义变化。AI review 可以做辅助扫描，但不能替代人对产品语义、安全、数据处理和合并责任的判断。

Codex、Claude Code、Cursor 和框架放在哪里

先确定 workflow，再选工具。Codex 适合需要 reviewable diff、CLI、IDE、云任务和 PR-oriented workflow 的场景。Claude Code 适合本地连续会话、复杂上下文和权限细则更多的任务。Cursor background agents、worktree wrapper、Agents SDK 或其他 orchestration framework 都可以实现同一流程。

如果问题是 Codex 和 Claude Code 怎么选，应该看单独的 Claude Code 和 Codex 对比。如果问题是 Codex 使用额度或 quota 边界，应该看 OpenAI Codex 使用限制。本流程的主人不是任何一个品牌，而是 brief、隔离、handoff、diff、验证和人工合并。

工具选择只问一个问题：它能不能保存任务 brief、隔离 workspace、展示 diff、记录 proof、让 reviewer 停下 merge。如果做不到，再强的模型也会把小团队推向不可审查的并行。

用 review 小时衡量，而不是数 agent

agent 数量是弱指标，commit 数也是弱指标。小团队要看 accepted diff per review hour。一个代理能生成很大 diff，但如果 reviewer 花两小时才敢合并，它的实际吞吐未必高。

先跑两三个 issue，再把流程写进团队规范。和一个表现不错的单代理 baseline 比较。如果双代理流水线带来更清楚的测试、更快 review 或更多可接受 diff，就保留。否则缩小拆分。

一周落地计划

第一天，挑一个低风险 issue，写 task brief，只开一个实现分支。第二天，增加验证代理，但不允许它做实现编辑，只让它读 brief、diff、测试输出和 handoff。第三天，顺序合并并记录 review 分钟数。第四天，只有在接口稳定时才尝试第二个独立实现者。第五天，对比 accepted work、rework、冲突、CI 和 review time，决定保留、缩小还是停止。

目标不是证明代理团队很酷，而是找到最小流程，让小团队用更少 lead time 和更少返工交付可审查代码。

FAQ

最小安全多代理编程工作流是什么？

从一个人工 lead、一个实现代理、一个验证代理开始。实现代理在隔离工作区写 scoped diff，验证代理检查 brief、测试、allowed files 和风险，最后由人工 review 和 merge。

两个人团队应该用多个编码代理吗？

可以，但只适合可分离工作。两个人团队更应该先跑双代理流水线，而不是大代理团队。人工 lead 必须有时间审查 diff 和 handoff。

一定要用 Git worktree 吗？

不一定。worktree 是强默认，因为每个代理有独立 working tree。干净 checkout 或分支也能工作。真正要求是 workspace isolation 和 merge plan。

哪些文件应该保持单 owner？

schema、migration、package lock、env、auth middleware、feature flag、public API、共享 route map 都应该单 owner，除非人工 lead 显式改合同。

AI review 能替代人工 review 吗？

不能。AI review 可以找语法、测试、样式和一致性问题。人工 review 仍然负责语义、产品风险、安全、数据处理和合并责任。

什么时候停止使用多个代理？

当代理需要同一批文件、接口还在变、reviewer 跟不上、CI 同类失败重复、accepted diff per review hour 低于单代理 baseline 时，就缩回单代理或顺序流程。

Codex 和 Claude Code 应该怎么分工？

把 Codex、Claude Code、Cursor 或 orchestration framework 都视为同一 workflow 的实现表面。选择能保存 brief、隔离 workspace、展示 diff、记录 proof 和支持 review gate 的工具。

小团队一次能跑多少 agent？

多数小团队先证明一个实现代理加一个验证代理。三代理只有在范围独立时才值得试。更大的 agent team 需要强所有权、CI、merge queue 和 review 能力。