Джеффри Хантли чинит кодинг-агентов pre-commit хуком и получает 10 из 10

Джеффри Хантли описал приём, который, по его словам, довёл соблюдение агентом внутреннего правила до «десяти из десяти». Он не стал уговаривать модель очередной строчкой в инструкциях, а поставил на пути коммита pre-commit хук. Цитату из его эссе «nobody should type code by hand anymore. here's what's left» опубликовал Саймон Уиллисон. Метрика здесь субъективная: методики измерения автор не приводит. Но сама механика заслуживает разбора.

Где ломается AGENTS.md

Ситуация знакомая каждому, кто работал с кодинг-агентами. В проекте есть собственная библиотека диагностики, обёртка над наблюдаемостью. Агент вместо неё вызывает модули observability напрямую. Очевидный ход — дописать правило в AGENTS.md и надеяться, что модель его учтёт.

Хантли объясняет, почему этого мало. Можно заставить агента проанализировать собственное поведение и обновить файл, но между инструкцией и реальной практикой всё равно остаётся разрыв («delta»), и он будет дрейфовать. Текстовые правила вероятностны: контекст разрастается, формулировки конкурируют между собой, сменилась модель или версия. Файл с инструкциями остаётся пожеланием.

Как устроен хук

Хантли переносит правило из текста в код. Схема короткая:

• Триггер: попытка сделать git commit.
• Проверка: скрипт читает git diff и ищет прямые вызовы модулей observability, которые обходят diagnostics-модуль.
• Реакция: при совпадении коммит падает.
• Обратная связь: в агента инжектится промпт с требованием использовать diagnostics library.
• Результат по оценке автора: десять из десяти.

Важна последняя связка. Отказ коммита без пояснений агент мог бы обойти случайным способом. Здесь же сообщение об ошибке одновременно говорит, что именно не так, и что делать. Агент получает исправление в момент, когда оно ему нужно, а не в начале сессии среди сотен строк контекста.

Проверка при этом детерминирована. Она не зависит от того, что модель «помнит» из AGENTS.md, и работает одинаково на любой модели и в любом агентном инструменте, который делает коммиты через git.

Как применить у себя

Вывод из подхода Хантли инженерный. Правила для агентов делятся на две группы: те, что можно проверить механически, и те, что нельзя. Первые стоит переносить в хуки, линтеры и CI. Вторые, например архитектурный вкус или нюансы предметной области, остаются в AGENTS.md.

Кандидаты на перенос видны сразу: запрет прямых вызовов в обход внутренней обёртки, обязательный логгер, единый способ работы с конфигами, запрещённые зависимости. Если нарушение находится регулярным выражением или разбором diff, оно не должно жить в текстовой инструкции.

Несколько оговорок, которые стоит учесть самому (это мои соображения, в цитате их нет):

• Текст ошибки пишите как промпт: что найдено, почему нельзя, чем заменить.
• Локальный хук можно обойти флагом --no-verify, поэтому ту же проверку разумно продублировать в CI.
• Следите за ложными срабатываниями: если хук блокирует легитимные коммиты, агент начнёт «лечить» код вокруг проверки, а не по существу.
• Ведите счётчик срабатываний. Он покажет, какие правила агент нарушает чаще всего, и заодно даст ту метрику, которой не хватает оценке «10/10».

Теги записи у Уиллисона, agentic-engineering и coding-agents, точно описывают направление. Инженерия вокруг агента, то есть хуки, проверки и обратная связь, начинает значить не меньше, чем подбор модели.