Forward from: Pavel Zloi
Вокруг AGENTS.md и всяких "универсальных" файлов для агентов в последнее время как-то слишком много разговоров. Особенно забавно это выглядит на фоне того, что рядом уже начали появляться вполне трезвые наблюдения о том, что польза таких файлов слегка преувеличена.
Например, у @gonzo_ML был хороший разбор статьи Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? (arxiv:2602.11988). Если совсем кратко, то вывод там неприятный, но логичный - автоматически сгенерированные контекстные файлы на уровне репозитория часто не помогают, а скорее мешают. Они снижают долю успешно решённых задач и одновременно увеличивают стоимость инференса. Модель вместо решения задачи уходит в блуждание по кодовой базе и бесконечное "изучение архитектуры", порождая галюнчики.
Из свеженького, что меня побудило написать этот пост:
- в мой любимый KodaCode добавили поддержку SKILLS.md, и AGENTS.md
- @max_about_ai была здравая мысль про документацию в эпоху AI
- а у @countwithsasha был пост про то, как вообще собирать агента из скиллов
То есть с моей точки зрения рынок постепенно обрастает всем этим зоопарком форматов, манифестов и "магических" markdown-файлов.
Проблема не в том, что агенту не нужен контекст (без контекста, увы, никак). Проблема в том, что люди пытаются запихнуть в один файл вообще всё подряд - архитектуру, команды запуска, ограничения, стили кодинга, особенности тестирования, бизнес-логику, карту директорий, описание CI, правила коммитов, правила работы с миграциями, требования к безопасности и ещё сверху тысячу строк "полезных пояснений". В итоге на каждом запросе в контекст летят тысячи, а на сложных проектах и десятки тысяч токенов текста, большая часть из которых в конкретный момент просто не нужна.
И вот тут у меня каждый раз возникает простой вопрос - а кому вообще выгодна эта мода на огромные универсальные AGENTS.md? Разработчику точно нет. Агенту тоже не особо. Зато очень выгодно вендору, который продаёт доступ к моделям по API. Чем больше токенов вы стабильно прокидываете в каждый запрос, тем больше вы тратите токенов, тем больше зарабатывает вендор.
Поэтому на мой взгляд куда более практичный путь давно уже показал Cursor со своими Cursor Rules. Не потому что это какой-то идеальный формат, а потому что там хотя бы немного подумали над логикой динамического наполнения контекста в процессе работы кодового агента.
В Cursor правила можно дробить на небольшие, специализированные и адресные кусочки. Какие-то применять всегда, какие-то только по glob-маскам, какие-то подключать вручную, какие-то держать на уровне монорепы, а какие-то внутри конкретного подпроекта. То есть вместо одного аморфного AGENTS.md вы получаете управляемую систему контекста с дюжиной небольших файлов, из которых подтягивается только то, что действительно относится к текущему файлу, текущей задаче или текущему этапу работы.
Чуть более подробно почитать про Cursor Rules можете тут, там я рассказываю как раскладывать правила по .cursor/rules/, как ссылаться из них на документацию и почему такой формат удобнее в реальных проектах, а вот тут ещё один пост, где я показывал как использовать правила, документацию и TDD/BDD-подход в связке с агентом.
Подытожу, документация агентам нужна, правила нужны, скиллы нужны, но всё это должно быть модульным, иначе вместо управляемого контекста вы просто сжигаете токены.
Например, у @gonzo_ML был хороший разбор статьи Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? (arxiv:2602.11988). Если совсем кратко, то вывод там неприятный, но логичный - автоматически сгенерированные контекстные файлы на уровне репозитория часто не помогают, а скорее мешают. Они снижают долю успешно решённых задач и одновременно увеличивают стоимость инференса. Модель вместо решения задачи уходит в блуждание по кодовой базе и бесконечное "изучение архитектуры", порождая галюнчики.
Из свеженького, что меня побудило написать этот пост:
- в мой любимый KodaCode добавили поддержку SKILLS.md, и AGENTS.md
- @max_about_ai была здравая мысль про документацию в эпоху AI
- а у @countwithsasha был пост про то, как вообще собирать агента из скиллов
То есть с моей точки зрения рынок постепенно обрастает всем этим зоопарком форматов, манифестов и "магических" markdown-файлов.
Но лично мне вся эта практика с одним условным большим `AGENTS.md` на 10к токенов кажется порочной.
Проблема не в том, что агенту не нужен контекст (без контекста, увы, никак). Проблема в том, что люди пытаются запихнуть в один файл вообще всё подряд - архитектуру, команды запуска, ограничения, стили кодинга, особенности тестирования, бизнес-логику, карту директорий, описание CI, правила коммитов, правила работы с миграциями, требования к безопасности и ещё сверху тысячу строк "полезных пояснений". В итоге на каждом запросе в контекст летят тысячи, а на сложных проектах и десятки тысяч токенов текста, большая часть из которых в конкретный момент просто не нужна.
И вот тут у меня каждый раз возникает простой вопрос - а кому вообще выгодна эта мода на огромные универсальные AGENTS.md? Разработчику точно нет. Агенту тоже не особо. Зато очень выгодно вендору, который продаёт доступ к моделям по API. Чем больше токенов вы стабильно прокидываете в каждый запрос, тем больше вы тратите токенов, тем больше зарабатывает вендор.
Поэтому на мой взгляд куда более практичный путь давно уже показал Cursor со своими Cursor Rules. Не потому что это какой-то идеальный формат, а потому что там хотя бы немного подумали над логикой динамического наполнения контекста в процессе работы кодового агента.
В Cursor правила можно дробить на небольшие, специализированные и адресные кусочки. Какие-то применять всегда, какие-то только по glob-маскам, какие-то подключать вручную, какие-то держать на уровне монорепы, а какие-то внутри конкретного подпроекта. То есть вместо одного аморфного AGENTS.md вы получаете управляемую систему контекста с дюжиной небольших файлов, из которых подтягивается только то, что действительно относится к текущему файлу, текущей задаче или текущему этапу работы.
Не "один файл, в котором описана вся подноготная проекта", а "набор маленьких правил, каждое из которых отвечает за свою область".
Чуть более подробно почитать про Cursor Rules можете тут, там я рассказываю как раскладывать правила по .cursor/rules/, как ссылаться из них на документацию и почему такой формат удобнее в реальных проектах, а вот тут ещё один пост, где я показывал как использовать правила, документацию и TDD/BDD-подход в связке с агентом.
Подытожу, документация агентам нужна, правила нужны, скиллы нужны, но всё это должно быть модульным, иначе вместо управляемого контекста вы просто сжигаете токены.