Почему это не очевидно
Инстинктивный порядок работ обратный: «у нас так принято — опишу в AGENTS.md, и агент будет делать как надо». Он не срабатывает по причине, которая видна только в масштабе: инструкция — самое слабое из средств починки, действующее лишь пока её читают, и вдобавок занимающее место в контексте при каждом запуске (Harness Optimization — лестница средств по надёжности, где запись в файле инструкций стоит посередине и выбирается неправильно чаще всего).
Смена конвенции переносит то же требование на ступень выше: оно перестаёт быть текстом, который надо прочитать и вспомнить, и становится свойством проекта, которое модель распознаёт без подсказки. Разница не в качестве текста, а в том, что принуждает.
Критерий выбора конвенции — след в обучении, а не качество
Практическое правило формулируется неприятно, и в этом его ценность: выбирается не лучшая конвенция, а та, у которой больше след в обучающих данных. Старая, широко распространённая и давно стабильная побеждает молодую и лучшую — потому что модель работает с первой изнутри, а вторую придётся объяснять на каждом заходе.
Наблюдавшиеся случаи, все одного вида:
- универсальный раннер команд с двадцатилетней историей вместо нового и более удобного: модель понимает такой файл целиком, выводит из него, как проект собирается, тестируется и запускается, и часть содержимого
AGENTS.mdпосле этого просто не нужна; - классический тестовый фреймворк вместо собственной надстройки над ним: замена своей предметной обёртки на общепринятый способ записи тестов заметно улучшила результат при неизменном всём остальном;
- типизированный язык вместо динамического — не только ради типов как таковых, но и потому, что вместе с ними в проекте появляется способ проверки, которую агент запускает сам;
- общепринятая раскладка каталогов вместо своей, даже если своя стройнее.
Побочный эффект стоит назвать отдельно: каждая такая замена сокращает файл инструкций, а не дополняет его. Это ровно тот обратный ход, которого ратчету обычно не хватает (Agent First Repository).
Где приём не работает
Границ три, и каждая своя.
Требование сильнее удобства. Если общепринятая конвенция противоречит требованию безопасности, регуляторному ограничению или устройству предметной области, менять нечего — остаётся инструкция, а лучше проверка. Правило действует там, где своя конвенция лучше незначительно; когда она лучше принципиально, вопрос перестаёт быть про экономию контекста.
Приём консервативен по построению. Он систематически выбирает вчерашнее и тем самым закрепляет мейнстрим: новая библиотека, объективно лучшая, проигрывает старой ровно потому, что новая. Цена реальная, и платить её осознанно — часть решения, а не побочный ущерб. Смягчается тем, что след в обучающих данных пополняется: сегодняшний проигрыш временный, но горизонт измеряется версиями моделей, а не неделями.
Знание модели о конвенции датировано. Она знает состояние на момент обучения, поэтому версия, которую подставит по умолчанию, обычно на шаг позади текущей. Лечится не инструкцией «используй свежее», а явной фиксацией версий там, где она видна: в манифесте зависимостей и в файле инструкций рядом с именем библиотеки. Иначе поправлять придётся в каждой сессии.
Проверка, что проект действительно подстроен
Признак готовности наблюдаемый и дешёвый: спросить агента в режиме планирования, чем он проверит собственные шаги.
У подготовленного проекта ответ — перечень из нескольких конкретных проверок: прогон тестов целиком и точечно, линтер, проверка типов, интеграционный набор, запуск в браузере, чтение журналов. Ответ вида «я всё сделаю, а ты посмотри» означает не лень модели, а что в проекте нечем проверить результат — и тогда любые инструкции вторичны, потому что цикл починки не замкнут.
Тот же вопрос полезен как периодическая интроспекция: агента спрашивают не «сделай фичу», а «как ты понимаешь этот проект и как его проверяешь», и расхождение между ответом и реальностью показывает, что подстраивать дальше.
Связано с
- Agent First Repository — среда вокруг агента целиком; здесь один её приём, работающий против роста файла инструкций
- Harness Optimization — почему запись в файле инструкций слабее проверки, и планка, отсеивающая лишние правки
- Context Layers — что вообще стоит держать в контексте; конвенция уходит из него совсем
- Prompt Engineering — противоположный подход: добиваться поведения текстом, а не устройством проекта
- Parallel Agent Dispatch — снижение переделок как измеримая цель, ради которой это и делается