Git pre-commit hook предотвращает фиксацию изменений AI-агентами программирования с устаревшей документацией.

Проблема: AI-агенты для написания кода коммитят код с устаревшей документацией

При работе с AI-ассистентами для написания кода, такими как Claude Code, в течение нескольких сессий разработчики сталкиваются с конкретной проблемой: ИИ вносит изменения в код (добавляет маршруты, рефакторит компоненты, переименовывает элементы), но не обновляет файлы документации, такие как ARCHITECTURE.md и README. Это приводит к тому, что последующие сессии начинаются с того, что ИИ читает документацию, описывающую код недельной давности.

Последствия включают:

• Claude галлюцинирует имена функций, которых больше не существует
• Ссылается на API-эндпоинты, которые были переименованы
• Предлагает паттерны, противоречащие текущей архитектуре

Предупреждения не работают, потому что когда Claude делает коммит, никто не видит вывод stderr.

Решение: Блокирующий pre-commit hook

Разработчик создал Git pre-commit hook со следующим рабочим процессом:

• Хук знает, какие изменения файлов должны запускать обновление документации (настраиваемые паттерны для каждого проекта)
• Когда Claude Code делает коммит, хук обнаруживает это через переменные окружения
• Хук пропускает попытки автоматически исправить документацию (что вызвало бы взаимную блокировку из-за запуска Claude внутри Claude)
• Вместо этого он завершает работу с кодом 1 и выводит понятное сообщение: "документация устарела, обновите эти файлы, затем повторите попытку"
• Claude читает ошибку, обновляет документацию, повторяет коммит, и коммит проходит

Для коммитов, сделанных человеком, хук напрямую вызывает API Anthropic и исправляет соответствующие разделы (занимает примерно 20 секунд).

Каждый коммит генерирует файл session-context.md с кратким описанием недавней активности, чтобы следующая сессия имела преемственность.

Детали реализации

Инструмент доступен как npm-пакет: @mossrussell/agent-guard

Ключевые характеристики:

• Работает с Claude Code, Cursor, Windsurf и Copilot
• Нет зависимостей
• Доступен по адресу: https://www.npmjs.com/package/@mossrussell/agent-guard