Хуки — Автоматизация рабочего процесса — Презентация

Продолжительность: ~10 минут Цель: Студенты понимают, что такое хуки, четыре их типа, как работает сопоставление событий и как коды выхода управляют потоком.

Слайд 1: CI/CD для вашей сессии Claude

Вы знакомы с CI/CD-пайплайнами, верно? Происходит что-то (push, merge, расписание), и автоматически срабатывают действия: lint, test, build, deploy. Вы не запускаете их вручную каждый раз – они срабатывают по событиям.

Хуки – та же идея, но для вашей сессии Claude Code.

CI/CD Pipeline:               Claude Code Hooks:
  on: push                       on: PostToolUse (Write)
    - run: lint                    - run: prettier --write $FILE
    - run: test                  on: PreToolUse (Edit)
    - run: build                   - block if: .env, package-lock.json
                                 on: SessionStart
                                   - run: git status && echo "Ready!"

Что-то происходит в рабочем процессе Claude (файл редактируется, команда выполняется, сессия начинается), и ваши хуки срабатывают автоматически. Никакого ручного вмешательства. Никаких “я забыл запустить линтер”. Оно просто происходит.

Слайд 2: Четыре типа хуков

Claude Code поддерживает четыре типа хуков. Каждый служит своей цели:

1. Командные хуки (shell-скрипты)

Самый распространённый тип. Запускают любую shell-команду.

{
  "type": "command",
  "command": "FILE=$(cat | jq -r '.tool_input.file_path // empty'); [ -n \"$FILE\" ] && prettier --write \"$FILE\""
}

Хуки получают контекст в виде JSON на stdin – используйте jq для извлечения пути к файлу. Применяйте для: форматирования, линтинга, уведомлений, логирования, файловых операций.

2. Промпт-хуки (ИИ да/нет)

Задают Claude вопрос. Если Claude отвечает “нет”, действие блокируется.

{
  "type": "prompt",
  "prompt": "Does this edit look like it could delete user data? Answer only yes or no."
}

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

3. Агент-хуки (сложная оценка)

Запускают отдельную оценку Claude. Дороже, но могут обрабатывать сложную логику.

{
  "type": "agent",
  "prompt": "Review this file change for security vulnerabilities. If you find any, return exit code 2."
}

Применяйте для: аудита безопасности, проверок соответствия, сложной валидации.

4. HTTP-хуки (вебхуки)

Отправляют HTTP-запрос во внешний сервис.

{
  "type": "http",
  "url": "https://hooks.slack.com/services/T00/B00/xxx",
  "method": "POST",
  "body": "{\"text\": \"Claude session completed\"}"
}

Применяйте для: Slack-уведомлений, сбора метрик, аудит-логирования.

В этом курсе мы сосредоточимся на командных хуках – они наиболее практичны и проще всего для понимания. Остальные работают по тому же принципу.

Слайд 3: События – Когда хуки срабатывают

Каждый хук слушает событие. Вот те, которые вы будете использовать чаще всего:

Есть и другие события, но эти четыре покрывают 90% реальных сценариев использования.

Матчеры: Фильтрация по инструменту

Вы не хотите, чтобы хук Prettier срабатывал, когда Claude читает файл – только когда записывает. Для этого нужны матчеры.

{
  "event": "PostToolUse",
  "matcher": "Write|Edit",
  "hooks": [...]
}

matcher – это регулярное выражение, фильтрующее по имени инструмента. Распространённые имена инструментов:

• Write – создание или перезапись файла
• Edit – изменение части файла
• Bash – выполнение shell-команды
• Read – чтение файла
• Glob – поиск файлов
• Grep – поиск по содержимому файлов

Можно комбинировать: "matcher": "Write|Edit" срабатывает и на запись, и на редактирование. "matcher": "Bash" срабатывает только на shell-команды.

Слайд 4: Коды выхода – Пропустить или заблокировать

Вот где хуки становятся по-настоящему мощными: они могут управлять потоком.

Когда срабатывает хук PreToolUse, его код выхода определяет, что произойдёт дальше:

Так вы строите ограждения безопасности:

#!/bin/bash
# pre-edit-check.sh — exits 2 if the file is protected
# Hook receives tool context as JSON on stdin
FILE=$(cat | jq -r '.tool_input.file_path // empty')
PROTECTED_FILES=".env package-lock.json yarn.lock"
for f in $PROTECTED_FILES; do
  if [[ "$FILE" == *"$f"* ]]; then
    echo "BLOCKED: $f is a protected file"
    exit 2
  fi
done
exit 0

Exit 0 = “продолжай”. Exit 2 = “ни в коем случае”. Вот и вся логика.

Представьте себе охранника на входе в клуб. Хук проверяет список гостей (путь к файлу) и либо пропускает операцию (exit 0), либо разворачивает её (exit 2). Без обсуждений.

Слайд 5: Где живут хуки

Хуки настраиваются в settings.json – том же файле, который вы использовали для разрешений. Они могут находиться на трёх уровнях:

Уровень проекта (.claude/settings.json):

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "FILE=$(cat | jq -r '.tool_input.file_path // empty'); [ -n \"$FILE\" ] && prettier --write \"$FILE\""
          }
        ]
      }
    ]
  }
}

Уровень пользователя (~/.claude/settings.json) – хуки, которые следуют за вами во всех проектах.

Корпоративный уровень – управляется администратором вашей организации.

Порядок разрешения: корпоративный > проект > пользователь. Корпоративные хуки всегда выполняются. Проектные и пользовательские хуки суммируются.

Как хуки получают контекст

При срабатывании хука Claude Code передаёт контекст в виде JSON на stdin. Ваш скрипт хука читает его с помощью jq или аналогичных инструментов. JSON включает имя инструмента, путь к файлу и другие детали в зависимости от события.

Для хуков PreToolUse и PostToolUse stdin выглядит так:

{
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.ts",
    "content": "..."
  }
}

Извлечение значений с помощью jq:

# Get the file path from stdin
FILE_PATH=$(cat | jq -r '.tool_input.file_path // empty')

Кроме того, всегда доступны следующие переменные окружения:

Они позволяют вашим хук-скриптам быть умными – понимать, что делать, исходя из того, что делает Claude.

Слайд 6: Подробный режим – Наблюдаем за работой хуков

Как узнать, что ваши хуки действительно срабатывают? Подробный режим.

Нажмите Ctrl+O в Claude Code для переключения подробного вывода. Когда он включён, вы увидите:

[hook] PostToolUse:Write matched "Write|Edit"
[hook] Running: prettier --write "src/app/page.tsx"
[hook] Exit code: 0 (proceed)

Это неоценимо для отладки. Если хук не срабатывает, подробный режим объясняет почему – неправильное событие, неправильный матчер, неправильный путь. Если хук срабатывает, когда не должен, вы видите, что именно его активировало.

Включайте при создании хуков. Выключайте, когда закончите.

Ключевые выводы

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