Хуки Claude Code: повний гайд для розробників із готовими прикладами для продакшену

Хуки Claude Code: повний посібник для розробника з прикладами, готовими до продакшену

Claude Code чудово пише код, але це все одно ймовірнісна система. Ви можете попросити його запускати Prettier після кожного редагування файлу. Ви можете помістити цю інструкцію у ваш CLAUDE.md. І іноді він просто... забуде. Хуки Claude Code вирішують цю проблему, даючи вам детермінований, гарантований контроль над тим, що відбувається до, під час та після кожної дії, яку виконує Claude.

Протягом останніх кількох місяців я налаштовував хуки в десятках проєктів, і вони непомітно стали найважливішою частиною мого налаштування Claude Code. Цей посібник охоплює все: від основ до стартового набору, готового до продакшену, який ви можете впровадити в будь-який проєкт вже сьогодні. Якщо ви використовували Claude Code разом з інструментами на кшталт Cursor чи Copilot, ви вже знаєте цінність кастомізації — хуки виводять це на новий рівень.

Що таке хуки Claude Code (і чому вам варто про них знати)?

Хуки Claude Code — це визначені користувачем shell-команди, HTTP-ендпоінти або LLM-промпти, які автоматично виконуються в певних точках життєвого циклу Claude Code. Згідно з офіційною документацією Anthropic, на відміну від інструкцій у промптах, які Claude може проігнорувати, хуки спрацьовують детерміновано щоразу, забезпечуючи вам гарантований контроль над форматуванням, безпекою, сповіщеннями та автоматизацією робочих процесів.

Імовірнісна проблема

Справа ось у чому: інструкції в CLAUDE.md — це рекомендації, а не контракти. Ви можете написати «завжди виконуй npx prettier --write після редагування файлів TypeScript» у контексті свого проєкту, і Claude дотримуватиметься цього більшість часу. Але «більшість часу» — недостатньо, коли ви забезпечуєте єдине форматування коду в команді, блокуєте пуші в продакшн або логуєте кожну shell-команду для аудиту безпеки.

У цьому й полягає головна суперечність будь-якого AI-інструменту для написання коду. Claude — це мовна модель, яка оперує ймовірностями. Ваша інженерія контексту може скеровувати поведінку, але не здатна її гарантувати.

Як хуки розв'язують цю проблему

Хуки повністю оминають LLM. Це shell-скрипти, HTTP-виклики або AI-оцінки, які спрацьовують на певних подіях життєвого циклу: перед запуском інструменту (PreToolUse), після його завершення (PostToolUse), коли з'являється сповіщення, коли починається сесія або коли Claude зупиняється. Уявіть їх як Git-хуки, але для вашого AI-асистента з програмування.

Існує чотири типи хуків: command (shell-скрипти), HTTP (POST-запити вебхуків), prompt (однораундові оцінки Claude «так/ні») та agent (запускає субагента з доступом до інструментів). Ми розберемо кожен із них пізніше — command-хуки покривають приблизно 90% ваших потреб.

Як працюють хуки Claude Code: життєвий цикл

Хуки Claude Code виконуються у чітко визначеному життєвому циклі: спершу спрацьовує подія (наприклад, PreToolUse), потім засіб зіставлення перевіряє, чи застосовується цей хук, після чого запускається скрипт хука, який отримує JSON через stdin, а код виходу визначає, що станеться далі. Код виходу 0 означає продовження виконання, код виходу 2 означає блокування дії. Цей порядок однаковий незалежно від того, який тип хука ви використовуєте.

Подія -> Матчер -> Хук -> Код виходу (4-кроковий процес)

Ось як працює кожне виконання хука:

1. EVENT FIRES          e.g., PreToolUse(Write)
       |
2. MATCHER CHECKS       Does "Write" match the hook's matcher pattern?
       |
3. HOOK EXECUTES        Shell script runs, receives JSON via stdin
       |
4. EXIT CODE DECIDES    0 = proceed | 2 = block | other = error

JSON, що надходить на stdin, містить усе про подію: tool_name, tool_input (шлях до файлу, вміст, команду) та метадані сесії. Ваш скрипт зчитує цей JSON, виконує потрібну логіку та завершується з відповідним кодом.

Для хуків PreToolUse код виходу 2 — найпотужніший: він повністю блокує дію та надсилає ваше повідомлення зі stdout назад Claude як зворотний зв'язок. Claude бачить ваше повідомлення й може скоригувати свій підхід.

