git-guardrails-claude-code

配置 Git 安全防护栏 (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. 确认作用域 (Scope)

询问用户：是仅为当前项目配置（.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. 询问自定义需求

询问用户是否需要在拦截列表 (blocked list) 中添加或删除匹配规则 (patterns)。并根据用户需求编辑复制后的脚本。

5. 验证配置

运行快速测试命令：

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

脚本应以退出码 (exit code) 2 结束运行，并在 stderr 中输出包含 BLOCKED 的提示信息。