Git Guardrails — 给 Claude Code 装上 git 安全钩子

技能概述

Git Guardrails 通过 Claude Code 的 PreToolUse 钩子，在命令真正执行前拦截 git push、git reset --hard、git clean -fd、git branch -D、git checkout . 等破坏性 git 操作，让 AI 在动你的代码仓库之前先被拦一道。

适用场景

1. 防止 AI 误删未提交的代码：当 Claude 试图用 git reset --hard 或 git checkout . "清理"工作区时，钩子会直接拦下，你辛苦写了一下午还没提交的改动不会被一键抹掉。
2. 防止强制推送覆盖远程分支：团队共用仓库时，git push --force 是最容易造成不可逆损失的操作。装好钩子后，所有 push 变体（含 --force）都会被阻止，Claude 只能把改动留在本地等你处理。
3. 给团队的 Claude Code 统一加一道防护线：可以只装在当前项目，也可以装到全局配置，让所有项目的 Claude Code 都遵守同一套 git 操作红线，尤其适合新人较多、仓库权限较松的团队。

核心功能

1. 执行前拦截，而不是事后补救：钩子挂在 PreToolUse 的 Bash 匹配器上，命令还没跑就被拦下并返回退出码 2，比依赖 git reflog 事后恢复可靠得多。
2. 默认覆盖五类高危命令：git push（所有变体，含 --force）、git reset --hard、git clean -f / git clean -fd、git branch -D、git checkout . / git restore .。
3. 可按项目或按全局安装，拦截清单可自定义：项目级写入 .claude/settings.json，全局级写入 ~/.claude/settings.json；如果已有配置，钩子会合并进现有的 hooks.PreToolUse 数组，不会覆盖你的其他设置。装完后还能按需增删拦截模式。

常见问题

这个技能会阻止哪些 git 命令？

默认拦截 git push（包括 --force 在内的所有变体）、git reset --hard、git clean -f 和 git clean -fd、git branch -D，以及 git checkout . / git restore .。这份清单不是穷举的——git rebase、git stash drop 等并不在默认范围内，如需拦截可以自行修改钩子脚本里的模式。

命令被拦截后会发生什么？

钩子以退出码 2 结束并向 stderr 输出 BLOCKED 信息，Claude 会看到一条提示，告诉它没有权限访问这些命令。结果是命令不会执行，Claude 需要换一种方式完成任务，或者把操作交回给你手动执行。

装了钩子会影响我自己在终端里敲 git 命令吗？

不会。钩子只作用于 Claude Code 的 Bash 工具调用，也就是只拦 Claude 执行的命令，你自己的终端会话完全不受影响，该 push 还是能 push。

怎么确认钩子真的生效了？

可以用一条测试命令验证：把 {"tool_input":{"command":"git push origin main"}} 通过管道传给钩子脚本，正常情况下它会以退出码 2 退出，并向 stderr 打印 BLOCKED 提示。看到这个结果就说明脚本本身工作正常。