Області налаштувань: користувач, проєкт і локальні

Хуки зберігаються у settings.json на трьох рівнях:

Налаштування проєкту найкорисніші для команд. Додайте свої хуки у .claude/settings.json, закомітьте його — і кожен розробник у команді автоматично отримає ті самі захисні обмеження.

Поле if: точне фільтрування

Починаючи з Claude Code v2.1.85, хуки підтримують поле if, яке дає змогу фільтрувати за аргументами інструменту, а не лише за його назвою. Як зазначено в довіднику з хуків Anthropic, це означає, що ви можете написати хук, який спрацьовуватиме лише на команди Bash, що відповідають git push, замість того щоб запускатися на кожен виклик Bash.

{
  "matcher": "Bash",
  "if": "tool_input.command matches 'git push'",
  "hooks": [{ "type": "command", "command": "./scripts/check-branch.sh" }]
}

Це було значним покращенням. До появи if вам доводилося або надто широко збігати (кожна команда Bash), або виконувати фільтрування всередині скрипта (неохайно).

Усі події хуків Claude Code: таблиця швидкого довідника

Claude Code надає понад 20 подій хуків упродовж свого життєвого циклу, як задокументовано в офіційному довіднику з хуків та журналі змін Claude Code. Найчастіше використовуються PreToolUse, PostToolUse, Notification і Stop, але новіші події, як-от ConfigChange і FileChanged, відкривають можливості для розширених патернів автоматизації.

Ось повний довідник:

Порада професіонала: У 80% випадків ви використовуватимете PreToolUse і PostToolUse. SessionStart — наступний за корисністю, він ідеально підходить для впровадження контексту проєкту, який потрібен Claude на початку кожної сесії.

4 типи хуків Claude Code: детальний розбір

Claude Code підтримує чотири типи обробників хуків: командні хуки виконують shell-скрипти, HTTP-хуки надсилають POST-запити на URL-адреси, промпт-хуки ставлять Claude запитання з відповіддю «так/ні», а агентні хуки запускають субагента з доступом до інструментів. За нашим досвідом, командні хуки покривають 90% сценаріїв використання. HTTP-хуки варто застосовувати для зовнішніх інтеграцій, а промпт- та агентні хуки — для неоднозначних рішень, які потребують оцінки ШІ.

Хуки команд (робоча конячка)

Хуки команд виконують shell-команду та використовують код виходу для визначення результату. Вони отримують JSON-дані події через stdin.

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "jq -r '.tool_input.command' | grep -q 'rm -rf /' && exit 2 || exit 0"
      }]
    }]
  }
}

Саме це ви використовуватимете для форматування, захисту файлів, сповіщень та більшості автоматизацій. Швидко, просто та передбачувано.

HTTP-хуки (зовнішні інтеграції)

HTTP-хуки надсилають POST-запит на URL із JSON події в тілі. Код статусу відповіді визначає результат (200 = продовжити, 403 = заблокувати).

{
  "hooks": {
    "Stop": [{
      "matcher": "",
      "hooks": [{
        "type": "http",
        "url": "https://your-api.com/claude-webhook"
      }]
    }]
  }
}

Чудово підходить для надсилання подій у Slack, Discord, PagerDuty або на власну панель керування. Ви також можете використовувати це для запиту до зовнішнього рушія політик перед дозволом на виконання інструменту.

Промпт-хуки (рішення на основі ШІ)

Промпт-хуки передають дані події самому Claude для одноразової оцінки «так/ні». Claude повертає JSON-відповідь із \"decision\": \"allow\" або \"decision\": \"block\" плюс обґрунтування.

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "prompt",
        "prompt": "Is this bash command safe to run in a production environment? Consider: does it modify system files, delete data, or access sensitive credentials?"
      }]
    }]
  }
}

Використовуйте їх економно. Вони додають затримку (повний виклик LLM на кожне виконання хука) і витрати. Але для справді суб'єктивних перевірок безпеки, як-от «чи виглядає ця міграція бази даних руйнівною?», їм важко знайти заміну. Якщо вам цікаво про перемикання моделей Claude Code, модель, що використовується для промпт-хуків, відповідає моделі вашого поточного сеансу.

Хуки агента (перевірка за допомогою інструментів)

