Что такое AGENTS.md — файл, который ИИ-агент читает без твоей просьбы

Знакомая сцена: ты в третий раз объясняешь агенту, что тут pnpm, а не npm. Он снова предложил npm install. Ты снова поправил. Завтра новая сессия — и всё сначала.

Это чинится одним файлом. Он называется AGENTS.md.

И хитрая штука в нём вот какая: агент читает его сам, ещё до того как ты что-то попросил. Ты не прикладываешь файл к запросу — он там уже есть. Это не документация, которую когда-нибудь откроют. Это часть каждого твоего промпта.

AGENTS.md — это README, но для роботов

Обычный README.md пишут для людей: что за проект, как установить, как помочь.

AGENTS.md — то же самое место, только для ИИ-агентов. Туда кладут скучные технические детали, которые человеку в README не нужны, а агенту критичны: какой командой собрать, чем запустить тесты, какой стиль кода, куда не лезть.

Формат — просто Markdown. Никакой схемы, никаких обязательных полей, ничего не сломается от лишнего заголовка. Обычные списки, как в заметке.

Файл кладут в корень репозитория. Дальше агент находит его сам.

Почему один файл, а не пять

Пару лет назад каждый инструмент завёл свой формат. Codex читал AGENTS.md, Claude Code — CLAUDE.md, Gemini CLI — GEMINI.md, Cursor — правила в отдельной папке.

Итог был смешной: в репозитории лежали три файла с одинаковым текстом. Или симлинки друг на друга. Или человек сдавался, оставлял один — и остальные агенты работали вслепую.

AGENTS.md выиграл как общий знаменатель. Это открытый формат без хозяина: его курирует Agentic AI Foundation при Linux Foundation, его читают больше двадцати инструментов — Codex, Cursor, Copilot, Aider, Zed, Jules — и он лежит уже более чем в 60 000 открытых репозиториев.

Последним присоединился Claude Code: 18 сентября 2026, версия 2.1.277. Правило простое — если в папке нет CLAUDE.md, Claude Code читает AGENTS.md. Свой формат остаётся в приоритете, но общий файл больше не игнорируется.

Что реально класть внутрь

Главная ошибка новичка — вывалить туда всю документацию проекта. Так делать нельзя, и вот почему: этот файл подмешивается в каждый запрос и занимает место в контекстном окне. Чем он длиннее, тем дороже сессия и тем сильнее размывается главное.

Работает вот что:

• Команды — буквально. Не «запустите тесты», а pnpm test. Не «соберите проект», а pnpm build. Агент такую строку выполнит, а не перескажет своими словами.
• Стек и версии. «Next.js 16, pnpm, TypeScript strict». Без этого он угадает по привычке — и угадает мимо, потому что в интернете больше примеров на npm.
• Границы. «Папку legacy/ не трогай», «в main напрямую не пушить». Запреты дают самый большой эффект: это ровно то, чего агент не может узнать из кода.
• Соглашения. Стиль коммитов, язык комментариев, куда класть новые файлы.

А чего класть не надо: описание продукта, историю команды, рассуждения об архитектуре. Это для людей — это в README.

Держись в пределах страницы-двух. Если не влезает — у формата есть вложенность: положи отдельный AGENTS.md в подпапку монорепозитория, и агент возьмёт тот, что ближе к файлу, над которым работает.

Как проверить, что он вообще читается

Проверка на тридцать секунд, без всякой магии.

Открой новую сессию и спроси агента: «какой командой тут запускаются тесты?» — не подсказывая ответ. Если он назвал ровно твою команду из файла — значит прочитал. Если предложил npm test наугад — файл не подхватился.

Тогда проверь три вещи: имя ровно AGENTS.md (регистр важен), файл лежит в корне проекта, и агент запущен из этой же папки.

Дальше — просто дописывай файл каждый раз, когда ловишь себя на повторном объяснении. Поправил агента дважды — значит, строчке место в AGENTS.md. Это те же двадцать минут, что ты уже тратишь на объяснения, только вложенные один раз. Подробнее про весь подход — в гайде о том, как дать ИИ контекст о твоём коде.

Чем AGENTS.md отличается от README?

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

У меня уже есть CLAUDE.md — его удалять?

Нет. Claude Code читает CLAUDE.md в первую очередь и берёт AGENTS.md, только если своего файла нет. Если работаешь несколькими агентами — держи общие правила в AGENTS.md, а специфичное для Claude оставь в CLAUDE.md.

Агент точно будет слушаться?

Не всегда. Это инструкции, а не настройки: модель может их проигнорировать — особенно если файл длинный и сам себе противоречит. Поэтому короче и конкретнее. Пять чётких правил работают лучше трёх страниц пожеланий.