Хуки

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

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

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

Хук получает на стандартный ввод JSON с описанием события (какой инструмент, какие аргументы, в какой папке), может что-то сделать и ответить — кодом выхода или JSON на стандартном выводе.

События

Список событий длинный и растёт; полный — в справочнике по хукам. Для практики достаточно этих:

Есть и более специальные: FileChanged (файл на диске изменился), ConfigChange, PermissionRequest, PostToolUseFailure и другие.

Формат настроек

Хуки живут в тех же файлах, что и права: ~/.claude/settings.json для себя, .claude/settings.json для команды, .claude/settings.local.json для себя в этом проекте. Структура: событие → список групп с matcher → список обработчиков.

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

matcher для событий инструментов — имя инструмента: Bash, Edit|Write, регулярное выражение вроде mcp__.* для всех MCP-инструментов. Пустая строка или * — любое. Для Stop и UserPromptSubmit matcher не нужен. Дополнительно можно сузить условием "if": "Bash(rm *)" в синтаксисе правил разрешений.

Тип обработчика command — обычная команда. Ещё есть prompt (решение принимает модель по вашему тексту) и agent (субагент с инструментами, экспериментальный). У обработчика есть timeout в секундах (по умолчанию 600 для команд) и флаг async, чтобы не блокировать сессию.

Скрипты удобно держать в .claude/hooks/ и ссылаться через ${CLAUDE_PROJECT_DIR} — так путь не зависит от того, из какой подпапки запущен Claude. Скрипт должен быть исполняемым (chmod +x).

Посмотреть, что настроено, — команда /hooks. Меню только для чтения; менять — в JSON руками или попросив Claude («напиши хук, который запускает eslint после каждой правки» — он умеет).

Как хук отвечает

Три варианта ответа, из которых нужно выбрать один на хук:

• Код выхода 0 без вывода — всё в порядке, продолжаем.
• Код выхода 2 — заблокировать действие. Текст из stderr уходит Claude как обратная связь (для PreToolUse, Stop, UserPromptSubmit), и он подстраивается. Для PostToolUse блокировать уже нечего — событие после факта.
• Код выхода 0 и JSON на stdout — структурированное решение. Для PreToolUse это permissionDecision: allow, deny или ask, плюс permissionDecisionReason и при необходимости updatedInput — изменённые аргументы. Есть общие поля additionalContext (добавить Claude информацию) и systemMessage (показать пользователю).

Любой другой код выхода — неблокирующая ошибка: в транскрипте появится пометка, действие продолжится.

Важно про взаимодействие с правами: PreToolUse срабатывает до проверки режима, в любом режиме, включая bypassPermissions. Хук, ответивший deny, блокирует даже там. Обратное неверно: allow от хука не отменяет правило deny из настроек. Хуки могут ужесточить, но не ослабить.

Пример 1. Форматирование после каждой правки

Самый простой и самый полезный хук. После любой правки файла запускаем форматтер — и в дифах больше нет шума от отступов:

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

jq вытаскивает путь из входного JSON, xargs передаёт его Prettier. Для файлов, которые меняются shell-командами, а не инструментом редактирования, есть событие FileChanged.

Пример 2. Защита файлов

Запрещаем Claude трогать .env, lock-файл, папку миграций и .git/, чем бы ни закончилась проверка прав. Скрипт .claude/hooks/protect-files.sh:

#!/bin/bash
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
FILE_PATH="${FILE_PATH//\\//}"

PROTECTED=(".env" "pnpm-lock.yaml" "prisma/migrations/" ".git/")

for pattern in "${PROTECTED[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Заблокировано: $FILE_PATH попадает под шаблон '$pattern'" >&2
    exit 2
  fi
done
exit 0

Регистрация:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
          }
        ]
      }
    ]
  }
}

Код выхода 2 блокирует правку, а сообщение из stderr Claude получает как объяснение и меняет подход — например, предлагает вам самому создать миграцию. Правило deny в настройках сделало бы похожее, но хук умеет то, что правилу недоступно: проверять содержимое команды, время, ветку, что угодно.

Пример 3. Не завершать ход, пока не прошли тесты

Тот самый жёсткий барьер, о котором шла речь в уроке про навыки проверки. Хук на Stop запускает тесты; если они падают, Claude не может завершить ход и продолжает работу. Скрипт .claude/hooks/tests-before-stop.sh:

#!/bin/bash
INPUT=$(cat)

# Если хук уже возвращал Claude к работе, не зацикливаемся
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0
fi

cd "$CLAUDE_PROJECT_DIR" || exit 0

# Нечего проверять — выходим
if git diff --quiet && git diff --cached --quiet; then
  exit 0
fi

OUTPUT=$(pnpm test 2>&1)
if [ $? -ne 0 ]; then
  echo "Тесты не проходят. Исправь падения и покажи вывод pnpm test:" >&2
  echo "$OUTPUT" | tail -n 30 >&2
  exit 2
fi
exit 0

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/tests-before-stop.sh",
            "timeout": 300
          }
        ]
      }
    ]
  }
}

Две детали, без которых хук будет вредить. Поле stop_hook_active во входном JSON говорит, что Claude уже продолжил работу по требованию этого хука; без проверки он будет гонять тесты по кругу. Claude Code сам снимает барьер после восьми блокировок подряд без прогресса, но лучше до этого не доводить. И timeout: тесты могут идти дольше стандартного лимита — задайте свой.

Если проверка требует не команды, а суждения, есть хук типа prompt: он отправляет ваш текст и данные события модели, которая отвечает ok: true или ok: false с причиной. Например: «Проверь, все ли пункты задачи выполнены; если нет — верни список оставшегося». Это дешёвый способ добавить самопроверку без скрипта.

Уведомление, когда Claude ждёт

Для длинных сессий полезен хук на Notification: когда Claude Code ждёт подтверждения, а вы переключились в другое окно, придёт системное уведомление. На macOS:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code ждёт ответа\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

Этот хук личный, ему место в ~/.claude/settings.json.

Где какой хук держать

Командные хуки (форматтер, защита файлов, тесты перед остановкой) коммитьте в .claude/settings.json — они должны работать у всех одинаково. Личные (уведомления) — в ~/.claude/settings.json. Если набор хуков нужен в двадцати проектах, его упаковывают в плагин с файлом hooks/hooks.json того же формата — об этом в уроке «Плагины».

Помните и о доверии: хуки из .claude/settings.json чужого репозитория выполняются на вашей машине. Claude Code спрашивает, доверяете ли вы папке, прежде чем применить проектные хуки; читайте, что подключаете.