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 автоматично експортує метадані поточної операції у системні змінні оточення (Environment Variables).

Змінні середовища Claude Code для хуків ЗбільшитиЗмінні середовища Claude Code для хуківЗмінні середовища Claude Code для хуків

Довідник системних змінних Claude Code

Змінна оточенняТип значенняОпис та приклад вмісту
$CLAUDE_FILE_PATHАбсолютний шляхШлях до конкретного файлу, який зараз створюється чи редагується (/Users/dev/project/src/index.ts)
$CLAUDE_TOOL_NAMEТекстовий ідентифікаторНазва інструмента, який ініціював подію (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 запускається до виконання дії інструмента і здатний заблокувати її при ненульовому exit code. PostToolUse запускається після успішного завершення операції та використовується для форматування або лінтингу.

Порада

2. Навіщо в хуках форматування додають || true?

Відповідь: Щоб помилки лінтера чи форматера не повертали аварійний статус і не зупиняли процес генерації відповіді агента.

Порада

3. Яка змінна оточення містить шлях до файлу, який щойно редагувався?

Відповідь: Змінна $CLAUDE_FILE_PATH.

Підсумковий чек-лист впровадження Hooks

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