Практика До 12 минут Уровень: продвинутый

Claude Code: как ловить повторяющиеся ошибки с помощью hooks

Claude Code: как ловить повторяющиеся ошибки с помощью hooks
Temporary fallback cover; replace in editorial pass.

Hook — это автоматическая проверка, которая запускается вокруг действия Claude Code. В отличие от одной только инструкции в CLAUDE.md, hook может остановить запрещённый вызов инструмента или потребовать проверку перед завершением сессии.

Самое важное из мира AI — в канале MAX AgentLabОтдельные разборы, инструменты и практические схемы Читайте Agent Lab в Telegram Разборы, кейсы и новости о практических AI-агентах без лишней воды.

Почему CLAUDE.md иногда недостаточно

CLAUDE.md задаёт контекст: правила проекта, предпочтения по стилю и ограничения для агента. Но это всё ещё текстовая инструкция. Если задача длинная, контекст меняется или правило сформулировано неоднозначно, Claude Code может снова выбрать уже запрещённый путь.

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

  • PreToolUse — блокирует опасный или явно запрещённый вызов до его выполнения;
  • Stop — не позволяет без проверки объявить исправление завершённым.

Примеры ниже предназначены для адаптации. Пути, названия команд и правила нужно заменить на те, что действительно используются в вашем репозитории.

Что будем защищать

Возьмём типичный сценарий. В проекте запрещено напрямую менять файлы миграций, а любое заявление «исправление готово» должно подтверждаться проверкой рабочего дерева и запуском существующей команды проверки.

Это не означает, что hook должен самостоятельно доказывать корректность всей программы. Его задача уже и безопаснее: поймать конкретный риск. Например, он может отклонить вызов инструмента, если тот пытается выполнить команду с запрещённым шаблоном, а при остановке — запустить короткую локальную проверку.

Шаг 1. Зафиксируйте правила в CLAUDE.md

Начните с понятных правил проекта. Формулировка должна описывать действие, а не намерение. Сравните:

# Неудачная формулировка
Пожалуйста, будьте осторожны с миграциями.

# Более проверяемая формулировка
Не изменяй файлы в db/migrations/ напрямую.
Перед заявлением об исправлении запусти:
./scripts/verify-fix.sh

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

Шаг 2. Добавьте PreToolUse для запрещённых команд

Для проверки до вызова инструмента удобно использовать небольшой скрипт. Ниже пример на POSIX shell. Он читает JSON из стандартного ввода, ищет команду и отклоняет вызов, если в ней встречается явно запрещённый путь.

#!/bin/sh
set -eu

payload=$(cat)

command=$(printf '%s' "$payload" |
  jq -r '.tool_input.command // empty')

