Правила Cursor: як писати файли .cursor/rules, які дійсно працюють

Правила Cursor: як писати файли .cursor/rules, які дійсно працюють

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

Що таке правила Cursor і чому вони важливі?

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

Старий підхід полягав у використанні єдиного файлу .cursorrules у корені проєкту. Він досі працює, але вважається застарілим. Поточна система використовує директорію .cursor/rules/ з окремими файлами .mdc (Markdown Cursor), кожен з яких прив’язаний до конкретних ситуацій. Це набагато краща настройка, оскільки ви не намагаєтеся вмістити всі інструкції в один величезний файл, а розділяєте правила за сферами відповідальності, і Cursor завантажує лише ті, що релевантні поточному завданню.

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

Налаштування вашого першого файлу правил

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

mkdir -p .cursor/rules

Кожне правило — це файл .mdc, який містить YAML frontmatter, за яким слідує контент у форматі markdown. Ось його скелет:

---
description: "When this rule should apply"
globs: ["src/components/**/*.tsx"]
alwaysApply: false
---

Your instructions go here in plain markdown.

Три поля frontmatter керують усім процесом:

Ви також можете створювати правила безпосередньо через Cursor: введіть /create-rule у чаті та опишіть, що вам потрібно. Але ручне написання дає більше контролю.

Пояснення чотирьох типів правил

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

Завжди застосовувати (Always Apply)

---
alwaysApply: true
---

Завантажується в кожен запит до ШІ. Використовуйте це обережно, для фундаментальних налаштувань проєкту, таких як оголошення технологічного стеку або критичні угоди, що діють всюди. Кожне правило, що завжди активне, витрачає токени з кожної взаємодії, незалежно від того, чи воно релевантне.

Автоматичне прикріплення (на основі Glob)

---
globs: ["src/api/**/*.ts", "src/routes/**/*.ts"]
alwaysApply: false
---

Активується лише тоді, коли ви редагуєте файли, які відповідають шаблонам glob. Це основний тип правил. Ваші угоди щодо компонентів React завантажуються, коли ви працюєте з файлами компонентів, патерни API — коли ви в обробниках маршрутів, а правила тестування — коли ви пишете тести.

Запит агента (Інтелектуальне)

---
description: "Database migration patterns using Drizzle ORM"
alwaysApply: false
---

Немає ні glob-шаблонів, ні прапорця always-apply, лише опис. Агент Cursor читає опис і вирішує, чи релевантне правило до поточного завдання. Якщо ви попросите його написати міграцію, він використає це правило. Якщо ви стилізуєте кнопку, він його пропустить. Це дивно добре працює для правил, які не мають чіткої прив’язки до шляхів файлів.

Ручне (Manual)

---
---

Поля frontmatter не встановлені (або порожні). Такі правила активуються лише тоді, коли ви явно згадуєте їх через @rule-name у чаті. Добре підходять для рідко використовуваних, але важливих інструкцій, таких як чеклисти деплою або гайди з рефакторингу, які потрібні лише час від часу.

Шаблони Glob, які дійсно працюють

Globs визначають, які файли запускають правила з автоматичним прикріпленням. Якщо зробити їх неправильно, правила або ніколи не спрацьовують, або спрацьовують всюди. Ось що працює:

# All TypeScript files in src
globs: ["src/**/*.ts", "src/**/*.tsx"]

# Only component files
globs: ["**/components/**/*.tsx"]

# Python files, excluding tests
globs: ["**/*.py", "!**/test_*.py"]

# Multiple specific directories
globs: ["src/api/**", "src/services/**"]

Кілька підводних каменів із реального досвіду:

• src/* відповідає лише одному рівню директорій. Вам майже завжди потрібно src/**/* для рекурсивного пошуку.
• *.js не знайде файли .jsx або .ts. Чітко вказуйте розширення.
• Globs мають бути списком YAML. Синтаксис фігурних дужок, як-от {src,lib}/**/*.ts, може тихо не спрацювати, тому краще використовувати окремі елементи списку.
• Префікс ! виключає шаблони, що корисно для ігнорування згенерованих файлів або застарілого коду.

Практичні приклади правил

Саме тут теорія зустрічається з реальністю. Це правила, які можна додати в проєкт і миттєво побачити покращення результатів ШІ.

Базове правило для всього проєкту (Always Apply)

