git-guardrails-claude-code

git-guardrails-claude-code skill 概览

git-guardrails-claude-code skill 的作用很直接：在 Claude Code 真正执行前，拦住一小组高破坏性的 Git 命令。它的核心价值不是“提醒 AI 小心一点”，而是给 AI 编码会话加上一层实际生效的安全护栏，避免它随手执行 git push、git reset --hard、git clean -f、用 git branch -D 删除分支，或通过 git checkout .、git restore . 清空工作区改动。

哪些人适合使用 git-guardrails-claude-code

这个 skill 特别适合以下用户：

• 直接让 Claude Code 操作真实仓库
• 希望获得 AI 辅助，但不希望它执行不可逆的 Git 操作
• 在共享仓库、生产仓库或客户代码库中工作
• 比起靠“请小心一点”的提示，更偏好本地强制约束

如果你最担心的是 agent 会话中误删代码，或未经授权就执行 push，那么 git-guardrails-claude-code 会很适合。

它和普通提示词的区别是什么

你当然可以在 prompt 里要求 Claude 不要运行高风险命令，但 prompt 只是“软约束”。git-guardrails-claude-code 用的是 PreToolUse hook，也就是说，限制是在 Claude Code 的实际执行链路里生效，而不只是停留在对话层面。这正是它和普通提示词最大的区别，也是最值得安装的原因。

它实际会拦哪些命令

随附的 shell 脚本会检查传入的 Bash 命令，并阻止以下模式，包括：

• git push
• git reset --hard
• git clean -f
• git clean -fd
• git branch -D
• git checkout .
• git restore .
• 与强制推送相关的匹配，例如 push --force

拦截时返回的信息会明确告诉 Claude：它没有权限使用该命令。

这个 skill 不会做什么

git-guardrails-claude-code 不是完整的 Git 策略引擎。它不会：

• 审查 commit 质量
• 强制审批流程
• 区分哪些 push 目标安全、哪些不安全
• 理解仓库自身的分支规则
• 保护脚本中未列出的其他命令，除非你手动修改脚本

这一点很重要：它是一个聚焦型 guardrail，不是全面治理方案。

如何使用 git-guardrails-claude-code skill

先决定 git-guardrails-claude-code 的作用范围

上游 skill 的第一个实际选择，是你要把这层 guardrail 安装到：

• 仅当前项目 的 .claude/settings.json，还是
• 所有项目 的 ~/.claude/settings.json

这个决定会直接影响脚本复制到哪里，以及拦截规则会覆盖多大范围。对大多数团队来说，先按项目级安装更适合测试；等确认你希望所有环境都遵循同样的 Git 限制后，再改成全局安装会更稳妥。

先看这两个文件

如果你想快速弄清重点，优先阅读：

1. SKILL.md
2. scripts/block-dangerous-git.sh

这个阅读顺序很有用，因为 SKILL.md 解释的是 hook 如何接线，而 scripts/block-dangerous-git.sh 展示的是到底拦哪些命令模式。要是你关心误拦截或漏拦截，比起说明文档，脚本本身更关键。

git-guardrails-claude-code 的安装上下文

git-guardrails-claude-code install 本质上是在 Claude Code 的 hook 系统里做一轮手动接入：

1. 把 shell 脚本复制到 hooks 目录
2. 给它可执行权限
3. 在 PreToolUse 下把它注册到 Bash matcher

源码脚本所在仓库路径是：

scripts/block-dangerous-git.sh

目标位置分别是：

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

然后赋予执行权限：

chmod +x .claude/hooks/block-dangerous-git.sh

或全局安装时：

chmod +x ~/.claude/hooks/block-dangerous-git.sh

正确添加 Claude Code hook

如果按项目级安装，这个 skill 提供的方式是在 .claude/settings.json 里配置一个 PreToolUse hook，并通过 "$CLAUDE_PROJECT_DIR" 来调用复制后的脚本。

接线时要确认这几个关键点：

• hook 事件：PreToolUse
• matcher：Bash
• hook 类型：command
• command：指向 block-dangerous-git.sh 的路径

如果这个 hook 没有注册在 PreToolUse 下，那脚本就算存在，也永远不会拦截命令。

脚本在实际运行中是怎么工作的

这个 shell 脚本会从标准输入读取 tool 输入，用 jq 提取 .tool_input.command，再通过 grep -qE 把命令和一小组危险模式做匹配。

