Что сюда класть, а что нет - главный вопрос. В AGENTS.md кладут только универсальное и устойчивое: команды, жёсткие границы, критерии готовности. Длинную процедуру на десятки шагов выносят в skill, который подгружается по требованию, а не висит всегда; документация Devin прямо советует предпочитать skills правилам там, где это возможно, потому что навык попадает в контекст лишь когда релевантен. Хороший тест на место строки простой: если она описывает шаг за шагом, как что-то делать, это материал для навыка; если она задаёт неизменную рамку - команду, запрет, критерий, - её место в контракте.

Цена раздутого контракта не абстрактна. Каждая лишняя строка - это токены в каждом turn и отвлечённое внимание там, где нужен ответ на текущую задачу. Противоречие между файлом и реальным кодом уводит агента по ложному следу. И отдельно: AGENTS.md коммитится, поэтому секретам, ключам и токенам здесь не место - для них есть tracked config и переменные окружения, но не общий контракт.

Как выглядит рабочий минимум, проще показать, чем описать. Три коротких раздела - команды, границы, правила завершения - помещаются на один экран и покрывают большинство повторяющихся вопросов агента.

Проверять такой контракт нужно с одной оговоркой: правило направляет, но не принуждает. Фраза "не запускай deploy" в Markdown - полезная подсказка, но не граница безопасности; её честно исполнит только тот агент, который решил её исполнить. Настоящую границу создаёт permission deny, sandbox или hook с блокирующим исходом. Поэтому критичные строки контракта дублируют жёстким механизмом, а работу файла проверяют по факту: следует ли агент командам из Commands и останавливается ли на границах из Boundaries. Раздел Completion проверяют так же буквально: агент обязан показать соответствующий diff, назвать точные команды проверки и их исход и не объявлять готовность при пропущенных проверках.

Типичные провалы сводятся к трём. AGENTS.md превращают в свалку документации - и он раздувается, устаревает и перестаёт читаться. В него кладут изменчивое или секретное - и получают либо утечку, либо ложь в контексте. На него полагаются как на защиту - и удивляются, что Markdown никого не остановил. Признак один: файл растёт, а доверия к нему всё меньше. Держите контракт коротким, изменчивое уводите в skills, а критичное подкрепляйте permission - тогда AGENTS.md остаётся тем, чем должен быть: коротким постоянным контрактом, а не длинной инструкцией, которую никто не соблюдает.