У AGENTS.md есть неприятное свойство - его легко раздуть.
Сначала туда попадают правила работы с проектом. Потом команды запуска, описание архитектуры, история решений и другие детали. В какой-то момент AGENTS.md превращается в ещё один README.
Я стараюсь этого избегать.
У файла должна быть одна задача
Я не считаю строки и не придерживаюсь жёсткого ограничения по размеру. Такого стандарта пока нет.
Для меня важнее другое. AGENTS.md должен отвечать только на один вопрос:
Как работать с этим проектом?
Если информация не помогает ответить на этот вопрос, ей, скорее всего, место в другом документе.
Каждый документ хранит свой контекст
В проекте уже есть файлы, отвечающие за разные задачи.
README объясняет, что это за проект.
ADR фиксируют причины архитектурных решений.
CHANGELOG показывает историю изменений.
Документация описывает детали реализации.
AGENTS.md не должен заменять их все. Его задача - хранить краткий рабочий контекст проекта.
Что стоит оставить
Обычно в AGENTS.md достаточно хранить:
- стек
- структуру репозитория
- инженерные соглашения
- ограничения
- правила работы с документацией
- стиль написания текстов
Этой информации достаточно, чтобы AI понял, как устроен проект.
И её достаточно, чтобы самому быстро восстановить контекст спустя несколько месяцев.
Что стоит убрать
Я стараюсь не хранить в AGENTS.md:
- историю проекта
- changelog
- подробное описание архитектуры
- список всех команд
- детали API
- информацию, которая уже есть в документации
Если текст можно удалить без потери смысла, его лучше удалить.
Хороший ориентир
Я не измеряю размер файла в строках.
Но если AGENTS.md уже нельзя спокойно прочитать за одну-две минуты, он, скорее всего, стал слишком большим.
Это не правило. Скорее индикатор того, что файл начинает брать на себя чужие задачи.
Вывод
Хороший AGENTS.md редко бывает длинным.
Не потому, что длинные файлы плохие.
А потому, что каждый документ должен отвечать только за один вид контекста.
README рассказывает, что это за проект.
ADR объясняют, почему приняты те или иные решения.
AGENTS.md помогает понять, как с этим проектом работать.
Когда каждый документ выполняет только свою задачу, поддерживать их становится значительно проще.