using-git-worktrees

using-git-worktrees 技能總覽

using-git-worktrees 技能的作用是什麼

using-git-worktrees 技能會協助代理在開始新工作時，建立獨立的 Git worktree，而不是直接重用你目前的 checkout。它真正處理的不只是「執行 git worktree add」，而是會先選擇合理的目錄、確認本機 worktree 資料夾已被安全忽略，並避免污染主要工作目錄。

哪些人適合安裝

這個技能特別適合經常需要以下工作方式的人：

• 開始新功能開發時，保留目前變更不受影響
• 平行檢視或實作多個分支
• 希望 AI 協助寫程式時更安全、降低來回切 branch 的風險
• 需要一套可重複使用的方法，在不同專案中建立隔離工作空間

如果你常對助理說「這個請在獨立 branch 開始」或「不要動到我現在這棵 tree」，那麼 using-git-worktrees 會非常合適。

要解決的核心工作

使用者真正要的是同一件事：在盡量少出設定錯誤的前提下，於隔離工作空間中開始實作。using-git-worktrees 技能之所以有用，是因為它在建立前多了一層判斷流程：

• 若專案已經有 worktree 目錄，優先沿用
• 若 CLAUDE.md 有記錄 repo 偏好的位置，則遵循該設定
• 如果沒有安全的預設值，會先詢問使用者
• 若要在專案內建立 worktree，會先驗證 ignore 行為

因此它比那種直接跳到 shell 指令的通用 prompt 更可靠。

它與一般 prompt 的差異在哪裡

一般 prompt 可能知道 Git worktree 的概念，但仍然會漏掉 repo 特定的設定細節。這個技能為代理提供了明確的操作順序與安全檢查，尤其是在目錄放置與 .gitignore 處理上。這也是 using-git-worktrees for Git Workflows 最主要的差異：減少安裝與建立時的猜測，不是提供更多 Git 理論。

什麼情況下不適合用這個技能

以下情況可以略過 using-git-worktrees：

• 你永遠只在單一 branch、單一目錄工作
• 你的環境不允許建立額外工作目錄
• 你只是想快速切 branch，不需要隔離執行環境
• 你的團隊已經有固定 wrapper script，完整取代了這套判斷邏輯

這些情況下，直接下 shell 指令或沿用內部流程通常更快。

如何使用 using-git-worktrees 技能

安裝 using-git-worktrees 的情境與方式

請從 obra/superpowers 技能集合安裝：

npx skills add https://github.com/obra/superpowers --skill using-git-worktrees

安裝後，當你準備開始一項不該重用目前 checkout 的工作時，就可以使用它。

使用者實際上會怎麼叫用這個技能

repo 中明確表示，代理在開始時應先宣告要使用這個技能。實務上，你的請求最好把「需要隔離」說清楚，例如：

• 「Use using-git-worktrees and set up an isolated workspace for this feature.」
• 「Before implementing, create a worktree for branch feature/auth-refresh.」
• 「Use the using-git-worktrees skill so my current changes stay untouched.」

這樣更能提高代理照著技能執行、而不是臨場自行發揮的機率。

這個技能需要哪些輸入

若想得到較好的結果，建議提供：

• 目標 branch 名稱
• 這是新 branch 還是既有 branch
• 你偏好使用專案內還是全域的 worktree 儲存位置
• repo 特定限制，例如「必須放在 project root 底下」

最低限度、但仍有用的輸入：

• branch／任務名稱
• 允許建立 worktree

更理想的輸入：

• branch 名稱
• 希望採用的目錄策略
• 目前 checkout 是否有未提交變更
• 建立完成後接下來要做什麼，例如「然後開始實作」

內建的目錄選擇邏輯

using-git-worktrees skill 最有價值的地方，在於它的目錄選擇流程。優先順序如下：

1. 如果 .worktrees 已存在，就使用它
2. 否則若 worktrees 已存在，就使用它
3. 否則檢查 CLAUDE.md 是否有記錄偏好
4. 若以上都沒有，則詢問使用者要選哪一個：
   • .worktrees/
   • ~/.config/superpowers/worktrees/<project-name>/

這一點很重要，因為如果每次工作階段都隨意新建位置，worktree 很快就會四散失控，後續維護會很麻煩。

在專案內建立前的安全檢查

一個關鍵採用細節是：如果 worktree 會建立在 repository 內，這個技能會要求先確認該目錄已被 ignore，才會真正建立。這能避免 worktree 資料夾被意外納入追蹤，或讓 git status 輸出變得雜亂。

這是它相較臨時手動操作的一項實際優勢。如果你的團隊預期使用專案內 worktrees，請先確保 .worktrees/ 或 worktrees/ 已被 Git 忽略，再依賴這套流程。

適合 using-git-worktrees 的強 prompt 寫法

較弱的 prompt：

• 「Start working on OAuth cleanup.」

較強的 prompt：

• 「Use using-git-worktrees to create an isolated workspace for new branch feature/oauth-cleanup. Prefer .worktrees/ if safe and ignored. After setup, begin implementation without touching my current checkout.」

為什麼這樣更好：

