AGENTS.md: что это и пример для Codex и Claude
AGENTS.md это обычный Markdown-файл в корне репозитория с инструкциями для ИИ-агентов, которые пишут код: какими командами собирать и тестировать проект, как он устроен, чего не трогать. Особого синтаксиса нет. Сами его читают Codex, Claude Code с версии 2.1.277, opencode и агент GitHub Copilot. Gemini CLI подключает его через настройку. С ним все агенты работают по одним правилам, и отдельный файл под каждого не нужен. Но если рядом лежит CLAUDE.md, Claude Code читает только его, а Codex, наоборот, только AGENTS.md. Чинится это строкой @AGENTS.md в начале CLAUDE.md, ниже проверка на опыте.
Кто читает AGENTS.md
Общий у всех только проектный файл в корне. Личные файлы, лимиты и вложенные папки каждый агент обрабатывает по-своему.
Codex
да, CLAUDE.md не читает; ещё личный ~/.codex/AGENTS.md
ничего
Claude Code
да, если в проекте нет CLAUDE.md и CLAUDE.local.md
иначе вписать в CLAUDE.md строку @AGENTS.md
opencode
да, CLAUDE.md только при отсутствии AGENTS.md
ничего
Агент GitHub Copilot
да, с августа 2025 года
ничего
Gemini CLI
нет, по умолчанию GEMINI.md
указать AGENTS.md в context.fileName настроек
Формат выпустила OpenAI в августе 2025 года, а с 9 декабря им управляет Agentic AI Foundation при Linux Foundation. Next.js с версии 16.2 по умолчанию кладёт AGENTS.md в новый проект: в проекте, созданном через create-next-app в мае, файл появился в первом же коммите вместе с CLAUDE.md из одной строки @AGENTS.md.
Пример AGENTS.md
Этот файл я проверил 1 октября в Codex CLI 0.159.2 и Claude Code 2.1.280: оба агента назвали команду проверки типов из него, не открывая ни одного файла.
# AGENTS.md ## Проект Сайт на Next.js и TypeScript, база MySQL через TypeORM. ## Команды - Установка: `yarn install --frozen-lockfile` - Тесты одного файла: `yarn vitest run <путь>` - Проверка типов: `yarn typecheck` ## Правила - Перед коммитом: проверка типов и тесты затронутых файлов. - Миграции не применяй сам, только пиши их. - Секреты из `.env` не печатай в ответах и логах. ## Где что лежит - Архитектура: `docs/architecture.md`, открой перед правкой модулей.
Главное в файле это команды: без них агент гадает, чем собирать и тестировать проект. Правила пишите так, чтобы по ним можно было проверить действие. Пересказывать структуру папок не стоит: в университетском исследовании 2026 года на 138 задачах из 12 репозиториев обзор проекта агенту не помог, а любой файл правил поднимал стоимость работы примерно на 20%. Как отличить рабочее правило от пожелания, разобрано в статье про CLAUDE.md.
Опыт: один файл, два агента
Я собрал папки с этим AGENTS.md, дописал в него кодовое слово ЯНТАРЬ и попросил каждого агента, не открывая файлов, назвать команду проверки типов и кодовое слово проекта. У Codex в журнале запуска нет ни одной команды, у Claude Code инструменты отключены: ответ берётся только из того, что агент получил при старте.
Только AGENTS.md
знает
знает
AGENTS.md и CLAUDE.md без импорта
знает
не знает
CLAUDE.md со строкой @AGENTS.md
знает
знает
Только CLAUDE.md
не знает
знает
Симлинк между файлами
знает
знает
Главное во второй строке: CLAUDE.md добавили ради одной мелочи, и Claude Code во всех трёх запусках перестал видеть общие правила. Обратное тоже верно: правила, записанные только в CLAUDE.md, Codex не получит, пока вы не добавите это имя в настройку project_doc_fallback_filenames. Тогда к нему уйдут и правила только для Claude Code.
Как связать AGENTS.md и CLAUDE.md
Пока в проекте нет CLAUDE.md, хватит одного AGENTS.md. Надёжнее сделать как генератор Next.js: CLAUDE.md начинается с импорта @AGENTS.md, ниже то, что нужно только Claude Code. Так общие правила не выпадут и при личном CLAUDE.local.md.
@AGENTS.md ## Только для Claude Code - Правки в `db/` начинай в режиме плана.
Этот вариант я тоже проверил: Claude Code знает и кодовое слово из AGENTS.md, и правило про режим плана. Если в вашем CLAUDE.md написано словами «прочитай AGENTS.md», замените фразу этой строкой: упомянутый файл агент откроет, только если сам решит. А в самом AGENTS.md импорты не пишите: строку @docs/extra.md Claude Code раскрыл, а Codex в двух запусках из двух получил просто текст с путём.
Второй способ: симлинк. Если главный файл у вас CLAUDE.md, хватит ln -s CLAUDE.md AGENTS.md. Так сделано в одном клиентском проекте, где один файл заведён на Claude Code, Codex и opencode. Обратное направление в опыте тоже сработало. Но Git на Windows по умолчанию положит при клонировании вместо симлинка файл с одной строкой пути. Если в команде разные системы, надёжнее импорт.
Вложенные файлы и лимит Codex
Codex склеивает инструкции при запуске. Сначала личный ~/.codex/AGENTS.md, затем по одному файлу на каждую папку от корня репозитория до той, откуда вы его запустили. Нижние идут позже и потому главнее. AGENTS.override.md в той же папке заменяет обычный файл, но Claude Code его не читает. Правку файла подхватит следующий запуск.
Вложенный файл я проверил на обоих агентах: положил в services/bot свой AGENTS.md с другим кодовым словом и командой тестов. Запущенные из этой папки, Codex и Claude Code назвали оба слова и команду из ближнего файла. Но если в корне лежит CLAUDE.md с импортом, Claude Code файл папки пропускает: запущенный из корня с доступом к файлам, он прочитал код в services/bot и придумал команду тестов. Помог такой же CLAUDE.md из строки @AGENTS.md рядом с вложенным файлом, два запуска из двух. В режиме -p из самой папки корневые правила не дошли.
Корневой файл раздувать опасно: все файлы проекта вместе Codex читает до 32 КБ, остальное отрезает. CLAUDE.md этого сайта весит 103 КБ, он написан под Claude Code. Я добавил его в ту же настройку project_doc_fallback_filenames и попросил Codex процитировать последнюю строку, которую тот видит.
$ codex exec -s read-only -c model_reasoning_effort=low \
-c 'project_doc_fallback_filenames=["CLAUDE.md"]' \
"Не открывая файлов: процитируй последний заголовок и последнюю строку инструкций проекта"
Последний заголовок:
> #### Деплой: новая сборка встаёт рядом, старая ждёт под рукой
Последняя строка (так пришла, обрезана):
> 3. **Неу�Целиком Codex получил девять разделов правил из девятнадцати, десятый оборвался на половине буквы. В выводе команды предупреждения нет. Лимит поднимается параметром project_doc_max_bytes в ~/.codex/config.toml, но надёжнее сократить сам файл.
Чего AGENTS.md не делает
Правило из AGENTS.md агент может нарушить. Команду, которую нельзя выполнять никогда, ставьте запретом в настройках самого агента. AGENTS.md клонированного проекта агент прочитает так же доверчиво, как ваш, поэтому откройте его до первого запуска: что бывает, когда агент выполняет чужую приписку, показано в статье про промпт-инъекцию. Длинные процедуры выносите в скилы: файл SKILL.md тоже понимают оба агента, различаются папки и часть полей.
Частые вопросы
Что сделать сегодня: допишите в AGENTS.md кодовое слово и спросите о нём каждого агента в новой сессии, запретив открывать файлы. Если молчит Claude Code, ищите рядом CLAUDE.md или CLAUDE.local.md без строки @AGENTS.md. Если молчит Codex, проверьте, не больше ли файл 32 КБ и нет ли рядом AGENTS.override.md. Если правила уже разъехались по разным файлам, сведём их в один на менторинге по вайб-кодингу.
Читайте также
Как создать сайт с помощью нейросети и проверить
Как создать сайт с помощью нейросети: лендинг с заявкой, три дефекта и лишние обещания. Прогон Claude Code, задания, исходники и проверка перед запуском.
CLAUDE.md: что это, шаблон и правила для агента
Что такое CLAUDE.md в Claude Code, где лежит и что писать: шаблон, проверенный запуском, правила, которые агент выполняет, и пример из нашего проекта.
Контекст в Claude Code: что это и когда кончается
Рабочая память агента: правила, файлы, выводы команд. Что происходит, когда окно заполняется, что переживает сжатие и как продолжить проект после обрыва.