GateGuard — 操作前强制事实门控¶

一个 PreToolUse 钩子，强制 Claude 在编辑前进行调查。它不依赖自我评估（“你确定吗？”），而是要求提供具体事实。调查这个动作本身所产生的认知，是自我评估永远无法产生的。

何时启用¶

• 在文件编辑会影响多个模块的任何代码库上工作
• 数据文件具有特定模式或日期格式的项目
• AI 生成的代码必须匹配现有模式的团队
• 任何 Claude 倾向于猜测而非调查的工作流

核心概念¶

LLM 的自我评估不起作用。问“你是否违反了任何策略？”答案永远是“没有”。这一点已通过实验验证。

但若要求“列出导入此模块的所有文件”，就会迫使 LLM 运行 Grep 和 Read。调查本身所建立的上下文会改变输出结果。

三阶段门控：

1. DENY  — block the first Edit/Write/Bash attempt
2. FORCE — tell the model exactly which facts to gather
3. ALLOW — permit retry after facts are presented

没有其他方案能做到全部三步。大多数都止步于 DENY 阶段。

证据¶

两组独立的 A/B 测试，代理完全相同，任务也相同：

两个代理生成的代码都能运行并通过测试。差异在于设计深度。

门控类型¶

Edit / MultiEdit 门控（每个文件的首次编辑）¶

MultiEdit 的处理方式相同——批次中的每个文件都会被单独门控。

Before editing {file_path}, present these facts:

1. List ALL files that import/require this file (search the tree — Glob/Grep, or find/grep via Bash)
2. List the public functions/classes affected by this change
3. If this file reads/writes data files, show field names, structure,
   and date format (use redacted or synthetic values, not raw production data)
4. Quote the user's current instruction verbatim

Write 门控（首次创建新文件）¶

Before creating {file_path}, present these facts:

1. Name the file(s) and line(s) that will call this new file
2. Confirm no existing file serves the same purpose (search the tree — Glob/Grep, or find/grep via Bash)
3. If this file reads/writes data files, show field names, structure,
   and date format (use redacted or synthetic values, not raw production data)
4. Quote the user's current instruction verbatim

破坏性 Bash 门控（每次破坏性命令）¶

触发条件：rm -rf、git reset --hard、git push --force、drop table 等。

1. List all files/data this command will modify or delete
2. Write a one-line rollback procedure
3. Quote the user's current instruction verbatim

常规 Bash 门控（每个会话一次）¶

1. The current user request in one sentence
2. What this specific command verifies or produces

快速开始¶

方案 A：使用 ECC 钩子（零安装）¶

本插件包含位于 scripts/hooks/gateguard-fact-force.js 的钩子。通过 hooks.json 启用它。

如果 GateGuard 阻止了设置或修复工作，请使用 ECC_GATEGUARD=off 启动会话。若需钩子级控制，可继续将 ECC_DISABLED_HOOKS 与 GateGuard 钩子 ID 配合使用。

方案 B：带配置的完整包¶

pip install gateguard-ai
gateguard init

这会添加 .gateguard.yml 用于按项目配置（自定义消息、忽略路径、门控开关）。

反模式¶

• 不要用自我评估来代替。“你确定吗？”得到的永远是“确定”。这一点已通过实验验证。
• 不要跳过数据模式检查。两组 A/B 测试代理都假定使用 ISO-8601 日期格式，而实际数据使用的是 %Y/%m/%d %H:%M。检查数据结构（使用脱敏值）可以避免这一整类 bug。
• 不要对每一条 Bash 命令都进行门控。常规 Bash 命令每个会话只门控一次。破坏性 Bash 命令每次都要门控。这种平衡既能避免拖慢速度，又能捕获真正的风险。

最佳实践¶

• 让门控自然触发。不要试图预先回答门控问题——调查本身才是提升质量的关键。
• 针对你的领域自定义门控消息。如果你的项目有特定约定，请将它们添加到门控提示中。
• 使用 .gateguard.yml 忽略诸如 .venv/、node_modules/、.git/ 等路径。

相关技能¶

• safety-guard — 运行时安全检查（互补，不重叠）
• code-reviewer — 编辑后审查（GateGuard 是编辑前调查）