---
status: accepted
---

# 以集中式雜湊路徑的 worktree 隔離平行工作包

`/sdlc-feat` 與 `/sdlc-fix` 一律在獨立的 worktree 上工作，而非在同一個工作目錄上切換分支；worktree 集中於 `~/.tea-sdlc/worktrees/{hash}`，`hash` 為正規化後 `owner/repo/分支名` 的 sha256 前 12 碼。這麼做的核心理由是 agent 非同步讀檔：它可能在分支被切走之後才去讀，而它不會察覺自己讀到的是別顆工作包的程式碼，產出看似合理卻接錯上下文——前兩種常見損耗（未提交變更擋路、建置產物跨分支混淆）人會當場發現，這一種不會，所以規則是「一律」而非「有衝突才用」。

## Considered Options

- **repo 內的 `.worktrees/`**：未被忽略時會出現在目標專案的 `git status`，而要它不出現就得改目標專案的忽略設定——本 plugin 明文不修改目標專案的檔案。
- **目標 repo 的兄弟目錄**：不污染 repo，但會在使用者的專案父目錄長出一堆目錄，而那個目錄結構屬於使用者，不屬於這個工具。
- **把分支名的斜線攤平成 `-` 當目錄名**：`feat/a-b/main` 與 `feat/a/b/main` 會撞成同一個名字，而既有的分支命名規則（`{類型}/{需求描述}/{功能描述}`）恰好讓這種形狀有機會出現。
- **目錄名加可讀後綴**：被否決，因為 `git worktree list` 本來就會把分支名印在路徑旁邊，可讀性缺口有限。

## Consequences

- 路徑由工作包**純函式推導**，不需要任何本機對照表或狀態檔，因此換機器或換 agent 之後推導結果相同；推導不到就重建，這正是「不寫入任何本機狀態檔」這條既有約束所要求的接手方式。
- `git worktree add` 仍會在目標 repo 的 `.git/worktrees/` 底下寫中繼資料。這是 git 的機制，無法避免。「不修改目標專案的檔案」指的是專案內容檔，不含 git 自身的內部中繼資料——這條界線是本決策劃定的。
- 目錄名是雜湊，光看路徑字串認不出是哪顆工作包。緩解來自兩處：`git worktree list` 印出分支名，PR 檢查腳本回報推導出的路徑。
- 正規化（小寫、去前後空白）是必要的：沒有它，同一棵 worktree 會因輸入大小寫或多一個空白而被推導成兩個不同路徑。