Как писать Cursor Rules, которые остаются короткими и применяются

Хорошие Cursor Rules — это короткие проектные инструкции с понятной областью действия и проверяемым результатом. Они дают агенту только тот контекст, который нужен для текущих файлов или процедуры, и не пытаются заменить документацию, спецификации, тесты и CI.

Проблема большинства rules-файлов не в недостатке подробностей. Они растут как журнал всех прошлых ошибок, всегда загружаются вместе и начинают противоречить друг другу. В итоге агент получает больше токенов, но меньше ясности.

Сначала выберите способ подключения

Cursor Project Rules хранятся в .cursor/rules/*.mdc. Frontmatter управляет тем, когда правило входит в контекст. Выбор режима — часть смысла правила, а не техническая мелочь. Если нужен обзор формата до практической настройки, начните со статьи «Cursor Rules: что это и как настроить».

Always Apply

Используйте для небольшого набора действительно глобальных инвариантов:

• команда package manager;
• основной язык и formatter;
• критичная архитектурная граница;
• обязательная последовательность gates перед release;
• запрет на изменение generated files.

Если правило относится только к database code, оно не должно быть always. Глобальный контекст — самый дорогой: он конкурирует с задачей в каждой сессии.

Apply to Specific Files

Выбирайте glob, когда область можно определить по пути:

• src/db/** для schema и migrations;
• src/**/*.test.* для тестовых соглашений;
• src/app/**/page.tsx для route boundaries;
• infra/** для deployment-конфигурации.

Glob должен описывать файлы, где правило нужно применить, а не все файлы, которые оно когда-либо упоминает.

Apply Intelligently

Режим подходит для тематического знания без стабильного пути: performance review, accessibility audit, обработка внешнего API. Description должна объяснять триггер достаточно конкретно, иначе агент не поймёт, когда правило запрашивать.

Apply Manually

Используйте для редких процедур: release, dependency upgrade, incident review, миграция между major versions. Такие инструкции не должны занимать контекст обычной feature-задачи.

Одно правило — один контракт

Файл project-rules.mdc, где одновременно описаны React, SQL, Git, deployment и tone of voice, невозможно правильно привязать к области. Разделение по одному контракту делает правила короче и позволяет выбрать активацию:

.cursor/rules/
  architecture.mdc
  database-migrations.mdc
  frontend-accessibility.mdc
  testing.mdc
  release.mdc

Название должно отвечать на вопрос, что защищает правило. important.mdc и misc.mdc скрывают назначение и почти гарантируют дальнейшее накопление.

Пишите наблюдаемую инструкцию

«Пиши качественный код» нельзя проверить. «Каждый route handler валидирует request через schema до использования данных» задаёт наблюдаемую границу.

Сильная инструкция содержит:

1. Контекст: где она применяется.
2. Действие: что агент делает или не делает.
3. Проверку: какой командой или тестом доказать результат.
4. Исключение: где правило сознательно не действует.
5. Ссылку: где лежит подробный контракт, если он длинный.

Пример:

---
description: Validate external input in server routes and actions
globs: "src/app/**/{route,actions}.ts"
alwaysApply: false
---

- Parse request data with the project schema before use.
- Return the existing typed validation error; do not invent a second format.
- Run `pnpm test --filter server-input` after changing this boundary.
- Full contract: `docs/rules/security.md`.

Правило не пересказывает весь security document. Оно подаёт нужную часть и указывает проверку.

Не храните в rules то, что уже знает репозиторий

Агент может прочитать package.json, types и соседний код. Rules нужны для неочевидного: причин архитектурной границы, обязательного порядка действий, опасного edge case или команды, которую легко пропустить.

Плохие кандидаты:

• полный список dependencies;
• документация framework API;
• дерево каждого каталога;
• стиль, уже автоматически задаваемый formatter;
• требования одной текущей фичи;
• длинные примеры, доступные в самом коде.

Хорошие кандидаты:

• «middleware не делает network calls, потому что работает на edge boundary»;
• «migration после применения не редактируется, создаётся новая»;
• «новый тест считается готовым только после доказанного красного запуска»;
• «внешняя операция требует idempotency key».

AGENTS.md и Cursor Rules не должны конкурировать

Cursor поддерживает корневые и вложенные AGENTS.md как plain-Markdown инструкции. Удобная граница:

• AGENTS.md — карта проекта, команды и общие инварианты;
• .cursor/rules/*.mdc — selective context и Cursor-специфичные процедуры;
• docs/specs/ — контракт конкретного изменения;
• lint/tests/hooks — машинная проверка.

Если один абзац копируется в три файла, выберите canonical document и оставьте короткие ссылки. Дублирование создаёт не надёжность, а три будущих версии правила.

Сравнение форматов — в статье «AGENTS.md vs CLAUDE.md vs Cursor Rules».

Правило не заменяет enforcement

Cursor Rules включают инструкции в контекст модели. Они не гарантируют, что каждое действие будет им соответствовать. Машинно проверяемые требования нужно переносить в инструменты:

• formatter — форматирует;
• linter — проверяет статические границы;
• type checker — форму данных и API;
• tests — поведение;
• hooks — запрещённые tool calls или обязательные preconditions;
• CI — итоговую последовательность gates.

Rules объясняют агенту, как пройти проверки и почему они существуют. Это важная роль, но другая.

Как сокращать существующий набор

Проведите audit в таком порядке:

1. Выпишите все Always Apply rules.
2. Для каждого спросите, относится ли он к каждой задаче.
3. Разделите path-scoped, relevance-scoped и manual процедуры.
4. Удалите факты, которые агент получает из кода автоматически.
5. Найдите противоречия и выберите один canonical source.
6. Привяжите каждое критичное утверждение к проверке.
7. Добавьте дату или триггер review для правил о быстро меняющемся tool API.

После сокращения проверьте реальную задачу: видит ли агент нужное правило, может ли назвать обязательный gate и не загрузил ли unrelated инструкции.

Когда добавлять новое правило

Не добавляйте его после любой ошибки. Сначала выясните причину:

• агент не знал проектного факта — обновить правило;
• требование было неоднозначным — обновить spec;
• проверка отсутствовала — добавить test или gate;
• tool API изменился — обновить integration и источник;
• исключение было разумным — уточнить границу, а не запрещать всё.

Правило оправдано, если ошибка повторяема, контекст долговечен и инструкция изменит решение будущего агента.

Нужно привести набор Cursor Rules к рабочей системе, а не к длинному prompt? Опишите репозиторий и текущие правила — можно разложить контекст по областям, убрать дублирование и связать критичные ограничения с gates.