AGENTS.md: один файл контекста для любого агента-кодера (Codex, Antigravity, Claude)

Ты потратил полдня, чтобы написать аккуратный CLAUDE.md. Агент наконец перестал гадать про твой стек и начал запускать правильную команду тестов. А потом коллега открывает тот же репозиторий в Codex, ты пробуешь Antigravity CLI на отдельной ветке, и весь этот с таким трудом собранный контекст никуда не переносится. Каждому инструменту подавай свой файл, в своём месте.

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

Что такое AGENTS.md на самом деле

Никакой магии. Это Markdown-файл с именем AGENTS.md, обычно в корне репозитория, который агент загружает как постоянные инструкции перед началом работы. Считай его README, который ты пишешь для своих ИИ-коллег, а не для людей: что это за проект, как его собирать и тестировать, какие соглашения соблюдать и каких ловушек избегать.

Это открытое соглашение, которое уже читают Codex и растущий список агентских инструментов, и придумано оно специально, чтобы быть переносимым между ними. Один файл, много агентов, вместо отдельного файла под каждый инструмент.

AGENTS.md vs CLAUDE.md vs GEMINI.md

Когда этот гайд писался впервые, каждый инструмент искал свой собственный файл. С тех пор большинство из них сошлись на AGENTS.md:

• Codex читает AGENTS.md, как и GitHub Copilot CLI, Cursor, Amp и большинство новых агентских CLI.
• Claude Code читает CLAUDE.md, а начиная с версии 2.1.277 сам читает и AGENTS.md, если в твоей рабочей папке и папках выше нет ни CLAUDE.md, ни CLAUDE.local.md. Когда CLAUDE.md существует, Claude читает только его, если только ты не изменишь настройку Project instructions в /config.
• Antigravity CLI читает AGENTS.md или GEMINI.md, в корне репозитория или в любой подпапке, плюс папку .agents/rules/ и глобальные правила в ~/.gemini/.

Содержимое во всех трёх почти одинаковое: контекст проекта, команды, соглашения. Различается до сих пор другое: какой файл инструмент выбирает, когда находит несколько. Именно поэтому вручную дублировать одни и те же правила в трёх файлах: заведомо проигрышная затея (как держать их синхронными, разберём ниже). Мы проверили это поведение 10 октября 2026 года по документации Claude Code о памяти и по документации Antigravity о правилах.

Если ты работаешь в основном в Claude Code, наш гайд по CLAUDE.md подробно разбирает структуру, специфичную для Claude. AGENTS.md: это нейтральный, независимый от провайдера родственник того файла.

Что в него класть

Держи его коротким и плотным по смыслу. Агент читает этот файл при каждой задаче, поэтому каждая строка борется за внимание. Самое важное:

• Стек, в одном дыхании. "Next.js 16, TypeScript, Prisma, MariaDB." Без истории, без маркетинга.
• Команды, которые важны. Как установить, запустить, собрать, протестировать и прогнать линтер. Точные команды: npm test, а не "запусти тесты."
• Соглашения. Именование, раскладка файлов, обработка ошибок, паттерны, которые ты реально требуешь на ревью.
• Карта каталогов. Две строчки о том, где что лежит, чтобы агент перестал грепать вслепую.
• Правила "прочитай, прежде чем трогать". "Прочитай docs/payments.md, прежде чем менять что-либо под billing/." Одна эта привычка предотвращает кучу бед.
• Жёсткие запреты. "Никогда не создавай ветку без запроса." "Никаких абсолютных машинных путей в закоммиченных файлах."

Ошибки, из-за которых агенты игнорируют файл

Файл контекста проваливается тихо. Агент не выдаёт ошибку, он просто уплывает в сторону. Обычные причины:

1. Слишком длинный. Файл на 600 строк хоронит пять правил, которые действительно важны. Вырежи всё, что агент может вывести из самого кода.
2. Противоречия. "Всегда пиши тесты" в одной секции, "пропускай тесты для прототипов" в другой. Агент выбирает одно наугад.
3. Машинно-зависимые пути. /Users/you/project/... в закоммиченном файле ломается у каждого коллеги и у каждого агента на любой другой машине. Держи пути относительными.
4. Устаревшие команды. Команда тестов поменялась полгода назад, а файл нет. Теперь агент с полной уверенностью запускает не то.
5. Никаких приоритетов. Всё "важно", а значит, не важно ничего. Поставь то, что не обсуждается, в начало и отметь это.
6. Свалка документации. Это инструкции, а не вики. Дай ссылки на свою документацию, не вклеивай её внутрь.

Как держать единый контекст между провайдерами

Вот та практическая часть, которую большинство гайдов пропускает. Если ты или твоя команда запускаете больше одного агентского CLI, тебе не нужны три расходящиеся копии одних и тех же правил.

