ToWow / Flowness 工程进展:从需求到交付

开了 worktree,多个 Claude Code 照样撞车:乐观锁搬过来,还要先报要改的文件

Agent 版乐观锁:每个 Agent 开工前先报要改的文件,合并回主干前再核一次版本。后一半就是数据库的乐观锁,“先报”是给 Agent 补的。读完你能用几份认领文件、一道 hook 和一个合并脚本,把越界的改动挡在主干外面。

我们照最常见的做法试了一次:两个自己在后台干活的 Agent,各用一个 worktree,也就是 git 给同一个仓库开的另一个工作区,各给一个小计算器加一个子命令。两个 Agent 谁也没看见谁,测试都跑绿了,也都改了同一个文件:登记子命令的那张表。先把第一个合进主干 main,再合第二个,git 报:

CONFLICT (content): Merge conflict in commands/__init__.py

Claude Code 的官方文档说,每个 Agent 开一个 worktree,改动就不会相撞。干活的时候确实不撞,撞车只是推迟到了合并那一刻。

这篇回答的是:几个 Agent 同时改一个仓库,怎么让撞车在开工时就露出来,不等活都干完;露不出来的,怎么在合并前再拦一道。我们的做法叫 Agent 版乐观锁:每个 Agent 开工前先报要改的文件,合并回主干前再核一次版本。后一半就是数据库的乐观锁;前一半是给 Agent 补的:数据库退回重来只花几毫秒,Agent 退回一次,丢的是一整轮活。

一、开 worktree、锁任务、撞了再解:各管住了一段

第一个直觉是开 worktree。它管住的是干活的时候,每个 Agent 改自己那份文件、跑自己的测试;合并它不管,开头那次实测就是。

第二个直觉是锁任务。2026 年 2 月,Anthropic 的 Nicholas Carlini 让 16 个 Claude 并行写一个 C 编译器,交出了一个 10 万行、能编译 Linux 内核的编译器。为了不让两个 Agent 同时做同一件事,每个 Agent 开工前往 current_tasks/ 目录里写一个文本文件,算是给这个任务上锁。锁住的是任务的名字:一个 Agent 写下 parse_if_statement.txt,别的 Agent 就不会再领这个任务。可是两个不同的任务完全可能改到同一个文件。登记表、路由表、主入口,谁加功能都要碰,锁任务名锁不住它们。

第三个直觉是撞了再说,让 Agent 自己解冲突。Carlini 写道:

Merge conflicts are frequent, but Claude is smart enough to figure that out.

3 月初,一位在 Hacker News 上分享并行跑编码 Agent 做法的作者,却在评论里承认,合并冲突和认知负担是这套做法的两大难题;这位作者碰上过几次糟糕的合并,不太敢放手让 Agent 去合。两人说的都对。git 报出来的冲突是文字上的,两边改了同一段,比如我们实测里冲突块两边各是一行 import 加一项登记,Agent 把两边合起来并不难。难的是 git 不报的:两边改了同一个文件的不同地方,它直接合上,合得对不对它不管;一边改了某个函数的意思,另一边还照旧意思调用,它一个字都不会说。还有一样是时间,等到合并时才发现,两个 Agent 的活已经都干完了。

做法 管住了 漏了
开 worktree 干活时互不干扰 合并时才撞
锁任务 同一个任务只做一次 不同任务改同一个文件
合并时让 Agent 解 文字冲突 git 不报的冲突,发现得晚

二、老方法,新补丁:后一半照搬乐观锁,前一半得补

把数据库的乐观锁搬过来,合并那一半几乎不用改。改不掉的是它的一个前提:数据库清楚每个事务读了什么、写了什么,冲突了退回重来只花几毫秒;Kung 和 Robinson 1981 年提出乐观方法时,赌的就是冲突很少。Agent 一轮读、改、写动辄几十分钟到几个小时,开工前它自己也说不全要改哪些文件,说出来的还常常偏小。所以要补一步:开工前先把要改的文件报出来,从完成判据(判定这个任务算做完的那几条)倒推着报,再在它写下每个文件的那一刻核对一次。这一半按文件先占住,其实是一把悲观锁。