• 直接點名技能
• 指定 branch 目標
• 說明目錄偏好
• 告訴代理建立完成後下一步要做什麼

建立完成後建議的工作流程

一個實用的 using-git-worktrees usage 流程如下：

1. 先要求代理使用這個技能
2. 確認 worktree 位置與 branch 名稱
3. 要求代理把工作切換到新的工作空間
4. 之後才開始編輯、測試或規劃實作

如果你目前的 checkout 已經有未提交變更，這套順序尤其重要。

在 repository 中應優先閱讀哪些檔案

這裡真正有意義的來源檔只有一個：SKILL.md。

請優先查看它，確認：

• 精確的目錄優先順序
• 沒有既定偏好時，技能會如何提示使用者
• ignore 驗證的要求
• 觸發用語，也就是代理必須先宣告技能使用的那段說明

這個技能本身很輕量，所以採用與否的核心問題其實是：這套邏輯是否符合你團隊的 Git workflow。

在正式依賴前要知道的實際限制

這個技能刻意設計得很聚焦。看起來它不提供以下能力：

• wrapper scripts
• 自動化輔助工具
• branch 命名規範強制
• 過期 worktree 的清理流程
• 針對不同平台的 fallback

所以 using-git-worktrees install 帶來的是判斷與建立指引，不是一整套完整的 worktree 管理系統。若你需要涵蓋生命週期的自動化，最好再搭配自己的 shell 工具。

using-git-worktrees 技能 FAQ

using-git-worktrees 適合新手嗎？

適合，前提是這位新手已經理解基本 branch 概念，而且想要一套更安全的「不要動到我目前工作空間」流程。它不是 Git 教學，而是一個結構化的設定技能。若是完全初學者，可能還是需要額外理解什麼是 worktree，以及它和 clone 有何不同。

這個技能比一般 prompt 更擅長解決什麼問題？

一般 prompt 常會略過最麻煩的部分：worktree 到底該建在哪裡，以及專案內目錄是否有被安全地 ignore。技能中編碼好的 using-git-worktrees guide 能降低這些設定失誤，也讓代理的行為更一致。

一定要使用專案內 worktrees 才能用嗎？

不需要。當本機目錄不存在、repo 內也沒有記錄偏好時，這個技能可以引導改用全域位置。因此即使你不想在 repository 內增加額外資料夾，也一樣能使用。

using-git-worktrees 可以用在既有 branch 嗎？

可以。把既有 branch checkout 到獨立工作空間時，這套流程仍然有價值。它的核心價值在於隔離，不只是在建立新 branch。

什麼時候不該使用 using-git-worktrees？

以下情況不建議使用：

• 你只是要在目前 branch 做一個很小的修改
• 你的團隊禁止使用未受管理的 worktree 位置
• 你已經有可預測、固定的內部工具，會處理位置與 ignore 規則
• 你的 repo 有這個技能無法理解的特殊 Git 限制

這會取代 Git 知識嗎？

不會。using-git-worktrees skill 能改善呼叫方式與建立流程的紀律，但你仍然需要基本的 Git 判斷能力，例如 branch 命名、rebase、清理，以及 merge 策略。

如何改善 using-git-worktrees 技能的使用效果

明確提供 branch 與目錄意圖

最大的品質提升方式，就是同時把 branch 目標與目錄策略講清楚。例如：

「Use using-git-worktrees for branch fix/cache-invalidation. If .worktrees/ exists and is ignored, use it; otherwise ask before using a global location.」

這能消除最常見的模糊地帶。

把偏好寫進 CLAUDE.md

因為這個技能會檢查 CLAUDE.md，你可以把以下資訊寫進去，改善之後的結果：

• 偏好的 worktree 目錄
• 是否允許使用專案內 worktrees
• branch 或資料夾的命名慣例

這樣就能把一再重複的使用者澄清，轉成 repo 層級的固定政策。

先配置好本機目錄的 ignore 規則

如果你的團隊想把 .worktrees/ 或 worktrees/ 放在專案內，請先把 ignore 規則加好。這會讓 using-git-worktrees for Git Workflows 的流程更順，因為安全驗證可以直接通過，不必在任務中途才停下來討論。

留意常見失敗模式

主要失敗模式其實很可預期：

• 代理把 worktree 建在未經允許的位置
• 本機 worktree 資料夾沒有被 ignore
• 因為功能需求描述太模糊，branch 名稱被錯誤推斷
• 還沒完成隔離前，就先在原本 checkout 開始實作

這些問題大多來自 prompt 不夠完整，而不是技能本身。

在開始寫程式前要求確認

一個簡單但有效的改善 prompt：

• 「Use using-git-worktrees, then report the final path and branch before making edits.」

這能及早攔下錯誤，對於有多層巢狀資料夾或特殊規範的 repository 特別有幫助。

第一次跑完後持續微調

如果第一次輸出可接受但還不夠理想，建議微調工作模式，而不是整套重寫：

• 固定你偏好的目錄位置
• 在 CLAUDE.md 補上說明
• 在 prompt 中統一 branch 命名方式
• 明確要求編輯前先確認

這樣能讓 using-git-worktrees usage 隨時間變得更可預測，也能減少重複的前置設定摩擦。