В свежем рисёрч пейпере о пользе/вреде AGENTS.md утверждают интересную вещь: файлы, которые вы генерите для своих репозиториев, чтобы помогать агентам в них ориентироваться – на самом деле делают только хуже.

Некоторые факты из статьи:

• AGENTS.md файлы, сгенерированные с помощью /init, в среднем понижают success rate на 3%
• Если вы будете дотошно писать AGENTS.md вручную, то получится добиться улучшения в 4%
• Все контекстные файлы повышают стоимость ваших запросов на 20%, так как агенту приходится делать больше шагов
• Навигация по вашей кодовой базе, которую вы всегда включаете в свой AGENTS.md как собаке пятая нога. Агент и так неплохо ориентируется, используя cat, ls, grep и другие bash тулы, навигационные секции ему не помогают

Кстати, про похожую проблему с контекст-bloat я уже 👉 писал тут, когда разбирал косяки MCP серверов – декларация всех тулов в контексте создаёт такой же мусор, который не помогает модели.

С появлением SKILLs в современных кодинг агентах пропагандирую максимально минималистичный AGENTS.md. Лучше ссылаться из него на определённые скилы и документацию, чем пихать всё в одно место.

Кстати, в SkillsBench показали, что Claude Code с правильными скилами улучшает success rate на 23% – это в 5+ раз больше, чем улучшение от самого дотошного ручного AGENTS.md. Писать чонить про скилы?

Context engineering я уже затрагивал 👉 тут.

Ну а теперь, когда чары псиопа спали, я начну пользоваться контекстными файлами так, как мне всегда казалось интуитивным.

Например, я замечаю, что агент напрямую вносит изменения в файл pyproject.toml и добавляет какую-то непонятную версию библиотеки, которая устарела пару лет назад, и делает он это на постоянке, а это значит, нужно внести новое правило в AGENTS.md:

для добавления новых библиотек и изменения версий существующих зависимостей всегда используй uv package manager, никогда не модифицируй pyproject.toml напрямую

Таким образом, контекстный файл стоит расширять лишь теми вещами, которые агент конзистентно забывает и мисинтерпретирует.

Короче, давайте переставать использовать /init, он всё усугубляет.

К посту прикрепляю префикс к вашему апдейтнутому CLAUDE.md/AGENTS.md/rules файлу, разбирайте. С сегодняшнего дня использую его на всех своих проектах.

Пост переслать, сообщение лайкнуть, Соколовскому насыпать корма, чтобы ещё чонить писал.