AGENTS.md: один файл инструкций для Codex, Cursor и Claude Code

Проектные инструкции для кодовых агентов лежат в репозитории под разными именами: CLAUDE.md у Claude Code, .cursor/rules у Cursor, .github/copilot-instructions.md у Copilot, GEMINI.md у Gemini CLI. AGENTS.md сводит их к одному файлу. Это открытый формат, обычный Markdown в корне репозитория с командами сборки и тестов, соглашениями по коду и ограничениями. Спецификация на agents.md называет его «README для агентов», а курирует формат Agentic AI Foundation при Linux Foundation.

В ноябре 2026 года AGENTS.md читают Codex, Cursor и GitHub Copilot, а Claude Code с версии 2.1.277 читает его, если в проекте нет CLAUDE.md. Но каждый инструмент читает по-своему: одни склеивают все файлы по дереву, другие берут ближайший, у Codex есть лимит 32 KiB на всю цепочку, а Claude Code молча переключается на CLAUDE.md, если тот лежит рядом.

Статья о том, кто и как читает AGENTS.md, как совместить его с CLAUDE.md в команде, где работают несколько агентов, что класть в общий файл и какие ловушки встречаются на практике. Поведение Claude Code проверено на версии 2.1.318, остальное описано по документации на 6 ноября 2026 года. Уровни CLAUDE.md и порядок их загрузки разобраны отдельно в гайде по CLAUDE.md.

Что такое AGENTS.md

Происхождение и стюардство

Формат появился в экосистеме OpenAI Codex и быстро вышел за её пределы. В декабре 2025 года Linux Foundation запустила Agentic AI Foundation, и AGENTS.md (от OpenAI) вошёл в неё вместе с MCP от Anthropic и goose от Block (SD Times, InfoQ). Сайт agents.md сообщает, что формат используют более 60 тысяч open-source проектов, а в основном репозитории OpenAI на момент написания страницы было 88 файлов AGENTS.md.

Главное, что нужно знать о формате: схемы нет. На вопрос об обязательных полях спецификация отвечает «нет, это обычный Markdown». Ни frontmatter, ни зарезервированных заголовков формат не требует, механизма условного применения в нём нет. Всё, что сложнее «прочитай этот текст», каждый инструмент реализует сам.

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

Что туда писать

Спецификация рекомендует пять разделов: обзор проекта, команды сборки и тестов, стиль кода, тестирование, безопасность. Минимальный рабочий файл помещается в полтора десятка строк:

# AGENTS.md

## Команды
- Установка: `pnpm install`
- Тесты: `pnpm test` (перед каждым коммитом)
- Линтер: `pnpm lint --fix`

## Соглашения
- TypeScript strict, без `any`
- API-обработчики лежат в `src/api/handlers/`

## Ограничения
- Не добавлять зависимости без согласования
- Не коммитить `.env*` и секреты

Полный шаблон для команды есть в разделе «Шаблон AGENTS.md и тонкий CLAUDE.md».

Кто читает AGENTS.md: матрица инструментов

Таблица собрана по первичной документации каждого инструмента, дата проверки: 6 ноября 2026 года. Поведение меняется от релиза к релизу, поэтому перед внедрением стоит перепроверить свой инструмент по ссылке из последней колонки.

В списке поддерживающих инструментов на agents.md есть ещё Jules, Devin, Windsurf, Junie, Zed, Warp, Factory, goose, opencode, Amp, RooCode, Kilo Code, Augment Code и другие. Их собственную документацию для этой статьи не проверяли. Отдельная оговорка про Gemini CLI: в мае 2026 года Google объявила о переходе на Antigravity CLI: с 18 июня 2026 года Gemini CLI перестал обслуживать бесплатных пользователей и подписчиков Google AI Pro и Ultra, доступ сохранился у лицензий Gemini Code Assist Standard и Enterprise и при работе через платные API-ключи. Читает ли AGENTS.md сам Antigravity CLI, не проверяли.

Codex: цепочка файлов и лимит 32 KiB

Codex собирает инструкции заново при каждом запуске. Сначала глобальный уровень в ~/.codex (или в CODEX_HOME): берётся AGENTS.override.md, а если его нет, AGENTS.md; используется первый непустой. Затем проектный уровень: Codex идёт от корня проекта (обычно корня Git-репозитория) вниз до текущей директории и в каждом каталоге берёт не больше одного файла в порядке AGENTS.override.md → AGENTS.md → имена из project_doc_fallback_filenames.