---
alwaysApply: true
---

# Project: Acme Dashboard

## Tech Stack
- Next.js 15 (App Router only — no Pages Router)
- TypeScript strict mode
- Tailwind CSS v4
- Drizzle ORM with PostgreSQL
- pnpm for package management

## Critical Conventions
- All components are React Server Components by default
- Use "use client" only when the component needs interactivity
- Import paths use @/ alias mapped to src/
- Error handling: wrap async operations in try/catch, never use .catch()
- No default exports except for pages and layouts

Тримайте його коротшим за 30 рядків. Воно завантажується з кожним запитом, тому кожне слово коштує токенів.

Правило для компонентів React (Auto-Attached)

---
description: "React component patterns and conventions"
globs: ["src/components/**/*.tsx", "src/app/**/*.tsx"]
alwaysApply: false
---

# React Component Rules

## Structure
Every component file follows this order:
1. Imports
2. Type definitions (Props interface)
3. Component function (named export)
4. Sub-components (if any)

## Patterns

Use named exports, not default:
- YES: `export function Button({ label }: ButtonProps)`
- NO: `export default function Button()`

For data fetching in Server Components:
```tsx
// Отримуйте дані безпосередньо в компоненті, без useEffect
export async function UserProfile({ id }: { id: string }) {
  const user = await db.query.users.findFirst({
    where: eq(users.id, id)
  });
  return <div>{user.name}</div>;
}

Anti-Patterns (NEVER do these)

• No useEffect for data fetching in Server Components
• No CSS modules — use Tailwind exclusively
• No barrel exports (index.ts re-exports)
• No prop drilling beyond 2 levels — use context or composition

### Правило для API на Python (Auto-Attached)

```yaml
---
description: "FastAPI endpoint conventions and patterns"
globs: ["src/api/**/*.py", "src/routes/**/*.py"]
alwaysApply: false
---

# FastAPI Conventions

## Endpoint Structure
- Use APIRouter for route grouping
- Type all request/response models with Pydantic v2
- Dependency injection for database sessions

## Pattern
```python
from fastapi import APIRouter, Depends, HTTPException
from sqlalchemy.ext.asyncio import AsyncSession

router = APIRouter(prefix="/users", tags=["users"])

@router.get("/{user_id}", response_model=UserResponse)
async def get_user(
    user_id: int,
    db: AsyncSession = Depends(get_db)
) -> UserResponse:
    user = await db.get(User, user_id)
    if not user:
        raise HTTPException(status_code=404, detail="User not found")
    return UserResponse.model_validate(user)

Error Handling

• Always use HTTPException, not raw Response objects
• Log errors with structlog before raising
• Return consistent error shapes: {"detail": "message"}

### Правило для сервісу на Go (Auto-Attached)

```yaml
---
description: "Go service patterns and error handling"
globs: ["**/*.go", "!**/*_test.go"]
alwaysApply: false
---

# Go Conventions

## Error Handling
- Always handle errors immediately — no _ for error returns
- Wrap errors with fmt.Errorf("context: %w", err)
- Use sentinel errors for expected failure cases

## Project Layout
- cmd/ for entrypoints
- internal/ for private packages
- pkg/ for public libraries

