Как писать правила Cursor в .cursor/rules и не тратить токены зря

Правила Cursor избавляют от необходимости в каждом чате заново объяснять агенту стек, структуру проекта и запреты. Правило пишется один раз и автоматически попадает в контекст модели. Но всё, что попадает в контекст, стоит токенов. Ниже — актуальный формат правил по официальной документации Cursor (страница Rules), примеры и советы, как держать правила компактными.

Какие бывают правила в Cursor

• Project Rules — файлы .mdc в папке .cursor/rules проекта. Хранятся в git и действуют в этом проекте.
• User Rules — личные правила для всех проектов, задаются в Customize → Rules.
• Team Rules — правила команды из панели управления, доступны на тарифах Team и Enterprise.
• AGENTS.md — простой Markdown-файл в корне проекта или в подпапках. Альтернатива .cursor/rules без метаданных.

Порядок приоритета при конфликте: Team Rules, затем Project Rules, затем User Rules.

Формат файла правила

Каждое проектное правило — отдельный файл с расширением .mdc в .cursor/rules/ (можно раскладывать по подпапкам). Обычный .md в этой папке игнорируется: у него нет метаданных. Структура файла: шапка с полями и текст правила.

Шапка управляет тем, когда правило подключается:

В интерфейсе эти режимы называются Always Apply, Apply to Specific Files, Apply Intelligently и Apply Manually.

Примеры правил

Общее правило, которое действует всегда. Держите его коротким:

---
alwaysApply: true
---

- Python 3.12, FastAPI, SQLAlchemy 2.x, PostgreSQL
- Run `make test` before proposing a commit
- Never edit files in `migrations/versions/` by hand; use `alembic revision --autogenerate`
- Ask before adding a new dependency

Правило для конкретных файлов:

---
globs: app/api/**/*.py
alwaysApply: false
---

- Each router lives in its own module under `app/api/`
- Validate input with Pydantic models, never accept raw dicts
- Return errors as `{"code": ..., "message": ...}`
- See @app/api/users.py for the reference structure

Правило, которое агент подключает по описанию:

---
description: Database migration conventions for Alembic
alwaysApply: false
---

- Every migration must have both upgrade and downgrade
- Never change a column type in place: add a column, backfill, drop the old one

Через @имя_файла правило ссылается на файл с образцом. Это лучше, чем копировать код в текст правила: образец не устареет.

Создать правило можно командой /create-rule в чате агента (агент сам сгенерирует файл с шапкой) или через Customize → Rules → Add Rule.

Плохой пример

---
alwaysApply: true
---

You should write really good, clean, well-designed code that follows best
practices. Think about edge cases, performance and security. Use good names.
Add comments where needed. Refactor if something seems messy.

Что с ним не так:

• нет ни одного факта о проекте, агент и так старается писать хороший код;
• alwaysApply: true отправляет эти строки в каждый чат;
• нечего проверить: непонятно, нарушил агент правило или нет.

Документация Cursor даёт похожие советы: держать правила короче 500 строк, делить большие правила на несколько, давать конкретные примеры или ссылки на файлы, не копировать целые стайлгайды (для этого есть линтер) и не описывать команды, которые агент и так знает (npm, git, pytest). Добавлять правило стоит тогда, когда агент повторяет одну и ту же ошибку.

Правила и расход токенов

Подключённое правило вставляется в начало контекста модели. Поэтому правило с alwaysApply: true оплачивается в каждом запросе, а правила с globs и description — только когда они нужны.

Пример расчёта. Правила с alwaysApply: true занимают 1 500 токенов, за день агент сделал 300 запросов. Это 1 500 × 300 = 450 000 входных токенов, или 0.45 × $0.3 = $0.135 по цене Zukko для Claude Sonnet 5 или GPT-5.6 Sol ($0.3 за 1M входных). Сократите постоянную часть до 500 токенов, остальное переведите на globs, и эта статья расхода уменьшится втрое. Оговорка про кэш: у вендора чтение из кэша промптов стоит около 10% входной цены, а в Zukko кэшированные токены оплачиваются по обычной входной цене. Поэтому для повторяющихся блоков реальная разница с официальным прайсом меньше, чем при прямом сравнении цен.

Размер правила в токенах можно измерить через эндпоинт count_tokens↗:

jq -n --rawfile t .cursor/rules/general.mdc '{model: "claude-sonnet-5", messages: [{role: "user", content: $t}]}' |
curl -s https://api.zukko.pro/v1/messages/count_tokens \
  -H "Authorization: Bearer fetch_ваш_ключ" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d @-

Ответ содержит input_tokens. У разных моделей токенизаторы отличаются, так что это оценка.

Подключение Cursor к Zukko

В настройках моделей Cursor включите Override OpenAI Base URL и укажите:

• Base URL: https://api.zukko.pro/v1;
• API Key: ваш ключ fetch_... из кабинета Zukko↗;
• модель — алиас Zukko для Cursor: cursor-sonnet-5 (Claude Sonnet 5), cursor-gpt-sol (GPT-5.6 Sol) или cursor-opus-55 (Claude Opus 5.5).

Подробная инструкция с проверкой — в документации Zukko по Cursor↗. Актуальный список моделей — GET https://api.zukko.pro/v1/models или страница «Модели» в кабинете. Правила работают одинаково, какую бы модель вы ни выбрали. Какая модель лучше следует вашим правилам, проверьте на нескольких своих задачах.

Частые вопросы

Почему правило не применяется?

Проверьте тип. Для Apply Intelligently нужно заполненное description, для Apply to Specific Files — шаблон globs, который совпадает с файлами в контексте. И убедитесь, что у файла расширение .mdc.

Можно ли сослаться из правила на другой файл?

Да: @имя_файла в тексте правила добавляет файл в контекст. Правило можно и вручную подключить в чате через @-упоминание.

Влияют ли правила на автодополнение Tab?

Нет. Правила не действуют на Cursor Tab и другие функции, кроме агента. User Rules не применяются и к Inline Edit (Cmd/Ctrl+K).

Что выбрать: .cursor/rules или AGENTS.md?

AGENTS.md проще: обычный Markdown без метаданных, его читают и другие агенты (Codex, Aider и т.д.). .cursor/rules нужен, когда правило должно подключаться только для определённых файлов или по описанию.