Хуки агента створюють субагента з доступом до інструментів Read, Grep і Glob. Субагент може перевіряти файли перед ухваленням рішення.

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write",
      "hooks": [{
        "type": "agent",
        "prompt": "Check if the file being written follows the project's naming conventions and import patterns. Read .claude/CONVENTIONS.md for the rules."
      }]
    }]
  }
}

Це найпотужніший тип хуків, але водночас найповільніший. Використовуйте його лише для критично важливих перевірок, де для ухвалення правильного рішення потрібен контекст файлів.

7 готових до продакшену прикладів хуків Claude Code (копіюй і вставляй)

Найкорисніші хуки Claude Code включають автоформатування за допомогою Prettier або Black після редагування файлів, блокування запису в захищені файли, надсилання сповіщень на робочий стіл після завершення завдання, впровадження контексту проєкту на початку сесії, запуск тестів після змін коду, забезпечення захисту гілок та аудит використання всіх інструментів. Я використовую різні варіації цих хуків у кожному проєкті протягом останніх трьох місяців.

Кожен наведений нижче приклад — це готовий фрагмент settings.json, який можна додати у ваш .claude/settings.json. Колекції спільноти, як-от awesome-claude-code, містять ще більше патернів.

1. Автоформатування під час збереження

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "FILE=$(jq -r '.tool_input.file_path // .tool_input.file' /dev/stdin); case \"$FILE\" in *.ts|*.tsx|*.js|*.jsx) npx prettier --write \"$FILE\" 2>/dev/null;; *.py) black \"$FILE\" 2>/dev/null;; esac; exit 0"
      }]
    }]
  }
}

Це спрацьовує після кожного Write або Edit, витягує шлях до файлу з JSON у stdin і запускає відповідний форматувальник. exit 0 наприкінці гарантує, що хук ніколи не блокує виконання — помилки форматування не повинні зупиняти Claude.

Порада: додайте *.go з gofmt та *.rs з rustfmt, якщо ви працюєте з різними мовами.

2. Блокування запису в захищені файли

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write|Edit",
      "if": "tool_input.file_path matches '(\\.env|\\.env\\.local|package-lock\\.json|yarn\\.lock|pnpm-lock\\.yaml)'",
      "hooks": [{
        "type": "command",
        "command": "echo '{\"message\": \"BLOCKED: This file is protected. Edit it manually.\"}' && exit 2"
      }]
    }]
  }
}

Код виходу 2 блокує дію та надсилає JSON-повідомлення назад до Claude. Claude бачить зворотний зв'язок і коригується — зазвичай він повідомляє, що хотів змінити файл, і просить вас зробити це вручну. Поле if запобігає спрацюванню на кожен виклик Write.

3. Сповіщення на робочому столі після завершення

{
  "hooks": {
    "Notification": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "MSG=$(jq -r '.message // \"Claude Code task finished\"' /dev/stdin); if [ \"$(uname)\" = 'Darwin' ]; then osascript -e \"display notification \\\"$MSG\\\" with title \\\"Claude Code\\\"\"; else notify-send 'Claude Code' \"$MSG\"; fi; exit 0"
      }]
    }]
  }
}

Працює на macOS (osascript) і Linux (notify-send). Порожній матчер означає, що воно спрацьовує на всі сповіщення. Це справді корисно, коли ви запускаєте тривале завдання й перемикаєтеся на інше вікно.

4. Ін'єкція контексту на початку сесії

{
  "hooks": {
    "SessionStart": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "echo '{\"message\": \"Project: '\"$(basename $(pwd))\"' | Branch: '\"$(git branch --show-current 2>/dev/null || echo none)\"' | Last commit: '\"$(git log --oneline -1 2>/dev/null || echo none)\"'\"}'; exit 0"
      }]
    }]
  }
}

Це впроваджує назву поточного проєкту, гілку Git та останній коміт у кожну сесію. Claude отримує цей контекст автоматично — не потрібно повідомляти йому, на якій гілці ви перебуваєте.

5. Автоматичний запуск тестів після змін коду

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "if": "tool_input.file_path matches '\\.(ts|tsx|js|jsx|py)$'",
      "hooks": [{
        "type": "command",
        "command": "FILE=$(jq -r '.tool_input.file_path' /dev/stdin); TEST_FILE=$(echo \"$FILE\" | sed 's/\\.[^.]*$/.test&/'); if [ -f \"$TEST_FILE\" ]; then npx jest \"$TEST_FILE\" --no-coverage 2>&1 | tail -5; fi; exit 0",
        "timeout": 30000
      }]
    }]
  }
}