Два чистых подхода:

• Один AGENTS.md, и больше ничего. Если никому не нужны правила только для Claude, держи один AGENTS.md: его читают и Codex, и Antigravity CLI, и Claude Code 2.1.277 и новее. Подвох незаметный: CLAUDE.md или личный CLAUDE.local.md, добавленный позже, заставляет Claude Code перестать читать AGENTS.md.
• Один канонический файл, один импорт. Держи всё в AGENTS.md, начни CLAUDE.md со строки @AGENTS.md, а ниже напиши правила только для Claude. Claude сначала читает импортированный файл. Наш собственный репозиторий устроен именно так: его CLAUDE.md состоит из одной этой строки. Символическая ссылка (ln -s AGENTS.md CLAUDE.md) тоже работает, но плохо в Windows: там для её создания нужны права администратора или режим разработчика, а клон без core.symlinks получает вместо твоих инструкций текстовый файл из одной строки.

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

Когда ты запускаешь несколько агентов сразу

AGENTS.md на уровне репозитория отвечает на вопрос "что это за проект". Он не отвечает на вопрос "кто этот агент". Когда ты запускаешь агента Backend, агента Frontend и агента QA параллельно на одном и том же коде, каждому нужен общий контекст проекта плюс его собственная роль.

Это тот слой, который AgentsRoom добавляет поверх твоего AGENTS.md. Каждый агент получает выделенную роль со своим системным промптом (DevOps, Frontend, безопасность и другие), так что общий файл остаётся лёгким, а каждый агент всё равно знает свою задачу. По задумке всё независимо от провайдера, поэтому одна и та же настройка крутит Claude, Codex или Antigravity бок о бок, а твои повторно используемые инструкции живут в библиотеке промптов, а не перепечатываются в каждой сессии.

Когда дойдёшь до этого момента, метод, как запускать несколько агентов параллельно и не терять нить, станет естественным следующим чтением.

Что вынести

Напиши один AGENTS.md. Держи его коротким, держи его актуальным, держи его переносимым. Нацель на него каждый инструмент вместо того, чтобы вести отдельный файл под каждого агента. Твой контекст перестаёт быть привязанным к тому CLI, с которого ты случайно начал, и твои агенты, какими бы они ни были, стартуют с одной и той же страницы.

Хочешь видеть всех агентов на одном экране, каждый со своей ролью и твоим общим контекстом? Скачай AgentsRoom, подключи своего провайдера и запусти весь флот в работу.

Часто задаваемые вопросы

Что такое AGENTS.md?

Markdown-файл, обычно в корне репозитория, который агенты-кодеры загружают как постоянные инструкции перед началом работы: что это за проект, как его собирать и тестировать, какие соглашения соблюдать и каких ловушек избегать. Это открытое соглашение, общее для разных инструментов, а не файл какого-то одного из них. Его читают Codex, Antigravity CLI, GitHub Copilot CLI, Cursor, Amp и, начиная с версии 2.1.277, Claude Code.

Читает ли Claude Code AGENTS.md?

Да, начиная с Claude Code 2.1.277, но только если в твоей рабочей папке и выше нет ни CLAUDE.md, ни .claude/CLAUDE.md, ни CLAUDE.local.md. Тогда он загружает каждый AGENTS.md от рабочей папки вверх, а также AGENTS.md подпапки, когда открывает в ней файл. Если CLAUDE.md существует, Claude читает только его, если только ты не переключишь Project instructions на claude-md-and-agents-md в /config. В более старых версиях поставь строку @AGENTS.md в начало CLAUDE.md.

Antigravity использует AGENTS.md или GEMINI.md?

Оба. Antigravity читает AGENTS.md, GEMINI.md или папку .agents/rules/ в корне репозитория или в любой подпапке, а также глобальные правила из ~/.gemini/. Правила складываются, а не заменяют друг друга, а когда два из них противоречат друг другу, побеждает правило более конкретной папки.

Что оставить: AGENTS.md или CLAUDE.md?

Оставь AGENTS.md единственным файлом, который ты поддерживаешь. Если тебе нужны ещё и правила только для Claude, добавь CLAUDE.md, первая строка которого @AGENTS.md, и напиши эти правила под ней: Claude сначала читает импортированный файл. Если такие правила не нужны, для Claude Code 2.1.277 и новее хватит одного AGENTS.md. Избегай двух полных копий одних и тех же правил: та, которую никто не правит, устаревает.

Где должен лежать AGENTS.md?

В корне репозитория, для правил, которые действуют везде. Claude Code и Antigravity читают и файлы AGENTS.md в подпапках, так что пакет или сервис со своими командами может иметь собственный файл, который читается, когда агент работает в этой папке.