Back to Details

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:
TaskGatedUngatedGap
Analytics module8.0/106.5/10+1.5
Webhook validator10.0/107.0/10+3.0
Average9.06.75+2.25
Both agents produce code that runs and passes tests. The difference is design depth.
两组独立A/B测试，使用相同Agent和任务：
任务带关卡无关卡差距
分析模块8.0/106.5/10+1.5
Webhook验证器10.0/107.0/10+3.0
平均9.06.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).
bash
pip install gateguard-ai
gateguard init
这会添加
.gateguard.yml
文件用于项目级配置（自定义消息、忽略路径、开关关卡）。

Anti-Patterns

反模式

  • Don't use self-evaluation instead. "Are you sure?" always gets "yes." This is experimentally verified.
  • Don't skip the data schema check. Both A/B test agents assumed ISO-8601 dates when real data used 
    %Y/%m/%d %H:%M
    . Checking data structure (with redacted values) prevents this entire class of bugs.
  • Don't gate every single Bash command. Routine bash gates once per session. Destructive bash gates every time. This balance avoids slowdown while catching real risks.
  • 不要用自我评估替代：“你确定吗？”的答案永远是“是”，这已通过实验验证。
  • 不要跳过数据架构检查：两组A/B测试的Agent都假设使用ISO-8601日期格式，但实际数据采用的是
    %Y/%m/%d %H:%M
    。检查数据结构（使用脱敏值）可避免这类全部bug。
  • 不要拦截所有Bash命令：常规Bash关卡每个会话触发一次，破坏性Bash关卡每次触发。这种平衡可避免流程变慢，同时捕捉真实风险。

Best Practices

最佳实践

  • Let the gate fire naturally. Don't try to pre-answer the gate questions — the investigation itself is what improves quality.
  • Customize gate messages for your domain. If your project has specific conventions, add them to the gate prompts.
  • Use 
    .gateguard.yml
    to ignore paths like 
    .venv/
    , 
    node_modules/
    , 
    .git/
    .
  • 让关卡自然触发。不要试图预先回答关卡问题 — 调查过程本身就是提升质量的关键。
  • 根据你的领域自定义关卡提示。如果项目有特定约定，可将其添加到关卡提示中。
  • 使用
    .gateguard.yml
    忽略
    .venv/
    、
    node_modules/
    、
    .git/
    等路径。

Related Skills

相关技能

  • safety-guard
    — Runtime safety checks (complementary, not overlapping)
  • code-reviewer
    — Post-edit review (GateGuard is pre-edit investigation)
  • safety-guard
    — 运行时安全检查（互补而非重叠）
  • code-reviewer
    — 编辑后审查（GateGuard是编辑前调查）