NC
← Все гайды
Продвинутое

Cursor Rules: полное руководство с примерами для Python и Next.js

Обновлено: 2026-07-06

Что такое Cursor Rules

Cursor Rules — постоянные инструкции для ИИ-агента и автодополнения. Они задают стиль кода, архитектуру, язык ответов и ограничения (например, не логировать персональные данные). Агент учитывает их в каждом диалоге, без повторения «пиши на typed Python» в каждом запросе.

Rules — главный инструмент E-E-A-T для вашего репозитория: чем точнее правила, тем предсказуемее результат и меньше правок вручную.

Где хранятся правила

МестоОбластьКогда использовать
Cursor Settings → Rules (User)все ваши проектыличные привычки, язык ответов
.cursor/rules/*.mdcодин репозиторийкоманда, продакшен-конвенции
AGENTS.md в корнеодин репозиторийкраткий манифест для агента
.cursorrules (legacy)проектстарый формат, лучше мигрировать в .mdc

Файлы в .cursor/rules/ поддерживают frontmatter с полем globs — правило применяется только к нужным файлам.

User rules vs Project rules

User rules — ваши глобальные настройки в Cursor: «отвечай на русском», «минимальный diff», «не коммить без запроса».

Project rules — в git, для всей команды: стек, структура папок, как писать API и тесты.

Рекомендация: общее поведение — в User rules; всё, что связано с кодом проекта — в .cursor/rules/.

Пример 1: Python / FastAPI (backend)

Файл .cursor/rules/backend-python.mdc:

---
description: Backend FastAPI conventions
globs: backend/**/*.py
alwaysApply: false
---

- Typed Python, Pydantic на границе API, бизнес-логика в services/.
- SQLAlchemy 2 async, параметризованные запросы, миграции Alembic обратимо.
- Не логировать пароли, токены, email — маскировать PII.
- Новые эндпоинты: явная authz, rate limit для публичных форм.
- Минимальный diff; не рефакторить несвязанный код без запроса.

Пример 2: валидация и ошибки API

---
description: API error handling
globs: backend/app/api/**/*.py
---

- В роутерах только HTTP-слой; ошибки домена — через HTTPException или handler.
- 422 для валидации Pydantic, 404 если сущность не найдена, 401/403 для auth.
- Сообщения ошибок без PII и без stack trace наружу в prod.

Пример 3: Next.js App Router (frontend)

Файл .cursor/rules/frontend-nextjs.mdc:

---
description: Next.js frontend conventions
globs: frontend/**/*.{ts,tsx}
---

- App Router, Server Components по умолчанию; "use client" только при необходимости.
- metadata / generateMetadata для SEO: title, description, canonical.
- Публичные env только NEXT_PUBLIC_*; секреты не в клиент.
- Следовать существующим компонентам и Tailwind-токенам проекта.
- Один H1 на страницу; alt у изображений; текст на русском для UI.

Пример 4: AGENTS.md в корне монорепо

# NeiroCursor — инструкции для агента

Стек: Next.js 16 + FastAPI + PostgreSQL + Docker.

Перед изменениями читай AGENTS.md и правила в `.cursor/rules/`.
Деплой: docker-compose.prod.yml на VPS, nginx проксирует /api.

Не коммить deploy-credentials, .env, ключи API.
После правок backend — проверь типы; после frontend — npm run build.

Как проверить, что Rules работают

  1. Откройте новый чат агента в Cursor.
  2. Спросите: «Какие правила проекта ты видишь?» — агент перечислит активные rules.
  3. Дайте задачу в зоне globs (например, «добавь эндпоинт в FastAPI») и проверьте, что код совпадает с конвенциями.

Типичные ошибки

  • Слишком длинные rules — агент теряет фокус. Дробите на файлы по globs.
  • Противоречия между User и Project rules — приоритет сбивает модель.
  • Правила без примеров — добавьте 2–3 строки «как мы пишем X».
  • Секреты в rules — только ссылки на env, не реальные ключи.
  • Копипаст чужого .cursorrules без адаптации под ваш стек.

Чеклист перед коммитом rules

  • User rules — личное; Project rules — в git
  • У каждого .mdc есть description и при необходимости globs
  • Нет паролей, токенов, email в примерах
  • AGENTS.md короткий (1 экран), ссылается на .cursor/rules/
  • Команда знает, что rules — живой документ (обновлять при смене стека)

Что дальше