AGENTS.md: что это за файл и как его читают Codex, Claude Code и OpenCode

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

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

Формат появился из совместной работы OpenAI Codex, Amp, Jules от Google, Cursor и Factory. OpenAI выпустила AGENTS.md в августе 2025 года. 9 декабря 2025 года Linux Foundation объявила о создании Agentic AI Foundation (AAIF), и AGENTS.md стал одним из трёх стартовых проектов фонда вместе с MCP от Anthropic и goose от Block. С тех пор форматом управляет AAIF.

AGENTS.md лежит больше чем в 60 тысячах открытых проектов. Файл подхватывают Codex, Cursor, OpenCode, Gemini CLI, GitHub Copilot, VS Code, Devin, Jules, Zed, goose, Kilo Code, Warp, Windsurf, Junie и другие агенты.

Название файла общее, но ищет его каждый агент по-своему: одни склеивают все AGENTS.md от корня до текущей папки, другие берут первый найденный, третьи подгружают файлы подпапок по ходу работы. Настройки MCP для этих агентов собраны в разделе /mcp/klienty/.

Минимальный пример для монорепозитория на pnpm и Turborepo. В нём три блока: подсказки по окружению, как запускать и чинить тесты и правила для pull request.

Личные привычки для всех проектов Codex берёт из ~/.codex/AGENTS.md, например «запускать npm test после правки JavaScript» или «спрашивать перед добавлением новых зависимостей». Временно подменить его можно файлом ~/.codex/AGENTS.override.md, удалите его, и вернутся обычные правила.

# Sample AGENTS.md file

## Dev environment tips
- Use `pnpm dlx turbo run where <project_name>` to jump to a package instead of scanning with `ls`.
- Run `pnpm install --filter <project_name>` to add the package to your workspace so Vite, ESLint, and TypeScript can see it.
- Use `pnpm create vite@latest <project_name> -- --template react-ts` to spin up a new React + Vite package with TypeScript checks ready.
- Check the name field inside each package's package.json to confirm the right name—skip the top-level one.

## Testing instructions
- Find the CI plan in the .github/workflows folder.
- Run `pnpm turbo run test --filter <project_name>` to run every check defined for that package.
- From the package root you can just call `pnpm test`. The commit should pass all tests before you merge.
- To focus on one step, add the Vitest pattern: `pnpm vitest run -t "<test name>"`.
- Fix any test or type errors until the whole suite is green.
- After moving files or changing imports, run `pnpm lint --filter <project_name>` to be sure ESLint and TypeScript rules still pass.
- Add or update tests for the code you change, even if nobody asked.

## PR instructions
- Title format: [<project_name>] <Title>
- Always run `pnpm lint` and `pnpm test` before committing.

Пишите то, что рассказали бы новому человеку в команде. Codex по команде /init составляет файл на 200–400 слов с разделами о структуре проекта, командах, стиле кода, тестах, коммитах и pull request. OpenCode по /init собирает команды сборки, линтера и тестов, порядок проверок, архитектуру, которую не понять по именам файлов, и особенности настройки окружения.

Claude Code советует держать файл короче 200 строк: длинный тратит контекст, и агент хуже следует правилам. Из двух противоречащих правил агент может выбрать любое, поэтому их стоит вычищать. Правила пишите конкретными, с числами и примерами: «цикломатическая сложность меньше 10».

В большом монорепозитории положите отдельный AGENTS.md в каждый пакет. Агент читает ближайший к редактируемому файлу AGENTS.md, и при конфликте он главнее. Прямые указания в чате важнее любого файла. В основном репозитории OpenAI было 88 файлов AGENTS.md.

Codex собирает цепочку один раз при запуске и останавливается на текущей папке: AGENTS.md из подпапок ниже он не прочитает. Запускайте его из папки пакета, например codex --cd services/payments, а правила для отдельной команды кладите в AGENTS.override.md рядом с её кодом.

Claude Code, Cursor, goose, Kilo Code, Hermes Agent и Gemini CLI подхватывают файлы подпапок по ходу работы, когда открывают там файлы. Antigravity ниже рабочей папки правила не грузит. В OpenCode файлы пакетов подключает шаблон packages/*/AGENTS.md в ключе instructions файла opencode.json.

project/
  AGENTS.md              # Global instructions
  frontend/
    AGENTS.md            # Frontend-specific instructions
    components/
      AGENTS.md          # Component-specific instructions
  backend/
    AGENTS.md            # Backend-specific instructions

Все три файла — Markdown для агента, разница в том, кто их читает и когда они попадают в контекст.

Codex перестаёт добавлять файлы, когда их общий размер доходит до project_doc_max_bytes, по умолчанию 32 КиБ. Пустые файлы он пропускает. Лимит поднимают в ~/.codex/config.toml, там же список запасных имён файлов, или разносят правила по вложенным папкам. Цепочку Codex пересобирает при каждом запуске, кэш чистить не нужно.

Antigravity обрезает любой файл правил больше 24 000 байт, а на все постоянные правила даёт 20 000 токенов. При превышении самые большие файлы заменяются ссылками, и агент читает их по необходимости.

Hermes Agent режет длинный файл с сохранением 70% начала и 20% конца. Порог задаёт context_file_max_chars, без него он зависит от окна модели: от 20 000 до 500 000 знаков. Claude Code советует держать файл до 200 строк, импорты через @ контекст не экономят: подключённые файлы грузятся вместе с основным.

# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536