# Хуки Claude Code: как превратить правило из CLAUDE.md в проверку перед командой

Хуки Claude Code: как перенести правило из CLAUDE.md в проверку, которая останавливает команду до выполнения. Пример хука, его проверка и поведение при сбое.

URL: https://posts.danashkin.ru/guides/huki-claude-code-pravilo-bez-isklyucheniy
Обновлено: 2026-11-15

---

Хуки Claude Code - это команды, которые среда запускает сама в заданный момент: перед вызовом инструмента, после правки файла, когда агент закончил ответ. Правило из CLAUDE.md агент читает и может не выполнить. Хук на событии «перед командой» проверяет каждую команду и останавливает запрещённую до того, как она выполнится, в любом режиме разрешений. Поэтому в хук переносят правила, нарушение которых трудно откатить.

## Почему агент нарушает правило из CLAUDE.md?

**Главное**

CLAUDE.md попадает агенту в контекст как текст, и модель сама решает, как применить его к конкретной команде. Документация Claude Code описывает хуки как детерминированное управление: действие происходит всегда и не зависит от того, решит ли модель его выполнить. Правило, которое держится на внимательности модели, однажды пропускается.

Файл-память хорош для всего, что требует понимания: как называть файлы, где лежат материалы, что проверить перед сдачей. [Подробнее о том, что писать в CLAUDE.md](/guides/chto-pisat-v-claude-md) - в отдельном разборе. У файла есть предел. Это инструкция, которую агент учитывает вместе со всем остальным контекстом, и на сотой команде длинной сессии она может проиграть текущей задаче.

Вот как это выглядело у меня. 15 сентября я ввёл правило: при отправке кода на сервер агент увозит только коммиты своего чата, а коммиты соседних окон не трогает. Правило стояло в CLAUDE.md и в скилле завершения сессии. 16 сентября агент напечатал список того, что уедет, и следом выполнил push, не сверившись с этим списком. На сервер ушли два чужих коммита.

Текст в CLAUDE.md и скилле правило не удержал. 18 сентября его стал проверять хук.

На практике это значит: push, удаление, отправка данных наружу либо необратимы, либо дорого откатываются. Для них мало того, что агент обычно помнит правило. Почему параллельные окна вообще сталкиваются в одной папке, есть в статье [про два окна агента](/guides/dva-okna-agenta-odnovremenno).

## Хук простыми словами: событие, фильтр, команда

**Главное**

Хук - запись в файле настроек из трёх частей: событие (когда сработать), фильтр (на какой инструмент) и команда (что запустить). Claude Code передаёт команде описание действия, и она отвечает: пропустить, остановить или ничего не решать.

Хуки живут в файле настроек Claude Code. Личный `~/.claude/settings.json` действует во всех твоих проектах на этом компьютере. Файл `.claude/settings.json` в папке проекта работает только в ней и уезжает в репозиторий вместе с кодом, то есть достаётся всем, кто откроет проект.

