Imported from tarrragon/claude (skills/worktree/SKILL.md). Install upstream with npx skills add tarrragon/claude --skill worktree. Copyright stays with the author.

Worktree Management SKILL

統一 Git Worktree 管理工具 — 簡化並行開發流程。

核心功能

管理 git worktree，自動從 Ticket ID 推導分支名和路徑。支援多 Ticket 並行開發時的環境隔離。

Agent isolation worktree（cc 自動建 worktree-agent-*）

本章節說明 Claude Code runtime 自動建立的 agent worktree（與本 SKILL 的人工 /worktree create 為不同來源），重點在殭屍累積的成因與專案 GC 對策。

機制

Claude Code 的 Agent tool 設定 isolation: "worktree" 派發 subagent 時，cc runtime 會自動執行下列動作：

• 在 .claude/worktrees/agent-XXXXXXXX 建立隔離 worktree（XXXXXXXX 為隨機 hash）
• 對應分支命名為 worktree-agent-XXXXXXXX
• 同時對該 worktree 加 git lock，lock reason 內含 cc CLI process 的 PID，目的是阻止 git 自動 GC 在 agent 執行期間誤清

Why：worktree 隔離讓 subagent 的檔案改動與主 repo 解耦，避免並行派發時互相覆蓋；lock + PID 是 cc 對 git GC 的防護，確保長時間 agent 執行不被 git worktree prune 中斷。

Base ref 與隔離邊界（W3-007 / W3-008）

Why：worktree 隔離只改變 agent 的 shell cwd，對「session 啟動時靜態綁定主 repo 根目錄」的寫入工具（dart MCP daemon）不生效，這類工具的寫入會繞過隔離邊界洩漏到主 repo。

ticket 狀態統一寫入主倉庫（2026-09-02 起，刻意設計，非洩漏）

上表「ticket CLI auto-commit 洩漏」列記錄的是 W3-008 當時的問題與當時對策：讓 get_project_root() 具 worktree 感知，使 ticket CLI 的寫入跟隨 agent 所在 worktree。該對策已被後續的架構決策取代——paths.py:get_ticket_state_root()（2026-09-02 新增）現為 ticket 狀態操作（ticket track claim / append-log / check-acceptance 等讀寫 ticket md 與其 auto-commit）的唯一根目錄解析入口，其行為與 get_project_root() 相反：偵測到呼叫端位於 linked worktree 時，反向回推主倉庫根目錄，使 ticket 狀態一律寫入主倉庫，不進 worktree 分支。

Why：若 ticket 狀態沿用 worktree 感知，多個隔離 agent 各自把票面寫入自己的 worktree 分支，PM 在主倉庫看不到最新狀態（觀察性失效），且 body 內容不會隨 worktree 分支合併帶回主倉庫——受控實驗實測並行派發的 worktree agent 全數出現票面分裂。統一寫入主倉庫消除此分裂，ticket 狀態單一事實來源恆為主倉庫。

與程式碼提交的分離：本節僅涵蓋 ticket 狀態（md 讀寫 + auto-commit）。ticket track commit（程式碼提交）維持 resolve_project_cwd 的原 worktree 感知行為不變，程式碼隔離不受影響——worktree agent 的產品碼變更仍 commit 進該 worktree 對應分支，由 PM 之後 git merge 帶回主倉庫。也就是說：程式碼提交走 worktree 分支，ticket 狀態寫入主倉庫，兩者是不同的 root 解析路徑，不會互相影響。

Consequence（agent 誤讀為缺陷時）：worktree 內執行 ticket track full 讀到的內容與主倉庫一致（非該 worktree 自身分支上的 ticket md 版本），這是設計行為，不是 bug；ticket track append-log 等寫入的 commit 會出現在主倉庫的 git log，而非該 worktree 對應分支。誤判為缺陷並嘗試「修復」會反轉此設計，重新引入票面分裂風險。

Action：worktree 內需要讀取「該 worktree 自身分支上的 ticket md 版本」時（例如驗證某次寫入是否落在預期分支），改用 git show <branch>:<path> 或直接 cat 該 worktree working tree 內的檔案，不依賴 ticket track full 的輸出——後者恆讀主倉庫。完整理由見 .claude/skills/ticket/ticket_system/lib/paths.py 的 get_ticket_state_root() docstring；ticket 狀態與程式碼提交分離的說明另見 .claude/skills/ticket/SKILL.md「Ticket 狀態與程式碼提交的 root 分離」節。