乐观锁就是带着读到的版本去写,版本变了就拒:HTTP 里是 If-Match 对不上回 412,数据库里是 WHERE version = 读到的版本 改到 0 行。搬到 Agent 身上,对应关系很直:worktree 是本地副本,开工时主干所在的那个提交是读到的版本,合并前的检查是验证,合并本身是写回,被拒就是 412。

别人改了你在调用的函数,文件认领看不出来,这套最小版里只能靠合并前在最新主干上从入口跑测试。这是前提里“读了什么”那一半,先报补不上(论文里的验证不只看写,还要看你读过的东西有没有被先提交的事务改过):文件认领只看得见“改了哪些文件”,看不见“用了谁的函数”。测试要是不从用户走的那条路进去,它也看不见,第五节有一次实测正好撞上。

三、先报:从完成判据倒推要改的文件

先报听起来只是多写一份清单,难在报全。我们自己吃过这个亏。

6 月,我们有一批 14 个任务,每一个都漏报了测试文件和接线点(把新代码接进系统的那一处:登记表、检查列表、入口里的一行调用)。这是一个评审 Agent 把这批任务扫了一遍后报告的;它举的例子里,新写的校验得接进检查列表,“否则建好永不被调用=假完成”。评审报告出来之前,其中一个任务已经撞上了:它只报了要修的那个实现文件,执行的 Agent 要补完成判据里点名的测试时,被系统里一道只许写已报文件的拦截挡下了。

所以要改的文件不能靠回忆。6 月那次以后,我们定过一条规矩:从每条完成判据倒推“实现它必然要写的东西”,先是接线点和测试两类,后来扩成四类。第一类是接线点;第二类是测试文件;第三类是跟着一起变的同批文件,比如说明文档、脚本;第四类不是文件,换到你的项目里,可能是数据库里的一条记录,文件认领管不到它,最小版只能写进任务说明。接线点在第五节的实测里还会从测试里漏掉。

扩成四类时还加了一句更重的:报小了比不报更坏。你什么都没报,别人知道要提防你;你报了一份不全的,检查就以为自己看全了。两份认领一对,没有交集,你放心地让两个任务同时跑,其实它们都要改登记表,只是谁也没写。

四、开工前认领:写的那一刻就核对

报出来的文件要有地方放,还要有人在 Agent 动手的那一刻去对。最小版用两样东西。

一样是认领文件。scripts/claim.sh a 文件… 做两件事:从主干开一个 worktree .claude/worktrees/a,再在仓库的 .git/claims/ 下写一份认领,第一行记下此刻主干所在的提交,下面一行一个文件。放在 .git 里,是因为所有 worktree 共用这一个目录,谁看到的都是同一份,也不会被提交进哪个分支。别的任务已经认领的文件,claim.sh 直接拒绝。

另一样是一道 hook(Claude Code 在调用工具之前自动跑的脚本),挂在编辑和写文件这两个工具上。Agent 每写一个文件,hook 先看它在哪个 worktree、写的是谁的文件。别人认领的,拦下,告诉它先把自己那部分做完、提交,再告诉人缺哪个文件;自己没认领、也没人认领的,也拦下,告诉它用 claim.sh 补报。写到自己 worktree 外面的,别的 worktree 也好、主目录也好,同样拦下。

补报这里,我们选了放开:Agent 可以自己补报没人要的文件,补报的那一行前面带个加号,合并时脚本先把这些行打印出来给人看。第三节那个任务走的是另一边,不许自己扩,只能退回规划,那一轮做好的实现就没能合进去。最小版宁可让它扩,但留下痕迹。

这道 hook 有个盲区:它只管编辑和写文件这两个工具,Agent 用 shell 写文件,echo >>、heredoc、一段 Python,它都看不见。我们实测的三个装了这套配置的 Agent 里,有两个主要就是用 shell 写文件的。兜底在合并那一步。

