Claude Code Hooks: Полное руководство по настройке автоматизации

Каждый раз, когда Claude записывает файл — нужно вручную запустить Prettier. Каждый раз при выполнении npm test — появляется запрос на разрешение. Каждая сессия начинается с одного и того же объяснения контекста проекта.

Знакомо? Эти мелкие точки трения накапливаются и превращают работу с Claude Code в рутину. Хорошая новость: Claude Code Hooks решают все эти проблемы — автоматически.

Если ты уже работаешь с Claude Code, но ещё не настраивал хуки — эта статья для тебя. Мы пройдём путь от простейшего примера до продвинутых техник автоматизации.

Что такое хуки и зачем они нужны

Хук — это команда, которую ты создаёшь для автоматического выполнения при определённом событии в Claude Code. Например, когда Claude собирается записать файл или когда ты отправляешь запрос.

Представь, что Claude — талантливый, но рассеянный стажёр. Хуки — это автоматизированная система контроля. Они гарантируют, что он всегда использует правильные инструменты, записывает свои действия в журнал и не полезет в сейф с секретными паролями.

Хуки решают три категории проблем:

1. Устраняют рутину. Вместо ручного запуска форматтера после каждого изменения — хук делает это автоматически.

2. Применяют правила проекта. Можно блокировать опасные команды, защищать важные файлы, принуждать к использованию определённых инструментов

3. Внедряют контекст. Хук может передать Claude статус git и список задач при старте сессии — без ручного копирования.

8 типов хуков — когда какой использовать

Claude Code предоставляет восемь типов событий, которые охватывают весь жизненный цикл сессии:

Хук	Когда срабатывает	Примеры использования
PreToolUse	До выполнения инструмента	Блокировка опасных команд, валидация путей
PermissionRequest	До появления диалога разрешения	Автоодобрение тестов
PostToolUse	После завершения инструмента	Запуск форматтера, логирование
PreCompact	До сжатия контекста	Резервное копирование транскриптов
SessionStart	При начале сессии	Внедрение git status, загрузка TODO
Stop	Когда Claude завершает ответ	Звуковое уведомление, проверка качества
SubagentStop	Когда субагент завершается	Валидация вывода субагента
UserPromptSubmit	При отправке запроса	Внедрение контекста спринта

Не нужно запоминать все сразу. Начни с одного — Stop. Он самый простой и даёт мгновенную обратную связь.

Начинаем с простого — твой первый хук

Где хранятся настройки

Хуки настраиваются в файлах settings.json:

• Проект: .claude/settings.json — для команды, коммитится в репо
• Пользователь: ~/.claude/settings.json — для всех твоих проектов
• Локальный: .claude/settings.local.json — личные настройки, не коммитятся

Для первого хука используй пользовательские настройки — они будут работать везде.

Звук по завершении задачи

Это изменило мою модель работы с Claude. Раньше я сидел и смотрел, как модель пишет код. Теперь — пишу промпт, запускаю и иду делать другие дела. Когда слышу звук — возвращаюсь.

Открой файл ~/.claude/settings.json и добавь:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Glass.aiff"
          }
        ]
      }
    ]
  }
}

Это для macOS. Для Linux замени на paplay /usr/share/sounds/..., для Windows — на PowerShell-команду воспроизведения.

Теперь каждый раз, когда Claude завершает ответ — ты услышишь звук. Можешь спокойно переключиться на другую задачу.

Мне теперь жалко времени работать самому, если Claude не делает чего-то полезного на фоне.

Практические сценарии использования

Автоформатирование кода

Устал напоминать Claude про Prettier? Настрой хук PostToolUse, который запускает форматтер после каждого изменения файла:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write "$CLAUDE_TOOL_INPUT_FILE_PATH""
          }
        ]
      }
    ]
  }
}

Как это работает:

• matcher: "Write|Edit" — хук срабатывает только для инструментов записи и редактирования
• $CLAUDE_TOOL_INPUT_FILE_PATH — переменная окружения с путём к файлу

Для Python замени на black "$CLAUDE_TOOL_INPUT_FILE_PATH".

Quality Gates — автопроверка перед завершением

