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

Тривалість: ~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. Command-хуки (shell-скрипти)

Найпоширеніший тип. Запуск будь-якої shell-команди.

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

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

2. Prompt-хуки (AI так/ні)

Ставлять Claude питання. Якщо Claude каже “ні”, операцію блокується.

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

Використовуйте для: перевірок безпеки, що потребують міркування, а не лише паттерн-матчингу.

3. Agent-хуки (складна оцінка)

Запуск окремої оцінки 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, збору метрик, аудит-логування.

На цьому курсі ми зосередимося на command-хуках — вони найпрактичніші та найлегші для розуміння. Решта слідує тому ж патерну.

Слайд 3: Події — коли хуки спрацьовують

Кожен хук слухає подію. Ось ті, які ви будете використовувати найчастіше:

Є й інші події, але ці чотири покривають 90% реальних випадків використання.

Matchers: фільтрація інструментів для хука

Ви не хочете, щоб ваш Prettier-хук спрацьовував, коли Claude читає файл — тільки коли записує. Саме для цього існують matchers.

{
  "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) — хуки, що слідують за вами у всіх проєктах.

Рівень підприємства — керуються адміністратором вашої організації.

Порядок пріоритету: enterprise > project > user. Хуки enterprise завжди виконуються. Хуки project та user додаються один до одного.

Як хуки отримують контекст

Коли хук спрацьовує, 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: Verbose Mode — спостереження за роботою хуків

Як дізнатися, чи справді ваші хуки спрацьовують? Verbose mode.

Натисніть Ctrl+O у Claude Code для перемикання розширеного виводу. Коли увімкнено, ви побачите:

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

Це безцінно для дебагу. Якщо хук не спрацьовує, verbose mode покаже чому — неправильна подія, неправильний matcher, неправильний шлях. Якщо хук спрацьовує, коли не повинен, ви побачите, що саме його тригернуло.

Вмикайте під час створення хуків. Вимикайте, коли закінчите.

Ключові висновки

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