现在的 AI 编程工具已经不满足于“补全几行代码”。

Codex、Cursor、Claude Code 这类 Agent 可以读取代码库、修改多个文件、执行测试，甚至同时处理多个开发任务。Codex 的桌面工作流已经强调并行任务和内置 Worktree；Cursor 文档提供了在隔离 Git Worktree 中运行 Agent 的能力；Claude Code 也支持通过 claude --worktree 启动相互隔离的并行会话。

问题也随之出现：

两个 AI Agent 同时改一个项目，会不会把对方的代码覆盖掉？

会。

如果它们共用同一个工作目录，就可能同时修改文件、切换分支、安装依赖、运行格式化命令，最终产生一份很难判断归属的混合 Diff。

解决这个问题，一个实用方案就是 Git Worktree。

---

一、Git Worktree 到底解决什么问题？

普通情况下，一个 Git 仓库只有一个工作目录。

你想同时处理两个任务，通常只能：

1. 先暂存当前修改；
2. 切换分支；
3. 处理另一个任务；
4. 再切回来恢复现场。

当两个 AI Agent 并行工作时，这种方式就不够用了。

Git Worktree 允许同一个仓库同时拥有多个工作目录，每个目录可以检出不同分支。它们共享仓库中的对象和大部分引用，但各自拥有独立的 HEAD、索引和工作区文件。Git 官方将其定义为“为同一仓库管理多个工作树”，让开发者可以同时检出多个分支。

可以把它理解为：

my-project/                    main
my-project-agent-login/        agent/fix-login-timeout
my-project-agent-tests/        agent/add-auth-tests

三个目录属于同一个 Git 仓库，但各自有独立文件现场。

因此：

• Agent A 可以修改登录模块；
• Agent B 可以补充测试；
• 你可以继续在主目录查看代码；
• 三者不会直接覆盖彼此尚未提交的文件。

但要注意：

Worktree 能隔离编辑现场，不代表最终合并时绝对没有冲突。

两个 Agent 如果都修改了同一段代码，合并分支时仍然可能产生冲突。

---

二、准备一个实际任务

假设项目结构如下：

agent-worktree-demo/
├── package.json
├── src/
│   ├── auth/
│   │   └── login.js
│   └── cache/
│       └── redis.js
└── tests/
    └── auth/
        └── login.test.js

现在需要并行处理两个任务：

Agent A

修复 Redis 超时时，登录接口直接返回 500 的问题。

对应分支：

agent/fix-login-timeout

Agent B

为登录接口补充 Redis 超时测试。

对应分支：

agent/add-auth-tests

如果让两个 Agent 都进入原项目目录，它们可能同时修改 login.js、测试文件和依赖配置。

更稳的方式是给它们分别创建 Worktree。

---

三、创建两个独立 Worktree

先回到主项目目录，确认当前工作区干净：

git status

如果存在未提交代码，先提交或暂存，不要直接开始并行任务。

更新主分支：

git switch main
git pull --ff-only

创建第一个 Worktree：

git worktree add \
  ../agent-worktree-demo-login \
  -b agent/fix-login-timeout \
  main

创建第二个 Worktree：

git worktree add \
  ../agent-worktree-demo-tests \
  -b agent/add-auth-tests \
  main

-b 后面是新分支名称，最后的 main 表示两个分支都从当前主分支开始。

执行完以后，目录结构会变成：

workspace/
├── agent-worktree-demo/
├── agent-worktree-demo-login/
└── agent-worktree-demo-tests/

查看全部 Worktree：

git worktree list

示例输出：

/path/agent-worktree-demo        62904b7 [main]
/path/agent-worktree-demo-login  62904b7 [agent/fix-login-timeout]
/path/agent-worktree-demo-tests  62904b7 [agent/add-auth-tests]

Git 官方文档说明，git worktree add <path> -b <branch> <commit-ish> 会创建新分支，并将其检出到新的关联工作树；如果省略起始提交，默认从当前 HEAD 创建。

Windows PowerShell 也可以使用类似路径：

