Cursor Rules: як навчити AI працювати з вашим проєктом

💡 Усі статті, обговорення, новини про AI — в одному місці. Приєднуйтесь до AI спільноти!

Мене звати Владислав, я працюю Senior Software Engineer у MEV. Мій професійний шлях охоплює проєкти у сферах охорони здоров’я, безпеки та розробки веб і мобільних систем, де я відповідав за архітектуру, інтеграцію сервісів, оптимізацію продуктивності та створення масштабованих рішень.

Вже близько 2 років активно працюю з AI-інструментами. Використовую їх переважно для особистої продуктивності: прискорення написання коду, аналізу даних, створення технічної документації та дослідження нових технологій. Основні AI-assistant інструменти, з якими працюю, — Claude Code, Codex та Cursor. І в цій статті хочу детальніше розповісти про останній.

Cursor для багатьох досі виглядає як розумний автокомпліт: ти щось питаєш — він щось генерує. Але лише тоді, коли AI справді розуміє структуру твого проєкту — де лежить бізнес-логіка, як називаються змінні, який код краще не чіпати — він починає давати реальну користь. Без цього кожна нова сесія перетворюється на дежавю: знову пояснювати ті самі речі та виправляти ті самі помилки.

Cursor Rules якраз і створені для того, щоб цього уникнути. Це спосіб один раз онбордити Cursor у свій репозиторій, а не «наймати» його заново щодня. Ви закладаєте в правила архітектурні рішення, стилі, конвенції та робочі процеси — і далі модель спирається на них, коли дописує код, редагує файли чи виконує типові задачі.

У цій статті розбираємося, як працюють Cursor Rules, які існують типи правил (Project, User, Team, AGENTS.md), як вони взаємодіють між собою та з .cursorignore, і як побудувати систему правил для реального проєкту. Мета проста: перетворити Cursor з універсального, але забудькуватого асистента на передбачуваного члена команди, який пам’ятає ваші стандарти й допомагає підтримувати порядок у кодовій базі.

Чому важливі Cursor Rules

Cursor Rules — це постійні інструкції, які допомагають AI-асистенту зрозуміти саме ваш проєкт. Вони навчають модель вашої структури коду, стилю та підходу до роботи, щоб вона поводилася як досвідчений колега, а не починала щоразу з нуля.

Без правил вам доводиться повторювати одні й ті самі пояснення та щоразу виправляти однакові помилки. З правилами AI пам’ятає ваші стандарти, підтримує єдиний стиль коду, виконує команди та автоматизує рутинні задачі.

Найкраще налаштовувати Rules на старті нового проєкту. Так усе, що створюватиме AI, одразу відповідатиме вашим стандартам — це заощадить час і зусилля в майбутньому.

Примітка: ця ідея не унікальна для Cursor. Подібні можливості мають Claude Code, Codex, GitHub Copilot та інші AI-інструменти для розробки. Це швидко стає стандартним способом взаємодії з AI-асистентами. Тож варто опанувати підхід не лише для Cursor, а й для будь-якого інструмента цього типу.

Cursor Rules — це системні інструкції, що застосовуються до Agent і Inline Edit (але не до Cursor Tab). Вони зберігають контекст, уподобання та робочі процеси для вашого проєкту.

Великі мовні моделі не зберігають пам’ять між окремими виконаннями. Rules дають їм постійний і багаторазовий контекст на рівні промпту.

Коли правило застосовано, його зміст додається на початок контексту моделі. Це дає AI чіткі орієнтири для написання коду, інтерпретації правок і підтримки робочих процесів.

Типи правил

Cursor підтримує 4 типи правил:

1. Project Rules — зберігаються в .cursor/rules, належать до конкретного проєкту, версіонуються та застосовуються лише до поточної кодової бази.
2. User Rules — звичайний текст, глобальні для вашого середовища Cursor, застосовуються скрізь. Визначаються у налаштуваннях і завжди активні.
3. Team Rules — правила на рівні команди, керуються з панелі керування. Доступні у планах Team та Enterprise.
4. AGENTS.md — інструкції для агентів у форматі Markdown. Простий альтернативний спосіб до .cursor/rules.

Примітка: єдиний файл .cursorrules (legacy) у корені проєкту був початковим підходом Cursor. Він все ще підтримується, але його буде прибрано в майбутньому. Команда Cursor рекомендує мігрувати на Project Rules або на AGENTS.md.

Правила для проєкту (Project Rules)