Я настроил хук Stop, который выполняет проверки качества: запуск тестов, проверка форматирования и линтинга. Если проверка не пройдена — Claude видит ошибку и исправляет себя автоматически.

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npm test && npx prettier --check src/"
          }
        ]
      }
    ]
  }
}

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

Результат: я перешёл из «режима кодирования» в «режим рецензента». Большую часть времени трачу на планирование и проверку, а не на написание рутинного кода.

Защита важных файлов

Используй PreToolUse для блокировки записи в конфиденциальные файлы:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/check-protected-files.py"
          }
        ]
      }
    ]
  }
}

Скрипт check-protected-files.py:

import sys
import json

input_data = json.load(sys.stdin)
file_path = input_data.get('tool_input', {}).get('file_path', '')

protected = ['.env', 'package-lock.json', 'credentials.json']

for pattern in protected:
    if pattern in file_path:
        print(json.dumps({
            "decision": "block",
            "reason": f"Файл {pattern} защищён от изменений"
        }))
        sys.exit(0)

sys.exit(0)

Теперь Claude физически не может изменить эти файлы — даже если ты попросишь.

Авто-коммит после каждой сессии

Хочешь «точки сохранения» для отката неудачных изменений?

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/auto-commit.sh"
          }
        ]
      }
    ]
  }
}

Скрипт auto-commit.sh:

#!/bin/bash
if [ -n "$(git status --porcelain)" ]; then
  git add .
  git commit -m "🤖 Auto-commit: Claude Code Session"
  echo "✅ Changes saved to git"
fi

Продвинутые техники

Журнал аудита всех команд

Хочешь знать, какие именно команды выполняет Claude? Настрой логирование:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/log-command.py"
          }
        ]
      }
    ]
  }
}

Скрипт записывает каждую bash-команду в bash-command-log.txt. Полная прозрачность действий агента — незаменимо для отладки.

Принуждение к правилам проекта

Если проект использует bun, а Claude пытается запустить npm:

import sys
import json

input_data = json.load(sys.stdin)
command = input_data.get('tool_input', {}).get('command', '')

if command.startswith('npm '):
    print(json.dumps({
        "decision": "block",
        "reason": "Этот проект использует bun, не npm. Используй bun вместо npm."
    }))
    sys.exit(0)

sys.exit(0)

Claude видит ошибку и автоматически корректирует команду. Не нужно каждый раз напоминать.

Внедрение контекста в каждый запрос

Хук UserPromptSubmit добавляет информацию к каждому твоему сообщению:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "cat ./current-sprint-context.md"
          }
        ]
      }
    ]
  }
}

Всё, что выводит команда, добавляется в контекст Claude. Он всегда знает текущие приоритеты без повторных объяснений.

---

Отладка хуков

Логирование через wrapper-скрипт

Если хук не работает — добавь логирование:

#!/bin/bash
LOG=~/.claude/hooks.log
INPUT=$(cat)

TOOL=$(echo "$INPUT" | jq -r '.tool_name // "n/a"')
EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // "n/a"')

echo "=== $(date) | $EVENT | $TOOL ===" >> "$LOG"
echo "$INPUT" >> "$LOG"

# Запуск основного скрипта
echo "$INPUT" | "$1"
CODE=$?

echo "Exit: $CODE" >> "$LOG"
exit $CODE

Используй как обёртку: bash log-wrapper.sh your-script.py

Чтение транскриптов

Каждый хук получает поле transcript_path — путь к файлу с историей сессии. Следи за ним в реальном времени:

tail -f /path/to/transcript.jsonl | jq

Часто задаваемые вопросы

Заключение

Хуки превращают Claude Code из помощника, которого нужно постоянно контролировать, в надёжный инструмент автоматизации. Критически важные операции выполняются всегда — а не когда модель «вспомнит» о них.

Начни с одного простого хука — звукового уведомления. Когда поймёшь, как работают события, появятся идеи для практических применений: форматирование, защита файлов, Quality Gates.

Хуки позволяют формировать Claude Code под твой рабочий процесс, а не адаптировать процесс под инструмент.

Официальная документация: code.claude.com/docs/en/hooks