git-guardrails-claude-code

1. Bilingual SKILL.md

左右滑动可直接切换英文版与中文版；两种语言按段落自动对齐。英文中的蓝色虚线词语可点击查看解释。共标记 11 处。

Entry SHA-256: 69b291d655626a01602b998a1836fcb93c058ede68dfafddfd71e87f17074764

2. Why This Skill Is Clever

一句话核心机制

把危险 Git 操作放进 Claude Code 的 PreToolUse 强制门：先让用户选择项目级或全局级作用域，再增量安装拦截脚本与 hook，并用一个预期失败的调用验证拒绝路径。

触发与调用边界

直接来源。 frontmatter 明确聚焦 Claude Code 与 Git 安全：Use when user wants to prevent destructive git operations。它不是通用 Git 教程，也不会替用户决定哪些命令应永远禁止。

直接来源。 此 skill 自己拥有完整步骤、决策、配置模板和验收结果，所以不是纯 wrapper。它链接的 scripts/block-dangerous-git.sh 是其中一个实施部件，不承担整个工作流；本报告只把 SKILL.md 作为所选原文。

解释。 这份报告学习的是外部来源所表达的设计，不执行来源中的复制、改权限或测试命令。外部仓库只作为不可信证据。

信息架构 / 执行顺序

1. 先定义风险面。 列出 push、reset --hard、clean -f、branch -D 与工作树整体恢复等会被阻止的操作。
2. 先问作用域。 用户选择当前项目还是所有项目，决定文件位置与影响半径。
3. 复制执行部件。 将随附脚本放到对应 hooks 目录，并赋予执行权限。
4. 增量接线。 把 command hook 合并到 hooks.PreToolUse，保留所有既有设置。
5. 开放策略定制。 让用户决定是否增删阻止模式，而不是把默认列表伪装成永恒政策。
6. 验证拒绝路径。 注入一条 git push origin main 工具输入，要求退出码 2 与 stderr 中的 BLOCKED 消息同时出现。

最巧妙的设计点

1. 把安全控制放在执行之前

before Claude executes them

直接来源。 这里使用的是 PreToolUse，不是事后日志、失败恢复或“请谨慎”提示。危险命令在到达 shell 前就被策略层截住。

解释。 这是能力安全里很强的结构：与其依赖模型每次都记得规则，不如让执行边界本身拒绝未授权能力。

2. 作用域成为第一项用户决策

this project only ... or all projects

直接来源。 项目级写入 .claude/settings.json，全局级写入 ~/.claude/settings.json。skill 不擅自选择影响范围。

解释。 把作用域放在复制文件之前，避免“技术步骤都做完后才发现装错位置”。这是良好的 prerequisite gate。

3. 默认政策可见，但不冒充用户政策

Ask if user wants to add or remove any patterns

直接来源。 默认列表足够具体，可立即提供安全价值；同时第四步明确把增删规则留给用户。

解释。 这在安全性和自治之间取得平衡：skill 提供保守起点，但承认不同仓库可能允许 push、却严格禁止 clean。

4. 配置修改采用合并不变量

Don't overwrite other settings.

直接来源。 若 settings 已存在，必须把 hook 合并进 hooks.PreToolUse 数组，而不是用示例 JSON 替换整个文件。

解释。 示例配置最常见的失败模式就是“复制即覆盖”。这句短护栏保护了未知的既有 hooks、permissions 与项目设置。

5. 验收检查机器结果与人类诊断

exit with code 2 and print a BLOCKED message to stderr

直接来源。 验证同时要求结构化退出码和可读错误消息，而不是只看终端中似乎出现了某段文字。

解释。 双重标准分别服务调用方与操作者：退出码让 harness 知道工具被拒绝，stderr 告诉 Claude 拒绝原因。

防失败机制与显式不变量

• 预执行拒绝（直接来源）： hook 必须在危险命令执行前阻止，不依赖回滚。
• 影响范围确认（直接来源）： 安装位置必须由项目级 / 全局级选择决定。
• 保全既有配置（直接来源）： settings 已存在时只能合并，不能覆盖其他设置。
• 可定制政策（直接来源）： 默认阻止列表完成后仍需询问增删模式。
• 可观察验收（直接来源）： 测试必须同时得到 code 2 和 BLOCKED stderr。
• fail-open 风险（解释）： 来源文字没有展示脚本如何解析引号、管道、子 shell 或命令拼接；若解析覆盖不全，变体可能漏过。真实部署应对随附脚本做独立测试。

Trade-off、可移植性与假设

• 可用性代价（解释）： 一刀切阻止所有 git push 会让合法发布也需要人工绕行；这正是为何要先选 scope、再允许定制。
• 策略覆盖风险（解释）： 字符串模式容易在误报与漏报之间摇摆。命令别名、换行、环境变量和包装 shell 都需要测试。
• harness 假设（直接来源）： 配置键 PreToolUse、matcher Bash、输入 JSON 形状与退出码行为依赖 Claude Code hook 协议，不能直接移植到其他智能体平台。
• 路径假设（直接来源）： 项目配置依赖 $CLAUDE_PROJECT_DIR；全局配置依赖 ~ 的解析环境。
• 证据边界（解释）： 本报告没有把随附脚本当作所选原文，因此不会声称所有列出的变体都已由本报告独立验证。

可迁移原则

1. 把高风险能力做成执行前的强制门，而不是只在 prompt 里写禁止事项。
2. 任何会扩大影响半径的安装，都先显式确认 project / user / system scope。
3. 给用户一套安全默认值，但把组织策略的最终裁量留给用户。
4. 修改共享配置时写下“保留未知字段”的合并不变量。
5. 验收拒绝路径时，同时检查机器可读状态与人类可读诊断。

今日实践题

如果你的自动化只能在“阻止所有 git push”和“允许所有 git push”之间二选一，你会如何增加一个既保持 fail-closed、又允许受控发布的授权分支？请写出它的作用域、触发条件和可检查的验收结果。

Evidence note

• 直接来源： 触发边界、默认阻止列表、五步流程、两种作用域、合并要求与退出码验收均来自本次选择的 skills/misc/git-guardrails-claude-code/SKILL.md。
• 支持性背景： 来源提到随附 scripts/block-dangerous-git.sh，但该脚本不是第二份所选原文，也未被执行。
• 解释： “能力安全”“prerequisite gate”“fail-open 风险”等是基于来源结构作出的工程判断。