tarrragon Worktree Management SKILL
統一 Git Worktree 管理工具 — 簡化並行開發流程。
核心功能
管理 git worktree，自動從 Ticket ID 推導分支名和路徑。支援多 Ticket 並行開發時的環境隔離。
Agent isolation worktree（cc 自動建 worktree-agent-*）
完整行為說明（機制、base ref 陷阱、dart MCP 洩漏、ticket 狀態 root 分離、殭屍清理、EnterWorktree mid-session 切換）：
references/agent-isolation-worktree.md（按需讀取）。本節僅速查表，逐項路由。
cc runtime 派發 isolation: "worktree" 的 subagent 時自動建立隔離 worktree（.claude/worktrees/agent-XXXXXXXX，分支 worktree-agent-XXXXXXXX，附 PID lock），與本 SKILL 的人工 /worktree create 為不同來源。目的是讓 subagent 檔案改動與主 repo 解耦，避免並行派發互相覆蓋。
| 議題 | 一行結論 | 詳見 references 節 |
|---|---|---|
| worktree base 落點 | base 取自 origin/main（非 local main HEAD），落後時建在 stale 基底；派發前先 push |
〈Base ref 與隔離邊界〉 |
| dart MCP 寫入洩漏 | daemon root 綁主 repo，worktree 內禁用 dart MCP 寫入工具，改 Bash dart fix/dart format 或 Edit |
〈Base ref 與隔離邊界〉 |
| ticket 狀態該寫哪 | ticket md 讀寫恆落主倉庫（刻意設計，非洩漏）；程式碼提交才走 worktree 分支，ticket track commit 需帶 --worktree |
〈ticket 狀態統一寫入主倉庫〉 |
| 殭屍累積 | cc 結束不自動 remove，累積佔磁碟；本專案有 SessionStart hook 自動 GC | 〈殭屍問題〉〈手動清理指令〉 |
| 與人工 /worktree create 的區別 | 路徑/分支/生命週期/清理機制皆不同，判別看路徑前綴（.claude/worktrees/agent- vs ../ccsession-） |
〈與人工 /worktree create 的區別〉 |
| EnterWorktree mid-session 切換 | v2.1.157 起可中途切換 worktree；切換後須 git branch --show-current + pwd 查核再 commit/merge |
〈EnterWorktree mid-session 切換〉 |
Action：遇上述議題任一者，先查 references 對應節再處置，不要憑印象操作。
worktree 不含的狀態（0.2.1-W3-274，框架 issue 46）
核心概念：git worktree 是版本控制層的隔離機制，只複製 git 追蹤的內容（已 commit 或已 staged 的檔案）。任何
.gitignore排除、或執行期才產生的狀態，都不會隨 worktree 建立而出現在新的工作目錄中。適用於本 SKILL 的人工/worktree create與 cc runtime 自動建立的 agent isolation worktree 兩者。
三類典型非 git 狀態
| 類別 | 說明 | 典型症狀（未補齊時） |
|---|---|---|
| gitignore 排除的產物 | 建置或套件管理工具產生但被 .gitignore 排除的檔案或目錄 |
測試/建置找不到對應資源，錯誤訊息通常不直接指向「worktree 缺此目錄」這個根因 |
| 建置快取 | 編譯器/工具鏈的中介快取（非追蹤內容，重建耗時但非必要進 git） | 首次建置變慢，或依賴快取的步驟失敗 |
| 依賴目錄 | 套件管理器安裝的第三方依賴（通常 .gitignore 排除，體積大不適合進 git） |
依賴解析/引用失敗 |
Why：worktree 共享 git object store，但各自的 working directory 是獨立生成的——.gitignore 排除的內容從未進入 git object store，自然不會出現在任何新建立的 worktree 中，與 base 落後 main 幾個 commit 是完全不同的機制（見 references/agent-isolation-worktree.md〈Base ref 與隔離邊界〉：該節處理「git 追蹤內容落後多少」，本節處理「git 完全不追蹤的內容從未存在」）。
Consequence：未載明補齊方式時，代理人各自在 worktree 內摸索，成功與否取決於個別代理人是否碰巧試出正確命令，同一問題在不同代理人間重複發生而無人留下可複用記錄（框架 issue 46 症狀一實證：四個代理人三個撞牆且回報各異，有解法但不在任何文件或 prompt 中）。
Action：具體前置命令屬於 consumer 專案知識（依語言/框架/套件管理器而異），本 SKILL 不列舉任何專案專屬命令字面。consumer 專案應：
- 在專案層文件（
CLAUDE.md對應章節或scripts/下的腳本）記錄本專案 worktree 建立後所需的前置命令 - 派發需在 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 的變更數
子命令詳細說明
完整參數表、推導規則、成功範例與錯誤情境：
references/subcommands.md（按需讀取）。本節保留於〈快速開始〉的最小指令示範已足夠日常使用；需要查特定參數或錯誤訊息時才讀該檔。
create：建立 worktree，見references/subcommands.md〈create — 建立 Worktree〉status：查看 worktree 狀態，見references/subcommands.md〈status — 查看 Worktree 狀態〉
使用場景
場景 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。