Запись выглядит так:

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "$HOME/.claude/hooks/stop-force-push.sh" }
        ]
      }
    ]
  }
}
```

В ней три решения. `PreToolUse` - событие «до вызова инструмента». `Bash` - фильтр: хук срабатывает только на команды терминала, правки файлов и поиск идут мимо. Последняя строка - путь к скрипту, который получит описание команды.

Когда событие наступает, Claude Code передаёт скрипту JSON: какое событие, какой инструмент, с какими аргументами. Для команды терминала там лежит её полный текст. Скрипт его читает и отвечает кодом выхода. Код 0 означает «возражений нет», и дальше команда идёт обычным порядком разрешений. Код 2 означает «стоп»: команда не выполняется, а текст из потока ошибок уходит агенту как объяснение, почему.

Писать скрипт руками не обязательно. Документация прямо предлагает описать агенту, что нужно, и попросить его собрать хук. Твоя часть - сформулировать правило и проверить готовый хук до того, как ему довериться. [ИИ-агент](/concepts/ai-agent) пишет скрипт за минуту, проверка занимает ещё пять.

## Как хук останавливает опасную команду?

**Главное**

Скрипт на событии PreToolUse получает текст команды, находит в нём запрещённое и выходит с кодом 2. Команда не выполняется, в том числе в режиме без подтверждений. Проверить скрипт можно до подключения: подать ему JSON вручную и посмотреть код выхода.

Обезличенный пример: хук, который не даёт агенту перезаписать историю на сервере командой push с принудительной перезаписью.

```bash
#!/bin/bash
# Хук PreToolUse (пример): ловит push с перезаписью истории в распространённых формах
command -v jq >/dev/null || { echo "Хук не может проверить команду: нет jq" >&2; exit 2; }
CMD=$(jq -r '.tool_input.command // ""')
# есть ли в команде git push, в том числе git -C <папка> push
echo "$CMD" | grep -qE '(^|[^[:alnum:]_-])git([[:space:]]+-[^[:space:]]+([[:space:]]+[^-[:space:]][^[:space:]]*)?)*[[:space:]]+push([[:space:]]|$)' || exit 0
# флаги силы: --force и его варианты, короткие флаги с f (-f, -fu), ветка с плюсом (+main)
if echo "$CMD" | grep -qE '[[:space:]](--force[^[:space:]]*|-[a-zA-Z]*f[a-zA-Z]*|\+[^[:space:]]+)([[:space:]]|$)'; then
  echo "Стоп: push с перезаписью истории запрещён. Сделай обычный push или спроси меня." >&2
  exit 2