Правила проєкту зберігаються в директорії .cursor/rules і слугують інструкціями, які навчають AI-модель працювати саме з вашим проєктом. Кожне правило — це окремий файл, який версіонується разом із вашим кодом.

Правила можуть бути

• Локальними — застосовуватися лише до певних файлів за заданими шляхами.
• Викликаними вручну — коли потрібна специфічна інструкція.
• Автоматично підключеними — коли вони релевантні поточній задачі.
• Постійними — завжди активними у всьому проєкті.

Підкаталоги також можуть мати власну директорію .cursor/rules, і правила в ній автоматично застосовуватимуться до цього каталогу та його вмісту.

Навіщо використовувати Project Rules

• Передати моделі специфічні знання про вашу кодову базу (архітектурні рішення, стилістика тощо).
• Автоматизувати робочі процеси чи патерни, притаманні проєкту.
• Уніфікувати стиль, архітектуру чи конвенції у межах проєкту.

Як створити Project Rules

Варіант 1. Через налаштування Cursor

Перейдіть до Settings → Rules, і додайте потрібні правила:

Варіант 2. Ручне створення

Створіть директорію у корені вашого проєкту:

mkdir –p .cursor/rules

Цю директорію варто закомітити в Git, щоб усі члени команди мали однакові правила.

Варіант 3. Через Command Palette

• Відкрийте Command Palette: Cmd + Shift + P (Mac) або Ctrl + Shift + P (Windows/Linux).
• Введіть і виберіть «New Cursor Rule».
• Cursor створить шаблон .mdc-файлу, де ви можете визначити description, globs, alwaysApply та інструкції.

Варіант 4. Попросити AI

Можете просто написати агенту в чаті, щоб він створив для вас нове правило.

Детально про Project Rules: формат MDC

Формат Metadata Content (MDC) використовує структуру з двох частин: спершу блок YAML frontmatter для метаданих конфігурації, а потім стандартну секцію Markdown для детальних інструкцій та прикладів.

–––
description:
globs: [Array of file path patterns]
alwaysApply: [boolean:true/false]
–––
# Detailed Instructions and Code Snippets (Markdown Content)

Frontmatter у MDC керує тим, як правила підтягуються в контекст моделі й коли вони активуються.

Ключові властивості:

• description: обов’язковий короткий, прикладний опис змісту правила. Для певних типів правил AI-агент спочатку дивиться саме на description, щоб вирішити, чи це правило релевантне, перш ніж запитувати повний контент. Це економить контекст і час обробки.
• globs: шаблони шляхів до файлів (наприклад, src/**/*.ts). Якщо активний файл збігається з одним із цих шаблонів, правило підтягується в контекст.
• alwaysApply: якщо true, правило додається в контекст моделі незалежно від активного файлу чи запиту користувача.

Важливо: Надто довгі правила (наприклад, більше ~500 рядків) або занадто багато правил з alwaysApply: true можуть «перевантажити» модель. Для великих наборів інструкцій краще використовувати точково налаштовані правила типу Apply Intelligently або Apply Manually, а не суцільні Always Apply.

Типи правил MDC і логіка їх активації

Always Apply — правило завжди включається в контекст моделі; автоматично доступне у всіх чатах.

Apply Intelligently — AI автоматично вирішує, чи включати правило, базуючись на description правила та наміру користувача.

Apply to Specific Files — правило включається до контексту, коли активний файл відповідає шаблону з поля globs (наприклад, frontend/**/*.tsx).

Apply Manually — правило активується лише тоді, коли його явно згадують у чаті через @ruleName.

Створення комплексної системи правил

Щоб побудувати ефективну систему правил, варто підходити стратегічно та організовано. Ось рекомендований порядок:

1. Створіть файл правил на рівні всього проєкту, який охоплює основні принципи, що застосовуються у всіх випадках — форматування коду, стиль коментарів, правила іменування та організацію імпортів.
2. Додайте правила для конкретного фреймворку з використанням globs, щоб вони застосовувалися автоматично саме до відповідних файлів. Наприклад: файл react–components.mdc з globs: src/components/**/*.tsx гарантує, що правила для React—компонентів застосовуються лише коли ми працюємо з компонентами.
3. Додайте домен—специфічні правила для різних частин вашого застосунку — наприклад: api–patterns.mdc для бекенду, database–queries.mdc для роботи з базою даних, ui–accessibility.mdc для інтерфейсу та доступності.
4. Включіть правила для тестування у спеціалізованому файлі, щоб забезпечити послідовну структуру тестів, іменування і вимоги до покриття.

