AGENTS.md: что это, примеры файла и как подключить в Cursor, Codex и Claude Code

Проверено по официальной документации Cursor, Codex, Claude Code, opencode и Devin Desktop 12 октября 2026 года.

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

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

Формат открытый, его описание лежит на agents.md. Над форматом вместе работали OpenAI Codex, Amp, Jules от Google, Cursor и Factory, а сейчас его курирует Agentic AI Foundation при Linux Foundation. По данным сайта, на 12 октября 2026 года AGENTS.md используют более 60 тысяч open-source проектов.

Обязательных полей нет. Это обычный Markdown: заголовки и списки, какие удобно. Агент просто читает текст.

Какие агенты читают AGENTS.md#

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

Пара деталей из той же документации. У Codex общий размер всех файлов инструкций по умолчанию ограничен 32 КиБ: то, что не влезло, агент не увидит.

Claude Code и AGENTS.md: как не дублировать

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

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

Чтобы этого не было без настроек, есть два способа:

1. Импорт. Первой строкой CLAUDE.md пишете @AGENTS.md, ниже добавляете то, что нужно только Claude Code. Claude Code сначала прочитает AGENTS.md, потом остальное. Этот способ работает везде.
2. Симлинк (ссылка на файл): команда ln -s AGENTS.md CLAUDE.md в корне проекта. Подходит, если своих правил для Claude Code нет. Если кто-то работает с проектом на Windows, документация советует импорт: симлинк там создаётся только с правами администратора или в режиме разработчика, а git без особой настройки скачает его как обычный текстовый файл в одну строку.

Проверить, какие файлы загрузились, можно командой /context в сессии Claude Code: загруженные файлы перечислены в разделе Memory files.

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

Cursor понимает оба варианта. AGENTS.md — простой Markdown без настроек, документация Cursor так его и описывает: простая замена .cursor/rules для несложных случаев. Правила в .cursor/rules — это файлы .mdc с заголовком-настройкой, где можно указать, к каким файлам правило относится и когда его подключать. Обычный .md в папке .cursor/rules Cursor игнорирует. Если проект открывают в разных агентах, общее держите в AGENTS.md, а в .mdc оставьте только правила для отдельных типов файлов. Подробности — в документации Cursor о правилах.

Что писать в AGENTS.md#

Хороший файл отвечает на вопросы, которые новый разработчик задал бы в первый день. Обычно хватает семи разделов:

1. О проекте. Одно-два предложения: что это и для кого. Агенту это помогает понять, какие решения уместны.
2. Команды. Как установить зависимости, запустить, собрать, прогнать тесты и линтер (программу, которая проверяет стиль кода). Это самый полезный раздел: по документации agents.md агент сам запускает перечисленные проверки и исправляет ошибки до того, как скажет «готово».
3. Структура папок. Где страницы, где компоненты, где данные. Только то, что не очевидно из названий.
4. Стиль кода. Только то, что отличается от общепринятого: язык, именование, формат.
5. Секреты и безопасность. Где лежат ключи и что их нельзя писать в код.
6. Что не трогать. Сгенерированные файлы, чужие модули, настройки деплоя.
7. Как проверить работу. Что должно пройти, прежде чем агент отчитается.

Пишите конкретно, так чтобы правило можно было проверить. «Запускай npm test перед коммитом» работает, «тестируй изменения» — нет. Документация Claude Code приводит такие же примеры и советует держать файл коротким: длинный файл занимает больше контекста, и агент хуже его соблюдает.

Когда обновлять файл

AGENTS.md не пишут один раз навсегда. Удобное правило: если вы второй раз поправили агента в одном и том же, это правило пора внести в файл. Например, агент дважды положил компонент не в ту папку, значит, в разделе «Структура» не хватает строки.

Обновляйте файл и тогда, когда меняется сам проект: поменялась команда сборки, появилась новая папка, переехал хостинг. Устаревшая команда в AGENTS.md хуже, чем никакой: агент честно её запустит, получит ошибку и начнёт чинить то, что не сломано. Изменения в AGENTS.md коммитьте вместе с кодом, тогда в истории репозитория видно, когда и почему правило появилось.

Что не писать

• Секреты. Токены, пароли и ключи не кладут в AGENTS.md: файл лежит в репозитории, и его видят все, у кого есть доступ.
• Пересказ документации. Агент и так знает npm, git и pytest. Объяснять, как ими пользоваться, не нужно: пишите только то, что особенно в вашем проекте.
• То, что видно из кода. Список зависимостей есть в package.json, дерево всех папок агент увидит сам. Лучше сошлитесь на файл, чем копируйте его содержимое.
• Устаревшие правила. Если правило больше не действует, удалите его. Два противоречащих правила хуже, чем ни одного: агент выберет одно наугад.

Пустой шаблон AGENTS.md#

Скопируйте и заполните места в квадратных скобках. Разделы, которые вам не нужны, удалите.

# AGENTS.md