装上以后,我们把开头那个场景再跑一遍,这次先分好认领。任务 a 认领了它的实现、测试和登记表;任务 b 只认领了实现和测试,漏了登记表,漏的正是 6 月那批任务漏的那一类。b 的 Agent 进了 worktree,先查自己的认领,然后说:

The claim covers commands/mul.py and tests/test_mul.py, but not commands/__init__.py, where the registry is wired. I'll claim that file.

补报被拒:“REFUSED: commands/init.py is claimed by a”。它没去碰登记表,把认领范围里的实现和测试写完、提交,提交说明写着“registry wiring pending”,汇报里写明缺的就是登记表里那一行。没装的那次,冲突在两个 Agent 都干完以后才冒出来;这一次,它照 CLAUDE.md 先查了认领,开工时就知道撞了。

五、合并前再核一次版本

合并只由人来做。Agent 说做完了,你在主目录跑 scripts/land.sh b,它按顺序查四样,哪一样不过都拒绝,主干不动。第一样是认领的兜底,后三样就是乐观锁:核版本、验证、带条件地写回。

第一样,这个分支改过的每个文件,都得在 b 自己的认领里,并且不在别人的认领里。shell 写的文件逃得过 hook,逃不过这一步。我们让一个 Agent 用 echo >> 往 a 认领的登记表里追加一行再提交,hook 一声没出,合并时被拒:“REFUSED: changed outside the claim: commands/init.py(unclaimed) commands/init.py(claimed by a)”。

第二样,从认领那一刻起,主干有没有改过 b 认领的文件。认领第一行记的那个提交就是读到的版本;这些文件在主干上变了,说明有人没认领就改了它们,先停下让人看一眼,看过没问题再加 --accept。

第三样,把 b 的分支 rebase 到最新主干上(把这个分支的提交挪到最新的主干后面重放一遍),在那里跑一遍测试。这一步替的是论文里对读过的东西的那次检查:别人改了你在用的东西,指望测试会红。

第四样,git merge --ff-only,也就是快进合并:只有主干还停在刚才跑测试的那个提交上,才把 b 接上去。跑测试的这几分钟里,你在另一个终端合了别的任务,或者有个 Agent 没守规矩直接往主干提交了,它就拒绝,提示你重跑一遍。这一步就是 If-Match,检查和写入之间的那道空档(TOCTOU)在这里合上。

再说第四节那次实测后来的事。我们替任务 a 提交了它的子命令,实现、登记、测试都有,合并成功,再跑 claim.sh --release a 放开 a 的认领(合并脚本不会替你放开)。接着我们故意拿 b 的半成品去试合并,这一步开跑前就写进了测试计划,押它会在第三样被拒。押错了:b 的 Agent 写的测试直接调用新函数,不经过登记表,测试全绿,合了进去。合进主干以后,用户真正会敲的 python3 cli.py mul 4 3 报 KeyError: 'mul'。b 的 Agent 其实在汇报里写明了登记表还没接;真用时,汇报里写着没接上的分支不合,第六节那条规矩说的就是这个。

这一下说明,核版本管的是文件和版本,不管功能接没接上。接线点要单列一类,正是因为它容易从认领里漏掉,也容易从测试里漏掉。所以完成判据里写明从用户平时走的入口跑通,这里就是 cli.py,测试也从那里进。我们在脚本里补跑了一例:同样漏了登记表的分支,测试改成去跑 cli.py,合并在第三样就被拒,主干不动;同一个分支把测试改回直接调函数,就合了进去,入口照样报 KeyError。

我们另起一个后台 Agent 接着做:

  1. a 的认领已经放开,登记表没人认领了。
  2. b 的分支已经跟上主干:上一次试合并时,land.sh 已经把它 rebase 到最新主干。
  3. 新 Agent 补报登记表,一次就过;它把子命令登记进去、提交。我们再跑 land.sh b,脚本先打印“claimed after the start: + commands/init.py”,测试通过,合进主干。
  4. mul 4 3 输出 12。

