Коротко
Качество ответа Cursor почти всегда упирается не в «магию модели», а в контекст. Символы @ в чате/Composer — способ явно сказать: смотри этот файл, весь репозиторий, доки или веб.
Запросы вроде «cursor @codebase», «как добавить файл в контекст cursor» — сюда.
Зачем явный контекст
Без @ модель видит:
- открытый файл / выделение;
- часть недавней переписки;
- иногда куски индекса.
С @ вы фиксируете источник правды. Это снижает выдуманные API и правки «не в тот файл».
Основные @-символы
| Символ | Что даёт | Когда |
|---|---|---|
@filename | конкретный файл | точечный баг, ревью функции |
@folder | папка | модуль/feature целиком |
@codebase | поиск по индексу репо | «где у нас auth?», сквозные вопросы |
@docs | подключённая документация | внешние API, внутренние гайды |
@web | свежий веб-поиск | изменения API, версии пакетов |
@git (если доступно) | diff/ветка | ревью PR, откат |
Названия и набор зависят от версии Cursor — смотрите подсказки при вводе @ в чате.
Паттерны хороших промптов
Плохо: «Почини авторизацию.»
Лучше:
@src/auth/session.ts @src/middleware.ts
Почини проверку сессии: сейчас 401 на /api/me после логина.
Не трогай UI. Добавь тест, если есть папка tests/auth.
Для исследования:
@codebase
Где задаётся rate limit для API? Покажи файлы и кратко схему.
Пока без правок кода.
Для внешней доки:
@docs Next.js App Router
Как правильно сделать server action для формы логина в нашем @app/login/page.tsx?
@codebase: сильные и слабые стороны
Сильно: найти место, собрать карту модуля, ответить «как устроено».
Слабо: если индекс устарел, репо гигантское или важные пути в .cursorignore.
Практика:
- Сначала
@codebase+ «только объясни». - Потом точечные
@file+ «внеси правки». - После больших изменений — новая индексация / перезапуск при странностях.
Подробнее про ignore: .cursorignore и индексация.
Контекст и Rules
@ — разовый контекст. Rules — постоянный. Держите в rules стек, стиль, запреты; в @ — файлы текущей задачи.
См. правила и агенты и полное руководство по Rules.
Частые ошибки
- Кидать весь
@codebaseна мелкий фикс — шум и расход usage. - Не давать тест/контракт — агент «угадывает» поведение.
- Забывать
@web, когда пакет обновился (ломающие изменения). - Просить правки без списка файлов — дифф уезжает не туда.
Чеклист перед Agent
- Есть 1–3 ключевых
@fileили папка - Сформулирован критерий готово
- Указано, что не трогать
- При необходимости
@docs/@web - Понимаете лимит usage — гайд
Примеры плохих и хороших связок @
Плохо: @codebase сделай авторизацию как в Amazon.
Слишком широко, нет критерия, агент фантазирует.
Лучше:
@src/auth @tests/auth + «добавь refresh token по образцу session.ts, тесты зелёные, UI не трогать».
Плохо: кинуть 15 файлов «на всякий случай».
Лучше: 2–3 файла + один эталонный тест.
Контекст и стоимость
Каждый лишний кусок контекста увеличивает расход на премиум-моделях. Если задача локальная — не вызывайте @codebase. Если исследовательская — сначала @codebase без правок, потом точечные файлы. См. лимиты.
Документация проекта как @docs
Положите в репо docs/architecture.md и подключите как docs (или просто @docs/architecture.md через файл). Это дешевле, чем каждый раз пересказывать архитектуру в чате, и стабильнее Rules для длинных описаний.
Практический мини-кейс
- Возьмите реальный небольшой баг или задачу из вашего бэклога (30–60 минут работы руками).
- Сначала решите её без Agent — только Tab/Chat, чтобы почувствовать потолок.
- Затем откатите изменения в git и решите с Agent и явным
@контекстом. - Сравните: время, качество diff, сколько usage ушло, сколько правок пришлось откатить.
- Зафиксируйте в Rules команды 2–3 правила, которые сэкономили больше всего времени.
Такой прогон один раз калибрует ожидания лучше любой теории.
FAQ
Чем @codebase отличается от открытия всех файлов?
Индекс ищет релевантные куски. Это не «загрузить репо целиком в промпт».
Можно ли без @?
Да, на маленьких задачах. На средних и больших явный контекст стабильнее.
@docs — это интернет?
Обычно — добавленные вами источники/доки. Для интернета — @web, если доступен.