Хуки в Claude Code: как автоматизировать проверки

Хуки в Claude Code (в англоязычной документации — Claude Code hooks) — команды, которые выполняются автоматически в определённые моменты работы агента: перед вызовом инструмента, после изменения файла, когда агент заканчивает ответ, при старте сессии и в других точках. Хук может запустить форматирование, прогнать тесты, отправить уведомление, добавить агенту контекст — или запретить действие, которое нарушает ваши правила. Главное отличие от инструкций в CLAUDE.md: инструкцию модель может проигнорировать, а хук срабатывает всегда.

Для команды хуки — способ превратить договорённости в гарантии. «Всегда форматируй код», «не трогай .env», «запускай тесты перед тем, как сказать, что готово» перестают зависеть от того, насколько внимательно агент прочитал инструкции. В статье — как хуки устроены, где их настраивать, как они принимают решения и семь рецептов, которые можно взять как есть. Короткая справка — в карточке /hooks в справочнике по Claude Code.

Что такое хуки и чем они отличаются от CLAUDE.md

У Claude Code есть два способа влиять на поведение агента. Первый — инструкции: файл CLAUDE.md, правила, скиллы. Это текст, который попадает в контекст модели, и модель старается ему следовать. Документация прямо говорит, что Claude воспринимает такие файлы как контекст, а не как обязательную конфигурацию. Обычно этого достаточно, но в длинной сессии, после сжатия контекста или в нестандартной ситуации инструкция может быть проигнорирована.

Второй способ — хуки. Это обычные программы: скрипт в терминале, запрос к серверу, вызов инструмента. Их запускает сам Claude Code, а не модель, и модель не может решить «в этот раз не запускать». Если хук сказал «нельзя», действие не выполнится. Поэтому документация рекомендует для запретов, которые должны работать всегда, использовать не строчку в CLAUDE.md, а хук на событие PreToolUse.

Удобное правило распределения: в CLAUDE.md — то, что помогает агенту работать лучше (соглашения, команды, устройство проекта), в хуки — то, что должно происходить без исключений (форматирование, проверки, запреты). Как писать CLAUDE.md, разобрано в гайде файл CLAUDE.md.

Где хранятся настройки хуков

Хуки описываются в JSON-файлах настроек. От места хранения зависит, на какие проекты хук действует и попадёт ли он к коллегам.

Хуки с разных уровней не заменяют, а дополняют друг друга: срабатывают все подходящие. Для команды основное место — .claude/settings.json в репозитории: хуки проекта приходят к каждому вместе с кодом. Личные удобства вроде уведомлений на рабочий стол — в ~/.claude/settings.json. Посмотреть все действующие хуки и отключить лишние можно командой /hooks прямо в сессии.

Структура настройки — три уровня вложенности: событие (например, PostToolUse), группа с фильтром-матчером (например, только инструменты Edit и Write) и один или несколько обработчиков, которые выполняются при совпадении. Все подходящие обработчики запускаются параллельно, а одинаковый обработчик, описанный в нескольких файлах, выполняется один раз.

События: когда срабатывает хук

В документации Claude Code больше 30 событий — от старта сессии и переключения модели до создания рабочей копии репозитория. Для большинства задач хватает десятка основных.

Матчер уточняет, для чего срабатывает хук. Для PreToolUse и PostToolUse это имя инструмента: Bash, Edit|Write, инструменты MCP-серверов. Дополнительное поле if позволяет сузить условие правилом в синтаксисе разрешений, например Bash(git *) — только для команд git, или Edit(*.ts) — только для правок файлов TypeScript.

Как хук принимает решение: вход, выход, код 2

Когда событие срабатывает, Claude Code передаёт хуку описание события в формате JSON: для команды — на стандартный ввод. В описании есть общие поля (идентификатор сессии, рабочая папка, имя события) и поля события: для PreToolUse — имя инструмента и его параметры, например текст команды или путь к файлу. Скрипт читает это описание, проверяет, что нужно, и сообщает результат кодом выхода и выводом.

Код 0 — всё в порядке, действие продолжается. Если хук при этом печатает JSON, Claude Code читает из него решение и дополнительные поля, например контекст для агента. Код 2 — блокирующая ошибка: на событиях, которые могут блокировать, действие отменяется, а текст из стандартного потока ошибок передаётся агенту как объяснение. Для PreToolUse код 2 блокирует вызов даже если в JSON написано «разрешить». Любой другой код для большинства событий не блокирует: действие продолжается, а в журнале появляется сообщение об ошибке хука.

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

Семь рецептов на каждый день

1. Форматирование после каждой правки. Событие PostToolUse, матчер Edit|Write, команда, которая берёт путь к файлу из входных данных и запускает форматтер проекта — Prettier, Black, gofmt. Агент больше не тратит время на отступы, а в пул-реквестах нет правок «исправил форматирование». Команду форматтера подставьте свою — ту, что уже используется в проекте.