Якщо існує відповідний файл тесту, він запускається автоматично після того, як Claude відредагує вихідний код. tail -5 робить вивід лаконічним, а тайм-аут запобігає неконтрольованому виконанню наборів тестів. Це добре поєднується з процесом ШІ-рецензування коду.

6. Застосування захисту гілок (розширено)

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "if": "tool_input.command matches 'git push.*(main|master|production)'",
      "hooks": [{
        "type": "command",
        "command": "echo '{\"message\": \"BLOCKED: Direct push to protected branch. Use a feature branch and open a PR.\"}' && exit 2"
      }]
    }]
  }
}

Це блокує будь-який git push, спрямований на гілки main, master або production. Claude отримає зворотний зв'язок і запропонує натомість створити гілку функціональності (feature branch).

7. Журналювання аудиту безпеки (розширене)

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "INPUT=$(cat /dev/stdin); CMD=$(echo \"$INPUT\" | jq -r '.tool_input.command'); echo \"[$(date -u +%Y-%m-%dT%H:%M:%SZ)] BASH: $CMD\" >> .claude/audit.log; exit 0"
      }]
    }]
  }
}

Записує кожну команду Bash, яку виконує Claude, у файл аудиту з позначкою часу UTC. Незамінне для перевірок безпеки та розуміння того, що саме Claude робив протягом сеансу. Додайте .claude/audit.log до вашого .gitignore.

Хуки проти MCP проти Skills проти CLAUDE.md: коли що використовувати

Використовуйте хуки для детермінованої автоматизації, яка має запускатися завжди (форматування, блокування, сповіщення). Використовуйте MCP, щоб надати Claude доступ до зовнішніх інструментів і даних. Використовуйте Skills для багаторазових пакетів промптів. Використовуйте CLAUDE.md для поведінкових настанов і контексту проєкту. Хуки гарантовані; все інше — імовірнісне. Це єдина найважливіша відмінність, і я постійно повертаюся до неї, консультуючи команди.

Матриця рішень

Щоб дізнатися більше про MCP, перегляньте наш посібник з MCP. Якщо ви переходите з Cursor, то система правил Cursor приблизно аналогічна CLAUDE.md, але в Cursor немає нічого подібного до хуків.

Коли вони перетинаються (і як обрати)

Ось блок-схема, якою я користуюся:

• «Це ПОВИННО відбуватися щоразу, без винятків?» — Хук. Форматувати код, блокувати захищені файли, надсилати сповіщення. Нульова неоднозначність.
• «Чи потрібна Claude нова МОЖЛИВІСТЬ, якої він не має?» — MCP-сервер. Доступ до бази даних, виклик API, пошук у зовнішній документації.
• «Чи хочу я мати багаторазові ІНСТРУКЦІЇ для конкретного робочого процесу?» — Навичка (slash-команда). Шаблони код-рев'ю, чеклисти розгортання.
• «Чи хочу я сформувати ПОВЕДІНКУ Claude у цьому проєкті?» — CLAUDE.md. Стандарти кодування, архітектурні рішення, бажані бібліотеки.

Реальні приклади, які прояснюють межу:

• «Завжди форматуй за допомогою Prettier» = Хук (це має відбуватися щоразу)
• «Використовуй Prettier для форматування» у CLAUDE.md = Рекомендація (Claude може забути)
• «Шукай у документації нашої компанії» = MCP (нова можливість)
• «Дотримуйся нашого стайл-гайду під час код-рев'ю» = Навичка або CLAUDE.md

Як зазначено в оголошенні Anthropic про плагіни, хуки — це лише частина ширшої екосистеми плагінів, яка також включає MCP та Навички. Вони створені, щоб доповнювати одне одного, а не конкурувати.

Стартовий набір: готова конфігурація хуків Claude Code для будь-якого проєкту

Стартова конфігурація хуків для Claude Code має включати автоформатування під час редагування файлів, сповіщення про завершення завдання, захист чутливих файлів, ін'єкцію контексту сесії та стоп-хук для очищення. Це саме та конфігурація, яку я додаю в кожен новий проєкт — адаптована під стек, але структура залишається незмінною.

Конфігурація

