Cursor Rules: как настроить .cursor/rules и AGENTS.md

Cursor Rules — постоянные инструкции, которые Agent может учитывать при работе с проектом. Проектные правила хранятся в .cursor/rules в формате .mdc; для простого набора инструкций можно использовать AGENTS.md. В frontmatter правила задаются область применения, описание и режим включения.

Актуальная официальная документация Cursor Rules описывает четыре типа: Project Rules, User Rules, Team Rules и AGENTS.md. Ниже — практическая схема для личного репозитория и команды.

Правило оправдано, если вы регулярно повторяете одну и ту же инструкцию:

Rules не являются магическим исправлением. Они дают Agent устойчивый контекст, но не заменяют линтер, типы, тесты и code review. Если ограничение можно гарантировать инструментом, лучше сделать это инструментом, а не только текстовой инструкцией.

Хранятся в .cursor/rules, могут быть добавлены в Git и относятся к конкретной кодовой базе. Это основной формат для архитектурных соглашений и локальных workflows.

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

Командные правила, управляемые через dashboard на соответствующих планах. Их можно включать и, при необходимости, принудительно применять к участникам команды.

Простой Markdown-файл с инструкциями для Agent. Он удобен, если не нужны frontmatter и разные режимы применения. Cursor поддерживает AGENTS.md в корне и во вложенных каталогах, причём более специфичные инструкции могут уточнять родительские.

Проектные Rules в .cursor/rules должны быть файлами .mdc с frontmatter. Обычный .md в этой папке не будет распознан как проектное правило. Если нужна простая Markdown-инструкция без метаданных, используйте AGENTS.md.

Минимальная структура .mdc выглядит так:

description: Правила для компонентов и API
globs: components/**/*.tsx, app/api/**/*.ts
alwaysApply: false

Проверяй входные данные на границе API.
Используй существующие компоненты интерфейса.
После изменения запусти type-checker.

В самом файле Cursor использует frontmatter-метаданные. Конкретный способ создать и включить правило проверяйте в текущем интерфейсе и официальной документации.

В Cursor есть четыре практических варианта:

Выбирайте самый узкий режим, который решает задачу. Глобальное правило на 400 строк создаёт шум и повышает риск конфликтов. Локальное правило для components/**/*.tsx легче проверить и обновить.

Вместо расплывчатой фразы:

Пиши хороший код.

Напишите конкретнее:

Для API-обработчиков:
1. Валидируй входные данные до вызова бизнес-логики.
2. Возвращай существующий формат ошибок проекта.
3. Не меняй публичную схему без отдельного плана.
4. Добавляй тест на ошибочный и успешный путь.

Каждый пункт должен помогать принять решение по конкретному diff. Если правило нельзя проверить глазами или тестом, оно, вероятно, слишком общее.

Укажите, где находится бизнес-логика, где запросы к базе и какие слои не должны импортировать друг друга.

Сошлитесь на существующие компоненты и конфигурацию линтера вместо копирования всей style guide. Cursor рекомендует держать правила focused, actionable and scoped.

Перечислите команды type-checker, тестов или сборки, но не добавляйте десятки редко используемых команд.

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

Не добавляйте:

Официальные best practices Cursor советуют начинать с малого и добавлять правило после того, как Agent несколько раз повторил одну и ту же ошибку.

Если проект небольшой, начните с AGENTS.md в корне:

# Project instructions

## Architecture
- Keep API validation at the route boundary.
- Put database access in lib/.

## Verification
- Run the existing type-checker after TypeScript changes.
- Run focused tests before the full suite.

## Safety
- Do not modify generated files without an explicit plan.
- Do not print secrets in terminal output.

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

После создания не предполагайте, что оно применяется. Проверьте:

Попросите Agent явно перечислить применённые правила. Если он их не называет, проверьте область и тип применения.

Rules — долгосрочная инструкция, а @-ссылка — контекст конкретного запроса. Не заменяйте одно другим. Укажите в Rule общую границу, а в запросе добавьте конкретный файл или символ. Подробно о краткосрочном контексте — в гайде PLPB, о многофайловых задачах — в статье про Cursor Agent.

Не создавайте сразу большую библиотеку инструкций. Выберите повторяющуюся ошибку и напишите одно короткое правило:

Когда меняешь API-обработчик:
1. Сначала проверь существующую схему входных данных.
2. Сохрани публичный формат ошибки.
3. Добавь тест на успешный и ошибочный путь.
4. Запусти текущий type-checker.

Проверьте его на двух похожих задачах. Если правило помогает и не создаёт ложных ограничений, оставьте его в проекте. Если оно слишком общее, сузьте glob или перепишите формулировку.

Для небольшого репозитория достаточно такой схемы:

.cursor/
  rules/
    api.mdc
    frontend.mdc
AGENTS.md

AGENTS.md может содержать общие правила, а .mdc — инструкции для отдельных слоёв. Не дублируйте один и тот же текст в трёх местах: конфликтующие источники труднее сопровождать.

Glob должен соответствовать реальным путям. components/**/*.tsx и app/**/*.tsx — разные области. После создания правила проверьте его на файле, который точно должен совпадать, и на файле, который точно не должен совпадать.

Если правило применилось слишком широко, не лечите проблему ещё одним исключением. Сначала исправьте область первого правила.

Правило нужно пересматривать, если:

Владелец проекта должен понимать, почему правило существует. Пишите дату или причину только там, где это действительно помогает сопровождению, и не превращайте файл в журнал истории.

Текстом можно объяснить архитектурную мотивацию, но проверяемую часть лучше реализовать в коде: типах, тестах, линтере, pre-commit hook или CI. Тогда Agent получает полезную подсказку, а проект сам отклоняет нарушение.

В .cursor/rules в виде .mdc-файлов. Храните их в Git, если они нужны всей команде.

Нет, для проектных правил нужен формат .mdc с метаданными. Для простой Markdown-инструкции используйте AGENTS.md.

Rules удобнее для областей применения и разных режимов включения. AGENTS.md проще для коротких иерархических инструкций без сложной настройки.

Правила предназначены прежде всего для Agent и связанных сценариев. Не рассчитывайте, что текстовая инструкция изменит поведение каждой AI-функции; проверяйте ограничения конкретного режима.

Нет. Оставьте короткие проверяемые требования и ссылки на канонические примеры. Полный style guide лучше поддерживать отдельно и автоматизировать линтером.

Проверьте расширение .mdc, frontmatter, glob-пути, режим применения и конфликт с другим правилом. Попросите Agent показать список применённых инструкций.