Как держать ИИ-агентов для кодинга в узде: Git hooks, которые реально работают

ИИ-агенты вроде Claude или Copilot пишут код на раз-два. Но без контроля они плодят спагетти: огромные файлы, запутанную логику и бардак в истории коммитов. В итоге codebase тонет в техдолге, а команда в ярости.

Выход простой: общие Git hooks, которые блокируют плохой код на входе в репозиторий.

Почему ИИ-агенты без тормозов — это катастрофа

Дайте агентам полную свободу — и получите:

• Монстр-файлы, где нарушен принцип единственной ответственности
• Лабиринты кода, которые разбирать дольше, чем писать заново
• Хлам в git log из бессмысленных коммитов
• Обходы проверок через --no-verify

Агенты рвутся помочь, но без рамок гонятся за скоростью, а не за качеством.

Git hooks — ваш фильтр качества

Git hooks — это скрипты, которые срабатывают на ключевых этапах: перед коммитом, пушем или мерджем. Как охранник у двери: не прошёл проверку — не зашёл.

Два топовых инструмента упрощают жизнь:

1. pre-commit — универсальный фреймворк, стандарт для Python и смешанных стэков.

2. husky — для JS/TS, интегрируется с npm, удобный для фронтендеров.

Пример настройки для строгого контроля:

Ключевые правила хуков для ИИ

# Пример .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: file-size-limit
        name: Ограничение строк в файле
        entry: python -c "import sys; sys.exit(0 if max([len(open(f).readlines()) for f in sys.argv[1:]]) <= 600 else 1)"
        language: system
        types: [python]
      
      - id: cyclomatic-complexity
        name: Лимит цикломатической сложности
        entry: flake8 --max-complexity=10 --filename=*.py
        language: system
        types: [python]

Откуда такие лимиты?

• 600 строк на файл — жёстко против дампов, но терпимо для сложных модулей.
• Сложность McCabe до 10 — функции остаются читаемыми и тестовыми.

Если агент нарушает — хук валит коммит. Код не уходит в репозиторий, пока не переписан.

Инструменты, которые агенты обязаны освоить

Чтобы проходить проверки, агентам нужны суперсилы по рефакторингу:

Для Python: rope — мастер автоматизации. Разбивает файлы, выносит функции, переименовывает переменные.

Для TypeScript/JS: ts-morph — работает с AST, позволяет агентам сами улучшать архитектуру.

Это не ручной труд — агенты вызывают их в коде и самоисправляются.

Конституция для агентов: правила в одном файле

Создайте AGENTS.md в корне репо — это их инструкция:

# Правила для ИИ-агентов

## Коммиты
- Делайте осмысленные коммиты по частям, без гигантских дампов
- Указывайте тикет и объясняйте "зачем": "feat(login): Ротация OAuth токенов [#123]"

## Установка хуков
- Запускайте `git config core.hooksPath .husky` (или аналог для pre-commit)
- Тестируйте локально перед пушем

## Главное табу
- **Никогда не юзайте `--no-verify` без явного ок от юзера**
- Это отключает все проверки — пишите, зачем оно нужно

## Подход к коду
- TDD: тест сначала (red), зелёный, рефакторинг
- Так архитектура выходит чистой сама собой

Это не диктатура, а чёткие ожидания. Агенты с ними работают лучше.

Зачем это нужно команде

Разрабы уже устали от техдолга. С хуками:

✅ Доверие к main — код приходит проверенным
✅ Лёгкие ревью — фокус на логике, а не на стиле
✅ Простой онбординг — новички видят стандарты сразу
✅ Агенты эволюционируют — учатся генерить качественный код

Чеклист по внедрению

1. Выберите фреймворк — pre-commit для Python, husky для JS (или оба)
2. Задайте лимиты — 600 строк и complexity 10 как база, подстройте под проект
3. Добавьте рефакторинг — rope или ts-morph в арсенал агента
4. Документируйте — AGENTS.md с объяснениями
5. Вводите поэтапно — сначала варнинги, потом блочеры
6. Следите — логи фейлов хуков покажут, куда подкрутить

Главный инсайт

Это не про блокировку плохого кода. Это про среду, где хороший код — самый простой путь.

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

В NameOcean мы фанатеем от масштабируемой инфраструктуры — от domain до хостинга и dev-процессов. Codebase требует той же дисциплины, что и серверы. Начните с Git hooks. Будете благодарны себе позже.