{
  "hooks": {
    "SessionStart": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "echo '{\"message\": \"Project: '\"$(basename $(pwd))\"' | Branch: '\"$(git branch --show-current 2>/dev/null)\"' | Node: '\"$(node -v 2>/dev/null)\"'\"}'; exit 0"
      }]
    }],
    "PreToolUse": [{
      "matcher": "Write|Edit",
      "if": "tool_input.file_path matches '(\\.env|\\.env\\..+|.*lock\\.json|.*lock\\.yaml)'",
      "hooks": [{
        "type": "command",
        "command": "echo '{\"message\": \"Protected file. Edit manually.\"}' && exit 2"
      }]
    }],
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "FILE=$(jq -r '.tool_input.file_path // .tool_input.file' /dev/stdin); case \"$FILE\" in *.ts|*.tsx|*.js|*.jsx) npx prettier --write \"$FILE\" 2>/dev/null;; *.py) black \"$FILE\" 2>/dev/null;; *.go) gofmt -w \"$FILE\" 2>/dev/null;; esac; exit 0"
      }]
    }],
    "Notification": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "MSG=$(jq -r '.message // \"Done\"' /dev/stdin); osascript -e \"display notification \\\"$MSG\\\" with title \\\"Claude Code\\\"\" 2>/dev/null || notify-send 'Claude Code' \"$MSG\" 2>/dev/null; exit 0"
      }]
    }],
    "Stop": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "echo '[STOP] '\"$(date +%H:%M:%S)\"'' >> .claude/session.log; exit 0"
      }]
    }]
  }
}

Як налаштувати під ваш стек

Замініть команди форматування та тестування у наведеній вище конфігурації відповідно до вашого стеку. Структура залишається незмінною.

Перевірка роботи хуків

Існує три способи переконатися, що хуки активні:

1. Команда /hooks — введіть /hooks у Claude Code, щоб переглянути всі зареєстровані хуки, їхні матчері та статус.
2. Перевірка транскрипту — після спрацювання хука перегляньте транскрипт сесії. Виконання хуків відображаються разом із їхнім виводом і кодом виходу.
3. Швидке перемикання — додайте "disableAllHooks": true до вашого settings.json, щоб тимчасово вимкнути всі хуки без видалення конфігурації. Видаліть цей рядок (або встановіть значення false), щоб увімкнути їх знову.

Інтеграція з CI/CD: хуки Claude Code у headless-режимі

Хуки Claude Code працюють у headless-режимі (claude -p) з деякими відмінностями: хуки сповіщень і надалі спрацьовують, але їх варто переспрямувати в логування замість сповіщень на робочому столі. Хуки PreToolUse з кодом виходу 2 можуть призупиняти headless-сесії для перевірки людиною. GitHub Actions використовує anthropics/claude-code-action@v1 разом із хуками для автоматизованих робочих процесів.

Поведінка в headless-режимі

Головний сюрприз headless-режиму: хуки PreToolUse, що завершуються з кодом 2, не просто тихо завершуються помилкою. Вони призупиняють сесію і дають змогу відновити її через --resume, що реалізує патерн «людина в циклі» (human-in-the-loop) для CI-конвеєрів.

Інтеграція з GitHub Actions

Ось мінімальний робочий процес GitHub Actions, який використовує Claude Code з хуками. Як задокументовано в офіційному посібнику з GitHub Actions:

- name: Run Claude Code
  uses: anthropics/claude-code-action@v1
  with:
    prompt: "Review this PR and suggest improvements"
    allowed_tools: "Read,Grep,Glob"
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

Ваші хуки у .claude/settings.json подорожують разом із репозиторієм, тому вони спрацьовуватимуть у CI точно так само, як і локально. Просто переконайтеся, що будь-які хуки, які покладаються на інструменти, специфічні для робочого столу (як-от osascript), мають резервні варіанти або умовні перевірки.

Керування хуками в команді

Патерн, який добре працює для команд:

• .claude/settings.json (закомічено), Спільні хуки команди: захист файлів, форматувальники, захист гілок. Це отримують усі.
• .claude/settings.local.json (в ігнорі git), Особисті хуки: налаштування сповіщень, власне логування, експериментальні хуки.
• ~/.claude/settings.json (глобальний для користувача), Ваші типові налаштування для всіх проєктів: стиль сповіщень, особисті вподобання щодо форматування.

