Git Worktree 多 Agent 衝突排除：6 種問題的診斷與修復

Git Worktree 的故障模式是可預測的

一個工廠地板上，每個工人有獨立工作站。這解決了顯而易見的問題：沒人撞到彼此的手肘。但工作站共用電力供應、通風系統、和裝卸區。出問題的時候，幾乎都是那些共享系統——不是工作站本身。

Git worktree 運作方式一模一樣。它讓每個 AI agent 擁有自己的工作目錄、自己的 branch、自己的 staging area。這解決了兩個 agent 同時編輯同一個檔案的問題。但 worktree 之間共享的東西比你想的多：.git 物件資料庫、lock 檔機制、以及 agent 平行修改的所有被追蹤檔案。這些共享層面產生六種不同的衝突類型，每種都有明確的成因、診斷方式和修復方法。

如果你是第一次設定 worktree，請先看 Git Worktree 多 Agent 設定指南。這篇文章假設你的 worktree 已經在跑，而且出了問題。

1. Lock 檔衝突

現象： 兩個 agent 在不同 worktree 中各自執行 npm install（或 yarn install、pnpm install）。每次安裝都修改 lockfile（package-lock.json、yarn.lock 或 pnpm-lock.yaml）。因為 lockfile 被 git 追蹤，兩個 agent 在各自的 branch 上產出不同版本的 lockfile。Merge 時出現 5,000 行的 diff，沒有人能手動 review。

原因： Lockfile 對每次安裝是確定性的，但跨 branch 不是。如果 agent A 裝了 zod，agent B 裝了 date-fns，兩邊都會重新產生整棵依賴樹的 lockfile。即使實際的依賴變更很小，結果檔案幾乎每行都不同。

診斷：

# 檢查 worktree 中 lockfile 是否被修改
cd ~/project-feature-auth
git diff --name-only main -- package-lock.json yarn.lock pnpm-lock.yaml

修復：

# 方法 1：從 merge 後的 package.json 重新產生 lockfile
git checkout main
git merge feature-auth --no-commit
# 接受兩邊的 package.json 變更
# 然後重新產生 lockfile
npm install          # 或 yarn install / pnpm install
git add package-lock.json
git commit -m "merge feature-auth with regenerated lockfile"

# 方法 2：用 npm 內建的 merge driver
npx npm-merge-driver install -g
# 之後的 merge 會自動處理 package-lock.json 衝突

預防： 在 .gitattributes 中加入規則，讓 git 用 npm merge driver 處理 lockfile。或者協調 agent 的工作，讓只有一個 branch 安裝新依賴，其他 agent 用現有的依賴集合。

package-lock.json merge=npm-merge-driver

2. Git Index Lock 錯誤

現象： Agent 的 git 操作失敗，錯誤訊息如下：

fatal: Unable to create '/path/to/repo/.git/worktrees/feature-auth/index.lock': File exists.

Agent 無法 stage 檔案、commit、或執行任何對 index 的寫入操作。

原因： Git 在任何寫入操作前會建立 index.lock 檔，防止同時修改。如果 agent process 當掉、終端被關閉、或系統在 git 操作進行中斷電，lock 檔就會殘留。就像一個卡住的門閂——門鎖著，但裡面沒人。每個 worktree 有自己的 index lock，位在 .git/worktrees/<name>/index.lock，所以只影響當掉的那個 worktree。

診斷：

# 檢查所有 worktree 是否有殘留的 lock 檔
find .git/worktrees -name "index.lock" -ls

# 確認是否有 git process 還在執行
ps aux | grep git

修復：

# 確認沒有 git process 在使用這個 lock 後才刪除
rm .git/worktrees/feature-auth/index.lock

預防： 不要用 kill -9 終止 agent process，也不要在 git 操作進行中關閉終端。用 kill -15（SIGTERM），讓 process 有時間清理。如果你用 Claude Code 的 --worktree 跑 agent，讓 session 用 /exit 正常結束，不要強制關閉終端。

