Хуки Claude Code и гейты качества: защита до коммита

Дисциплина не масштабируется. Усталость, пятница, «тут одна строчка» — и в main уезжает упавший тест или, хуже, ключ от базы. Ещё острее эта проблема с AI-агентом: Claude Code генерирует код пачками, коммиты летят быстрее, чем успеваешь их проверять. Решение — гейт качества, автоматический барьер, который срабатывает сам. В этой статье разберём два слоя таких барьеров: git-хуки и хуки Claude Code — как они устроены, чем различаются и как их сбалансировать, чтобы гейт защищал, а не тормозил работу.

Два вида хуков — два разных слоя защиты

Первое, что важно понять: «хуки» в контексте Claude Code — это два совершенно разных механизма, и их часто путают.

Git-хуки — скрипты, которые git запускает на определённых событиях: pre-commit (перед тем как коммит попадёт в историю) и pre-push (перед отправкой в удалённый репозиторий). Срабатывают у всех, кто коммитит — и человек, и агент.

Хуки Claude Code — конфигурация в .claude/settings.json, которая перехватывает события самого агента: PreToolUse (до вызова инструмента) и PostToolUse (после). Срабатывают только когда работает агент — это ранний барьер конкретно для его действий.

Вместе они образуют два рубежа: git-хук — последний заслон перед историей репозитория, хук Claude Code — защита на уровне действий агента ещё до того, как он что-то запишет. Чем раньше барьер стоит, тем меньше шанс инцидента.

Гейт качества: три обязательные проверки

Минимальный гейт закрывает три вопроса до того, как изменение попадёт в репо:

1. Линт и типы — eslint + tsc --noEmit. Код вообще валиден, нет синтаксических ошибок и нарушений типов.
2. Тесты — юнит и/или быстрый e2e. Ничего не сломано регрессией.
3. Секрет-скан — никаких ключей и паролей в диффе. Секрет, попавший в историю git, считается скомпрометированным — ротация обязательна.

Все три запускаются локально и бесплатно. Это и есть «минимальный CI на своей машине».

Настройка git-хука через Husky

На практике git-хуки удобнее всего управлять через Husky (lefthook — альтернатива с похожим принципом). Установка:

npm i -D husky lint-staged
npx husky init        # создаёт .husky/ и pre-commit

Для pre-commit настраиваем только быстрые проверки — линт по затронутым файлам и секрет-скан. В package.json:

{
  "lint-staged": {
    "*.{ts,tsx}": ["eslint --fix", "bash -c 'tsc --noEmit'"]
  }
}

Содержимое .husky/pre-commit:

npx lint-staged
npm run scan:secrets

Тяжёлые тесты — на pre-push, а не на каждый коммит. Создаём .husky/pre-push:

npm run test:unit
npx playwright test --project=chromium

Логика проста: коммитим часто — значит, на коммите только лёгкое (секунды). Пушим реже — там можно позволить e2e (десятки секунд). Полный CI в облаке закрывает оставшееся (минуты).

Секрет-скан: простой и надёжный варианты

Для секрет-скана есть два подхода. Первый — готовый инструмент вроде gitleaks, который умеет распознавать форматы токенов крупных провайдеров. Второй — минималистичный grep-гейт, который хорошо работает как fallback и легко читаем:

# scan:secrets — грубый, но наглядный пример
if git diff --cached -U0 | grep -E -i '(api[_-]?key|secret|password|BEGIN.*PRIVATE KEY)\s*[:=]'; then
  echo "Похоже на секрет в изменениях. Коммит остановлен."
  exit 1
fi

Готовый сканер надёжнее: меньше ложных срабатываний, знает о форматах токенов AWS, GitHub, Stripe. Но даже три строки grep уже ловят большинство случайных утечек. Выбор зависит от зрелости проекта — принцип один: секреты не должны доезжать до истории репозитория.

Хук Claude Code: защищаем .env от агента

Git-хуки ловят проблему на коммите. Хук Claude Code ловит её ещё раньше — до того как агент вообще прикоснулся к чувствительному файлу. Это особенно важно при работе с правами и безопасностью Claude Code: агент может попытаться обновить конфигурацию по инструкции и случайно записать что-то в .env.

Настраивается в .claude/settings.json проекта:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          { "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/protect-env.sh" }
        ]
      }
    ]
  }
}

Хук-скрипт проверяет путь целевого файла (получает событие из stdin как JSON) и возвращает deny, если путь соответствует .env. Просим агента «обнови конфиг в .env» — агент получает отказ. Изменение даже не начинается.

Точную схему полей PreToolUse и формат решения (permissionDecision) сверяйте через актуальную документацию Claude Code — это интерфейс, который может обновляться.

На реальном проекте: CoffeeCRM

В CoffeeCRM (Next.js + NestJS + PostgreSQL) гейт выглядит так в связке:

• pre-commit — lint-staged по TypeScript-файлам + секрет-скан за несколько секунд.
• pre-push — юнит-тесты NestJS и быстрый Playwright-тест критичного флоу (создание заказа).
• .claude/settings.json — PreToolUse с запретом на Write|Edit в .env.

Три кейса, которые доказывают работу гейта:

• Упавший тест: меняем статус ответа на неверный, коммитим (pre-commit прошёл — линт в порядке), делаем git push → pre-push гонит e2e → пуш заблокирован с сообщением об упавшем тесте.
• Секрет в коде: добавляем строку вида const dbPassword = "p@ssw0rd-prod", git add, git commit → коммит заблокирован секрет-сканом. Ключ даже не доехал до истории.
• Корректное изменение: чиним тест, убираем секрет — всё зелёное, проходит без задержки.

Об организации самого процесса тестирования с агентом — в статье code review и тесты с агентом.

Баланс строгости и скорости

Слишком строгий гейт убивает себя сам. Если полный e2e гоняется на каждый коммит, люди начинают обходить его на автомате — и барьер, который всегда обходят, не защищает.

Рабочий принцип: на pre-commit — только быстрое (линт, типы, секрет-скан, затронутые юнит-тесты); тяжёлое — на pre-push или в облачном CI.

Аварийный обход существует — git commit --no-verify и git push --no-verify пропускают хуки. Но это стоп-кран, а не ежедневная практика. Правило, которое хорошо работает в команде: если обходишь гейт — напиши в PR почему. Если обходишь часто — гейт настроен неправильно, его надо облегчить, а не привыкать обходить.

Итог

Хуки Claude Code и git-хуки — это два слоя одной системы. Git-хук (pre-commit, pre-push) закрывает историю репозитория от битого кода и секретов. Хук Claude Code (PreToolUse) не даёт агенту совершить опасное действие ещё до коммита. Баланс — быстрое на коммите, тяжёлое на пуше — делает гейт защитой, а не препятствием.

Если хотите выстроить весь рабочий процесс — от первых запросов к агенту до деплоя с гейтами — это подробно разобрано в полном курсе по Claude Code. Там же — практика на CoffeeCRM с артефактами, которые можно сразу применять в своих проектах.

Про основы того, что такое Claude Code и как устроена его модель работы — читайте в отдельном материале.