Файл .cursorrules и правила проекта: как настроить Cursor под свой стек

Языковая модель ничего не помнит между ответами. Каждый новый запрос она читает с чистого листа: не знает, что у вас TypeScript, а не JavaScript, что вы отступаете двумя пробелами, что импорты идут по алиасам, а компоненты лежат в src/components. И каждый раз, когда вы это не напомнили, ИИ-агент честно угадывает — иногда мимо.

Правила (rules) в Cursor — это способ перестать напоминать одно и то же руками. Вы один раз описываете, как устроен ваш проект и как в нём принято писать код, а Cursor подкладывает это описание в начало каждого запроса к агенту. Получается постоянная, переиспользуемая память проекта, которая едет вместе с репозиторием и работает одинаково у всей команды.

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

Что такое правила и что они реально делают

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

SpaceX · xStockSpaceX — частная компания. Торгуй её токеном на Bybit за крипту.Торговать SpaceX →

Важно сразу очертить границу, о которую спотыкаются новички: правила работают только в чате агента (Agent/Chat), но не влияют на автодополнение Cursor Tab и не применяются к строчному редактированию Inline Edit (Cmd/Ctrl+K) — по крайней мере пользовательские правила. Это официально задокументировано. То есть если вы ждали, что правило поменяет поведение автодополнения на лету, — оно не поменяет. Правила — это про агента.

Ковенанты биткоина: пять лет после Taproot и 0% сигнализации за OP_CTV

Claude Code включил форк-субагентов по умолчанию: разбор релизов с 2.1.232 по 2.1.239

Slack Code: агент заводит канал под задачу, а код уходит только после одобрения

OpenAI закрыла в Codex баг, из-за которого агент стирал домашний каталог

OpenAI поставила надзор за моделями: тревога за 30 минут и 20% вычислений сверху

Как устроен сам агентный чат — план до кода, чекпоинты для откатов и что реально контролирует авто-запуск команд — разобрано в статье про Agent Mode на максимум.

Зачем они нужны на практике:

• Закодировать знания о проекте — стек, архитектурные решения, соглашения об именах. То, что вы иначе объясняете каждому новому разработчику (и каждому новому чату).
• Стандартизировать стиль — чтобы код от ИИ выглядел как ваш, а не как усреднённый код из интернета.
• Автоматизировать типовые шаги — «после изменения схемы обнови типы», «новый эндпоинт — сразу с тестом».

Три формата правил: не путайте их

За пару лет у Cursor сменилось несколько способов хранить правила, и старые статьи описывают уже неактуальные форматы. Вот полная картина на июль 2026.

Старый .cursorrules (один файл в корне) Cursor всё ещё читает — ради обратной совместимости, — но документация и практики единогласно советуют мигрировать на папку .cursor/rules. Три независимых источника формулируют это одинаково: файл «работает, но deprecated».

AGENTS.md — это не конкурент .cursor/rules, а официально признанный Cursor вариант того же механизма: обычный markdown-файл с инструкциями для агента, «простая альтернатива» без метаданных. У него есть одна особенность, которая делает его сильнее в монорепозиториях, — о ней ниже.

Если ещё не поставили сам редактор, чтобы всё это попробовать: Cursor ставится бесплатно, правила доступны и на free-тарифе. Хотите сперва понять, что за инструмент и на чьих моделях он работает, — у нас есть полный обзор возможностей Cursor.

BYBITВсё ещё смотришь со стороны?Рынок работает без выходных. Счёт на Bybit открывается за 2 минуты.Начать сейчас

Четыре типа правил — и путаница в их названиях

Вот место, где ошибаются почти все. У проектных правил есть четыре типа поведения — когда именно правило подключается. В 2026 году Cursor переименовал эти типы, но огромная часть гайдов (в том числе обновлённых в июне 2026) до сих пор использует старые названия. Если вы читаете чужую статью и видите «Auto Attached» или «Agent Requested» — это устаревшая терминология.

Эту таблицу соответствия не даёт ни один из конкурентных гайдов — а без неё легко настроить правило «по инструкции из интернета» и не понять, почему оно ведёт себя не так, как обещали.

Как устроен .mdc-файл

