AGENTS.md: что это и как подружить Claude Code с Codex
Содержание
AGENTS.md — файл в корне репозитория, который описывает правила проекта для любого AI-агента: Codex, Cursor, Copilot, Gemini CLI, Aider и других. Если коротко, это README для агентов: один файл, одна правда. Сайт стандарта пишет, что им пользуются больше 60 000 открытых проектов, его ведёт Linux Foundation, а нативно читают больше двадцати инструментов. Вот как я внедрил AGENTS.md у себя в марте 2026 и решил главную проблему: Claude Code тогда читал только CLAUDE.md.
Обновлено 15 октября 2026: с версии 2.1.277 Claude Code сам читает AGENTS.md, если CLAUDE.md в проекте нет.
Готовый пример этой схемы лежит в публичном репозитории serejaris/agent-starter: один файл правил и общая папка скиллов для Claude Code, Codex и Cursor. Про правила и скиллы я писал отдельно: как написать файл правил, чтобы агент слушался и как держать одни скиллы во всех агентах.
Проблема: агенты живут в разных реальностях
У меня три агента на проекте. Claude Code на Opus 4.6 — основной, делает всё: от фич до рефакторинга. Codex CLI на gpt-5.4-codex — крупные задачи и финальное ревью. Cursor — UI-правки, когда нужно быстро поправить кнопку. Так было в марте 2026. С тех пор модели сменились: в changelog Claude Code уже Opus 5.5. Актуальные смотри в самих инструментах.
Каждый хорош в своём. Но каждый живёт в своей картине мира.
Claude Code читает CLAUDE.md. Cursor — .cursor/rules/. Codex — AGENTS.md. Три инструмента, три файла, три версии правды о проекте. Добавил новое правило? Обнови три файла. Забыл один — агент нарушает конвенцию, которую ты вчера зафиксировал.
Я ловил такое: Codex следовал конвенциям из AGENTS.md, а Claude Code — своим из CLAUDE.md. За день структура проекта расползалась.
Не конкуренция — специализация
Держать одну модель — как один нож на кухне. У каждого агента своя сильная сторона.
Claude Code — breadth. Широкий контекст, хорошо держит в голове весь проект, быстро переключается между задачами. Идеален для ежедневных операций: фичи, баги, рефакторинг, деплой.
Codex — depth. Медленнее, дороже, но копает глубже. Находит edge cases, которые Claude пропускает. Идеален для ревью и сложной логики. Я уже писал про кросс-валидацию моделей — связка работает лучше, чем каждый по отдельности.
Cursor — precision. Открыл файл, ткнул в строку, подправил. Без промпта, без ожидания. Для мелких визуальных правок быстрее, чем объяснять агенту словами.
Но специализация работает только если все трое договорились о правилах. Иначе — хаос.
Что такое AGENTS.md
AGENTS.md — это конвенция, а не фича конкретного инструмента. Файл в корне репозитория, который описывает:
- Архитектурные принципы проекта
- Конвенции именования
- Запрещённые паттерны
- Workflow для типовых задач
- Границы: что можно делать, что нельзя, что требует подтверждения
Формат стартовал летом 2025 как community-инициатива. К марту 2026 за ним стоит Linux Foundation через Agentic AI Foundation. На 15 октября 2026 сайт стандарта пишет про «более 60 тысяч открытых проектов» и больше двадцати поддерживающих инструментов: Codex, Copilot, Gemini CLI, Windsurf, Aider, JetBrains Junie и другие. В марте я ссылался на обзор Socket и DeployHQ. Свежих независимых цифр у меня нет.
Описываешь правила один раз — каждый агент подхватывает их автоматически.
РЕПОЗИТОРИЙ
├── AGENTS.md ← один файл, одна правда
├── src/
├── tests/
└── ...
AGENTS.md
│
┌────┼────────────┐
│ │ │
▼ ▼ ▼
Codex Cursor Windsurf
Copilot Cline Aider
... ...
20+ инструментов читают нативно
(по списку agents.md)Нюанс: Claude Code и CLAUDE.md
Как было в марте. Claude Code не читал AGENTS.md. Он искал только CLAUDE.md, свой формат. Можно было вылизывать AGENTS.md сколько угодно, Claude Code его игнорировал.
Как сейчас. Claude Code научился читать AGENTS.md. В changelog версии 2.1.277 (сентябрь 2026) написано: в проекте без CLAUDE.md он берёт AGENTS.md. Версия 2.1.281 добавила то же для сессий на Bedrock, Vertex, Foundry, за LLM-шлюзами и с выключенной телеметрией. По документации по умолчанию так:
| В репозитории лежит | Claude читает |
|---|---|
| только AGENTS.md | AGENTS.md |
| AGENTS.md и CLAUDE.md (или CLAUDE.local.md) | только CLAUDE.md |
CLAUDE.md с @AGENTS.md внутри |
CLAUDE.md и подтянутый через импорт AGENTS.md |
Проверка простая: если Claude Code прочитал AGENTS.md сам, в начале сессии будет строка вида no CLAUDE.md found; AGENTS.md loaded: .... Поведение меняется в /config, в поле Project instructions. Оговорка из доков: в сессиях на версиях до 2.1.277 или с выключенным встроенным плагином Claude читает только CLAUDE.md.
Что это значит для схемы из этой статьи. Один источник правды в AGENTS.md по-прежнему правильный выбор. Тонкий CLAUDE.md теперь нужен не всегда:
- Если Claude-специфичных правил нет, CLAUDE.md можно вообще не заводить, Claude Code возьмёт AGENTS.md сам.
- Если правила для Claude есть, оставляй CLAUDE.md и первой строкой пиши импорт
@AGENTS.md, дальше свои пункты. Этот вариант прямо приведён в документации и не даёт прочитать файл дважды. - Симлинк
CLAUDE.md -> AGENTS.mdтоже работает, так сделано в agent-starter. Доки предупреждают про две вещи: Edit и Write откажутся писать через симлинк, а на Windows симлинк без прав администратора превращается в однострочный текстовый файл.
Моя мартовская обёртка держалась на словах: в CLAUDE.md стояла фраза «читай AGENTS.md». Доки пишут, что так Claude увидит файл, только если сам решит его открыть. Импорт @AGENTS.md надёжнее, его я и рекомендую.
Дублировать контент в оба файла я не стал: два источника правды, рассинхрон гарантирован. Я сделал CLAUDE.md тонкой обёрткой.
Я попросил агента:
Промпт для Claude Code (Opus 4.6):
Сделай CLAUDE.md минимальным: только ссылка на AGENTS.md как source of truth и специфичные для Claude Code инструкции. Никакой дублирующей логики.
Агент превратил CLAUDE.md в указатель. Весь канонический контент — архитектура, конвенции, границы, workflow — живёт в AGENTS.md. CLAUDE.md содержит одну секцию: “Читай AGENTS.md” плюс пара Claude Code-специфичных правил (формат коммитов, какие файлы не трогать). Сегодня я бы заменил эту фразу импортом @AGENTS.md.
РЕПОЗИТОРИЙ
├── AGENTS.md ← канонический контент
├── CLAUDE.md ← thin wrapper: @AGENTS.md (с сентября 2026 можно без него)
├── .cursor/rules ← thin wrapper: "читай AGENTS.md"
└── src/
┌──────────┐
│ AGENTS.md│ ← single source of truth
│ │
│ • архитектура
│ • конвенции
│ • границы
│ • workflow
└──────────┘
│
┌────┼─────────┐
│ │ │
▼ ▼ ▼
CLAUDE.md .cursor/rules (другие)
│ │ │
│ "читай │ "читай │
│ AGENTS" │ AGENTS" │
│ + свои │ + свои │
│ правила │ правила │
▼ ▼ ▼
Claude Cursor Остальные
Code агентыТеперь обновляю правила в одном месте. Claude Code получает их через обёртку. Codex, Copilot и все остальные — напрямую.
Что писать в AGENTS.md
Создать AGENTS.md — полдела. Я пробовал класть туда абстрактные принципы вроде “соблюдайте чистый код”. Бесполезно — агент кивает и делает по-своему. Сработало, когда правила стали конкретными.
Я попросил агента сгенерировать первую версию:
Промпт для Claude Code (Opus 4.6):
Создай AGENTS.md для моего проекта. Включи: архитектурные принципы, конвенции именования, запрещённые паттерны, workflow для новых фич. Сделай так, чтобы любой AI-агент, прочитав файл, понял контекст проекта без дополнительных объяснений.
Что работает:
- Canonical paths — где лежит что. Агенты не гадают, в какой папке создавать файл.
- Границы — что можно делать автономно, что требует подтверждения, что запрещено. Таблица из трёх строк спасает от катастроф.
- Source of truth — какой файл является каноном для каких данных. Когда у тебя data layer для агентов, важно указать, откуда брать числа.
- Safe defaults — что делать в ситуации неопределённости. “Сначала проверь X, потом обнови Y, потом Z.”
Что не работает:
- Абстрактные принципы вроде “пиши чистый код”
- Слишком длинные описания — агент теряет суть в стене текста
- Дублирование одних и тех же правил в нескольких секциях
Git worktrees: изоляция без боли
Единый AGENTS.md решает проблему правил. Но остаётся проблема пространства. Два агента не могут одновременно редактировать одни и те же файлы.
Решение — git worktrees. Встроенная возможность git: один репозиторий, несколько рабочих директорий. По сути — каждый агент получает свою песочницу со своей веткой, но общей историей.
Промпт для Claude Code (Opus 4.6):
Настрой git worktrees так, чтобы каждый агент мог работать в отдельной директории. Claude Code — в одной ветке, Codex — в другой. Общий .git, изолированные рабочие директории.
Агент создал две рабочие директории рядом с основным репозиторием. Claude Code работает в одной, Codex — в другой. Оба видят одинаковый AGENTS.md (он в общем .git), но не мешают друг другу при редактировании файлов.
Claude Code v2.1.49 добавил флаг --worktree (-w): сессия стартует сразу в изолированном git worktree. Субагенты тоже умеют работать во временном worktree.
~/project/ ← основная директория (Claude Code)
~/project-codex/ ← worktree (Codex)
Оба:
├── AGENTS.md ← одинаковый
├── CLAUDE.md ← одинаковый
├── src/ ← разные ветки, разные файлы
└── .git → ~/project/.git ← общий репозиторийAGENTS.md — единые правила. Worktrees — изолированное пространство. Вместе получается команда, а не группа фрилансеров, которые никогда не разговаривали друг с другом.
Итог
Не модель определяет полезность агента — инфраструктура вокруг неё. Я это понял, когда перестал гнаться за лучшей моделью и занялся тем, чтобы агенты договорились между собой.
Три шага:
- Создать AGENTS.md с конкретными правилами проекта
- Если нужны Claude-специфичные правила, сделать CLAUDE.md тонким файлом с импортом
@AGENTS.md; если не нужны, Claude Code сам читает AGENTS.md (с версии 2.1.277)..cursor/rules/свести к ссылке на AGENTS.md - Дать каждому агенту свой worktree
60 000 проектов, 20+ инструментов, Linux Foundation, а с сентября 2026 ещё и Claude Code. Если у тебя больше одного AI-агента на проекте — AGENTS.md уже пора. Готовую папку с правилами и общими скиллами можно взять в agent-starter.