TL;DR
Исследование 401 опенсорсного проекта показало: разработчики систематически описывают для AI-ассистентов пять типов контекста — структуру проекта, соглашения команды, руководства по работе, примеры кода и прямые директивы модели. Cursor rules (.mdc файлы) — это постоянные инструкции для AI в IDE, которые работают как "память проекта". Вместо того чтобы каждый раз объяснять контекст заново, разработчик один раз записывает ключевую информацию, и AI учитывает её во всех запросах.
Главная находка: Эффективный контекст для AI — не просто "вот код проекта", а структурированное описание того, как устроен проект (архитектура, технологии), какие приняты соглашения (стиль, паттерны), как надо работать (лучшие практики, workflow), плюс конкретные примеры и директивы поведению модели. Без этого AI генерирует код "вообще правильный", но не подходящий конкретному проекту — не тот стиль именования, не те библиотеки, не учитывает связи между компонентами.
Принципы применимы шире IDE: То, что работает в Cursor для проектов, работает в ChatGPT/Claude для любых задач. Когда начинаешь работу над проектом/документом/анализом — инициализируй контекст: опиши структуру, технологии, соглашения, покажи примеры, скажи как хочешь получать ответы. Один раз в начале сессии вместо повторения в каждом запросе.
Таксономия контекста (5 категорий)
Исследователи выделили пять категорий контекста, которые разработчики чаще всего указывают для AI:
1. PROJECT (Проект) — о чём проект и как устроен - Functionality — что делают разные части: "папка /api — REST endpoints, /lib — переиспользуемые утилиты" - Environment — технологии: "Next.js 14, TypeScript, Prisma ORM, PostgreSQL"
2. CONVENTION (Соглашения) — как принято в команде - Code Style — правила кода: "camelCase для переменных, PascalCase для компонентов" - Naming — именования: "хуки начинаются с use-, типы заканчиваются на Type" - Structure — организация файлов: "один компонент = одна папка с index.ts и styles.css"
3. GUIDELINE (Руководства) — как правильно делать - Development Practice — процесс разработки: "всегда пиши тесты перед кодом" - Security — безопасность: "никогда не логируй токены, валидируй все входы" - Performance — производительность: "используй React.memo для тяжёлых компонентов"
4. EXAMPLES (Примеры) — конкретный референсный код - Показать желаемый стиль: "Вот пример хорошего API endpoint: [код]"
5. LLM DIRECTIVES (Директивы модели) — как AI должна работать - Verification — что проверять: "Всегда проверяй типы перед генерацией" - Reasoning — как думать: "Объясняй решения пошагово" - Output Format — формат ответа: "Отвечай кратко, без лишних комментариев"
Пример применения
Задача: Работаешь над стартапом — SaaS-сервис для управления подписками (аналог российского Stripe). Проект на TypeScript + React, команда из трёх человек, у вас свои соглашения по коду. Хочешь, чтобы Claude помогала писать код, но она не знает вашу архитектуру и стиль.
Промпт (инициализация проекта в начале сессии):
Я работаю над проектом PayRu — SaaS для управления подписками компаний.
СТРУКТУРА ПРОЕКТА:
- /apps/web — фронтенд (Next.js 14, React, TypeScript)
- /apps/api — бэкенд (NestJS, PostgreSQL, Prisma)
- /packages/shared — общие типы и утилиты
- /packages/ui — библиотека UI-компонентов
ТЕХНОЛОГИИ:
- Фронт: Next.js 14 App Router, React Server Components, Tailwind CSS
- Бэк: NestJS, Prisma ORM, PostgreSQL, Redis для кеша
- Аутентификация через JWT, оплата через ЮKassa API
СОГЛАШЕНИЯ КОМАНДЫ:
- Компоненты: PascalCase, один компонент = папка с index.tsx и types.ts
- Хуки: всегда начинаются с use-, лежат в /hooks
- API endpoints: /api/v1/{resource}, всегда RESTful
- Типы: суффикс Type для интерфейсов (UserType, SubscriptionType)
- Ошибки: кастомные классы в /errors, всегда с кодом и сообщением
ПРАВИЛА РАЗРАБОТКИ:
- Всегда типизируй всё, никаких any
- API responses оборачивай в { data, error, meta }
- Валидируй входные данные через Zod-схемы
- Логируй ошибки, но не логируй токены/пароли
- Для тяжёлых списков используй виртуализацию
ПРИМЕРЫ СТИЛЯ:
Хороший API endpoint:
@Get('subscriptions/:id')
async getSubscription(@Param('id') id: string) {
const subscription = await this.service.findOne(id);
return { data: subscription, error: null };
}
КАК МНЕ ПОМОГАТЬ:
- Предлагай код сразу, без долгих объяснений
- Если неясна задача — задай уточняющие вопросы
- Указывай на потенциальные проблемы безопасности/производительности
- Когда генеришь новый компонент — сразу с типами и базовыми тестами
Готова работать в этом контексте?
Результат:
Claude подтвердит понимание контекста. Дальше во всех запросах этой сессии она будет: - Генерировать код в вашем стиле (правильные имена, структура файлов) - Использовать ваш стек (Next.js 14, Prisma, правильные импорты) - Следовать вашим правилам (типизация, обёртка ответов, валидация) - Отвечать в нужном формате (код без воды, с уточнениями)
Больше не нужно в каждом запросе объяснять "мы используем NestJS" или "используй наш стиль именования".
Почему это работает
Слабость LLM: Модель не знает ваш проект. Без контекста она генерирует "правильный код вообще" — синтаксически корректный, но: - Не тот стиль именования (snake_case вместо вашего camelCase) - Не те библиотеки (axios вместо вашего fetch-wrapper) - Не та архитектура (прямые SQL-запросы вместо вашего ORM) - Не те паттерны (классы вместо ваших функций)
Сильная сторона LLM: Модель отлично следует явным правилам и примерам, если они в контексте. Она видит паттерн и воспроизводит его. Но правила должны быть в текущей сессии — между сессиями память не сохраняется.
Как работает метод: Вместо повторения контекста в каждом запросе ("помни, мы используем TypeScript"), ты один раз инициализируешь сессию полным описанием проекта. Это как briefing для нового разработчика: "вот наш стек, вот наши соглашения, вот как мы работаем". Дальше все ответы в сессии учитывают этот контекст.
Рычаги управления:
- Глубина описания технологий — минимум (Next.js) vs подробно (Next.js 14 App Router, React Server Components) → подробнее = точнее генерация
- Конкретность примеров — абстрактно ("используй REST") vs конкретный код → конкретный код = точное воспроизведение стиля
- Директивы формата ответа — "объясняй подробно" vs "код без комментариев" → контролируешь объём ответа
- Уровень детализации правил — общие ("пиши типы") vs специфичные ("суффикс Type для интерфейсов") → специфичные = меньше отклонений
Для простой задачи достаточно 3-4 предложений. Для сложного проекта на 6 месяцев — можешь потратить 10 минут на детальное описание, оно окупится.
Шаблон промпта
Я работаю над {описание проекта}.
СТРУКТУРА ПРОЕКТА:
{какие основные части, что где лежит, как связаны}
ТЕХНОЛОГИИ:
{языки, фреймворки, библиотеки, инструменты}
СОГЛАШЕНИЯ:
{стиль кода, именования, структура файлов, паттерны}
ПРАВИЛА РАЗРАБОТКИ:
{лучшие практики, что обязательно, чего избегать}
ПРИМЕРЫ СТИЛЯ:
{1-2 примера кода, который ты считаешь хорошим}
КАК МНЕ ПОМОГАТЬ:
{формат ответов: кратко/подробно, с объяснениями/без, когда уточнять}
Готова работать в этом контексте?
Что подставлять:
- {описание проекта} — одно предложение: тип (веб-приложение, CLI-инструмент, API), назначение
- {структура} — основные директории/модули и их роли
- {технологии} — конкретные названия и версии (если важно)
- {соглашения} — ваши team conventions, если есть
- {правила} — что всегда/никогда не делать
- {примеры} — 1-2 фрагмента реального кода из проекта
- {как помогать} — желаемый стиль работы AI
Необязательно заполнять все секции. Для быстрой задачи достаточно технологий + 1-2 правила.
Адаптация под другие задачи:
Этот шаблон работает не только для кода, но для любой работы с проектным контекстом:
Для текстового проекта (статья, документация):
Я пишу {тип документа} для {аудитория}.
СТРУКТУРА ДОКУМЕНТА:
{разделы и их назначение}
СТИЛЬ И ТОН:
{формальный/неформальный, технический/популярный, примеры фраз}
ПРАВИЛА:
{что обязательно включать, чего избегать, ограничения}
ПРИМЕРЫ:
{фрагмент текста в желаемом стиле}
КАК ПОМОГАТЬ:
{генерировать сразу / сначала структуру, короткие ответы / с объяснениями}
Для аналитики/исследования:
Я анализирую {предмет исследования} для {цель}.
КОНТЕКСТ:
{что уже известно, какие данные есть}
МЕТОДЫ:
{какие подходы использую, какие метрики важны}
ОГРАНИЧЕНИЯ:
{что нельзя/незачем анализировать}
ФОРМАТ ВЫВОДОВ:
{структура ответа, уровень детализации}
Принцип один: дай AI полный контекст один раз, дальше работай в этой рамке без повторений.
Ограничения
⚠️ Ручная работа: Контекст не появится сам — его нужно сформулировать и поддерживать. Для небольшой одноразовой задачи ("исправь баг") это overhead. Окупается на проектах, где работаешь долго (недели-месяцы) или часто возвращаешься.
⚠️ Отсутствие памяти между сессиями: ChatGPT/Claude не сохраняют контекст между отдельными чатами. Начал новый чат — придётся инициализировать заново. Решение: храни шаблон в заметках, копируй в начале каждой новой сессии. Или используй один длинный чат для всего проекта (но это свои минусы — контекст засоряется).
⚠️ Риск устаревания: Проект меняется — технологии обновляются, соглашения эволюционируют, архитектура перестраивается. Контекст в начале сессии может отстать от реальности. Нужно периодически пересматривать и обновлять описание.
⚠️ Не заменяет конкретные инструкции: Даже с полным контекстом проекта, для конкретной задачи всё равно нужен конкретный промпт. Контекст — это фундамент, не решение каждой задачи. "Вот наш стек" + "напиши API endpoint для логина" → хороший результат. Только "вот наш стек" без задачи → AI не поймёт что делать.
Как исследовали
Команда из University of California собрала 401 опенсорсный репозиторий с cursor rules (.mdc файлами) через Sourcegraph — поисковик по всем публичным GitHub-проектам. Исключили форки, архивные проекты и неанглоязычные репозитории. В итоге проанализировали 1,876 файлов с правилами из реальных проектов, от небольших личных до крупных корпоративных (самый большой — 12.63 GB кода).
Методология была качественной: два исследователя вручную прочитали и закодировали правила из 30 репозиториев (по 3 из каждого популярного домена: AI, TypeScript, Java, security, ecommerce и др.). Это заняло несколько часов на репозиторий. Построчно выделяли: что именно разработчик считает важным сообщить AI. После выработки таксономии масштабировали анализ на все 401 репозиторий через LLM (Gemini 2.5 Flash) с тройным голосованием для надёжности. Согласованность с ручной разметкой — substantial (Cohen's Kappa = 0.64-0.65).
Главные находки из количественного анализа:
- 72.57% репозиториев включали описание проекта (архитектура, технологии)
- Соглашения о стиле кода — самая частая категория в многих доменах
- Прямые директивы LLM ("отвечай кратко", "проверяй типы") встречались в 43% проектов
- Примеры кода давали реже — только 28% (возможно, сложно поддерживать актуальность)
Интересно: разработчики адаптируют традиционную документацию под AI. Много элементов из cursor rules дублируют README, CONTRIBUTING.md, style guides. Но появились и уникальные для AI паттерны — метаинструкции про формат ответа, про то как проверять и рассуждать. Это не для людей, это prompt engineering на уровне проекта.
Исследование показало: проекты на разных языках фокусируются на разном. TypeScript-проекты больше про соглашения и стиль, Python — про архитектуру и практики разработки, Go — про производительность и паттерны конкурентности. Это логично — контекст отражает специфику экосистемы языка.
Ресурсы
An Empirical Study of Developer-Provided Context for AI Coding Assistants in Open-Source Projects Shaokang Jiang, Daye Nam (University of California, Irvine)
Анонимный репозиторий с полным датасетом: https://anonymous.4open.science/r/cursorrule-supp-110E
Связанные ресурсы: - Cursor IDE и cursor rules: https://cursor.sh - GitHub Copilot custom instructions - Awesome Cursor Rules (коллекция примеров): https://github.com/PatrickJS/awesome-cursorrules - Reddit-обсуждение: https://www.reddit.com/r/cursor/comments/1ju63ig/the_one_golden_cursor_rule_that_improved/