殭屍問題

cc runtime 在 agent 結束或 process 異常死亡時不會自動 remove agent worktree。後果：

• 殘留目錄不會自動消失（cc 只 unlock，不 remove，見下方 lock 行為說明）
• .claude/worktrees/ 下殘留 worktree 目錄，累積佔用磁碟空間
• git worktree list 與 statusline 顯示大量無用 entries，干擾人工判讀

Lock 行為（CC v2.1.157 起的變化）：

Why：v2.1.157 起 cc 在 agent 正常結束時主動 unlock worktree（release note：「Worktrees managed by Claude are now left unlocked when the agent finishes」），使 git worktree remove/prune 能直接清理；但異常死亡（process 被 kill / crash）來不及 unlock，仍會殘留 lock，故 unlock 前置步驟對該情境保留。

Consequence：未清理的殭屍 worktree 會無上限累積，每次 cc session 派發 isolation:worktree subagent 都新增一個，數天內可達數十個，污染 git 視圖並佔用 GB 級空間。

Action：依賴下方「專案對策」自動 GC，或在察覺累積時執行「手動清理指令」。

專案對策（W17-119.1 SessionStart hook GC）

本專案在 .claude/skills/worktree/hooks/worktree-zombie-cleanup-hook.py 實作 SessionStart 觸發的自動 GC，邏輯如下：

安全防護：

• worktree 內 dirty 檔案數 != 0 時僅輸出警告，不自動清，避免誤刪未保存改動
• 排除建立時間 < 30 分鐘的 worktree，避免清掉剛啟動還沒來得及註冊的 agent
• 透過環境變數開關，可在偵錯時暫時關閉

Why：SessionStart 是 cc session 入口，每次新 session 都做一次清理可保證殭屍上限不超過上一 session 累積量。

手動清理指令

當自動 GC 失效或要主動清理時，使用以下指令：

# 列出殭屍（PID 已死的 agent worktree lock）
git worktree list --porcelain | grep "^locked" | grep -oE "pid [0-9]+" | awk '{print $2}' | while read p; do
  ps -p $p > /dev/null 2>&1 || echo "$p dead"
done

# 路徑 1（v2.1.157+ 首選）：清理已 unlock 的殘留（正常結束的 agent worktree）
# agent 正常結束已自動 unlock，prune 可直接回收，無需 unlock 前置
git worktree prune

# 路徑 2（異常死亡殘留 lock 時）：強制清所有 agent worktree（謹慎使用：不檢查 dirty）
git worktree list --porcelain | grep "^worktree .*\.claude/worktrees/agent-" | awk '{print $2}' | while read wt; do
  git worktree unlock "$wt" 2>/dev/null
  git worktree remove --force "$wt"
done

Action：第一段指令僅列舉，可安全執行確認殭屍數量；路徑 1（git worktree prune）為 v2.1.157+ 首選，清理正常結束（已 unlock）的殘留，安全且免 unlock 前置；路徑 2 為強制清理（含 unlock），用於異常死亡殘留 lock 的情境，執行前請先用 git worktree list 人工確認沒有正在進行中的 agent。

絆腳索：若 git worktree prune 實測仍因 lock 無法清理某 worktree，表示該 worktree 屬異常死亡殘留 lock，改走路徑 2（unlock + remove --force）。

與人工 /worktree create 的區別

兩者表面都是 git worktree，但來源、生命週期、清理機制完全不同。混淆會導致誤清正在工作的 worktree。

Action：判斷某個 worktree 屬哪一類，看路徑前綴即可（.claude/worktrees/agent- vs ../ccsession-）；自動 GC hook 僅處理前者，後者請使用本 SKILL 的人工流程管理。

EnterWorktree mid-session 切換（CC v2.1.157）

CC v2.1.157 起 EnterWorktree 工具支援在 session 中途切換 Claude-managed worktree（不必重啟 session），前一個 worktree 的工作狀態保留。

Why：可在同一 session 於多個工作目錄間切換（例如特性開發中途切到緊急 bugfix worktree），免去重啟成本。

Consequence（查核必要性反而上升）：mid-session 切換使 cwd 落點更易在無感知下改變。若不確認當前所在 worktree 就 commit / merge，變更可能落到非預期分支（與既有「PM cwd 被 runtime 自動切進 agent worktree」風險同源）。

Action：

