79 个 Claude Code 子智能体如何共用工作目录
一次会话共启动 79 个子智能体,峰值并发为 27 个。团队用两个基于 mkdir 的目录锁串行处理可能冲突的写入,并约束子智能体执行会修改 Git 索引或历史的命令。
AI 深度解读
79 个 Claude Code 子代理共用一个 Git checkout,峰值 27 个同时在跑。作者团队靠任务分工、两把 mkdir 锁和一个统一提交的主会话,让这批代理在同一目录里改代码、跑测试、写数据。
这次实测最有参考价值的是他们怎么划分冲突。源码按任务分,可能覆盖彼此结果的数据写入排队,吃资源的检查单独排队。这个办法在一台 Mac 上跑了一晚,日志能说明代理怎么协作,至于排队花了多久、最后能否顺利提交,原文没有给出结果。
同一个目录里,哪些操作真会撞车?
Claude Code 的子代理默认从主会话的当前工作目录启动。在代理定义的 frontmatter 里加上 isolation: worktree,可以给它一个临时 Git worktree。作者所在仓库的所有者禁止用 worktree,最近一次确认是在 2026-11-11。那晚的代理共用一个 checkout,没有额外开分支,彼此的未提交修改随时可见。
团队 10 月曾让三个 Claude Code 会话共享同一个 checkout,还用 PreToolUse hook 拦下第 11 个同时运行的子代理。取消注册该 hook 的提交日期是 2026-11-04,此后任务说明不再设并发上限。2026-11-10 16:08 至 18:10 UTC,作者从子代理日志的时间戳、工作目录和 Bash 调用文本里数出 79 个子代理、一个工作目录、4,930 次 Bash 调用。峰值 27 是按每个代理的首尾日志时间算的,等锁或等消息的时间也算在内。

源码和文档靠任务说明划分修改范围。偶尔两个人要改同一份文档,Claude Code 的 Edit 工具如果发现文件自上次读取后变过,就会拒绝这次编辑。代理按约定重读再试。真正需要排队的是 state/ 下的 JSON Lines 文件。有些写入命令会先读入全部记录,改完再整份写回。两个进程如果读的是同一份旧内容,后写回的那个就可能抹掉前一个进程刚加的记录。
两把锁分别管数据写入和重任务
下面这三行把一次共享数据写入放进 ledger.lock 的保护范围。
until mkdir "$S/t2/ledger.lock" 2>/dev/null; do sleep 3; done
pnpm -s <command> <input.json>; rc=$?
rmdir "$S/t2/ledger.lock"; echo "exit=$rc"
第一行靠 mkdir 抢锁。同一路径的目录已经存在时,其他调用创建失败,每隔 3 秒再试。第三行用 rmdir 释放锁,并打印上一条命令的退出码。$S 指向仓库外的临时目录,锁目录不会出现在 git status 里。日志里有 24 个代理用过这把锁,共 98 次。其余 55 个代理没拿过这把锁,其中有 14 个评审和 2 个只读代理,它们的产出不会写入这些共享文件。
第二把 heavy.lock 用相同的方式排队,保护的是机器资源。仓库在一台 Mac 上做全量类型检查要 2 到 3 分钟,大批测试也差不多。任务说明要求类型检查和超过 10 个文件的测试先拿这把锁,全量测试套件留给主会话收尾时跑一次。17 个代理用了它,共 62 次。两把锁各自获取和释放,任务说明禁止嵌套,避免两个任务各持一把锁、互相等对方释放。
提交和任务回传怎么收口?
任务说明禁止子代理执行 git add、git commit、git stash、git checkout、git reset、git rebase 和 git push。作者扫描了 Bash 调用的命令位置,在统计窗口里没有发现这些命令被执行。主会话负责暂存和提交。如果同一文件里混有多个任务的改动,它会用仓库内的小工具列出差异块(hunk),只暂存改动行包含指定字符串的块。发稿时,最终提交还没完成,作者也就没有报告这套收尾到底有多顺。
另一处容易卡住的是结果回传。前两版稿子的两个评审都写出了评审文件,主调代理却收到「结束时未交付报告」的通知。读取约定的文件让工作继续了。Claude Code 2.1.321 修过自动模式压缩会话时丢失后台代理报告的问题,2.1.319 修过让代理误等自己既未启动也未接手的后台任务通知的问题。那晚用的是已包含两项修复的 2.1.322,这两次报告丢失的原因仍未查明。另有一次长命令在后台跑,代理一直等不到完成通知,团队后来改成让长命令在前台运行并等待结束。
我的判断
这套做法最容易复用的地方,是把锁放在具体的共享操作上。ledger.lock 保护的是一次完整的读、改、写。它能否生效,取决于每个写入入口是否都拿同一把锁。作者那晚主要靠任务说明约束代理。换到有定时任务、手工脚本和多个写入入口的团队,把锁放进共享写入工具里,会比让调用者各自记住三行命令更容易核查。能使用 worktree 的团队也可以用它隔开源码改动,但如果任务仍共用同一份外部状态文件,那个写入口照样需要协调。
锁的故障处理还有个缺口。持有者在 mkdir 成功后、rmdir 之前退出,后来者就可能一直等。主会话的监视器会标记日志 15 分钟没更新的代理,这能暴露卡住的等待者,却无法指出谁留下了锁。作者提到可以记录持有者身份,当晚还没实现。
这是一台 Mac、一个会话、一晚的记录。锁调用计数没有等待时长,27 也包含空等,最终提交结果尚未验证。用它来理解共享 checkout 的冲突处理,有具体操作和日志可看。若要据此判断吞吐量、并发上限,或它和 worktree 哪个更快,原文没给对照数据。
能拿来做什么
- 用 Claude Code 并行改前端代码时,在每个任务里写清可修改的文件范围,把
git add和提交集中到主会话。同一个文件混入多项任务的改动时,先按差异块核对,再暂存。 - 检查 Node 或
pnpm脚本是否会读入共享 JSON Lines 再整份写回。若有多个调用者,就在共享写入入口串行化整个读改写过程,并留下可查的锁持有者信息。 - 在本机同时跑多个代理时,给全量类型检查和大批测试安排单独的队列。需要调整排队门槛时,记录实际等待和运行时间,再看哪些命令适合并发。
- 给长期运行的代理任务约定可读取的产出文件。评审通知丢失时检查文件,长命令依赖的后台完成通知不稳定时,让代理在前台等到退出结果。