← [Раздел](README.md) · [Главная](../README.md)

# @-упоминания и переменные контекста

## Цель

Уверенно использовать **`@` mentions** в Cursor для точечной подачи файлов, папок, документации и правил; понимать встроенные переменные и избегать утечки лишнего контекста.

## Предварительно

- [templates-i-snippets.md](templates-i-snippets.md)
- Учебный проект с несколькими файлами и `.cursor/rules/`

## Время

~45–60 минут.

---

## Синтаксис @ в Cursor

В поле промпта символ **`@`** открывает меню **контекстных вложений**:

| Тип | Пример | Что попадает в контекст |
|-----|--------|-------------------------|
| Файл | `@src/main.go` | Содержимое или индексированная ссылка |
| Папка | `@internal/auth/` | Обзор файлов папки (зависит от настроек) |
| Codebase | `@Codebase` | Семантический поиск по репо |
| Docs | `@Docs` | Подключённая документация |
| Web | `@Web` | Поиск в интернете (если включено) |
| Git | `@Git` | Diff, коммиты |
| Rules | `@.cursor/rules/common-security.mdc` | Текст правила |
| Notepad | `@Notepad` | Личные заметки |

Точный набор пунктов меню зависит от версии Cursor.

---

## Когда что прикреплять

```text
Задача: исправить функцию в одном файле     → @конкретный-файл
Задача: найти, где используется тип         → @Codebase + уточнение
Задача: свериться с OWASP в docs            → @Docs или MCP Context7
Задача: стиль всего проекта                 → @rules (короткие), не весь код
```

---

## @Codebase — осторожно

`@Codebase` запускает **поиск по репозиторию**. Плюс: не нужно знать путь. Минус:

- может принести нерелевантные файлы;
- расходует токены;
- на больших monorepo — шум.

**Лучше:** сначала узкий `@папка`, потом codebase при неудаче.

---

## @Rules

Правила из `.cursor/rules/*.mdc` часто подключаются **автоматически** по `globs` в frontmatter:

```yaml
---
description: Security guidelines
globs: "**/*.ts"
---
```

Явное `@common-security.mdc` нужно, когда:

- правило не попало по glob;
- вы тестируете новое rule;
- хотите сослаться на конкретный файл в промпте для агента.

---

## @Git

Полезные формулировки:

```text
@Git объясни diff текущей ветки к main
```

```text
@Git какие файлы менялись в последних 3 коммитах
```

Агент получает метаданные git без ручного `git log`.

---

## Переменные и «динамический» контекст

Cursor и агент **не имеют** единого стандарта `{{var}}` как в Jinja во всех режимах. Практические подходы:

| Подход | Как |
|--------|-----|
| Плейсхолдеры в шаблоне | Вы заменяете `{{BUG_ID}}` перед отправкой |
| Упоминание в тексте | «Ветка: feature/login, тикет: PROJ-42» |
| Slash-команда | Аргументы после `/cmd` |
| MCP | Актуальные данные из Tracker, DB |

Для тикетов Yandex Tracker — MCP `user-yandex-tracker` (если настроен у вас).

---

## Комбинирование @ и /

```text
/code-review @src/api/handlers.go @.cursor/rules/common-security.mdc
```

Порядок: команда задаёт процесс, `@` — материал.

---

## Контекстные ошибки новичков

| Ошибка | Последствие | Исправление |
|--------|-------------|-------------|
| @весь-backend | Переполнение окна | Одна папка или файл |
| Забыли @rule security | Уязвимый код | Явно прикрепить или проверить globs |
| Дубль: rule + тот же текст в промпте | Трата токенов | Один источник правды |
| @файл с секретами | Утечка в логи провайдера | .cursorignore, env |

---

## .cursorignore

Как `.gitignore`, но для индексации AI:

```text
.env
*.pem
secrets/
```

Файлы не попадут в `@Codebase` и автоматический контекст.

---

## Упражнение

1. Задача: «объясни функцию X» — только `@file` с функцией.
2. Задача: «где вызывается X» — `@Codebase` с именем символа.
3. Добавьте в `.cursorignore` фейковый `fake-secret.env` и убедитесь, что агент не цитирует его при поиске.

---

## Самопроверка

1. Чем `@file` отличается от `@Codebase`?
2. Когда rules подключаются сами, без @?
3. Зачем `.cursorignore`?
4. Как передать номер тикета без встроенной переменной Cursor?

---

## Дальше

→ [Functions и MCP tools](functions-i-mcp-tools.md)  
← [Шаблоны и snippets](templates-i-snippets.md)