gateguard

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GateGuard — Fact-Forcing Pre-Action Gate

GateGuard — 事实验证前置关卡

A PreToolUse hook that forces Claude to investigate before editing. Instead of self-evaluation ("are you sure?"), it demands concrete facts. The act of investigation creates awareness that self-evaluation never did.

这是一个PreToolUse钩子，强制Claude在编辑前先进行调查。它不采用自我评估（“你确定吗？”）的方式，而是要求提供具体事实。调查过程本身能建立起自我评估永远无法实现的认知。

When to Activate

激活场景

Working on any codebase where file edits affect multiple modules
Projects with data files that have specific schemas or date formats
Teams where AI-generated code must match existing patterns
Any workflow where Claude tends to guess instead of investigating

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

Core Concept

核心理念

LLM self-evaluation doesn't work. Ask "did you violate any policies?" and the answer is always "no." This is verified experimentally.

But asking "list every file that imports this module" forces the LLM to run Grep and Read. The investigation itself creates context that changes the output.

Three-stage gate:

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

No competitor does all three. Most stop at deny.

大语言模型（LLM）的自我评估无效。问“你是否违反了任何政策？”得到的答案永远是“没有”，这已通过实验验证。

但如果要求“列出所有导入该模块的文件”，则会迫使LLM运行Grep和Read操作。调查过程本身会构建上下文，从而改变输出结果。

三阶段关卡流程：

1. 拦截 — 阻止首次编辑/写入/Bash尝试
2. 强制 — 明确告知模型需要收集哪些事实
3. 允许 — 在提交事实后允许重试

没有竞品能做到这三点，大多数仅停留在拦截阶段。

Evidence

验证数据

Two independent A/B tests, identical agents, same task:

Task	Gated	Ungated	Gap
Analytics module	8.0/10	6.5/10	+1.5
Webhook validator	10.0/10	7.0/10	+3.0
Average	9.0	6.75	+2.25

Both agents produce code that runs and passes tests. The difference is design depth.

两组独立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生成的代码均可运行并通过测试，差异在于设计深度。

Gate Types

关卡类型

Edit / MultiEdit Gate (first edit per file)

编辑 / 多文件编辑关卡（每个文件首次编辑时触发）

MultiEdit is handled identically — each file in the batch is gated individually.

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

多文件编辑的处理方式相同 — 批量中的每个文件会单独触发关卡。

在编辑{file_path}前，请提供以下事实：

1. 列出所有导入/引用该文件的文件（使用Grep）
2. 列出此变更会影响的公开函数/类
3. 如果该文件会读取/写入数据文件，请展示字段名称、结构、
   和日期格式（使用脱敏或合成值，而非原始生产数据）
4. 逐字引用用户当前的指令

Write Gate (first new file creation)

写入关卡（首次创建新文件时触发）

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

在创建{file_path}前，请提供以下事实：

1. 指明将调用此新文件的文件及行号
2. 确认没有现有文件具备相同功能（使用Glob）
3. 如果该文件会读取/写入数据文件，请展示字段名称、结构、
   和日期格式（使用脱敏或合成值，而非原始生产数据）
4. 逐字引用用户当前的指令

Destructive Bash Gate (every destructive command)

破坏性Bash关卡（每次执行破坏性命令时触发）

Triggers on:

rm -rf

git reset --hard

git push --force

drop table

, etc.

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

触发场景：

rm -rf

、

git reset --hard

、

git push --force

、

drop table

等

1. 列出该命令将修改或删除的所有文件/数据
2. 编写一行回滚流程
3. 逐字引用用户当前的指令

Routine Bash Gate (once per session)

常规Bash关卡（每个会话触发一次）

Quote the user's current instruction verbatim.

逐字引用用户当前的指令。

Quick Start

快速开始

Option A: Use the ECC hook (zero install)

选项A：使用ECC钩子（无需安装）

The hook at

scripts/hooks/gateguard-fact-force.js

is included in this plugin. Enable it via hooks.json.

本插件包含位于

scripts/hooks/gateguard-fact-force.js

的钩子，可通过hooks.json启用。

Option B: Full package with config

选项B：完整配置包

bash

pip install gateguard-ai
gateguard init

This adds

.gateguard.yml

for per-project configuration (custom messages, ignore paths, gate toggles).