Урок 3: .cursorrules — программируем AI под ваш проект

Чему вы научитесь

• Что такое .cursorrules и как он работает
• Создавать правила для разных стеков технологий
• Структурировать инструкции по роли, стилю и архитектуре
• Применять готовые примеры .cursorrules из реальных проектов

Что такое .cursorrules и Project Rules?

flowchart LR
  A[".cursor/rules/*.mdc"] --> B["Cursor читает"]
  B --> C["Контекст к промпту"]
  C --> D["AI в рамках правил"]

.cursorrules (устаревший) и Project Rules (новый формат) — это способ “запрограммировать” AI на работу с вашей кодовой базой. Это аналог инструкции для AI: “Вот как нужно писать код в нашем проекте”.

Когда вы открываете проект в Cursor, он автоматически находит правила в .cursor/rules/ (или .cursorrules для обратной совместимости) и использует их во всех диалогах с AI.

Новый формат: .cursor/rules/*.mdc

Файлы .mdc — это структурированный Markdown с поддержкой метаданных:

.cursor/
└── rules/
    ├── typescript.mdc   # Правила для TypeScript файлов
    ├── python.mdc       # Правила для Python
    └── general.mdc      # Общие правила проекта

Преимущества нового формата:

• Можно задать glob-паттерны (например, только для *.tsx файлов)
• Лучшая организация по типам файлов
• Проще обновлять отдельные правила

Зачем это нужно?

Без .cursorrules:

Ты: Создай компонент для входа.

AI: Создаёт компонент без типов, с обычным CSS,
    неправильной структурой проекта,
    не следуя вашим соглашениям.

С .cursorrules:

Где размещать правила

Приоритет: если есть несколько правил, применяются все подходящие по glob-паттернам.

Структура .cursorrules

Нет жёсткого формата, но рекомендуемая структура:

# <Название проекта>

## Роль

Ты — опытный разработчик на [язык/фреймворк].
Твоя цель — помогать разработке проекта [название] на основе этих правил.

## Стек технологий

- Runtime: [Node 18+, Python 3.9, etc.]
- Framework: [React 18, FastAPI, etc.]
- Language: [TypeScript, JavaScript, Python, etc.]
- Package Manager: [npm, pnpm, pip, etc.]
- Testing: [Jest, pytest, etc.]

## Соглашения о коде

### Именование
- Компоненты React: PascalCase (Button.tsx)
- Функции и переменные: camelCase
- Константы: UPPER_SNAKE_CASE

### Структура файлов
- Components: /src/components/ComponentName/ComponentName.tsx
- Hooks: /src/hooks/useHookName.ts
- Types: /src/types/index.ts
- Utils: /src/utils/utilName.ts

### Стиль кода
- Используй Prettier для форматирования
- Используй ESLint для проверки
- Максимальная длина строки: 100 символов

## Архитектурные правила

[Описание подходов к разработке]

## Запреты

[Что AI категорически не должен делать]

Пример 1: React + TypeScript (Frontend)

Пример 2: Python + FastAPI (Backend)

Пример 3: Next.js (Fullstack)

# Next.js fullstack приложение

## Роль

Ты — fullstack разработчик на Next.js и TypeScript.
Помогай разработке фронтенда и бэкенда в одном проекте.

## Стек технологий

- Next.js 13+ (App Router)
- React 18.2+
- TypeScript 5.0+
- Tailwind CSS
- Prisma (ORM)
- PostgreSQL
- NextAuth.js (аутентификация)

## Соглашения о коде

### Структура проекта

app/ ├── layout.tsx (root layout) ├── page.tsx (home page) ├── (auth)/ │ ├── login/page.tsx │ ├── register/page.tsx ├── dashboard/ │ ├── layout.tsx │ ├── page.tsx │ └── posts/[id]/page.tsx ├── api/ │ ├── auth/[…nextauth]/route.ts │ ├── posts/ │ │ ├── route.ts (GET, POST) │ │ └── [id]/route.ts (GET, PUT, DELETE) │ └── users/route.ts ├── components/ │ ├── Header.tsx │ ├── Footer.tsx │ └── PostCard.tsx └── lib/ ├── auth.ts ├── db.ts └── utils.ts

prisma/ ├── schema.prisma (модели БД) └── migrations/

### API Routes как Server Functions

```typescript
// app/api/posts/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { prisma } from '@/lib/db';
import { auth } from '@/lib/auth';

export async function GET(request: NextRequest) {
  const posts = await prisma.post.findMany({
    include: { author: true }
  });
  return NextResponse.json(posts);
}

export async function POST(request: NextRequest) {
  const session = await auth();
  if (!session) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  const data = await request.json();
  const post = await prisma.post.create({
    data: {
      ...data,
      authorId: session.user.id
    }
  });
  return NextResponse.json(post, { status: 201 });
}

Архитектурные правила

• Используй App Router, не Pages Router
• Server Components по умолчанию, ‘use client’ только где нужно
• API Routes в app/api/
• Prisma для типобезопасной работы с БД
• NextAuth.js для аутентификации

Запреты

• НЕ используй Pages Router в новых проектах
• НЕ смешивай server и client компоненты
• НЕ делай fetch на сервере без кэширования

## Пример 4: Data Science (Python + pandas)

```markdown
# Data Science проект на Python

## Роль

Ты — опытный data scientist.
Помогай анализу данных, машинному обучению и визуализации.

## Стек технологий

- Python 3.10+
- pandas 2.0+
- numpy 1.24+
- scikit-learn (ML моделей)
- matplotlib + seaborn (визуализация)
- Jupyter Notebook для EDA
- pytest для тестирования

## Соглашения о коде

### Структура проекта

project/ ├── data/ │ ├── raw/ (исходные данные) │ ├── processed/ (обработанные) │ └── external/ (внешние источники) ├── notebooks/ │ ├── 01_eda.ipynb │ ├── 02_preprocessing.ipynb │ └── 03_modeling.ipynb ├── src/ │ ├── init.py │ ├── data_loader.py │ ├── preprocessing.py │ ├── models.py │ ├── visualization.py │ └── utils.py ├── tests/ │ ├── test_preprocessing.py │ └── test_models.py ├── models/ (сохранённые модели) ├── requirements.txt └── README.md

### Стиль анализа

```python
import pandas as pd
import numpy as np
from sklearn.preprocessing import StandardScaler
from sklearn.model_selection import train_test_split

# Загрузка данных
df = pd.read_csv('data/raw/dataset.csv')

# Проверка качества
print(f"Shape: {df.shape}")
print(f"Missing: {df.isnull().sum()}")
print(df.head())

# Обработка
df['feature_1'] = df['raw_feature'].astype('category')
df = df.dropna()

# Разделение
X_train, X_test, y_train, y_test = train_test_split(
    df.drop('target', axis=1),
    df['target'],
    test_size=0.2,
    random_state=42
)

# Масштабирование
scaler = StandardScaler()
X_train_scaled = scaler.fit_transform(X_train)
X_test_scaled = scaler.transform(X_test)

Архитектурные правила

• Не изменяй исходные данные (raw/ всегда нетронуты)
• Документируй все шаги предобработки
• Используй sklearn для ML, не самописные решения
• Визуализируй промежуточные результаты
• Сохраняй модели (pickle, joblib)

Запреты

• НЕ используй старые версии pandas (< 1.0)
• НЕ смешивай обработку в ноутбуках и скриптах
• НЕ забывай про random_state для reproducibility

## Пример 5: React Native (Mobile)

```markdown
# React Native мобильное приложение

## Роль

Ты — опытный React Native разработчик.
Помогай разработке кроссплатформенного приложения для iOS и Android.

## Стек технологий

- React Native 0.72+
- TypeScript 5.0+
- React Navigation (маршрутизация)
- Redux Toolkit (состояние)
- React Query (API)
- Jest + React Native Testing Library

## Соглашения о коде

### Структура проекта

src/ ├── navigation/ │ ├── RootNavigator.tsx │ └── AuthNavigator.tsx ├── screens/ │ ├── HomeScreen.tsx │ ├── ProfileScreen.tsx │ └── SettingsScreen.tsx ├── components/ │ ├── Button.tsx │ ├── Card.tsx │ └── Loading.tsx ├── redux/ │ ├── store.ts │ ├── authSlice.ts │ └── userSlice.ts ├── services/ │ ├── api.ts │ └── storage.ts ├── types/ │ └── index.ts └── App.tsx

### Типобезопасный Redux

```typescript
import { configureStore } from '@reduxjs/toolkit';
import authReducer from './authSlice';
import { useDispatch, useSelector } from 'react-redux';

export const store = configureStore({
  reducer: {
    auth: authReducer
  }
});

export type RootState = ReturnType<typeof store.getState>;
export type AppDispatch = typeof store.dispatch;

export const useAppDispatch = () => useDispatch<AppDispatch>();
export const useAppSelector = <T,>(selector: (state: RootState) => T) =>
  useSelector(selector);

Архитектурные правила

• Используй Functional Components с Hooks
• Redux для глобального состояния
• React Query для API запросов
• React Navigation для маршрутизации
• Platform-specific файлы: Button.ios.tsx и Button.android.tsx

Запреты

• НЕ используй класс компоненты
• НЕ смешивай Redux и useState для одного состояния
• НЕ забывай про platform-specific логику

## Best Practices для .cursorrules

### 1. Будьте конкретны

**Плохо:**

Используй хорошие практики и стандарты.

**Хорошо:**

Все компоненты должны иметь JSDoc с примерами использования. Используй TypeScript strict mode (noImplicitAny: true). Функции не должны превышать 30 строк.

### 2. Показывайте примеры

**Плохо:**

Код должен быть читаемым.

**Хорошо:**
```javascript
// Плохо
function f(a,b) { return a.map(x => x.prop).filter(x => x) }

// Хорошо
function extractActiveNames(users: User[]): string[] {
  return users
    .map(user => user.name)
    .filter(name => name.length > 0);
}

3. Обновляйте регулярно

Когда ваш проект меняется (обновление версии, смена архитектуры), обновляйте .cursorrules. AI будет следовать новым инструкциям.

4. Инструируйте, не ограничивайте

Плохо:

НЕ используй async/await, это медленно.

Хорошо:

Используй async/await для асинхронных операций.
Избегай callback hell'а. Для параллельных операций используй Promise.all().

Как тестировать .cursorrules

Создайте тестовую задачу:

Напиши компонент Button согласно стандартам проекта.

Проверьте:

• Следует ли структуре файлов
• Правильно ли именует (camelCase, PascalCase)
• Использует ли правильные типы (TypeScript)
• Стиль кода совпадает
• Документация присутствует

Если что-то не так, обновите .cursorrules и попробуйте снова.

Ключевые выводы

• Project Rules (.cursor/rules/*.mdc) — актуальный формат в Cursor с 2025 года
• .cursorrules — устаревший формат, работает для обратной совместимости, но мигрируйте
• Структура правил: роль, стек, соглашения, архитектура, запреты
• Примеры для React, Python, Next.js, Data Science, React Native показывают реальные структуры
• Будьте конкретны — примеры кода важнее, чем общие фразы
• Обновляйте регулярно, когда меняется проект
• Тестируйте инструкции — дайте AI простую задачу и проверьте результат

Следующий урок

В Уроке 4: CLI vs IDE — когда что сравним два подхода:

• Когда лучше использовать Cursor (IDE)
• Когда лучше использовать Claude Code или другой CLI
• Сценарии и примеры для каждого
• Гибридный workflow