六、照着搭:装进真仓库之前,先故意犯一次

动手前先说顺序:先在一个新建的空仓库里故意犯一次,都对了,再装进你的真仓库。故意犯一次里有一步要直接往主干提交,在真仓库里跑,会把一行测试用的改动,连同你手上还没提交的改动,一起提交进你的主干;仓库 README 的步骤都钉在 ~/drill 这个目录里。

五个文件在 macOS 上用 Claude Code 2.1.302 的后台 Agent 实测过,都在配套仓库 github.com/Towow-ai/harness-patterns 的 05-file-claims 目录,README 写了怎么装:

.claude/settings.json    挂上 hook
.claude/hooks/claims.sh  写文件前核认领
scripts/claim.sh         开 worktree、写认领
scripts/land.sh          核四样、快进合并
CLAUDE.md                给 Agent 的四条规矩

故意犯一次,就是让 a 认领一个文件,再让 b 去碰它,看三道关各拦不拦:

做的 该看到 谁拦
b 的 Agent 改 a 的文件 is claimed by hook 或 claim.sh
从 shell 替它写进去,合并 b changed outside the claim land.sh 第一样
主干上直接改 a 的文件,合并 a main changed your files land.sh 第二样

第一件看的是 Agent 去写别人认领的文件,当场被拦;第二件是 hook 看不见的 shell 写入,在合并时兜住;第三件就是核版本。每条命令和该看到的原文都在 README 的编号步骤里。

装进真仓库以后,有一条规矩要人来守:Agent 汇报里说缺哪个文件、哪里还没接上的,先别合。等占着那个文件的任务合并,用 claim.sh --release 放开它的认领;把这个 Agent 的 worktree rebase 到主干,再让它补报、做完,一次合进去。

七、代价与不适用

最直接的代价是热点文件会让任务排队。登记表、路由表这类文件谁加功能都要碰,一个任务认领了,别的任务只能先做别的,等它合并、放开。这既是代价,也是本意:我们的规矩是,要改的文件有交集的任务必须排先后。

合并和放开认领都要人来跑,换来的是写回主干这一步不交给 Agent。认领报得准不准,仍然要人看:合并时打印出来的加号行,是 Agent 自己扩的范围,值得读一眼。

不是哪里都要装。同一时间只跑一个 Agent;几个任务按目录天然分开,谁也不碰共同的文件;子 Agent 只读不写:这几种情况,开 worktree 就够了。

回到那 16 个 Claude

Carlini 说合并冲突很常见,Claude 解得了。文字上的冲突确实解得了。解冲突的那个 Agent 不知道的,是另一个任务原本想做什么,也不知道新代码到底接没接上。前一样要开工前写下来,后一样要合并前从入口跑一遍才知道。

这套做法是两种锁拼在一起,叫它乐观锁,是跟着搬来的那一半起的名。数据库通常二选一:要么先占住,要么先干活、最后再核。Agent 两样都要,因为它既输不起一整轮活,又说不全自己要碰什么。

今天能做的第一步:下一次同时开两个 Agent 之前,先替每个任务写下它要改的文件,从完成判据倒推,接线点和测试都写上。两份一对,有交集的那两个,别同时开。

配置、故意犯一次的步骤和实测条件,都在 github.com/Towow-ai/harness-patterns 的 05-file-claims 目录。


Flowness 是我们自己做的自运转 Harness,也就是让很多个 Agent 节点共用一份事件记录(按时间记下每个决定和结果)、一起完成复杂任务的那套系统。这个系列里的模式,整理自这样一个烧了粗略估计 1400 亿 Claude token,持续运行超过六个月并真实使用在生产交付的系统中所遇到的问题。

下一步

如果你的团队正在把 agent 放进真实业务,想了解 Flowness,或想聊企业 AI 落地怎么做,请在“联系我们”页写下行业和想解决的问题,我们按这些内容回复。 联系我们