Git worktree：一個 Agent 一個工作區

上一堂留了一個問題：想讓兩個 Agent 各自完成一個功能，但它們在同一個資料夾裡工作，會互相干擾。

你可能會想到「那就複製一份資料夾吧」。方向對了，但手動複製有很多麻煩：兩份資料夾的 Git 歷史各自獨立，改完要怎麼合在一起？Git 其實早就為這件事準備好了工具，叫做 worktree。

先複習一下分支

在工程基本功單元學 Git 時，你認識了分支（branch）：從某個時間點岔出去，在上面做的修改不會影響主線，做完再合併回來。

平常一個資料夾一次只能「站在」一個分支上。想換分支，就要先把手上的修改存好再切換。一個人工作時沒問題，但兩個 Agent 要同時在兩個分支上工作，就辦不到了。

Worktree：同一個專案，好幾張書桌

Worktree（工作樹）讓同一個 Git 專案同時擁有好幾個工作資料夾。每個資料夾站在自己的分支上，檔案各自獨立；但它們背後共用同一份 Git 歷史，任何一邊的 commit，另一邊都看得到。

可以想成同一間辦公室裡的幾張書桌：大家各自在自己的桌上工作，但共用同一個檔案櫃。

用 Git 指令操作

以前面單元的記帳專案 expense-app 為例。在專案資料夾裡，先確認目前的修改都已經 commit，再建立兩個 worktree：

git worktree add ../expense-app-export -b feature/export
git worktree add ../expense-app-fix -b fix/total

這行指令的意思是：在上一層資料夾建立 expense-app-export，並在那裡開一個新分支 feature/export。

查看目前有哪些 worktree：

git worktree list

C:/Users/you/expense-app          a1b2c3d [main]
C:/Users/you/expense-app-export   a1b2c3d [feature/export]
C:/Users/you/expense-app-fix      a1b2c3d [fix/total]

接著開兩個終端機，各自進入一個資料夾啟動 Claude Code：

cd ../expense-app-export
claude

cd ../expense-app-fix
claude

現在兩個 Agent 各有自己的桌子，A 改了 main.py，B 完全看不到，也不會被影響。

Claude Code 的捷徑

Claude Code 把上面的步驟包成一個選項：

claude --worktree export-csv

它會在專案裡的 .claude/worktrees/export-csv/ 建立一個 worktree，開一個新分支，並直接在裡面啟動 Agent。在另一個終端機用不同的名字再執行一次，就有第二個獨立的工作區。

幾個值得知道的細節：

• 專案至少要有一次 commit，因為 worktree 要從某個 commit 岔出去。
• 把 .claude/worktrees/ 加進 .gitignore，不然原本的資料夾會把這些工作區當成新檔案。
• 結束對話時，如果工作區裡沒有任何修改，Claude Code 會自動清掉它；有修改的話，會問你要保留還是刪除。

你也可以在對話中直接說「請在 worktree 裡做這件事」，或者讓子代理各自在獨立的 worktree 裡工作。實際的行為和選項可能隨版本調整，請以 Claude Code 官方文件中關於 worktrees 的說明為準。

別忘了準備工作環境

這是最多人卡住的地方。worktree 是一份全新的檔案，只包含被 Git 追蹤的內容。所以：

• 虛擬環境不在裡面：每個 worktree 要各自建立虛擬環境並安裝套件，或請 Agent 幫你做。
• .env 不在裡面：金鑰檔案本來就不該進版控，所以新的 worktree 裡沒有它。

Claude Code 支援在專案根目錄放一個 .worktreeinclude 檔案，寫法和 .gitignore 一樣，列出要自動複製到新工作區的檔案：

.env

這樣每次建立新的 worktree，.env 就會一起複製過去。如果你是用 git worktree add 手動建立的，就要自己複製。

做完之後：一個一個合併回來

兩個 Agent 都完成後，回到原本的資料夾，把它們的分支合併進主線：

一次合併一個，有問題馬上知道是哪一個造成的。

cd ../expense-app
git merge feature/export
pytest
git merge fix/total
pytest

如果你的專案在 GitHub 上，更好的做法是讓每個分支各開一個 Pull Request，在網頁上檢查修改內容再合併。下一堂課會讓 GitHub 在每個 Pull Request 自動跑測試。

如果兩個分支剛好改到同一段程式，合併時會出現衝突（conflict）。別慌，Git 會標出衝突的位置，你可以請 Agent 幫忙：「合併時發生衝突，請說明兩邊各改了什麼，並建議怎麼保留兩邊的修改」。衝突多半代表當初的拆法讓兩個工作碰到同一個檔案，這也是上一堂說「先別平行」的情況。

收拾工作區

合併完成後，把不需要的 worktree 和分支清掉：

git worktree remove ../expense-app-export
git branch -d feature/export

git worktree remove 會檢查資料夾裡有沒有還沒 commit 的修改，有的話會拒絕刪除，保護你不會不小心丟掉工作。