## О проекте
[Что это и для кого, 1–2 предложения]

## Команды
- Установка: [например, npm install]
- Запуск для разработки: [команда]
- Сборка: [команда]
- Тесты: [команда или «тестов пока нет»]
- Линтер: [команда или «нет»]

## Структура
- [папка]/ — [что в ней лежит]
- [папка]/ — [что в ней лежит]

## Стиль кода
- [Язык и версия, если важно]
- [Правило, которое отличается от общепринятого]

## Секреты
- Ключи и токены только в [.env или переменных окружения хостинга]
- Никогда не пиши секреты в код и в этот файл

## Что не трогать
- [Файлы или папки, которые агент не меняет без просьбы]

## Перед тем как сказать «готово»
- [Какие команды должны пройти без ошибок]
- Коротко перечисли, какие файлы изменил и зачем

Почему так:

• Порядок разделов повторяет то, что агенту нужно в работе: понять проект, запустить, найти файлы, не сломать.
• Раздел «готово» превращает общие слова в проверку: агент знает, что запустить перед отчётом.
• Строка про отчёт по файлам помогает вам быстро понять, что изменилось.

Где лежит файл и вложенные AGENTS.md#

Основной AGENTS.md кладут в корень репозитория, рядом с README. В большом проекте можно положить ещё один файл в подпапку, например в frontend/ или bot/. Тогда в этой папке действуют её собственные правила.

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

• Codex собирает файлы от корня до текущей папки и склеивает их. Более близкие идут последними и поэтому перекрывают общие правила. В одной папке он берёт один файл, причём AGENTS.override.md важнее AGENTS.md.
• Cursor объединяет вложенный файл с файлами родительских папок, и более конкретные инструкции важнее.
• Devin Desktop включает корневой файл всегда, а вложенный — только когда агент читает или правит файлы в этой папке.
• Claude Code читает вложенный AGENTS.md, когда открывает файл в этой папке, если там нет своего CLAUDE.md.

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

Пример 1: AGENTS.md для лендинга#

Одностраничный сайт на HTML и Tailwind, форма заявки отправляется через внешний сервис форм.

# AGENTS.md

## О проекте
Одностраничный сайт [название]: рассказывает об услуге и собирает
заявки через форму.

## Команды
- Установка: npm install
- Разработка: npm run dev
- Сборка: npm run build (скрипты описаны в package.json)

## Структура
- index.html — вся страница
- src/styles.css — подключение Tailwind и свои стили
- images/ — картинки, только сжатые webp или jpg

## Правила
- Не добавляй фреймворки, библиотеки и npm-пакеты без моей просьбы.
- Стили пиши классами Tailwind. Отдельный CSS только там, где без него никак.
- Вёрстка адаптивная: проверяй ширину 360 px и 1280 px.
- Все тексты на русском, не придумывай отзывы, цифры и контакты.

## Форма
- Форма отправляется на [адрес сервиса форм].
- Ключ сервиса, если он нужен, только в переменной окружения
  [ИМЯ_ПЕРЕМЕННОЙ]. В код и в этот файл ключ не пиши.

## Перед тем как сказать «готово»
- npm run build проходит без ошибок.
- Страница открывается, в консоли браузера нет ошибок.
- Форма отправляется, после отправки видно сообщение об успехе.
- Перечисли, какие файлы изменил.

Почему так написано:

• Запрет на новые пакеты стоит отдельной строкой. Без него агент легко тянет в маленький лендинг целый фреймворк.
• Ширины для проверки указаны числами, поэтому агент может проверить их сам, а не «сделать адаптивно».
• Правило «не придумывай отзывы и контакты» нужно для лендинга: агенты любят заполнять пустые блоки выдуманным текстом.
• Ключ формы вынесен в переменную окружения, а в файле указано только её имя.

Как такой файл работает в настоящем проекте сайта, показано в разделе сайт с нейросетью.

Пример 2: AGENTS.md для Telegram-бота#

Бот на Python и aiogram 3, получает сообщения через polling (бот сам регулярно спрашивает Telegram о новых сообщениях).

# AGENTS.md

## О проекте
Telegram-бот [название]: [что делает, одно предложение].

## Команды
- Окружение: python -m venv .venv, потом активируй его
- Зависимости: pip install -r requirements.txt
- Запуск: python [main.py]

## Структура
- [main.py] — запуск бота
- handlers/ — обработчики команд и сообщений, один файл на тему
- [config.py] — чтение настроек из окружения

## Правила
- Библиотека aiogram 3. Не переходи на другую библиотеку и не смешивай
  с примерами для aiogram 2.
- Бот работает через polling. Не меняй на вебхук без моей просьбы.
- Новый обработчик — новый файл в handlers/, подключи его в [main.py].
- Новые зависимости добавляй в requirements.txt и объясняй, зачем они.

## Секреты
- Токен бота только в файле .env, переменная BOT_TOKEN.
- .env должен быть в .gitignore. Проверь это, прежде чем что-то коммитить.
- Никогда не выводи токен в лог и в ответ.

