Как дать Cursor контекст кодовой базы: @Code, @File, @Folder и .cursorignore

Контекст Cursor — это сведения, которые AI получает вместе с вашей задачей: код, файлы, структура проекта, ошибка, документация и ограничения. Начните с автоматического контекста, а затем добавляйте точные ссылки через @Code, @File и @Folder. Ненужные и чувствительные пути исключайте через .cursorignore, но не считайте его полной защитой от доступа терминала и MCP-инструментов.

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

Это действие и критерий результата:

Добавь проверку ответа API и сохрани текущий публичный интерфейс.

Это конкретная информация, на которой нужно основывать решение:

Ошибка возникает при пустом поле email. Текущий обработчик находится
в auth/validate.ts, тесты — в auth/validate.test.ts.

Если дать только намерение, AI будет угадывать архитектуру. Если дать только состояние, он может не понять, что именно должно измениться. Объединяйте цель, файлы, ограничения и проверку.

Cursor может сам искать релевантные участки кодовой базы, учитывать текущий файл и предыдущие сообщения. Это удобно, когда задача типовая и проект небольшой. Но автоматический подбор не гарантирует, что будет выбран именно тот модуль, который вы считаете главным.

Признаки, что контекст нужно уточнить:

В таких случаях добавьте явные @-ссылки и попросите сначала перечислить использованный контекст.

@Code подходит, когда вы знаете имя функции, класса, типа или другого символа, но не хотите прикладывать весь файл. Это хороший выбор для вопроса о контракте или поведении одной сущности.

Пример:

@Code validateOrder
Объясни, какие состояния она принимает и где формируется ошибка.
Не меняй код.

Плюс такого подхода — точность. Минус — нужно знать имя символа и понимать, не зависит ли он от соседних типов или констант. Если зависимостей много, добавьте файл с реализацией и тест.

Используйте @File, когда важно прочитать целый модуль: компонент, обработчик, конфигурацию или тест. Это удобно, если вы знаете путь, но не уверены, какой именно фрагмент важен.

Пример:

@File app/api/orders/route.ts
Найди путь обработки ошибки оплаты и перечисли все внешние вызовы.
Не вноси изменения.

Для длинных файлов уточните, какой раздел нужно разобрать. Целый большой модуль может добавить много нерелевантного контекста.

@Folder подходит, когда задача затрагивает каталог или несколько тесно связанных файлов. Cursor получает путь и обзор содержимого; в настройках может быть доступен режим полного содержимого папки. На больших каталогах это увеличивает объём контекста, поэтому включайте полный режим только при понятной необходимости.

Пример:

@Folder components/checkout
Опиши, где находятся форма, валидация и запрос API.
Предложи минимальный план изменения без редактирования.

Для монорепозитория лучше начать с узкой папки, а не прикладывать весь src.

В зависимости от текущего режима и версии Cursor могут быть доступны ссылки на документацию, Git-изменения, веб-страницы и правила проекта. Смысл один: передать AI источник, который вы хотите обсуждать, вместо длинной ручной вставки.

Если нужно объяснить библиотечный API, лучше добавить официальную документацию и указать версию зависимости. Если нужно понять регрессию, приложите diff и тест, который падает.

Создайте в корне проекта файл .cursorignore в формате, близком к .gitignore:

# Секреты и учётные данные
**/.env
**/.env.*
**/credentials.json
**/*.pem
**/*.key

# Сгенерированные и тяжёлые каталоги
node_modules/
.next/
dist/
coverage/
**/*.log

Официальная справка Cursor по ignore-файлу указывает, что .cursorignore ограничивает доступ к перечисленным путям для Agent, Tab, Inline Edit и @-ссылок. Одновременно она предупреждает: терминал и MCP-серверы Agent не блокируются этим файлом.

Поэтому .cursorignore не заменяет:

Используйте шаблон:

Цель: [что должно измениться]
Контекст: @File ... @Code ... @Folder ...
Ограничения: [что нельзя менять]
Критерий готовности: [какая проверка должна пройти]
Сначала: [объясни / составь план / предложи diff]

Пример для отладки:

Цель: найти причину 500 при пустом customerId.
Контекст: @File app/api/orders/route.ts @File lib/orders.ts
Ограничения: не менять схему базы и публичный ответ успешного запроса.
Критерий готовности: добавить регрессионный тест и запустить текущую проверку.
Сначала объясни цепочку вызовов, без правок.

Большой объём не равен хорошему контексту. Начните с точки входа и ближайших зависимостей.

Запрос «перепиши авторизацию, обнови дизайн и исправь CI» сложно проверить. Разделите его на этапы.

Если в конфигурации есть ключи, замените их на плейсхолдеры и опишите форму данных.

Переданный файл — это источник информации, а не автоматическое разрешение его изменять. В запросе явно указывайте, что можно редактировать.

Контекст одного запроса — краткосрочный. Если инструкция должна применяться к проекту постоянно, вынесите её в Rules или AGENTS.md. Если нужно поручить задачу на несколько файлов, используйте Agent. Полное объяснение этих режимов — в гайде по работе с Cursor и статье про Cursor Rules.

Недостаток контекста заметен не только по ошибке в коде. Cursor может:

В такой ситуации не добавляйте сразу весь репозиторий. Сначала попросите назвать предположения, затем приложите один источник, который их проверяет: @File, @Code, тест, лог или документацию.

Передайте @Code функции, @File с тестами и опишите неизменяемый публичный контракт.

Добавьте маршрут, сервис, тип ответа, текст ошибки и шаг воспроизведения. Не прикладывайте .env и реальные токены.

Передайте компонент, родительский layout, существующий похожий компонент и скриншот или описание состояния. Укажите, какие стили нельзя менять глобально.

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

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

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

Помните о трёх разных задачах:

Они не взаимозаменяемы. Проверьте каждый слой отдельно и не кладите секреты в проект в открытом виде «потому что файл исключён».

После крупного рефакторинга старые сообщения могут содержать устаревшие предположения. Начните новый запрос с короткого описания текущего состояния, приложите свежий diff и попросите перечитать канонические файлы. Это полезнее, чем продолжать длинную цепочку, где Cursor уже опирается на старую структуру.

@Code — для конкретного символа. @File — когда важен весь модуль или вы не знаете, какой фрагмент внутри него определяет поведение.

Когда задача относится к каталогу и нескольким связанным файлам. Начинайте с узкой папки, чтобы не добавлять лишний контекст.

Обычные AI-контекстные функции должны исключать перечисленные пути, но терминал и MCP-инструменты имеют отдельные правила доступа. Не храните секреты в рабочем окружении без дополнительной защиты.

Нет. Автоматического контекста часто достаточно для простых задач. Явные @-ссылки нужны, когда важно направить поиск или исключить ошибочную интерпретацию.

Попросите Cursor перечислить файлы и символы, на которых основан ответ, затем сравните их с задачей.

Да, если текущий режим поддерживает ссылку на документацию или веб-страницу. Используйте первичный источник и укажите версию библиотеки или продукта.