Полный анализ механизма Claude Code Hooks: пять типов событий, управление кодами выхода и четыре реальные конфигурации для аудита, перехвата и автоматизации действий ИИ.
Каждый раз, когда Claude Code читает файл, пишет код или выполняет команду, в фоновом режиме работает система событий. Hooks — это интерфейс для подключения к этой системе: можно внедрять собственную логику в любой момент, автоматически запускать линтеры, записывать операции, блокировать опасные действия или запускать любые shell-команды.
Эта статья полностью охватывает механизм Hooks, настройку и практическое применение.
Hooks — это shell-команды, настроенные в settings.json, которые Claude Code автоматически выполняет при наступлении определённых событий.
Самая прямая аналогия: git hooks. Git может запускать скрипты до и после операций commit и push. Claude Code Hooks работают точно так же — разница в том, что точками срабатывания являются вызовы инструментов ИИ.
Почему это важно?
Чем мощнее становится Claude Code, тем больше нужен детерминированный уровень контроля. Hooks обеспечивают:
- Гарантии выполнения, не зависящие от промпта (Claude может игнорировать инструкции, но hook выполнится всегда)
- Проверяемые журналы операций
- Автоматизированные проверки качества
| Тип | Триггер | Типичное использование |
|---|---|---|
PreToolUse |
До вызова инструмента | Блокировка опасных операций, запись намерения |
PostToolUse |
После вызова инструмента | Авто-линт, запуск тестов |
PreCompact |
До сжатия контекста | Сохранение снапшота текущего состояния |
Notification |
Когда Claude отправляет уведомление | Десктопные уведомления, сообщения в Slack |
Stop |
Когда Claude завершает ответ | Сводка логов, запуск последующих процессов |
Чаще всего используются PreToolUse и PostToolUse — для перехвата и постобработки вызовов инструментов.
Hooks записываются в ~/.claude/settings.json (глобально) или в .claude/settings.json в корне проекта (уровень проекта):
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [{"type": "command", "command": "npm run lint --silent"}]
}
]
}
}
Три ключевых поля: matcher — regex для имён инструментов; type — только "command"; command — любая shell-команда.
| Код | Значение |
|---|---|
0 |
Успех, продолжить выполнение |
2 |
Блокировка: отменить вызов инструмента, передать stderr Claude |
| Другой ненулевой | Записать ошибку, продолжить |
Код 2 наиболее полезен — позволяет писать логику перехвата в PreToolUse.
Автоформатирование после записи файлов — PostToolUse на Write|Edit, запускает rubocop для .rb файлов.
Запрет удаления каталогов — PreToolUse на Bash, при обнаружении rm .*/migrations возвращает код 2.
Журнал аудита — PostToolUse на Write|Edit|Bash, дописывает в ~/.claude/audit.log.
Уведомление по завершении — Stop hook, запускает osascript или notify-send.
Глобальный (~/.claude/settings.json): правила для всех проектов. Уровень проекта (.claude/settings.json): специфичные проверки. Оба набора объединяются и выполняются вместе. Рекомендуется коммитить settings.json проекта в git.
Write не writeecho "triggered" >> /tmp/hook.log для диагностикиЦенность Hooks — соединить непредсказуемое поведение ИИ с детерминированными инженерными стандартами. Claude может забыть запустить тесты, но PostToolUse hook — нет. Начните с одного hook: авто-линт после записи файлов.