AGENTS.md в Claude Code: как включить и проверить

Как подключить AGENTS.md в Claude Code: короткий ответ

Действуйте в таком порядке:

1. Запустите claude --version. Нужна v2.1.277 или более новая версия.
2. При необходимости обновитесь. При прямой установке подойдет claude update; Homebrew и WinGet обновляются командами соответствующих пакетных менеджеров.
3. Убедитесь, что сеанс может получать флаги функций Anthropic. Нативная загрузка AGENTS.md недоступна в сеансах через сторонних провайдеров, включая Amazon Bedrock, Google Cloud's Agent Platform и Microsoft Foundry, а также когда настройки телеметрии или необязательного трафика блокируют получение этого флага.
4. Поместите AGENTS.md или .claude/AGENTS.md в каталог проекта. В режиме по умолчанию убедитесь, что в рабочем каталоге и выше по дереву нет проектного CLAUDE.md, .claude/CLAUDE.md или CLAUDE.local.md.
5. Если нужны оба семейства файлов, откройте /config и установите для Project instructions значение claude-md-and-agents-md.
6. Проверьте результат в новом сеансе. Первый сеанс после установки или обновления — исключение, поэтому прежде чем делать вывод, откройте следующий.

Это и есть нативный способ. Если пункта Project instructions нет в /config, сохраните документированный импорт @AGENTS.md в CLAUDE.md.

Как Claude Code на самом деле выбирает файл

Новый механизм — это переключатель, а не безусловный поиск всех файлов с инструкциями. В стандартном режиме claude-md-or-agents-md Claude Code сначала ищет проектные инструкции Claude. К AGENTS.md он переходит, только если в рабочем каталоге и выше по дереву нет ни одного подходящего файла Claude.

Главная тонкость — область действия. CLAUDE.local.md в родительском каталоге отключает резервный переход на AGENTS. А личный ~/.claude/CLAUDE.md, управляемый организацией CLAUDE.md и .claude/rules/ его не отключают. Именно поэтому два разработчика могут открыть один репозиторий и увидеть разное поведение.

Когда резервный вариант применим, при старте сеанса Claude Code читает AGENTS.md и .claude/AGENTS.md из рабочего каталога и каталогов выше. AGENTS.md из подкаталога может загрузиться позднее, когда Claude обратится к находящемуся там файлу, если в этом подкаталоге нет собственного подходящего файла Claude. Напрямую AGENTS.local.md, AGENTS.override.md и файлы из .agents/ не читаются.

Механизм больше похож не на поиск по папкам, а на электрический переключатель в здании. Сначала он выбирает активную цепь инструкций. Файлы в другой цепи могут быть полностью корректными, но все равно останутся отключенными.

Выберите режим Project instructions осознанно

Откройте /config, найдите Project instructions и выберите вариант в зависимости от того, где в репозитории должен находиться основной источник правил:

• Fallback, claude-md-or-agents-md: подходит репозиторию, который уже использует AGENTS.md и не содержит проектного файла Claude. Это режим по умолчанию.
• Both, claude-md-and-agents-md: подходит, если в AGENTS.md хранятся общие правила, а в CLAUDE.md — рекомендации только для Claude.
• Claude only, claude-md: подходит команде, которая пока не готова сделать общие инструкции для агентов доступными Claude Code.
• Managed only, managed-only: подходит для контролируемого запуска, при котором должны загружаться политика организации и автоматическая память, но не инструкции репозитория.

В режиме Both Claude Code в каждом каталоге читает содержимое Claude перед содержимым AGENTS. Один и тот же AGENTS.md повторно не загружается, если CLAUDE.md уже импортирует его или является симлинком на него.

Выбор начинает действовать со следующего сообщения и сохраняется в новых сеансах. Параметр также можно задать для встроенного плагина agents-md@builtin в пользовательских настройках, в файле --settings или в управляемых настройках. В проектных и локальных файлах настроек Claude Code этот параметр игнорирует, поэтому репозиторий не может незаметно навязать всем разработчикам один режим. Администратор может централизованно установить его через управляемые настройки.

Как проверить, какой файл загрузил новый сеанс

Для проверки используйте безобидный факт, а не опасную инструкцию. Добавьте в нужный файл строку:

Project probe: BASALT-HERON.

Затем закройте сеанс, откройте в репозитории новый и спросите: What is the project probe? Если в ответе появится BASALT-HERON, значит содержимое попало в контекст сеанса. После проверки удалите строку.

Не считайте /context единственным источником истины. Напрямую загруженный AGENTS.md не отображается в списке Memory files. В стандартном резервном режиме интерактивный сеанс может показать при запуске строку AGENTS.md loaded. Проверка с безобидным маркером работает и в остальных режимах выбора.

Если маркер не сработал, проверяйте по порядку:

1. Версия: v2.1.277 или новее.
2. Номер сеанса: это не первый запуск после установки или обновления.
3. Провайдер: сеанс не использует провайдера, который блокирует получение флагов функций Anthropic.
4. Окружение: ни одна переменная телеметрии или необязательного трафика не отключила получение флага.
5. Плагин и политика: встроенный плагин agents-md включен, а disableAllHooks и allowManagedHooksOnly его не блокируют.
6. Иерархия файлов: на текущем уровне и выше нет подходящего CLAUDE.md, .claude/CLAUDE.md или CLAUDE.local.md, если используется стандартный режим.
7. Режим: в /config выбрано ожидаемое поведение.

Если пункта Project instructions нет в /config, это уже диагностический признак: используется неподдерживаемая версия или сеанс не может использовать функцию.

Сохраните импорт там, где нативная поддержка недоступна

