git-guardrails

Git 防护栏

设置一个 PreToolUse 钩子，在 Claude Code 执行危险的 git 命令之前拦截并阻止这些命令。

前置条件

• jq：钩子脚本需要用它解析工具输入，可通过 brew install jq 或 apt-get install jq 安装
  • 重要：如果未安装 jq，钩子会故障放行（允许所有命令）。设置完成后务必确认 jq 可用。

何时使用此技能

在以下情况下启用：

• 用户想阻止 AI Agent 执行破坏性的 git 操作
• 用户要求为 Claude Code 添加 git 安全钩子
• 用户想阻止 git push、git reset --hard 或其他危险命令
• 用户正在设置新项目，并希望为 git 操作添加防护栏

会阻止哪些命令

以下命令会在执行前被拦截并阻止：

模式	描述
git push	所有 push 变体（防止未经审查的推送）
git push --force	强制推送（会改写远程历史记录）
git push --force-with-lease	强制推送变体
git reset --hard	丢弃所有未提交的更改
git clean -f / git clean -fd	永久删除未跟踪的文件
git branch -D	未检查合并状态就强制删除分支
git checkout .	丢弃工作区中的所有更改
git restore .	丢弃工作区中的所有更改
git rebase on main/master	阻止对受保护分支执行 rebase

命令被阻止时，Claude 会看到一条消息，告知其无权执行这些命令。如有需要，用户必须手动运行这些命令。

设置步骤

步骤 1：询问作用范围

询问用户：仅为此项目（.claude/settings.json）安装，还是为所有项目（~/.claude/settings.json）安装？

步骤 2：复制钩子脚本

随附脚本位于：reference/block-dangerous-git.sh

根据作用范围将其复制到目标位置：

• 项目：.claude/hooks/block-dangerous-git.sh
• 全局：~/.claude/hooks/block-dangerous-git.sh

将其设为可执行文件：

chmod +x <path-to-script>

步骤 3：将钩子添加到设置中

将钩子添加到相应的设置文件中。

项目范围（.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"
          }
        ]
      }
    ]
  }
}

如果设置文件已存在，请将钩子合并到现有的 hooks.PreToolUse 数组中。不要覆盖其他设置。

步骤 4：询问是否需要自定义

询问用户是否想在阻止列表中添加或移除任何模式。相应地编辑复制的脚本。

用户可能想添加的常见规则：

• 阻止 git stash drop（防止意外丢失暂存内容）
• 阻止 git tag -d（防止删除标签）
• 允许 git push，但仅阻止 --force 变体

步骤 5：验证安装

运行快速测试，确认钩子正常工作：

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

预期结果：以代码 2 退出，并向 stderr 打印一条 BLOCKED 消息。

再运行一次安全命令测试：

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

预期结果：以代码 0 退出（允许执行）。

工作原理

Claude Code 支持 PreToolUse 钩子，可在任何工具调用前运行。该钩子会：

1. 从 stdin 接收 JSON 格式的工具输入
2. 使用 jq 提取 command 字段
3. 将命令与危险模式列表进行比对
4. 如果匹配，则以代码 2 退出（告知 Claude 该命令已被阻止）
5. 如果不匹配，则以代码 0 退出（允许正常执行）

重要说明

• 此钩子只会阻止 AI Agent 运行的命令。用户仍可在终端中手动运行任何 git 命令。
• 被阻止的模式使用正则表达式匹配，因此 git push 也会匹配 git push origin main --force。
• 如果未安装 jq，脚本会故障放行（允许所有命令）。请确保 jq 可用。
• 此钩子不会修改任何 git 配置；它只会拦截 Claude Code 的工具调用。