git-guardrails-claude-code

技能简介

该技能用于在 Claude Code 中自动设置 PreToolUse 钩子，在执行前拦截并阻止危险的 git 命令（如 git push、git reset --hard、git clean -f、git branch -D 等），从而避免破坏性操作对代码库造成不可逆的损失。

使用场景

• 防止 Claude 在执行任务时不小心执行 git push 或强制推送（--force）
• 阻止 git reset --hard、git clean -fd 等导致工作区内容丢失的命令
• 在团队或多人协作环境中，为所有项目统一配置 git 安全钩子
• 需要对某些高危 git 命令做个性化拦截时，快速修改拦截列表

使用方法

1. 确认安装范围

询问用户：仅对当前项目生效（.claude/settings.json），还是对所有项目生效（~/.claude/settings.json）。

2. 复制钩子脚本

将脚本复制到对应位置，并赋予执行权限：

# 项目级
cp scripts/block-dangerous-git.sh .claude/hooks/block-dangerous-git.sh
chmod +x .claude/hooks/block-dangerous-git.sh

# 全局
cp scripts/block-dangerous-git.sh ~/.claude/hooks/block-dangerous-git.sh
chmod +x ~/.claude/hooks/block-dangerous-git.sh

3. 添加钩子配置

在 settings.json 中添加：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-dangerous-git.sh"
          }
        ]
      }
    ]
  }
}

如果 settings.json 已存在，请合并 hooks.PreToolUse 数组，不要覆盖已有配置。

4. 自定义拦截列表（可选）

询问用户是否需要增删被阻止的命令模式，并修改脚本中的拦截列表。

5. 验证

运行以下命令测试钩子是否生效：

echo '{"tool_input":{"command":"git push origin main"}}' | <脚本路径>

预期输出：以状态码 2 退出，并在 stderr 中输出 BLOCKED 提示。

注意事项

• 若 settings.json 中已有其他钩子配置，务必合并而非覆盖，否则会破坏现有 Claude Code 配置。
• 钩子脚本通过返回非零退出码阻止命令执行，此时 Claude 会视为「无权限执行该命令」。