事实强制门控，阻止编辑/写入/Bash（包括MultiEdit），并要求在允许操作之前进行具体调查（导入器、数据模式、用户指令）。与无门控代理相比，输出质量可测量提升+2.25分。
GateGuard — 事实强制操作前门控
一个PreToolUse钩子，强制Claude在编辑前进行调查。不同于自我评估（“你确定吗？”），它要求具体事实。调查行为本身创造了自我评估从未实现的意识。
何时激活
- 处理任何文件编辑影响多个模块的代码库
- 项目包含具有特定模式或日期格式的数据文件
- 团队要求AI生成的代码必须匹配现有模式
- 任何Claude倾向于猜测而非调查的工作流程
核心概念
LLM自我评估无效。问“你是否违反了任何策略？”答案总是“没有”。这已通过实验验证。
但问“列出所有导入此模块的文件”会强制LLM运行Grep和Read。调查本身创造了改变输出的上下文。
三阶段门控：
1. 拒绝 — 阻止第一次编辑/写入/Bash尝试
2. 强制 — 告诉模型具体要收集哪些事实
3. 允许 — 在事实呈现后允许重试
没有竞争对手能做到全部三步。大多数只停留在拒绝。
证据
两个独立的A/B测试，相同的代理，相同的任务：
| 任务 | 有门控 | 无门控 | 差距 |
|---|---|---|---|
| 分析模块 | 8.0/10 | 6.5/10 | +1.5 |
| Webhook验证器 | 10.0/10 | 7.0/10 | +3.0 |
| 平均 | 9.0 | 6.75 | +2.25 |
两个代理都能生成运行并通过测试的代码。区别在于设计深度。
门控类型
编辑 / MultiEdit 门控（每个文件的第一次编辑）
MultiEdit处理方式相同——批次中的每个文件单独门控。
在编辑 {file_path} 之前，请呈现以下事实：
1. 列出所有导入/需要此文件的文件（搜索树——使用Glob/Grep，或通过Bash使用find/grep）
2. 列出受此更改影响的公共函数/类
3. 如果此文件读取/写入数据文件，请显示字段名、结构
和日期格式（使用脱敏或合成值，而非原始生产数据）
4. 逐字引用用户当前的指令
写入门控（第一次创建新文件）
在创建 {file_path} 之前，请呈现以下事实：
1. 命名将调用此新文件的文件和行号
2. 确认没有现有文件服务于相同目的（搜索树——使用Glob/Grep，或通过Bash使用find/grep）
3. 如果此文件读取/写入数据文件，请显示字段名、结构
和日期格式（使用脱敏或合成值，而非原始生产数据）
4. 逐字引用用户当前的指令
破坏性Bash门控（每次破坏性命令）
触发条件：rm -rf、git reset --hard、git push --force、drop table等。
1. 列出此命令将修改或删除的所有文件/数据
2. 写一行回滚步骤
3. 逐字引用用户当前的指令
常规Bash门控（每个会话一次）
1. 用一句话描述当前用户请求
2. 此特定命令验证或生成什么
快速开始
选项A：使用ECC钩子（零安装）
位于 scripts/hooks/gateguard-fact-force.js 的钩子已包含在此插件中。通过hooks.json启用。
如果GateGuard阻止了设置或修复工作，请以 ECC_GATEGUARD=off 启动会话。对于钩子级别的控制，继续使用 ECC_DISABLED_HOOKS 并指定GateGuard钩子ID。
在长时间会话中，只有前 GATEGUARD_FACT_FORCE_FULL_DENIALS 次事实强制拒绝（默认3次）会发出完整的四事实块；后续拒绝会压缩为一行，携带拒绝序号，这样几乎相同的块不会在上下文窗口中累积并放大模型重复循环（#2142）。在呈现事实后重试同一文件或命令不会再次触发门控。
选项B：带配置的完整包
pip install gateguard-ai
gateguard init
这会添加 .gateguard.yml 用于每个项目的配置（自定义消息、忽略路径、门控开关）。
反模式
- 不要使用自我评估代替。 “你确定吗？”总是得到“是”。这已通过实验验证。
- 不要跳过数据模式检查。 两个A/B测试代理都假设了ISO-8601日期，而实际数据使用
%Y/%m/%d %H:%M。检查数据结构（使用脱敏值）可以防止这类错误。 - 不要对每个Bash命令都门控。 常规Bash门控每个会话一次。破坏性Bash门控每次触发。这种平衡避免了速度下降，同时捕获了真正的风险。
最佳实践
- 让门控自然触发。不要试图预先回答门控问题——调查本身才是提高质量的关键。
- 为你的领域自定义门控消息。如果你的项目有特定约定，将它们添加到门控提示中。
- 使用
.gateguard.yml忽略路径，如.venv/、node_modules/、.git/。
相关技能
safety-guard— 运行时安全检查（互补，不重叠）code-reviewer— 编辑后审查（GateGuard是编辑前调查）
