Cursor Rules: как настроить правила проекта

Коротко

Cursor Rules — это инструкции, которые Cursor автоматически подмешивает в контекст ИИ-агента: стек проекта, стиль кода, запреты и командные договорённости. Актуальный формат — файлы .cursor/rules/*.mdc с YAML-frontmatter из трёх полей: description, globs, alwaysApply. Старый .cursorrules в корне проекта пока читается ради совместимости, но официально объявлен legacy. Правило бывает четырёх типов: Always (в каждом запросе), Auto Attached (по маске файлов), Agent Requested (агент сам решает по описанию) и Manual (только по @имя-правила). Типичные причины «правила не работают»: расширение .md вместо .mdc, сломанный frontmatter, тысячи строк текста и alwaysApply: true на всём подряд. Ниже — рабочие примеры под пять задач, разбор ошибок и способ вообще не писать .mdc руками.

Что такое Cursor Rules и зачем они нужны

У модели нет памяти между чатами: каждый новый диалог агент начинает с нуля и заново «угадывает» ваш стек, стиль и границы дозволенного. Cursor Rules решают ровно эту проблему — это постоянный контекст, который редактор сам добавляет к промпту в нужный момент. Один раз описали, что проект на Next.js с pnpm, что any запрещён, а секреты живут только в переменных окружения, — и больше не повторяете это в каждом запросе.

На практике правила экономят не только время, но и качество: агент, который знает границы, реже фантазирует и реже требует переделок. Это тот же принцип, что и в постановке задач: чем точнее контекст, тем меньше итераций (разбирали в статье как поставить задачу, чтобы агент понял; системные техники работы с агентами собраны в приёмах вайб-кодинга).

Какой формат актуален: .cursorrules или .cursor/rules?

.cursorrules — это устаревший формат: один plain-text файл в корне проекта, без метаданных и без выборочного подключения. Cursor пока читает его ради обратной совместимости, но в официальной документации формат помечен как legacy, и новые возможности на него не распространяются. Если он у вас ещё живёт — мигрируйте: перенесите содержимое в .cursor/rules/ и разбейте на тематические файлы.

Актуальных механизмов два:

• .cursor/rules/*.mdc — основной формат. Каждое правило — отдельный .mdc-файл с YAML-шапкой, которая управляет тем, когда правило попадает в контекст. Вложенные папки поддерживаются: .cursor/rules/frontend/react.mdc — валидный путь, а каталог .cursor/rules внутри пакета монорепы действует только на этот пакет.
• AGENTS.md — это простой markdown-файл без метаданных в корне проекта (или в подкаталогах — тогда более специфичные инструкции побеждают). Межинструментальный стандарт, который читают и Cursor, и другие агенты. Подходит для короткого описания проекта, но не умеет ни glob-масок, ни ручного вызова.

Важная деталь: в .cursor/rules/ работают только файлы с расширением .mdc. Обычный .md там молча игнорируется — это, пожалуй, самая частая причина жалобы «правила не применяются».

Как устроен .mdc и четыре типа правил

Файл .mdc — это markdown с YAML-frontmatter из трёх полей. Комбинация полей определяет тип правила:

Логику выбора типа мы подробно разбирали в статье Always, Auto, Agent, Manual: какой тип правила когда брать; коротко — так:

• alwaysApply: true — только для фундамента: стек, менеджер пакетов, главные запреты. Такое правило тратит токены в каждом запросе, поэтому блок обязан быть коротким.
• globs — для всего, что привязано к типу файлов: правила тестов не нужны при вёрстке, а правила CSS — при написании миграций.
• description — для ситуационных правил; пишите описание так, будто объясняете человеку, когда его применять. Расплывчатое описание агент просто не «поймает».
• Manual — для процедур по требованию: формат коммита, чек-лист релиза.

Официальная рекомендация Cursor — держать правило в пределах 500 строк и резать большие темы на композируемые файлы. Практический ориентир жёстче: 20–60 строк. Правило-«роман» агент выполняет хуже, чем три коротких.

Примеры правил под пять задач

1. Стиль кода — Auto Attached на исходники:

---
description: Стиль TypeScript-кода
globs: src/**/*.ts,src/**/*.tsx
alwaysApply: false
---
- Только именованные экспорты, default запрещён
- Вместо any — unknown с сужением типа
- Ошибки не глотать: catch либо пробрасывает, либо логирует с контекстом

2. Стек проекта — Always, максимально коротко:

---
description: Контекст проекта
alwaysApply: true
---
Next.js 15 (App Router) + TypeScript + Prisma/PostgreSQL + Tailwind.
Пакетный менеджер — pnpm; npm и yarn не предлагать.
Новые зависимости — только после явного согласования.

3. Тесты — Auto Attached на спеки:

---
description: Правила тестов
globs: **/*.test.ts,**/*.spec.ts
alwaysApply: false
---
- Vitest, моки через vi.mock, снапшоты запрещены
- Имя теста = поведение: «возвращает 404, если пользователь не найден»
- Не подгонять код под тест — сначала спросить

4. Безопасность — Always, потому что дыры не привязаны к маске файлов:

