Хуки и Preflight-контроль | Cursor & Antigravity Rules Guide

🛑

Проблема: Текст правила — это просьба, а не гарантия

Сколько бы восклицательных знаков вы ни ставили в правиле («НЕ ПРАВЬ КОД БЕЗ ПРОВЕРКИ!!!»), языковая модель всё равно может сразу вызвать инструмент edit_file или write_file. В стрессовой ситуации или при спешке модель просто игнорирует текстовый запрет.

Решение: Хуки жизненного цикла Cursor (Hooks). Это Python-программы, которые запускаются средой разработки перед тем, как разрешить агенту применить инструмент. Если проверка не пройдена, хук возвращает JSON с permission: "deny", и IDE физически блокирует запись на диск.

⚙️ Конфигурация hooks.json

{
  "version": 1,
  "hooks": {
    "sessionStart": [
      { "command": "python3 .cursor/hooks/rules_preflight_session_start.py", "timeout": 5 }
    ],
    "preToolUse": [
      { "command": "python3 .cursor/hooks/rules_preflight_gate.py", "failClosed": true, "timeout": 8 },
      { "command": "python3 .cursor/hooks/rules_sheet_gate.py", "failClosed": false, "timeout": 5 },
      { "command": "python3 .cursor/hooks/rules_probe_log.py", "failClosed": false, "timeout": 3 }
    ]
  }
}

sessionStart

Срабатывает при открытии нового окна. Инициализирует состояние и подготавливает список обязательных правил к прочтению.

preToolUse (Gate)

Вызывается перед каждым инструментом. Проверяет: прочитал ли агент инварианты и создал ли Preflight Sheet перед редактированием.

Probe & Audit Log

Логирует траекторию вызовов инструментов для последующего анализа в документе причин сбоев.

📄 Как устроен Preflight Sheet (rules_sheet_gate.py)

Обязательно для src/

Хук запрещает редактировать любые файлы в src/, packages/ и scripts/, пока агент не запишет во временный файл .cursor/hooks/.state/preflight_<id>.md три строго валидируемые строки:

DRY:  src/shared/math/vectorUtils.ts :: calculateSceneBounds
CARD: C3
UI:   MobX editorStore.selectedMesh, e.stopPropagation()

1. Строка DRY:
Python проверяет на диске: файл реально существует? И действительно ли внутри файла объявлена названная функция?

2. Строка CARD:
Python ищет заголовок карточки в файле PRODUCT_TOOLS_AGENT_HUB.md, чтобы убедиться, что агент сверился с каталогом фич.

3. Строка UI:
Фиксация дисциплины: если есть интерфейс, где хранится состояние (MobX) и есть ли защита от сквозного клика на холст.

💥

Поучительный инцидент: Катастрофа 120 обязательных чтений

В первой версии preflight-хука разработчики решили перестраховаться и вставили в sessionStart логикуglob("*.mdc"). Хук требовал от агента обязательно прочитать все 120 файлов правил перед тем, как сделать хоть одно действие.

Что произошло в реальности:
Агент тратил 10 минут на бесконечное чтение сотен файлов, быстро исчерпывал лимиты вызовов инструментов (Tool Limit), контекст переполнялся мусором, и модель полностью висла. В итоге PM просто выключил хуки, переименовав конфиг в hooks.json.off!

Главный урок: «Чрезмерный контроль с недостижимым порогом хуже полного отсутствия контроля, потому что он парализует работу и заставляет людей полностью отключать систему безопасности».

В текущей версии порог сократили до 4 обязательных файлов (.cursorrules + 3 ключевых инварианта), добавили авторазблокировку после 6 отказов (MAX_DENY = 6) и кнопку аварийного отключения (HOOKS_OFF).

Хуки и Preflight-гейты: Физический контроль кода

⚙️ Конфигурация hooks.json

📄 Как устроен Preflight Sheet (rules_sheet_gate.py)

Поучительный инцидент: Катастрофа 120 обязательных чтений