# AGENTS.md: один файл инструкций для Codex, Cursor и Claude Code

> Что такое AGENTS.md, какие инструменты его читают и как совместить с CLAUDE.md: прямое чтение, @-импорт, symlink, вложенные файлы, лимиты.
> Author: Roman Belov · Published: 2026-10-07 · Source: https://futurecraft.pro/ru/blog/agents-md-guide/

Проектные инструкции для кодовых агентов лежат в репозитории под разными именами: CLAUDE.md у Claude Code, `.cursor/rules` у Cursor, `.github/copilot-instructions.md` у Copilot, GEMINI.md у Gemini CLI. AGENTS.md сводит их к одному файлу. Это открытый формат, обычный Markdown в корне репозитория с командами сборки и тестов, соглашениями по коду и ограничениями. Спецификация на [agents.md](https://agents.md) называет его «README для агентов», а курирует формат Agentic AI Foundation при Linux Foundation.

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

Статья о том, кто и как читает AGENTS.md, как совместить его с CLAUDE.md в команде, где работают несколько агентов, что класть в общий файл и какие ловушки встречаются на практике. Поведение Claude Code проверено на версии 2.1.318, остальное описано по документации на 6 ноября 2026 года. Уровни CLAUDE.md и порядок их загрузки разобраны отдельно в [гайде по CLAUDE.md](https://futurecraft.pro/ru/blog/claude-md-guide/).

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

### Происхождение и стюардство

Формат появился в экосистеме OpenAI Codex и быстро вышел за её пределы. В декабре 2025 года Linux Foundation запустила Agentic AI Foundation, и AGENTS.md (от OpenAI) вошёл в неё вместе с MCP от Anthropic и goose от Block ([SD Times](https://sdtimes.com/ai/linux-foundation-forms-agentic-ai-foundation-to-be-new-home-for-mcp-goose-and-agents-md/), [InfoQ](https://infoq.com/news/2025/12/agentic-ai-foundation/)). Сайт agents.md сообщает, что формат используют более 60 тысяч open-source проектов, а в основном репозитории OpenAI на момент написания страницы было 88 файлов AGENTS.md.

Главное, что нужно знать о формате: схемы нет. На вопрос об обязательных полях спецификация отвечает «нет, это обычный Markdown». Ни frontmatter, ни зарезервированных заголовков формат не требует, механизма условного применения в нём нет. Всё, что сложнее «прочитай этот текст», каждый инструмент реализует сам.

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

### Что туда писать

Спецификация рекомендует пять разделов: обзор проекта, команды сборки и тестов, стиль кода, тестирование, безопасность. Минимальный рабочий файл помещается в полтора десятка строк:

```markdown
# AGENTS.md

## Команды
- Установка: `pnpm install`
- Тесты: `pnpm test` (перед каждым коммитом)
- Линтер: `pnpm lint --fix`

## Соглашения
- TypeScript strict, без `any`
- API-обработчики лежат в `src/api/handlers/`

## Ограничения
- Не добавлять зависимости без согласования
- Не коммитить `.env*` и секреты
```

Полный шаблон для команды есть в разделе «Шаблон AGENTS.md и тонкий CLAUDE.md».

## Кто читает AGENTS.md: матрица инструментов

Таблица собрана по первичной документации каждого инструмента, дата проверки: 6 ноября 2026 года. Поведение меняется от релиза к релизу, поэтому перед внедрением стоит перепроверить свой инструмент по ссылке из последней колонки.

| Инструмент | Как читает AGENTS.md | Вложенные файлы | Лимит / рекомендация по размеру | Источник |
|---|---|---|---|---|
| **Codex** | Основной формат. Глобальный `~/.codex/AGENTS.override.md` или `AGENTS.md`, затем по одному файлу на каталог от корня проекта до текущей директории | Склеиваются от корня вниз, ближайшие идут позже и выигрывают | 32 KiB на всю цепочку (`project_doc_max_bytes`) | [docs Codex](https://learn.chatgpt.com/docs/agent-configuration/agents-md) |
| **Claude Code** | С v2.1.277, если в рабочей директории и выше нет `CLAUDE.md`, `.claude/CLAUDE.md`, `CLAUDE.local.md` | AGENTS.md подкаталога подгружается, когда Claude читает файл из этого подкаталога | Для CLAUDE.md рекомендация: до 200 строк | [docs Claude Code](https://code.claude.com/docs/en/memory) + проверка на 2.1.318 |
| **Cursor** | В корне и в подкаталогах, как альтернатива `.cursor/rules` | Объединяются с родительскими, более специфичные приоритетнее | Для правил рекомендация: до 500 строк | [docs Cursor](https://cursor.com/docs/context/rules) |
| **GitHub Copilot** | Cloud agent, code review, Copilot CLI, Chat в VS Code. Вместо AGENTS.md можно один `CLAUDE.md` или `GEMINI.md` в корне | Приоритет у ближайшего в дереве | Не указан | [docs GitHub](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions), [таблица поддержки](https://docs.github.com/en/copilot/reference/custom-instructions-support) |
| **Gemini CLI** | По умолчанию читает `GEMINI.md`; AGENTS.md читает после настройки `context.fileName` в `settings.json` | Все найденные файлы склеиваются | Не указан | [docs Gemini CLI](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/gemini-md.md) |
| **Aider** | Сам файлы не ищет; AGENTS.md подключается через `read: AGENTS.md` в `.aider.conf.yml` или `--read` | Не описано | Не указан | [docs Aider](https://aider.chat/docs/usage/conventions.html), [FAQ agents.md](https://agents.md) |

В списке поддерживающих инструментов на agents.md есть ещё Jules, Devin, Windsurf, Junie, Zed, Warp, Factory, goose, opencode, Amp, RooCode, Kilo Code, Augment Code и другие. Их собственную документацию для этой статьи не проверяли. Отдельная оговорка про Gemini CLI: в мае 2026 года Google [объявила](https://developers.googleblog.com/an-important-update-transitioning-gemini-cli-to-antigravity-cli/) о переходе на Antigravity CLI: с 18 июня 2026 года Gemini CLI перестал обслуживать бесплатных пользователей и подписчиков Google AI Pro и Ultra, доступ сохранился у лицензий Gemini Code Assist Standard и Enterprise и при работе через платные API-ключи. Читает ли AGENTS.md сам Antigravity CLI, не проверяли.

### Codex: цепочка файлов и лимит 32 KiB

Codex собирает инструкции заново при каждом запуске. Сначала глобальный уровень в `~/.codex` (или в `CODEX_HOME`): берётся `AGENTS.override.md`, а если его нет, `AGENTS.md`; используется первый непустой. Затем проектный уровень: Codex идёт от корня проекта (обычно корня Git-репозитория) вниз до текущей директории и в каждом каталоге берёт не больше одного файла в порядке `AGENTS.override.md` → `AGENTS.md` → имена из `project_doc_fallback_filenames`.

Найденные файлы не заменяют друг друга, а склеиваются через пустую строку от корня вниз. Ближайшие к рабочей директории идут последними и поэтому выигрывают при противоречии. Пустые файлы пропускаются. Как только суммарный размер достигает `project_doc_max_bytes` (по умолчанию 32 KiB), Codex перестаёт добавлять файлы. Документация советует либо поднять лимит, либо разнести инструкции по вложенным каталогам.

Запасные имена задаются в `~/.codex/config.toml`:

```toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536
```

Проверить, что Codex видит, можно его же запросом из корня репозитория: `codex --ask-for-approval never "Summarize the current instructions."`. Для подкаталога добавьте флаг `--cd subdir`.

### Cursor: AGENTS.md или .cursor/rules

Cursor поддерживает оба механизма, и они решают разные задачи. AGENTS.md - простой Markdown без метаданных, документация Cursor предлагает его «для простых случаев». Файлы в подкаталогах объединяются с родительскими, более специфичные инструкции приоритетнее.

Правила `.cursor/rules` хранятся в файлах с расширением `.mdc` и frontmatter из трёх полей: `description`, `globs`, `alwaysApply`. От них зависит тип применения: Always Apply (в каждой сессии), Apply Intelligently (агент решает по описанию), Apply to Specific Files (по шаблону пути), Apply Manually (по @-упоминанию). В старых версиях документации последние два назывались Agent Requested и Auto Attached. Обычный `.md` в `.cursor/rules` без frontmatter система правил игнорирует.

Поверх проектных правил есть User Rules (глобальные для пользователя) и Team Rules (тарифы Team и Enterprise). При конфликте порядок такой: Team → Project → User. Про устаревший `.cursorrules` текущая страница документации не пишет ничего, поэтому утверждать что-либо о его статусе по ней нельзя.

### GitHub Copilot: copilot-instructions.md, applyTo и AGENTS.md

У Copilot три вида репозиторных инструкций. `.github/copilot-instructions.md` действует на весь репозиторий. Файлы `.github/instructions/NAME.instructions.md` с ключом `applyTo` (glob) действуют на часть путей, их поддерживают только cloud agent и code review, а ключом `excludeAgent` (`"code-review"` или `"cloud-agent"`) файл можно скрыть от одного из них. Третий вид называется agent instructions: один или несколько AGENTS.md в любом месте репозитория, где приоритет у ближайшего, либо одиночный `CLAUDE.md` или `GEMINI.md` в корне.

Кто именно читает agent instructions, видно из [таблицы поддержки](https://docs.github.com/en/copilot/reference/custom-instructions-support): cloud agent (на GitHub.com и из IDE), code review, Copilot CLI и Copilot Chat в VS Code. Copilot Chat в JetBrains, Visual Studio, Eclipse и Xcode в таблице agent instructions не поддерживает. Если команда пользуется Chat вне VS Code, `copilot-instructions.md` пока нужен.

Личные инструкции Copilot приоритетнее репозиторных, а репозиторные приоритетнее организационных; в запрос уходят все релевантные наборы.

### Claude Code: что изменилось и правила выбора

До версии 2.1.277 Claude Code читал только CLAUDE.md, и AGENTS.md приходилось подключать обходными путями. Теперь встроенный плагин читает AGENTS.md сам, но с условием: по умолчанию (`claude-md-or-agents-md`) только если в рабочей директории и выше нет ни одного из трёх файлов: `CLAUDE.md`, `.claude/CLAUDE.md`, `CLAUDE.local.md`. Пользовательский `~/.claude/CLAUDE.md`, управляемый CLAUDE.md организации и `.claude/rules/` в эту проверку не входят и грузятся вместе с AGENTS.md.

| В репозитории | Что читает Claude Code |
|---|---|
| Только AGENTS.md | AGENTS.md |
| AGENTS.md + CLAUDE.md (без импорта) | Только CLAUDE.md |
| AGENTS.md + CLAUDE.md с `@AGENTS.md` | CLAUDE.md и AGENTS.md через импорт |
| AGENTS.md + CLAUDE.local.md | Только CLAUDE.local.md |

**Проверено:** 6 ноября 2026 года, Claude Code 2.1.318, временные папки с уникальной фразой-маркером в каждом файле. Во всех четырёх случаях модель назвала маркеры только из указанных в таблице файлов, а `/context all` показал те же файлы в разделе Memory files. Импорт `@AGENTS.md` дубля не дал: каждый файл в списке один раз.

Ещё три отличия AGENTS.md, прочитанного напрямую, от CLAUDE.md по документации: на него не срабатывают хуки `InstructionsLoaded` (для импортированного или подключённого через symlink AGENTS.md срабатывают); AGENTS.md из каталогов, добавленных через `--add-dir`, не грузится; не читаются `AGENTS.local.md`, `AGENTS.override.md` и содержимое каталога `.agents/`. Если у вас есть Codex-специфичный `AGENTS.override.md`, Claude Code его не увидит.

## Как совместить AGENTS.md с CLAUDE.md

Вариантов четыре, и универсально правильного среди них нет. Выбор зависит от того, есть ли в команде Windows, нужны ли инструкции только для Claude Code и укладывается ли общий текст в лимит Codex.

### Вариант 1: только AGENTS.md

CLAUDE.md в репозитории нет, Claude Code читает AGENTS.md сам. Подходит, если инструкции действительно общие, а Claude-специфичного (hooks, skills, plan mode) в них нет или оно лежит в `.claude/rules/` и `.claude/settings.json`.

Главная ловушка здесь `CLAUDE.local.md`. Это личный, незакоммиченный файл, и кажется, что он только добавляет инструкции. На деле он считается за CLAUDE.md, и Claude Code перестаёт читать AGENTS.md. В живой проверке модель с AGENTS.md и CLAUDE.local.md в одной папке видела только маркер из CLAUDE.local.md. Сообщения об ошибке нет: агент просто работает без проектных инструкций.

Второе ограничение связано с версиями. Сессии на Claude Code до 2.1.277 AGENTS.md не видят. До 2.1.281 его не видели и некоторые сессии на свежих версиях, например на Amazon Bedrock или с отключённой телеметрией. Иногда его не читает и первая сессия сразу после обновления с версии 2.1.276 или более ранней.

### Вариант 2: CLAUDE.md с @AGENTS.md

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

```markdown
@AGENTS.md

## Claude Code
- Изменения в `src/billing/`: только через plan mode
- Перед коммитом запусти skill `pre-push`
```

Claude Code сначала читает импортированный файл, затем остальной CLAUDE.md. Схема работает и в сессиях, где прямое чтение AGENTS.md недоступно, и при любом значении настройки Project instructions, а дубля в контексте не бывает: документация обещает, что импорт никогда не заставит прочитать AGENTS.md дважды, и живая проверка это подтверждает. Минус один: если кто-то добавит в CLAUDE.md общие правила, другие агенты их не увидят. Такие вещи ловит только ревью.

### Вариант 3: symlink

```bash
ln -s AGENTS.md CLAUDE.md
```

Содержимое одно, читают его все. Документация Claude Code перечисляет два ограничения. Первое: инструменты Edit и Write не пишут через symlink, и Claude перенаправит правку в целевой файл, AGENTS.md. Второе: Windows. Создание symlink требует прав администратора или Developer Mode, а Git без `core.symlinks` извлекает закоммиченную ссылку как обычный текстовый файл. У разработчика на Windows CLAUDE.md окажется однострочным файлом с текстом `AGENTS.md` вместо инструкций.

Встречается и обратная схема: `AGENTS.md -> CLAUDE.md`. В рабочем пространстве автора (около 15 проектов, Claude Code и Codex параллельно) так устроено большинство проектов: они начинались с Claude Code, и источником правды остался CLAUDE.md. Направление ссылки определяет, какой файл настоящий, и это важно в двух местах. Править нужно цель, а не ссылку. И всё, что лежит в цели, видят все агенты: при `AGENTS.md -> CLAUDE.md` Codex получает и Claude-специфичные инструкции про hooks и skills, которых у него нет.

### Вариант 4: два файла разной длины

Иногда общий текст объективно не помещается в лимит Codex. Пример из того же рабочего пространства: в продуктовом монорепозитории CLAUDE.md занимает около 708 строк и 41 415 байт, а AGENTS.md около 128 строк и 10 КБ. Длинный файл в лимит Codex по умолчанию (32 768 байт) не поместился бы. Что Codex делает с единственным файлом больше лимита, документация не уточняет: она описывает только остановку при накоплении суммы. Этот случай не проверяли.

Короткая версия для Codex фиксирует только операционный минимум: язык ответов, консервативные изменения, запреты (удаление файлов, новые зависимости, долгоживущие процессы, секреты), порядок проверки и ссылку «подробности в `docs/`, не здесь». Такое разделение осознанное: у короткого файла своя задача, и пересказывать длинный он не пытается.

Цена варианта в том, что получается два файла, которые нужно синхронизировать вручную. Работает, только если короткий файл действительно короткий и меняется редко.

### Таблица выбора

«Да» в ячейке означает, что вариант подходит при этом условии.

| Критерий | Только AGENTS.md | CLAUDE.md + `@AGENTS.md` | Symlink | Два файла |
|---|---|---|---|---|
| Есть разработчики на Windows | Да | Да | Нет | Да |
| Нужны инструкции только для Claude Code | Только через `.claude/rules/` | Да | Нет | Да |
| Сессии на Claude Code < 2.1.277 | Нет | Да | Да | Да |
| Личные `CLAUDE.local.md` у участников | Нет, отключают AGENTS.md | Да | Да | Да |
| Общий текст больше 32 KiB | Нет | Нет | Нет | Да |
| Число файлов, которые правят люди | 1 | 1 + тонкая обёртка | 1 | 2 |

### Режим claude-md-and-agents-md и проверка через /context all

Если и CLAUDE.md, и AGENTS.md нужны, а импорт ставить не хочется, Claude Code можно переключить на чтение обоих файлов. В интерактивной сессии: `/config` → **Project instructions** → `claude-md-and-agents-md`. В файле настроек:

```json
{
  "pluginConfigs": {
    "cc-plugin-agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}
```

Эта настройка читается только из `~/.claude/settings.json`, из файла, переданного через `--settings`, и из managed settings. В проектном `.claude/settings.json` и в `settings.local.json` она игнорируется, поэтому закоммитить её в репозиторий для всей команды нельзя. До v2.1.285 плагин назывался `agents-md@builtin`; с 2.1.285 принимаются оба ID. Остальные значения: `claude-md` (только CLAUDE.md) и `managed-only` (только управляемые инструкции организации).

**Проверено:** 6 ноября 2026 года, Claude Code 2.1.318, настройка передана через `--settings`. С CLAUDE.md без импорта модель увидела маркеры обоих файлов, с CLAUDE.local.md тоже маркеры обоих. Режим лечит и обычную ситуацию «CLAUDE.md рядом с AGENTS.md», и ловушку с `CLAUDE.local.md`.

Быстрее всего проверить загрузку командой `/context all` в начале сессии. Раздел **Memory files** перечисляет файлы инструкций с их уровнем (Project, Local, User) и числом токенов. Команда работает и в неинтерактивном режиме: `claude -p "/context all"`. Если вместо ожидаемого AGENTS.md в списке только CLAUDE.local.md, причина найдена.

## Вложенные AGENTS.md и монорепозитории

Спецификация рекомендует класть отдельный AGENTS.md в каждый пакет монорепозитория. Общее правило: ближайший файл выигрывает, но механика у инструментов разная:

- **Codex** склеивает всю цепочку от корня до текущей директории, и вложенные файлы тратят общий бюджет 32 KiB. Дробление на пакеты помогает, только если корневой файл короткий: он попадает в каждую цепочку.
- **Cursor** объединяет вложенный файл с родительскими, более специфичный выигрывает при конфликте.
- **Copilot** берёт ближайший файл в дереве.
- **Claude Code** при старте читает AGENTS.md из рабочей директории и всех директорий выше, а AGENTS.md подкаталога подгружает, когда открывает файл из этого подкаталога и там нет своего CLAUDE.md. Вложенные файлы в живой проверке не тестировались, здесь описано поведение по документации.

Дробить имеет смысл, когда у пакетов действительно разные команды и соглашения: фронтенд на pnpm и Vitest, бэкенд на Go, отдельный пакет с инфраструктурой. Если вложенный файл повторяет корневой с парой отличий, лучше оставить одну строку в корневом: «в `packages/api` тесты запускаются через `go test ./...`».

## Что класть в общий файл, а что нет

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

- команды сборки, тестов, линтера;
- соглашения по коду и структуре, которые не выводятся из самого кода;
- запреты: секреты, новые зависимости, удаление файлов, ручной деплой;
- порядок проверки перед коммитом;
- ссылки на `docs/` и ADR вместо пересказа.

Инструмент-специфичное уходит в файл инструмента. Hooks, skills, plan mode, субагенты, MCP-серверы Claude Code описываются в CLAUDE.md или `.claude/`. Codex-специфичное кладут в `AGENTS.override.md` или глобальный `~/.codex/AGENTS.md`. Фраза «запусти skill `pre-push`» в общем файле заставит Codex искать то, чего у него нет. Жёсткие правила, которые нельзя нарушать, вообще лучше выносить из текста в механизмы: в Claude Code для этого есть [hooks](https://futurecraft.pro/ru/blog/claude-code-hooks/). Инструкция в любом из файлов для модели только контекст, выполнение она не гарантирует.

Личные правила AGENTS.md не шарит. Это проектный файл: глобальные предпочтения у Claude Code живут в `~/.claude/CLAUDE.md`, у Codex в `~/.codex/AGENTS.md`, и синхронизировать их придётся отдельно.

Что касается содержания, есть эмпирика. В исследовании ETH Zurich и LogicStar.ai ([arXiv 2602.11988](https://arxiv.org/abs/2602.11988), v3 от 29.09.2026) агентов прогоняли на задачах SWE-bench и на наборе issues из репозиториев, где разработчики сами закоммитили контекст-файлы. Вывод авторов: такие файлы в целом не повышают долю решённых задач, а стоимость инференса растёт в среднем более чем на 20%. Инструкции агенты выполняют хорошо, обзоры репозитория не помогают. Польза есть там, где нужно описать нестандартные практики проекта.

Отсюда практический вывод: писать в AGENTS.md неочевидное и проверяемое. Структуру каталогов агент прочитает сам, пересказывать её незачем. Каждая строка файла расходует контекст в каждой сессии; почему этот расход важен, разобрано в гайде по [context engineering](https://futurecraft.pro/ru/blog/context-engineering-guide/).

## Шаблон AGENTS.md и тонкий CLAUDE.md

Шаблон для репозитория, с которым работают несколько агентов. Конкретные команды и пути заменить своими.

```markdown
## Проект
Монорепозиторий: `apps/web` (Next.js), `apps/api` (Go), `packages/ui`.
Архитектура описана в `docs/architecture.md`, решения в `docs/adr/`.

## Команды
- Установка: `pnpm install`
- Тесты всего репозитория: `pnpm test`; один пакет: `pnpm --filter <pkg> test`
- API: `cd apps/api && go test ./...`
- Линтер и формат: `pnpm lint --fix`

## Соглашения
- TypeScript strict, без `any`; ошибки API отдаются через `ApiError`
- Новые эндпоинты добавляются с тестом в `apps/api/internal/.../*_test.go`
- Миграции БД только новыми файлами, существующие не редактировать

## Ограничения
- Не добавлять зависимости без согласования в PR
- Не коммитить `.env*`, ключи и токены
- Не удалять файлы и крупные блоки кода без явной просьбы
- Не запускать долгоживущие процессы (dev-серверы, watchers)

## Перед коммитом
1. `pnpm lint` и `pnpm test` проходят
2. Изменение описано в PR: что и зачем
```

И тонкий CLAUDE.md рядом:

```markdown
@AGENTS.md

## Только для Claude Code
- Изменения в `apps/api/internal/billing/`: через plan mode
- Перед push запускай skill `pre-push`
```

Обе части вместе укладываются в несколько килобайт: до лимита Codex далеко, и до рекомендованных 200 строк для CLAUDE.md тоже. Что ещё писать в Claude-части, разобрано в [гайде по CLAUDE.md](https://futurecraft.pro/ru/blog/claude-md-guide/).

## Миграция существующей настройки

**Из CLAUDE.md.** Перенести общее в AGENTS.md, в CLAUDE.md оставить `@AGENTS.md` и Claude-специфичное. Если Claude-специфичного нет, CLAUDE.md можно удалить, и свежий Claude Code прочитает AGENTS.md сам. Ранее для этой задачи использовали генерацию AGENTS.md из CLAUDE.md внешними утилитами вроде [AgentSync](https://futurecraft.pro/ru/blog/agentsync-mcp-config-sync/) с исключением Claude-специфичных разделов. Для правил прямое чтение AGENTS.md эту задачу в основном снимает, а синхронизация MCP-конфигов между агентами остаётся отдельной.

**Из `.cursor/rules`.** Правила типа Always Apply переносятся в AGENTS.md. Правила, привязанные к шаблонам файлов, остаются в `.mdc` или превращаются во вложенный AGENTS.md соответствующего каталога. Правила типа Apply Intelligently аналога в AGENTS.md не имеют.

**Из `.github/copilot-instructions.md`.** Общий текст переносится в AGENTS.md. Сам `copilot-instructions.md` стоит оставить, если в команде пользуются Copilot Chat вне VS Code: там AGENTS.md не читается.

**Через инструменты Claude Code.** `/init` при генерации CLAUDE.md учитывает `.cursor/rules`, `.cursorrules` и `.github/copilot-instructions.md`; с переменной `CLAUDE_CODE_NEW_INIT=1` ещё и AGENTS.md, `.devin/rules/`, `.windsurf/rules/` и `.clinerules`. `/import` один раз копирует конфигурацию другого агента, включая AGENTS.md, в CLAUDE.md. В обоих случаях получается копия текста: если AGENTS.md остаётся в репозитории, лучше заменить скопированный текст на `@AGENTS.md`. Сгенерированный файл целиком оставлять не стоит: `/init` пишет обзор проекта, а такие обзоры, судя по данным ETH, агентам не помогают.

**Старые обходы.** Документация Claude Code разбирает четыре распространённых варианта:

| Было | Что делать |
|---|---|
| CLAUDE.md с `@AGENTS.md` | Оставить; удалить, если в нём больше ничего нет и все сессии на свежей версии |
| CLAUDE.md с фразой «читай AGENTS.md» | Заменить фразу на `@AGENTS.md` или удалить CLAUDE.md: агент открывает файл, только если сам решит |
| Symlink CLAUDE.md → AGENTS.md | Можно оставить или удалить, содержимое читается один раз |
| SessionStart-хук, печатающий AGENTS.md | Удалить, иначе в контексте будет вторая копия |

## Типичные ошибки

**Две копии, которые правят независимо.** Классический сценарий дрейфа. В одном из проектов автора CLAUDE.md и AGENTS.md начинались как одинаковые копии; со временем они разошлись в нескольких абзацах, и уже нельзя сказать, какая версия правильная. Агенты в одном репозитории получают разные правила.

**Автозамена имён.** Копию для другого агента делают поиском и заменой `Claude` → `Codex`. Вместе с названием меняются пути: строка `~/.claude/team-rules.md` превращается в `~/.Codex/team-rules.md`, которого не существует. Ошибка молчаливая: агент просто не находит файл.

**Claude-специфика в общем файле.** Для других агентов упоминания skills, hooks, субагентов и MCP-серверов Claude Code в AGENTS.md становятся инструкциями, которые они не могут выполнить. В лучшем случае это лишний расход контекста, в худшем агент тратит шаги на поиск несуществующего. Особенно легко это случается при схеме `AGENTS.md -> CLAUDE.md`.

**Symlink в команде с Windows.** У части команды вместо инструкций окажется однострочный файл. Это легко пропустить: агент работает как обычно, просто без проектных правил.

**`CLAUDE.local.md` в проекте на AGENTS.md.** Личный файл молча отключает чтение общего. Лечится импортом `@AGENTS.md` в CLAUDE.local.md или режимом `claude-md-and-agents-md` в пользовательских настройках.

**Устаревший файл.** AGENTS.md с командами, которые больше не работают, хуже отсутствия файла: агенты выполняют инструкции старательно. Файл стоит менять в том же PR, что и команды сборки, и проверять на ревью.

Разница между самими агентами разобрана в [сравнении Claude Code и Codex](https://futurecraft.pro/ru/blog/claude-code-vs-codex/), место файлов правил в командном процессе описано в [гайде по vibe coding](https://futurecraft.pro/ru/blog/vibe-coding-guide/), общая настройка Claude Code есть в [полном гайде по Claude Code](https://futurecraft.pro/ru/blog/claude-code-complete-guide/).

## С чего начать

1. Запустить `/context all` в Claude Code и посмотреть, какие файлы инструкций реально загружаются сейчас.
2. Найти все файлы инструкций в репозитории: CLAUDE.md, CLAUDE.local.md, AGENTS.md, `.cursor/rules`, `.github/copilot-instructions.md`. Если среди них есть копии, выбрать одну источником правды.
3. Перенести общее в AGENTS.md, Claude-специфичное оставить в CLAUDE.md под строкой `@AGENTS.md`.
4. Проверить размер: `wc -c` по всем AGENTS.md в цепочке от корня до самого глубокого пакета; сумма должна оставаться заметно ниже 32 KiB.
5. Проверить каждым агентом: `/context all` в Claude Code, `codex ... "Summarize the current instructions."` в Codex, `/memory show` в Gemini CLI, если он у вас ещё работает.