2. Запрет опасных команд. PreToolUse с матчером Bash и скриптом из предыдущего раздела: проверка текста команды на rm -rf, git push --force, удаление базы данных. Код 2 и понятное объяснение в потоке ошибок — агент увидит причину и предложит другой путь.

3. Защита секретов. PreToolUse для инструментов чтения и правки файлов: если путь указывает на .env, ключи или папку с сертификатами — код 2. Правило в CLAUDE.md «не читай .env» агент может нарушить, а хук — нет, сколько бы ни длилась сессия.

4. Тесты перед завершением. Событие Stop: когда агент решил, что закончил, хук запускает тесты. Если они падают — код 2 и вывод тестов в поток ошибок, и агент продолжает работу, пока тесты не пройдут. Если тесты идут долго, их удобнее запускать асинхронно после каждой правки файла и сообщать результат агенту по готовности — такой пример есть в документации. 5. Уведомление. Событие Notification: звук или сообщение на рабочий стол, когда агенту нужно ваше решение. Полезно для длинных задач, пока вы заняты другим.

6. Контекст при старте. Событие SessionStart: хук выводит текущую ветку git, 5 последних коммитов и список открытых задач из трекера, и Claude Code добавляет этот вывод в контекст. Агент с первой минуты знает, что сейчас происходит в проекте, и вам не нужно рассказывать это заново в каждой сессии.

7. Журнал действий. Событие PostToolUse без матчера, обработчик дописывает в файл время, имя инструмента и его параметры, а в компании — отправляет то же самое HTTP-запросом в общую систему журналов. Через месяц такой журнал отвечает на вопрос «что агент делал в пятницу вечером», который иначе задать некому.

Не только команды: HTTP, MCP, промпт и агент

Обработчиков пять типов. command — скрипт в терминале, самый частый вариант. http — отправка описания события POST-запросом на адрес: удобно для централизованного журнала или корпоративной системы контроля; для таких адресов можно задать список разрешённых. mcp_tool — вызов инструмента на подключённом MCP-сервере.

prompt — отправка описания события модели Claude для одношаговой оценки с решением в JSON. Это полезно, когда правило сложно описать скриптом: «не завершай работу, пока не выполнены все пункты из исходной задачи». agent — запуск субагента, который может сам почитать файлы и поискать по проекту, прежде чем принять решение. Два последних типа гибче, но медленнее и сами расходуют лимиты, поэтому для простых проверок лучше скрипт.

Хуки можно встраивать в скиллы и описания субагентов: тогда они действуют, только пока активен скилл или работает субагент. Это удобно для узких сценариев — например, строгие проверки только во время миграции базы данных. Готовые наборы хуков распространяются в составе плагинов; подборки есть в маркетплейсе скиллов.

Безопасность и отладка

Хуки выполняются автоматически с правами вашего пользователя, поэтому к ним применимы те же правила, что к любому скрипту из интернета. Читайте код хуков из чужих плагинов и репозиториев перед установкой. Используйте абсолютные пути к скриптам, берите в кавычки переменные, проверяйте входные данные — описание события формирует модель, и в нём может оказаться что угодно. В интерактивной сессии Claude Code не запускает хуки ни из одного файла настроек, пока вы не подтвердите доверие к папке.

С неинтерактивным режимом — отдельная ловушка. При запуске claude -p или через SDK диалога доверия нет, папка считается доверенной, и хуки из файла .claude/settings.json чужого репозитория выполнятся сразу. Прежде чем запускать агента в скрипте на репозитории, который писали не вы, просмотрите его папку .claude/ или отключите хуки для этого запуска.

Для компаний есть корпоративный режим: администратор может разрешить только хуки из управляемых настроек и заблокировать пользовательские, проектные и плагинные. Это защищает от ситуации, когда хук из случайного репозитория получает доступ к рабочему компьютеру сотрудника.

Если хук не срабатывает, начните с команды /hooks — она показывает, какие хуки загружены и откуда. Затем проверьте матчер (имя инструмента должно совпадать точно, например Bash или Edit), что скрипт исполняемый и что он читает стандартный ввод. Подробный журнал выполнения хуков пишется в режиме отладки Claude Code. Хорошая практика — сначала протестировать скрипт вручную, подав ему на вход пример JSON из документации, и только потом подключать к агенту. Другие команды для диагностики — в справочнике по Claude Code.

Как внедрять Claude Code hooks в команде, чтобы они помогали, а не раздражали. Первая неделя — 1–2 хука, которые ничего не блокируют: форматирование после правки и уведомление. Вторая — 1 запрет с понятным объяснением, например защита файлов с секретами. Третья — проверка тестов на событии Stop. Каждый новый хук стоит обсудить с командой и записать в README проекта, зачем он нужен: хук, причину которого никто не помнит, рано или поздно отключат как «мешающий».

Автор: Артём Беспалов, маркетинговое ИИ-агентство «Термос Беспалова», Калининград.

Источники: справочник Claude Code по хукам · документация Claude Code о CLAUDE.md (проверено 27.09.2026).