fi
exit 0
```

Скрипт проверен 1 ноября 2026 года на 18 командах, поданных вручную, без подключения к агенту. Код 2 и текст «Стоп» получили `git push --force origin main`, `git push origin main --force`, `git push -f`, `git push -fu origin main`, `git push origin +main`, `git -C /repo push --force origin main`, `git push --force-with-lease origin main` и `cd /repo && git push -f origin main`. Обычные `git push origin main`, `git push -u origin main`, `git push origin feature-fix` и `ls -la` прошли с кодом 0.

Это пример, а не защита. Хук читает текст команды, поэтому не видит того, чего в тексте нет. Проверено: `git pf`, если так назван псевдоним для force push, и `bash ./deploy.sh` с push внутри скрипта проходят с кодом 0. Страховка, которая от текста команды не зависит, - защита ветки на стороне сервера: по документации GitHub правило защиты ветки по умолчанию запрещает в неё force push. Хук ловит ошибку агента раньше и объясняет ему, что не так, а сервер держит то, что хук пропустил.

Третья строка скрипта отвечает на вопрос, что делать, если проверить нечем. Скрипт читает JSON утилитой jq. Если её нет, он не пропускает команду молча, а останавливает с объяснением. Этот случай тоже проверен: с пустым списком путей поиска программ скрипт вернул код 2.

Главное свойство такого хука: запрет на PreToolUse действует в каждом режиме разрешений, включая режим без подтверждений и запуск с флагом `--dangerously-skip-permissions`. Хук срабатывает раньше, чем Claude Code смотрит на режим.

Это видно и в живой работе. Агент в моей рабочей сессии работал без подтверждений. Когда он попытался одной командой рекурсивно удалить свою черновую папку, мой хук-сторож остановил её с объяснением: массовое удаление требует явного подтверждения. Агенту пришлось завести новую папку вместо чистки старой.

## События: до команды, после правки, в конце ответа

**Главное**

Под запреты берут PreToolUse: оно срабатывает до действия и умеет его остановить. PostToolUse срабатывает после, отменить уже ничего не может, зато подходит для сверок и пересборки файлов. Stop и Notification нужны для звуков и уведомлений.

Событий в документации больше тридцати, в ежедневной работе хватает четырёх. Так они распределены у меня:

| Событие | Когда срабатывает | Может остановить | Что на нём у меня |
|---|---|---|---|
| PreToolUse | перед вызовом инструмента | да | два хука на команды терминала: сторож секретов и проверка push |
| PostToolUse | после успешного вызова | нет, действие уже выполнено | сверка каталога правил и пересборка файла правил для второго агента |
| Stop | агент закончил ответ | может не дать агенту остановиться | звук |
| PermissionRequest | агент спрашивает разрешение | может отклонить запрос ответом deny в объекте решения, код 2 здесь не работает | звук |
| Notification | агент ждёт ответа | нет | звук |

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

PostToolUse полезен там, где после каждого изменения нужен порядок. В моей рабочей папке два агента, и у каждого свой файл правил. Хук после каждой правки собирает файл второго агента из первого, поэтому они не расходятся. Чем эти файлы отличаются, разобрано в статье [AGENTS.md и правила для агента](/guides/agents-md-pravila-dlya-agenta).

Звуковые хуки - самый простой вход в тему. На курсе по ИИ-агентам их ставят в первом модуле: звук, когда агент закончил задачу, и звук, когда он ждёт разрешения. Запреты на чтение файлов с ключами и на удаление папок там настраиваются следующим шагом, через правила разрешений. Если хочется пройти эти шаги на своём рабочем месте агента под присмотром, от звуковых хуков до правил разрешений, это программа [обучения работе с ИИ-агентами](https://danashkin.ru/agents/).

## Что будет, если хук сломается?

**Главное**

На большинстве событий упавший или зависший хук пропускает действие: в транскрипте появится ошибка хука, а команда выполнится. Поэтому хук-запрет стоит писать так, чтобы в непонятной ситуации он запрещал. В свежих версиях Claude Code для этого есть поле onFailure со значением block.

Это неочевидное место. Документация описывает его так: если хук завершился кодом, отличным от 0 и 2, не смог запуститься или вывел некорректный JSON, это неблокирующая ошибка, и действие выполняется. Хук-запрет с опечаткой в пути к скрипту молча пропускает всё подряд. То же с таймаутом: зависший PreToolUse вызов не блокирует.

Три способа закрыть эту дыру:

1. **Сбой внутри скрипта ведёт к запрету**

   Предусмотри в скрипте ситуации, где проверить нельзя, и отвечай на них запретом, как пример выше без jq. У меня проверка push при любой собственной ошибке отправку не пускает, а сторож секретов отвечает запретом, если на компьютере нет jq.

2. **Поле onFailure**

   В свежих версиях у хука есть поле `"onFailure": "block"`: если хук упал или не запустился, действие блокируется. По документации оно работает с версии 2.1.295. Свою версию покажет команда `claude --version`.

3. **Первый запуск под присмотром**

   Документация советует при первом прогоне хука-политики следить за уведомлением `hook error` в транскрипте: опечатка в пути к скрипту означает, что хук не запускается вообще.

## Как проверить, что хук работает?

**Главное**

Три проверки: подать скрипту JSON вручную до подключения, открыть /hooks и убедиться, что хук стоит на нужном событии, и вести журнал решений. Журнал показывает, что хук не только подключён, но и останавливает то, что должен.

Первая проверка делается до подключения, как в примере выше:

```bash
echo '{"tool_input":{"command":"git push -f"}}' | ./stop-force-push.sh; echo $?
```

На запрещённой команде ждёшь 2, на обычной 0.

Вторая проверка - после подключения. Команда `/hooks` в Claude Code показывает все хуки по событиям. Если твоего там нет, проверь, что JSON в файле настроек правильный: лишняя запятая или комментарий его ломают. Сочетание Ctrl+O открывает транскрипт, где видно, сработал ли хук и что он ответил.

Третья - журнал. Моя проверка push пишет строку на каждое решение: репозиторий, ветка, сколько чужих коммитов нашлось и сколько коммитов разрешено явно. Чужим хук считает коммит, который уедет на сервер, но не создан в этом чате и не является копией своего.

С 18 сентября по 31 октября хук сделал 580 проверок push в рабочих репозиториях. В 100 из них в списке нашлись чужие коммиты, и push не пошёл. Ещё около 1300 строк журнала - проверки во временных копиях репозиториев: приёмка самого хука и отправки из чистых клонов.

Приёмка нашла дыру, которую автор хука не видел. Хук сверяет то, что уедет, по состоянию до команды. Если в одной команде с push стояла другая git-команда, которая меняет ветку, хук её результата не видел, и чужой коммит проскакивал. Теперь такие связки он не пускает: сначала одна команда, push следующей. Отчёт агента «хук настроен» этого не показал бы, показал только прогон. Как принимать работу агента по факту, есть в статье [агент отчитался, а результата нет](/guides/agent-otchitalsya-a-rezultata-net).

## Границы: что оставить файлу и правилам разрешений

**Главное**

Хук нужен, когда правило проверяется механически, а нарушение дорого. Правила, где нужно понимание, остаются в CLAUDE.md. Простые запреты на чтение и запуск закрываются правилами разрешений. Любой хук работает с твоими правами, поэтому чужой хук подключают, только прочитав.

Перед тем как писать хук, задай себе два вопроса. Можно ли проверить правило по тексту команды или файла, не вникая в смысл? Дорого ли его нарушение? Если оба ответа «да», это хук. «Не пушь с --force» проверяется по тексту команды, с оговоркой из примера выше: псевдонимы и скрипты такой проверке не видны. «Пиши понятно для клиента» так не проверить, это остаётся файлу-памяти.

Для запретов вида «не читай этот файл» и «спрашивай перед удалением» в том же файле настроек есть правила разрешений. Они проще хука, но правка файла настроек сама по себе может уронить агента. Как вносить такие правки безопасно, разобрано в статье [агент настроил себе защиту и перестал запускаться](/guides/agent-pravit-svoi-nastroyki).

Для правил, где нужна оценка, документация описывает хуки с типом `prompt`: решение по действию принимает модель Claude. Это уже не детерминированная проверка, это вторая модель, которая смотрит на действие первой.

И последнее. Документация предупреждает, что хук выполняет команды с полными правами твоей учётной записи и может изменить, удалить или прочитать любой доступный тебе файл. Хук из чужого репозитория или плагина - это чужой код на твоём компьютере, читай его до подключения.

## Частые вопросы

**Главное**

Спрашивают, нужно ли уметь программировать, что значит сообщение hook error и как временно отключить все хуки.

### Частые вопросы

**Нужно ли уметь программировать, чтобы завести хук?**

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

**Что значит PreToolUse hook error в транскрипте?**

Скрипт хука завершился неожиданным кодом или не запустился, а действие при этом выполнилось. Частые причины по документации: относительный путь вместо абсолютного, у скрипта нет права на запуск (лечится `chmod +x`), на компьютере нет jq. Проверь скрипт вручную, подав ему JSON.

**Как временно отключить все хуки?**

В файле настроек есть ключ `"disableAllHooks": true`. Хуки из управляемых настроек организации при этом продолжают работать, если ключ не выставлен там же.

## Главный вывод

**Главное**

CLAUDE.md объясняет агенту, как работать, хук проверяет то, что нельзя пропустить. В хук переносят правила, которые проверяются по тексту команды и дорого стоят при нарушении.

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

Начать можно с одного хука на одно правило, которое агент уже нарушал. Описать его агенту, получить скрипт, прогнать вручную на двух командах, подключить и найти в `/hooks`.

Вспомни правило из своего CLAUDE.md, которое агент уже нарушал: его можно проверить по тексту команды или нет?

### Источники

- [Автоматизация действий с помощью hooks - руководство Claude Code](https://code.claude.com/docs/ru/hooks-guide)
- [Справочник по hooks: события, коды выхода, поле onFailure - документация Claude Code](https://code.claude.com/docs/ru/hooks)
- [Файлы параметров Claude Code и их приоритет](https://code.claude.com/docs/ru/settings)
- [Как Claude запоминает проект: файлы CLAUDE.md - документация Claude Code](https://code.claude.com/docs/ru/memory)
- [About protected branches: правила защиты веток и запрет force push - документация GitHub](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches)
