Rules files and project context

У модели нет памяти между запросами. Каждый новый чат начинается с нуля: агент не знает, что в проекте принят строгий TypeScript, что стили пишутся токенами, а не сырыми hex-значениями, и что тесты живут рядом с кодом. Без правил вы повторяете эти вводные в каждом промпте — а в день, когда забудете, получите правку в чужом стиле.

Rules-файлы решают это системно: их содержимое автоматически подставляется в контекст модели в начале работы, как постоянная часть системного промпта. Это даёт три свойства, которых нет у устных договорённостей. Повторяемость: одинаковые вводные в каждом запросе, а не по памяти. Версионируемость: правила лежат в репозитории, меняются через обычный PR и ревьюятся командой. Общность: новый человек — или новый агент — получает те же конвенции, что и все.

Что уместно в правилах: версии стека и запрещённые библиотеки, конвенции именования и структуры каталогов, паттерны обработки ошибок, глоссарий доменных терминов, команды сборки и тестов. Что неуместно: секреты и ключи (правила попадают в контекст модели и в git), длинные пересказы того, что и так проверяет линтер, устаревшие инструкции, противоречащие текущему коду. Правило, которому не следует сам код проекта, хуже отсутствия правила — оно учит модель игнорировать ваши инструкции.

Исторически Cursor читал один файл .cursorrules в корне репозитория. Формат ещё поддерживается, но объявлен устаревшим: один плоский файл не масштабируется на монорепо и не умеет подключаться выборочно. Современный формат — каталог .cursor/rules/ с файлами *.mdc: markdown плюс frontmatter-метаданные.

---
description: Стандарты API-роутов сервера
globs: ["src/server/api/**/*.ts"]
alwaysApply: false
---

- Хендлеры возвращают Result<T, ApiError>, исключения наружу не бросаем.
- Вход валидируем zod-схемами из src/server/schemas, не вручную.
- Новый роут регистрируем в src/server/router.ts в алфавитном порядке.

@src/server/api/users.ts

Метаданные определяют, когда правило попадает в контекст, и дают четыре типа подключения. Always (alwaysApply: true) — правило включается всегда; годится только для короткого ядра конвенций. Auto Attached — правило подтягивается, когда в контексте появляются файлы, совпадающие с globs: правила про API включаются, только когда агент трогает API. Agent Requested — у правила есть description, и агент сам решает, нужно ли оно для текущей задачи. Manual — правило включается только явным упоминанием @имя-правила в запросе.

Строка @src/server/api/users.ts в конце — ссылка на файл-эталон: Cursor приложит его к контексту вместе с правилом, и «пиши как в этом файле» станет исполняемой инструкцией. В монорепо каталоги .cursor/rules можно класть в подпроекты — вложенные правила действуют на своё поддерево.

Хорошее правило похоже на хороший код-ревью-комментарий: конкретное, проверяемое, с примером. Сравните: «пиши чистый код» — модель не извлечёт из этого ничего; «функции-хендлеры не длиннее 40 строк, бизнес-логика выносится в src/services» — исполняемая инструкция. Сильнейший приём — пара примеров «плохо/хорошо» прямо в правиле: два коротких фрагмента кода учат модель быстрее, чем абзац описания.

Держите каждое правило сфокусированным и коротким — ориентир не больше 500 строк, а лучше значительно меньше. Большую тему режьте на несколько составных правил с точными globs: отдельно API, отдельно стили, отдельно тесты. Так в контекст попадает только относящееся к задаче, а не весь свод законов.

Откуда берутся правила? Из ревью. Рабочий ритуал: исправили в AI-диффе одну и ту же ошибку второй раз — остановитесь и добавьте правило. Модель раз за разом тянет moment вместо принятого в проекте date-fns — правило. Кладёт тесты не в тот каталог — правило. Так набор правил растёт из реальных ошибок, а не из абстрактных пожеланий.

Антипаттерны: расплывчатые эссе о ценностях команды; дублирование того, что и так ловят линтер и форматтер; правила-простыни на тысячу строк; и главное — протухшие правила, противоречащие коду. Правила — это код: ревьюйте их в PR и удаляйте мёртвые.

Команды редко живут в одном инструменте: кто-то в Cursor, кто-то в VS Code с Copilot, терминальные агенты читают свои файлы. У каждого инструмента свой формат инструкций: Cursor — .cursor/rules, Copilot — .github/copilot-instructions.md плюс файлы *.instructions.md с glob-привязкой, Claude Code — CLAUDE.md. Если поддерживать три копии одних и тех же конвенций, они разъедутся за месяц — и разные агенты начнут писать в разных стилях в одном репозитории.

Появился открытый стандарт AGENTS.md — единый markdown-файл инструкций в корне репозитория, который понимают многие инструменты, включая Cursor. Идея та же, что у README: один предсказуемый файл, но адресованный агентам, а не людям — команды сборки, конвенции, предупреждения о минных полях.

Практичная стратегия — один канонический источник и тонкие адаптеры. Общие конвенции проекта живут в AGENTS.md; инструменто-специфичные файлы либо ссылаются на него, либо содержат только то, чего стандарт не умеет: например, выборочное подключение по globs — это сила именно .cursor/rules и *.instructions.md, её и оставляйте в нативных форматах. Проверка простая: задайте один и тот же вопрос о конвенциях проекта агенту в Cursor и агенту в терминале — ответы должны совпадать. Если нет, ваши источники инструкций уже разошлись, и пора возвращать их к одному канону.