Нижче — набір прикладів Project Rules, який може надихнути на власні експерименти:

project/
├── .cursor/
│   └── rules/
│       ├── general–standards.mdc      # Always applied fundamentals
│       ├── typescript–conventions.mdc # TypeScript–specific rules
│       ├── git–workflow.mdc           # Commit and PR conventions
│       ├── backend/
│       │   ├── api–design.mdc         # RESTful API patterns
│       │   ├── authentication.mdc     # Auth implementation rules
│       │   └── database.mdc           # Database query standards
│       └── frontend/
│           ├── react–components.mdc   # React component structure
│           ├── styling.mdc            # CSS/Tailwind guidelines
│           └── accessibility.mdc      # A11y requirements

Для великих застосунків або монорепозиторіїв організуйте правила ієрархічно. Розміщуйте директорії .cursor/rules всередині піддиректорій (наприклад, backend/), щоб автоматично обмежити правила певному піддереву та уникнути конфліктів між різними технологічними стек­ами.

project/
├─.cursor/rules/          # Global project rules
│  ├─ naming.mdc
│  └─ architecture–overview.mdc
├─ backend/
│  ├─.cursor/rules/       # Backend–scoped rules
│  │  └─ rpc–template.mdc
│  └─ server.py
└─ frontend/
   ├─.cursor/rules/       # Frontend–scoped rules
   │  └─ component–style.mdc
   └─ app.tsx

Правила користувача (User Rules)

Правила користувача — це глобальні уподобання, які задаються в Settings → Rules у Cursor і застосовуються до всіх проєктів. Це звичайний текст, тож вони ідеально підходять для налаштування стилю спілкування або код-конвенцій, яких ви хочете дотримуватися.

Так можна додати User Rules у Cursor:

Приклади User Rules

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

Правила команди (Team Rules)

Для тарифів Cursor на рівні команди чи компанії є можливість керувати спільними правилами через дашборд Cursor (налаштування в хмарі).

Team Rules поширюються на всю організацію — усі члени команди отримують єдиний базовий набір правил, який застосовується за замовчуванням.

Це зручно, коли потрібно підтримувати стандарти на рівні організації, наприклад: вимоги безпеки чи формат коміт-меседжів — доповнюючи правилами конкретного проєкту.
Такі правила налаштовуються власниками або адміністраторами команди й автоматично розповсюджуються серед усіх користувачів.

Докладніше про Team Rules можна прочитати в офіційній документації: https://cursor.com/docs/context/rules#team—rules

Файл AGENTS.md

AGENTS.md — це простий Markdown-файл для опису інструкцій агентам. Його кладуть у корінь проєкту як альтернативу .cursor/rules у простих сценаріях.

Якщо Project Rules використовують формат MDC для точного й гнучкого налаштування, то AGENTS.md — це звичайний Markdown без метаданих чи складної конфігурації. Він не має frontmatter-частини, тож не підтримує globs або alwaysApply для вибіркового застосування правил.

# Project Instructions

## Code Style
– Use TypeScript for all new files
– Prefer functional components in React
– Use snake_case for database columns

## Architecture
– Follow the repository pattern
– Keep business logic in service layers

## Package Management
– Use pnpm for package management (not npm or yarn)
– Always use and install the latest versions of all dependencies

**Important:**  
– Do **not** manually add packages to `package.json` with hardcoded or random versions
– Always use package manager commands to ensure consistent and up–to–date dependency versions

## Documentation
Always refer to the latest documentation when working with dependencies:
– Use **context7 MCP** to check the most up–to–date documentation
– Since we use the latest versions of all dependencies, official documentation is the source of truth

## UI Components (shadcn/ui)
– Always use the CLI to install shadcn/ui components
– Do **not** manually copy component code or add components to the codebase

You can also use @filename.ts to include files in your rule's context.

Це правило застосовується до директорії або піддиректорії, у якій файл розміщено. Для великих застосунків або монорепозиторіїв, які потребують тонкого налаштування — наприклад, щоб стандарти для React-компонентів застосовувалися лише до директорії frontend/, а правила для Django — лише для backend/ — формат MDC пропонує більшу гнучкість. Це — рекомендований вибір для складної конфігурації.

Підтримка вкладених AGENTS.md

