Как не превратить AGENTS.md в свалку

AGENTS.md – удобная штука, чтобы задать агенту контекст о проекте. Но сам по себе файл еще не делает работу с агентом лучше.

На практике я часто вижу такие проблемы:
– умная машина сгенерила большой файл, а нужно ли все это добро – непонятно. Часто это просто булшит на все случаи жизни
– файл не обновляется. Открываешь проект, а там напротив AGENTS.md updated 5 months ago, старые пути и уже неактуальные решения. Вспомните, когда вы пытались изучать неактуальную доку, какие были ощущения, а агента это вообще может уводить не туда
– каждый понемногу дописывает свои правила, что-то дублируется, что-то друг другу противоречит

Примерно о том же пишет Мэтт Покок. Советы довольно банальные и понятные, но мало кто им реально следует:
– не генерить AGENTS.md автоматически
– держать корневой AGENTS.md минималистичным, только факты, никакой воды
– не фиксировать структуру файлов в проекте – она быстро устаревает. Лучше дать агенту более стабильные ориентиры: что делает система и за что отвечают ее части
– использовать progressive disclosure: правила для TypeScript, тестов, API и других отдельных областей вынести в свои документы, а из AGENTS.md только ссылаться на них
– в монорепе раскладывать контекст по уровням: в корне оставить общие правила, а детали конкретного пакета положить в его собственный AGENTS.md
– регулярно вычищать противоречивые, дублирующиеся, слишком общие и очевидные инструкции вроде "пиши чистый код" или "пиши как опытный разработчик". Для такой ревизии Мэтт даже дает готовый промпт: найти противоречия, оставить в корневом файле только необходимое, разнести остальные правила по тематическим документам, а лишнее пометить на удаление

Короче, нужно бдеть и не давать всякой фигне прорастать в AGENTS.md

#ai