切換後 commit/merge 前未查核 → 變更落點不可信，須先 git branch --show-current + pwd 對齊預期再操作。

worktree 不含的狀態（0.2.1-W3-274，框架 issue 46）

核心概念：git worktree 是版本控制層的隔離機制，只複製 git 追蹤的內容（已 commit 或已 staged 的檔案）。任何 .gitignore 排除、或執行期才產生的狀態，都不會隨 worktree 建立而出現在新的工作目錄中。適用於本 SKILL 的人工 /worktree create 與 cc runtime 自動建立的 agent isolation worktree 兩者。

三類典型非 git 狀態

Why：worktree 共享 git object store，但各自的 working directory 是獨立生成的——.gitignore 排除的內容從未進入 git object store，自然不會出現在任何新建立的 worktree 中，與 base 落後 main 幾個 commit 是完全不同的機制（見上方「worktree 快照過舊防護」：該節處理「git 追蹤內容落後多少」，本節處理「git 完全不追蹤的內容從未存在」）。

Consequence：未載明補齊方式時，代理人各自在 worktree 內摸索，成功與否取決於個別代理人是否碰巧試出正確命令，同一問題在不同代理人間重複發生而無人留下可複用記錄（框架 issue 46 症狀一實證：四個代理人三個撞牆且回報各異，有解法但不在任何文件或 prompt 中）。

Action：具體前置命令屬於 consumer 專案知識（依語言/框架/套件管理器而異），本 SKILL 不列舉任何專案專屬命令字面。consumer 專案應：

1. 在專案層文件（CLAUDE.md 對應章節或 scripts/ 下的腳本）記錄本專案 worktree 建立後所需的前置命令
2. 派發需在 worktree 內執行測試/建置的 agent 時，在派發 prompt 引用該文件——見 .claude/references/agent-dispatch-template.md「環境前置欄位」

例外：可自動補齊的 gitignore 排除產物——當缺漏檔案內容為固定樣板（無機器相依內容，可用固定字串重建，非真正的本機產物）時，worktree_manager.py 的 create 子命令會直接寫入補齊，不需 agent 手動介入。目前涵蓋：macOS 平台的 macos/Flutter/Flutter-Debug.xcconfig、Flutter-Release.xcconfig（僅 #include 相對路徑，Flutter 官方樣板固定內容）。此類補齊僅在 worktree 內偵測到對應平台目錄（如 macos/Flutter/）時才動作，對不含該平台的專案為無操作（no-op），不違反上述「不列舉專案專屬命令」原則——此為程式碼層的 opinionated default，非文件字面列舉。CocoaPods（Pods/ 目錄）因需網路且耗時，不自動執行 pod install，create 完成時僅輸出提示指令。

快速開始

建立 Worktree

/worktree create 1.0.0-W9-002.1

自動建立：

• 分支：feat/1.0.0-W9-002.1
• Worktree：../ccsession-1.0.0-W9-002.1

建立完成後輸出 cd 指令，一鍵切換工作環境。

查看 Worktree 狀態

# 查看所有 worktree
/worktree status

# 查看特定 Ticket 的 worktree
/worktree status 1.0.0-W9-002.1

顯示：

• 路徑和分支
• 相對於 main 的 commit 領先/落後情況
• 未 commit 的變更數

子命令詳細說明

create — 建立 Worktree

/worktree create <ticket-id> [--base <branch>] [--dry-run]

參數

推導規則

Ticket ID 自動推導為：

成功範例

$ /worktree create 1.0.0-W9-002.1

正在建立 worktree...
  Ticket: 1.0.0-W9-002.1
  分支:   feat/1.0.0-W9-002.1
  基礎:   main
  路徑:   /path/to/project-1.0.0-W9-002.1

建立成功。

下一步：
  cd /path/to/project-1.0.0-W9-002.1
正在同步最新 main...
main 無新變更，worktree 已是最新。

建立完成後會確定性執行一次 git merge main（issue #77 決議 A）：共享 .git 下 local main 為全機單一事實來源，此步驟消除 base 解析與 worktree 可用之間、其他 worktree 併行推進 main 的競態視窗。無新變更時為 no-op； 有衝突時會停下並輸出後果與下一步（不自動解），見下方「錯誤情境」表最後一列。

錯誤情境

status — 查看 Worktree 狀態

/worktree status [<ticket-id>]

參數

成功範例（無參數，顯示全部）

