Автор: Matt Connor 2026-09-19

Читает ли Claude Code AGENTS.md, если есть CLAUDE.md

Q: Почему AGENTS.md не загружается, хотя CLAUDE.md в репозитории нет?

Чаще всего виноват CLAUDE.local.md, который считается наравне с CLAUDE.md, или CLAUDE.md в родительском каталоге. Вторая причина: сессия не запрашивает feature flags. Это Bedrock, Vertex AI, Foundry, отключённая телеметрия, первая сессия после обновления или disableAllHooks. Признак: в /config нет пункта Project instructions. В таких сессиях положите рядом CLAUDE.md с импортом @AGENTS.md.

Q: Влияет ли это на ~/.claude/CLAUDE.md, память и хуки?

Нет. Пользовательский ~/.claude/CLAUDE.md, ~/.claude/rules/ и управляемый CLAUDE.md организации загружаются как раньше и не отключают AGENTS.md. Автопамять работает отдельно. Хуки работают, кроме одного случая: InstructionsLoaded не срабатывает для AGENTS.md, прочитанного напрямую, но срабатывает для AGENTS.md, импортированного из CLAUDE.md.

С версии 2.1.277 Claude Code читает AGENTS.md, но только если нет CLAUDE.md. Правило, переключатель в /config, исключения для Bedrock и две схемы для репозитория с Codex и Cursor.

Короткий ответ

Начиная с Claude Code 2.1.277, которая вышла 18 сентября 2026 года, Claude Code читает AGENTS.md. Но только как запасной вариант: если в проекте есть CLAUDE.md, читается он, а AGENTS.md игнорируется. Если CLAUDE.md нет, вместо него читается AGENTS.md. Поведение переключается в /config в пункте Project instructions. На Amazon Bedrock, Google Vertex AI и Microsoft Foundry этот запасной вариант пока не работает, там по-прежнему нужен импорт @AGENTS.md из CLAUDE.md.

Формулировка из журнала изменений (changelog) звучит так: «Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead; change it under "Project instructions" in /config». Дальше разбираем, что именно считается «есть CLAUDE.md», как правило ведёт себя во вложенных папках и какую схему выбрать, если в одном репозитории живут Claude Code, Codex и Cursor.

Что считается «в проекте есть CLAUDE.md»

Проверка идёт по рабочему каталогу и всем каталогам выше него. Считаются три файла: CLAUDE.md, .claude/CLAUDE.md и CLAUDE.local.md. Если хотя бы один из них найден в рабочем каталоге или в любом родительском, Claude Code читает его и не трогает AGENTS.md.

Не считаются и загружаются вместе с AGENTS.md как раньше: пользовательский ~/.claude/CLAUDE.md, управляемый (managed) CLAUDE.md вашей организации и файлы из .claude/rules/.

Когда ни один из трёх файлов не найден, при старте сессии читаются все AGENTS.md и .claude/AGENTS.md в рабочем каталоге и выше. В интерактивной сессии это видно по строке в диалоге:

no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md

Не читаются никогда: AGENTS.local.md, AGENTS.override.md и всё, что лежит в каталоге .agents/. Внутри самого AGENTS.md импорты @путь раскрываются, а шаблоны claudeMdExcludes применяются, то есть файл обрабатывается по тем же правилам, что и CLAUDE.md.

Самая частая ловушка здесь: CLAUDE.local.md. Многие держат в нём личные инструкции, которые не попадают в git. Он считается наравне с CLAUDE.md, так что один такой файл в проекте, который живёт на AGENTS.md, отключает чтение AGENTS.md лично для вас. Коллеги без CLAUDE.local.md этого не заметят, а вы не получите никакой ошибки. Если нужен и личный файл, и AGENTS.md, переключите Project instructions в claude-md-and-agents-md, об этом ниже.

Вложенные папки: срабатывает ли правило на каждом уровне

В changelog написано только «in a project with no CLAUDE.md», без деталей про подкаталоги. Документация по памяти отвечает точнее. Для сессии в целом проверка одна: рабочий каталог и всё, что выше. Внутри проекта AGENTS.md подкаталога подгружается по требованию, когда Claude открывает там файл инструментом Read, и только если в этом подкаталоге нет ни одного из трёх файлов CLAUDE.md. То есть в проекте без корневого CLAUDE.md подкаталоги решают за себя: где лежит свой CLAUDE.md, читается он, где нет, читается AGENTS.md.

Обратное неверно. Если CLAUDE.md найден в рабочем каталоге или выше, весь механизм по умолчанию выключен, и AGENTS.md в подкаталогах тоже не читается. Режим claude-md-and-agents-md меняет это: тогда в каждом каталоге сначала читаются его CLAUDE.md, затем его AGENTS.md. Как раскладывать инструкции по пакетам монорепозитория, разобрано в отдельной статье про вложенные AGENTS.md в монорепозиториях.