## Pattern
```go
func (s *UserService) GetByID(ctx context.Context, id string) (*User, error) {
    user, err := s.repo.Find(ctx, id)
    if err != nil {
        if errors.Is(err, ErrNotFound) {
            return nil, fmt.Errorf("user %s: %w", id, ErrNotFound)
        }
        return nil, fmt.Errorf("fetching user %s: %w", id, err)
    }
    return user, nil
}

## Керування «токенним податком»

Ось про що більшість гайдів по Cursor мовчать: кожне написане вами правило коштує токенів. Проєкт із 20 правилами, що завжди активні, може спалювати **понад 2000 токенів на запит** лише на інструкціях, перш ніж ШІ навіть подивиться на ваш код.

Це важливо, тому що контекст чату Cursor становить приблизно 20 000 токенів у стандартному режимі. Якщо ваші правила з’їдають 25% цього обсягу, ви втрачаєте чверть «простору для мислення» ШІ для вашого фактичного запитання. Ви помітите погіршення якості результату, коли правил стає багато, особливо в довгих розмовах.

Три принципи допоможуть зберегти здоров’я вашого бюджету токенів:

**1. Агресивно використовуйте правила з автоматичним прикріпленням та за запитом агента.** Лише оголошення стеку вашого проєкту має бути завжди активним. Усе інше має завантажуватися умовно. Те саме правило для компонентів React? Йому не потрібно бути в контексті, коли ви пишете SQL-міграції.

**2. Пишіть щільно, а не багатослівно.** Замініть «Наполегливо рекомендується розробникам використовувати інтерфейси TypeScript замість аліасів типів при визначенні контрактів публічного API» на «Віддавайте перевагу `interface` над `type` для публічних API». ШІ не потрібно переконувати, йому потрібні інструкції.

**3. Застосовуйте «Правило трьох».** Фіксуйте патерн як правило лише після того, як ШІ помилився тричі. Якщо Cursor уже правильно обробляє ваші угоди щодо найменувань без правила, пропустіть його створення. Кожне непотрібне правило — це марно витрачений контекст.

Ви можете моніторити використання токенів у статусному рядку внизу панелі чату Cursor. Слідкуйте за наближенням до 100% — це сигнал до очищення.

## Організація правил для реального проєкту

Продакшн-проєкт зазвичай потребує 5–8 файлів правил. Ось структура, яка добре працює:

```text
.cursor/rules/
  base.mdc            # Tech stack, always-apply (< 30 lines)
  components.mdc      # React/Vue patterns, glob to component dirs
  api.mdc             # Backend conventions, glob to API dirs
  database.mdc        # ORM patterns, glob to models/migrations
  testing.mdc         # Test conventions, glob to test files
  deployment.mdc      # CI/CD patterns, manual trigger
  personal.mdc        # Your preferences (gitignored)

Зафіксуйте все в системі контролю версій, окрім personal.mdc. Таким чином, вся ваша команда отримає однакову поведінку ШІ, а в цьому й полягає суть. Як каже один користувач форуму Cursor, хороші правила означають, що «ви приймаєте більше пропозицій як є, а результат відповідає вашим угодам з першої спроби».

Якщо ви працюєте з іншими інструментами AI-кодингу разом із Cursor, ці концепції переносяться безпосередньо. Claude Code використовує CLAUDE.md, GitHub Copilot має файли інструкцій, а Windsurf має власний формат, але базовий принцип ідентичний.

Як працює пріоритет правил

Коли кілька правил застосовуються до одного й того самого файлу, Cursor дотримується чіткої ієрархії:

Командні правила доступні на планах Team та Enterprise. Вони встановлюються адміністраторами в дашборді Cursor і застосовуються в усій організації; окремі розробники не можуть їх вимкнути.

У межах проєктних правил, якщо два правила застосовуються до одного файлу і конфліктують, поведінка не є суворо визначеною. На практиці правила, завантажені пізніше, мають вищий пріоритет. Нумерація ваших файлів (001-base.mdc, 002-components.mdc) забезпечує передбачуваний порядок.

Поширені помилки та способи їх виправлення

Після прочитання десятків тем на спільнотах і тестування правил у різних проєктах, ось помилки, які найбільше заплутують людей:

Написання надто загальних правил. «Пишіть чистий код» нічого не говорить ШІ. «Використовуйте іменовані експорти, а не експорти за замовчуванням. Структуруйте компоненти так: імпорти, типи, функція, підкомпоненти» дає йому конкретні дії.

Встановлення always-apply для всього. Ваш перший імпульс — поставити alwaysApply: true для кожного правила. Стримайтеся. Аудитуйте свої правила щокварталу; якщо у вас більше 2–3 завжди активних правил, ви, ймовірно, марнуєте токени.

Забування тестувати правила. Після написання правила відкрийте відповідний файл і попросіть Cursor згенерувати щось, що має відповідати правилу. Якщо ні, можливо, ваш шаблон glob неправильний або інструкція недостатньо чітка.

Ігнорування антипатернів. Сказати ШІ, що робити, — це половина справи. Сказати йому, чого не робити, — друга половина. Додайте розділ «НІКОЛИ не робіть цього» до кожного правила з чіткими прикладами неправильного підходу.

Ігнорування збереження правил в UI. Відома помилка призводить до зникнення змін у правилах. Якщо зміни зникають, повністю закрийте Cursor, виберіть «Override» у спливаючому вікні про незбережені зміни та відкрийте програму знову.

