AGENTS.md это README для ИИ-агентов: одно место, куда складывают правила проекта. Разбираем, что писать внутри, где файл лежит, кто его читает и как подружить с CLAUDE.md.
AGENTS.md это markdown-файл в корне репозитория с правилами проекта для ИИ-агентов: команды сборки и тестов, стиль кода, запреты. Авторы стандарта называют его README для агентов — человек читает README, агент читает AGENTS.md. Обязательных полей нет, формат свободный. Файл поддерживают больше двадцати инструментов, включая Codex, opencode, Cursor и Kilo Code, и используют больше 60 тысяч открытых проектов. Claude Code в этом списке особняком: он читает CLAUDE.md. Факты проверены 15 августа 2026 года по стандарту и документации агентов.
Что узнаешь из гайда
Зачем нужен AGENTS.md и что он экономит
Готовый пример файла на копипаст
Где он лежит и как работают вложенные файлы
Какие агенты читают файл и с какими оговорками
Как связать его с CLAUDE.md без дублирования
Часть 1 · Понятие
Что такое AGENTS.md и зачем он нужен
Главное
Это предсказуемое место для контекста проекта: агент всегда знает, куда смотреть, и не выясняет заново, как запускать тесты.
Формулировка стандарта короткая: выделенное предсказуемое место, где лежит контекст и инструкции, помогающие агенту работать с проектом. Идея выросла из простого наблюдения: README пишут для людей, туда не затащишь длинный список команд и оговорок, а агенту как раз нужны именно они.
Экономит повторы. Всё, что ты объясняешь агенту во второй раз, должно жить в файле.
Едет вместе с кодом. Файл коммитится в репозиторий, поэтому правила одинаковы у всей команды и у CI.
Работает у разных агентов. Один текст читают Codex, opencode, Cursor, Kilo Code и ещё полтора десятка инструментов.
Формат простой. Обычный markdown, никаких обязательных полей и схемы.
Часть 2 · Практика
Что писать в AGENTS.md: пример
Главное
Правило отбора одно: в файл идёт то, что агент не выведет сам из кода — команды, договорённости, запреты.
Типовые разделы, которые предлагает сам стандарт: обзор проекта, команды сборки и тестов, стиль кода, инструкции по тестированию, вопросы безопасности. Ниже рабочий скелет, который остаётся только заполнить под свой проект.
AGENTS.md · пример
# AGENTS.md
## О проекте
Веб-приложение на Next.js и Postgres. Фронтенд в app/, серверная логика в lib/.
## Команды
- Установка: npm ci
- Запуск: npm run dev (порт 3000)
- Тесты: npm test
- Проверки перед коммитом: npm run typecheck && npm run lint
## Стиль кода
- TypeScript строгий, any запрещён.
- Именование файлов через дефис, компоненты в PascalCase.
- Комментарии по-русски, объясняют «почему», а не «что».
## Тестирование
- Новая логика без теста не принимается.
- Тесты лежат рядом с кодом, суффикс .test.ts.
## Чего делать нельзя
- Не править файлы миграций задним числом.
- Не коммитить .env и ключи.
- Не менять схему базы без отдельного согласования.
Проверка на полезность строки
Если строку можно вывести из самого репозитория за минуту — она лишняя: агент прочитает package.json и сам поймёт, что тут npm. Ценность несут вещи, которых в коде нет: почему выбран такой подход, что ломается при отклонении, где грабли.
Часть 3 · Расположение
Где лежит файл и как работает вложенность
Главное
Основной файл — в корне репозитория. В монорепозитории у каждого пакета может быть свой, ближайший главнее.
Имя пишется заглавными буквами. В документации Kilo Code это вынесено отдельным требованием: так файл одинаково находится в разных операционных системах, где регистр в путях учитывается по-разному. Там же оговорено запасное имя AGENT.md в единственном числе, но полагаться на такие исключения не стоит.
Вложенные файлы решают типовую боль монорепозитория: правила фронтенда не нужны агенту, когда он правит сервис на другом языке. Стандарт описывает поведение прямо: побеждает ближайший файл. Агенты подтягивают такие файлы по мере того, как заходят в соответствующую папку, — Kilo Code, например, вставляет содержимое ближайшего файла в диалог, когда читает файл из этой директории.
структура · монорепозиторий
repo/
├── AGENTS.md # общие правила
├── apps/
│ ├── web/
│ │ └── AGENTS.md # правила фронтенда
│ └── api/
│ └── AGENTS.md # правила сервиса
└── packages/
└── ui/
└── AGENTS.md # правила библиотеки компонентов
Часть 4 · Совместимость
Какие агенты читают AGENTS.md
Главное
Список на сайте стандарта — больше двадцати инструментов. Правила чтения у них отличаются в деталях, и это стоит знать заранее.
Среди поддерживающих инструментов перечислены OpenAI Codex, Google Jules, Factory, Aider, goose, opencode, Zed, Warp, VS Code, Devin, JetBrains Junie, Amp, Cursor, RooCode, Gemini CLI, Kilo Code, GitHub Copilot, Windsurf и Augment Code. Ниже — то, что удалось подтвердить по документации самих агентов.
Агент
Как обращается с файлом
Codex CLI
Создаёт файл сам: слэш-команда /init собирает правила проекта в AGENTS.md
opencode
Сначала ищет AGENTS.md, при его отсутствии берёт CLAUDE.md; глобальный файл лежит в ~/.config/opencode/AGENTS.md
Kilo Code
AGENTS.md в корне, запасное имя AGENT.md, вложенные файлы подгружаются на ходу; файл защищён от записи агентом
Cursor
Считает файл простой альтернативой каталогу .cursor/rules для несложных случаев
Claude Code
Не читает: работает с CLAUDE.md, подключение AGENTS.md — через импорт
Claude Code читает CLAUDE.md, а не AGENTS.md. Официальное решение — импорт одного файла в другой, без копирования текста.
Это самая частая ловушка в смешанной команде: в репозитории лежит аккуратный AGENTS.md, все агенты его читают, а Claude Code ведёт себя так, будто правил нет. В документации Anthropic сказано прямо: читается CLAUDE.md. Дублировать текст в два файла не нужно — достаточно импорта.
CLAUDE.md · импорт правил
@AGENTS.md
## Claude Code
Для правок в src/billing/ сначала включай режим планирования.
Первая строка подтягивает содержимое AGENTS.md в контекст, ниже можно дописать инструкции, которые касаются только Claude. Второй путь — симлинк командой ln -s AGENTS.md CLAUDE.md, он подходит, когда отдельных инструкций нет. На Windows симлинк требует прав администратора или включённого режима разработчика, поэтому там надёжнее импорт.
Перенести разово. Команда /import в Claude Code переносит конфигурацию другого агента: дописывает содержимое AGENTS.md в CLAUDE.md и подтягивает MCP-серверы, команды, субагентов и скилы. Нужна версия v2.1.213 или новее.
Собрать с нуля. Команда /init генерирует CLAUDE.md по коду проекта; с переменной CLAUDE_CODE_NEW_INIT=1 она заодно читает AGENTS.md и правила других агентов.
Держать файл коротким. Anthropic советует не превышать 200 строк: длинный файл съедает контекст и хуже соблюдается.
Как устроен сам CLAUDE.md, что в него класть и как обновлять, разобрано в отдельном гайде про настройку памяти проекта через CLAUDE.md. Если Claude ты запускаешь не в терминале, а в графическом интерфейсе, порядок тот же — подробности в разборе приложения Claude Desktop.
Часть 6 · Грабли
Частые ошибки в файле правил
Главное
Файл перестаёт работать по трём причинам: он слишком длинный, устарел или противоречит сам себе.
Роман вместо инструкции. Правила читаются в начале каждой сессии и занимают контекст. Чем длиннее файл, тем хуже он соблюдается.
Противоречия. Если два пункта требуют разного, агент выберет любой. Особенно легко это проглядеть во вложенных файлах.
Устаревшие команды. Команда сборки поменялась, файл остался прежним — агент уверенно делает не то. Файл правил стареет так же, как документация.
Инструкции на один случай. Длинную процедуру, которая нужна изредка, лучше вынести в скил: он подгрузится только по делу. Как это устроено, разобрано в гайде про скилы Claude Code и свою библиотеку навыков.
Правила это не защита
Строчка «никогда не трогай продовую базу» в файле правил остаётся текстом, а не техническим ограничением: агент читает её как контекст и может истолковать иначе. Настоящие запреты ставятся правами доступа и хуками, разбор — в гайде про права доступа агента.
Коротко
AGENTS.md это markdown-файл с правилами проекта для агентов, лежит в корне репозитория и коммитится вместе с кодом.
Обязательных полей нет; типовые разделы — обзор, команды, стиль, тесты, безопасность и запреты.
В монорепозитории работают вложенные файлы, ближайший к рабочей папке главнее.
Файл читают больше двадцати инструментов, среди них Codex, opencode, Cursor и Kilo Code; используют больше 60 тысяч проектов.
Claude Code читает CLAUDE.md: связывать через импорт @AGENTS.md, симлинк или разовый перенос командой /import.
Вопросы
Частые вопросы
Что такое AGENTS.md?
AGENTS.md это обычный markdown-файл в корне репозитория, куда складывают правила проекта для ИИ-агентов: команды сборки и тестов, принятый стиль кода, ограничения по безопасности. Авторы стандарта называют его README для агентов: человек читает README, агент читает AGENTS.md. Обязательных полей в файле нет.
Что писать в AGENTS.md?
Пишут то, что иначе приходится объяснять агенту в каждой сессии: как запускать проект, чем тестировать, какие директории трогать нельзя, какие соглашения приняты в команде. Типовые разделы — обзор проекта, команды сборки и тестов, стиль кода, инструкции по тестированию и требования безопасности. Общие рассуждения о хорошем коде туда класть смысла нет.
Где должен лежать файл AGENTS.md?
В корне репозитория. Для монорепозитория стандарт разрешает вложенные файлы: свой AGENTS.md в каждом пакете, и тогда ближайший к рабочей папке файл главнее. Имя пишется заглавными буквами, иначе часть агентов его не найдёт. Файл коммитят в репозиторий, чтобы правила ехали вместе с кодом.
Какие агенты читают AGENTS.md?
На сайте стандарта перечислено больше двадцати инструментов, среди них OpenAI Codex, opencode, Cursor, Kilo Code, Gemini CLI, Zed, Warp, Aider, goose, GitHub Copilot, Windsurf, JetBrains Junie и Devin. Codex создаёт файл сам по команде /init. По данным стандарта, AGENTS.md используют больше 60 тысяч открытых проектов.
Claude Code читает AGENTS.md?
Нет. В документации сказано прямо: Claude Code читает CLAUDE.md, а не AGENTS.md. Если в репозитории уже есть AGENTS.md, официальный обход — создать CLAUDE.md и первой строкой поставить импорт @AGENTS.md, тогда оба агента работают по одному тексту. Второй вариант — симлинк, но на Windows он требует прав администратора.
Чем AGENTS.md отличается от скилов?
AGENTS.md загружается в контекст в начале работы и действует всегда, поэтому в нём держат короткие постоянные правила. Скил подгружается только тогда, когда задача ему подходит, и может быть сколь угодно подробным. Если инструкция нужна раз в месяц и занимает страницу, ей место в скиле, а не в файле правил.
Собери свой ИИ-офис и перестань делать руками то, что делает нейросеть
Платформа и сообщество, где я по шагам показываю, как поставить ИИ на рутину: контент, код, продажи, аналитика. Заходи и забирай рабочие связки, которыми пользуюсь сам.
Завайбкодил контент-ферму на США в Instagram (более 300 тыс. подписчиков, среди читателей Дональд Трамп Младший), создатель платформы и сообщества ИИ-офис, автор блога о нейросетях «Выжимаем из ИИ Максимум».
