git-guardrails-claude-code

git-guardrails-claude-code skill 概覽

git-guardrails-claude-code skill 會在 Claude Code 執行前，先拒絕一小部分具破壞性的 Git 指令。它的核心作用其實很單純：替 AI 寫程式流程加上一層安全防護，避免 agent 在工作階段中隨手執行 git push、git reset --hard、git clean -f、用 git branch -D 刪除分支，或透過 git checkout .、git restore . 清空 working tree 變更。

哪些人適合使用 git-guardrails-claude-code

這個 skill 特別適合以下使用者：

• 直接讓 Claude Code 操作真實 repository
• 想要 AI 協助，但不希望它執行不可逆的 Git 動作
• 在共用 repo、生產環境 repo 或客戶專案中工作
• 比起靠「請小心一點」的提示，更偏好本機層級的強制限制

如果你最在意的是 agent 工作階段中誤刪程式碼，或未經授權就執行 push，那麼 git-guardrails-claude-code 會是很合適的選擇。

這和一般 prompt 有什麼不同

一般 prompt 可以要求 Claude 不要執行高風險指令，但 prompt 本質上只是軟性約束。git-guardrails-claude-code 用的是 PreToolUse hook，所以限制會直接進入 Claude Code 的執行路徑，而不只是停留在對話層。這正是它和單純提示最大的差異，也是最值得安裝的原因。

它實際會封鎖哪些內容

內附的 shell script 會檢查傳入的 Bash 指令，並封鎖下列模式：

• git push
• git reset --hard
• git clean -f
• git clean -fd
• git branch -D
• git checkout .
• git restore .
• 與 force-push 相關的比對，例如 push --force

封鎖訊息會明確告訴 Claude：它沒有權限使用這個指令。

這個 skill 不會做什麼

git-guardrails-claude-code 不是完整的 Git policy engine。它不會：

• 檢查 commit 品質
• 要求人工核准
• 區分哪些 push 目的地安全、哪些不安全
• 理解 repository 專屬的 branching 規則
• 保護清單以外的指令模式，除非你自行修改 script

這點很重要：它是一個聚焦型 guardrail，不是全面性的治理方案。

如何使用 git-guardrails-claude-code skill

先決定套用範圍

上游 skill 的第一個實務選擇，是決定要把 guardrail 安裝在哪一層：

• 只套用在目前專案，寫進 .claude/settings.json
• 或套用到所有專案，寫進 ~/.claude/settings.json

這個決定會影響 script 要複製到哪裡，也會影響封鎖規則的覆蓋範圍。對多數團隊來說，先做 project-level 安裝比較安全，測試起來也容易。等你確認想在所有地方都使用同一套 Git 限制後，再改成 global install 會更合理。

先讀這兩個檔案

你只要先看這兩個檔案，幾乎就能掌握所有重點：

1. SKILL.md
2. scripts/block-dangerous-git.sh

這個閱讀順序很有用，因為 SKILL.md 會說明 hook 怎麼接進去，而 scripts/block-dangerous-git.sh 會直接揭露實際封鎖的指令模式。如果你在意 false positive 或規則漏洞，那 script 比說明文字更值得仔細看。

git-guardrails-claude-code 的安裝脈絡

git-guardrails-claude-code install 本質上大多是手動接進 Claude Code 的 hook 系統：

1. 把 shell script 複製到 hooks 目錄
2. 讓它具備可執行權限
3. 在 PreToolUse 事件下，為 Bash matcher 註冊這個 script

來源 script 在 repository 中的路徑是：

scripts/block-dangerous-git.sh

目標位置則是：

• project scope：.claude/hooks/block-dangerous-git.sh
• global scope：~/.claude/hooks/block-dangerous-git.sh

接著要把它設成可執行：

chmod +x .claude/hooks/block-dangerous-git.sh

或若是 global scope：

chmod +x ~/.claude/hooks/block-dangerous-git.sh

正確加入 Claude Code hook

如果是 project scope，這個 skill 會在 .claude/settings.json 中示範一個 PreToolUse hook，透過 "$CLAUDE_PROJECT_DIR" 來執行複製後的 script。

接線時要確認的重點有：

• hook event：PreToolUse
• matcher：Bash
• hook type：command
• command：指向 block-dangerous-git.sh 的路徑

如果這個 hook 沒有註冊在 PreToolUse 底下，那 script 就算存在，也永遠不會攔截指令。

git-guardrails-claude-code 實際運作方式

這支 shell script 會從 standard input 讀取 tool input，使用 jq 擷取 .tool_input.command，再用 grep -qE 對照一小組危險模式。

