概觀
using-git-worktrees 是什麼？
using-git-worktrees 是來自 obra/superpowers 儲存庫的工作流程技能，會引導你建立用於功能開發的隔離 Git worktrees。它將 worktree 建立的位置與方式標準化，讓你可以同時在多個分支上安全工作，而不需要一直在同一個工作目錄裡切換分支。
與其手動猜測 worktree 應該放在哪裡、或冒著產生未追蹤又未忽略目錄的風險，這個技能把一套清楚的目錄選擇與驗證流程寫死在流程裡。目標是為實作工作提供可靠的隔離，同時維持主要專案樹乾淨整潔。
這個技能適合誰？
這個技能是為下列開發者設計的：
- 同時處理多個功能或修補工作
- 想在不同專案之間維持一致、可重複使用的 Git worktree 慣例
- 希望確認 worktree 目錄放的位置正確，不會汙染 commits
- 使用指令列版 Git，且能輕鬆執行基本 shell 指令
特別適合想要有文件化且一致 Git 工作流程的團隊，也適合希望用更安全方式啟動暫時或長期功能環境的情境。
using-git-worktrees 解決了哪些問題？
using-git-worktrees 協助你避免在操作多個分支時常見的問題：
- 頻繁切換分支的成本： 可以同時在多個分支上工作，而不用一直 stash、checkout 來回切換。
- 專案根目錄變得凌亂： 避免隨手在亂七八糟的位置建立臨時資料夾和 worktree 目錄。
- 誤把 worktree 目錄 commit 進去： 流程會強調在建立 worktree 前先確認本機 worktree 目錄有被忽略。
- 不同機器之間慣例不一致： 透過檢查現有目錄和
CLAUDE.md中的選用偏好，這個技能會推動你在每個專案採用統一的目錄佈局。
如果你經常使用 Git worktrees，或準備開始安全地使用它們，這個技能提供一套輕量、具明確觀點的操作流程。
什麼情況下適合使用 using-git-worktrees？
你可以在下列情況使用 using-git-worktrees：
- 你準備開始一個需要與目前工作空間隔離的功能開發。
- 你打算依照既有設計或規劃開始實作，希望有乾淨的 worktree 來執行。
- 你的儲存庫已經使用
.worktrees或worktrees目錄，並希望延續這個慣例。
在下列情況可能比較幫不上忙：
- 你一次只會在單一分支上工作，不需要多份工作複本。
- 你已經有嚴格且自動化的內部工具，以不同方式管理 worktrees。
在其他大多數情境下，導入 using-git-worktrees 的流程，都能讓你的 Git 工作模式更可預期也更安全。
使用方式
安裝與基本設定
想在你的環境加入 using-git-worktrees 技能，請從 obra/superpowers 儲存庫安裝：
npx skills add https://github.com/obra/superpowers --skill using-git-worktrees
安裝完成後：
- 在儲存庫的 checkout 中開啟
skills/using-git-worktrees/SKILL.md檔案。 - 從頭到尾讀過一次，了解目錄選擇與安全驗證的步驟。
- 確認你目前位於一個你願意在其中建立額外 worktree 目錄的 Git 儲存庫裡。
除了 Git 與可執行技能說明中指令的 shell 之外，你不需要額外相依套件。
核心流程：開始隔離的功能開發
當你要啟動新功能開發並希望使用隔離工作空間時，可以依照 using-git-worktrees 所定義的高層流程進行：
-
宣告你要使用這個流程（給自己，也給任何助理或工具）：
"I'm using the using-git-worktrees skill to set up an isolated workspace."
-
決定 worktree 目錄，依照目錄選擇流程（見下一節）。這能避免在任意路徑亂丟 worktrees。
-
執行安全驗證，依照選定目錄的類型（專案本地 vs. 全域）做合適的檢查。這是避免誤把 worktree 目錄 commit 進去的關鍵步驟。
-
為需要的分支建立 Git worktree。例如：
git worktree add <path-to-worktree> <branch-name> -
切換到新的 worktree，在裡面進行實作工作，保持原本的工作複本乾淨並可隨時拿來做 code review、快修或其他任務。
每當你要開始新的功能、技術 spike 或實驗，且不希望干擾目前工作目錄時，就可以重複這個流程。
目錄選擇流程
using-git-worktrees 定義了一套有結構的目錄選擇順序，讓你永遠知道 worktrees 該放在哪裡，而不需要每次重頭思考。
1. 優先使用既有的 worktree 目錄
在儲存庫 root 執行以下指令，依優先順序檢查建議的 worktree 目錄：
ls -d .worktrees 2>/dev/null # Preferred (hidden)
ls -d worktrees 2>/dev/null # Alternative
- 如果
.worktrees存在，就用它。 - 如果沒有
.worktrees但有worktrees，就用worktrees。 - 如果兩者都沒有，進入下一步。
這個規則可以讓你在同一個專案內跟既有決定保持一致。
2. 在 CLAUDE.md 裡檢查專案偏好設定
如果沒有標準的 worktree 目錄，請在專案根目錄的 CLAUDE.md 檔案裡尋找是否有偏好設定：
grep -i "worktree.*director" CLAUDE.md 2>/dev/null
如果 CLAUDE.md 有寫明 worktree 目錄慣例，就直接採用，不需要再多問。這讓專案可以集中記錄偏好的 worktree 佈局。
3. 完全沒有偏好時，詢問並選定新位置
如果沒有現成目錄，CLAUDE.md 又沒有記錄偏好，就要明確選擇新的 worktree 放置位置。技能建議用清楚的選項提供給你自己（或團隊）：
No worktree directory found. Where should I create worktrees?
1. .worktrees/ (project-local, hidden)
2. ~/.config/superpowers/worktrees/<project-name>/ (global location)
Which would you prefer?
- 選項 1：
.worktrees/讓 worktrees 跟專案放在一起，預設隱藏，也容易在 repo 內找到。 - 選項 2：
~/.config/superpowers/worktrees/<project-name>/則是把每個專案的 worktrees 集中放在 repo root 之外，如果你想讓 Git 工作目錄在視覺上維持精簡，會很實用。
一旦選定其中一個選項，之後在同一專案中就持續使用那個位置，避免分散。
建立 worktree 前的安全驗證
using-git-worktrees 特別強調安全檢查，尤其當你使用位在 Git 儲存庫內的專案本地目錄時。
驗證專案本地目錄有被忽略
對於 .worktrees 或 worktrees 這類專案本地目錄，要在其中建立 worktree 之前，務必先確認它們已被 Git 忽略。這在技能中被標為 必須（MUST） 的條件。
至少應該：
- 確認
.worktrees或worktrees有被寫在合適的 ignore 檔中（.gitignore、.git/info/exclude或全域 ignore 檔），且 - 使用
git check-ignore確認在目前設定下，Git 真的會忽略該目錄。
典型的做法是對該目錄路徑執行 git check-ignore，確認 Git 依照本地、全域與系統 ignore 設定把它視為忽略項目。
如果目錄沒有被忽略：
- 把它加入適當的 ignore 檔；如果應該被版本控制，就把 ignore 規則一併 commit，然後
- 在該位置建立任何 worktree 之前，重新執行檢查。
這可以降低 worktree 基礎設施被誤加入暫存或 commit 的風險。
安全使用全域位置
如果你選擇全域目錄選項（例如 ~/.config/superpowers/worktrees/ 底下），這些目錄位於儲存庫之外，也不會被 Git 追蹤。這種情況下，忽略規則就沒那麼關鍵，不過仍然建議你確認：
- 路徑在不同機器間是否穩定，或至少有文件說明給團隊成員使用。
- 磁碟空間足夠容納多個完整 worktrees。
持續執行這些驗證步驟，可以讓你的 Git 歷史聚焦在原始碼變更，而不是工具產生的副產品。
將技能調整成符合你工作流程的做法
using-git-worktrees 刻意設計得輕量且以儲存庫為中心。你可以這樣把它整合進更廣泛的工作流程：
- 在專案的貢獻指南或新成員上線文件中，寫明你最終選定的 worktree 目錄。
- 考慮在
CLAUDE.md裡加上一小節，描述整個團隊如何使用 Git worktrees。 - 如果想要「一個指令就能完成設定」，可以把目錄選擇與安全驗證步驟包成自己的 shell script，同時把原本的規則當作權威準則。
這個技能的定位是清楚的參考實作，你可以照單全收，也可以在理解原則後再調整成符合你環境的版本。
常見問題（FAQ）
using-git-worktrees 相較於一般 Git checkout 的主要好處是什麼？
using-git-worktrees 透過建立額外的工作目錄（worktrees），讓你更容易同時處理多個分支，這些 worktrees 會共用同一套 Git 歷史。與其在單一目錄裡不斷 checkout 和 stash，你可以讓每個功能或修補有自己的獨立工作空間，並透過一致的目錄選擇與安全流程來管理。
我要如何安裝 using-git-worktrees 技能？
從 obra/superpowers 儲存庫安裝這個技能：
npx skills add https://github.com/obra/superpowers --skill using-git-worktrees
安裝後，在本機的 checkout 中打開 skills/using-git-worktrees/SKILL.md，依照裡面的詳細流程操作。
我需要大幅調整現有的 Git 工作流程才能使用這個技能嗎？
不需要大改你的整體流程。using-git-worktrees 只聚焦在「如何啟動與管理隔離工作空間」。你仍然可以照原本習慣進行 commit、rebase、push；這個技能主要是標準化你建立 worktrees 的位置與方式，並確保它們以安全方式放置。
using-git-worktrees 可以用在任何 Git 儲存庫上嗎？
可以，只要該儲存庫本身支援 Git worktrees 即可。這個技能只仰賴標準 Git 指令和 shell 工具。為了得到最佳效果，請從儲存庫 root 執行目錄檢查，並依建議為任何專案本地 worktree 目錄設定 ignore 規則。
如果我的專案已經有自己的 worktree 慣例怎麼辦？
如果你的專案已經使用 .worktrees、worktrees，或在 CLAUDE.md 中記錄了慣例，using-git-worktrees 會透過目錄選擇規則自然沿用這些偏好。如果完全是另一套慣例，你仍然可以直接採用這個技能所提倡的原則（清楚的目錄選擇與安全檢查），再指向你現有的目錄佈局。
using-git-worktrees 適合大型或長期維運的專案嗎？
適合。對於有多個長期分支的大型專案，這個技能特別有用。它有結構的目錄選擇流程與對 ignore 規則的重視，可以在長時間累積許多 worktrees 的情況下，仍然保持儲存庫井然有序。
什麼時候我可以不用 using-git-worktrees？
如果你很少同時在多個分支上工作，或團隊已經在用另一套專門的工具管理 worktrees 並強制其自己的目錄慣例，那這個技能帶來的額外結構，可能不足以讓你願意改變既有習慣。
我在哪裡可以看到這個技能的原始定義？
using-git-worktrees 的權威定義位於 GitHub 上 obra/superpowers 儲存庫中的 skills/using-git-worktrees 目錄下的 SKILL.md 檔案。若要取得最精準與最新的行為說明，請以該檔案為準。