AGENTS.md (инструкции для ИИ-агента): что это и как работает

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

Сайт стандарта agents.md называет его «README для агентов»: README пишется для людей, а AGENTS.md собирает то, что нужно агенту и только загромоздило бы README, например точные команды запуска тестов и негласные договорённости команды. Формат открытый, стандарт сейчас ведёт Agentic AI Foundation при Linux Foundation, а по данным сайта им пользуются более 60 тысяч открытых проектов.

Зачем появился AGENTS.md

Раньше у каждого агента был свой файл настроек: CLAUDE.md, .cursorrules, .windsurfrules, .github/copilot-instructions.md. Если в команде работали с несколькими инструментами, одни и те же правила копировали в пять файлов и потом рассинхронизировали. AGENTS.md предлагает один файл, который читают разные агенты. Список поддерживающих инструментов на agents.md включает Codex, Jules, Aider, goose, opencode, Zed, Warp, VS Code, Gemini CLI, Cursor, Windsurf, GitHub Copilot coding agent и другие.

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

Как это работает

1. Чтение при старте. Агент находит AGENTS.md и добавляет его текст в системный контекст сессии. Модель «знает» проект, ещё не открыв ни одного файла.
2. Расход токенов. Файл входит в запрос на каждом шаге цикла агента. Это input-токены: чем длиннее файл, тем больше они стоят, если провайдер не кэширует неизменный префикс. Поэтому AGENTS.md должен быть коротким.
3. Вложенные файлы. В монорепозитории можно положить AGENTS.md в каждый подкаталог. По FAQ agents.md ближайший к редактируемому файлу выигрывает, а явная просьба в чате важнее любого файла.
4. Конфликты. Общее правило такое: чем ближе файл к рабочему каталогу, тем выше приоритет, а прямая инструкция пользователя сильнее файла. Детали различаются по инструментам.

Как это устроено в конкретных агентах:

Подробности установки и подключения этих агентов к RouterAI — в гайдах по Claude Code, Codex, Cline, OpenCode и Hermes Agent.

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

Полезные разделы:

• Обзор проекта. Одна-две фразы: что делает приложение и на чём написано.
• Команды. Как установить зависимости, запустить, прогнать тесты и линтер. Это самое ценное: без них агент угадывает или тратит шаги на поиск по package.json.
• Структура. Где лежит код, где тесты, что генерируется автоматически.
• Стиль кода. Только то, что нельзя вывести из самого кода или конфигурации линтера.
• Границы. Что не трогать: сгенерированные файлы, миграции, секреты, внешние API. Чего не делать без вопроса, например добавлять зависимости.
• Проверки перед коммитом. Какие команды должны пройти до того, как агент объявит задачу выполненной.

Плохой файл длинный и размытый:

# Project

Мы любим чистый код. Пишите качественно, соблюдайте best practices,
тестируйте всё, не ломайте существующее. Код должен быть читаемым.

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

# AGENTS.md

## Команды
- Установка: `npm install`
- Тесты: `npm test` (запускает `node --test`)
- Один файл: `node --test invoices.test.js`

## Границы
- Не добавляй зависимости без согласования.
- Не меняй формат данных в `invoices.js` без обновления тестов.

Рабочее правило: если строку можно удалить и агент всё равно сделает то же самое, её не стоит держать в файле.

Чем AGENTS.md отличается от Skills, MCP и промпта

Практический выбор: то, что верно для проекта всегда и коротко, пишите в AGENTS.md. Длинные процедуры, нужные раз в неделю, оформляйте как навык, чтобы они не расходовали токены в остальное время. Всё, что требует действия во внешней системе, подключайте через MCP. А «в этот раз сделай иначе» оставляйте в промпте: он по определению важнее файла.

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

AGENTS.md и RouterAI

RouterAI не читает AGENTS.md: файл обрабатывает сам агент, а до модели он доходит как часть запроса. Поэтому всё сказанное выше работает одинаково при любом способе подключения: агент к RouterAI по OpenAI-совместимому API https://routerai.ru/api/v1 или по Anthropic Messages API https://routerai.ru/api. Работа из России без VPN, оплата в рублях, один ключ на все модели из каталога.

Что это даёт при работе через RouterAI:

• Меньше шагов. Когда в файле указаны команды запуска тестов и структура проекта, агент не тратит вызовы модели на разведку. Каждый вызов оплачивается по токенам, поэтому лишние шаги стоят денег.
• Короткий файл дешевле. Текст AGENTS.md входит в запрос каждого шага, так что 200 лишних строк умножаются на число шагов в сессии. Стоимость токенов смотрите в каталоге: она зависит от модели.
• Один файл на несколько моделей. Если вы переключаете агента между anthropic/claude-sonnet-5.5, openai/gpt-5.5 и deepseek/deepseek-v4-flash, правила проекта остаются теми же.

Практика: AGENTS.md для демо-проекта

Возьмём небольшой Node-проект «Invoices»: app.js, invoices.js, invoices.test.js и package.json со скриптами start и test. Для него хватает такого файла:

# AGENTS.md

Учебный Node.js-проект: хранилище счетов (`invoices.js`) и точка входа (`app.js`).

## Команды
- Запуск: `npm start`
- Тесты: `npm test` (встроенный раннер `node --test`)

## Структура
- `invoices.js` — данные и функции работы со счетами
- `invoices.test.js` — тесты, лежат рядом с кодом

## Стиль
- CommonJS (`require` / `module.exports`), без сторонних библиотек.
- Комментарии на русском.

## Границы
- Не добавляй зависимости в `package.json`.
- Не меняй существующие поля счетов, только добавляй новые.

## Перед коммитом
- Для любой новой функции добавь тест и запусти `npm test`.

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

1. Положите AGENTS.md в корень проекта и запустите агента в этом каталоге. Для Codex есть документированная проверка: codex --ask-for-approval never "Summarize the current instructions." — агент должен процитировать пункты из файла.
2. В других агентах попросите: «Перечисли инструкции проекта, которые ты загрузил, и откуда». Если ответ пересказывает общие советы, а не строки из файла, агент его не увидел.
3. В Claude Code при отсутствии CLAUDE.md в начале сессии выводится строка вида no CLAUDE.md found; AGENTS.md loaded: ....
4. Для надёжности временно добавьте в файл необычное правило («в конце ответа пиши слово "ёжик"»), убедитесь, что агент его выполняет, и удалите.

Если агент не видит файл, чаще всего он запущен не из каталога проекта, файл назван AGENT.md вместо AGENTS.md, либо у инструмента приоритетнее другой файл (в Claude Code это CLAUDE.md, в Hermes Agent .hermes.md).

Связанные термины

• Agent Skills — навыки, которые подгружаются только по необходимости
• MCP — подключение внешних инструментов
• Agent Harness — обвязка, которая читает AGENTS.md и собирает контекст
• Agent Memory — память, которую агент копит сам
• Контекст-инжиниринг — как управлять тем, что видит модель
• Вайб-кодинг — работа с coding-агентами в целом

Что почитать

• agents.md — сайт стандарта, примеры и список поддерживающих агентов
• Custom instructions with AGENTS.md — как Codex собирает цепочку инструкций
• Cline Rules — правила и поддержка AGENTS.md в Cline
• OpenCode Rules — порядок поиска файлов и команда /init
• Claude Code: memory и AGENTS.md — когда Claude Code читает AGENTS.md