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

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

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

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

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

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

AGENTS.md vs CLAUDE.md vs GEMINI.md

Сейчас картина разбита по инструментам:

• CLAUDE.md: это то, что ищет Claude Code.
• GEMINI.md: это соглашение Gemini CLI.
• AGENTS.md: это межинструментальный стандарт, который читают Codex и другие, задуманный как нейтральный файл.

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

Если ты работаешь в основном в 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.md и GEMINI.md сделай файлами из одной строки со словами "смотри AGENTS.md", или поставь на них символические ссылки. Один источник истины, накормлены все инструменты.
• Один файл, общий по договорённости. Если твои инструменты можно нацелить на произвольный путь, направь их все на AGENTS.md и удали остальные.

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

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

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

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

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

Что вынести

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

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