Skip to main content
Все гайды
Содержание гайда

Содержание гайда

Время на изучение: 12 мин
#automation#hooks#claude#code#guide#beginners
Новичок12 мин

Hooks в Claude Code для начинающих: автоматизируем повторяющиеся действия

Полное практическое руководство по настройке Hooks в Claude Code: автоматический линтинг, форматирование, защитные проверки перед коммитом, уведомления и Headless-автоматизация.

Опубликовано:

1. Что такое Hooks в Claude Code и зачем они нужны

Работая с AI-ассистентом в терминале, разработчики часто вынуждены повторять одни и те же рутинные команды: "теперь запусти ESLint", "отформатируй код через Prettier", "проверь типы перед коммитом". Даже если прописать эти правила в системных инструкциях CLAUDE.md, языковая модель может периодически забывать их выполнить или пропускать ради экономии токенов.

Hooks (хуки) в Claude Code решают эту проблему радикально: это детерминированные триггеры, которые автоматически вызывают системные команды или скрипты в точные моменты жизненного цикла работы ассистента.

Принцип работы хуков предельно прост:

Если Claude выполнил событие X → операционная система гарантированно запускает действие Y.

mermaid
flowchart LR subgraph Текстовая_инструкция["CLAUDE.md (Вероятностная)"] A["Промпт: 'Всегда запускай линтер'"] --> B{"Модель помнит?"} B -->|Иногда| C["Запуск проверки"] B -->|Пропустила| D["Ошибки накапливаются"] end subgraph Нативный_Hook["Hooks в settings.json (Детерминированная)"] E["Событие: Редактирование файла"] --> F["Автоматический триггер ОС"] F --> G["Гарантированное выполнение npx eslint"] end

Сравнение подходов к автоматизации

ХарактеристикаРучные промптыИнструкции в CLAUDE.mdНативные Hooks
Надежность выполненияНизкая (зависит от человеческого внимания)Средняя (вероятностное поведение LLM)100% (детерминированный перехват событий)
Расход токеновВысокий (тратятся токены на каждый запрос)Средний (правило подгружается в каждый контекст)Нулевой (выполняется локально в shell)
Скорость реакцииМедленная (ручной ввод команд)Требует дополнительного раунда генерацииМгновенная (нативный вызов процесса)
Возможность блокировкиОтсутствуетОтсутствуетЕсть (ненулевой exit code останавливает действие)
Примечание

Хуки Claude Code настраиваются в формате JSON в файле .claude/settings.json на уровне отдельного репозитория или глобально в ~/.claude/settings.json.

2. Жизненный цикл событий: PreToolUse, PostToolUse, Notification и Stop

В Claude Code предусмотрено четыре фундаментальные точки перехвата (события), к которым можно привязать запуск автоматических команд.

mermaid
sequenceDiagram autonumber actor Dev as Разработчик participant Agent as Claude Code participant Hook as Система Hooks participant Tool as Инструмент (Bash/Edit/Write) Dev->>Agent: Запрос на изменение кода Agent->>Hook: Попытка вызова инструмента Note over Hook: PreToolUse Hook Hook-->>Agent: Проверка пройдена (Exit Code 0) Agent->>Tool: Выполнение операции Tool-->>Agent: Результат успешен Agent->>Hook: Событие завершения операции Note over Hook: PostToolUse Hook Hook-->>Agent: Результат линтинга / форматирования Agent->>Hook: Завершение ответа модели Note over Hook: Stop Hook (Уведомление) Agent-->>Dev: Финальный ответ

Основные точки срабатывания

  1. PreToolUse (Перед использованием инструмента): срабатывает до того, как агент выполнит действие. Если команда хука возвращает ошибку (exit code не равен 0), выполнение блокируется. Идеальное место для защитных проверок перед коммитом или пушем.
  2. PostToolUse (После использования инструмента): срабатывает сразу после успешного завершения инструмента. Самый востребованный триггер для автоматического форматирования кода (Prettier) или линтинга измененного файла (ESLint).
  3. Notification (Уведомление): активируется, когда ассистенту необходимо уведомить пользователя или запросить подтверждение.
  4. Stop (Завершение ответа): срабатывает в момент, когда Claude Code полностью завершил генерацию ответа и ожидает следующей реплики пользователя. Используется для воспроизведения звуковых сигналов и десктопных уведомлений.