git worktree add `
  ..\agent-worktree-demo-login `
  -b agent/fix-login-timeout `
  main

---

四、让两个 Agent 分别进入自己的目录

Agent A 的目录

cd ../agent-worktree-demo-login

可以给 Agent A 这样的任务：

任务：修复登录流程中 Redis 超时时直接返回 500 的问题。

修改范围：
- src/auth/login.js
- src/cache/redis.js
- 必要的相关测试文件

限制：
1. 不修改接口路径；
2. 不改变原有成功响应结构；
3. 不新增第三方依赖；
4. Redis 超时时返回 AUTH_CACHE_TIMEOUT；
5. 不允许修改生产配置；
6. 修改完成后运行 npm test；
7. 最后输出修改文件、测试结果和风险点。

Agent B 的目录

打开另一个终端：

cd ../agent-worktree-demo-tests

给 Agent B 的任务：

任务：为登录接口补充 Redis 超时测试。

修改范围：
- tests/auth/login.test.js

限制：
1. 不修改业务代码；
2. 不降低现有测试断言；
3. 模拟 Redis 超时；
4. 验证返回错误码 AUTH_CACHE_TIMEOUT；
5. 不安装新依赖；
6. 修改完成后运行对应测试；
7. 输出新增测试覆盖的场景。

两个 Agent 此时操作的是不同目录和不同分支。

即便它们同时保存文件，也不会直接写进对方的工作目录。

Claude Code 官方提供的并行用法也是为不同任务启动不同 Worktree，例如：

claude --worktree feature-auth

官方说明每个 Worktree 都是位于自己分支上的独立检出，因此并行会话不会在编辑阶段相互冲突。

---

五、每个 Worktree 都要单独准备运行环境

Worktree 会检出 Git 跟踪的文件，但不会自动复制未跟踪文件。

这意味着下面这些内容通常需要单独处理：

node_modules/
.env
.env.local
dist/
coverage/
临时缓存目录

Node.js 项目

分别进入两个 Worktree 安装依赖：

cd ../agent-worktree-demo-login
npm ci

cd ../agent-worktree-demo-tests
npm ci

如果使用 pnpm：

pnpm install --frozen-lockfile

虽然每个目录都有独立的 node_modules，但 pnpm 的全局内容寻址存储通常可以减少重复下载。

环境变量

不要直接把生产环境 .env 复制给 Agent。

可以从脱敏模板生成本地配置：

cp .env.example .env.local

例如：

DATABASE_URL=postgres://local:local@localhost:5432/demo
REDIS_URL=redis://localhost:6379
JWT_SECRET=development-only

涉及数据库、Redis、对象存储等服务时，还要避免两个 Worktree 共用容易互相影响的数据。

例如给每个 Worktree 配置不同测试数据库：

# Agent A
TEST_DATABASE_NAME=demo_agent_login

# Agent B
TEST_DATABASE_NAME=demo_agent_tests

否则，即使代码目录隔离了，两个 Agent 仍可能同时修改同一个测试数据库。

---

六、分别检查 Agent 的修改

Agent 完成任务后，不要马上合并。

先检查第一个 Worktree：

git -C ../agent-worktree-demo-login status --short
git -C ../agent-worktree-demo-login diff --stat
git -C ../agent-worktree-demo-login diff
git -C ../agent-worktree-demo-login diff --check

再检查第二个：

git -C ../agent-worktree-demo-tests status --short
git -C ../agent-worktree-demo-tests diff --stat
git -C ../agent-worktree-demo-tests diff
git -C ../agent-worktree-demo-tests diff --check

这些命令分别用于查看：

• 修改了哪些文件；
• 新增和删除了多少行；
• 具体代码变化；
• 是否存在明显空白字符错误。

重点检查：

有没有修改任务范围以外的文件
有没有改动 package.json 或锁文件
有没有删除测试
有没有降低断言强度
有没有碰生产配置
有没有重构无关代码
有没有上传密钥或敏感信息

Worktree 只是隔离工具，不能替代代码审查。

---

七、分别运行测试并提交

登录修复分支

cd ../agent-worktree-demo-login

npm test
npm run lint
npm run typecheck

测试通过后提交：

git add src/auth/login.js src/cache/redis.js tests/
git commit -m "fix(auth): handle redis timeout"

测试补充分支

cd ../agent-worktree-demo-tests

npm test
npm run lint
npm run typecheck

提交：

git add tests/auth/login.test.js
git commit -m "test(auth): cover redis timeout"

不要使用：

git add .

尤其是 Agent 参与开发时，建议明确指定要提交的文件，避免把日志、临时配置或无关修改一起提交。

---

八、不要直接合并进 main，先建集成分支

两个 Agent 的代码都通过各自测试，不代表组合以后一定正常。

建议先创建一个集成分支：

cd ../agent-worktree-demo

git switch main
git pull --ff-only
git switch -c integration/auth-agent-batch

先合并 Agent A：

git merge --no-ff agent/fix-login-timeout

运行测试：

npm ci
npm test
npm run lint
npm run typecheck

再合并 Agent B：

git merge --no-ff agent/add-auth-tests

再次运行完整测试：

npm test
npm run lint
npm run typecheck

最终流程是：

main
 ├── agent/fix-login-timeout
 ├── agent/add-auth-tests
 └── integration/auth-agent-batch
       ├── 合并登录修复
       ├── 运行测试
       ├── 合并测试补充
       ├── 再次运行测试
       └── 人工 Review

这样即使组合后的代码出现问题，也不会污染主分支。

---

九、Worktree 不能消除合并冲突

假设两个 Agent 都修改了：

src/auth/login.js

Agent A 修改：

try {
  const session = await redis.get(sessionKey);
  return session;
} catch (error) {
  throw new AuthError('AUTH_CACHE_TIMEOUT');
}

Agent B 同时重构为：

const session = await cacheService.findSession(sessionKey);

if (!session) {
  throw new AuthError('SESSION_NOT_FOUND');
}

编辑阶段它们不会互相覆盖，因为位于两个独立目录。

但第二个分支合并时仍可能出现：

CONFLICT (content): Merge conflict in src/auth/login.js

这说明：

Worktree 解决的是工作目录隔离，不是业务逻辑冲突。

发生冲突后，先查看：

git status

处理冲突文件：

git add src/auth/login.js
git commit

然后重新运行完整测试。

如果两个任务天然需要改同一模块，更合理的方式可能是：

1. 先完成基础重构；
2. 合并后更新另一个 Agent 的分支；
3. 再启动第二项任务。

并行不是越多越好。

只有任务之间依赖较少时，Worktree 并行才真正省时间。

---

十、什么时候适合并行，什么时候不要并行？

适合并行

Agent A：修改后端接口
Agent B：补充独立测试
Agent C：更新 README
Agent D：整理前端文案

这些任务修改范围相对独立。

不适合强行并行

Agent A：重构用户数据模型
Agent B：修改依赖用户模型的接口
Agent C：为新数据模型写迁移

这三项任务存在明显前后依赖。

强行并行会导致：

• 基础类型不一致；
• 接口反复修改；
• 数据库迁移冲突；
• 测试基于不同假设；
• 合并成本高于节省的时间。

并行开发前，可以先做一张任务依赖表：

任务	修改范围	是否依赖其他任务	是否适合并行
修复登录超时	auth、cache	否	是
补登录测试	tests/auth	部分依赖	是，但最后统一验证
重构用户模型	models、services	否	先执行
修改用户接口	controllers、services	依赖模型重构	否
更新 README	docs	否	是

---

十一、如何正确清理 Worktree？

确认分支已经提交并完成合并后，查看状态：

git worktree list

进入每个目录检查是否干净：

git -C ../agent-worktree-demo-login status
git -C ../agent-worktree-demo-tests status

使用 Git 命令移除：

git worktree remove ../agent-worktree-demo-login
git worktree remove ../agent-worktree-demo-tests

不要直接执行：

rm -rf ../agent-worktree-demo-login

如果手动删除了目录，Git 仓库中可能还保留关联管理信息。

Git 官方建议使用 git worktree remove 正常移除；如果目录已被手动删除，可以用 git worktree prune 清理失效的管理记录。

先查看哪些记录会被清理：

git worktree prune --dry-run

确认后执行：

git worktree prune

最后删除已经合并的分支：

git branch -d agent/fix-login-timeout
git branch -d agent/add-auth-tests

如果 Git 拒绝删除，先确认分支是否真的已经合并，不要立即使用大写 -D 强制删除。

---

十二、5 个常见错误

1. 两个 Agent 共用一个分支

Worktree 应该遵循：

一个任务
一个 Worktree
一个独立分支

不要让两个 Worktree 同时围绕同一个任务分支反复修改。

2. 两个 Agent 同时修改锁文件

如果 Agent A 和 Agent B 都执行依赖安装，可能同时修改：

package-lock.json
pnpm-lock.yaml
yarn.lock

没有新增依赖时，可以明确要求：

不要修改 package.json 和任何锁文件。

3. 两个 Agent 共用同一个数据库

目录隔离不等于外部资源隔离。

测试数据库、Redis DB、端口、临时文件目录也需要区分。

例如：

PORT=3101
REDIS_DB=11

PORT=3102
REDIS_DB=12

4. Worktree 还没提交就强制删除

如果目录中有未提交或未跟踪文件，正常的 git worktree remove 通常会拒绝删除。

先检查：

git -C ../agent-worktree-demo-login status --short

不要为了清理方便直接使用：

git worktree remove -f ...

除非已经确认里面没有需要保留的代码。

5. 认为测试分别通过就可以直接上线

Agent A 测试通过，Agent B 也测试通过，只能说明各自分支状态正常。

最终还必须在集成分支运行：

npm test
npm run lint
npm run typecheck

因为组合后的行为可能发生变化。

---

十三、一套可以直接复用的多 Agent 流程

完整流程可以固定为：

1. 更新 main
2. 拆分无强依赖任务
3. 每个任务创建独立分支和 Worktree
4. 每个 Agent 只进入自己的目录
5. 限定文件和命令权限
6. 分别运行测试
7. 分别检查 Diff
8. 每个分支独立提交
9. 创建 integration 分支
10. 顺序合并并重复测试
11. 人工 Review
12. 移除 Worktree 和废弃分支

对应命令：

git switch main
git pull --ff-only

git worktree add ../project-agent-login \
  -b agent/fix-login-timeout \
  main

git worktree add ../project-agent-tests \
  -b agent/add-auth-tests \
  main

git worktree list

git -C ../project-agent-login diff --stat
git -C ../project-agent-tests diff --stat

git switch -c integration/auth-agent-batch
git merge --no-ff agent/fix-login-timeout
npm test

git merge --no-ff agent/add-auth-tests
npm test

git worktree remove ../project-agent-login
git worktree remove ../project-agent-tests

git worktree prune --dry-run

这套流程与具体 Agent 无关。

无论使用 Codex、Cursor、Claude Code，还是其他能修改本地代码的 Agent，都可以采用相同的隔离思路。

---

十四、AI 工具只是执行者，Git 流程才是保护层

如果长期使用 ChatGPT Plus、Claude Pro、Cursor、Kiro 等工具，也可以通过 gpt68.com 了解相关 AI 会员充值服务。

需要说明的是，gpt68.com 是第三方 AI 会员充值平台，不是相关工具的官方网站或官方授权合作方，也不是共享账号服务。使用前应看清套餐说明、账号要求、到账说明和售后规则。

不过对开发者而言，开通工具只是准备工作。

真正决定多个 Agent 能否安全并行的是：

任务是否拆得足够独立
分支是否隔离
Worktree 是否独立
环境是否隔离
测试是否完整
Diff 是否人工检查
合并是否经过集成分支

Agent 可以提高执行速度。

Git Worktree、测试和 Review 才负责控制风险。

---

总结

多个 AI Agent 同时修改项目时，不要让它们挤在同一个工作目录里。

更稳的做法是：

一个 Agent
一个任务
一个分支
一个 Worktree

Git Worktree 可以让同一个仓库同时检出多个分支，每个 Agent 在独立目录中修改和测试，避免编辑阶段互相覆盖。

但它不能自动解决所有问题。

合并冲突、共享数据库、端口占用、锁文件变化、错误业务假设，仍然需要开发者处理。

所以完整流程不能只有“创建 Worktree”，还要包括：

任务拆分
环境隔离
独立测试
Diff 检查
集成分支
人工 Review
安全清理

当 AI Agent 越来越擅长并行写代码时，开发者真正需要补上的，不只是更好的提示词，而是一套能隔离、验证和回滚的工程流程。