我遇到的问题
给 Claude Code 开了 Bash 权限之后,它会在三种情况下主动碰 git:
- 写完一批改动,觉得"该提交了",顺手
git add -A && git commit; - 提交失败或冲突,想"回退到干净状态",
git reset --hard; - 清理构建产物时把
git clean -fd也带上。
第 1 种通常无害。第 2、3 种会把没提交的工作直接抹掉,而且不可恢复。我在一个跑了半天实验的仓库里踩过一次 reset --hard,那之后再没让 AI 裸跑过 git。
试过的做法
先说没用的:
- 在
CLAUDE.md里写"不要 push"。这是文本,模型在压力下权重会飘。它写了,也不代表每次都读到。 - 在提示词里反复强调。同上,而且占上下文。
- 收窄 Bash 权限到只允许
git status。太窄,正常的 commit 也没法做。
最后的做法:PreToolUse 钩子
钩子的位置决定了它和模型的区别:模型决定"要不要做",钩子决定"能不能做"。它跑在模型之外,不受提示词影响。
这个 skill 叫 git-guardrails-claude-code,在 skills.pub 上有收录:https://skills.pub/en/skills/mattpocock-skills-git-guardrails-claude-code
它的核心就是这个脚本:
#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')
DANGEROUS_PATTERNS=(
"git push" "git reset --hard" "git clean -fd" "git clean -f"
"git branch -D" "git checkout \." "git restore \." "push --force" "reset --hard"
)
for pattern in "${DANGEROUS_PATTERNS[@]}"; do
if echo "$COMMAND" | grep -qE "$pattern"; then
echo "BLOCKED: '$COMMAND' matches dangerous pattern '$pattern'. The user has prevented you from doing this." >&2
exit 2
fi
done
exit 0
两个细节值得说:
- 退出码 2 是关键。Claude Code 把 PreToolUse 钩子的非零退出当拒绝,工具调用压根不会发生。不是"做了然后报错",是"没做"。
push --force和reset --hard单独列了一遍。因为命令可能通过管道或变量拼出来,不一定带git前缀,只匹配git push会漏。
9 个模式分别挡什么
| 模式 | 为什么在名单里 |
|---|---|
git push |
覆盖所有变体,含 --force |
git reset --hard |
未提交的工作直接丢,不可恢复 |
git clean -fd |
删未跟踪的文件和目录 |
git clean -f |
删未跟踪文件 |
git branch -D |
不做合并检查直接删分支 |
git checkout \. |
丢弃工作区全部改动 |
git restore \. |
同上,新语法 |
push --force |
兜住没有 git 前缀的写法 |
reset --hard |
同上 |
安装步骤
skill 会让你先选作用域,别跳过这步:
- 选范围:只给当前项目(
.claude/settings.json),还是全部项目(~/.claude/settings.json)。 - 拷脚本到
.claude/hooks/block-dangerous-git.sh或~/.claude/hooks/block-dangerous-git.sh,然后chmod +x。 - 合并到 settings。如果你已经有别的钩子,合并进
hooks.PreToolUse数组,不要覆盖整个文件——覆盖会静默丢掉其他钩子。skill 原文专门强调了这点。 - 问你要不要增删模式,删改拷过去的脚本即可。
- 验证。
怎么验证
不用开 Claude Code,一条命令就能单测脚本:
echo '{"tool_input":{"command":"git push origin main"}}' | .claude/hooks/block-dangerous-git.sh
预期:退出码 2,stderr 打印 BLOCKED。
| 测试命令 | 预期 | 不符合时查什么 |
|---|---|---|
git push origin main |
退出 2,BLOCKED | 缺 jq,或脚本路径不对 |
git status |
退出 0,无输出 | 某个模式写得太宽 |
git reset --hard HEAD~1 |
退出 2,BLOCKED | 编辑时把数组改坏了 |
两个它没写出来的坑
这部分是我实测加的,skill 文档里没有:
1. jq 是隐性依赖,缺失时会静默放行。
脚本用 jq -r '.tool_input.command' 解析输入。机器上没装 jq 时,COMMAND 是空字符串,空串匹配不上任何模式,于是全部放行且不报错。钩子看起来装好了,实际什么都不挡。
修法:在脚本开头加一段检查。
command -v jq >/dev/null 2>&1 || {
echo "BLOCKED: jq missing, guardrails inactive" >&2; exit 2; }
2. git branch -D 挡了,但 --delete --force 没挡。
那是同一个操作的两种写法:
git branch --delete --force my-branch # 不在名单里,会通过
如果团队习惯用长参数,把 "git branch -D" 换成更宽的正则,或者两个都加。
它不解决什么
要把边界说清楚,否则容易误以为装了它就安全:
- 不挡 commit。AI 仍然可以把你不想提交的文件(含密钥)提交上去,只是在 push 时被拦。要防这个得配 pre-commit 的密钥扫描,这个 skill 不管。
- 不是安全沙箱。它是对命令字符串做子串匹配。字符串里出现
git push字样会被误拦,而运行时拼出来的命令可能漏过。它防的是"AI 一时兴起要 push",不是"有人在攻击"。 - 全局安装会影响所有项目。装到
~/.claude/后,那些本来就该由 AI 执行 push 的项目也会被挡。
小结
| 你担心的事 | 这个方案管不管 |
|---|---|
AI 自己 git push |
管 |
AI reset --hard 丢改动 |
管 |
| AI 提交了密钥 | 不管,需要额外扫描 |
| 有人恶意绕过 | 不管,这不是安全边界 |
| 换个 harness 还能用吗 | 只要它认钩子的退出码就能用 |
这个模式值得抄的地方不是这 9 个正则,是用退出码把"请你别做"变成"你做不到"。任何支持钩子的 harness 都能用同一招。
原文(英文):https://skills.pub/en/blog/git-guardrails-claude-code-blocking-destructive-git
这个 skill 在 skills.pub 上的页面:https://skills.pub/en/skills/mattpocock-skills-git-guardrails-claude-code