Хуки для ИИ-агента: защита от опасных команд и утечек

Что такое хук простыми словами

Представь, что ты дал ребёнку ключи от кухни. В целом он молодец: готовит, моет посуду, складывает тарелки стопочкой. Но раз в сто заходов по запарке может сунуть вилку в розетку или выкинуть твой паспорт - он же лежал на столе, мешался.

ИИ-агент устроен ровно так же. В 99% случаев всё хорошо. А в оставшийся 1% он спокойно выполнит команду, которая удалит твою папку, зальёт пароль в открытый репозиторий или снесёт рабочую базу. И сделает это бодро, с уверенным лицом и фразой «Готово!».

Чтобы этого 1% не случилось, ставят хук Хук (от англ. hook - «крючок, перехватчик») - это код, который автоматически срабатывает в определённый момент: перед командой, перед записью в файл, в конце ответа агента. Он успевает проверить действие до того, как оно произошло. - что-то вроде охранника на входе. Перед каждым опасным действием он встаёт и говорит: «Так, стоп. А ну покажи, что ты задумал».

Зачем вайбкодеру защита от опасных действий агента

Ты вайбкодер. Сваливаешь на агента кучу рутины - и правильно делаешь. Но доверие без страховки однажды стоит тебе нервов и данных. Хуки нужны, чтобы ты:

• спал спокойно - агент физически не выполнит то, что ты запретил;
• не повторял один и тот же запрет по сто раз в каждом новом чате;
• ловил ошибки заранее, а не разгребал последствия с кружкой холодного кофе в три ночи;
• не залил случайно пароли и ключи в открытый доступ - классика, на которой обжигались все.

Между «агент удалил мне три дня работы» и «агент попытался, но хук его остановил» лежит один маленький текстовый файл с правилом. Сейчас научимся его писать.

Как работают hookify-правила

Писать хуки руками на коде - больно. Поэтому есть инструмент hookify hookify - простой способ задавать хуки обычным текстом, без программирования. Ты пишешь правило в маркдаун-файле: на что смотреть и что сказать или сделать. Никакого кода. : ты создаёшь обычный текстовый файл-правило, и всё. Никакого кода.

Каждое правило отвечает на три вопроса.

КОГДА смотреть - событие (event)

Охранник не торчит сразу везде. Ты говоришь, в какой момент ему просыпаться:

• bash - когда агент собирается выполнить команду в терминале (тут ловят rm -rf, sudo и прочую тяжёлую артиллерию);
• file - когда агент пишет или правит файл (тут ловят пароли в коде и отладочный мусор);
• prompt - когда ты сам что-то написал агенту;
• stop - момент, когда агент закончил ответ (удобно для напоминалок);
• all - на любое событие.

ЧТО ловить - шаблон (pattern)

Это «словесный портрет» опасного действия. Технически - паттерн Паттерн (регулярное выражение) - это шаблон для поиска текста. Например, шаблон «rm одна-или-больше-пробелов -rf» поймает команду удаления, как бы агент её ни написал - с одним пробелом или с тремя. . Скажем, шаблон rm\s+-rf поймает страшную команду удаления, даже если агент влепит лишний пробел.

ЧТО делать - действие (action)

Поймал охранник нарушителя - и дальше у него два варианта реакции:

• warn - предупредить и пропустить. «Эй, ты точно хочешь это сделать? Ну ладно, проходи». Режим по умолчанию.
• block - заблокировать наглухо. «Стоп. Не пущу. Точка». Действие не выполнится вообще.

Как выглядит hookify-правило

Само правило - короткий текстовый файл. Сверху между двумя линиями --- идут настройки, ниже - сообщение, которое агент увидит, когда правило сработает. Вот и вся конструкция.

Опишем словами правило «блокируй опасное удаление файлов»:

• имя правила: block-rm-rf (имя лучше начинать с глагола: warn-, block-, require-);
• включено: да;
• событие: bash (следим за командами в терминале);
• действие: block (блокируем);
• шаблон: ловит команду удаления rm с флагами -rf;
• сообщение: «Стоп. Это удаление без возможности отката. Подтверди вручную, прежде чем продолжить».

Файлы правил лежат в папке .claude внутри проекта. И вот тут - самая важная мысль урока.

Пример: как хук ловит утечку секретов

Ты пилишь свой первый стартап. Подключаешь платёжку, агент создаёт файл .env и кладёт туда секретный ключ от Stripe. Через пять минут ты просишь «залей всё на гитхаб», агент бодро делает git push - и твой денежный ключ теперь виден всему интернету. Ещё пара часов - и кто-то спокойно выкачивает по нему лимит. Поздравляю, ты оплатил чужие выходные.

Знакомая катастрофа? А теперь смотри, как она гасится одним правилом.

Ты заранее ставишь хук: «как только агент пишет что-то похожее на API-ключ в файл .env - напомни проверить .gitignore». Вот промпт, который попросит агента собрать такую защиту за тебя.

Создай мне hookify-правило для защиты от утечки секретов.
Условия правила:

Событие - запись в файл (event file).
Срабатывает, когда путь файла оканчивается на .env
И когда в новом тексте встречается API_KEY, SECRET или TOKEN.
Действие - предупредить (warn), не блокировать.
Сообщение агенту: «Ты пишешь секрет в .env. Проверь, что этот
файл добавлен в .gitignore и не попадёт в публичный репозиторий».
Положи правило в папку .claude проекта и объясни мне простыми
словами, что именно оно делает.

Хорошее правило против плохого

Хуки - мощная штука, но ими легко переборщить. Повесишь block на каждый чих - и агент встанет колом: шагу ступить не сможет. Вот как поймать баланс.

Частые ошибки новичка с хуками

• Думать, что слов в чате достаточно. «Я же просил не удалять» - а агент забыл после компакта. Запрет должен жить в файле.
• Вешать block на всё подряд. Агент задохнётся, и ты сам в сердцах отключишь хуки. Блокируй только необратимое.
• Слишком широкий шаблон. Запретил слово rm - и агент больше не может написать слово «information». Делай шаблон точным.
• Запрет без подсказки «а что теперь». Агент упёрся в стену и ходит по кругу. Пиши в сообщении, как сделать правильно.
• Игнорировать .gitignore для секретов. Хук предупредил, а ты пролистал мимо. Читай, что говорит охранник.
• Не проверить, что правило вообще срабатывает. Попроси агента выполнить тестовую безопасную команду и убедись, что хук её поймал.