Найденные файлы не заменяют друг друга, а склеиваются через пустую строку от корня вниз. Ближайшие к рабочей директории идут последними и поэтому выигрывают при противоречии. Пустые файлы пропускаются. Как только суммарный размер достигает project_doc_max_bytes (по умолчанию 32 KiB), Codex перестаёт добавлять файлы. Документация советует либо поднять лимит, либо разнести инструкции по вложенным каталогам.

Запасные имена задаются в ~/.codex/config.toml:

project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

Проверить, что Codex видит, можно его же запросом из корня репозитория: codex --ask-for-approval never "Summarize the current instructions.". Для подкаталога добавьте флаг --cd subdir.

Cursor: AGENTS.md или .cursor/rules

Cursor поддерживает оба механизма, и они решают разные задачи. AGENTS.md - простой Markdown без метаданных, документация Cursor предлагает его «для простых случаев». Файлы в подкаталогах объединяются с родительскими, более специфичные инструкции приоритетнее.

Правила .cursor/rules хранятся в файлах с расширением .mdc и frontmatter из трёх полей: description, globs, alwaysApply. От них зависит тип применения: Always Apply (в каждой сессии), Apply Intelligently (агент решает по описанию), Apply to Specific Files (по шаблону пути), Apply Manually (по @-упоминанию). В старых версиях документации последние два назывались Agent Requested и Auto Attached. Обычный .md в .cursor/rules без frontmatter система правил игнорирует.

Поверх проектных правил есть User Rules (глобальные для пользователя) и Team Rules (тарифы Team и Enterprise). При конфликте порядок такой: Team → Project → User. Про устаревший .cursorrules текущая страница документации не пишет ничего, поэтому утверждать что-либо о его статусе по ней нельзя.

GitHub Copilot: copilot-instructions.md, applyTo и AGENTS.md

У Copilot три вида репозиторных инструкций. .github/copilot-instructions.md действует на весь репозиторий. Файлы .github/instructions/NAME.instructions.md с ключом applyTo (glob) действуют на часть путей, их поддерживают только cloud agent и code review, а ключом excludeAgent ("code-review" или "cloud-agent") файл можно скрыть от одного из них. Третий вид называется agent instructions: один или несколько AGENTS.md в любом месте репозитория, где приоритет у ближайшего, либо одиночный CLAUDE.md или GEMINI.md в корне.

Кто именно читает agent instructions, видно из таблицы поддержки: cloud agent (на GitHub.com и из IDE), code review, Copilot CLI и Copilot Chat в VS Code. Copilot Chat в JetBrains, Visual Studio, Eclipse и Xcode в таблице agent instructions не поддерживает. Если команда пользуется Chat вне VS Code, copilot-instructions.md пока нужен.

Личные инструкции Copilot приоритетнее репозиторных, а репозиторные приоритетнее организационных; в запрос уходят все релевантные наборы.

Claude Code: что изменилось и правила выбора

До версии 2.1.277 Claude Code читал только CLAUDE.md, и AGENTS.md приходилось подключать обходными путями. Теперь встроенный плагин читает AGENTS.md сам, но с условием: по умолчанию (claude-md-or-agents-md) только если в рабочей директории и выше нет ни одного из трёх файлов: CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md. Пользовательский ~/.claude/CLAUDE.md, управляемый CLAUDE.md организации и .claude/rules/ в эту проверку не входят и грузятся вместе с AGENTS.md.

Проверено: 6 ноября 2026 года, Claude Code 2.1.318, временные папки с уникальной фразой-маркером в каждом файле. Во всех четырёх случаях модель назвала маркеры только из указанных в таблице файлов, а /context all показал те же файлы в разделе Memory files. Импорт @AGENTS.md дубля не дал: каждый файл в списке один раз.

Ещё три отличия AGENTS.md, прочитанного напрямую, от CLAUDE.md по документации: на него не срабатывают хуки InstructionsLoaded (для импортированного или подключённого через symlink AGENTS.md срабатывают); AGENTS.md из каталогов, добавленных через --add-dir, не грузится; не читаются AGENTS.local.md, AGENTS.override.md и содержимое каталога .agents/. Если у вас есть Codex-специфичный AGENTS.override.md, Claude Code его не увидит.

Как совместить AGENTS.md с CLAUDE.md

Вариантов четыре, и универсально правильного среди них нет. Выбор зависит от того, есть ли в команде Windows, нужны ли инструкции только для Claude Code и укладывается ли общий текст в лимит Codex.

Вариант 1: только AGENTS.md

CLAUDE.md в репозитории нет, Claude Code читает AGENTS.md сам. Подходит, если инструкции действительно общие, а Claude-специфичного (hooks, skills, plan mode) в них нет или оно лежит в .claude/rules/ и .claude/settings.json.

