GateGuard — Контрольный этап перед действием, основанный на фактах

Хук PreToolUse, который заставляет Клода проводить расследование перед редактированием. Вместо самооценки («вы уверены?») он требует конкретных фактов. Сам процесс расследования формирует осознанность, которой самооценка никогда не могла обеспечить.

Когда активировать

• При работе с любой кодовой базой, где редактирование файлов затрагивает несколько модулей
• Проекты с файлами данных, имеющими определённые схемы или форматы даты
• В командах, где код, сгенерированный ИИ, должен соответствовать существующим шаблонам
• Любой рабочий процесс, в котором 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

Ни один из конкурентов не выполняет все три этапа. Большинство останавливаются на этапе «отрицания».

Доказательства

Два независимых A/B-теста, идентичные агенты, одна и та же задача:

Оба агента генерируют код, который работает и проходит тесты. Разница заключается в глубине проектирования.

Типы контрольных точек

Ворота «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

Шлюз записи (создание первого нового файла)

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

Шлюз «Destructive 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.

В длительных сессиях только первые 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 — это проверка до редактирования)