Тип правила задаётся не в выпадающем меню на глаз, а тремя полями в YAML-заголовке (frontmatter) .mdc-файла:

• alwaysApply — булево. true = правило всегда в контексте (тип Always Apply).
• description — строка. Короткое описание, по которому агент решает, релевантно ли правило (тип Apply Intelligently — когда description задан, а globs нет).
• globs — маски файлов. Когда открытый файл подходит под маску, правило подключается (тип Apply to Specific Files).

Комбинация этих трёх полей и определяет тип. Пустой заголовок без всего — это Apply Manually: правило сработает, только если вы позовёте его через @имя-правила.

Пример простого проектного правила .cursor/rules/typescript.mdc:

---
description: Правила TypeScript-кода для этого проекта
globs: ["**/*.ts", "**/*.tsx"]
alwaysApply: false
---

- Строгий режим: никаких `any`, используем `unknown` + сужение типов.
- Именованные экспорты вместо default export.
- Асинхронные функции — только с обработкой ошибок через Result-тип из @/lib/result.

Отдельная грабля: проектные правила обязаны иметь расширение .mdc. По официальной документации обычный .md-файл в папке .cursor/rules игнорируется системой правил, потому что у него нет YAML-заголовка. Тут источники расходятся: один сторонний гайд утверждает, что .md «тоже работает, просто без метаданных». Мы держимся формулировки первоисточника — Cursor прямо говорит «ignored», так что не рискуйте и ставьте .mdc.

Где лежат файлы и почему подпапки монорепо ломаются

Папка .cursor/rules сканируется только в корне рабочего пространства. Внутри неё можно раскладывать правила по подпапкам (.cursor/rules/frontend/some-rule.mdc) — это Cursor видит и читает рекурсивно. А вот отдельные папки .cursor/rules внутри подкаталогов монорепо (например, packages/api/.cursor/rules) Cursor не обнаруживает — даже с alwaysApply: true.

Это подтверждённый ответ команды Cursor на форуме, а не догадка. И это самая частая причина жалоб «моё правило не применяется»: разработчик кладёт правила в подпакет монорепо и удивляется тишине.

Официальное решение как раз и объясняет, зачем нужен AGENTS.md: вложенные AGENTS.md автоматически обнаруживаются в любой подпапке и применяются к файлам этой директории и её потомков. Поэтому для монорепо рекомендация такая: общие правила — в корневой .cursor/rules, а специфику подпакета — в packages/api/AGENTS.md, а не во вложенной .cursor/rules.

Приоритет: кто побеждает при конфликте

Правил обычно несколько, и они бывают трёх уровней. Официальный порядок приоритета при конфликте инструкций:

Team Rules → Project Rules → User Rules. Team-правила (командные, задаются админом в дашборде) — высший приоритет; при спорной ситуации побеждает более ранний в этой цепочке источник.

Здесь важно предупредить: часть блогов даёт обратный порядок (якобы User-правила главнее всех). Это ошибка — не тиражируйте её. Официальная документация и независимый технический гайд сходятся на «Team → Project → User».

• User Rules — глобальные, на всё ваше окружение Cursor, задаются в настройках. Ваши личные привычки.
• Project Rules — в репозитории, едут с проектом, общие для всех, кто его клонирует.
• Team Rules — доступны на планах Team и Enterprise, управляются из дашборда. Админ может включить флаг Enforce — тогда правило обязательно для всех и его нельзя отключить локально.

Готовые шаблоны под свой стек

Писать правила с нуля не обязательно. Крупнейшая community-коллекция готовых наборов — репозиторий awesome-cursorrules от PatrickJS (около 40 тысяч звёзд на июль 2026): шаблоны под Next.js, React, Angular, Python, Go и десятки других стеков.

Есть и официальный способ подтянуть чужие правила прямо в интерфейсе: Customize → Rules → Add Rule → Remote Rule импортирует .mdc-правила из любого GitHub-репозитория, к которому у вас есть доступ, и раскладывает их в .cursor/rules/imported/.

Три коротких примера-заготовки под популярные комбинации (адаптируйте под себя):

React / Next.js + TypeScript — globs: ["**/*.tsx"]:

- Функциональные компоненты + хуки; классовых компонентов нет.
- Server Components по умолчанию; "use client" — только где реально нужен интерактив.
- Стили — Tailwind, без inline-стилей.

Python / FastAPI — globs: ["**/*.py"]:

- Тайпинги обязательны, mypy strict.
- Валидация вход/выхода — Pydantic-модели, не dict.
- Зависимости — через Depends, бизнес-логика вынесена из роутов в сервисы.

Монорепо — общее правило в корне + AGENTS.md в каждом пакете:

- Общие соглашения — в корневой .cursor/rules.
- Специфику пакета описывать в его AGENTS.md, не во вложенной .cursor/rules.

Как создать правило и не потерять его

Актуальных способов создать правило два:

1. /create-rule прямо в чате агента — опишите, что хотите, и агент сгенерирует .mdc-файл с правильным заголовком и положит его в .cursor/rules.
2. Customize → Rules → Add Rule в сайдбаре.

Старый путь через палитру команд Cmd+Shift+P → New Cursor Rule, который встречается в гайдах, в текущем интерфейсе заменён на /create-rule — ещё один пример дрейфа, из-за которого чужие инструкции не сходятся с тем, что вы видите на экране.

И главное правило про правила: коммитьте .cursor/rules в git. Это единогласная рекомендация всех источников без исключения. Правила версионируются вместе с кодом, приезжают ко всей команде при клонировании, а когда агент повторяет одну и ту же ошибку — вы правите правило, и на следующем pull выигрывают все.

Ещё один приём из документации: ссылайтесь на файлы кода через @filename, а не копируйте их содержимое в правило. Скопированный кусок кода устаревает при первом же рефакторинге, а ссылка остаётся актуальной. Консенсус трёх источников.

Слабые места и риски, о которых молчат

Вот где правила подводят на практике.

Apply Intelligently срабатывает не всегда. Тип, где агент сам решает по описанию, подключать ли правило, работает ненадёжно — и это подтвердил представитель Cursor на форуме ещё в феврале 2026. Рекомендация от самой команды: если критично, чтобы правило точно применилось, делайте его коротким и Always Apply, а не полагайтесь на «умное» подключение. Независимой перепроверки этого признания нет, но источник — сама Cursor.

Налог на токены. Каждое always-apply правило занимает место в контекстном окне ещё до того, как модель прочитает ваш код. Оценки разнятся: один источник называет «2000+ токенов на запрос» для 20 правил, другой — «16000+ токенов (8–12% окна)» для тех же 20 правил, но по 200 строк каждое. Числа не сопоставимы напрямую — всё зависит от длины файлов. Вывод один: правила должны быть короткими. Официальный потолок — до 500 строк на файл, практики советуют до 100–150.

Конфликтующие правила = непредсказуемость. Если два правила противоречат друг другу («используй default export» и «никогда не используй default export»), Cursor следует более свежезагруженному или выдаёт непоследовательный результат. Чёткого механизма разрешения конфликтов внутри одного типа документация не даёт — так что при добавлении новых правил проверяйте их на противоречия со старыми.

Антипаттерны: как формулировать не надо

Правило работает ровно настолько, насколько конкретно оно написано. Расплывчатые инструкции модель трактует как хочет — и вы получаете тот же разнобой, от которого пытались уйти. Сравните:

• Плохо: «Пиши хороший код и следуй лучшим практикам». Для модели это шум — «хороший» у каждого свой, конкретного действия тут нет.

• Хорошо: «Компоненты — функциональные, с типизированными пропсами через interface; побочные эффекты только в useEffect с явным списком зависимостей».

• Плохо: «Обрабатывай ошибки». — Как именно? Try/catch? Result-тип? Логирование?

• Хорошо: «Ошибки в асинхронном коде — через Result<T, E> из @/lib/result; голый throw в бизнес-логике запрещён».

Второй антипаттерн — раздувать одно правило до полотна на весь проект. Длинное always-apply правило и токены съедает, и хуже соблюдается: чем больше инструкций в контексте, тем слабее модель держит каждую из них — известный эффект больших языковых моделей. Лучше пять коротких правил под разные зоны, чем один свод на несколько сотен строк.