Файли AGENTS.md можна розміщувати в будь-якій піддиректорії вашого проєкту, і вони автоматично застосовуватимуться, коли працюєте з файлами в цій директорії та всередині її дочірніх папок.

Це дозволяє отримати більш детальний контроль над інструкціями агента, залежно від того, над якою частиною кодової бази ви зараз працюєте.

project/
  AGENTS.md              # Global instructions
  frontend/
    AGENTS.md            # Frontend–specific instructions
    components/
      AGENTS.md          # Component–specific instructions
  backend/
    AGENTS.md            # Backend–specific instructions

Інструкції з вкладених файлів AGENTS.md об’єднуються з інструкціями з батьківських директорій, причому більш конкретні правила мають вищий пріоритет.

Пріоритет між AGENTS.md та .cursor/rules

Немає офіційної документації, яка б прямо пояснювала, який з цих файлів має вищий пріоритет у разі конфлікту між .cursor/rules і AGENTS.md. Із наявної інформації можна зробити висновок, що вони задумувалися як взаємодоповнювальні, а не такі, що суперечать одне одному.

Оскільки обидва файли підвантажуються одночасно, варто уникати конфліктів, використовуючи їх для різних завдань:

• AGENTS.md — для загальних інструкцій проєкту, команд налаштування та високорівневих рекомендацій.
• .cursor/rules/*.mdc — для конкретних, вузько спрямованих правил, які застосовуються до певних файлів або контекстів.

Пріоритет правил і обробка конфліктів

Якщо різні типи правил суперечать одне одному, Cursor застосовує їх у такому порядку:

Team Rules → Project Rules → User Rules

Ця ієрархія гарантує, що стандарти організації мають вищий пріоритет, ніж особисті налаштування.

• Team Rules — визначають обов’язкові вимоги (безпека, відповідність стандартам, архітектура) на рівні всієї організації.
• Project Rules — керують деталями реалізації, специфічними для конкретного репозиторію.
• User Rules — особисті вподобання інженера, які не мають порушувати командні та проєктні стандарти.

.cursorignore

Файл .cursorignore у корені проєкту дозволяє приховати певні файли або папки від Cursor. Усе, що додано в цей файл, буде виключено з індексації, автодоповнення (Tab completions), дій Agent та Inline Edit, а також із посилань через @.

Навіщо ігнорувати файли

• Безпека: обмежте доступ до API—ключів, облікових даних і секретів. Хоча Cursor блокує такі файли, повної гарантії безпеки немає — моделі залишаються непередбачуваними.
• Продуктивність: у великих кодових базах або монорепозиторіях виключайте непотрібні частини, щоб прискорити індексацію та покращити пошук файлів.

Cursor автоматично ігнорує все з .gitignore і власного дефолтного списку.
До типових шаблонів ігнорування входять:

• Файли середовища: */.env, */.env.*
• Облікові дані: */credentials.json, */secrets.json
• Ключі: */*.key, */*.pem, */id_rsa

Докладніше про це можна прочитати тут: https://cursor.com/docs/context/ignore—files

Навіщо використовувати правила навіть для великих кодових баз

Може виникнути логічне питання:

Якщо в нас уже є велика кодова база і ми починаємо користуватися Cursor, чи взагалі потрібні Cursor Rules? Хіба ШІ сам не «зчитує» стиль і архітектуру проєкту з наявного коду?

Коли Cursor індексує велику кодову базу, він добре справляється з:

• пошуком файлів і символів;
• виявленням патернів (наприклад, «ми використовуємо services + DTOs + controllers»);
• генерацією коду, схожого на наявний.

Але це імітація, а не розуміння. Модель може копіювати стиль, але не знає, які з патернів є обовʼязковими, а які — просто історичні помилки, що колись потрапили в код.

Що AI не здатен зрозуміти просто з коду

Поточні архітектурні рішення. У коді можуть одночасно жити старі й нові підходи. Модель не знає: «ми вже мігрували на V2-сервіси — V1 більше не використовуємо».

Командні домовленості, яких не видно в коді. На кшталт: «усі network-помилки проходять через цей helper», «ніколи не повертаємо сирі DB-моделі з хендлерів» або «логування для аудиту робимо ось так». Такі речі часто живуть у головах людей або в Confluence, а не в коді.

Пріоритети задач і контексту. З коду не видно: «зараз ми сфокусовані на BLE-продуктивності в мобільному застосунку, тому не пропонуй важке логування».