case "$command" in
  *db/migrations/*)
    echo "Запрещено: прямое изменение db/migrations/" >&2
    exit 2
    ;;
esac

exit 0

Сохраните скрипт, например, как .claude/hooks/block-migrations.sh, и сделайте его исполняемым:

mkdir -p .claude/hooks
chmod 700 .claude/hooks/block-migrations.sh

Команда chmod изменяет только права указанного файла. Если скрипт лежит в другом месте, подставьте точный путь и проверьте его перед запуском.

Теперь подключите hook к событию PreToolUse. Конкретный формат конфигурации зависит от версии и способа настройки Claude Code, поэтому используйте синтаксис, поддерживаемый вашей установленной версией. Концептуально правило должно выглядеть так:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/block-migrations.sh"
          }
        ]
      }
    ]
  }
}

Здесь matcher ограничивает область действия hook вызовами инструмента командной строки. Если ваш рабочий процесс редактирует файлы через другой инструмент, добавьте отдельное правило для него или выберите иной уровень контроля.

Почему проверять нужно до выполнения

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

Шаг 3. Настройте Stop для подтверждения результата

Второй класс ошибок — преждевременное заявление об успехе. Модель может написать «исправлено», хотя тесты не запускались, рабочее дерево содержит незапланированные изменения или проблема просто не была воспроизведена.

Hook Stop должен запускать узкую проверку завершения. Для примера предположим, что в проекте уже есть скрипт ./scripts/verify-fix.sh. Не создавайте такую команду только ради статьи: подставьте существующую проверку проекта или сначала определите её отдельно.

#!/bin/sh
set -eu

if [ ! -x "./scripts/verify-fix.sh" ]; then
  echo "Проверка не настроена: нет исполняемого ./scripts/verify-fix.sh" >&2
  exit 2
fi

./scripts/verify-fix.sh

Сохраните его как .claude/hooks/verify-before-stop.sh и ограничьте права:

chmod 700 .claude/hooks/verify-before-stop.sh

Затем подключите его к Stop:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/verify-before-stop.sh"
          }
        ]
      }
    ]
  }
}

Если проверка завершается ненулевым кодом, остановка должна считаться неуспешной согласно поведению вашей версии Claude Code. В результате агент не должен безусловно сообщать о завершённом исправлении: сначала нужно разобраться с причиной сбоя или явно сообщить, что работа не закончена.

Шаг 4. Объедините правила без конфликтов

На практике настройки hooks могут расти. Держите каждую проверку узкой и именуйте её по событию и риску:

.claude/
  hooks/
    block-migrations.sh
    verify-before-stop.sh

Не помещайте в один скрипт десятки несвязанных правил. Если одна проверка блокирует миграции, а другая анализирует статус Git, их проще отлаживать отдельно. Общий конфигурационный файл должен только выбирать событие, инструмент и команду.

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

Безопасные команды для проверки

Проверяйте конфигурацию и скрипты небольшими командами с явными путями. Например:

test -x .claude/hooks/block-migrations.sh
test -x .claude/hooks/verify-before-stop.sh
jq empty path/to/settings.json
git diff -- .claude/hooks
git status --short

Эти команды не меняют рабочие файлы. Команда jq empty проверяет синтаксис JSON, а git diff и git status помогают увидеть, что именно изменилось.

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

Как проверить результат воспроизводимо

  1. Проверьте, что конфигурация читается вашей версией Claude Code.
  2. Запустите безопасную команду через обычный путь и убедитесь, что она не блокируется.
  3. Подготовьте контролируемый вызов, содержащий запрещённый путь, но не выполняющий изменение.
  4. Убедитесь, что PreToolUse отклоняет вызов до выполнения команды.
  5. Измените состояние проекта так, чтобы проверка завершения была неуспешной.
  6. Убедитесь, что Stop не позволяет считать исправление подтверждённым.
  7. После этого восстановите рабочее состояние и повторите проверку с успешным результатом.

Для каждого hook записывайте ожидаемое поведение: событие, входные данные, exit code и сообщение об отказе. Если поведение отличается, сначала проверьте формат входного JSON и точное имя инструмента — это частая причина ложного ощущения, что hook «не работает».

Типовые ошибки

Hook не запускается

Проверьте путь, права на выполнение, синтаксис конфигурации и соответствие matcher реальному имени инструмента. Также убедитесь, что настройки лежат там, где их ожидает ваша версия Claude Code.

Скрипт всегда блокирует действие

Возможно, проверка ищет слишком общий фрагмент. Строка вроде *migration* может совпадать с безопасными командами. Сузьте шаблон до конкретного пути или команды и добавьте диагностическое сообщение в stderr.

JSON читается не так, как ожидалось

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

Stop создаёт бесконечный цикл

Если проверка при каждой остановке запускает действие, которое снова вызывает остановку, возникает повторный запуск. Держите проверку конечной, не вызывайте из неё Claude Code и изучите механизм повторного входа в вашей конфигурации.

Проверка слишком медленная

Hook выполняется в чувствительной точке рабочего процесса. Вынесите долгие проверки в отдельный CI-процесс, а в Stop оставьте короткий локальный smoke-check, который действительно нужен для подтверждения результата.

Ограничения подхода

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

Не полагайтесь на hook как на единственный барьер для секретов. Секреты не должны попадать в команды, логи и файлы конфигурации. Ограничивайте права скриптов, проверяйте их содержимое в Git и не принимайте изменения hook без ревью.

Наконец, проверка «исправление завершено» должна быть определена заранее. Если команда проверки не отражает критерии готовности, Stop лишь создаст видимость контроля.

Итог

Надёжная схема состоит из двух уровней. CLAUDE.md объясняет правила и контекст, PreToolUse блокирует запрещённое действие до выполнения, а Stop требует подтвердить состояние проекта перед заявлением о завершении.

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