Claude Code｜雙 Worktree 實作與衝突整合

兩個 Claude 工作階段同時編輯專案，最容易出現的問題是互相改到同一份檔案，或各自測試通過、整合後卻失敗。本篇用兩個 Worktree 分別處理篩選預設值與介面文字，故意製造一次小衝突，再完成整合、驗證與清理。你不需要先啟用 Agent Teams。

先讀 Git 審查、Worktree 入門及工作交接。下載第 88 篇材料，使用全新解壓縮的 starter。需要 Git 與 Node.js 22；不要在包含其他未完成變更的日常專案直接照做。

為什麼隔離檔案還不夠

閱讀完整文字說明

雙 Worktree 實作與衝突整合，以流程和文件圖形呈現教學重點。

Worktree 讓同一 Git 儲存庫擁有不同工作目錄與分支，所以兩個工作階段可以各自編輯。但是 Git 外部的資源不會因此自動隔離：兩個網站仍可能爭用同一埠號，讀寫同一個資料庫，或將結果放入同一個暫存檔。

本練習不使用資料庫，兩邊若需要啟動網站，就各自指定不同 PORT；產物留在各自工作目錄。分工表應同時列出檔案範圍、服務埠號與交付方式，而不只是寫「一位做前端、一位做後端」。這樣最後整合時，才知道哪個成果屬於哪個任務。

兩份工作都涉及 view-mode.txt，是刻意安排的衝突案例。真實工作可以先切得更乾淨；但學會辨識重疊，比假設永遠不會衝突更實用。本篇也會讓你看見「檔案有衝突標記」與「需求有矛盾」並不總是同一件事。

先跑一次完整的受控示範

材料提供的 demo 會在系統暫存目錄建立新的練習 Git 儲存庫，不使用你當前專案的分支。它只處理自己建立的目錄，過程不需要網路，也不建立 GitHub PR。跑完會印出 receipt.json 路徑，保留基準提交、合併提交與每一步命令結果。

node worktrees/demo.mjs

打開紀錄，確認 controlledConflict 為 true，兩個功能都保留，coreTests 有實際測試輸出。示範程式完成代表 Git 流程可重現，不代表 Claude 已替你實作兩項功能。後面的手動流程要由你自己完成；需要 Claude 時，再把每個工作目錄交給獨立工作階段。

手動建立共同基準

另解壓一份乾淨材料，將這份 starter 當成主要工作目錄。先執行核心測試，再初始化新儲存庫並提交。提交身分使用你原本 Git 的設定；若沒有設定，先在這個練習儲存庫設定 user.name 與 user.email，不要修改所有專案的全域偏好。

node --test tests/model.test.mjs
git init --initial-branch=main
git add .
git commit -m "Create worktree exercise baseline"
git worktree add -b lab/filter ../filter main
git worktree add -b lab/labels ../labels main
git worktree list

確認 ../filter 與 ../labels 是你預期的新路徑，而且原本不存在重要檔案。git worktree list 應列出 main、lab/filter 與 lab/labels 對應的位置。若 Git 說分支已被其他工作目錄使用，先查清楚現有關係，不要為了通過命令任意加強制選項。

分別完成兩項修改

filter 工作新增 filterTasks 函式，並將 view-mode.txt 的 default 改為 active；labels 工作只改標籤。你可以手動修改，也可在各自工作目錄啟動 Claude，清楚交代範圍。不要讓第二個工作階段從第一個工作目錄啟動，否則對話分開了，實際檔案卻沒有分開。

只處理本工作目錄的篩選需求。
新增 filter.js 的 filterTasks(items, mode)，active 時回傳未完成項目，其他模式保留全部。
把 view-mode.txt 的 default 改成 active，不改 label。
保留原資料，執行相關測試，最後回報 diff；不要合併其他分支。

只把 view-mode.txt 的 label 改為「所有待辦」。
不要修改 default、filter.js 或其他工作目錄。
完成後回報變更，不自行合併。

每一邊都應先審閱 diff 再提交。提交前看 git status --short，確認沒有把執行紀錄、node_modules 或另一項工作的內容混進去。分支上的測試通過，只說明該版本的結果；接下來仍需要在整合版本重驗。

合併並理解衝突

回到主要 starter，先合併 filter，再合併 labels。受控示範的兩項修改位在相鄰的短文字區塊，Git 會要求處理衝突。你應讀取雙方意圖，保留 default=active 與 label=所有待辦，而不是盲目選取整個 ours 或 theirs。

git status --short
git merge lab/filter
git merge lab/labels

default=active
label=所有待辦

移除衝突標記後，執行 git diff --check 檢查空白及殘留問題，再把已解決的檔案加入提交。若你看不懂衝突，先保存閱讀紀錄並使用 git merge --abort 回到合併前；這只用在目前正在進行的合併，不是一般任務的萬用還原方式。

git diff --check
git add view-mode.txt
git commit -m "Preserve active filter and display label"
node --test tests/model.test.mjs

在整合版本驗收

先確認 view-mode.txt 的兩個值，再檢查 filterTasks 是否保留原資料。若你已把功能接到畫面，還要在瀏覽器切換篩選；只測純函式，不能宣稱介面也完成。這一層驗證可參考完整除錯流程。

比較三個提交：共同基準、各自功能與最終整合。若最後少了其中一個需求，即使所有衝突標記都消失，仍然不算解決成功。相反地，有時 Git 自動合併沒有標記，兩項功能卻在邏輯上互相干擾，因此整合測試不能省略。

整合前確認成果屬於哪一條分支

每個 worktree 都有自己的工作目錄，但仍共享儲存庫的物件與部分設定。整合前先查看各自的分支、提交與未提交差異，避免把尚未保存的成果當成已可合併。若其中一個目錄還有未追蹤檔案，先判斷它是成果或暫存資料。

衝突解決後使用最終檔案重新測試，不能只引用兩條分支合併前的綠燈。最後結果是第三種組合，可能產生單獨分支沒有出現的問題；本課的預設模式與標籤就需要同時保留並核對。

解決衝突時在紀錄寫出保留兩方需求的理由，不只記錄 Git 命令成功。命令成功代表提交完成，功能是否正確仍以最後檔案的行為為準。

清理與故障練習

清理前在每個工作目錄執行 git status，確認沒有未提交成果。只有已保存、已整合且工作目錄乾淨時，才從主要儲存庫移除對應 Worktree。移除工作目錄與刪除分支是兩件事，這裡先保留分支方便追查，不需要立即刪除歷史。

git -C ../filter status --short
git -C ../labels status --short
git worktree remove ../filter
git worktree remove ../labels
git worktree list

故障練習是在 filter 目錄加一個未提交檔，再嘗試移除 Worktree。預期 Git 阻止清理；請先保存或明確處理這個檔案，再重試。不要以強制刪除作為答案，因為這個阻擋正是在提醒你有成果尚未整理。

完成標準是兩個工作目錄曾經獨立運作、受控衝突有紀錄、整合保留雙方需求、測試在最終版本通過，最後沒有遺失未提交資料。小練習可再增加不同埠號的網站預覽，觀察停止其中一個服務是否影響另一個，確認你理解 Git 隔離與執行環境隔離的差別。

需要把責任交給專責代理時，可接續Subagent 審查；支援團隊功能的讀者再看Agent Teams 整合。先掌握可重現的 Git 流程，之後增加代理角色才有可靠的交付基礎。

回 Claude Code 教學總目錄

• AI 工具
• 教學
• Claude Code