这也意味着，部署时真正会卡住你的点其实很明确：

• 环境里必须有 jq
• settings 里的命令路径必须有效
• 脚本必须可执行
• Claude Code 确实要通过 hook 系统调用 Bash 工具

这些环节只要有一个出问题，保护效果就可能比你想象中弱，而且往往不会有很明显的报错。

这个 skill 需要你先给出哪些输入

上游 skill 本身对上下文要求不高，但一个更靠谱的 git-guardrails-claude-code usage 流程，最好先把这些问题想清楚：

• 只针对当前项目，还是全局启用
• 默认的拦截列表够不够
• 团队是否还想拦截额外命令，比如 git tag -d、git rebase --abort，或针对特定 remote 的 push
• 当确实需要合法 push 时，是否还需要一条明确的人工升级/放行路径

这些问题不先定下来，安装本身虽然不难，但实际策略可能并不适合你的团队。

把模糊目标改写成更强的 prompt

弱 prompt：

• “Set up git guardrails.”

更强的 prompt：

• “Install git-guardrails-claude-code for this project only. Copy the hook script into .claude/hooks/, make it executable, update .claude/settings.json with a PreToolUse hook for Bash, and then show me the exact blocked Git patterns from the script.”

为什么后者更好：

• 明确了作用范围
• 指定了目标路径
• 同时要求完成配置和验证
• 降低 Claude 临时发挥、改成另一套 hook 结构的概率

一套适合首次落地的 git-guardrails-claude-code 工作流

一个实用的 git-guardrails-claude-code guide 可以这样走：

1. 先决定项目级还是全局级
2. 检查 scripts/block-dangerous-git.sh
3. 把脚本复制到目标 hooks 目录
4. 对复制后的文件执行 chmod +x
5. 在正确的 settings 文件里接好 PreToolUse hook
6. 在安全仓库里，用无害模拟或显然会被拦截的命令做测试
7. 再决定是否要自定义匹配模式

这个顺序很重要，因为它能让你在大范围铺开前，先验证真正生效的拦截清单。

如何验证安装是否真的生效

不要停留在“文件已经在那儿了”。要验证行为：

• 确认 Claude Code 实际读取的是哪个 settings 文件
• 确认 hook command 指向的是复制后的脚本，而不是仓库里的源码路径
• 在一次性测试仓库里触发一个被拦截的模式
• 检查 Claude 收到的是拒绝信息，而不是命令真的被执行

对这个 skill 来说，行为验证比界面或文件层面的确认更重要。

git-guardrails-claude-code 最适合的 Git 工作流

git-guardrails-claude-code for Git Workflows 特别适合这样的 AI 使用方式：

• 让 Claude 自由编辑文件
• 让 Claude 查看 diff 和 status
• 但把删分支、force push、hard reset、清理类命令牢牢保留在人类手里

这种分工很合理：编码效率交给 AI，不可逆的仓库操作仍由人工掌控。

什么时候应该自定义脚本

默认列表本来就刻意保持简短。如果出现以下情况，就该考虑修改 scripts/block-dangerous-git.sh：

• 你的团队认为 git push 可以接受，但只想拦 --force
• 你还想拦截 git commit --amend
• 你的流程里存在敏感分支删除场景
• 你希望不同仓库有不同规则

这里的核心取舍是：简单性 vs 精细度。原版脚本容易审计；一旦高度定制，就需要更多测试。

git-guardrails-claude-code skill 常见问题

git-guardrails-claude-code 适合新手吗

适合，前提是这个新手已经在使用 Claude Code，并且希望 Git 默认更安全一些。整体配置步骤不长，概念也很好理解：在执行前拦截 Bash 工具调用。稍微有点技术门槛的部分，主要是 JSON hook 配置和 shell 脚本权限。

这比直接告诉 Claude “never push” 更好吗

对它覆盖到的那些命令来说，是的。git-guardrails-claude-code 把一条对话规则，变成了执行时检查，因此可靠性远高于只靠 prompt 和记忆约束。

git-guardrails-claude-code 会拦住所有危险 Git 命令吗

不会。它只会拦脚本里明确写出的模式。如果你的风险模型里还包含其他命令，需要你自己补进去。这是这个 skill 很明确的边界。

我可以全局使用 git-guardrails-claude-code 吗