這代表實際導入時的阻礙很明確：

• 執行環境裡必須有 jq
• settings 中的 command 路徑必須正確
• script 必須具備可執行權限
• Claude Code 必須真的有透過 hook system 呼叫 Bash tool

只要上述任何一環出錯，保護效果就會比你以為的弱，而且可能沒有明顯警訊。

這個 skill 需要你先提供哪些判斷

上游 skill 本身不太需要額外上下文，但要讓 git-guardrails-claude-code usage 順利，最好先想清楚以下幾件事：

• 要只限專案，還是全域套用
• 預設封鎖清單是否已足夠
• 你的團隊是否還想擋掉像 git tag -d、git rebase --abort，或特定 remote 的 push
• 對於合法 push 的情境，是否仍需要一條明確的人工升級／人工介入流程

如果這些問題沒有先定義好，安裝雖然不難，但實際政策可能未必符合你的工作方式。

把模糊需求變成更好的 prompt

較弱的 prompt：

• 「幫我設好 git guardrails。」

更強的 prompt：

• 「只在這個專案安裝 git-guardrails-claude-code。把 hook script 複製到 .claude/hooks/，設成可執行，更新 .claude/settings.json 加入給 Bash 用的 PreToolUse hook，最後把 script 中實際封鎖的 Git pattern 原樣列給我看。」

這樣更好的原因是：

• 有先定義 scope
• 明確指定目的地
• 同時要求 setup 與驗證
• 能降低 Claude 自行發明不同 hook 結構的機率

一套適合第一次上手的流程

實用的 git-guardrails-claude-code guide 可以照這個順序進行：

1. 選擇 project 還是 global scope
2. 檢查 scripts/block-dangerous-git.sh
3. 把 script 複製到目標 hooks 目錄
4. 對複製後的檔案執行 chmod +x
5. 在正確的 settings 檔中接上 PreToolUse hook
6. 在安全的 repo 裡，用無害模擬或明顯會被擋下的指令測試
7. 再決定是否要自訂 pattern

這個順序很重要，因為你可以在大範圍 rollout 前，先確認真正的強制清單到底長什麼樣。

如何驗證安裝是否生效

不要只停留在「檔案有放進去」這種表面確認。請驗證實際行為：

• 確認 Claude Code 使用的是哪個 settings 檔路徑
• 確認 hook command 指向的是你複製後的 script，而不是 repository 原始路徑
• 在可丟棄的 repo 中觸發一個會被封鎖的 pattern
• 檢查 Claude 收到的是拒絕訊息，而不是直接執行指令

對這個 skill 來說，行為驗證比畫面上看起來「有裝」更重要。

最適合的 Git 工作流

git-guardrails-claude-code for Git Workflows 特別適合以下 AI 協作模式：

• 讓 Claude 自由編輯檔案
• 讓 Claude 檢查 diff 和 status
• 將刪 branch、force push、hard reset、cleanup 這類操作保留給人類明確掌控

這種分工很實用，因為它保留了 AI 在寫程式上的效率，同時把不可逆的 repository 操作維持在人手動決策的範圍內。

什麼時候該自訂 script

預設清單是刻意保持精簡的。如果出現以下情況，就值得修改 scripts/block-dangerous-git.sh：

• 你的團隊認為 git push 可以接受，但只想封鎖 --force
• 你也想封鎖 git commit --amend
• 你的工作流包含敏感的 branch 刪除模式
• 你希望不同 repository 有不同規則

主要取捨在於簡單與精準之間。原版 script 容易審核；自訂很多的版本則需要更多測試。

git-guardrails-claude-code skill 常見問題

git-guardrails-claude-code 適合新手嗎

適合，前提是這位新手已經在使用 Claude Code，並希望 Git 預設行為更安全。整體設定不長，概念也很好懂：在 Bash tool call 執行前先攔截。稍微技術一點的部分，主要只有 JSON hook 設定和 shell script 權限。

這比直接跟 Claude 說「永遠不要 push」更好嗎

對它涵蓋的那些指令來說，答案是肯定的。git-guardrails-claude-code 會把對話層規則轉成執行時檢查，因此可靠度遠高於只靠 prompt 記憶。

git-guardrails-claude-code 會擋掉所有危險 Git 指令嗎

不會。它只會封鎖 script 中明列的 pattern。如果你的風險模型還包含其他指令，就必須自己加上去。這是這個 skill 很關鍵的邊界。

我可以全域使用 git-guardrails-claude-code 嗎