Погані приклади в репозиторії. У кожному реальному проєкті з великою кодовою базою є «давній» код: старі патерни, експериментальні папки, швидкі хотфікси. Модель теж може їх копіювати, бо не розуміє, які шматки — це «так більше не робимо».

Тому велика кодова база ≠ AI реально розуміє правила проєкту.

Як діяти для великих кодових баз

У великій кодовій базі вам не потрібен rules-файл на 1500 рядків. Корисніше додати тонкий шар правил, який підказує Cursor:

• які патерни є канонічними;
• які частини кодової бази — легасі;
• які файли варто використовувати в першу чергу;
• які інструменти/команди запускати;
• яких підходів уникати.

Правила «приземляють» модель у поточну епоху вашого проєкту. Кодова база зберігає минуле; Cursor Rules пояснюють AI, як працювати «тут і зараз»

Рекомендовані кроки

1. Тримайте правила сфокусованими й мінімальними. Почніть із простих формулювань, які уточнюють архітектурні рішення: «віддавай перевагу X замість Y», «ця папка — легасі, не перевикористовуй її».

2. Використовуйте правила, щоб вирівняти ШІ з поточною архітектурою та робочим процесом.

3. Використовуйте правила, щоб не допустити відкату до старих патернів.

Правила допомагають AI розуміти ваш проєкт так само як це роблять розробники: через розуміння того, що важливо сьогодні, а не що було пʼять років тому.

Рекомендовані практики

• Починайте з простого. Короткі та чіткі інструкції працюють краще.
• Уникайте розмитих формулювань. 150–300 рядків конкретних правил ефективніші за 1500 рядків туманного тексту.
  Пишіть «запусти pnpm test перед комітом», а не «тести мають бути запущені».
  
• Спершу правила, потім код. Це забезпечить єдині стандарти з першого дня.
• Оновлюйте правила. Коли змінюються API чи фреймворки — оновлюйте й правила.
• Виділяйте важливе. Використовуйте маркери «IMPORTANT» або «YOU MUST».
• Тримайте обсяг під контролем. До 500 рядків на файл.
  Забагато alwaysApply: true — перевантажують модель.
  
• Діліть правила на модулі. Наприклад:
  react-standards.mdc, api-validation.mdc, testing-patterns.mdc.
  
• Додавайте реальні приклади. Використовуйте @filename, щоб вказати на конкретний код — приклади діють краще, ніж пояснення.
• Використовуйте вкладені правила. .cursor/rules або AGENTS.md у піддиректоріях застосовуються лише до файлів у цих папках.
• Комітьте правила. Якщо правила не в репозиторії, у кожного в команді AI поводитиметься по-різному.
• Використовуйте LLM для покращення правил. Використовуйте іншу LLM або Cursor Agent, щоб створити першу версію правил або відшліфувати існуючі.

Висновок

Cursor Rules допомагають перетворити універсальну модель на більш передбачуваного асистента саме для вашої кодової бази. Вони дають їй контекст, який зазвичай губиться: як влаштований проєкт, як ви пишете код і які робочі процеси важливі. Це означає менше повторних пояснень, менше однакових помилок і більш стабільний результат.

• Project Rules (.cursor/rules) — стандарти й робочі процеси конкретного репозиторію.
• User Rules — особисті стилістичні вподобання, що діють усюди.
• Team Rules — правила на рівні команди.
• AGENTS.md — швидкий, мінімальний варіант для загальних інструкцій.

Тримайте правила короткими, прямими, створюйте їх до початку роботи й оновлюйте разом із розвитком проєкту. Діліть великі файли на менші, додавайте приклади й уникайте розмитості. Так модель завжди буде отримувати правильні орієнтири — і команда зможе працювати узгоджено, без зайвих зусиль.

Правила (Rules) — не унікальна функція Cursor. Вони стають стандартом для інструментів AI-розробки. Навчіть AI розуміти ваш проєкт один раз — і заощадите сотні годин на повторюванні пояснень.

Корисні джерела:

• Cursor Rules (офіційна документація)
• Матеріали про AGENTS.md як README для агентів

Рекомендую розглядати ці приклади як натхнення — перегляньте їх і підлаштуйте під свої задачі:

• хаб, де публікують правила
• велика GitHub-збірка правил для різних стеків і фреймворків
• ще одна добірка шаблонів і модульних правил у стилі MDC

Сподобалась стаття? Підписуйтесь на автора, щоб отримувати сповіщення про нові публікації на пошту.