3. Branch Checkout 衝突

現象： 你嘗試為一個已經被 checkout 的 branch 建立 worktree：

fatal: 'feature-auth' is already checked out at '/Users/you/project-feature-auth'

原因： Git 強制一個 branch 只能被一個 worktree checkout。這是刻意設計的。如果兩個 worktree checkout 同一個 branch，一邊的 commit 會無聲地移動另一邊的 HEAD，造成損壞狀態。這個錯誤是保護機制。

診斷：

# 看哪些 branch 在哪些 worktree 被 checkout
git worktree list

/Users/you/project                 abc1234 [main]
/Users/you/project-feature-auth    def5678 [feature-auth]

修復：

# 方法 1：從現有 branch 建立新 branch
git worktree add ../project-auth-v2 -b feature-auth-v2 feature-auth

# 方法 2：先移除不需要的舊 worktree
git worktree remove project-feature-auth
git worktree add ../project-feature-auth-new feature-auth

預防： 用命名慣例把 worktree 名稱綁定到 agent session。例如 feature-auth-agent1 和 feature-auth-agent2。Claude Code 的 --worktree flag 會自動產生不重複的 worktree 名稱。

4. Merge 時的程式碼衝突

現象： Agent A 在 feature-auth branch 修改了 src/routes/index.ts。Agent B 在 feature-api branch 也修改了同一個檔案。Merge 兩個 branch 到 main 時，git 無法自動解決重疊的變更。

原因： Worktree 在檔案系統層級隔離 agent，但不在語義層級協調。兩個 agent 開發不同功能時，經常會碰到共用的檔案：路由定義、設定檔、barrel export、type 定義、資料庫 schema。這些「熱點檔案」是每個 feature branch 都傾向修改的檔案。

診斷：

# Merge 前先檢查重疊檔案
git diff main...feature-auth --name-only > /tmp/auth-files.txt
git diff main...feature-api --name-only > /tmp/api-files.txt
comm -12 <(sort /tmp/auth-files.txt) <(sort /tmp/api-files.txt)

這會列出兩個 branch 都修改的檔案。清單越長，衝突越痛。

修復：

# 先 merge 第一個 branch
git checkout main
git merge feature-auth

# Merge 第二個 branch（衝突會在這裡出現）
git merge feature-api
# 手動解決衝突，然後：
git add .
git commit -m "merge feature-api, resolve conflicts with feature-auth"

如果 merge 過程中遇到 lockfile 衝突，參考上面的 lockfile 章節。

預防： 這是最難預防的衝突，因為需要 merge 前的規劃。三種策略有效：

1. 熱點檔案的單一寫入者規則。 指定一個 agent 負責共用檔案（例如路由定義）。其他 agent 把自己的路由寫在獨立檔案中，透過 import 整合。
2. 頻繁 merge。 不要讓 branch 分歧好幾天。第一個完成的 branch 先 merge 到 main，剩下的 branch 在完成前先 rebase。
3. 只做新增的變更。 透過 CLAUDE.md 或 prompt 指示 agent 在獨立檔案中新增 export、route、type，而不是修改現有檔案。新增很少衝突。

關於如何協調多個 AI agent 跨 worktree 工作，2026 AI CLI 工具完整指南有更全面的說明。

5. 過期的 Worktree 參照

現象： git worktree list 顯示已經不存在於磁碟上的 worktree。Git 指令偶爾會警告有孤立的 worktree metadata。

原因： 如果 agent session 當掉，或你用 rm -rf 刪除 worktree 目錄而不是用 git worktree remove，git 會保留 worktree 的 metadata 在 .git/worktrees/ 中。Worktree 出現在 git worktree list 但目錄已經不見了。就像電話簿上列著一棟已經拆掉的建築。這會阻止你用相同名稱或 branch 建立新的 worktree。

診斷：

