Хуки: то, что должно происходить всегда

Команды, которые Claude Code сам запускает в определённые моменты, что бы ни решила модель.

К концу этого урока

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

Правило в CLAUDE.md — это просьба: модель обычно её выполняет, но может забыть. Хук — команда, которую сам Claude Code запускает в определённый момент, например после каждой правки файла или перед каждой shell-командой. Хуки нужны для того, что должно происходить каждый раз.

События, которые нужны чаще всего

1PreToolUse: перед вызовом инструмента. Может заблокировать вызов.
2PostToolUse: после успешного вызова инструмента, например после Edit или Write. Подходит для форматирования.
3Stop: каждый раз, когда Claude заканчивает ответ, а не только в конце всей задачи.
4Notification: когда Claude Code отправляет уведомление, например ждёт твоего ответа или разрешения.
5SessionStart: когда сессия начинается или возобновляется. Её вывод может добавить контекст.
6UserPromptSubmit: когда ты отправил запрос, до того как Claude его обработает.

Первый хук: форматирование после каждой правки

💬 Пусть Claude напишет его сам

«Добавь в .claude/settings.json этого проекта хук, который запускает Prettier для каждого файла, который ты правишь или записываешь. Проверь, что jq и Prettier есть, испытай хук на одном файле и покажи мне, что ты добавил.»

Claude напишет хук вроде того, что ниже, и проверит его. Остальная часть урока объясняет, что он написал, чтобы было понятно, что проверять.

.claude/settings.json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

Claude Code передаёт команде данные о событии в виде JSON на стандартный ввод. Здесь jq достаёт путь к изменённому файлу, а Prettier его форматирует. matcher ограничивает хук инструментами Edit и Write; регистр в нём важен, а для примера нужны установленные jq и Node.js.

Проверь, что работает

1Набери /hooks в Claude Code. Хук должен быть в списке под PostToolUse.
2Попроси Claude добавить в JavaScript-файл строку со строками в одинарных кавычках.
3Открой файл: с настройками Prettier по умолчанию кавычки стали двойными. Успешный хук ничего не пишет в разговор.
4Если хука нет в списке, скажи Claude: «хук форматирования не срабатывает, выясни почему».

Блокировка действия и ловушка с кодом выхода

💬 Охранник для защищённых файлов

«Добавь хук PreToolUse, который запрещает любые правки .env, package-lock.json и файлов в .git/. Скрипт должен завершаться с кодом 2 и писать причину в stderr. Сделай его исполняемым, проверь на примере JSON и покажи мне код выхода.»

Claude напишет скрипт вроде того, что ниже, подключит его и докажет, что он блокирует.

bash

#!/bin/bash
# .claude/hooks/protect-files.sh
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

for pattern in ".env" "package-lock.json" ".git/"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
    exit 2
  fi
done

exit 0

Скрипт подключается как хук PreToolUse с matcher Edit|Write и командой "$CLAUDE_PROJECT_DIR"/.claude/hooks/protect-files.sh, а в macOS и Linux он должен быть исполняемым (chmod +x); и то и другое Claude сделает по просьбе. Когда Claude попытается изменить .env, правка будет остановлена до выполнения, а сообщение Blocked: дойдёт до Claude, и он выберет другой путь.

Что означает код выхода

10: возражений нет. Для PreToolUse это не разрешение: обычная проверка разрешений всё равно действует.
22: блокировка. Причину пиши в stderr; на событиях, которые можно заблокировать, Claude получит её как обратную связь.
3Любой другой ненулевой код, например 1: неблокирующая ошибка. Действие выполняется, а в транскрипте появляется сообщение об ошибке хука.
4Исключение: хук с "onFailure": "block" блокирует действие, если сам упал.

!Классическая ошибка

Скрипт-охранник, который при нарушении заканчивается exit 1, ничего не останавливает: правка проходит, только с сообщением об ошибке. Блокирующий хук должен завершаться exit 2. Проверь его, подав на вход пример JSON: echo '{"tool_name":"Edit","tool_input":{"file_path":".env"}}' | ./protect-files.sh; echo $? должно напечатать 2.

~/.claude/settings.json действует во всех твоих проектах; .claude/settings.json относится к одному проекту, и его можно закоммитить; .claude/settings.local.json — для одного проекта и остаётся только на твоём компьютере. Хуки бывают и внутри плагинов, скиллов и сабагентов. "disableAllHooks": true отключает их.

!Хуки работают от твоего имени

Командные хуки выполняются со всеми правами твоего пользователя и могут прочитать, изменить или удалить всё, что доступно твоей учётной записи. Читай каждый хук перед добавлением, включая хуки внутри плагинов. Интерактивная сессия придерживает хуки из настроек, пока ты не доверишь папку, но claude -p диалога доверия не показывает, и хуки из .claude/settings.json склонированного репозитория выполняются. Сначала проверь папку .claude/ или используй --bare.

✦Дальше

Кроме командных хуков есть типы http, mcp_tool, prompt (одноходовая проверка моделью) и agent (экспериментальный). Запрет (deny) от хука действует в любом режиме разрешений, включая bypassPermissions. Если подходят несколько хуков, они выполняются параллельно и побеждает самое строгое решение: deny, затем defer, ask, allow. Тайм-аут по умолчанию — 10 минут для командных хуков и 30 секунд для UserPromptSubmit. PostToolUse не может отменить уже выполненное действие. /goal сам по себе — prompt-хук Stop на время сессии.

Проверь себя

Твой охранник PreToolUse нашёл запрещённую правку и завершился exit 1. Что произойдёт?

Проверь себя

Какой хук подходит для «запускать форматирование после каждого файла, который правит Claude»?

Факты проверены по официальной документации Claude Code 24 октября 2026 г. · источник

ЕА

Автор

Евгений Арсентьев

PhD · CEO, digital health

Об авторе →

Хуки: то, что должно происходить всегда

1Первый хук: форматирование после каждой правки

2Блокировка действия и ловушка с кодом выхода

Первый хук: форматирование после каждой правки

Блокировка действия и ловушка с кодом выхода