Переключатель Project instructions в /config

Наберите /config в сессии и найдите пункт Project instructions. У него четыре значения:

claude-md-or-agents-md: CLAUDE.md, а если его нет, AGENTS.md. Это значение по умолчанию и то самое правило из первого абзаца.
claude-md-and-agents-md: оба файла, в каждом каталоге сначала CLAUDE.md, потом AGENTS.md. Уже загруженный AGENTS.md второй раз не читается, так что импорт или симлинк из CLAUDE.md не даёт дубля.
claude-md: только CLAUDE.md, поведение до 2.1.277.
managed-only: только управляемый CLAUDE.md организации и автопамять. Проектные, локальные и пользовательские CLAUDE.md, .claude/rules/ и все AGENTS.md при старте не загружаются.

То же самое можно задать в файле настроек. Значение живёт в pluginConfigs под идентификатором встроенного плагина agents-md@builtin: в ~/.claude/settings.json, в файле, переданном через --settings, или в управляемых настройках. В проектном .claude/settings.json и в settings.local.json оно игнорируется, так что задать его на уровне репозитория сразу для всей команды нельзя.

{
  "pluginConfigs": {
    "agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

Изменение применяется со следующего сообщения в текущей сессии и во всех новых.

Где запасной вариант не работает: Bedrock, Vertex AI, Foundry

Чтение AGENTS.md включается через feature flag, который Claude Code запрашивает у Anthropic при старте. Сессии, которые флаги не запрашивают, ведут себя как до 2.1.277: читают только CLAUDE.md, а пункт Project instructions в /config вообще не показывается. Документация прямо называет Amazon Bedrock и «любого другого стороннего провайдера», и Google Vertex AI с Microsoft Foundry попадают в ту же категорию. Так что если вы запускаете Claude Code через Bedrock или Vertex AI или подключаете Claude Code к Microsoft Foundry, одного AGENTS.md без CLAUDE.md для вас пока не существует.

Тот же эффект дают ещё три ситуации:

отключённая телеметрия, потому что вместе с ней отключается и запрос флагов;
первая сессия после установки или обновления до версии с поддержкой AGENTS.md: флаг подтягивается, и со следующей сессии всё работает;
disableAllHooks или allowManagedHooksOnly в настройках, а также выключенный в /plugin встроенный плагин agents-md.

Быстрый тест: наберите /config. Если пункта Project instructions там нет, ваша сессия из этого списка. Лечение одно и то же: положите рядом с AGENTS.md файл CLAUDE.md с импортом, это схема 2 ниже.

Две разумные схемы для репозитория с Codex и Cursor

Схема 1: один AGENTS.md и никакого CLAUDE.md

Самый переносимый вариант. AGENTS.md читают Codex, Cursor и GitHub Copilot, а Gemini CLI можно направить на него настройкой имени контекстного файла. С 2.1.277 Claude Code читает его же, и в репозитории лежит один файл инструкций вместо четырёх. Что в него писать, чтобы агент реально следовал написанному, разобрано в заметке про AGENTS.md и HUMAN.md.

Условия, при которых схема работает: ни у кого в команде нет CLAUDE.md, .claude/CLAUDE.md или CLAUDE.local.md в проекте и выше него, никто не работает через Bedrock, Vertex AI или Foundry, и все обновились до 2.1.277. Первое условие ломается тише всего: достаточно одному человеку создать CLAUDE.local.md, и у него AGENTS.md перестанет читаться, без единого предупреждения. Проверяйте по строке AGENTS.md loaded при старте.

Схема 2: тонкий CLAUDE.md, который импортирует AGENTS.md

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

@AGENTS.md

## Claude Code

Для изменений в `src/billing/` используй plan mode.

Claude читает сначала импортированный файл, потом остальное. Эта схема работает везде: на Bedrock, Vertex AI и Foundry, в режиме claude-md, на версиях старше 2.1.277. Она же правильный ответ, если CLAUDE.md в проекте уже есть и удалять его никто не хочет. И она безопасна при любом значении Project instructions: AGENTS.md, уже загруженный через импорт, повторно не читается.

Чего не делать: писать в CLAUDE.md фразу «прочитай AGENTS.md» словами. Тогда Claude увидит файл, только если сам решит его открыть. Либо удалите CLAUDE.md, либо замените фразу на импорт @AGENTS.md.

Симлинк: что это было и нужно ли теперь

До 2.1.277 стандартный обходной путь выглядел так:

ln -s AGENTS.md CLAUDE.md

Команда ничего не выводит при успехе, и Claude читает CLAUDE.md через ссылку. Если такой симлинк у вас уже есть, делать ничего не нужно: содержимое прочитается один раз при любом режиме. Можно и удалить, тогда сработает обычный запасной вариант. Для новых проектов симлинк смысла не имеет, у него два минуса. На Windows создание ссылки требует прав администратора или Developer Mode, а Git без core.symlinks выкачивает её как обычный текстовый файл с одной строкой, и у коллеги вместо инструкций окажется путь. Кроме того, инструменты Edit и Write отказываются писать через симлинк и отправляют Claude править AGENTS.md. Импорт @AGENTS.md не имеет ни одной из этих проблем.

Ещё один пережиток: хук SessionStart, который печатает AGENTS.md в контекст. Уберите его. С 2.1.277 он добавляет в контекст вторую копию файла, и вы платите за неё токенами каждую сессию. Как увидеть это в /context и что ещё занимает окно, показано в разборе управления контекстом Claude Code.

Что не меняется

Пользовательский ~/.claude/CLAUDE.md и ~/.claude/rules/ загружаются как раньше, при любом варианте: они не участвуют в проверке и не отключают AGENTS.md. Управляемый CLAUDE.md организации тоже. Автопамять (auto memory), которую Claude ведёт сам, живёт отдельно и от AGENTS.md не зависит. Хуки продолжают работать, за одним исключением: хук InstructionsLoaded не срабатывает для AGENTS.md, прочитанного напрямую через настройку. Для AGENTS.md, который подтянут импортом из CLAUDE.md, он срабатывает как обычно. Если у вас на этот хук что-то завязано, это ещё один довод в пользу схемы 2, а как вообще устроены хуки, объяснено в статье про хуки Claude Code.

Ещё два отличия напрямую прочитанного AGENTS.md. Он не показывается в /memory и в списке Memory files в /context. И каталоги, добавленные через --add-dir при включённом CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD, отдают свой CLAUDE.md, но не свой AGENTS.md.

Как проверить, что AGENTS.md действительно прочитан

Три способа. Первый: строка no CLAUDE.md found; AGENTS.md loaded: ... при старте интерактивной сессии. Второй: спросить Claude, что написано в его проектных инструкциях, и сравнить с файлом. Третий, от обратного: /context. Если там в Memory files есть CLAUDE.md, значит, он найден, и AGENTS.md по умолчанию не читался. Если AGENTS.md нигде не виден и строки при старте нет, ищите CLAUDE.md выше по дереву каталогов, проверяйте /config на значение claude-md или managed-only и вспоминайте, не через Bedrock ли вы работаете.

FAQ

Читает ли Claude Code AGENTS.md, если в проекте есть CLAUDE.md?

По умолчанию нет. С версии 2.1.277 AGENTS.md читается только тогда, когда в рабочем каталоге и выше нет ни CLAUDE.md, ни .claude/CLAUDE.md, ни CLAUDE.local.md. Чтобы читались оба файла, установите Project instructions в /config в значение claude-md-and-agents-md или добавьте в CLAUDE.md строку @AGENTS.md.

Почему AGENTS.md не загружается, хотя CLAUDE.md в репозитории нет?

Чаще всего виноват CLAUDE.local.md, который считается наравне с CLAUDE.md, или CLAUDE.md в родительском каталоге. Вторая причина: сессия не запрашивает feature flags. Это Bedrock, Vertex AI, Foundry, отключённая телеметрия, первая сессия после обновления или disableAllHooks. Признак: в /config нет пункта Project instructions. В таких сессиях положите рядом CLAUDE.md с импортом @AGENTS.md.

Нужен ли ещё симлинк CLAUDE.md на AGENTS.md?

Нет. Существующий можно оставить, содержимое прочитается один раз, или удалить. Для новых проектов используйте либо один AGENTS.md без CLAUDE.md, либо CLAUDE.md с импортом @AGENTS.md. Симлинк ломается на Windows без core.symlinks и мешает инструментам Edit и Write, которые отказываются писать через ссылку.

Влияет ли это на ~/.claude/CLAUDE.md, память и хуки?

Нет. Пользовательский ~/.claude/CLAUDE.md, ~/.claude/rules/ и управляемый CLAUDE.md организации загружаются как раньше и не отключают AGENTS.md. Автопамять работает отдельно. Хуки работают, кроме одного случая: InstructionsLoaded не срабатывает для AGENTS.md, прочитанного напрямую, но срабатывает для AGENTS.md, импортированного из CLAUDE.md.

#claude-code #agents-md#claude-md#coding-agents#project-instructions