AGENTS.md что это и чем отличается от CLAUDE.md

AGENTS.md и CLAUDE.md: что это, кто читает и какой выбрать

AGENTS.md — обычный Markdown-файл в корне репозитория с инструкциями для ИИ-агентов: как собирать, тестировать, какие соглашения соблюдать. CLAUDE.md делает то же самое для Claude Code, и с версии 2.1.277 Claude Code умеет читать AGENTS.md сам, но только если CLAUDE.md в проекте нет.

Что такое AGENTS.md

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

Формат курирует Agentic AI Foundation при Linux Foundation. На agents.md перечислены 23 продукта, среди них Codex, Cursor, Gemini CLI, GitHub Copilot coding agent, Windsurf, Zed, Aider, Devin и Junie. Сайт пишет, что AGENTS.md используют «больше 60 тысяч open-source проектов», но метод подсчёта не раскрыт. Поиск GitHub по имени файла на 24.10.2026 даёт 1 153 024 файла AGENTS.md, это файлы, а не репозитории.

Кто читает AGENTS.md, а кто CLAUDE.md

АгентЧто читаетОсобенностьClaude CodeCLAUDE.md; AGENTS.md с v2.1.277AGENTS.md только при отсутствии CLAUDE.md, .claude/CLAUDE.md и CLAUDE.local.mdCodexAGENTS.override.md, AGENTS.mdсклеивает от корня git до текущей папки, лимит 32 KiB; CLAUDE.md только через project_doc_fallback_filenamesCursorAGENTS.md в корне и подпапкахвложенные складываются с родительскимиGitHub CopilotAGENTS.md; в корне также CLAUDE.md и GEMINI.mdcloud agent и CLI читают все три, VS Code Chat только AGENTS.mdGemini CLIGEMINI.mdAGENTS.md только если добавить его в context.fileNameOpenCodeAGENTS.mdесли его нет, берёт CLAUDE.mdZedпервый файл из списка.rules, .cursorrules, …, AGENTS.md, CLAUDE.md, GEMINI.md: работает только первое совпадениеKiro, Windsurf (Devin Desktop), Cline, JunieAGENTS.mdу каждого есть и свой формат правил

Полная матрица с путями — в гайде по форматам.

Как Claude Code работает с CLAUDE.md и AGENTS.md

CLAUDE.md бывает на четырёх уровнях: managed-файл организации, личный ~/.claude/CLAUDE.md, проектный ./CLAUDE.md или ./.claude/CLAUDE.md и локальный ./CLAUDE.local.md, который в git не коммитят. Файлы не перекрывают друг друга, а склеиваются: от корня файловой системы к текущей папке. CLAUDE.md из подпапок подгружаются, когда Claude открывает файлы в этой подпапке.

С v2.1.277 у Claude Code есть встроенный плагин чтения AGENTS.md. В режиме по умолчанию он читает AGENTS.md, только если выше и в текущей папке нет ни CLAUDE.md, ни .claude/CLAUDE.md, ни CLAUDE.local.md. Подвох в последнем: личный CLAUDE.local.md тоже отключает AGENTS.md. Режим claude-md-and-agents-md грузит оба файла; переключается в /config → Project instructions.

Старый и по-прежнему документированный способ — мост. Одна строка в CLAUDE.md:

@AGENTS.md

Импорт раскрывает файл целиком. Глубина вложенных импортов до четырёх уровней.

Какой длины должен быть CLAUDE.md

Документация Anthropic советует держать каждый CLAUDE.md короче 200 строк. Импорты контекст не экономят: импортированный файл грузится вместе с основным.

Часто цитируют цифру «модели надёжно держат 150–200 инструкций». Это оценка из блога HumanLayer «Writing a good CLAUDE.md» (25.11.2025), а не результат исследования. Блог ссылается на работу IFScale (arXiv 2507.11538), но в её аннотации такой цифры нет: там проверяли до 500 инструкций, и лучшие модели при 500 давали 68 % точности. Сам HumanLayer держит корневой CLAUDE.md короче 60 строк.

Ещё одна вещь, которую стоит знать: CLAUDE.md — это контекст, а не принудительная настройка. Документация прямо советует ставить запреты хуком PreToolUse. Строчка «никогда не трогай prod» в CLAUDE.md работает до первого случая, когда модель сочтёт иначе.

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

Команды сборки, тестов и линтера, ровно в том виде, в каком их надо запускать.
Структуру репозитория: где код, где тесты, что генерируется и не правится руками.
Соглашения, которые агент не выведет из кода: как называть ветки, куда писать миграции.
Запреты, но дублировать их хуком, если нарушение стоит дорого.

Не стоит писать то, что агент и так видит в коде, и общие пожелания вроде «пиши чистый код». Каждая строка уходит в контекст каждого запроса.

Если CLAUDE.md ещё нет, команда /init в Claude Code сгенерирует черновик по коду проекта. Его почти всегда стоит сократить вдвое.

Что выбрать: AGENTS.md или CLAUDE.md

Работаете один и только в Claude Code — хватит CLAUDE.md. Если в команде два и больше агентов (Claude Code и Cursor, Claude Code и Codex), держите общий AGENTS.md как источник правды и CLAUDE.md из одной строки @AGENTS.md плюс то, что касается только Claude. Так правила не разъедутся.

Для зоопарка из пяти агентов есть генераторы, которые раскладывают один источник по нативным форматам: rulesync, ruler, block/ai-rules. Они описаны в гайде по форматам. Готовые файлы правил для изучения есть в разделе правил.

Частые вопросы

Для чего нужен AGENTS.md?

Чтобы один файл с инструкциями о проекте понимали разные ИИ-агенты: Codex, Cursor, Copilot, OpenCode, Zed и другие. Туда пишут команды сборки и тестов, структуру репозитория и соглашения.

Читает ли Claude Code файл AGENTS.md?

С версии 2.1.277 да, но по умолчанию только если в проекте нет CLAUDE.md, .claude/CLAUDE.md и CLAUDE.local.md. Иначе добавьте в CLAUDE.md строку @AGENTS.md или включите режим claude-md-and-agents-md.

Где должен лежать CLAUDE.md?

В корне проекта (./CLAUDE.md или ./.claude/CLAUDE.md), личный в ~/.claude/CLAUDE.md. Локальные заметки, которые не коммитят, кладут в CLAUDE.local.md.

Как создать CLAUDE.md?

Запустите /init в Claude Code: он сгенерирует черновик по коду проекта. Потом сократите его до того, что агент не может узнать из кода сам. Anthropic советует держать файл короче 200 строк.

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

Команды сборки, тестов и линтера, структуру репозитория, неочевидные соглашения и запреты. Общие пожелания вроде «пиши хороший код» только тратят контекст.