---
description: Безопасность
alwaysApply: true
---
- Секреты только из process.env: не хардкодить, не логировать
- Пользовательский ввод валидировать zod-схемой на границе API
- SQL — только параметризованный, через ORM

Какие ещё запреты стоит зашить агенту — в security-карточках арсенала.

5. Коммиты — Manual, вызывается как @commit-style перед коммитом:

---
alwaysApply: false
---
Conventional Commits: feat|fix|refactor|chore(scope): суть в повелительном
наклонении, до 72 символов. В теле коммита — «зачем», а не «что».

Почему правила не работают: типичные ошибки

1. .md вместо .mdc. Файл молча игнорируется — без ошибок и предупреждений.
2. Сломанный frontmatter. YAML чувствителен к регистру и синтаксису: True вместо true, забытые ---, кавычки и квадратные скобки в globs — и правило перестаёт подключаться. Самый совместимый формат масок — через запятую, без кавычек и скобок. После правок проверяйте список применённых правил в контексте ответа агента.
3. Всё на alwaysApply: true. Контекст раздувается, важное тонет в шуме, качество ответов падает. Always-правил в проекте должно быть одно-два.
4. Правило-«роман». Сотни строк смешанных тем — агент выхватывает случайные куски. Одно правило = одна зона ответственности.
5. Расплывчатый description. Описание «правила по коду» агент не сматчит никогда; «применяй при работе с формами и валидацией» — сматчит.
6. Ожидание, что правила действуют везде. Rules читает агент в чате; автодополнение Tab работает по коду вокруг курсора и правил не видит.
7. Правила не в git. Смысл проектных правил — общая договорённость команды, поэтому .cursor/rules/ коммитят в репозиторий, как и код.

Откуда брать готовые правила

Писать с нуля не обязательно:

• Команда /Generate Cursor Rules прямо в чате Cursor: агент составит черновик по итогам текущего диалога — удобно фиксировать договорённости, к которым пришли в работе.
• cursor.directory — крупнейший каталог правил под конкретные стеки: React, Python, Go и десятки других.
• awesome-cursorrules на GitHub — коллекция шаблонов, многие уже сконвертированы в .mdc.
• Наш арсенал промптов — 105 карточек, из которых собираются правила под русскоязычные проекты: формулировки запретов, чек-листы ревью, шаблоны контекста.

Чужие наборы — сырьё, а не готовый конфиг: выкидывайте всё, что не про ваш проект. Десять чужих правил «на всякий случай» работают хуже трёх своих.

Как масштабировать: одна спека вместо пачки .mdc

Ручная поддержка правил упирается в предсказуемую проблему: команды работают и в Cursor, и в Claude Code (сравнивали инструменты здесь), и одни и те же договорённости приходится дублировать в .mdc, CLAUDE.md и AGENTS.md. Через месяц копии расходятся, и агенты в разных инструментах живут по разным законам.

Мы решаем это компиляцией: в движке Quest правила проекта описываются один раз — единой спекой, из которой детерминированно собираются .cursor/rules/*.mdc с корректными типами подключения, пакет для Claude Code и универсальный AGENTS.md (механику разбирали в статье про экспорт под инструмент). Поменяли спеку — пересобрали все форматы, дрейф исчезает по построению. Движок ставится разово (4 900 ₽, модули под отдельные задачи — по 1 900 ₽; цены на июль 2026), а подход «правила — артефакт сборки, а не рукопись» окупается уже на втором инструменте или втором проекте.

Если пока пишете правила руками — начните с четырёх файлов из примеров выше: стек, стиль, тесты, безопасность. Это час работы, который меняет поведение агента заметнее, чем смена модели.

Частые вопросы

Старый .cursorrules ещё работает?

Да, пока читается ради обратной совместимости, но в документации формат помечен как legacy, а новые механизмы — типы правил, glob-маски, вложенные папки — работают только в .cursor/rules/*.mdc. Миграция — перенос текста, минут десять.

Чем Cursor Rules отличаются от AGENTS.md и CLAUDE.md?

AGENTS.md — это межинструментальный стандарт: простой markdown без метаданных, который читают разные агенты, включая Cursor. CLAUDE.md — аналог для Claude Code. Rules — механизм именно Cursor: с типами подключения, масками файлов и ручным вызовом. Базовый контекст проекта разумно держать в AGENTS.md, специфику — в .mdc.

Почему агент игнорирует моё правило?

Три главных подозреваемых: расширение .md вместо .mdc, невалидный YAML во frontmatter и расплывчатый description у Agent Requested-правила. Проверьте список применённых правил в ответе агента: если правила там нет — проблема в подключении, а не в формулировках.

Сколько правил нужно проекту?

Меньше, чем кажется: 1–2 коротких Always (стек и запреты), 3–5 Auto Attached под типы файлов, остальное — по мере надобности. Ориентир Cursor — до 500 строк на правило, практический — 20–60 строк.

Правила влияют на автодополнение Tab?

Нет. Rules подключаются к агенту и чату; Tab строит подсказки по коду вокруг курсора и .mdc не читает. Управлять автодополнением можно только самим кодом и типами.