Третий — противоречия между правилами, которые копятся незаметно. Каждый раз, добавляя новое правило, быстро проверьте, не спорит ли оно с уже существующим: агент при конфликте ведёт себя непредсказуемо.

Чек-лист миграции с .cursorrules на .mdc

Если у вас старый одиночный файл — вот безопасный путь на новый формат:

1. Аудит. Прочитайте свой .cursorrules и разбейте его на смысловые блоки: общий стиль, фронтенд, бэкенд, тесты.
2. Создайте базу. .cursor/rules/000-base.mdc с alwaysApply: true — сюда общие для всего проекта вещи (стек, язык, тон).
3. Разнесите по доменам. Отдельные .mdc под фронтенд (globs: ["**/*.tsx"]), бэкенд, тесты — каждый со своей маской.
4. Проверяйте на каждом шаге. После каждого файла задайте агенту простую задачу в этой зоне и посмотрите, следует ли он правилу.
5. Закоммитьте и удалите старый .cursorrules, когда убедитесь, что новые правила покрывают всё.

Неофициальный, но удобный приём: числовые префиксы в именах (00-base.mdc, 01-frontend.mdc) помогают держать порядок загрузки предсказуемым. В документации Cursor этого нет — это community-практика, но она встречается у нескольких авторов и не вредит.

Диагностика: правило не срабатывает

Если правило игнорируется, пройдите по списку — почти всегда причина здесь:

• Расширение. Файл точно .mdc, а не .md?
• Заголовок. YAML-frontmatter валиден? Опечатка в globs или alwaysApply — и правило молча не грузится.
• Маска. src/* и src/**/* — разные вещи; первая берёт только прямых потомков. Проверьте, что glob реально покрывает ваши файлы.
• Расположение. Файл в корневой .cursor/rules, а не в подпапке пакета монорепо (которая не сканируется)?
• Тип. Если стоит Apply Intelligently — вспомните, что он ненадёжен; для проверки временно переключите на Always Apply.
• Прямой вопрос. Спросите агента в чате: «Какие правила сейчас загружены?» — быстрый способ увидеть, видит ли он ваш файл вообще.

Коротко о главном

Правила Cursor — это память проекта для ИИ-агента, которая живёт в репозитории и работает у всей команды одинаково. Новый формат — папка .cursor/rules с .mdc-файлами; старый одиночный .cursorrules ещё работает, но пора мигрировать; AGENTS.md — простая альтернатива, особенно для монорепо. Держите правила короткими, коммитьте в git, ссылайтесь на файлы вместо копирования и помните про границы: правила — про агента, а не про автодополнение.

Хорошо настроенные правила не превращают ИИ в волшебника, но сильно поднимают планку: агент перестаёт угадывать ваш стиль и начинает писать так, как принято именно в вашем проекте. А если вы только осваиваетесь с самим подходом работы через ИИ-агента, начните с разбора, что такое вайб-кодинг и где у него границы.

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

.cursorrules ещё работает или уже нет? Работает — Cursor читает его ради обратной совместимости. Но формат признан устаревшим; для новых проектов используйте .cursor/rules/*.mdc.

Чем AGENTS.md отличается от .cursor/rules? Это markdown без YAML-заголовка и без типов правил — проще, но без условного подключения по маскам. Главный плюс: вложенные AGENTS.md работают в подпапках монорепо, где обычные .cursor/rules не сканируются.

Сколько правил можно держать? Технически сколько угодно, но каждое always-apply правило ест контекст. Держите файлы короткими (до 100–150 строк на практике, официальный потолок — 500) и не делайте всё «always».

Работают ли правила с автодополнением Cursor Tab? Нет. Правила применяются только в чате агента, не в Tab и не в Inline Edit (Cmd/Ctrl+K).

Почему моё правило игнорируется? Чаще всего причина в одном из пяти пунктов: файл не с расширением .mdc, битый YAML-заголовок, неверная маска glob, файл лежит в подпапке монорепо (которая не сканируется) или выбран тип Apply Intelligently, который срабатывает не всегда. Пройдите по чек-листу диагностики выше — он закрывает почти все случаи.