同时跑多个 AI 编程 Agent 并行改同一个仓库我最开始以为最难的是模型选型或者提示词设计真正上手后才发现最先崩掉的往往是 Git 工作区本身。Agent A 改到一半的未提交变更在 Agent B 眼里就是已有代码两个 Agent 各自为政一提交就把对方的工作覆盖了。我试过给每个 Agent 单独克隆仓库试过反复切分支也试过在同一个目录里硬排时间错开最后稳定落地的方案是 Worktrunk——一个面向并行 AI Agent 工作流的 Git Worktree 管理 CLI。Worktrunk 本质上是在 Git Worktree 能力之上加了一层编排管理它把同一个仓库按约定拆成多个独立工作目录每个目录对应独立分支和独立索引Agent 在各自隔离的目录里读写、编译、提交互不污染。它解决的核心问题很简单当一个仓库里同时有多个智能体在工作时怎么让它们的工作现场彼此隔离、又共享同一套 Git 对象库。它适合用 Claude Code、Codex CLI、Gemini CLI、Cursor 这类工具并行开发多个特性的个人开发者也很适合想让多分支并行开发变得有秩序的团队。这篇博文我会把 Worktrunk 解决的问题、命令设计、落地过程以及我实际跑并行 Agent 时踩过的坑一次说清楚。1. 并行 Agent 工作流中最先失控的是仓库而不是模型1.1 单工作区并行的真实灾难现场很多人对 AI Agent 编程的想象是给几个 Agent 各丢一个任务它们在同一个项目里各干各的最后合并完成。真实情况远比这血腥。有一次我在一个前端仓库里同时跑 Claude Code 和 Codex CLIClaude Code 正在改src/api/client.ts的接口定义Codex CLI 在另一个任务里已经基于旧接口写好了十几个调用点。等两边都开始格式化、跑测试的时候整个目录就是一场灾难——文件被来回覆盖未提交的变更搅在一起我甚至没法判断某个改动到底是谁写的。这类问题在只有一个工作目录的仓库里几乎无解因为 Git 分支本质上只是指针分支切换并不隔离工作区。你切到另一个分支时如果当前工作区还有未提交的修改轻则被带入新分支重则直接拒绝切换。对 AI Agent 来说它们不像人一样有先提交再切换的自觉几乎每个 Agent 都会在工作区里留下大量中间产物和半成品。1.2 为什么直接克隆仓库也不对我第一反应是给每个 Agent 单独克隆一份完整仓库效果确实解决了隔离问题但带来了三个新麻烦。第一是磁盘占用翻倍尤其是带node_modules的 Node 项目一个仓库动辄几个 GB克隆三份就要多花十多个 GB。第二是仓库之间的 remote 配置各管各的Agent 在某个克隆里改了代码另一个克隆什么都不知道我还得手动做跨仓库同步。第三是引用关系断裂每个克隆都是独立的世界Agent 看不到其他分支的演进脉络协作起来非常别扭。如果用 Git Worktree 就不一样了。Worktree 是 Git 原生功能它允许同一个仓库同时检出多个工作目录每个目录有自己独立的 HEAD、索引和工作区文件但共享同一个.git对象库。这意味着目录之间互不干扰Git 对象和压缩增量可以复用磁盘占用远低于多次克隆。Agent 在各目录里提交的代码仍然属于同一个仓库分支、引用、历史全部共享后续合并与代码审查完全透明。1.3 为什么还需要 Worktrunk 这一层既然 Git Worktree 本身就能做到隔离为什么还要一个 Worktrunk CLI因为原生命令太原教旨了在并行 Agent 场景下用起来非常啰嗦。每次创建 worktree 都要自己选目录名、分支名还要记挂哪棵 worktree 对应哪个分支几个 Agent 跑起来之后我经常忘记谁在哪个目录。更麻烦的是清理工作tree合并完分支以后手工删 worktree 再删分支是两套命令经常漏一个时间一长就攒下一堆僵尸 worktree。Worktrunk 做的是把这一堆重复操作收敛成几条约定命令。它把目录名、分支名、工作区状态这些信息统一管理起来并且给 AI Agent 输出结构化结果让 Agent 自己也能看懂当前工作台上有哪些并行工作区。2. Worktrunk 的设计思路与命令全景2.1 设计理念约定大于配置目录即工作台Worktrunk 有一个核心设计原则把所有工作区放在一个约定的根目录下比如~/worktrunks/。每次创建一个并行工作区它都自动生成一个语义清晰的目录名并以这个目录名作为分支的基础。比如你创建feat/api-refactorWorktrunk 就会自动创建目录~/worktrunks/feat/api-refactor并在仓库里建立一个同名分支feat/api-refactor同时把 HEAD 指向origin/main的最新提交。这样做的好处是不用在配置文件里维护任何映射关系——目录名、分支名、工作区名三者天然一致。这对 Agent 特别重要因为它只需要看一眼路径就知道自己在哪个工作区、在改哪个分支不需要额外的记忆或询问。我平时同时开三四个 Agent直接在终端里ls ~/worktrunks就能一目了然知道现在有哪些任务在进行。项目根目录下也可以放一个worktrunk.yml做基础配置配置项很少默认值就能覆盖绝大多数场景# worktrunk.yml workspace: ~/worktrunks # worktree 统一存放目录 base_branch: main # 新工作区默认基于哪个分支 default_install: pnpm install # 创建后是否自动装依赖 ignore: - .env* - node_modules - *.log2.2 核心命令init / create / list / attach / status / sync / pruneWorktrunk 把并行 Agent 场景里的高频操作拆成了几条命令命令不多但每个都对应一个真实痛点。worktrunk init初始化工作台创建 workspace 根目录并记录当前仓库。worktrunk create name为核心操作创建一棵新 worktree自动完成目录创建、分支创建、base 分支同步。worktrunk list列出所有工作树支持--json输出。worktrunk attach name切换当前终端的 注意力 到某个工作区打印该目录路径方便直接cd进去。worktrunk status name查看某个工作区相对 base 分支多了哪些提交、哪些未提交变更。worktrunk sync把 base 分支的最新提交同步到所有工作区内部做 rebase 或 merge按配置选择。worktrunk prune清理删除已合并分支对应的 worktree也可以带--merged自动识别。我在实际项目里最常用的组合只有四五个。创建并行工作区用worktrunk create切换视角用worktrunk attach干活之前看一眼全局用worktrunk list开发完一轮统一同步用worktrunk sync。工具只有足够简单Agent 才愿意用如果你让我在每次并行开发前配一堆参数我大概率用一两次就放弃了。2.3 输出要为 Agent 消费--json 与提示模板普通 Git 工具的输出是给人看的但 Worktrunk 的目标用户有一半其实是 AI Agent。所以在命令设计上它天然支持机器可读的输出格式。比如worktrunk list --json的输出大致长这样[ { name: feat/api-refactor, path: /home/user/worktrunks/feat/api-refactor, branch: feat/api-refactor, base: origin/main, status: clean }, { name: test/e2e-new, path: /home/user/worktrunks/test/e2e-new, branch: test/e2e-new, status: dirty } ]这看起来只是一个小细节实际价值很大。把这段 JSON 直接注入到 Agent 的 system prompt 里Agent 立刻就知道当前工作台有几个工作区、自己该在哪个目录工作、哪些目录有未提交变更、哪些可以做代码参考。我经常在一开始给 Claude Code 的提示词里附加这样一段这是当前项目的工作区地图 {worktrunk list --json 的输出} 你负责的工作区在 /home/user/worktrunks/feat/api-refactor。 你只能修改这个目录下的文件。 其他工作区只读不要跨目录改动。加上这段以后Agent 跑偏的概率明显下降。因为之前最头疼的就是一个 Agent 蠢蠢欲动地去改另一个 Agent 的文件有了明确的工作区边界它至少不会无意识地越界。3. 实操三 Agent 并行工作台从零搭建3.1 场景设定三个 Agent 同时动一个仓库我用一个真实场景完整走一遍流程。假设我有一个电商前端项目storefront需要同时完成三件事Agent A重构 API 请求层统一错误处理涉及src/api/。Agent B改造商品详情页前端组件涉及src/components/。Agent C补一套端到端测试覆盖新增的商品流程涉及test/e2e/。这三个任务互有耦合但不至于需要同时改同一个文件。最理想的方式就是每个 Agent 一个独立工作区。如果不用 Worktrunk我需要手工做三次git worktree add还要自己保证分支命名和目录命名一致比较繁琐。用 Worktrunk 之后流程非常固定。3.2 初始化仓库并快速创建三个 Worktree首先进入项目仓库执行初始化cd ~/storefront worktrunk init --workspace ~/worktrunks接着创建三个并行工作区worktrunk create feat/api-refactor worktrunk create feat/product-detail-redesign worktrunk create test/e2e-new-product每条create命令执行时Worktrunk 会自动做以下事情基于origin/main创建本地分支、在~/worktrunks/下建立目录、把当前 HEAD 检出到该目录、如果有default_install配置就自动装一次依赖。创建完成后worktrunk list会直接显示三个工作区及对应状态。实际使用中有一点要注意三个工作区如果都从同一个origin/main创建它们的起点是完全一致的这是并行开发的理想状态。如果 A 工作区先完成了一部分公共改动B 想基于 A 的最新进度继续可以等 A 提交并推送后在 B 里执行worktrunk sync feat/api-refactor把指定工作区同步进来。Worktrunk 的sync命令支持指定来源工作区灵活性比无脑同步到 latest 高很多。3.3 给每个 Agent 下发工作区边界创建好三个目录之后我的启动命令一般是这样的cd ~/worktrunks/feat/api-refactor claude-code --allowedTools Bash,Edit,Write另一个终端cd ~/worktrunks/feat/product-detail-redesign codex第三个终端cd ~/worktrunks/test/e2e-new-product gemini每个 Agent 启动后我会在 prompts 里明确告诉它你的工作目录在哪个路径、需要改哪些模块、不许碰哪些模块。这里最需要注意的是依赖的独立性问题。每个 worktree 虽然是同一个仓库但node_modules不会自动共享实际上也不应该共享所以如果创建时没有自动安装依赖记得在每个工作区里手动跑一次安装命令。这也是为什么我在worktrunk.yml里配置了default_install就是为了省掉反复安装依赖的体力活。Agent 开始工作之后我每个小时做一次巡检worktrunk status看每个工作区是否有异常提交git -C ~/worktrunks/feat/api-refactor log --oneline main..HEAD看它到底改了多少东西。巡检不需要很频繁因为 Agent 通常会自动循环执行 编辑-编译-测试太频繁反而打断节奏。3.4 并行开发中的同步与收尾三个 Agent 各自提交了几个版本之后我一般在每个 Agent 完成一个稳定的里程碑时做一次集中整合顺序很重要先把 main 分支更新到最新然后从优先级最低的工作区开始逐个worktrunk sync最后统一解决冲突。git checkout main git pull origin main worktrunk sync如果某个工作区在同步时出现 rebase 冲突我会让对应的 Agent 去解决而不是自己手动改。实际上 Claude Code 这类工具在冲突处理上已经相当顺手了你只要告诉它你的分支在 rebase 之后出现了冲突请解决冲突并保持原功能逻辑它就能自己去读冲突标记、保留合适的代码。我在好几次并行开发里都是这么干的效果反而比我自己手工解冲突更快。任务全部完成之后清理工作区也只是一条命令的事情。如果三个功能分支都已经合并回 main直接执行worktrunk prune --merged它会自动删掉所有已合并的 worktree 目录和对应分支整个环境回到干净状态。以前我手工做这一步经常漏掉一两个 worktree现在一条命令搞定磁盘空间也不会被幽灵目录吃干。4. 并行环境下的典型故障与排查实录4.1 引用锁与 index.lock 冲突多 Agent 并行最典型的故障就是某个工作区报fatal: Unable to create /path/to/repo/.git/index.lock: File exists。这个错误几乎都是因为两个 Git 进程同时尝试写同一个仓库的索引。虽然 worktree 的工作目录互相独立但它们毕竟共享同一个.git某些全局操作比如 fetch、gc同时跑起来还是可能发生锁冲突。我的处理方式很朴素先检查是不是有残留的index.lock文件确认没有其他 Git 命令在跑之后直接删掉它rm -f .git/index.lock更好的办法是预防。给所有 Agent 统一设定一条约束不要同时执行会修改全局引用的大操作。比如不要在三个工作区里同时跑git fetch --prune也不要在同一时刻多端并行 push 同一条分支。更重要的是在worktrunk.yml里可以开启串行全局操作让 worktree 级别的 fetch 自动排队虽然会让某些操作轻微变慢但换来的稳定性非常值。4.2 分支重名与 worktree 目录残留另一个高频踩坑点是创建同名工作区。比如你已经创建过feat/api-refactor后来忘了再次执行worktrunk create feat/api-refactorGit 会直接报 branch already exists 或 worktree already exists。Worktrunk 在创建前会做重名检查但如果跨项目、跨机器协作还是可能碰到旧的 worktree 记录残留在.git/worktrees/里的情况。如果遇到这类残留用git worktree prune清理元数据之后再执行 Worktrunk 的 create 命令。我自己的习惯是给新建工作区加一个日期标识比如feat/api-refactor-0612这样即使重名失败也能看出哪个是旧的、哪个是新的。4.3 磁盘耗尽与依赖安装的隐性问题磁盘问题在并行场景下最容易被低估。一个 Node 项目的node_modules可能占好几个 GB三个 worktree 各装一份依赖加上.git对象库本身的膨胀磁盘说满就满。我经历过一次最惨的三个 Agent 同时跑测试产物文件疯狂增长最后磁盘 100% 写满所有 Agent 一起崩溃重启都没用。现在的预防措施是三层第一在 workspace 根目录外用一个脚本定期清理node_modules/.cache、dist、coverage这类可再生的产物目录第二给 Worktrunk 配置 ignore 列表避免产物文件被提交第三在工作区目录下尽量用 pnpm 的 content-addressable 存储它能跨 worktree 复用依赖文件比 npm 省太多空间。如果项目允许也可以让多个 worktree 共享一个node_modules前端的 monorepo 配合 symlink 能做但配置成本偏高不是所有项目都值得。4.4 常见问题速查表症状可能原因处理方式index.lock报错多个 Git 全局操作同时写 .git确认无运行任务后删除锁文件并开启串行全局操作create 提示 branch/worktree 已存在命名冲突或残留元数据用git worktree prune清理并改用带日期的新名称sync 时出现大量冲突base 分支改动过大或 Agent 越界改文件手动/交给 Agent 解冲突并给 Agent 更严格的文件边界磁盘空间突然打满依赖与产物文件在各 worktree 重复清理缓存目录改用 pnpm让 ignore 配置生效branch 提交记录飘了Agent 把分支 base 指错用worktrunk attach name回到正确工作区rebase 回 base 分支这五类问题基本覆盖了并行 AI Agent 开发中 90% 的 Git 层故障。值得一提的是很多故障的根源其实是工作区边界没定好Agent 越界修改了共享文件。我后来把项目里最容易被多个 Agent 同时触碰的文件比如全局类型定义、公共组件入口单独放在一个只读区并在 Agent 提示词里明确禁止修改这类问题就明显变少了。5. 把 Worktrunk 嵌入已有 Agent 工作流的几个经验5.1 在系统提示词里注入工作区地图很多人会低估 system prompt 里环境信息的价值。给 Agent 一段worktrunk list --json的输出它相当于给 Agent 一张项目布局图。我实际用的注入模板大致是这样当前有多个并行 Agent 工作区 - /home/user/worktrunks/feat/api-refactor (feature/api-refactor) - /home/user/worktrunks/feat/product-detail-redesign (feat/product-detail-redesign) - /home/user/worktrunks/test/e2e-new-product (test/e2e-new-product) 你的任务只与 /home/user/worktrunks/feat/api-refactor 相关。 所有文件修改必须发生在这个目录下。 不要读取或修改其他工作区的文件。 如果发现你需要参考其他工作区接口请先输出你的理解并等待确认。加了这个上下文之后Agent 的路径意识和权限意识会明显增强。我在实际使用中明显感觉到它不会再凭感觉从仓库根目录找文件也不会突然去改一个本不该它动的文件。对需要同时在多个 Agent 之间做并行上下文协作的场景这一步几乎是刚需。5.2 用包装脚本统一 Agent 的启停流程Worktrunk 本身是命令但实际使用中你会发现还需要一个启动 Agent 并绑定工作区的统一入口。我写了一个非常薄的 shell 包装脚本内容大致是#!/usr/bin/env bash workspace_name$1 shift case $1 in start) worktrunk attach $workspace_name cd $(worktrunk status --path $workspace_name) echo 当前工作区: $workspace_name echo 目录: $(pwd) ;; stop) # 先把未提交变更的摘要记录下来方便后续恢复上下文 worktrunk status --json $workspace_name echo Agent 会话已结束工作区保留。可随时用 start 恢复。 ;; esac这个脚本解决了一个实际问题每个 Agent 工作区就是一个长期存在的目录你不需要每次重新建直接start进去接着之前的上下文继续开发。因为 worktree 里的未提交变更会一直保留着Agent 下次启动时就能读到之前的进度整个工作流非常有连续性。5.3 密钥管理与清理习惯最后说一个很容易翻车的细节多工作区并行会让你的.env文件散落得到处都是。X Agent 在第一个工作区配置了密钥Y Agent 在第二个工作区又需要同一套配置。我的经验是不要在多个 worktree 里手动维护多份.env那样迟早会出现环境变量不一致导致的诡异问题。建议的做法是在worktrunk.yml的ignore配置里统一忽略.env*然后创建 worktree 之后用一个脚本从安全的本地目录复制一份统一下发的.env到新工作区。这样既保证所有 Agent 的环境一致又避免密钥被意外提交。Worktrunk 本身不做密钥管理但它的 ignore 机制让你在并行环境下管密钥不至于失控。清理习惯也值得刻意培养。我每个迭代结束都会执行一次完整的worktrunk prune --merged再定期检查一下.git/worktrees/目录有没有多余的记录。别小看这个动作它直接决定了工作台从逐渐混乱还是始终保持整洁。我见过不少人用 Git 用得漂亮却在 worktree 滥用之后让仓库变成一团浆糊。个人经验里还有一个很实用的小技巧给 worktrunk 设置一个短别名wt然后在worktrunk list输出的路径里直接用一个终端窗口常驻显示。每次给 Agent 派完任务我瞄一眼列表就知道现在几个工作区在跑、各自状态如何。这种全局可见性在并行 Agent 开发里非常重要它让你在任何时候都能快速回答现在有哪些 Agent 在动我的代码这个问题。Worktrunk 对我最核心的价值也正在于此它让并行 AI Agent 协作从过家家式的各自乱改变成了有边界的工业化协同。