Це відображає те, як працюють .editorconfig (закомічено) та локальні налаштування IDE (особисті). Як зазначено в посібнику з CI/CD від Анджело Ліми, команди, які стандартизують спільні хуки, стикаються з меншою кількістю проблем у стилі «на моїй машині працює» при роботі з Claude Code.

Усунення несправностей хуків Claude Code та поширені помилки

Серед поширених проблем із хуками Claude Code — хуки не спрацьовують (перевірте правильність написання матчера та розташування settings.json), хуки виконуються, але не блокують (неправильний код завершення — використовуйте 2, а не 1), нескінченні цикли (хук Stop запускає сам себе) та повільний запуск (забагато синхронних хуків). Найпоширеніша помилка, яку я бачу, — це плутанина з кодами завершення: розробники використовують exit 1, коли мають на увазі exit 2.

Хук не спрацьовує

Симптоми: Ви додали хук, але коли відбувається подія, нічого не відбувається.

Виправлення:

• Помилка в матчері. Матчери чутливі до регістру. "write" не збіжиться з інструментом Write. Перевірте точні назви інструментів за допомогою /hooks.
• Неправильний файл налаштувань. Хуки у ~/.claude/settings.json не з'являться у виводі /hooks для області видимості проєкту. Спробуйте .claude/settings.json у корені проєкту.
• Синтаксична помилка JSON. Зайва кома або відсутня дужка тихо вимикає всю конфігурацію хуків. Проганьте ваш settings.json через jq ., щоб перевірити валідність.
• disableAllHooks: true. Перевірте, чи не залишив хтось (або попередній сеанс налагодження) цей прапорець увімкненим.

Хук виконується, але не блокує

Симптоми: Ваш хук PreToolUse виконується, але дія все одно продовжується.

Виправлення:

• Неправильний код виходу, Код виходу 1 означає «помилка» (хук не спрацював), а не «блок». Використовуйте exit 2, щоб заблокувати дію. Це збиває з пантелику майже всіх, як зазначено в офіційній документації.
• Відсутній JSON у stdout, Для блокувальних хуків виводіть JSON-повідомлення, щоб Claude знав, чому дію було заблоковано: echo '{"message": "Blocked: reason"}'

Нескінченні цикли

Симптоми: Claude продовжує повторювати ту саму дію, або ваш комп'ютер підозріло нагрівається.

Виправлення:

• Хук Stop запускає дії, Якщо ваш хук Stop записує файл або виконує команду, яка змушує Claude відповідати, ви створили цикл. Хуки Stop мають виконувати лише пасивні дії: логування, сповіщення, очищення.
• Хук PostToolUse спричиняє редагування, Хук PostToolUse, який змінює файл, запускає іншу подію PostToolUse. Захистіться від цього за допомогою конкретних матчерів або поля if.

Проблеми з продуктивністю

Симптоми: Запуск Claude або виконання інструментів помітно уповільнюються.

Виправлення:

• Забагато хуків SessionStart, Кожен із них виконується синхронно під час запуску. Тримайте їх легкими (не більше 1 секунди кожен).
• Важкі скрипти на гарячих шляхах, Хуки на PreToolUse та PostToolUse спрацьовують часто. Якщо ваш скрипт виконує мережеві запити або ресурсомісткі обчислення, додайте поле timeout (у мілісекундах) і подумайте, чи не варто натомість зробити його HTTP-хуком.
• Відсутність кешування, Якщо ви неодноразово перевіряєте одне й те саме (наприклад, «чи це захищена гілка?»), кешуйте результат у тимчасовий файл замість запуску команд Git під час кожного виклику хука.

Часті запитання

Що таке хуки Claude Code і як вони працюють?

Хуки Claude Code — це визначені користувачем скрипти автоматизації, які виконуються на певних подіях життєвого циклу під час сесії Claude Code. Ви налаштовуєте їх у settings.json, вказуючи шаблон збігу та обробник (команду оболонки, HTTP-ендпоінт, промпт або агент). Коли спрацьовує відповідна подія, хук виконується автоматично та використовує коди виходу для керування результатом.

Як налаштувати хуки у settings.json Claude Code?

Додайте об'єкт \"hooks\" до будь-якого з трьох розташувань конфігурації: ~/.claude/settings.json (глобальний для користувача), .claude/settings.json (спільний для проєкту) або .claude/settings.local.json (особистий для проєкту). Кожен тип події зіставляється з масивом визначень хуків із matcher, необов'язковим полем if та масивом hooks, що містить об'єкти обробників із type і command або url.

