Файл .cursorrules і правила проєкту: як налаштувати Cursor під свій стек

Мовна модель нічого не пам’ятає між відповідями. Кожен новий запит вона читає з чистого аркуша: не знає, що у вас TypeScript, а не JavaScript, що ви робите відступ двома пробілами, що імпорти йдуть через аліаси, а компоненти лежать у src/components. І щоразу, коли ви цього не нагадали, ІІ-агент чесно вгадує — інколи повз.

Правила (rules) у Cursor — це спосіб перестати нагадувати те саме руками. Ви один раз описуєте, як влаштований ваш проєкт і як у ньому заведено писати код, а Cursor підкладає цей опис на початок кожного запиту до агента. Виходить постійна, багаторазова пам’ять проєкту, яка їде разом із репозиторієм і працює однаково у всієї команди.

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

Що таке правила і що вони реально роблять

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

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

Opus 5 коштує як Opus 4.8, а працює вдвічі дешевше за Fable — Anthropic продає не потужність, а економію токенів

Яку модель вмикати в Cursor під задачу: Composer, Grok, Claude і GPT

Agent Mode у Cursor на максимум: Plan Mode і прийоми професіоналів

Збираємо Telegram-бота в Cursor: від ідеї до деплою за один вечір

Робочий воркфлоу вайб-кодингу в Cursor, який доїжджає до продакшену

Як влаштований сам агентний чат — план до коду, чекпоінти для відкатів і що насправді контролює авто-запуск команд — розібрано в статті про Agent Mode на максимум.

Навіщо вони потрібні на практиці:

• Закодувати знання про проєкт — стек, архітектурні рішення, домовленості щодо імен. Те, що ви інакше пояснюєте кожному новому розробнику (і кожному новому чату).
• Стандартизувати стиль — щоб код від ІІ виглядав як ваш, а не як усереднений код з інтернету.
• Автоматизувати типові кроки — «після зміни схеми онови типи», «новий ендпоінт — одразу з тестом».

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

За пару років у Cursor змінилося кілька способів зберігати правила, і старі статті описують уже неактуальні формати. Ось повна картина на липень 2026.

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

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

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

Чотири типи правил — і плутанина в їхніх назвах

Ось місце, де помиляються майже всі. У правил проєкту є чотири типи поведінки — коли саме правило підключається. У 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, що спрацьовує не завжди. Пройдіть по чек-листу діагностики вище — він закриває майже всі випадки.