AGENTS.md vs CLAUDE.md vs Cursor Rules: какой файл инструкций выбрать
AGENTS.md, CLAUDE.md и Cursor Rules — это файлы постоянных инструкций для coding agents. Они передают агенту архитектуру проекта, команды проверки, ограничения и рабочий процесс при каждой новой задаче. Различие не в качестве правил, а в том, какой инструмент обнаруживает файл и как подключает его к контексту.
Короткий ответ: AGENTS.md подходит как переносимый базовый слой,
CLAUDE.md — как точка входа Claude Code, а .cursor/rules/*.mdc — как
механизм точного подключения правил в Cursor. В проекте, где используются
несколько агентов, обычно нужен не выбор одного победителя, а один канонический
набор правил и тонкие адаптеры для конкретных инструментов.
AGENTS.md: переносимая карта репозитория
AGENTS.md — открытый формат инструкций для coding agents. Это обычный Markdown без обязательной схемы. В нём удобно держать сведения, которые должны одинаково понимать разные инструменты:
- назначение продукта и границы задачи;
- карту каталогов и направление импортов;
- команды запуска, тестов, lint и сборки;
- инварианты безопасности и качества;
- правила для документации и Git;
- критерии готовности изменения.
Стандарт допускает вложенные AGENTS.md: корневой файл задаёт общие правила,
а файл внутри пакета или каталога уточняет их для своей области. Это делает
формат полезным в монорепозиториях и в проектах, где один и тот же код открывают
разные агенты.
Важно отделять спецификацию от инструкций. AGENTS.md говорит как работать
с репозиторием, а feature spec — какое поведение нужно получить в конкретном
изменении. Если положить требования одной фичи в постоянный файл, они останутся
в контексте и после завершения работы.
Подробнее о структуре и готовом шаблоне — в статье «AGENTS.md: пример и шаблон файла для AI-агентов».
CLAUDE.md: нативная память проекта для Claude Code
CLAUDE.md — файл постоянных инструкций, который Claude Code загружает в
контекст проекта. Документация Claude Code
разделяет написанные человеком инструкции и auto memory: первое задаёт правила,
второе хранит накопленные агентом наблюдения. Оба механизма дают контекст, но не
являются принудительным ограничением.
Claude Code читает CLAUDE.md, а не AGENTS.md напрямую. Если канонические
правила уже лежат в AGENTS.md, документация рекомендует импортировать их:
@AGENTS.md
## Claude Code
- Use plan mode before changing the billing flow.
Так общие правила не расходятся, а ниже остаётся место для действительно
Claude-специфичного поведения. Если дополнительных инструкций нет, возможен
symlink CLAUDE.md → AGENTS.md.
Для больших проектов у Claude Code есть .claude/rules/: отдельные Markdown-
файлы можно привязать к путям, чтобы не загружать frontend-правила при работе с
миграцией. Это ближе к Cursor Rules по области действия, хотя формат и механизм
обнаружения отличаются.
Cursor Rules: правила с явным способом подключения
Cursor Project Rules живут в
.cursor/rules/*.mdc. MDC-файл сочетает Markdown-инструкции и frontmatter,
который определяет, когда правило попадёт в контекст. В текущей документации
есть четыре режима:
Always Apply— правило присутствует в каждой сессии;Apply Intelligently— агент подключает его по описанию;Apply to Specific Files— правило связано с glob-паттернами;Apply Manually— правило добавляют через@-упоминание.
Cursor также поддерживает корневые и вложенные AGENTS.md как простой Markdown-
вариант без metadata. Поэтому базовые правила не обязательно дублировать в MDC.
Cursor Rules нужны там, где важна управляемая активация: например, требования к
SQL-миграциям должны появляться при работе с migrations/**, а сценарий релиза —
только по явному запросу.
Подробный разбор формата есть в статье «Cursor Rules: как настроить правила для AI-редактора».
Что выбрать для одного инструмента
Если проект открывают только в Claude Code, достаточно CLAUDE.md и, по мере
роста, .claude/rules/. Это нативный путь с понятной диагностикой через
/context.
Если работа идёт только в Cursor, для небольшого репозитория достаточно
AGENTS.md; MDC-правила стоит добавлять, когда появляются path-scoped или
ручные процедуры.
Если инструменты меняются, каноническим слоем лучше сделать AGENTS.md, а
CLAUDE.md использовать как импорт и место для Claude-специфичных добавлений.
Cursor при этом прочитает AGENTS.md, а его собственные правила останутся в
.cursor/rules/.
Рабочая структура без дублирования
Практичная конфигурация выглядит так:
AGENTS.md # общие правила проекта
CLAUDE.md # @AGENTS.md + только Claude-специфичное
.claude/rules/testing.md # правила Claude для конкретной области
.cursor/rules/testing.mdc # способ подключения в Cursor
docs/specs/ # требования к отдельным изменениям
Содержимое testing.md и testing.mdc не обязано дословно совпадать. Лучше
вынести сам контракт тестирования в обычный файл документации, а в agent rules
оставить короткую ссылку, область действия и обязательную команду проверки.
Тогда изменение стандарта происходит в одном месте.
Почему файл инструкций не является enforcement
Любой из трёх форматов влияет на контекст модели. Он повышает вероятность
правильного решения, но не делает запрещённое действие технически невозможным.
Документация Claude Code прямо предлагает использовать PreToolUse hook, если
операцию нужно блокировать независимо от решения агента.
Поэтому зрелая схема состоит из нескольких слоёв:
AGENTS.mdилиCLAUDE.mdобъясняет инвариант.- Path-scoped rules подают его в нужном контексте.
- Linter, type checker, test или hook проверяет машинно проверяемую часть.
- CI не пропускает изменение, если проверка красная.
Файл отвечает за понимание, gate — за соблюдение. Их нельзя считать взаимозаменяемыми.
Критерий хорошей конфигурации
Правильный набор файлов можно проверить без спора о названиях:
- новый агент быстро находит команды и границы архитектуры;
- правило загружается только там, где оно относится к задаче;
- общая инструкция редактируется в одном месте;
- невыполнимое пожелание не маскируется под «жёсткое правило»;
- критичные ограничения подтверждаются тестами, hooks или CI;
- завершённая feature spec не остаётся вечным глобальным контекстом.
Если эти условия выполняются, AGENTS.md, CLAUDE.md и Cursor Rules образуют
одну систему, а не три конкурирующих документа.
Нужно выстроить такой процесс для продукта или подготовить проект к работе с coding agents? Опишите задачу — разберём текущий репозиторий, границы автоматизации и набор проверяемых правил.