AGENTS.md: дружим Claude Code с Codex

Сережа Рис · 14 March 2026

AGENTS.md — файл в корне репозитория, который описывает правила проекта для любого AI-агента. Один файл, одна правда. 60 000+ репозиториев уже используют его, стандарт поддерживается Linux Foundation и читается нативно двадцатью инструментами. Вот как я внедрил его у себя и решил главную проблему — Claude Code читает не его, а CLAUDE.md.

Проблема: агенты живут в разных реальностях

У меня три агента на проекте. Claude Code на Opus 4.6 — основной, делает всё: от фич до рефакторинга. Codex CLI на gpt-5.4-codex — крупные задачи и финальное ревью. Cursor — UI-правки, когда нужно быстро поправить кнопку.

Каждый хорош в своём. Но каждый живёт в своей картине мира.

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. Больше 60 000 репозиториев уже содержат этот файл. Нативно его читают 20+ инструментов: Codex, Copilot, Gemini CLI, Windsurf, Cline, Aider, JetBrains Junie и другие.

Описываешь правила один раз — каждый агент подхватывает их автоматически.

РЕПОЗИТОРИЙ
├── AGENTS.md          ← один файл, одна правда
├── src/
├── tests/
└── ...

     AGENTS.md
         │
    ┌────┼────────────┐
    │    │             │
    ▼    ▼             ▼
 Codex  Cursor      Windsurf
 Copilot Cline      Aider
         ...         ...

    20+ инструментов читают нативно

Нюанс: Claude Code читает CLAUDE.md

Claude Code не читает AGENTS.md. Он ищет CLAUDE.md — свой формат. Можно вылизывать AGENTS.md сколько угодно, Claude Code его проигнорирует.

Дублировать контент в оба файла? Два источника правды, рассинхрон гарантирован. Я пошёл другим путём — сделал CLAUDE.md тонкой обёрткой.

Я попросил агента:

Агент превратил CLAUDE.md в указатель. Весь канонический контент — архитектура, конвенции, границы, workflow — живёт в AGENTS.md. CLAUDE.md содержит одну секцию: “Читай AGENTS.md” плюс пара Claude Code-специфичных правил (формат коммитов, какие файлы не трогать).

РЕПОЗИТОРИЙ
├── AGENTS.md          ← канонический контент
├── CLAUDE.md          ← thin wrapper: "читай AGENTS.md"
├── .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 — полдела. Я пробовал класть туда абстрактные принципы вроде “соблюдайте чистый код”. Бесполезно — агент кивает и делает по-своему. Сработало, когда правила стали конкретными.

Я попросил агента сгенерировать первую версию:

Что работает:

• Canonical paths — где лежит что. Агенты не гадают, в какой папке создавать файл.
• Границы — что можно делать автономно, что требует подтверждения, что запрещено. Таблица из трёх строк спасает от катастроф.
• Source of truth — какой файл является каноном для каких данных. Когда у тебя data layer для агентов, важно указать, откуда брать числа.
• Safe defaults — что делать в ситуации неопределённости. “Сначала проверь X, потом обнови Y, потом Z.”

Что не работает:

• Абстрактные принципы вроде “пиши чистый код”
• Слишком длинные описания — агент теряет суть в стене текста
• Дублирование одних и тех же правил в нескольких секциях

Git worktrees: изоляция без боли

Единый AGENTS.md решает проблему правил. Но остаётся проблема пространства. Два агента не могут одновременно редактировать одни и те же файлы.

Решение — git worktrees. Встроенная возможность git: один репозиторий, несколько рабочих директорий. По сути — каждый агент получает свою песочницу со своей веткой, но общей историей.

Агент создал две рабочие директории рядом с основным репозиторием. Claude Code работает в одной, Codex — в другой. Оба видят одинаковый AGENTS.md (он в общем .git), но не мешают друг другу при редактировании файлов.

Claude Code v2.1.49 добавил нативную поддержку worktrees — агент понимает, что он в worktree, и корректно работает с путями и ветками.

~/project/                ← основная директория (Claude Code)
~/project-codex/          ← worktree (Codex)

Оба:
├── AGENTS.md             ← одинаковый
├── CLAUDE.md             ← одинаковый
├── src/                  ← разные ветки, разные файлы
└── .git → ~/project/.git ← общий репозиторий

AGENTS.md — единые правила. Worktrees — изолированное пространство. Вместе получается команда, а не группа фрилансеров, которые никогда не разговаривали друг с другом.

Итог

Не модель определяет полезность агента — инфраструктура вокруг неё. Я это понял, когда перестал гнаться за лучшей моделью и занялся тем, чтобы агенты договорились между собой.

Три шага:

1. Создать AGENTS.md с конкретными правилами проекта
2. Превратить CLAUDE.md и .cursor/rules/ в thin wrappers
3. Дать каждому агенту свой worktree

60 000 репозиториев, 20+ инструментов, Linux Foundation. Если у тебя больше одного AI-агента на проекте — AGENTS.md уже пора.

Об авторе

Подписаться на обновления — @sereja_tech