Правило агент прочитает.Ошибку покажетпроверка.

Руководство по стилю кода когда-то было почти в каждой команде. Страница в вики: какие кавычки, где переносить строку, как называть файлы. Новичку давали на неё ссылку, а дальше её вспоминали в основном на ревью, когда спорили о кавычках. Споры стихли там, где стиль начал проверять инструмент. Prettier в справке так и называет себя: единственное руководство по стилю, которое работает полностью автоматически. Там же один из пользователей пишет, что хук на коммит сократил число замечаний по стилю в пулл-реквестах (Prettier).

С ИИ-агентами, по-моему, мы пишем такую страницу заново. Агент сделал не так, и в AGENTS.md или CLAUDE.md появляется строка: логи только через нашу обёртку, тесты запускать вот этой командой, папку legacy не трогать. Строка помогает?

Агент её как раз слушается. В исследовании Высшей технической школы Цюриха (ETH Zurich) и компании LogicStar агенты в целом выполняли то, что написано в таком файле. Если в нём упомянут менеджер пакетов uv, агент вызывал его в среднем 1,6 раза на задачу, без упоминания — почти никогда. А решались задачи почти так же, как без файла. Файлы, которые написала модель, снизили долю решённых задач примерно на 3%, а написанные людьми подняли примерно на 4%. А обходилась работа в среднем на 20% с лишним дороже: агент больше читал, больше искал и чаще гонял тесты (arXiv). Авторы советуют писать в файл только минимальные требования.

Джеффри Хантли 13 октября описал, что делает вместо очередной строки. Агент обходил его библиотеку диагностики. Можно было дописать AGENTS.md, но расхождение, по его словам, останется и со временем поплывёт. Он написал хук, который запускается перед коммитом (pre-commit hook). Хук ищет в изменениях прямые вызовы модулей наблюдаемости в обход библиотеки, роняет коммит и подсовывает агенту подсказку, чем пользоваться. После этого, пишет Хантли, стало десять из десяти.

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

А файл агент прочитал в начале сессии, и в длинной сессии про него легко забыть. На Хабре это сформулировали коротко: «Правило — пожелание. Hook — гарантия» (Хабр). Тем более что к пятой задаче агент читает проект хуже, чем к первой.

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

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

В следующий раз, когда агент сделал не так и хочется дописать строку в AGENTS.md, я бы сначала спросил: может ли это поймать скрипт? Запрещённый импорт, вызов в обход обёртки, файл не в той папке, тесты не той командой — может. Тогда пишите проверку, а в её сообщение об ошибке — то, что собирались написать в файл: что сделать вместо этого. Не может — вот тогда строка в файл.