前两天下午我差点把仓库搞成一锅粥AI coding agent 帮我改支付模块我自己同时手头在改优惠券模块两边都在同一个工作区里动代码。agent 一抬手把同事的改动格式化了一遍我又顺手把 agent 的提交覆盖了等发现的时候git diff已经乱到根本看不出谁改了什么。那之后我认真研究了一件事怎么在 AI 编程时代给并行开发上一道物理隔离——答案就是我以前一直没用上的 Git Worktree。Git Worktree 不是个新功能但配合 AI Coding Agent 之后它变成了我目前最离不开的开发基础设施。它解决的核心问题很朴素一份仓库多个互不干扰的工作目录每个目录各自 checkout 一个分支。AI agent 在里面随便造、随便试、随便提交都不会碰脏你手上正在改的代码。这篇文章我会从原理讲到实战把我自己用 Worktree 组织多个 AI agent 并行开发的完整流程、命令和踩坑记录都过一遍适合正在用 Cursor、Claude Code、GitHub Copilot 这类工具、又怕它们乱改代码的人。1. AI 编程时代为什么我重新拾起 Git Worktree在讲命令之前我想先把为什么要用这件事说透。如果你没有被 AI agent 坑过可能体会不到我下面说的这些痛。1.1 单工作区的三个典型混乱场景先说场景。以前我不开 Worktree 的时候所有活儿都在同一个目录下干AI agent 也在这个目录下干活于是反复出现三类问题。第一类是改动互相覆盖。我正在某个文件里手改逻辑agent 根据它的理解在同一文件里做了完全不同的改动两个人都没留意对方的版本一保存总有一个人的劳动成果没了。这类冲突在 AI coding 时代特别常见因为 agent 执行任务时往往会顺手优化附近代码我明明只让它改一个函数它能给你把整个文件格式化一遍。第二类是构建和测试状态被污染。我用 Cursor 让 agent 帮我调一个 bugagent 跑了一遍测试顺带改了配置还生成了调试用的临时文件。我手头的另一项工作正常跑测试时莫名其妙挂掉了查了半天才发现是 agent 留下的环境状态问题。单工作区模式下agent 的实验和我的生产挤在一起谁都没法对当前环境负责。第三类是并行任务根本没有并行。我又想让 agent 做 A 功能又想自己同时做 B 功能但是在单工作区里要么我把代码提交了再让 agent 接手要么 agent 改到一半我插一脚两边互相等待、互相干扰。后来我尝试在同一个仓库里靠git stash和git checkout切来切去切一次跑一次构建动辄一两分钟起步一天下来时间全耗在等编译上了。1.2 为什么传统分支切换解决不了 AI 场景有人可能会说你开个新分支不就行了git checkout -b feature/xxx谁不会。问题在于切换分支会改变当前工作区的文件内容。你让 AI agent 开一个新的 feature 分支干活AI 改到一半你想切回 main 分支查个东西这时候要么提交它没写完的半成品要么 stash 起来——而 stash 一堆 agent 产生的东西过两天你根本不知道哪是哪。更难受的是 IDE 和终端。你在 Cursor 里打开了一个项目目录这个目录天然绑定在一个分支上。你想同时开两个 agent一个在 main 分支上看代码一个在 feature/xxx 分支上改代码单工作区根本做不了这件事你只能开两个窗口分别 clone 一份仓库。clone 的方案我试过很笨两份仓库各自要单独拉远程、单独同步做完改动还得记得推送来推送去AI agent 在一份 clone 里提交了代码我在另一份 clone 里根本看不见得先git fetch才能看到。1.3 Worktree 的一句话说清Worktree 的核心价值就一句话一份仓库、多份工作目录、同一个 .git 对象库每个目录对应一个分支互不干扰。你不再需要 clone 多份仓库也不再需要靠 stash 或者半成品提交来切换任务。每个目录里git status只反映那个目录自己的状态git commit提交后对象库全局共享你在任何工作目录里都能看到这个提交。就是把多仓库各搞各的变成了一个对象库、多个入口同步成本直接归零。这也正是 AI coding agent 的场景最需要的agent 天然就是一个独立的、随时可能乱来的同事给它一个隔离的工作目录比给它在你的主工作区旁边划一片虚拟区域要安全得多——物理隔离永远比逻辑隔离可靠。2. Worktree 的原理一份 .git、多份工作区理论层面的东西我不打算讲得很深但有一个关键概念必须弄明白为什么 Worktree 能做到共享但隔离。理解了它后面遇到诡异报错时你才能一眼定位。2.1 普通 Git 仓库的工作机制回顾一个普通 Git 仓库结构上大致是这样.git/目录存放对象库、引用、HEAD、index 等所有元数据而工作目录里的文件则是当前分支在某个提交上的实物形态。HEAD指向当前分支index暂存区记录你准备提交的内容对象库所有 commit、tree、blob 数据当你执行git checkout feature/xxx时Git 做的事是把 HEAD 切到 feature/xxx 分支然后根据该分支指向的 commit重新生成工作目录里的文件内容。在同一时刻一个仓库只有一个工作目录、一个 HEAD、一个 index。这就是在同一个目录下没法同时待两个分支的根本原因。2.2 Worktree 做了什么改造git worktree add做的事情本质上是给同一个仓库创建了第二个工作目录并且在这个新目录里生成了独立的 HEAD 和独立的 index但复用同一个对象库。用命令看一下实际结构$ git worktree add ../my-app-agent -b feature/order-refactor Preparing worktree (new branch feature/order-refactor) HEAD is now at a3f2c91 Merge pull request #112 $ ls .git/worktrees/ my-app-agent/打开.git/worktrees/my-app-agent/目录你会发现里面有HEAD、index、commondir这几个关键文件。commondir指向主仓库的.git目录——这就是共享对象库的桥梁。新目录里执行git log、git commit时读写的是同一个对象库但git status、git add看到的是各自目录自己的 index 和 HEAD 状态。用生活化的方式理解这就像两个人合租同一套房但各有各的房间门锁。公共区域对象库里的 commits是共享的你买了台冰箱放在客厅室友能看到也能用但各自房间工作目录和暂存区怎么布置互不干扰。你要进室友的房间得经过他自己的门Git 不会允许你俩同时占着同一个房间。2.3 和 clone、复用工具相比的根本差异我在前面提到过复制一份仓库的笨办法。这里把两种方案放到一张表里对比就一清二楚了对比项git worktree多份 git clone对象库共享同一个.git提交全局可见各自独立需要 push/fetch 同步本地分支所有分支共享切一个分支即可各自维护引用容易不同步新增目录一条命令秒建需要完整 clone 历史慢且占空间磁盘占用新增工作目录不复制历史仅文件对象增量每份 clone 都带全量历史用完清理git worktree remove一条命令删除后可能出现落后引用实际用下来多份 clone 的同步成本是隐性黑洞agent 在 A 仓库推了分支你在 B 仓库要git fetch才知道两个仓库的 remote 配置还可能不一样。Worktree 则完全不需要考虑这事所有本地分支天然就在一个命名空间里。另外补一句git worktree早在 Git 2.5 版本就发布了不是实验性功能。很多老开发者没用它是因为觉得单仓库够用但 AI 时代的并行开发强度把它的价值明显放大了。3. 基础命令实战创建、切换、提交与清理接下来是实操部分。我会把一套最常用的命令流程按从生到死的顺序走一遍尽量把命令背后的意图也讲清楚。3.1 创建 Worktree只要一条命令我常用的创建姿势是# 在仓库根目录执行 $ git worktree add ../shop-api-agent-order -b feature/order-refactor这条命令做了什么第一步在当前仓库所在目录的上一级..建一个名为shop-api-agent-order的文件夹第二步从当前 HEAD 创建一个名为feature/order-refactor的新分支第三步把新分支 checkout 到新目录里。目录名和分支名建议直接对应这样看到目录就知道这个工作区在做什么任务。我个人的命名习惯是仓库名-agent-任务名比如shop-api-agent-order、shop-api-agent-payment。如果你不想创建新分支而是想在已有分支上开一个工作区把-b去掉就好# 在已有的 develop 分支上开一个工作区不新建分支 $ git worktree add ../shop-api-develop develop还有一个小技巧如果你的某个分支正被 main 工作区占用但你只是想看看代码、不准备改可以加--detachgit worktree add --detach ../shop-api-temp main。这样会创建一个处于 detached HEAD 状态的临时工作区用于查看代码而不影响分支本身。3.2 查看和管理git worktree list任何时候用git worktree list都能看到当前仓库下所有工作区$ git worktree list /Users/me/code/shop-api a3f2c91 [main] /Users/me/code/shop-api-agent-order 612bd43 [feature/order-refactor] /Users/me/code/shop-api-agent-payment 8d2f01a [feature/payment-refactor]输出信息很直观路径、当前提交、所在分支。我一般会在开始一天的工作前跑一下git worktree list确认哪些任务的工作区还开着、哪些已经用完可以清掉。这不只是查看工具更是任务管理面板。3.3 在 Worktree 里提交修改和普通仓库完全一样这里要单独回应一下很多人搜的git worktree 如何提交修改——在 Worktree 里提交修改和你在普通仓库里提交修改的操作完全一致没有任何特殊命令。# 进入 worktree 目录 $ cd ../shop-api-agent-order # 查看此工作区自己的状态 $ git status # 添加和提交与普通仓库一致 $ git add . $ git commit -m refactor: 重构订单模块的状态机 # 推送到远程分支 $ git push -u origin feature/order-refactor唯一要记住的心理模型是你当前在哪个工作区目录下git 命令操作的就是哪个工作区的内容。比如你在主工作区shop-api里执行git status看到的是 main 分支的状态在shop-api-agent-order里执行git status看到的则是 feature/order-refactor 分支的状态。两者互不干扰你甚至可以同时开着两个终端分别对两个工作区执行git status。提交之后在任意一个工作区里执行git log --all --oneline --graph都能看到这条新提交——这就是共享对象库带来的好处。你不需要手动同步所有工作区共享同一套提交数据。3.4 清理 Worktree用完要收拾任务完成后清理分三步# 1. 从主仓库里移除 worktree 的工作目录 $ git worktree remove ../shop-api-agent-order # 2. 删除对应的本地分支如果它已经被合并 $ git branch -d feature/order-refactor # 3. 清理失效的 worktree 元数据一般 remove 后会自动清理但手动 prune 更安心 $ git worktree prune注意一点git worktree remove默认只允许删除没有未提交改动的工作区。如果 agent 在目录里留下了未提交的代码会报fatal: ... contains modified or untracked files。这时候你需要在对应工作区里先把改动处理掉提交、stash 或丢弃再回来 remove。也可以用--force强制删除但我会谨慎使用——强制删除等于直接把 agent 的现场销毁万一里面有你要的东西就找不回来了。4. 在 AI Agent 工作流中落地 Worktree 的完整方案这一节是整篇文章的核心。基础命令只是工具真正有价值的是把它们组织成一套可复用的 AI 并行开发工作流。4.1 目录与任务规划一个任务一个分支一个工作区我的推荐模型是一个任务对应一个分支、一个 worktree、一个 agent 会话。假设现在接到了三个任务任务 A重构订单模块的状态机任务 B修复支付回调的超时 bug任务 C给优惠券模块补充单元测试我会先把分支和工作区一次性建好$ git worktree add ../shop-api-agent-order -b feature/order-refactor $ git worktree add ../shop-api-agent-payment -b fix/payment-timeout $ git worktree add ../shop-api-agent-coupon -b test/coupon-unittest然后分别打开三个 Cursor 窗口 / 三个 Claude Code 会话每个会话的 workspace 指到对应的 worktree 目录。这样做的直接好处是agent 之间的上下文完全隔离不会出现 agent A 看到的代码里混着 agent B 的未提交改动。尤其注意一点AI coding agent 的上下文理解能力很强但它的视野完全取决于你给它的目录。在同一个目录里开两个 agent它们会互相看到对方的半成品代码然后基于错误的上下文给出错误建议。用 Worktree 分开之后agent 的世界里只有这个任务、这个分支干扰降到最低。4.2 完整操作演练从接任务到合并下面用一个具体例子走完从任务下发到合并的完整流程。第一步确认基线在创建 worktree 之前先确认主仓库的 main 分支是最新的并且你自己手上没有未提交的改动。这个顺序很重要因为 worktree 是从当前 HEAD 拉出来的如果 main 是旧状态后续合并时会出现一堆无谓冲突。$ git checkout main $ git pull origin main第二步创建 worktree 并初始化环境$ git worktree add ../shop-api-agent-order -b feature/order-refactor $ cd ../shop-api-agent-order进入目录后根据项目类型安装依赖。这里有一个容易踩的坑依赖目录要么单独安装要么做共享缓存。如果项目是 Node.js每个 worktree 里跑一遍npm install会多占几百 MB 磁盘如果是 Python 项目每个目录建一个 venv 也同样浪费。这部分我在第五节详细展开这里先按常见做法来。第三步给 agent 下发任务我给 agent 的 prompt 通常会包含三部分信息工作目录限定明确告诉它只允许修改当前工作区目录下的文件任务目标具体要完成什么提交约束完成任务后用哪种格式提交一个典型示例请在这个项目中完成任务 - 工作区目录/Users/me/code/shop-api-agent-order - 任务重构订单模块的状态机。当前的 order state machine 代码在 src/order/stateMachine.js请把 if/else 模式改为状态表驱动模式。 - 要求不要修改其他模块的代码完成后运行 npm test 确保现有测试通过通过后提交到当前分支提交信息为 refactor: order state machine to table-driven pattern第四步agent 提交后人工审核agent 完成提交后我在主工作区或任意一个目录里执行$ git fetch origin $ git log main..feature/order-refactor --oneline看到 agent 的提交记录清晰独立地在 feature 分支上后再执行$ git diff main...feature/order-refactor --stat审核改动是否合理。这一步我强烈建议不要跳过即使 agent 说测试全过了你也至少要看一遍关键文件的 diff。AI 写代码的能力已经很强但它对于项目的长期架构约束理解仍然有限。第五步合并与清理审核没问题后合并并清理$ git checkout main $ git merge --no-ff feature/order-refactor $ git push origin main # 回到主仓库移除 worktree 和分支 $ git worktree remove ../shop-api-agent-order $ git branch -d feature/order-refactor $ git worktree prune4.3 为什么不建议 agent 直接在主工作区干活的最后提醒如果你真的遇到没有时间建 worktree、直接让 agent 改完算了的情况我的建议是把git status里的改动总量当成风险评估指标。假如 main 工作区里有你自己未提交的改动agent 一进来就 add/commit它会把你的改动也卷进去——很多agent 把我的代码提价了的惨案就是这么发生的。Worktree 这套流程的本质是先划边界、再放 agent 进来干活。边界有了agent 怎么折腾都是安全的。这套思路同样适用于你自己如果你手上已经有一个分支在工作又需要临时查看另一个分支的代码直接git worktree add一个临时目录即可不用 stash、不用打扰当前工作区。5. 我踩过的坑Worktree 与 Agent 配合的注意事项最后一部分我把自己在实际使用中确实踩过的坑列出来这些坑不是文档里会写的但对工作效率影响巨大。5.1 同一个分支不能开两个 worktree这个报错来自 Git 本身的设计$ git worktree add ../shop-api-agent-order-2 feature/order-refactor fatal: feature/order-refactor is already checked out at /Users/me/code/shop-api-agent-order原因是 Git 不允许同一个分支在多个 worktree 中同时被 checkout。这个设计是对的如果两个工作区都指向同一个分支它们各自基于不同的 index 提交分支就会混乱。但这在实际工作中经常造成困扰尤其是当你想再开一个临时工作区看看 feature 分支的代码时。解决办法是用--detach或者老老实实基于当前 HEAD 新建另一个分支。5.2 依赖安装和缓存隔离磁盘空间与行为差异这是我最开始忽略、后来花了很多时间处理的问题。以 Node.js 项目为例我给三个任务建了三个 worktree然后分别npm install结果磁盘爆增了几个 G构建时间也成倍拉长。后来我的做法是共享缓存目录。具体来说Node.js设置npm config set cache /path/to/shared/.npm-cache或者用 pnpm 的全局 store。这样每个 worktree 安装依赖时软链接复用同一份内容寻址存储磁盘占用大幅下降。Python用 virtualenv 时直接让每个 worktree 共用同一个 venv注意路径兼容问题或者使用uv这类工具的全局缓存。前端构建缓存Webpack/Vite 的缓存目录可以单独指定到共享路径避免每个 worktree 都重新跑一遍完整构建。另外一个容易被忽略的点构建脚本里如果有硬编码的绝对路径worktree 换个目录后行为会不一样。agent 在 worktree 里跑出的构建产物跟主目录不一致你排查半天最后发现问题出在路径上是很常见的事。5.3 agent 跨工作区乱跑必须在 prompt 里锁定目录我遇到过最恼火的情况明明给 agent 开了独立的 worktree它却自动识别到了仓库根目录跑去看了其他模块的代码甚至把参考代码当成待改代码改了。AI coding agent 的上下文里工作目录往往是通过 IDE 打开的根目录决定的。如果你把 agent 当独立机器人用比如 Claude Code 的 CLI 模式它会基于当前所在目录来判断代码库范围。我的经验是在 agent 的 system prompt 或任务 prompt 里明确写上只修改 /absolute/path/to/worktree 目录下的代码给 agent 下发任务时不在仓库根目录启动命令而是 cd 到目标 worktree 再启动如果 agent 有只在当前工作区修改的配置选项务必打开5.4 忘记清理 worktree 导致的陈旧分支堆积时间一长git worktree list会越来越长堆了一堆用完没删的目录。这些目录本身不占太多空间但它们对应的文件在磁盘上是真实存在的而且如果里面还挂着 agent 跑完的 node_modules占用就大了。我现在的习惯是任务合并完成后立刻执行清理三步曲不让它过夜。如果确实想保留现场一段时间至少把git worktree list的输出在笔记软件里记一笔标注清楚哪个目录对应哪个任务。5.5 worktree 里执行 pull/merge 时要注意方向很多从主工作区养成的肌肉记忆在 worktree 里会出问题。比如有人在 worktree 里执行git pull origin main发现一堆冲突——因为当前 worrk tree 的分支是 feature/xxx拉取 main 进来自然要合并。这本身没问题但要注意你合并的是 main 到 feature不是 feature 到 main。方向搞反会造成 feature 分支里出现一堆 main 的历史review 的时候会非常痛苦。我推荐的流程是所有把所有分支更新到最新的操作都放在主工作区做。主工作区git pull origin main拉取默认分支更新其他 worktree 的任务分支不动等 feature 分支需要同步 main 的新改动时再单独执行。5.6 一个小技巧用脚本一键创建带 worktree 的任务环境建 worktree 的命令本身不长但加上依赖安装、目录命名、提示信息输出每次都手敲还是挺烦的。我自己写了一个简单脚本核心逻辑是这样#!/bin/bash # 用法: new-agent-task.sh 分支名 任务名 BRANCH$1 TASK$2 WORKTREE_PATH../shop-api-agent-${TASK} git worktree add $WORKTREE_PATH -b $BRANCH cd $WORKTREE_PATH npm install echo ✅ Agent 工作区已就绪: $WORKTREE_PATH (branch: $BRANCH)你完全可以根据自己的项目类型调整Java 项目就是 mvn 编译Python 项目就是建 venv。这没什么技术含量但能显著减少重复操作尤其当你同时开着三四个 agent 任务的时候。6. 我的一点心得Worktree 让 AI 编程从提心吊胆变成放心委托这套工作流跑了大概两个月后我最大的感受是心理负担完全不一样了。以前让 agent 改代码我总要在旁边盯着它每提交一次我都要审查一次当前工作区的状态生怕它把别的改动卷进去。现在我把 agent 放进独立的 worktree告诉它这是你的地盘、你随便改、改完提交到你的分支它提交完我再整体 review 一次 diff质量和效率都提升了不少。给还在犹豫的人一个建议先从最简单的场景开始——你正在 main 分支上改代码突然需要让 agent 帮忙修一个紧急 bug别在同一个目录里改git worktree add ../project-hotfix -b fix/xxx建一个隔离目录让 agent 进去干完事直接合并。试过一次你就再也不想回到单工作区硬扛 AI的状态了。
前两天下午我差点把仓库搞成一锅粥AI coding agent 帮我改支付模块我自己同时手头在改优惠券模块两边都在同一个工作区里动代码。agent 一抬手把同事的改动格式化了一遍我又顺手把 agent 的提交覆盖了等发现的时候git diff已经乱到根本看不出谁改了什么。那之后我认真研究了一件事怎么在 AI 编程时代给并行开发上一道物理隔离——答案就是我以前一直没用上的 Git Worktree。Git Worktree 不是个新功能但配合 AI Coding Agent 之后它变成了我目前最离不开的开发基础设施。它解决的核心问题很朴素一份仓库多个互不干扰的工作目录每个目录各自 checkout 一个分支。AI agent 在里面随便造、随便试、随便提交都不会碰脏你手上正在改的代码。这篇文章我会从原理讲到实战把我自己用 Worktree 组织多个 AI agent 并行开发的完整流程、命令和踩坑记录都过一遍适合正在用 Cursor、Claude Code、GitHub Copilot 这类工具、又怕它们乱改代码的人。1. AI 编程时代为什么我重新拾起 Git Worktree在讲命令之前我想先把为什么要用这件事说透。如果你没有被 AI agent 坑过可能体会不到我下面说的这些痛。1.1 单工作区的三个典型混乱场景先说场景。以前我不开 Worktree 的时候所有活儿都在同一个目录下干AI agent 也在这个目录下干活于是反复出现三类问题。第一类是改动互相覆盖。我正在某个文件里手改逻辑agent 根据它的理解在同一文件里做了完全不同的改动两个人都没留意对方的版本一保存总有一个人的劳动成果没了。这类冲突在 AI coding 时代特别常见因为 agent 执行任务时往往会顺手优化附近代码我明明只让它改一个函数它能给你把整个文件格式化一遍。第二类是构建和测试状态被污染。我用 Cursor 让 agent 帮我调一个 bugagent 跑了一遍测试顺带改了配置还生成了调试用的临时文件。我手头的另一项工作正常跑测试时莫名其妙挂掉了查了半天才发现是 agent 留下的环境状态问题。单工作区模式下agent 的实验和我的生产挤在一起谁都没法对当前环境负责。第三类是并行任务根本没有并行。我又想让 agent 做 A 功能又想自己同时做 B 功能但是在单工作区里要么我把代码提交了再让 agent 接手要么 agent 改到一半我插一脚两边互相等待、互相干扰。后来我尝试在同一个仓库里靠git stash和git checkout切来切去切一次跑一次构建动辄一两分钟起步一天下来时间全耗在等编译上了。1.2 为什么传统分支切换解决不了 AI 场景有人可能会说你开个新分支不就行了git checkout -b feature/xxx谁不会。问题在于切换分支会改变当前工作区的文件内容。你让 AI agent 开一个新的 feature 分支干活AI 改到一半你想切回 main 分支查个东西这时候要么提交它没写完的半成品要么 stash 起来——而 stash 一堆 agent 产生的东西过两天你根本不知道哪是哪。更难受的是 IDE 和终端。你在 Cursor 里打开了一个项目目录这个目录天然绑定在一个分支上。你想同时开两个 agent一个在 main 分支上看代码一个在 feature/xxx 分支上改代码单工作区根本做不了这件事你只能开两个窗口分别 clone 一份仓库。clone 的方案我试过很笨两份仓库各自要单独拉远程、单独同步做完改动还得记得推送来推送去AI agent 在一份 clone 里提交了代码我在另一份 clone 里根本看不见得先git fetch才能看到。1.3 Worktree 的一句话说清Worktree 的核心价值就一句话一份仓库、多份工作目录、同一个 .git 对象库每个目录对应一个分支互不干扰。你不再需要 clone 多份仓库也不再需要靠 stash 或者半成品提交来切换任务。每个目录里git status只反映那个目录自己的状态git commit提交后对象库全局共享你在任何工作目录里都能看到这个提交。就是把多仓库各搞各的变成了一个对象库、多个入口同步成本直接归零。这也正是 AI coding agent 的场景最需要的agent 天然就是一个独立的、随时可能乱来的同事给它一个隔离的工作目录比给它在你的主工作区旁边划一片虚拟区域要安全得多——物理隔离永远比逻辑隔离可靠。2. Worktree 的原理一份 .git、多份工作区理论层面的东西我不打算讲得很深但有一个关键概念必须弄明白为什么 Worktree 能做到共享但隔离。理解了它后面遇到诡异报错时你才能一眼定位。2.1 普通 Git 仓库的工作机制回顾一个普通 Git 仓库结构上大致是这样.git/目录存放对象库、引用、HEAD、index 等所有元数据而工作目录里的文件则是当前分支在某个提交上的实物形态。HEAD指向当前分支index暂存区记录你准备提交的内容对象库所有 commit、tree、blob 数据当你执行git checkout feature/xxx时Git 做的事是把 HEAD 切到 feature/xxx 分支然后根据该分支指向的 commit重新生成工作目录里的文件内容。在同一时刻一个仓库只有一个工作目录、一个 HEAD、一个 index。这就是在同一个目录下没法同时待两个分支的根本原因。2.2 Worktree 做了什么改造git worktree add做的事情本质上是给同一个仓库创建了第二个工作目录并且在这个新目录里生成了独立的 HEAD 和独立的 index但复用同一个对象库。用命令看一下实际结构$ git worktree add ../my-app-agent -b feature/order-refactor Preparing worktree (new branch feature/order-refactor) HEAD is now at a3f2c91 Merge pull request #112 $ ls .git/worktrees/ my-app-agent/打开.git/worktrees/my-app-agent/目录你会发现里面有HEAD、index、commondir这几个关键文件。commondir指向主仓库的.git目录——这就是共享对象库的桥梁。新目录里执行git log、git commit时读写的是同一个对象库但git status、git add看到的是各自目录自己的 index 和 HEAD 状态。用生活化的方式理解这就像两个人合租同一套房但各有各的房间门锁。公共区域对象库里的 commits是共享的你买了台冰箱放在客厅室友能看到也能用但各自房间工作目录和暂存区怎么布置互不干扰。你要进室友的房间得经过他自己的门Git 不会允许你俩同时占着同一个房间。2.3 和 clone、复用工具相比的根本差异我在前面提到过复制一份仓库的笨办法。这里把两种方案放到一张表里对比就一清二楚了对比项git worktree多份 git clone对象库共享同一个.git提交全局可见各自独立需要 push/fetch 同步本地分支所有分支共享切一个分支即可各自维护引用容易不同步新增目录一条命令秒建需要完整 clone 历史慢且占空间磁盘占用新增工作目录不复制历史仅文件对象增量每份 clone 都带全量历史用完清理git worktree remove一条命令删除后可能出现落后引用实际用下来多份 clone 的同步成本是隐性黑洞agent 在 A 仓库推了分支你在 B 仓库要git fetch才知道两个仓库的 remote 配置还可能不一样。Worktree 则完全不需要考虑这事所有本地分支天然就在一个命名空间里。另外补一句git worktree早在 Git 2.5 版本就发布了不是实验性功能。很多老开发者没用它是因为觉得单仓库够用但 AI 时代的并行开发强度把它的价值明显放大了。3. 基础命令实战创建、切换、提交与清理接下来是实操部分。我会把一套最常用的命令流程按从生到死的顺序走一遍尽量把命令背后的意图也讲清楚。3.1 创建 Worktree只要一条命令我常用的创建姿势是# 在仓库根目录执行 $ git worktree add ../shop-api-agent-order -b feature/order-refactor这条命令做了什么第一步在当前仓库所在目录的上一级..建一个名为shop-api-agent-order的文件夹第二步从当前 HEAD 创建一个名为feature/order-refactor的新分支第三步把新分支 checkout 到新目录里。目录名和分支名建议直接对应这样看到目录就知道这个工作区在做什么任务。我个人的命名习惯是仓库名-agent-任务名比如shop-api-agent-order、shop-api-agent-payment。如果你不想创建新分支而是想在已有分支上开一个工作区把-b去掉就好# 在已有的 develop 分支上开一个工作区不新建分支 $ git worktree add ../shop-api-develop develop还有一个小技巧如果你的某个分支正被 main 工作区占用但你只是想看看代码、不准备改可以加--detachgit worktree add --detach ../shop-api-temp main。这样会创建一个处于 detached HEAD 状态的临时工作区用于查看代码而不影响分支本身。3.2 查看和管理git worktree list任何时候用git worktree list都能看到当前仓库下所有工作区$ git worktree list /Users/me/code/shop-api a3f2c91 [main] /Users/me/code/shop-api-agent-order 612bd43 [feature/order-refactor] /Users/me/code/shop-api-agent-payment 8d2f01a [feature/payment-refactor]输出信息很直观路径、当前提交、所在分支。我一般会在开始一天的工作前跑一下git worktree list确认哪些任务的工作区还开着、哪些已经用完可以清掉。这不只是查看工具更是任务管理面板。3.3 在 Worktree 里提交修改和普通仓库完全一样这里要单独回应一下很多人搜的git worktree 如何提交修改——在 Worktree 里提交修改和你在普通仓库里提交修改的操作完全一致没有任何特殊命令。# 进入 worktree 目录 $ cd ../shop-api-agent-order # 查看此工作区自己的状态 $ git status # 添加和提交与普通仓库一致 $ git add . $ git commit -m refactor: 重构订单模块的状态机 # 推送到远程分支 $ git push -u origin feature/order-refactor唯一要记住的心理模型是你当前在哪个工作区目录下git 命令操作的就是哪个工作区的内容。比如你在主工作区shop-api里执行git status看到的是 main 分支的状态在shop-api-agent-order里执行git status看到的则是 feature/order-refactor 分支的状态。两者互不干扰你甚至可以同时开着两个终端分别对两个工作区执行git status。提交之后在任意一个工作区里执行git log --all --oneline --graph都能看到这条新提交——这就是共享对象库带来的好处。你不需要手动同步所有工作区共享同一套提交数据。3.4 清理 Worktree用完要收拾任务完成后清理分三步# 1. 从主仓库里移除 worktree 的工作目录 $ git worktree remove ../shop-api-agent-order # 2. 删除对应的本地分支如果它已经被合并 $ git branch -d feature/order-refactor # 3. 清理失效的 worktree 元数据一般 remove 后会自动清理但手动 prune 更安心 $ git worktree prune注意一点git worktree remove默认只允许删除没有未提交改动的工作区。如果 agent 在目录里留下了未提交的代码会报fatal: ... contains modified or untracked files。这时候你需要在对应工作区里先把改动处理掉提交、stash 或丢弃再回来 remove。也可以用--force强制删除但我会谨慎使用——强制删除等于直接把 agent 的现场销毁万一里面有你要的东西就找不回来了。4. 在 AI Agent 工作流中落地 Worktree 的完整方案这一节是整篇文章的核心。基础命令只是工具真正有价值的是把它们组织成一套可复用的 AI 并行开发工作流。4.1 目录与任务规划一个任务一个分支一个工作区我的推荐模型是一个任务对应一个分支、一个 worktree、一个 agent 会话。假设现在接到了三个任务任务 A重构订单模块的状态机任务 B修复支付回调的超时 bug任务 C给优惠券模块补充单元测试我会先把分支和工作区一次性建好$ git worktree add ../shop-api-agent-order -b feature/order-refactor $ git worktree add ../shop-api-agent-payment -b fix/payment-timeout $ git worktree add ../shop-api-agent-coupon -b test/coupon-unittest然后分别打开三个 Cursor 窗口 / 三个 Claude Code 会话每个会话的 workspace 指到对应的 worktree 目录。这样做的直接好处是agent 之间的上下文完全隔离不会出现 agent A 看到的代码里混着 agent B 的未提交改动。尤其注意一点AI coding agent 的上下文理解能力很强但它的视野完全取决于你给它的目录。在同一个目录里开两个 agent它们会互相看到对方的半成品代码然后基于错误的上下文给出错误建议。用 Worktree 分开之后agent 的世界里只有这个任务、这个分支干扰降到最低。4.2 完整操作演练从接任务到合并下面用一个具体例子走完从任务下发到合并的完整流程。第一步确认基线在创建 worktree 之前先确认主仓库的 main 分支是最新的并且你自己手上没有未提交的改动。这个顺序很重要因为 worktree 是从当前 HEAD 拉出来的如果 main 是旧状态后续合并时会出现一堆无谓冲突。$ git checkout main $ git pull origin main第二步创建 worktree 并初始化环境$ git worktree add ../shop-api-agent-order -b feature/order-refactor $ cd ../shop-api-agent-order进入目录后根据项目类型安装依赖。这里有一个容易踩的坑依赖目录要么单独安装要么做共享缓存。如果项目是 Node.js每个 worktree 里跑一遍npm install会多占几百 MB 磁盘如果是 Python 项目每个目录建一个 venv 也同样浪费。这部分我在第五节详细展开这里先按常见做法来。第三步给 agent 下发任务我给 agent 的 prompt 通常会包含三部分信息工作目录限定明确告诉它只允许修改当前工作区目录下的文件任务目标具体要完成什么提交约束完成任务后用哪种格式提交一个典型示例请在这个项目中完成任务 - 工作区目录/Users/me/code/shop-api-agent-order - 任务重构订单模块的状态机。当前的 order state machine 代码在 src/order/stateMachine.js请把 if/else 模式改为状态表驱动模式。 - 要求不要修改其他模块的代码完成后运行 npm test 确保现有测试通过通过后提交到当前分支提交信息为 refactor: order state machine to table-driven pattern第四步agent 提交后人工审核agent 完成提交后我在主工作区或任意一个目录里执行$ git fetch origin $ git log main..feature/order-refactor --oneline看到 agent 的提交记录清晰独立地在 feature 分支上后再执行$ git diff main...feature/order-refactor --stat审核改动是否合理。这一步我强烈建议不要跳过即使 agent 说测试全过了你也至少要看一遍关键文件的 diff。AI 写代码的能力已经很强但它对于项目的长期架构约束理解仍然有限。第五步合并与清理审核没问题后合并并清理$ git checkout main $ git merge --no-ff feature/order-refactor $ git push origin main # 回到主仓库移除 worktree 和分支 $ git worktree remove ../shop-api-agent-order $ git branch -d feature/order-refactor $ git worktree prune4.3 为什么不建议 agent 直接在主工作区干活的最后提醒如果你真的遇到没有时间建 worktree、直接让 agent 改完算了的情况我的建议是把git status里的改动总量当成风险评估指标。假如 main 工作区里有你自己未提交的改动agent 一进来就 add/commit它会把你的改动也卷进去——很多agent 把我的代码提价了的惨案就是这么发生的。Worktree 这套流程的本质是先划边界、再放 agent 进来干活。边界有了agent 怎么折腾都是安全的。这套思路同样适用于你自己如果你手上已经有一个分支在工作又需要临时查看另一个分支的代码直接git worktree add一个临时目录即可不用 stash、不用打扰当前工作区。5. 我踩过的坑Worktree 与 Agent 配合的注意事项最后一部分我把自己在实际使用中确实踩过的坑列出来这些坑不是文档里会写的但对工作效率影响巨大。5.1 同一个分支不能开两个 worktree这个报错来自 Git 本身的设计$ git worktree add ../shop-api-agent-order-2 feature/order-refactor fatal: feature/order-refactor is already checked out at /Users/me/code/shop-api-agent-order原因是 Git 不允许同一个分支在多个 worktree 中同时被 checkout。这个设计是对的如果两个工作区都指向同一个分支它们各自基于不同的 index 提交分支就会混乱。但这在实际工作中经常造成困扰尤其是当你想再开一个临时工作区看看 feature 分支的代码时。解决办法是用--detach或者老老实实基于当前 HEAD 新建另一个分支。5.2 依赖安装和缓存隔离磁盘空间与行为差异这是我最开始忽略、后来花了很多时间处理的问题。以 Node.js 项目为例我给三个任务建了三个 worktree然后分别npm install结果磁盘爆增了几个 G构建时间也成倍拉长。后来我的做法是共享缓存目录。具体来说Node.js设置npm config set cache /path/to/shared/.npm-cache或者用 pnpm 的全局 store。这样每个 worktree 安装依赖时软链接复用同一份内容寻址存储磁盘占用大幅下降。Python用 virtualenv 时直接让每个 worktree 共用同一个 venv注意路径兼容问题或者使用uv这类工具的全局缓存。前端构建缓存Webpack/Vite 的缓存目录可以单独指定到共享路径避免每个 worktree 都重新跑一遍完整构建。另外一个容易被忽略的点构建脚本里如果有硬编码的绝对路径worktree 换个目录后行为会不一样。agent 在 worktree 里跑出的构建产物跟主目录不一致你排查半天最后发现问题出在路径上是很常见的事。5.3 agent 跨工作区乱跑必须在 prompt 里锁定目录我遇到过最恼火的情况明明给 agent 开了独立的 worktree它却自动识别到了仓库根目录跑去看了其他模块的代码甚至把参考代码当成待改代码改了。AI coding agent 的上下文里工作目录往往是通过 IDE 打开的根目录决定的。如果你把 agent 当独立机器人用比如 Claude Code 的 CLI 模式它会基于当前所在目录来判断代码库范围。我的经验是在 agent 的 system prompt 或任务 prompt 里明确写上只修改 /absolute/path/to/worktree 目录下的代码给 agent 下发任务时不在仓库根目录启动命令而是 cd 到目标 worktree 再启动如果 agent 有只在当前工作区修改的配置选项务必打开5.4 忘记清理 worktree 导致的陈旧分支堆积时间一长git worktree list会越来越长堆了一堆用完没删的目录。这些目录本身不占太多空间但它们对应的文件在磁盘上是真实存在的而且如果里面还挂着 agent 跑完的 node_modules占用就大了。我现在的习惯是任务合并完成后立刻执行清理三步曲不让它过夜。如果确实想保留现场一段时间至少把git worktree list的输出在笔记软件里记一笔标注清楚哪个目录对应哪个任务。5.5 worktree 里执行 pull/merge 时要注意方向很多从主工作区养成的肌肉记忆在 worktree 里会出问题。比如有人在 worktree 里执行git pull origin main发现一堆冲突——因为当前 worrk tree 的分支是 feature/xxx拉取 main 进来自然要合并。这本身没问题但要注意你合并的是 main 到 feature不是 feature 到 main。方向搞反会造成 feature 分支里出现一堆 main 的历史review 的时候会非常痛苦。我推荐的流程是所有把所有分支更新到最新的操作都放在主工作区做。主工作区git pull origin main拉取默认分支更新其他 worktree 的任务分支不动等 feature 分支需要同步 main 的新改动时再单独执行。5.6 一个小技巧用脚本一键创建带 worktree 的任务环境建 worktree 的命令本身不长但加上依赖安装、目录命名、提示信息输出每次都手敲还是挺烦的。我自己写了一个简单脚本核心逻辑是这样#!/bin/bash # 用法: new-agent-task.sh 分支名 任务名 BRANCH$1 TASK$2 WORKTREE_PATH../shop-api-agent-${TASK} git worktree add $WORKTREE_PATH -b $BRANCH cd $WORKTREE_PATH npm install echo ✅ Agent 工作区已就绪: $WORKTREE_PATH (branch: $BRANCH)你完全可以根据自己的项目类型调整Java 项目就是 mvn 编译Python 项目就是建 venv。这没什么技术含量但能显著减少重复操作尤其当你同时开着三四个 agent 任务的时候。6. 我的一点心得Worktree 让 AI 编程从提心吊胆变成放心委托这套工作流跑了大概两个月后我最大的感受是心理负担完全不一样了。以前让 agent 改代码我总要在旁边盯着它每提交一次我都要审查一次当前工作区的状态生怕它把别的改动卷进去。现在我把 agent 放进独立的 worktree告诉它这是你的地盘、你随便改、改完提交到你的分支它提交完我再整体 review 一次 diff质量和效率都提升了不少。给还在犹豫的人一个建议先从最简单的场景开始——你正在 main 分支上改代码突然需要让 agent 帮忙修一个紧急 bug别在同一个目录里改git worktree add ../project-hotfix -b fix/xxx建一个隔离目录让 agent 进去干完事直接合并。试过一次你就再也不想回到单工作区硬扛 AI的状态了。