Яка різниця між хуками PreToolUse та PostToolUse?

PreToolUse спрацьовує до виконання інструменту, даючи вам змогу заблокувати його за допомогою коду виходу 2. PostToolUse спрацьовує після завершення виконання — він корисний для форматування, тестування або логування. PreToolUse призначений для запобігання та контролю доступу. PostToolUse призначений для валідації та очищення. Обидва отримують назву інструменту та вхідні дані у форматі JSON через stdin.

Чи можуть хуки Claude Code блокувати небезпечні команди?

Так. Хуки PreToolUse з кодом виходу 2 блокують виконання будь-якого інструменту. Ви можете захистити конфіденційні файли від запису, заблокувати shell-команди, що відповідають небезпечним шаблонам, як-от rm -rf або git push main, та запобігти доступу до продакшн-баз даних. Повідомлення про блокування надсилається назад Claude як зворотний зв'язок, щоб він міг скоригувати свій підхід.

Які події хуків доступні в Claude Code?

Claude Code надає понад 15 подій: PreToolUse і PostToolUse для виконання інструментів, Notification для сповіщень, Stop для завершення сесії, SessionStart для ініціалізації, UserPromptSubmit для фільтрації вхідних даних, PreCompact і PostCompact для керування контекстом, а також новіші події, як-от ConfigChange, FileChanged, TaskCreated і PermissionDenied. Повну таблицю посилань дивіться у розділі про події хуків вище.

Чим хуки відрізняються від інструментів MCP та Skills?

Хуки детерміновані: вони завжди спрацьовують на відповідних подіях, незалежно від того, що вирішить Claude. Інструменти MCP розширюють можливості Claude (доступ до бази даних, виклики API), але Claude сам обирає, коли їх використовувати. Skills — це багаторазові пакети інструкцій, які викликаються слеш-командами. CLAUDE.md надає рекомендації щодо поведінки. Використовуйте хуки, коли щось має відбуватися щоразу, а MCP — коли Claude потрібні нові можливості.

Чи працюють хуки Claude Code у headless-режимі?

Так, але з застереженнями. Хуки спрацьовують у headless-режимі (claude -p) як зазвичай, проте хуки, прив'язані до десктопу — як-от сповіщення macOS — потребують запасних варіантів. Важливо, що хуки PreToolUse, які завершуються з кодом виходу 2, можуть призупиняти headless-сесії для схвалення людиною через --resume. Це дає змогу будувати CI/CD-конвеєри з участю людини, де певні дії потребують ручного підтвердження.

Скільки хуків — це забагато? Чи уповільнюють хуки Claude Code?

Жорсткого обмеження немає, але кожен синхронний хук додає затримку. Хуки SessionStart виконуються під час запуску, тож тримайте їх швидкими (менше 1 секунди кожен). Хуки PreToolUse та PostToolUse спрацьовують на кожен відповідний виклик інструменту — важкі скрипти тут швидко накопичуються. Я рекомендую тримати загальну кількість хуків у межах 10–15, використовувати поле if для звуження області дії та додавати значення timeout, щоб запобігти неконтрольованому виконанню скриптів.

Чи можна використовувати хуки для автоформатування коду за допомогою Prettier або Black?

Так, це найпопулярніший сценарій використання хуків. Створіть хук PostToolUse, що відповідає Write|Edit, витягніть шлях до файлу з JSON у stdin і запустіть відповідний форматувальник залежно від розширення файлу. Повну, готову до копіювання конфігурацію, яка обробляє файли TypeScript, JavaScript і Python, дивіться у прикладі номер один у розділі виробничих прикладів.

Чи безпечні хуки Claude Code? Які існують ризики безпеки?

Хуки виконуються з усіма правами вашого користувача, жодної пісочниці немає. Шкідливий хук може прочитати ваші SSH-ключі, видалити файли або викрасти дані. Використовуйте лише хуки з надійних джерел, перевіряйте будь-який спільний файл .claude/settings.json, перш ніж додавати його до свого проєкту, і використовуйте .claude/settings.local.json для особистих хуків, які не повинні поширюватися. Щоб дізнатися більше про загальні підходи до безпеки ШІ, перегляньте наш посібник із захисних бар'єрів для LLM.