---

name: gateguard description: 事实强制门控，阻止Edit/Write/Bash（包括MultiEdit）操作，要求在允许操作前进行具体调查（导入者、数据模式、用户指令）。与无门控Agent相比，可测量地提升输出质量+2.25分。 origin: community

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测试，相同Agent，相同任务：

| 任务 | 有门控 | 无门控 | 差距 | | --- | --- | --- | --- | | 分析模块 | 8.0/10 | 6.5/10 | +1.5 | | Webhook验证器 | 10.0/10 | 7.0/10 | +3.0 | | 平均 | 9.0 | 6.75 | +2.25 |

两个Agent都能产生可运行并通过测试的代码。区别在于设计深度。

门控类型

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

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

Before editing {file_path}, present these facts:

1. List ALL files that import/require this file (use Grep)
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 (use Glob)
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测试Agent都假设ISO-8601日期，而真实数据使用%Y/%m/%d %H:%M。检查数据结构（使用脱敏值）可以防止这整类bug。
• 不要对每个Bash命令都门控。 常规bash每个会话门控一次。破坏性bash每次都门控。这种平衡避免了减速同时捕获真正的风险。

最佳实践

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

相关技能

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