Главная ловушка здесь CLAUDE.local.md. Это личный, незакоммиченный файл, и кажется, что он только добавляет инструкции. На деле он считается за CLAUDE.md, и Claude Code перестаёт читать AGENTS.md. В живой проверке модель с AGENTS.md и CLAUDE.local.md в одной папке видела только маркер из CLAUDE.local.md. Сообщения об ошибке нет: агент просто работает без проектных инструкций.

Второе ограничение связано с версиями. Сессии на Claude Code до 2.1.277 AGENTS.md не видят. До 2.1.281 его не видели и некоторые сессии на свежих версиях, например на Amazon Bedrock или с отключённой телеметрией. Иногда его не читает и первая сессия сразу после обновления с версии 2.1.276 или более ранней.

Вариант 2: CLAUDE.md с @AGENTS.md

Этот вариант стоит выбирать по умолчанию. AGENTS.md служит источником правды для всех агентов, а CLAUDE.md остаётся тонкой обёрткой: первой строкой импорт, ниже то, что относится только к Claude Code.

@AGENTS.md

## Claude Code
- Изменения в `src/billing/`: только через plan mode
- Перед коммитом запусти skill `pre-push`

Claude Code сначала читает импортированный файл, затем остальной CLAUDE.md. Схема работает и в сессиях, где прямое чтение AGENTS.md недоступно, и при любом значении настройки Project instructions, а дубля в контексте не бывает: документация обещает, что импорт никогда не заставит прочитать AGENTS.md дважды, и живая проверка это подтверждает. Минус один: если кто-то добавит в CLAUDE.md общие правила, другие агенты их не увидят. Такие вещи ловит только ревью.

Вариант 3: symlink

ln -s AGENTS.md CLAUDE.md

Содержимое одно, читают его все. Документация Claude Code перечисляет два ограничения. Первое: инструменты Edit и Write не пишут через symlink, и Claude перенаправит правку в целевой файл, AGENTS.md. Второе: Windows. Создание symlink требует прав администратора или Developer Mode, а Git без core.symlinks извлекает закоммиченную ссылку как обычный текстовый файл. У разработчика на Windows CLAUDE.md окажется однострочным файлом с текстом AGENTS.md вместо инструкций.

Встречается и обратная схема: AGENTS.md -> CLAUDE.md. В рабочем пространстве автора (около 15 проектов, Claude Code и Codex параллельно) так устроено большинство проектов: они начинались с Claude Code, и источником правды остался CLAUDE.md. Направление ссылки определяет, какой файл настоящий, и это важно в двух местах. Править нужно цель, а не ссылку. И всё, что лежит в цели, видят все агенты: при AGENTS.md -> CLAUDE.md Codex получает и Claude-специфичные инструкции про hooks и skills, которых у него нет.

Вариант 4: два файла разной длины

Иногда общий текст объективно не помещается в лимит Codex. Пример из того же рабочего пространства: в продуктовом монорепозитории CLAUDE.md занимает около 708 строк и 41 415 байт, а AGENTS.md около 128 строк и 10 КБ. Длинный файл в лимит Codex по умолчанию (32 768 байт) не поместился бы. Что Codex делает с единственным файлом больше лимита, документация не уточняет: она описывает только остановку при накоплении суммы. Этот случай не проверяли.

Короткая версия для Codex фиксирует только операционный минимум: язык ответов, консервативные изменения, запреты (удаление файлов, новые зависимости, долгоживущие процессы, секреты), порядок проверки и ссылку «подробности в docs/, не здесь». Такое разделение осознанное: у короткого файла своя задача, и пересказывать длинный он не пытается.

Цена варианта в том, что получается два файла, которые нужно синхронизировать вручную. Работает, только если короткий файл действительно короткий и меняется редко.

Таблица выбора

«Да» в ячейке означает, что вариант подходит при этом условии.

Режим claude-md-and-agents-md и проверка через /context all

Если и CLAUDE.md, и AGENTS.md нужны, а импорт ставить не хочется, Claude Code можно переключить на чтение обоих файлов. В интерактивной сессии: /config → Project instructions → claude-md-and-agents-md. В файле настроек:

