Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback
使用 Git Worktrees
概述
確保工作在隔離的工作區中進行。優先使用平台的原生 worktree 工具。僅在沒有原生工具可用時，才回退到手動 git worktree。
核心原則： 先偵測現有隔離。然後使用原生工具。最後才回退到 git。切勿與框架對抗。
開始時宣告： 「我正在使用 using-git-worktrees 技能來設定隔離的工作區。」
步驟 0：偵測現有隔離
在建立任何東西之前，先檢查你是否已經在隔離的工作區中。
GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
BRANCH=$(git branch --show-current)
子模組防護： GIT_DIR != GIT_COMMON 在 git 子模組內部也會成立。在得出「已在 worktree 中」的結論前，請確認你不在子模組中：
# 如果此命令回傳路徑，表示你在子模組中，而非 worktree — 視為一般儲存庫
git rev-parse --show-superproject-working-tree 2>/dev/null
如果 GIT_DIR != GIT_COMMON（且非子模組）： 你已經在一個連結的 worktree 中。跳到步驟 2（專案設定）。不要建立另一個 worktree。
回報分支狀態：
- 在分支上：「已在
<path>的隔離工作區中，位於分支<name>。」 - 分離 HEAD：「已在
<path>的隔離工作區中（分離 HEAD，外部管理）。需要在完成時建立分支。」
如果 GIT_DIR == GIT_COMMON（或在子模組中）： 你處於一般儲存庫的 checkout 中。
使用者的指令中是否已指定 worktree 偏好？如果沒有，請在建立 worktree 前徵求同意：
「您希望我設定一個隔離的 worktree 嗎？它可以保護您目前的分支不受變更影響。」
若已有宣告的偏好，則直接遵循，無需詢問。如果使用者拒絕同意，則在原地工作並跳到步驟 2。
步驟 1：建立隔離工作區
你有兩種機制。請依此順序嘗試。
1a. 原生 Worktree 工具（優先）
使用者已要求隔離工作區（步驟 0 同意）。你是否有建立 worktree 的方式？可能是名為 EnterWorktree、WorktreeCreate 的工具，或 /worktree 指令，或 --worktree 旗標。如果有，請使用它並跳到步驟 2。
原生工具會自動處理目錄放置、分支建立和清理。當你有原生工具時使用 git worktree add 會產生框架無法看見或管理的幽靈狀態。
只有在沒有原生 worktree 工具可用時，才繼續進行步驟 1b。
1b. Git Worktree 備援方案
僅在步驟 1a 不適用時使用 — 你沒有可用的原生 worktree 工具。使用 git 手動建立 worktree。
目錄選擇
依此優先順序進行。明確的使用者偏好永遠優先於觀察到的檔案系統狀態。
-
檢查你的指令中是否有宣告的 worktree 目錄偏好。 如果使用者已指定，直接使用，無需詢問。
-
檢查是否存在專案本地的 worktree 目錄：
ls -d .worktrees 2>/dev/null # 偏好（隱藏） ls -d worktrees 2>/dev/null # 替代如果找到，使用它。如果兩者都存在，
.worktrees優先。 -
如果沒有其他指引，預設使用專案根目錄下的
.worktrees/。
安全性驗證（僅限專案本地目錄）
在建立 worktree 前必須確認目錄已被忽略：
git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
如果未被忽略： 加入 .gitignore，提交變更，然後繼續。
為何重要： 防止意外將 worktree 內容提交到儲存庫。
建立 Worktree
# 根據選擇的位置決定路徑
path="$LOCATION/$BRANCH_NAME"
git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"
沙箱備援： 如果 git worktree add 因權限錯誤（沙箱拒絕）而失敗，告知使用者沙箱封鎖了 worktree 建立，你將改在目前目錄中工作。然後在原地執行設定和基準測試。
步驟 2：專案設定
自動偵測並執行適當的設定：
# Node.js
if [ -f package.json ]; then npm install; fi
# Rust
if [ -f Cargo.toml ]; then cargo build; fi
# Python
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
if [ -f pyproject.toml ]; then poetry install; fi
# Go
if [ -f go.mod ]; then go mod download; fi
步驟 3：驗證乾淨基準
執行測試以確保工作區從乾淨狀態開始：
# 使用專案適用的指令
npm test / cargo test / pytest / go test ./...
如果測試失敗： 回報失敗，詢問是否繼續或調查。
如果測試通過： 回報就緒。
回報
Worktree ready at <full-path>
Tests passing (<N> tests, 0 failures)
Ready to implement <feature-name>
快速參考
| 情況 | 動作 |
|---|---|
| 已在連結的 worktree 中 | 跳過建立（步驟 0） |
| 在子模組中 | 視為一般儲存庫（步驟 0 防護） |
| 有原生 worktree 工具可用 | 使用它（步驟 1a） |
| 無原生工具 | Git worktree 備援（步驟 1b） |
.worktrees/ 存在 |
使用它（確認已忽略） |
worktrees/ 存在 |
使用它（確認已忽略） |
| 兩者都存在 | 使用 .worktrees/ |
| 兩者都不存在 | 檢查指令檔案，然後預設 .worktrees/ |
| 目錄未被忽略 | 加入 .gitignore 並提交 |
| 建立時權限錯誤 | 沙箱備援，在原地工作 |
| 基準測試失敗 | 回報失敗並詢問 |
| 無 package.json/Cargo.toml | 跳過相依性安裝 |
常見錯誤
與框架對抗
- 問題： 當平台已提供隔離時仍使用
git worktree add - 修正： 步驟 0 偵測現有隔離。步驟 1a 優先使用原生工具。
跳過偵測
- 問題： 在現有 worktree 內部建立巢狀 worktree
- 修正： 在建立任何東西之前，務必執行步驟 0
跳過忽略驗證
- 問題： Worktree 內容被追蹤，污染 git 狀態
- 修正： 在建立專案本地 worktree 之前，務必使用
git check-ignore
假設目錄位置
- 問題： 造成不一致，違反專案慣例
- 修正： 遵循優先順序：明確指令 > 現有專案本地目錄 > 預設
在測試失敗時繼續
- 問題： 無法區分新錯誤與既有問題
- 修正： 回報失敗，取得明確許可後再繼續
紅旗
絕不：
- 在步驟 0 偵測到現有隔離時建立 worktree
- 當你有原生 worktree 工具（例如
EnterWorktree）時使用git worktree add。這是 #1 錯誤 — 如果有，就使用它。 - 跳過步驟 1a 直接跳到步驟 1b 的 git 指令
- 未確認 worktree 已被忽略（專案本地）就建立
- 跳過基準測試驗證
- 在測試失敗時未經詢問就繼續
務必：
- 先執行步驟 0 偵測
- 優先使用原生工具而非 git 備援
- 遵循目錄優先順序：明確指令 > 現有專案本地目錄 > 預設
- 確認專案本地目錄已被忽略
- 自動偵測並執行專案設定
- 驗證乾淨的測試基準
