.cursorrules - это файл конфигурации, который задаёт правила работы Cursor в рамках вашего проекта: указывает используемый стек технологий, определяет стиль кода (форматирование, naming‑convention) и перечисляет запрещённые конструкции или библиотеки. Настраивая его, вы фиксируете единые стандарты для всей команды, а Cursor автоматически проверяет соответствие кода этим правилам и предупреждает о нарушениях. Таким образом, .cursorrules обеспечивает согласованность стека, стиля и ограничений без необходимости ручного контроля.
до про · Cursor
Что такое .cursorrules и где он живёт в проекте
.cursorrules - это специальный текстовый файл конфигурации, который выступает в роли глобального системного промпта для искусственного интеллекта в среде Cursor. Этот файл определяет поведение модели при генерации кода, ответах на вопросы и рефакторинге внутри конкретной рабочей области. Он позволяет переопределить стандартные настройки ИИ, заставляя модель учитывать специфику проекта, архитектурные решения и предпочтения команды разработки. По сути, это набор законов, которым нейросеть обязана следовать при любом взаимодействии с кодовой базой.
Физически файл располагается в корневой директории проекта. Это означает, что путь к нему выглядит как ./.cursorrules, где он находится рядом с ключевыми файлами конфигурации, такими как package.json, tsconfig.json или docker-compose.yml. Такое размещение гарантирует, что Cursor автоматически подхватит настройки при открытии папки проекта. Название, начинающееся с точки, делает файл скрытым в файловых менеджерах Linux и macOS, но в дереве проекта редактора он остается видимым для удобства редактирования.
Механика работы файла проста и эффективна. При каждом запросе пользователя к ИИ, будь то использование Cmd+K для генерации или Cmd+L для чата, содержимое .cursorrules незаметно внедряется в контекстное окно модели. Это происходит до того, как ИИ начнет обработку самого запроса. Благодаря этому модель получает исчерпывающую информацию о том, какой стек технологий используется, какие фреймворки предпочтительны, а какие категорически запрещены.
Внутри файла обычно описываются конкретные правила написания кода. Например, разработчик может указать, что для стилизации используется исключительно Tailwind CSS, а все компоненты должны быть функциональными. Также здесь прописываются запреты, предотвращающие появление плохого кода. Это может быть запрет на использование устаревших методов, требование избегать магических чисел или обязательное написание JSDoc комментариев для сложных функций. Наличие такого файла исключает необходимость постоянно напоминать ИИ о стандартах команды в каждом новом чате. Он превращает редактор в эксперта, который уже знаком с кодовой базой и готов выдавать результат, соответствующий высоким стандартам качества, без дополнительных правок со стороны человека.
Структура хорошего .cursorrules файла
Хороший .cursorrules файл должен быть структурирован так, чтобы обеспечить максимальную читаемость и поддерживаемость. Для этого следует соблюдать следующие правила:
- Файл должен быть разделен на логические секции, каждая из которых отвечает за определенный аспект настроек Cursor.
- Каждая секция должна начинаться с заголовка, который описывает ее содержимое.
- Внутри секций следует использовать четкую и последовательную структуру, чтобы описывать настройки.
- Все настройки должны быть сгруппированы по категориям, чтобы облегчить поиск и редактирование необходимых параметров.
Пример структуры .cursorrules файла:
# Секция настроек стиля кода
style:
indent_size: 4
indent_style: space
max_line_length: 120
# Секция настроек форматирования
format:
trim_trailing_whitespace: true
insert_final_newline: true
# Секция настроек запретов
restrictions:
disallowed_functions:
- console.log
- alert
disallowed_variables:
- global
# Секция настроек стека
stack:
max_depth: 10
max_width: 80
В этом примере файл разделен на четыре секции: стиль кода, форматирование, запреты и стек. Каждая секция содержит настройки, связанные с определенным аспектом работы Cursor. Такая структура позволяет легко найти и редактировать необходимые настройки.
При создании своего .cursorrules файла следует учитывать следующие рекомендации:
- Используйте четкие и описательные названия секций и настроек.
- Группируйте настройки по категориям, чтобы облегчить поиск и редактирование.
- Используйте последовательную структуру внутри секций, чтобы описывать настройки.
- Не забывайте комментировать настройки, чтобы облегчить понимание их назначения и значения.
Описание стека: версии, фреймворки, линтеры
Четкое определение технологического стека в .cursorrules является фундаментом для качественной генерации кода. Искусственный интеллект по умолчанию опирается на самые актуальные тренды и документацию, что часто приводит к конфликтам с устаревшими проектами или строгими корпоративными стандартами. Исключение неоднозначности на этом этапе экономит часы на последующий рефакторинг и исправление несовместимостей.
Начинайте с фиксации версий рантайма и ключевых зависимостей. Укажите конкретную версию Node.js, Python или Go, используемую в проекте. Если вы работаете с legacy-кодом на React 16, обязательно запретите использование хуков или фич из React 18. Для современных проектов на Next.js уточните, используется ли Pages Router или App Router, так как архитектура приложений кардинально различается. Это предотвратит генерацию кода, который просто не запустится в вашей среде из-за синтаксических ошибок или отсутствия API.
Детализируйте список фреймворков и библиотек. Перечислите разрешенные пакеты для решения конкретных задач. Для работы с формами укажите React Hook Form или Formik. Для HTTP-запросов зафиксируйте Axios или Fetch API. Если в проекте принят специфический UI-кит, например, Ant Design или Material UI, потребуйте использования компонентов именно из этой библиотеки, а не написания кастомных стилей с нуля. Это сохраняет визуальную и техническую консистентность продукта.
Отдельный блок уделите инструментам статического анализа и форматирования. Линтеры и форматеры отвечают за читаемость и соответствие кода стандартам команды. Пропишите использование ESLint, Stylelint или Pylint. Задайте конкретные правила: одинарные кавычки вместо двойных, отсутствие точек с запятой, отступы в два или четыре пробела, максимальная длина строки. Укажите, нужно ли ИИ автоматически исправлять ошибки линтера при генерации кода.
Пример конфигурации для .cursorrules:
Технический стек и окружение:
- Рантайм: Node.js v20 LTS
- Фреймворк: Next.js 14 (App Router)
- Язык: TypeScript 5.2 (строгая типизация, запрещен any)
- Стилизация: Tailwind CSS, модули CSS
- Тестирование: Vitest, Testing Library
- Форматирование: Prettier (ширина 100, одинарные кавычки, trailing commas)
- Линтинг: ESLint (правила Airbnb)
Такой подход превращает ИИ из генератора случайного кода в предсказуемого помощника, который четко понимает контекст и ограничения вашего проекта.
Соглашения кода: именование, форматирование, структура файлов
Используйте camelCase для именования переменных, функций и методов. Имена должны быть семантическими и явно описывать назначение без излишней абстракции. Запрещаются однобуквенное переменные, кроме счетчиков в циклах. Булевы переменные начинайте с префиксов is, has, should, can (например, isLoading, hasAccess). Для классов, интерфейсов, типов и React-компонентов применяйте PascalCase. Константы уровня модуля или конфигурации пишите в UPPER_SNAKE_CASE. Частные свойства классов отмечайте префиксом _ или используйте синтаксис приватных полей.
Форматирование кода должно строго соответствовать настройкам линтера. Используйте 2 пробела для отступов. Максимальная длина строки ограничена 100 символами. Всегда ставьте точку с запятой в конце выражений. Строковые литералы заключайте в одинарные кавычки. В многострочных объектах и массивах ставьте запятую после последнего элемента. Операторы и запятые отделяйте пробелами. Импорты разделяйте на три блока: сторонние библиотеки, модули текущего проекта, относительные импорты. Между блоками оставляйте одну пустую строку. Сортировка импортов внутри блока производится по алфавиту. Не оставляйте неиспользуемые импорты и переменные. Группируйте связанные функции внутри файла пустыми строками, отделяя логические секции кода.
Организация файловой структуры строится по принципу функциональных модулей. Избегайте группировки файлов исключительно по типу. Создавайте папки по функциональным областям, например, auth, checkout, user-profile. Внутри модуля располагайте компоненты, хуки, сервисы, типы и стили рядом. Это обеспечивает высокую связность внутри модуля. Используйте файлы index.ts для реэкспорта публичного API модуля, что скрывает детали реализации и упрощает пути импорта. Имена файлов используйте в kebab-case (например, user-service.ts). Если файл содержит одну главную сущность, называйте файл в соответствии с ней. Абстракции общего назначения выносите в директорию shared или core. Строго следите за отсутствием циклических зависимостей. Путь к файлу должен отражать его иерархию в архитектуре приложения. Избегайте глубокого вложения директорий, желательно держать глубину не более 4 уровней.
Запреты: что Cursor не должен менять без спроса
Четко определите границы, за которые ИИ не имеет права заходить без явного подтверждения. Это сохранит целостность проекта и предотвратит критические ошибки. Первым делом заблокируйте доступ к конфиденциальным данным и настройкам окружения. В .cursorrules пропишите жесткое правило: никогда не модифицировать файлы .env, .env.local, .env.production и файлы с секретами. ИИ не должен добавлять новые переменные или менять значения существующих. Если код требует новую константу, помощник должен оставить комментарий с подсказкой, но не трогать сам файл. Это база безопасности.
Второй важный запрет касается зависимостей. Ограничьте автоматические правки в package.json, requirements.txt, go.mod и composer.json. Cursor не должен самостоятельно обновлять версии библиотек или добавлять новые пакеты. Такие действия часто ломают сборку или вносят несовместимости. Пусть ИИ предлагает команду для установки в терминале, но не правит манифест проекта. Это же касается файлов блокировок вроде package-lock.json или yarn.lock - их трогать строго запрещено, так как это ломает хеширование зависимостей.
Защитите инфраструктурный код. Запретите изменения в Dockerfile, docker-compose.yml и конфигурациях CI/CD пайплайнов без прямого указания. Ошибка в этих файлах может остановить деплой на всех окружениях. Также строжайше запретите ИИ создавать или изменять миграции базы данных. Самовольное изменение структуры таблиц, типов колонок или связей чревато потерей данных и конфликтами. Если правка требует изменения БД, ИИ должен описать SQL-запрос в отдельном блоке, но не генерировать файл миграции.
Отдельно оговорите работу с тестами. Cursor не должен переписывать тесты только ради того, чтобы они проходили после изменения кода. Это маскирует реальные ошибки. Тесты меняются только при явном запросе на рефакторинг тестовой логики. Также запретите глобальное переформатирование файлов. Если вы просите исправить опечатку в функции, ИИ не должен перестраивать весь файл под свой стиль кода или менять импорты в других модулях. Это создает бесполезный шум в git-истории. Наконец, запретите удаление или изменение комментариев, содержащих технический долг или важные контекстные пометки. ИИ часто считает их "мусором", но для команды это ценная информация.
Документация в .cursorrules: ссылки и описание архитектуры
Для эффективной работы ИИ необходимо предоставить контекст внешних ресурсов. В .cursorrules добавляйте прямые ссылки на актуальную документацию. Это включает спецификации API (Swagger/OpenAPI), внутренние базы знаний (Confluence, Notion) и официальные руководства используемых библиотек с указанием конкретных версий. ИИ не обладает встроенным знанием о специфике вашего проекта, поэтому ссылки служат якорями для достоверной информации, предотвращая использование устаревших методов или deprecated функций.
Форматируйте ссылки четко и сопровождайте их инструкциями по использованию. Не просто перечисляйте URL, а объясняйте, когда именно их применять. Пример: "При работе с модулем платежей всегда сверяйся с актуальной схемой базы данных по ссылке [URL]" или "Для стилизации компонентов используй гайдлайн по ссылке [URL], игнорируя дефолтные примеры библиотеки". Это снижает риск галлюцинаций и гарантирует соответствие актуальным стандартам проекта.
Описание архитектуры должно быть лаконичным, но емким. Опишите глобальную структуру приложения: монолит, микросервисы или модульный монолит. Укажите ключевые директории и их назначение. Например: "Папка /src/core содержит бизнес-логику, /src/infrastructure - работу с внешними сервисами, /src/api - контроллеры". Это помогает ИИ правильно маршрутизировать новые файлы и понимать зависимости модулей, избегая циклических импортов.
Важно прописать паттерны взаимодействия и поток данных. Если используется Event Sourcing, CQRS или специфичная слоистая архитектура, укажите это явно. Опишите маршрутизацию: "Запрос поступает в API Gateway, проходит валидацию в middleware, обрабатывается в Service слое, сохраняется в PostgreSQL, кэш - Redis". ИИ должен знать эти маршруты, чтобы предлагать корректные решения и не нарушать изоляцию слоев.
Отдельно выделите статус legacy-кода. Если проект содержит старые модули, которые нельзя рефакторить, укажите это: "Модуль /legacy не подлежит изменению, новые функции пишем только в /src/v2". Это предотвратит попытки ИИ "починить" стабильные, но устаревшие системы.
Добавьте жесткое правило обращения к документации перед началом работы. Строка "Перед написанием кода для новой фичи изучи раздел архитектуры в Notion по ссылке [URL]" превращает .cursorrules в навигационный центр. Не перегружайте текст деталями реализации низкого уровня, сосредоточьтесь на принципах, связях и контрактах. Четкая архитектура в правилах экономит время на исправление структурных ошибок и позволяет ИИ генерировать код, который сразу встраивается в существующую систему без необходимости глобального рефакторинга.
Отдельные .cursorrules для разных модулей монорепо
Монорепозитории часто объединяют разнородные технологии: Next.js на фронтенде, Go на бэкенде и Python в скриптах аналитики. Единый файл .cursorrules в корне проекта заставляет ИИ путаться, предлагая React-компоненты для Go-сервиса или SQL-запросы внутри Python-скриптов. Решение заключается в создании отдельных файлов конфигурации внутри каждого модуля. Это использует механизм приоритета контекста Cursor: ИИ считывает правила, находящиеся ближе всего к редактируемому файлу.
Разместите файл .cursorrules в корневой директории каждого сервиса или пакета. При редактировании файла в apps/backend/src/main.go Cursor сначала применит инструкции из apps/backend/.cursorrules. Если там не найдено конкретных указаний, система обратится к глобальному файлу в корне репозитория. Это позволяет создавать гибкую иерархию правил без конфликтов.
В локальных файлах концентрируйтесь на специфике стека. Для модуля apps/frontend пропишите обязательное использование Tailwind CSS вместо CSS-модулей, именование компонентов в PascalCase и хуки вместо классов. Для apps/backend укажите фреймворк, ORM
Шаблоны .cursorrules для Python/FastAPI, Next.js, Go
Для стека Python/FastAPI настройте фокус на асинхронности и безопасности типов. Используйте следующий набор правил: "Используй FastAPI. Все обработчики маршрутов должны быть асинхронными (async def). Применяй Pydantic v2 для валидации данных и сериализации. Обязательна аннотация типов для всех аргументов и возвращаемых значений. Структурируй проект по слоям: routers, services, models, schemas. Используй dependency injection для получения сессий базы данных. Запрещены глобальные переменные с состоянием. Для форматирования используй Black и Ruff. Не используй синхронные драйверы БД внутри асинхронных функций. Логирование должно быть структурированным, например, через structlog. Миграции базы данных выполняй через Alembic. Тесты пиши на pytest с микстурами."
Для Next.js (App Router) акцентируйте внимание на производительности и TypeScript: "Используй Next.js 14+ с App Router. Все компоненты по умолчанию должны быть Server Components. Используйте Client Components ('use client') только при необходимости интерактивности (onClick, useState). Строгий режим TypeScript: запрещено использование типа 'any'. Для стилизации применяй Tailwind CSS и библиотеку shadcn/ui. Получение данных выполняй через Server Actions или напрямую в Server Components. Запрещено использование useEffect для первичной загрузки данных. Используй path aliases (@/components) для импортов. API-роуты должны обрабатывать ошибки и возвращать JSON в едином формате. Оптимизируй изображения через next/image и шрифты через next/font."
Для Go установите стандарты чистой архитектуры и обработки ошибок: "Используй Go 1.21+. Обрабатывай ошибки сразу после их возникновения, не игнорируй их. Используй context.Context в первом аргументе всех функций, работающих с сетью или БД. Структурируй код по пакетам: cmd, internal, pkg. Используй интерфейсы для зависимостей. Для JSON-API применяй структурные теги (json:'field_name'). Форматирование кода обязательно через gofmt. Избегайте глубокой вложенности кода (guard clauses). Запрещено паниковать (panic) в бизнес-логике, возвращайте error вместо этого. Используйте стандартную библиотеку логирования (slog). Тесты должны быть написаны в table-driven стиле. Избегайте пакетных переменных, хранящих состояние."
Частые вопросы
.cursorrules это глобальный файл или per-project?
.cursorrules - это файл, который хранится в корне конкретного репозитория, поэтому его настройки действуют только для данного проекта. Если файл разместить в домашней папке, он будет применяться глобально, но по умолчанию Cursor ищет его именно в проекте.
Cursor загружает .cursorrules автоматически?
Cursor не читает .cursorrules сам по себе; файл нужно добавить в корень проекта и включить в настройках → «Project → Cursor Rules». После этого правила применяются автоматически при открытии файлов.
Есть ли лимит на размер .cursorrules?
Лимита на размер файла .cursorrules нет