20 сентября 2026 г.
AGENTS.md: один файл-инструкция, который читают все ИИ-кодеры
AGENTS.md - это обычный markdown-файл в корне репозитория, куда ты один раз пишешь, как устроен проект: чем собирать, чем тестировать, какие правила в коде, что трогать нельзя. ИИ-агент читает его перед работой и перестаёт спрашивать очевидное на каждой задаче. Смысл - один файл вместо отдельной инструкции под каждый инструмент. С 18 сентября его читает и Claude Code.
Звучит как мелочь, но за этим форматом уже стоят десятки тысяч проектов и почти все крупные кодинг-агенты. И то, что к ним присоединился Claude Code, - хороший повод разобраться, что это за файл, что в него класть и зачем он тебе, если ты гоняешь ИИ по своему коду.
Зачем вообще ещё один файл в проекте
Модель из коробки не знает твой репозиторий. Она не в курсе, что тесты у тебя запускаются одной командой, а не той, что она привыкла видеть, что в проекте camelCase, а не snake_case, и что папку с миграциями трогать нельзя вообще никогда. Пока ты это не сказал - агент угадывает. А угадывает он ровно так, как «принято в среднем по интернету», и половину времени мимо.
Решение придумали быстро: положить рядом с кодом текстовый файл с правилами, который агент подхватывает автоматически. Проблема была в другом. Каждый инструмент завёл свой формат. У Claude Code это CLAUDE.md, у Cursor - .cursorrules, у Copilot - .github/copilot-instructions.md, и так далее. Работаешь в одном проекте двумя-тремя агентами - держи три файла с одним и тем же содержимым и синхронизируй их руками. Классическая ситуация, когда у тебя не один источник правды, а три, и все чуть-чуть разошлись.
AGENTS.md родился как раз чтобы это схлопнуть. Один файл, который договорились читать все. Не замена README - тот по-прежнему для людей: описание проекта, быстрый старт, как контрибьютить. AGENTS.md - для агентов: сюда идёт та детальная техническая конкретика, которую человеку в README пихать незачем, а машине она нужна.
Что реально кладут в AGENTS.md
Формат максимально простой: это markdown, заголовки любые, никакой обязательной схемы. Но по факту устоялся набор секций, которые встречаются чаще всего.
- Обзор проекта - пара строк про архитектуру и стек, чтобы агент понимал, куда попал.
- Команды сборки и запуска - как поставить зависимости, как поднять дев-сервер.
- Тесты - какой командой гонять, как запустить один тест, а не весь прогон.
- Стиль кода - соглашения, которые не ловит линтер: именование, длина строки, паттерны.
- Безопасность и границы - что трогать нельзя: секреты, миграции, сгенерированный код.
- Правила коммитов и PR - формат сообщений, что должно быть зелёным перед мержем.
Главный совет от тех, кто это уже накатал на больших репозиториях: пиши команды, а не сочинение. Агенту полезнее строка npm test -- --watch=false, чем абзац про то, как важно тестировать. И не дублируй то, что и так проверяет линтер, - это шум. В файл идёт то, чего в коде нигде не видно: архитектурные решения, неочевидные ограничения, грабли конкретно этого проекта.
Откуда он взялся и кто им теперь рулит
Важный момент: это не стандарт одного вендора, который завтра передумает. Формат вырос из общей работы команд за OpenAI Codex, Amp, Google Jules, Cursor и Factory - то есть люди, которые делают конкурирующие инструменты, сели и договорились об общем файле. Сейчас стандартом рулит Agentic AI Foundation под крылом Linux Foundation. То же место, где живут другие открытые инфраструктурные штуки, - значит, формат не принадлежит никому лично и не исчезнет вместе с настроением одной компании.
Масштаб уже приличный. По данным самого проекта, AGENTS.md завели больше 60 тысяч открытых репозиториев, а читают его больше двадцати кодинг-инструментов: Codex, Cursor, Jules, Gemini CLI, Aider, агент внутри GitHub Copilot, Devin, Windsurf и дальше по списку. Для формата, которому пары лет нет, это уже фактический индустриальный стандарт, а не эксперимент.
Claude Code теперь тоже его читает
До недавнего времени Claude Code был белой вороной: читал только свой CLAUDE.md и в официальном списке совместимости с AGENTS.md не значился. В версии 2.1.277 от 18 сентября 2026 это починили.
Логика по умолчанию такая: если в проекте нет CLAUDE.md, Claude Code читает AGENTS.md вместо него. Есть свой файл - работает по нему, как раньше. То есть это режим подстраховки, а не слияния: два файла разом по умолчанию он не мержит. Поведение настраивается в /config в разделе «Project instructions» - там можно выбрать, читать только CLAUDE.md, использовать AGENTS.md как запасной, грузить оба формата или ограничиться централизованными инструкциями.
Монорепо: побеждает ближайший файл
Отдельно про большие проекты. AGENTS.md можно класть не только в корень. В монорепе кладёшь по файлу в каждый пакет, и агент читает тот, что ближе всего к правящемуся коду: ближайший в дереве каталогов побеждает. Корневой файл задаёт общие правила, а внутри пакета - уточнения именно под него.
Это не теория ради теории. В репозитории самого OpenAI, например, таких файлов 88 штук - на каждый серьёзный подпроект свой набор инструкций. Тебе столько вряд ли нужно, но принцип полезно держать в голове: если один общий файл начинает противоречить сам себе для разных частей проекта, разнеси его по папкам.
Как завести за пять минут
Порядок простой. Создаёшь в корне репозитория файл AGENTS.md. Пишешь туда обзор проекта в пару строк, команды установки и запуска, команду тестов, ключевые соглашения по стилю и список того, что трогать нельзя. Коммитишь вместе с кодом - файл живёт в репозитории, а не в настройках конкретной машины, поэтому работает у всех и во всех агентах сразу.
Если раньше вёл CLAUDE.md или .cursorrules - перенеси содержимое в AGENTS.md, суть у них одна. У многих инструментов есть команда инициализации: например, /init в Codex сам набросает стартовый AGENTS.md по проекту, дальше правишь руками. И держи файл живым: как только замечаешь, что агент второй раз наступает на одни грабли, - это сигнал дописать строку, а не молча исправлять за ним.
Где подвох
Честно про ограничения. Первое: файл читают все, но по-разному. Claude Code берёт его только как запасной, при отсутствии CLAUDE.md, - у других инструментов свои нюансы приоритета. Если ведёшь оба файла, следи, чтобы они не разъехались, иначе получишь ровно ту проблему с тремя источниками правды, от которой уходил.
Второе: AGENTS.md - это подсказка, а не гарантия. Агент читает инструкцию и обычно ей следует, но это не жёсткое правило на уровне кода. Написал «не трогай миграции» - в девяти случаях из десяти не тронет, но настоящую защиту важных вещей делай правами доступа и ревью, а не строчкой в markdown.
Третье: раздутый файл вредит. Если напихать туда всё подряд, включая то, что и так очевидно из кода или ловится линтером, ты просто зашумляешь контекст и жрёшь токены без пользы. Короткий файл с командами и реальными граблями работает лучше, чем простыня на три экрана.
Вывод простой. AGENTS.md - это разумная гигиена, если ты работаешь с ИИ-агентами по коду. Один файл, который понимают почти все инструменты, живёт в репозитории и экономит тебе объяснения на каждой задаче. Заводится за пять минут, а с подключением Claude Code читать его теперь умеет и лагерь Anthropic.
