git-guardrails-claude-code

設定 Git Guardrails

設定一個 PreToolUse hook，在 Claude 執行危險的 Git 指令前進行攔截並阻止。

受阻擋的指令

• git push（包含 --force 在內的所有變體）
• git reset --hard
• git clean -f / git clean -fd
• git branch -D
• git checkout . / git restore .

被阻擋時，Claude 會看到一條訊息，說明其無權執行這些指令。

步驟

1. 詢問套用範圍

詢問使用者：僅為當前專案安裝（.claude/settings.json），或是為所有專案安裝（~/.claude/settings.json）？

2. 複製 Hook 腳本

隨附的腳本位於：scripts/block-dangerous-git.sh

根據選定的範圍複製到目標位置：

• 專案 (Project): .claude/hooks/block-dangerous-git.sh
• 全域 (Global): ~/.claude/hooks/block-dangerous-git.sh

使用 chmod +x 讓它可執行。

3. 將 Hook 新增至設定檔

新增至對應的設定檔：

專案 (.claude/settings.json):

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-dangerous-git.sh"
          }
        ]
      }
    ]
  }
}

全域 (~/.claude/settings.json):

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/block-dangerous-git.sh"
          }
        ]
      }
    ]
  }
}

若設定檔已存在，請將 hook 合併 (merge) 到現有的 hooks.PreToolUse 陣列中，不要覆蓋其他設定。

4. 詢問是否需要客製化

詢問使用者是否要在阻擋清單中新增或移除比對模式 (patterns)。並相應編輯複製後的腳本。

5. 驗證

執行快速測試：

echo '{"tool_input":{"command":"git push origin main"}}' | <path-to-script>

應以 exit code 2 退出，並向 stderr 印出 BLOCKED 訊息。