Перейти к основному содержимому

AGENTS.md и кросс-инструментальная совместимость

Средний

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

What you'll learn
  • Что такое AGENTS.md и кто им управляет
  • Почему Claude Code читает CLAUDE.md, а не AGENTS.md
  • Три надёжных способа держать единый источник истины во всех инструментах
  • Как объединяются вложенные и глобальные файлы AGENTS.md
  • Что должно быть в файле — и что туда не стоит класть

Что такое AGENTS.md​

AGENTS.md — это обычный Markdown-файл в корне вашего репозитория; считайте его README, написанным для агентов, а не для людей. Он рассказывает кодинг-агенту, как собирать, тестировать проект и вносить в него вклад. У формата нет обязательных полей: агенты просто читают текст.

Это открытый стандарт, которым управляет Agentic AI Foundation (AAIF) под эгидой Linux Foundation, и по состоянию на середину 2026 года он используется в 60 тыс.+ опенсорсных проектах и читается 30+ инструментами — включая OpenAI Codex, Jules и Gemini CLI от Google, Cursor, Windsurf, Devin, Zed, Warp, Aider, goose, Amp и кодинг-агента GitHub Copilot.

What you'll learn
  • AGENTS.md — это соглашение, а не среда выполнения: каждый инструмент сам решает, как он находит, объединяет и внедряет файл.
  • Никакая схема не навязывается — понятный текст лучше жёсткой структуры.
  • Он дополняет ваш README; он его не заменяет.

Подвох с Claude Code​

Вот на чём люди спотыкаются: Claude Code читает CLAUDE.md, а не AGENTS.md. Если в вашем репозитории есть только AGENTS.md, Claude Code по умолчанию его игнорирует. Это не баг — он появился раньше стандарта — но это значит, что мультиинструментальному репозиторию нужна продуманная стратегия синхронизации, иначе ваши инструкции тихо разойдутся.

Watch out
  • Не думайте, что Claude Code откатывается к AGENTS.md — он не читает его автоматически.
  • Два вручную поддерживаемых файла (CLAUDE.md и AGENTS.md) разойдутся. Выберите один источник истины.
  • Перед тем как полагаться на любое заявление о резервном чтении, проверьте текущее поведение в официальной документации по памяти.

Держите единый источник истины​

Три подхода держат CLAUDE.md и AGENTS.md в синхронизации без дублирования содержимого. Выбирайте по платформе вашей команды.

Guided walkthrough1 of 3
  1. Сделайте CLAUDE.md символьной ссылкой на AGENTS.md. Claude Code следует по символьным ссылкам и читает цель байт в байт — один реальный файл, ноль логики слияния. Оговорка: в Windows для создания символьной ссылки нужен режим разработчика или права администратора, поэтому кросс-платформенные команды могут предпочесть метод импорта.

Сделать CLAUDE.md символьной ссылкой на общий стандарт (macOS / Linux)

ln -s AGENTS.md CLAUDE.md

Или держать однострочный CLAUDE.md, который его импортирует

@AGENTS.md
Pro tip
  • Символьная ссылка — когда вся команда на macOS/Linux: поддерживать нужно меньше всего.
  • Используйте @import, когда среди участников есть пользователи Windows.
  • Закоммитьте то, что выберете, чтобы вся команда получила одинаковое поведение.

Как объединяются вложенные и глобальные файлы​

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

Файлы, которые ближе к работе, побеждают, потому что они конкатенируются последними и переопределяют более ранние указания. Так services/payments/AGENTS.md наследует инструкции корня репозитория и добавляет правила, которые применяются только внутри этого сервиса — кладите специализированные указания как можно ближе к специализированному коду.

Совместимость с одного взгляда
Нажмите Enter или пробел, чтобы перевернуть карточку. Используйте стрелки влево и вправо для перехода между карточками.Показан термин.
1 / 5

Что туда класть​

Та же дисциплина, что и для хорошего CLAUDE.md — стандарт лишь предлагает несколько типичных разделов:

  • Обзор проекта — что это, в двух предложениях.
  • Команды сборки и тестов — как запускать, тестировать и линтить.
  • Стиль кода — соглашения, которые агент не может вывести сам.
  • Инструкции по тестированию — что значит «готово».
  • Соображения безопасности — чего никогда нельзя трогать или коммитить.
  • Правила коммитов / PR — формат сообщений, правила веток.
Watch out
  • Агенты следуют файлу буквально — устаревшие или желаемые инструкции активно вредят, ровно как в CLAUDE.md.
  • Держите его коротким и правдивым; описывайте, как проект работает сегодня.
  • Никогда не коммитьте секреты; ссылайтесь на большие документы вместо того, чтобы вставлять их.

Проверьте себя​

Проверьте себя

0/3
  1. Читает ли Claude Code AGENTS.md автоматически?
  2. Ваша команда полностью на macOS и Linux. Какой способ требует меньше всего обслуживания, чтобы один файл инструкций работал и в Claude Code, и в Codex?
  3. Когда агенты объединяют глобальный, корневой и подкаталожный AGENTS.md, какой из них побеждает при конфликтах?
Key takeaways
  • AGENTS.md — открытый стандарт под управлением Linux Foundation, который читают 30+ кодинг-агентов, — README для агентов.
  • Claude Code читает CLAUDE.md, а не AGENTS.md, поэтому мультиинструментальные репозитории должны держать их в синхронизации.
  • Сделайте CLAUDE.md символьной ссылкой → AGENTS.md на Mac/Linux или используйте однострочный импорт @AGENTS.md для кросс-платформенных команд.
  • Вложенные файлы объединяются глобальный → корень → подкаталог, побеждает ближайший файл.
  • Заполняйте его как отличный CLAUDE.md: обзор, команды сборки/тестов, соглашения, безопасность и ограничители — коротко и правдиво.

Дальше​

Источники и дополнительное чтение​