Hooks в Claude Code: как автоматически запускать нужную проверку

Вы работаете с Claude Code над каталогом магазина. После каждой правки приходится напоминать: отформатируй файл, проверь код, покажи ошибку. Для таких повторяющихся действий есть hooks — обработчики событий рабочего цикла. Один раз выбираете момент запуска и команду, затем проверка срабатывает по правилу.

Начать удобно с форматирования TypeScript-файлов. Результат сразу виден в diff, сценарий легко проверить на одном файле. Затем можно добавить проверку перед определённой командой или уведомление о завершении ответа.

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

Три части любого hook

Сначала выбирают событие: когда запускать обработчик. Затем matcher: какой инструмент или тип события нас интересует. Наконец, задают действие: например, выполнение локального скрипта.

Для первых задач достаточно четырёх событий:

Событие	Момент запуска	Практический пример
PreToolUse	Перед вызовом инструмента	Проверить условие допуска команды
PostToolUse	После успешного вызова	Отформатировать изменённый файл
Notification	При уведомлении Claude Code	Показать локальное уведомление
Stop	Когда Claude завершает ответ	Подать короткий звуковой сигнал

В PreToolUse и PostToolUse matcher фильтрует имя инструмента: Bash, Edit, Write. Условия по содержимому команды задают отдельно. Обработчик получает JSON через стандартный ввод, stdin; там находятся имя инструмента и его входные параметры. Точная схема приведена в справочнике hooks.

Представьте простой маршрут: Claude вызывает Edit, успешно меняет файл, возникает PostToolUse, matcher пропускает событие, ваш скрипт форматирует этот файл. Если агент читает документацию через другой инструмент, обработчик пропускает такой вызов.

Сначала проверьте ручную команду

Откройте package.json и найдите принятый способ форматирования. У команды могут быть собственные правила, игнорируемые каталоги и закреплённая версия форматтера. Используйте уже установленный инструмент проекта.

Возьмите один временный TypeScript-файл в обычном каталоге исходников и выполните форматирование вручную. Посмотрите код завершения, вывод и diff. Отдельно проверьте файл с пробелом в имени: так часто обнаруживаются ошибки передачи аргументов.

Первый промпт:

Изучи команды форматирования и конфигурацию Prettier в этом проекте. Предложи один PostToolUse hook для Edit и Write. Он должен работать только с существующими .ts и .tsx внутри src.

Сначала покажи ручную команду проверки на временном файле, способ получения пути из входного JSON и список файлов настройки. Объясни поведение при ошибке форматтера. До этого настройки оставь без изменений.

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

Соберите минимальную настройку

Общие проектные hooks размещают в .claude/settings.json; для личного эксперимента в проекте подходит .claude/settings.local.json. Пользовательские настройки в ~/.claude/settings.json действуют шире, на разные проекты. Области настроек описаны в документации Claude Code.

Пример связывает событие со скриптом, который предстоит создать и проверить:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/format_changed.py\""
          }
        ]
      }
    ]
  }
}

Сам JSON задаёт маршрут вызова. Для работы примера нужны Python 3 и файл format_changed.py. Задача скрипта — прочитать stdin, извлечь tool_input.file_path, проверить путь и передать его форматтеру отдельным аргументом. На неподходящем расширении скрипт должен спокойно завершиться.

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

Подготовь format_changed.py и проектную настройку из согласованного плана. Прочитай JSON из stdin, проверь наличие file_path, существование файла, расширение .ts/.tsx и принадлежность каталогу src после разрешения пути.

Запускай закреплённый форматтер проекта с передачей пути отдельным аргументом. При ошибке выведи краткую причину в stderr. Добавь понятную обработку некорректного JSON. Покажи diff и выполни ручные проверки на подходящем и неподходящем файлах.

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

Проверьте полный путь события

Ручной запуск подтверждает работу скрипта. Затем нужна проверка именно внутри Claude Code: откройте /hooks, убедитесь, что конфигурация загружена, и попросите агента изменить тестовый файл через Edit или Write. Руководство по настройке и диагностике есть в официальном разборе hooks.

Для учебного сценария ожидаемая последовательность выглядит так:

Изменён файл: src/catalog/search.ts
Сработало событие: PostToolUse
Форматтер обработал только этот файл
После форматирования просмотрен повторный diff

Это образец проверки, который нужно заполнить реальным выводом. Затем отредактируйте Markdown-файл: фильтр скрипта должен его пропустить. Проверьте синтаксически повреждённый TypeScript-файл: сообщение форматтера должно остаться доступным для разбора.

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

Как проверять код перед коммитом

Для проверки до команды подходит PreToolUse с matcher Bash. Содержимое Bash-вызова разбирает отдельное условие или скрипт. В современной документации для предварительного отбора также есть поле if; перед использованием сверьте поддержку в своей версии клиента.

Удобный учебный вариант — договориться, что агент вызывает одну команду проекта для подготовки коммита. Её обработчик запускает typecheck и lint, сохраняет понятный вывод и прекращает дальнейшее действие при ошибке.

Семантика завершения здесь существенна: для PreToolUse код 2 блокирует вызов. Обычный код 1 сам по себе обозначает неблокирующую ошибку hook. Эти варианты описаны в справочнике кодов выхода.

Спроектируй PreToolUse-проверку для нашего согласованного способа создания коммита. Найди реальные команды typecheck и lint. Объясни, как определяется нужный Bash-вызов и как ошибка проверки преобразуется в блокировку.

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

Проверка в Claude Code охватывает соответствующие вызовы внутри Claude Code. Коммиты из другого терминала или редактора имеют отдельный маршрут. Если правило обязательно для всей команды, дополните его принятым Git hook и проверкой в CI. Это разные точки контроля одного требования.

Почему hook молчит или мешает работе

Событие прошло, форматирования нет. Проверьте загруженный файл настроек, matcher и фактический инструмент. Изменение через shell-команду проходит как Bash; настройка Edit|Write такой вызов пропустит.

Скрипт работает вручную, но падает внутри Claude. Сравните рабочую папку, доступность Python или Node, переменные окружения и абсолютные пути. Среда запуска редактора может отличаться от вашей обычной оболочки.

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

Каждое редактирование стало долгим. Замерьте время обработчика. Форматирование одного файла уместно после правки; полный набор интеграционных тестов удобнее запускать на границе законченного этапа. Измерение покажет, какой перенос даст эффект.

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

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