可以。这个 skill 明确支持通过 ~/.claude/settings.json 和 ~/.claude/hooks/block-dangerous-git.sh 做全局安装。全局安装更方便，但如果不同仓库需要不同策略，项目级安装会更容易测试，也更安全。

它会不会影响正常编码工作

通常影响不大，前提是你的日常流程本来就不需要 Claude 去 push 或执行破坏性的 Git 清理。它最适合的模式是：Claude 负责改代码、跑测试、准备变更，人类保留最终的 Git 操作权限。

什么情况下不建议使用这个 skill

以下情况可以跳过 git-guardrails-claude-code：

• 你本来就希望 Claude 端到端管理 Git
• 团队需要的是细粒度 allowlist，而不是简单的模式屏蔽
• 你的环境无法依赖 shell hooks 或 jq
• 你需要的是超出本地 Claude Code 配置范围的组织级强制管控

在这些场景下，这个 skill 可能会显得太窄，或者太偏本地化。

如何改进 git-guardrails-claude-code skill

先把被拦截的模式和真实风险对齐

提升 git-guardrails-claude-code 最快的方法，就是把默认模式列表和你真正关心的 Git 失误类型逐一对照。很多团队并不是在意“所有 push”，而是更在意：

• force push
• 受保护分支上的删除操作
• monorepo 中的破坏性 clean
• 调试过程中的工作区 reset

如果你的策略重点不同，就直接修改模式数组，不要盲目照单全收默认值。

给 Claude 更明确的安装指令

如果你让 Claude 帮你应用这个 skill，请把细节说清楚：

• 作用范围
• 精确的目标路径
• 现有 hooks 是保留还是合并
• 是否输出最终 JSON 文件供复核
• 配置完成后是否马上测试 hook

更强的请求可以是：

• “Install git-guardrails-claude-code only in this repo, merge with any existing .claude/settings.json hooks instead of overwriting them, and show the final settings diff.”

这样能避开最常见的失败模式之一：把已有 hook 配置直接覆盖掉。

留意 hook 合并时的常见错误

一个很现实的问题，往往不在 shell 脚本本身，而在 settings 文件的更新方式。如果仓库原本已经配置了 hooks，粗心安装很容易把原配置冲掉。你应该明确要求：

• 给出 diff，而不是整份无提示重写
• 保留现有的 PreToolUse 条目
• 如果有多个命令要跑，解释 hook 的执行顺序

对很多用户来说，这部分甚至比拦截哪些命令更关键。

测试误拦截和绕过情况

由于脚本依赖模式匹配，你应该专门测试：

• 本该放行的合法命令
• 本该拦截的危险命令
• 你以为会被拦住、但实际上可能没拦住的变体
• 在非预期上下文里包含相似文本的命令字符串

这是提升 git-guardrails-claude-code usage 可靠性的正确位置，尤其适合在全局推广前完成。

看到真实漏拦后，再收紧脚本

很多人一开始就想一次性加很多模式，但除非你已经有证据，否则不建议这么做。短小、可读的 blocklist 更容易被信任，也更容易维护。更合理的做法是，在观察到以下情况后再扩展：

• Claude 经常尝试哪些命令
• 用户实际认定哪些命令风险高
• 哪些模式漏过去了
• 哪些命令被误拦，但其实不该拦

这样能让 guardrail 始终保持可理解。

设计一条人工升级路径

一个很实用的改进方式，是给这层 guardrail 配套一条清晰规则，例如：

• Claude 可以准备 commits，并说明 push 步骤
• 最终 push 或破坏性清理由人工手动执行

这样做的好处是，用户不会总想着和 guardrail 对抗，而是会围绕它来设计流程。

重新评估全局还是项目级是否仍然合适

在实际使用一段时间后，最好重新审视作用范围：

• 如果这套规则在所有仓库都适用，就迁移到全局
• 如果部分仓库需要更宽松的 Git 行为，就继续保留项目级
• 如果团队差异明显，就维护多个项目级脚本版本

这是在不改代码的前提下，提升适配度最简单的方式之一。

保持脚本可读

如果你决定自定义 git-guardrails-claude-code，尽量让 shell 脚本保持易审计。优先使用清晰的模式列表和单一路径的报错处理，而不是炫技式逻辑。对安全控制来说，可读性本身就是可靠性的一部分。