Существующий импорт остается самым надежным слоем совместимости для Bedrock, Vertex, Foundry, других сеансов через сторонних провайдеров, окружений с ограниченной телеметрией и команд, где используются разные версии. Добавьте в CLAUDE.md рядом с AGENTS.md такую строку:

@AGENTS.md

Ниже можно добавить инструкции только для Claude. Сначала Claude прочитает импортированный общий файл, затем — специфичные для Claude дополнения. Этот мост не приведет к двойной загрузке, если пользователь с поддерживаемым сеансом выберет режим Both.

Симлинк с CLAUDE.md на AGENTS.md тоже работает, но импорт надежнее на разных платформах. В Windows для создания симлинка могут потребоваться повышенные привилегии или Developer Mode, а Git — правильная настройка для симлинков. Хук SessionStart, который выводит содержимое AGENTS.md, после включения прямой загрузки следует удалить: иначе он может добавить в контекст дубликат.

Релиз меняет объем работы по сопровождению. Раньше команда с единой политикой для разных агентов часто держала два файла, промежуточный импорт или хук. Теперь в поддерживаемых сеансах достаточно одного файла инструкций в репозитории. Стоимость лицензии Claude от этого не снижается: Anthropic включает Claude Code в тариф Pro за $20 в месяц. Выигрыш — в меньшем числе точек синхронизации и в снижении риска, что сеанс будет работать по устаревшим правилам.

Остальные этапы настройки разобраны в расширенном руководстве по Claude Code: установка, контекст проекта и повседневные команды. Если в репозитории также определены специализированные агенты, руководство по субагентам объясняет особенности их отдельного стартового контекста.

Семь сценариев, в которых это особенно полезно

Сценарии расположены по масштабу координационной проблемы, которую снимает новый переключатель.

Первые три сценария дают наибольшую отдачу, потому что ошибка масштабируется на людей и репозитории. В одиночном репозитории с одним агентом удобство заметно, но невелико.

Какие продукты можно построить вокруг этой функции

1. Инструмент диагностики инструкций для разных агентов

Можно создать локальную CLI-утилиту и CI-проверку, которая точно объясняет, какие файлы с инструкциями загрузит каждый ИИ-агент разработки. Платформенные команды и консалтинговые компании заплатили бы за надежный ответ до развертывания правил в репозиториях.

Спрос уже виден: запрос claude code setup получает около 1,900 поисков в месяц в США, а claude md vs agents md — 480, причем за год он вырос на 1,500%. Минимальная коммерческая версия сканирует дерево файлов, определяет версию Claude Code и конфигурацию провайдера, отмечает перекрывающие файлы и выводит порядок загрузки. Платная версия для команд могла бы обеспечивать соблюдение одной политики во всех репозиториях.

Это самая сильная возможность, потому что продукт решает задачу диагностики, а не создания шаблонов. Ограничение — риск со стороны платформы. Anthropic может встроить такие проверки в claude doctor, поэтому устойчивому продукту нужна поддержка нескольких ИИ-агентов разработки и история изменений политики, а не одна команда Claude.

2. Конструктор и линтер политик AGENTS.md

Можно создать пошаговый редактор, который превращает команды сборки, правила тестирования, границы каталогов и требования к ревью в лаконичный AGENTS.md, а затем проверяет его на противоречия и расплывчатые формулировки. Покупатели — небольшие инженерные команды, внедряющие несколько ИИ-агентов.

Запрос agents md получает около 2,900 поисков в месяц в США. Более узкий agents md best practices получает 210 и за год вырос на 750%. Для MVP нужны сканер репозитория, короткий опрос, сгенерированный черновик и правила линтинга для дублирующихся или противоречивых инструкций. Результат должен соответствовать рекомендации провайдера по краткости проектных файлов, а не превращаться в огромный свод политик.

Ограничение в том, что такую идею легко скопировать. Любой агент для написания кода умеет создать черновик Markdown. Продукт оправдает свое существование, только если его проверка учитывает реальный порядок загрузки и подтверждает, что каждый поддерживаемый инструмент прочитал результат.

3. Аудит миграции смешанной агентной инфраструктуры

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

480 поисков в месяц по запросу claude md vs agents md, который вырос на 1,500% за год, — необычно прямое свидетельство этой путаницы. MVP может состоять из анализатора репозитория только для чтения и плана pull request. Автоматически удалять промежуточный файл нельзя: он все еще может требоваться в неподдерживаемых сеансах.

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

Ограничения и честный вывод

Нативная резервная загрузка убирает промежуточный файл. Она не превращает проектные инструкции в механизм принудительного контроля, не обеспечивает совместимость со всеми провайдерами и не разрешает конфликты правил. Anthropic описывает файлы инструкций как контекст. Если выполнение команды нужно гарантированно запретить, используйте правило разрешений или хук PreToolUse.

Кроме того, AGENTS.md не появляется в тех же диагностических интерфейсах, что и CLAUDE.md. Напрямую загруженный файл отсутствует в /memory и в списке Memory files внутри /context. Из-за этой непоследовательности безобидный маркер стоит сохранить в чек-листе миграции.

Не удаляйте работающий импорт в среде с несколькими провайдерами только потому, что нативная проверка прошла на одном ноутбуке. Не выбирайте режим Both, пока не проверите инструкции на противоречия. Внутри каталога содержимое Claude читается перед содержимым AGENTS, но порядок контекста не является жесткой системой приоритетов политик.

И все же релиз дает заметное операционное улучшение. Репозиторий, где AGENTS.md уже служит общим источником, теперь может работать с Claude Code, не делая вид, будто настоящим источником служит второй файл с другим именем. Функция небольшая, но существенно упрощает координацию.

Если вам нужна надежная система инструкций для нескольких агентов в ваших репозиториях, я помогу спроектировать агентную архитектуру и внедрить ее.