可以。這個 skill 明確支援透過 ~/.claude/settings.json 與 ~/.claude/hooks/block-dangerous-git.sh 進行 global install。全域安裝很方便，但如果不同 repo 需要不同政策，project-only install 會更容易測試，也更安全。

它會不會干擾一般寫程式工作

通常不太會，前提是你的日常流程本來就不期待 Claude 幫你 push，或執行破壞性的 Git cleanup。它最相容的模式，是讓 Claude 編輯程式碼、跑測試、整理變更，而最終 Git 權限仍由人來掌握。

什麼情況下不該用這個 skill

如果符合以下情況，就不建議使用 git-guardrails-claude-code：

• 你其實希望 Claude 端到端管理 Git
• 你的團隊需要細緻的 allowlist，而不只是簡單的 pattern block
• 你的環境無法依賴 shell hooks 或 jq
• 你需要超越本機 Claude Code 設定、在組織層級統一強制執行

在這些情境下，這個 skill 可能會顯得太窄、太偏本地端。

如何改進 git-guardrails-claude-code skill

依照真實風險重新盤點封鎖 pattern

最快提升 git-guardrails-claude-code 的方式，就是拿預設 pattern 清單去對照你真正擔心的 Git 失誤。很多團隊在意的重點，未必是所有 push，而更常是：

• force push
• 在受保護分支上刪 branch
• monorepo 中的破壞性 cleanup
• 除錯過程中的 working tree reset

如果你的政策和預設不同，不要照單全收；直接修改 pattern array 會更實際。

對 Claude 提供更明確的安裝指示

如果你要 Claude 幫忙套用這個 skill，請把細節講清楚：

• scope
• 精確的目的地路徑
• 要保留既有 hooks，還是與現有設定合併
• 是否要輸出最終 JSON 檔供你審閱
• 設定完成後是否要立即測試 hook

更好的要求方式例如：

• 「只在這個 repo 安裝 git-guardrails-claude-code，如果 .claude/settings.json 已經有 hooks，請合併而不是覆蓋，並把最後的 settings diff 顯示給我。」

這能避開最常見的失敗情境之一：把原有 hook 設定整個蓋掉。

留意 hook 合併錯誤

實務上常見的問題，往往不是 shell script 本身，而是 settings 檔更新方式。如果某個 repository 原本就設定了 hooks，粗心安裝很可能會把它們覆寫掉。你應該要求：

• 提供 diff，而不是整份盲改
• 保留既有的 PreToolUse entries
• 如果有多個 command 會執行，要解釋 hook 順序

對很多使用者來說，這比封鎖哪些指令還更重要。

測試 false positive 與繞過方式

由於 script 採用 pattern matching，你應該實測以下幾種情況：

• 合法且應該放行的指令
• 應該被擋下的指令
• 你以為會被擋，但其實未必有被擋到的變形寫法
• 在意料之外的位置出現類似字串的 command

這是提升 git-guardrails-claude-code usage 信心的正確做法，特別是在準備全域 rollout 之前。

看到真實漏網情況後，再收緊 script

很多人一開始就想把大量 pattern 全加進去，但如果沒有證據，最好先不要。短小、可讀的 blocklist 通常更容易被信任，也更好維護。等你觀察到以下情況後，再擴充：

• Claude 常嘗試哪些指令
• 使用者認為哪些指令風險高
• 哪些 pattern 曾經漏掉
• 哪些指令被擋了，但其實不該擋

這樣才能讓 guardrail 保持可理解。

加上一條人工升級路徑

一個很實用的營運層改善，是把 guardrail 和清楚規則一起搭配，例如：

• Claude 可以準備 commit，並說明 push 步驟
• 最後的 push 或破壞性 cleanup 由人工手動執行

這會讓這個 skill 更好用，因為使用者不再一直和 guardrail 對抗，而是改成依照這個限制去設計工作流程。

重新檢視全域或專案範圍是否仍然合適

使用一段時間後，建議重新評估 scope：

• 如果這條規則在所有 repo 都合理，就改成 global
• 如果某些 repo 需要較寬鬆的 Git 行為，就維持 project-local
• 如果團隊差異大，就為不同專案維護不同的 project-level script 版本

這是不改程式碼、卻能大幅提升適配度的最簡單方式之一。

讓 script 保持易讀

如果你有自訂 git-guardrails-claude-code，請維持 shell script 容易審核。比起花俏邏輯，更建議使用清楚的 pattern 清單與單一路徑的錯誤處理。對安全控制來說，可讀性本身就是可靠性的一部分。