Правила Cursor проти CLAUDE.md проти AGENTS.md

Cursor — не єдиний інструмент, який використовує файли інструкцій. Ось порівняння форматів для тих, хто працює з декількома AI-асистентами для кодингу:

Перевага Cursor — у гранулярності. CLAUDE.md та AGENTS.md простіші, вони завантажують усе завжди. Cursor дозволяє завантажувати правильні правила в правильний час, що стає важливим, коли набір інструкцій перевищує кілька сотень рядків.

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

FAQ

Чи застарів .cursorrules?

Так. Єдиний файл .cursorrules у корені вашого проєкту все ще працює, але Cursor рекомендує мігрувати на файли .cursor/rules/*.mdc. Новий формат підтримує шаблони glob, умовне завантаження та кращу організацію. Для міграції розділіть ваш монолітний файл на сфокусовані правила.

Яке розширення файлу використовувати: .mdc чи .md?

Використовуйте .mdc для файлів, які містять YAML frontmatter (description, globs, alwaysApply). Звичайні файли .md також працюють у директорії правил, але не підтримують метадані frontmatter, які дозволяють умовне завантаження.

Скільки правил має бути в проєкті?

П’ять-вісім — оптимальна кількість для більшості проєктів. Одне завжди активне базове правило, три-чотири правила з автоматичним прикріпленням, сфокусовані на типах файлів, і одне-два ручні правила для спеціальних завдань. Більше ніж 10 правил зазвичай означає, що деякі з них можна об’єднати або видалити.

Чи впливають правила Cursor на автодоповнення та завершення по Tab?

Правила застосовуються до чату та взаємодій з агентом. Користувацькі правила не застосовуються до inline-редагування (Cmd/Ctrl+K), і правила загалом не впливають на пропозиції автодоповнення Cursor Tab. Вони найбільш ефективні в чаті та сесіях Composer.

Чи можу я ділитися правилами між кількома проєктами?

Так, через функцію Remote Rules у Cursor. Перейдіть до Cursor Settings > Rules, Commands, виберіть "Remote Rule (GitHub)" і вставте URL репозиторію. Правила автоматично синхронізуються при оновленні вихідного репо. Альтернативно, ведіть спільний репозиторій правил і створюйте символьні посилання в кожному проєкті.

Яка максимальна рекомендована довжина правила?

Документація Cursor радить тримати окремі правила коротшими за 500 рядків. На практиці прагніть до менш ніж 100 рядків на правило. Коротші правила легше підтримувати і вони коштують менше токенів. Якщо правило перевищує 150 рядків, розділіть його на два сфокусовані правила.

Чи працюють правила з усіма AI-моделями в Cursor?

Правила працюють з кожною моделлю, яку підтримує Cursor: Claude, GPT-4o, Gemini та іншими. Правила додаються як контекст системного рівня незалежно від обраної моделі. Поведінка моделі може варіюватися, але самі правила не залежать від моделі.

Як налагодити правило, яке не працює?

Спочатку перевірте, чи шаблон glob відповідає вашому файлу: відкрийте файл і перевірте, чи з’являється правило в панелі контексту. По-друге, протестуйте з прямим запитанням, яке має активувати правило. По-третє, спробуйте тимчасово встановити alwaysApply: true, щоб підтвердити, що вміст самого правила працює. Якщо так, проблема у вашому шаблоні glob.

Чи варто комітити .cursor/rules у git?

Абсолютно. Вся суть проєктних правил — у консолідації команди. Комітьте все в .cursor/rules/, окрім файлів особистих уподобань. Додайте personal.mdc до .gitignore для індивідуальних налаштувань, які не повинні застосовуватися до всіх.

Чи можна використовувати правила Cursor разом із MCP-серверами?

Так, і вони добре доповнюють одне одного. Правила визначають, як ШІ має писати код, тоді як MCP-сервери надають ШІ доступ до зовнішніх інструментів і даних. Правило може говорити «завжди використовуйте наш внутрішній API-клієнт», тоді як MCP-сервер дозволяє ШІ фактично запитувати цей API під час розробки.

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

Джерела

• Документація правил Cursor
• Trigger.dev, Як писати чудові правила для Cursor
• Форум Cursor, Найкращі практики MDC-правил та усунення неполадок
• Peakvance, Гід з правил Cursor: Токенний податок
• awesome-cursor-rules-mdc на GitHub