# 列出所有 worktree，檢查是否有可清理的項目
git worktree list --porcelain

# 預覽哪些會被清理
git worktree prune --dry-run

修復：

# 移除所有過期的 worktree 參照
git worktree prune

# 確認清理結果
git worktree list

如果被清理的 worktree 的 branch 還有未 merge 的工作，branch 本身不受影響。清理只移除 metadata 連結，commit 留在 repository 中。

預防： 一律用 git worktree remove <path>，不要用 rm -rf。如果你用腳本自動化 worktree 的生命週期，把 git worktree prune 加入清理步驟。一個簡單的 alias 很有用：

# 加到 .bashrc 或 .zshrc
alias gwtclean='git worktree prune --dry-run && git worktree prune && git worktree list'

6. Build 產物汙染

現象： 某個 worktree 的 build 指令產出損壞或過時的結果，因為它讀到其他 worktree 產生的 cache。症狀包括建置失敗、bundle 內容錯誤、或測試在一個 worktree 通過但在另一個失敗。

原因： Next.js（.next/）、Vite（dist/）、TypeScript（tsconfig.tsbuildinfo）等 build 工具寫入相對於專案根目錄的位置。如果 worktree 之間共享 build cache（cache 目錄設為絕對路徑，或 monorepo 工具把 cache 存在共用位置），agent 之間的 build 就會互相汙染。就像兩個化學家共用一個燒杯，但實驗之間沒有清洗。

另外，node_modules/ 通常不在 worktree 之間共享（各有一份），但如果某個 worktree 的 node_modules 是從主 worktree symlink 過來的，當一邊的 agent 修改 package.json 時，依賴解析就會出問題。

診斷：

# 檢查是否有共用的 cache 目錄
ls -la .next/ dist/ .turbo/ node_modules/.cache/

# 比較跨 worktree 的 build fingerprint
md5sum ../project-feature-auth/.next/BUILD_ID .next/BUILD_ID

修復：

# 清除受影響 worktree 的 build cache
rm -rf .next/ dist/ .turbo/ node_modules/.cache/ tsconfig.tsbuildinfo
npm run build

預防： 確保 build 工具使用 worktree 內的本地 cache 目錄。Next.js 預設就是這樣（.next/ 相對於專案根目錄）。支援自訂 cache 路徑的工具，指向 worktree 內部的目錄：

// turbo.json 的 cache 預設就是 worktree 本地
// 多數工具不需要改

// 自訂 build 腳本用相對路徑
// 錯誤：CACHE_DIR=/tmp/shared-build-cache
// 正確：CACHE_DIR=./.build-cache

把 build 輸出目錄加進 .gitignore（如果還沒加的話）。每個 worktree 應該從原始碼獨立 build。

監控多個 Worktree

當你有三個以上的 worktree 在運作，重心從修復衝突轉移到提早偵測衝突。你需要看到每個 agent 在哪個 branch、是否有未 commit 的變更、哪些 branch 跟 main 分歧了。

# 快速檢查所有 worktree 的狀態
git worktree list | while read dir rest; do
  echo "=== $dir ==="
  git -C "$dir" status --short
done

手動執行這些指令很快就會膩。如果你同時管理多個 agent 終端，Termdock 在單一畫面中顯示所有 worktree 的 git 狀態，每個終端 pane 都會顯示它的 branch 和變更數量，你可以拖拉調整需要關注的 agent 視窗大小。

速查表：衝突類型對照

六種衝突的根本原因都是共享狀態。Worktree 隔離了工作目錄，但共享 git 資料庫、跨 branch 的追蹤檔案、以及用絕對路徑設定的 cache。辨識是哪一層的共享造成你的衝突，是最快找到修復方法的路徑。

完整的平行 AI agent worktree 設定指南，請看 Git Worktree 多 Agent 設定。更廣泛的 AI CLI 工具在現代開發流程中的定位，2026 AI CLI 工具完整指南有全面的整理。