多 agent 分工怎么落地:写作用域比提示词更重要

三个 agent 同时改一个仓库,最容易出的不是提示词冲突,是两个人写同一个文件。我改用任务板 + 写作用域隔离之后,合并冲突从每天三次降到零。

目录
  1. 任务板长什么样
  2. 关键改进:给每条任务加写作用域
  3. 合并冲突是怎么真的消失的
  4. 一个反直觉的结论:并行度不是越高越好
  5. 依赖顺序:先建地基,再装修
  6. 复盘

我第一次让两个 agent 同时干活,是让一个写文档、一个改脚本。结果两边都很听话,都在自己的 prompt 里被反复叮嘱"只改自己的部分"——然后它们同时改了 README.md,后写的把先写的整段覆盖掉了,谁也没报错。

那次之后我明白一件事:在文件系统面前,提示词是没有约束力的。 你可以在 prompt 里写十遍"不要碰别人的文件",但两个 agent 拿到的是同一个绝对路径,写下去就是覆盖。

这篇文章记录我换成"任务板 + 写作用域"之后的实际形态。

任务板长什么样

WorkBuddy 的任务板落在磁盘上,一个任务一个 JSON 文件:

text
C:\Users\admin\.workbuddy\tasks\<board-uuid>\1.json
C:\Users\admin\.workbuddy\tasks\<board-uuid>\2.json

单条任务的实际结构(这是我从一个真实看板里读出来的原文):

json
{
  "subject": "拉取本期行情与资金数据(申万指数+13只个股)",
  "description": "申万850818官方日线(含10-26官方值回补)、13只个股K线重算技术面信号、腾讯快照市值/PE、新浪20日资金流",
  "activeForm": "拉取行情与资金数据",
  "status": "completed",
  "id": "1",
  "createdAt": 1793522733411,
  "updatedAt": 1793522866238
}

我机器上现在有 14 个看板目录,每个里面 2~6 条任务。看 createdAt 和 updatedAt 的差值能算出真实耗时——上面这条是 1793522866238 - 1793522733411 = 132827 毫秒,约 2 分 13 秒。

这个时间戳差值是我后来判断"任务拆得对不对"的主要指标。 一条任务跑了 40 分钟,说明它其实是三件事;一条任务 8 秒就完了,说明它没有独立存在的必要。

关键改进:给每条任务加写作用域

默认的任务 JSON 里没有"我要改哪些文件"这个字段。我加了个约定:在 description 开头固定写一行范围声明。

text
WRITE_SCOPE: content/workbuddy/**
READS: docs/CONTENT-SPEC.md, docs/OUTLINE.md
DEPENDS_ON: task-1

三条各自的职责:

字段作用不写会怎样
WRITE_SCOPE这个 agent 唯一被允许写的目录两个 agent 抢同一个文件
READS只读的契约文件agent 以为契约也能改,或者根本不知道有契约
DEPENDS_ON必须先完成的前置任务构建器还没写好就有人开始写内容

第二条 READS 是我后来加的,加的原因很实际:只读不写的文件,如果不显式声明,agent 会倾向于忽略它。 我那次的契约文件 400 行、写得非常细,但两个写手 agent 谁都没读,因为任务描述里只说了"写 8 篇文章"。

合并冲突是怎么真的消失的

我总结出三层防线,按成本从低到高:

text
第一层:目录隔离     content/workbuddy/  vs  content/dsh/   零成本,最有效
第二层:文件命名约定  001-xxx.md ~ 008-xxx.md              防止同目录撞名
第三层:合并前 review 谁改了哪些文件                        兜底

第一层解决 90% 的问题。我把 28 篇文章按大类分给 3 个写手,每人一个 content/<category>/ 目录,物理上就不可能互相覆盖。这一层不需要任何工具支持,只需要分配任务时别偷懒。

第二层解决剩下的 9%。同一个目录内,文件名必须在任务描述里逐个列全,不能写"写 8 篇"。我吃过一次亏:两个 agent 对"第 3 篇"的理解不同,一个写了 003-automation.md,一个写了 003-automation-schedule.md,最后目录里出现 9 个文件。

第三层是我自己做的,只有一条命令:

bash
# 收工前确认每个 agent 只动了自己范围里的文件
git status --porcelain | awk '{print $2}' | sed 's#/[^/]*$##' | sort -u

输出里如果出现超出范围的目录,就是越界了。

一个反直觉的结论:并行度不是越高越好

我一开始以为 agent 越多越快。实测下来,三个写手并行确实比串行快,但第五个开始就变成负收益,原因有三个:

  1. 契约读取是重复成本。每个 agent 都要读一遍 400 行的 CONTENT-SPEC.md,5 个 agent 就是 5 次。
  2. 等待是串行的。构建器(task-1)没写完,所有写手都得等。这时候并行度再高也没用。
  3. review 变成瓶颈。5 个 agent 同时交活,我一个人看不过来,最后还是排队。

所以我现在的基本配置是:1 个基础设施(构建器/设计系统)+ 2~3 个内容生产者 + 1 个收尾(构建校验/部署),4~5 个 agent 就封顶。

依赖顺序:先建地基,再装修

任务板里 DEPENDS_ON 最典型的用法是构建器和内容的关系:

text
task-1  构建静态站引擎 + 设计系统      ← 无依赖,先跑
task-2  撰写 workbuddy 8 篇           ← 依赖 task-1
task-3  撰写 dsh 9 篇                 ← 依赖 task-1
task-4  撰写 review/pitfalls/method   ← 依赖 task-1
task-5  发布链路                       ← 依赖 task-1..4 全部

这里的坑是:内容生产其实不完全依赖构建器。markdown 格式是契约定义的,写手不需要等构建器就能开始写。真正的依赖只有一条——验收要能跑 npm run build。

所以更优的排法是:让 task-1 和 task-2/3/4 同时开跑,只在 task-5 之前汇合。我把这条写进任务描述里之后,整体墙钟时间从"等构建器 40 分钟 + 写作 60 分钟"变成了"写作 60 分钟(构建器在头 40 分钟里并行跑完)"。

复盘

三条我现在会坚持的:

  1. 目录即隔离。分配任务的第一件事是画目录边界,不是写 prompt。
  2. 文件名要逐个列全。"写 8 篇"这种量词是歧义的来源。
  3. 契约要显式声明为只读。不写在任务里的文件,等于不存在。

下一步我想验证一件事:把 WRITE_SCOPE 从"description 里的一行文本"升级成真正会被校验的字段——收工前自动 diff 一次写作用域,越界直接判失败,而不是靠我 git status 肉眼扫。这需要构建器那边配合,暂时还只是想法。