$ /worktree status

Worktree 狀態（共 3 個）
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[主倉庫]
  路徑：   /path/to/project
  分支：   main
  變更：   0 個未 commit

[1.0.0-W9-002.1]
  路徑：   /path/to/project-1.0.0-W9-002.1
  分支：   feat/1.0.0-W9-002.1
  領先：   +3 commits ahead of main
  落後：   -0 commits behind main
  變更：   2 個未 commit

[1.0.0-W9-002.2]
  路徑：   /path/to/project-1.0.0-W9-002.2
  分支：   feat/1.0.0-W9-002.2
  領先：   +1 commits ahead of main
  落後：   -1 commits behind main
  變更：   0 個未 commit

成功範例（指定 ticket-id）

$ /worktree status 1.0.0-W9-002.1

[1.0.0-W9-002.1]
  路徑：   /path/to/project-1.0.0-W9-002.1
  分支：   feat/1.0.0-W9-002.1
  領先：   +3 commits ahead of main
  落後：   -0 commits behind main
  變更：   2 個未 commit

無 Worktree 範例

$ /worktree status

目前沒有任何 worktree（除主倉庫外）。

建立新的 worktree：
  /worktree create <ticket-id>

使用場景

場景 1：新 Ticket 開發

# 1. 收到 Ticket 1.0.0-W9-002.1
# 2. 建立 worktree（自動推導名稱）
/worktree create 1.0.0-W9-002.1

# 3. 一鍵切換環境
cd /path/to/project-1.0.0-W9-002.1

# 4. 開始開發...

場景 2：多 Ticket 並行開發

# 建立多個 worktree（隔離環境）
/worktree create 1.0.0-W9-002.1
/worktree create 1.0.0-W9-002.2
/worktree create 1.0.0-W9-002.3

# 查看整體狀態
/worktree status

# 查看特定 Ticket 進度
/worktree status 1.0.0-W9-002.1

場景 3：檢查進度

# 在任何 worktree 中執行，檢查全局狀態
/worktree status

# 確認該 Ticket 有多少未提交變更
/worktree status 1.0.0-W9-002.1

與 Hook 系統的整合

branch-verify-hook

在保護分支（main）上編輯時：

• 允許：.claude/、docs/ 路徑的編輯（規則更新、文件維護）
• 阻止：程式碼路徑編輯（如 ui/lib/main.dart）
• 建議：使用 /worktree create <ticket-id> 建立隔離環境

branch-status-reminder

Session 啟動時：

• 正確環境（在 worktree + allowed 分支）→ 靜默
• 異常環境（主倉庫保護分支）→ 警告 + 建議使用 /worktree create

常見問題

Q: Worktree 與分支的對應關係是什麼？

A: 一個 worktree = 一個獨立的分支 + 隔離的檔案系統。

• 建立 worktree 時同時建立分支
• 多個 worktree 間檔案變更隔離
• 每個 worktree 有獨立的 git working directory

Q: 能否指定 base 分支？

A: 支援。使用 --base 參數：

/worktree create 1.0.0-W9-002.1 --base develop

Q: Dry-run 模式有什麼用？

A: 檢查將要執行的 git 命令，不實際建立分支和 worktree。適合驗證操作是否正確。

/worktree create 1.0.0-W9-002.1 --dry-run

Q: 如何刪除 Worktree？

A: 使用 git 命令（本 SKILL 暫不支援刪除）：

# 刪除 worktree（保留分支）
git worktree remove ../ccsession-1.0.0-W9-002.1

# 刪除分支
git branch -d feat/1.0.0-W9-002.1

參考資料

• Git Worktree 官方文件：https://git-scm.com/docs/git-worktree

修改 source 後無需重新安裝（shim 化）

重要：本 skill 已改用 cwd-resolving shim（ARCH-APP-002 / framework issue #12），不再走 uv tool install。shim 每次執行都 uv run --directory .claude/skills/worktree 當前專案源碼，修改 source 後改動即時生效，無 stale installed 問題（取代舊 uv-tool-staleness-check-hook 機制）。

檢查 / 安裝指令：

# 安裝 / 更新 shim（一次安裝 ticket / doc / worktree）
python3 .claude/scripts/install-skill-clis.py

# 檢查是否已 shim 化（exit 0/1）
python3 .claude/scripts/install-skill-clis.py --check

版本紀錄在同目錄的 CHANGELOG.md。