## Перед тем как сказать «готово»
- Бот запускается без ошибок.
- Бот отвечает на /start.
- Ошибки пишутся в лог, бот не падает молча.
- Перечисли, какие файлы изменил.

Почему так написано:

• Версия библиотеки указана явно. В интернете много примеров для старой версии aiogram, и без этой строки агент может их смешать.
• Запрет менять polling на вебхук защищает от лишней переделки: вебхук требует сервера с адресом и сертификатом.
• Блок про .env и .gitignore стоит отдельно, потому что утёкший токен бота — самая частая и неприятная ошибка.
• Проверка «бот отвечает на /start» простая, но её агент может выполнить и описать.

Как устроен файл в проекте бота целиком, смотрите в разделе Telegram-бот с нейросетью.

Пример 3: монорепо — корневой и вложенный AGENTS.md#

Монорепо — один репозиторий, где лежит несколько частей проекта, например сайт и бот. Корневой файл описывает общее, вложенные уточняют каждую часть.

Корневой AGENTS.md:

# AGENTS.md

## О проекте
Репозиторий [название]: сайт в папке site/ и Telegram-бот в папке bot/.

## Общие правила
- Работай только в той части, о которой я прошу. Не правь site/,
  если задача про bot/, и наоборот.
- Секреты только в .env внутри каждой части. .env не коммить.
- Новые зависимости добавляй только с объяснением.

## Как запустить
- Сайт: смотри site/AGENTS.md
- Бот: смотри bot/AGENTS.md

## Перед тем как сказать «готово»
- Выполни проверки из AGENTS.md той части, которую менял.
- Перечисли изменённые файлы.

Вложенный bot/AGENTS.md:

# AGENTS.md для бота

## Команды
- Все команды запускай из папки bot/.
- Зависимости: pip install -r requirements.txt
- Запуск: python [main.py]

## Правила
- aiogram 3, polling. Вебхук не включай без просьбы.

## Перед тем как сказать «готово»
- Бот запускается и отвечает на /start.

Почему так написано:

• Вложенный файл не повторяет правила про секреты и зависимости: они уже есть в корневом и действуют везде.
• Корневой файл не описывает команды частей, а отправляет к их файлам. Так команды лежат в одном месте и не расходятся.
• Правило «работай только в нужной части» защищает от правок в соседней папке, которых вы не просили.

Как проверить, что агент прочитал файл#

Самый простой способ работает в любом инструменте. Откройте новый чат и спросите агента, ничего не объясняя:

Какой командой ты проверишь, что проект собирается?
И что тебе нельзя делать в этом проекте?

Если агент назвал команду из вашего AGENTS.md и правила из раздела «что не трогать», файл подключён. Если отвечает общими словами или предлагает команду, которой в проекте нет, файл не прочитан.

Есть и способы конкретных инструментов:

• Claude Code. Если CLAUDE.md в проекте нет, при старте сессии появляется строка no CLAUDE.md found; AGENTS.md loaded: с путём к файлу. Команда /context показывает загруженные файлы в разделе Memory files.
• Codex. Документация советует запустить codex --ask-for-approval never "Summarize the current instructions.", то есть попросить его пересказать текущие инструкции.

Один проект — три файла: AGENTS.md, CLAUDE.md и .cursor/rules#

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

• AGENTS.md — всё основное: команды, структура, правила, проверка. Его читают Cursor, Codex, opencode и Devin Desktop.
• CLAUDE.md — первая строка @AGENTS.md, ниже только то, что нужно одному Claude Code.
• .cursor/rules/*.mdc — только правила для отдельных типов файлов, например для компонентов или тестов. Общие правила сюда не копируйте.

CLAUDE.md в три строки выглядит так:

@AGENTS.md

## Только для Claude Code
- Перед изменениями в [папка] сначала предложи план и дождись ответа.

Почему так:

• Правила живут в одном месте, и при изменении их нужно поправить один раз.
• Импорт @AGENTS.md работает и тогда, когда Claude Code не может прочитать AGENTS.md сам.
• Во втором блоке остаётся место для того, что есть только в Claude Code. Подробности — в документации Claude Code.

Как получить AGENTS.md автоматически#

Писать файл с нуля необязательно. Есть два способа:

• Попросить агента. Codex, Claude Code и opencode умеют составить файл по коду проекта: в opencode и Claude Code для этого есть команда /init (Claude Code создаёт CLAUDE.md). Готовый запрос, после которого агент сам составит AGENTS.md и задаст вопросы о том, чего не видно в коде: промт для создания AGENTS.md.
• Взять пример со страницы и поправить под себя.

Что бы вы ни выбрали, прочитайте результат. Агент не знает того, чего нет в коде: что нельзя трогать, куда уходят заявки, какие правила у бизнеса. Это допишите сами. Что оставить в ТЗ, а что перенести в AGENTS.md, разобрано в статье ТЗ для нейросети.