{
  "pluginConfigs": {
    "cc-plugin-agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

Эта настройка читается только из ~/.claude/settings.json, из файла, переданного через --settings, и из managed settings. В проектном .claude/settings.json и в settings.local.json она игнорируется, поэтому закоммитить её в репозиторий для всей команды нельзя. До v2.1.285 плагин назывался agents-md@builtin; с 2.1.285 принимаются оба ID. Остальные значения: claude-md (только CLAUDE.md) и managed-only (только управляемые инструкции организации).

Проверено: 6 ноября 2026 года, Claude Code 2.1.318, настройка передана через --settings. С CLAUDE.md без импорта модель увидела маркеры обоих файлов, с CLAUDE.local.md тоже маркеры обоих. Режим лечит и обычную ситуацию «CLAUDE.md рядом с AGENTS.md», и ловушку с CLAUDE.local.md.

Быстрее всего проверить загрузку командой /context all в начале сессии. Раздел Memory files перечисляет файлы инструкций с их уровнем (Project, Local, User) и числом токенов. Команда работает и в неинтерактивном режиме: claude -p "/context all". Если вместо ожидаемого AGENTS.md в списке только CLAUDE.local.md, причина найдена.

Вложенные AGENTS.md и монорепозитории

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

• Codex склеивает всю цепочку от корня до текущей директории, и вложенные файлы тратят общий бюджет 32 KiB. Дробление на пакеты помогает, только если корневой файл короткий: он попадает в каждую цепочку.
• Cursor объединяет вложенный файл с родительскими, более специфичный выигрывает при конфликте.
• Copilot берёт ближайший файл в дереве.
• Claude Code при старте читает AGENTS.md из рабочей директории и всех директорий выше, а AGENTS.md подкаталога подгружает, когда открывает файл из этого подкаталога и там нет своего CLAUDE.md. Вложенные файлы в живой проверке не тестировались, здесь описано поведение по документации.

Дробить имеет смысл, когда у пакетов действительно разные команды и соглашения: фронтенд на pnpm и Vitest, бэкенд на Go, отдельный пакет с инфраструктурой. Если вложенный файл повторяет корневой с парой отличий, лучше оставить одну строку в корневом: «в packages/api тесты запускаются через go test ./...».

Что класть в общий файл, а что нет

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

• команды сборки, тестов, линтера;
• соглашения по коду и структуре, которые не выводятся из самого кода;
• запреты: секреты, новые зависимости, удаление файлов, ручной деплой;
• порядок проверки перед коммитом;
• ссылки на docs/ и ADR вместо пересказа.

Инструмент-специфичное уходит в файл инструмента. Hooks, skills, plan mode, субагенты, MCP-серверы Claude Code описываются в CLAUDE.md или .claude/. Codex-специфичное кладут в AGENTS.override.md или глобальный ~/.codex/AGENTS.md. Фраза «запусти skill pre-push» в общем файле заставит Codex искать то, чего у него нет. Жёсткие правила, которые нельзя нарушать, вообще лучше выносить из текста в механизмы: в Claude Code для этого есть hooks. Инструкция в любом из файлов для модели только контекст, выполнение она не гарантирует.

Личные правила AGENTS.md не шарит. Это проектный файл: глобальные предпочтения у Claude Code живут в ~/.claude/CLAUDE.md, у Codex в ~/.codex/AGENTS.md, и синхронизировать их придётся отдельно.

Что касается содержания, есть эмпирика. В исследовании ETH Zurich и LogicStar.ai (arXiv 2602.11988, v3 от 29.09.2026) агентов прогоняли на задачах SWE-bench и на наборе issues из репозиториев, где разработчики сами закоммитили контекст-файлы. Вывод авторов: такие файлы в целом не повышают долю решённых задач, а стоимость инференса растёт в среднем более чем на 20%. Инструкции агенты выполняют хорошо, обзоры репозитория не помогают. Польза есть там, где нужно описать нестандартные практики проекта.

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

Шаблон AGENTS.md и тонкий CLAUDE.md

Шаблон для репозитория, с которым работают несколько агентов. Конкретные команды и пути заменить своими.

## Проект
Монорепозиторий: `apps/web` (Next.js), `apps/api` (Go), `packages/ui`.
Архитектура описана в `docs/architecture.md`, решения в `docs/adr/`.

## Команды
- Установка: `pnpm install`
- Тесты всего репозитория: `pnpm test`; один пакет: `pnpm --filter <pkg> test`
- API: `cd apps/api && go test ./...`
- Линтер и формат: `pnpm lint --fix`

## Соглашения
- TypeScript strict, без `any`; ошибки API отдаются через `ApiError`
- Новые эндпоинты добавляются с тестом в `apps/api/internal/.../*_test.go`
- Миграции БД только новыми файлами, существующие не редактировать

## Ограничения
- Не добавлять зависимости без согласования в PR
- Не коммитить `.env*`, ключи и токены
- Не удалять файлы и крупные блоки кода без явной просьбы
- Не запускать долгоживущие процессы (dev-серверы, watchers)

## Перед коммитом
1. `pnpm lint` и `pnpm test` проходят
2. Изменение описано в PR: что и зачем

И тонкий CLAUDE.md рядом:

@AGENTS.md

## Только для Claude Code
- Изменения в `apps/api/internal/billing/`: через plan mode
- Перед push запускай skill `pre-push`

Обе части вместе укладываются в несколько килобайт: до лимита Codex далеко, и до рекомендованных 200 строк для CLAUDE.md тоже. Что ещё писать в Claude-части, разобрано в гайде по CLAUDE.md.

Миграция существующей настройки

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

Из .cursor/rules. Правила типа Always Apply переносятся в AGENTS.md. Правила, привязанные к шаблонам файлов, остаются в .mdc или превращаются во вложенный AGENTS.md соответствующего каталога. Правила типа Apply Intelligently аналога в AGENTS.md не имеют.

Из .github/copilot-instructions.md. Общий текст переносится в AGENTS.md. Сам copilot-instructions.md стоит оставить, если в команде пользуются Copilot Chat вне VS Code: там AGENTS.md не читается.

Через инструменты Claude Code. /init при генерации CLAUDE.md учитывает .cursor/rules, .cursorrules и .github/copilot-instructions.md; с переменной CLAUDE_CODE_NEW_INIT=1 ещё и AGENTS.md, .devin/rules/, .windsurf/rules/ и .clinerules. /import один раз копирует конфигурацию другого агента, включая AGENTS.md, в CLAUDE.md. В обоих случаях получается копия текста: если AGENTS.md остаётся в репозитории, лучше заменить скопированный текст на @AGENTS.md. Сгенерированный файл целиком оставлять не стоит: /init пишет обзор проекта, а такие обзоры, судя по данным ETH, агентам не помогают.

Старые обходы. Документация Claude Code разбирает четыре распространённых варианта:

Типичные ошибки

Две копии, которые правят независимо. Классический сценарий дрейфа. В одном из проектов автора CLAUDE.md и AGENTS.md начинались как одинаковые копии; со временем они разошлись в нескольких абзацах, и уже нельзя сказать, какая версия правильная. Агенты в одном репозитории получают разные правила.

Автозамена имён. Копию для другого агента делают поиском и заменой Claude → Codex. Вместе с названием меняются пути: строка ~/.claude/team-rules.md превращается в ~/.Codex/team-rules.md, которого не существует. Ошибка молчаливая: агент просто не находит файл.

Claude-специфика в общем файле. Для других агентов упоминания skills, hooks, субагентов и MCP-серверов Claude Code в AGENTS.md становятся инструкциями, которые они не могут выполнить. В лучшем случае это лишний расход контекста, в худшем агент тратит шаги на поиск несуществующего. Особенно легко это случается при схеме AGENTS.md -> CLAUDE.md.

Symlink в команде с Windows. У части команды вместо инструкций окажется однострочный файл. Это легко пропустить: агент работает как обычно, просто без проектных правил.

CLAUDE.local.md в проекте на AGENTS.md. Личный файл молча отключает чтение общего. Лечится импортом @AGENTS.md в CLAUDE.local.md или режимом claude-md-and-agents-md в пользовательских настройках.

Устаревший файл. AGENTS.md с командами, которые больше не работают, хуже отсутствия файла: агенты выполняют инструкции старательно. Файл стоит менять в том же PR, что и команды сборки, и проверять на ревью.

Разница между самими агентами разобрана в сравнении Claude Code и Codex, место файлов правил в командном процессе описано в гайде по vibe coding, общая настройка Claude Code есть в полном гайде по Claude Code.

С чего начать

1. Запустить /context all в Claude Code и посмотреть, какие файлы инструкций реально загружаются сейчас.
2. Найти все файлы инструкций в репозитории: CLAUDE.md, CLAUDE.local.md, AGENTS.md, .cursor/rules, .github/copilot-instructions.md. Если среди них есть копии, выбрать одну источником правды.
3. Перенести общее в AGENTS.md, Claude-специфичное оставить в CLAUDE.md под строкой @AGENTS.md.
4. Проверить размер: wc -c по всем AGENTS.md в цепочке от корня до самого глубокого пакета; сумма должна оставаться заметно ниже 32 KiB.
5. Проверить каждым агентом: /context all в Claude Code, codex ... "Summarize the current instructions." в Codex, /memory show в Gemini CLI, если он у вас ещё работает.