企业官网建设流程全解析

前两天下午我差点把仓库搞成一锅粥：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 帮我调一个 bug，agent 跑了一遍测试，顺带改了配置，还生成了调试用的临时文件。我手头的另一项工作正常跑测试时，莫名其妙挂掉了，查了半天才发现是 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、复用工具相比的根本差异

我在前面提到过"复制一份仓库"的笨办法。这里把两种方案放到一张表里对比，就一清二楚了：

实际用下来，多份 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 工作区占用，但你只是想看看代码、不准备改，可以加--detach：git 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 通常会包含三部分信息：

1. 工作目录限定：明确告诉它"只允许修改当前工作区目录下的文件"
2. 任务目标：具体要完成什么
3. 提交约束：完成任务后，用哪种格式提交

一个典型示例：

请在这个项目中完成任务： - 工作区目录：/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 prune

4.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 模式），它会基于"当前所在目录"来判断代码库范围。我的经验是：

1. 在 agent 的 system prompt 或任务 prompt 里明确写上"只修改 /absolute/path/to/worktree 目录下的代码"
2. 给 agent 下发任务时，不在仓库根目录启动命令，而是 cd 到目标 worktree 再启动
3. 如果 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"的状态了。