Точки срабатывания Hooks в жизненном цикле ЗбільшитиТочки срабатывания Hooks в жизненном циклеТочки срабатывания Hooks в жизненном цикле

3. Структура конфигурации в settings.json и синтаксис Matcher

Конфигурация хуков хранится в файле .claude/settings.json. Если этого файла еще нет в корне вашего проекта, создайте его.

Базовый синтаксис конфигурации

json
{ "hooks": { "PreToolUse": [ { "matcher": "Edit", "hooks": [ { "type": "command", "command": "echo 'Начинается редактирование файла...'" } ] } ], "PostToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "echo 'Bash-команда завершена успешно'" } ] } ] } }

Как работает поле Matcher:

Поле matcher определяет, на какой именно инструмент агента должен реагировать конкретный хук:

  • "Edit" — перехватывает изменение уже существующих файлов.
  • "Write" — срабатывает при создании нового файла или полной перезаписи.
  • "Bash" — реагирует на запуск любых консольных команд.
  • "Bash(git commit*)" — точечный шаблон, фильтрующий вызовы Bash, начинающиеся с команды git commit.
  • "*" — универсальный селектор (wildcard), срабатывающий на любой доступный инструмент агента.
Совет

Шаблоны matcher чувствительны к регистру. Используйте стандартные названия инструментов Claude Code: Edit, Write, Bash, Glob, Grep.

4. Автоматический линтинг и форматирование (ESLint + Prettier)

Наиболее практичный ежедневный сценарий — передача форматирования и первичной проверки стиля утилитам Prettier и ESLint. Благодаря этому весь код сохраняется в репозитории в идеальном виде.

Настройка PostToolUse для ESLint и Prettier

json
{ "hooks": { "PostToolUse": [ { "matcher": "Edit", "hooks": [ { "type": "command", "command": "npx eslint --fix \"$CLAUDE_FILE_PATH\" 2>/dev/null || true" } ] }, { "matcher": "Write", "hooks": [ { "type": "command", "command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true" } ] } ] } }

Разбор флагов безопасности в команде

  • "$CLAUDE_FILE_PATH" — динамическая переменная окружения, куда Claude автоматически подставляет полный путь к файлу, только что измененному агентом.
  • 2>/dev/null — подавляет избыточный служебный вывод потока ошибок stderr, сохраняя консоль чистой.
  • || true — критически важная конструкция bash. Она гарантирует, что даже если линтер обнаружит неисправимые ошибки и вернет код 1, сам хук завершится с кодом 0 и не прервет рабочий процесс ассистента.
mermaid
flowchart TD A["Claude вызывает Edit"] --> B["Файл записан на диск"] B --> C["PostToolUse триггер"] C --> D["npx eslint --fix $CLAUDE_FILE_PATH"] D --> E{"Успешно или || true"} E --> F["Агент продолжает решать задачу"]

5. Защитные барьеры перед git commit (TypeCheck + Тесты)

Если для форматирования мы использовали мягкие хуки с || true, то для фиксации изменений в системе контроля версий требуется строгий контроль качества (Quality Gate).

С помощью PreToolUse можно заблокировать создание коммита, если в проекте есть ошибки компиляции TypeScript или падают модульные тесты.

Настройка блокирующего Pre-commit хука

json
{ "hooks": { "PreToolUse": [ { "matcher": "Bash(git commit*)", "hooks": [ { "type": "command", "command": "npm run typecheck && npm run lint" } ] } ] } }

Что происходит при обнаружении ошибок

  1. Claude формирует команду git commit -m "...".
  2. Перед ее исполнением система активирует PreToolUse.
  3. Запускаются скрипты валидации: npm run typecheck и npm run lint.
  4. Если обнаружена ошибка: процесс возвращает ненулевой код завершения (exit code 1).
  5. Claude Code перехватывает вывод ошибки компилятора прямо в своем контексте.
  6. Вместо сломанного коммита ассистент анализирует текст ошибки, исправляет типы в коде и делает повторную чистую попытку коммита.
Важно

Обратите внимание: в блокирующих проверках PreToolUse никогда не используйте || true, иначе проверка всегда будет считаться успешной, и защитный барьер перестанет действовать.

6. Аудио- и десктопные уведомления при завершении задач (Stop Hook)

Сложный рефакторинг или прогон полного набора тестов могут занимать от 2 до 10 минут. Вместо того чтобы непрерывно наблюдать за консолью, настройте уведомление через событие Stop.

Совет

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

7. Передача контекста через переменные окружения

Чтобы скрипты автоматизации были гибкими и контекстно-зависимыми, Claude Code автоматически экспортирует метаданные текущей операции в переменные окружения операционной системы.

Переменные окружения Claude Code для хуков ЗбільшитиПеременные окружения Claude Code для хуковПеременные окружения Claude Code для хуков

Справочник системных переменных Claude Code

Переменная окруженияТип значенияОписание и пример содержания
$CLAUDE_FILE_PATHАбсолютный путьПуть к целевому файлу, который сейчас создается или редактируется (/Users/dev/project/src/index.ts)
$CLAUDE_TOOL_NAMEСтроковый IDНазвание инструмента, инициировавшего событие (Edit, Write, Bash)
$CLAUDE_PROJECT_DIRАбсолютный путьКорневая директория проекта, где запущена текущая сессия Claude Code

Пример контекстного Bash-скрипта для хука

Создадим скрипт .claude/hooks/smart-validator.sh:

bash
#!/usr/bin/env bash set -e # Проверяем, существует ли файл и какое у него расширение if [[ -f "$CLAUDE_FILE_PATH" ]]; then case "$CLAUDE_FILE_PATH" in *.ts|*.tsx) echo "⚡ Валидация TypeScript файла: $CLAUDE_FILE_PATH" npx eslint --fix "$CLAUDE_FILE_PATH" || true ;; *.json) echo "🔍 Проверка валидности JSON..." jq empty "$CLAUDE_FILE_PATH" 2>/dev/null || echo "Ошибка формата JSON!" ;; *.md) echo "📝 Документация обновлена: $(basename "$CLAUDE_FILE_PATH")" ;; esac fi

Теперь в .claude/settings.json достаточно указать вызов этого скрипта:

json
{ "hooks": { "PostToolUse": [ { "matcher": "*", "hooks": [ { "type": "command", "command": "bash .claude/hooks/smart-validator.sh" } ] } ] } }

8. Паттерн «CI-in-a-Loop»: непрерывная обратная связь

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

CI-in-a-Loop (Короткий цикл обратной связи) устраняет эту проблему:

mermaid
flowchart TD A["Claude вносит правку в код"] --> B["Мгновенный запуск tsc"] B --> C{"Есть ошибка?"} C -->|Да| D["Claude видит 1 точечную ошибку"] D --> E["Мгновенное исправление за 5 секунд"] E --> B C -->|Нет| F["Переход к следующей строке/файлу"]

Конфигурация циклического TypeScript-аудита

json
{ "hooks": { "PostToolUse": [ { "matcher": "Edit", "hooks": [ { "type": "command", "command": "npx tsc --noEmit 2>&1 | head -n 20 || true" } ] } ] } }

Почему необходимо использовать head -n 20

Если вывод компилятора возвращает сотни строк логов, они попадают в контекст модели и могут быстро переполнить лимит токенов. Ограничение через head -n 20 отображает первые ключевые ошибки, давая модели четкий ориентир для немедленного исправления без перегрузки диалога.

9. Headless-автоматизация: режим -p, Cron и Git Hooks

Хуки можно объединять с автономным (headless) режимом Claude Code — флагом -p (print/prompt). Это позволяет автоматизировать выполнение инженерных задач полностью без участия человека.

mermaid
flowchart LR A["Расписание Cron (02:00)"] --> B["Скрипт nightly-audit.sh"] B --> C["claude -p 'Run test suite, fix bugs, commit'"] C --> D["Хуки PostToolUse контролируют код"] D --> E["Автоматический Push результата"]

Автономный скрипт ночного аудита (nightly-audit.sh)

bash
#!/usr/bin/env bash cd /var/www/my-project # Запуск Claude Code в автономном режиме с фиксированной задачей claude -p "Run full test suite. If any tests fail, inspect the stack trace and fix them. Ensure typecheck passes. Finally, commit all fixes with a conventional commit." >> /var/log/claude-audit.log 2>&1

Настройка расписания выполнения через Cron

Откройте планировщик задач (crontab -e) и настройте выполнение каждую ночь в 03:00:

text
0 3 * * * /usr/local/bin/nightly-audit.sh

Запуск проверки в нативном Git Hook (.git/hooks/post-merge)

Чтобы после каждого получения обновлений через git pull автоматически запускался аудит совместимости:

bash
#!/usr/bin/env bash # .git/hooks/post-merge echo "🚀 Запуск автоматической проверки зависимостей через Claude..." claude -p "Check if package.json was updated. If so, run npm install, verify build, and report summary."

Не забудьте выдать права на выполнение: chmod +x .git/hooks/post-merge.

10. Лучшие инженерные практики и правила безопасности Hooks

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

Четыре правила безопасной разработки хуков

  1. Субсекундное быстродействие: Хуки с событием PostToolUse вызываются после каждой модификации файла. Если хук выполняется дольше 1-2 секунд, интерактивная работа с Claude станет некомфортной. Оставляйте тяжелые E2E-тесты для PreToolUse перед коммитом, но не после каждого Edit.

  2. Обязательное логирование вывода: Всегда перенаправляйте вывод диагностических скриптов во временный лог-файл:

    bash
    "command": "bash .claude/hooks/check.sh >> /tmp/claude-hooks.log 2>&1 || true"

    Если хук перестанет работать, вы сможете открыть /tmp/claude-hooks.log и мгновенно локализовать сбой.

  3. Изолированное тестирование в чистом терминале: Перед добавлением любой команды в settings.json выполните ее вручную в обычном shell. Если команда падает с ошибкой в консоли, она гарантированно нарушит сессию Claude Code.

  4. Защита от бесконечной рекурсии: Никогда не настраивайте команду в PostToolUse, которая сама изменяет файлы проекта без правил игнорирования. Если скрипт вызовет повторный Edit, ассистент попадет в вечный цикл вызовов.

Внимание

Не запускайте через хуки команды, ожидающие интерактивного ввода от пользователя (например, подтверждения read -p или sudo с запросом пароля). Это приведет к зависанию терминального процесса.

11. Практический воркшоп, шпаргалка и итоговый чек-лист

Для быстрого старта в собственном проекте используйте готовую шпаргалку решений и проверенный production-конфиг.

Шпаргалка по выбору типа Hook для автоматизации ЗбільшитиШпаргалка по выбору типа Hook для автоматизацииШпаргалка по выбору типа Hook для автоматизации

Готовый файл конфигурации .claude/settings.json

Скопируйте этот эталонный конфиг в папку .claude вашего проекта:

json
{ "hooks": { "PreToolUse": [ { "matcher": "Bash(git commit*)", "hooks": [ { "type": "command", "command": "npm run typecheck && npm test" } ] } ], "PostToolUse": [ { "matcher": "Edit", "hooks": [ { "type": "command", "command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true" } ] }, { "matcher": "Write", "hooks": [ { "type": "command", "command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true" } ] } ], "Stop": [ { "hooks": [ { "type": "command", "command": "osascript -e 'display notification \"Работа завершена!\" with title \"Claude Code\"' 2>/dev/null || true" } ] } ] } }

Быстрая самопроверка

Совет

1. Чем PreToolUse принципиально отличается от PostToolUse?

Ответ: PreToolUse запускается до выполнения действия инструмента и способен заблокировать операцию при ненулевом коде возврата. PostToolUse запускается после успешного завершения и применяется для мягкой постобработки (форматирование, линтинг).

Совет

2. Зачем в хуках форматирования добавляют конструкцию || true?

Ответ: Чтобы предупреждения или ошибки форматирования не возвращали аварийный код завершения и не прерывали процесс генерации ответа модели.

Совет

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

Ответ: Переменная $CLAUDE_FILE_PATH.

Итоговый чек-лист внедрения Hooks:

  • Создана директория .claude/ и файл settings.json в корне проекта.
  • Настроено автоматическое форматирование измененных файлов через PostToolUse + Prettier.
  • Добавлен защитный барьер PreToolUse на Bash(git commit*) с запуском typecheck.
  • Подключено звуковое или экранное уведомление на событие Stop.
  • Все команды хуков проверены вручную в терминале перед сохранением в конфигурацию.
  • Проверено отсутствие интерактивных команд, ожидающих ввода пароля или подтверждения [y/N].
Этот гайд полностью бесплатный. Если он сэкономил вам вечер — вы можете поддержать развитие проекта.
Поддержать автора