Хуки в Claude Code: 32 события и три, которые реально нужны

В документации Claude Code перечислено 32 события, к которым можно привязать свою команду. У меня задействовано два.

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

Дальше — три рабочие настройки с конфигами и одна ошибка, из-за которой хуки начинают мешать.

Хук — это обычная команда в нужный момент

Магии тут нет. Ты указываешь событие и shell-команду, Claude Code запускает её сам.

Список событий покрывает весь жизненный цикл: старт сессии, отправка промпта, вызов инструмента, отказ в разрешении, ошибка инструмента, запуск и остановка субагента, создание и удаление worktree, компактификация до и после, смена модели, смена рабочей папки, попытка завершить работу. Тридцать два пункта.

Я этот список закрывал дважды, прежде чем разобраться.

Первый: подгрузить контекст на старте

Событие SessionStart. Срабатывает при запуске сессии, вывод команды попадает агенту в контекст.

У меня туда повешена одна строка:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "code-review-graph status", "timeout": 10 }
        ]
      }
    ]
  }
}

Команда печатает состояние графа кода по проекту: сколько узлов, связей, файлов, когда обновлялся. Агент видит это до первого моего сообщения и не начинает сессию с вопроса «а что тут вообще есть».

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

Второй: обновить состояние после правки

Событие PostToolUse с фильтром по инструменту. Срабатывает после того, как агент что-то сделал.

{
  "matcher": "Edit|Write|Bash",
  "hooks": [
    { "type": "command", "command": "code-review-graph update --skip-flows", "timeout": 30 }
  ]
}

Фильтр Edit|Write|Bash — это регулярное выражение по названию инструмента. После каждой правки файла граф проекта переиндексируется, и следующий поиск идёт по свежим данным, а не по вчерашним.

Тот же паттерн закрывает вещи попроще: прогнать форматтер после записи файла или пересобрать типы после правки схемы. Всё то, что забываешь сделать и вспоминаешь через полчаса, когда что-то не собирается.

Третий: не выпускать агента с недоделанной работой

Событие Stop. Срабатывает в момент, когда агент считает задачу законченной, и умеет вернуть его обратно в работу.

Это самый полезный из трёх и самый недооценённый. Проверкой может быть что угодно: прогон тестов, проверка на заглушки в коде, отсутствие эмодзи в тексте, наличие цифр в статье. Если проверка не прошла, агент не заканчивает сессию словом «готово», а идёт доделывать.

Смысл в том, что критерий приёмки перестаёт зависеть от твоей внимательности в конкретный вечер. Ты формулируешь его один раз, дальше он применяется без тебя.

Проверка на эмодзи в черновиках выглядит так:

{
  "matcher": "",
  "hooks": [
    { "type": "command", "command": "grep -rlP '[\\x{1F300}-\\x{1FAFF}]' drafts/ && exit 2 || exit 0" }
  ]
}

Код возврата 2 отправляет агента доделывать, ноль отпускает. У меня этот гейт пока не стоит, и каждый раз, когда эмодзи проскакивает в черновик, я про него вспоминаю.

Ошибка, из-за которой хуки мешают

Хук выполняется на каждое совпадение, без исключений. Ровно за это его и ставят.

Поэтому тяжёлая команда на частом событии превращает работу в ожидание. Полная пересборка проекта на PostToolUse занимает столько же, сколько сама правка, а срабатывает она после каждой.

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

Второе: хуки бывают трёх областей — общие для всех проектов, проектные и локальные. Держи в общих только то, что осмысленно в любом репозитории. Команда сборки конкретного проекта в глобальном конфиге сломает работу везде, кроме одного места.

С чего начать

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

Когда это приживётся, добавляй гейт на Stop. Остальные тридцать событий подождут: у меня из них не задействовано ни одного, и работать это не мешает.

Как собрать вокруг этого весь рабочий процесс, я разбирал в статье про настройку Claude Code под свой воркфлоу. Готовый код для хуков и автоматизаций лежит в гайде, там одиннадцать собранных систем с двумя треками — базовым и продвинутым.