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

# Slash-команды в Cursor

## Цель

Научиться вызывать встроенные и пользовательские slash-команды в Cursor, понимать формат файлов в `.cursor/commands/` и безопасно применять их в Agent и Chat.

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

- Cursor IDE установлен и открыт учебный репозиторий
- Базовое понимание [Agent vs Chat](../06-agents/README.md) (раздел 06)
- Права на создание папки `.cursor/commands/` в проекте

## Время

~45–60 минут.

---

## Что такое slash-команда

В поле ввода чата или Composer символ **`/`** открывает **палитру команд**. Каждая команда подставляет в контекст агента заранее написанный текст — инструкции, чеклисты, ссылки на файлы.

**Ментальная модель:** команда = «макрос промпта», который вы не переписываете вручную.

---

## Встроенные возможности Cursor

Помимо пользовательских `.md`-файлов, Cursor предлагает системные действия через `/`:

| Категория | Примеры (названия могут меняться в версиях) |
|-----------|---------------------------------------------|
| Контекст | Прикрепление файлов, папок, документации |
| Режимы | Переключение Plan / Agent / Ask |
| Редактор | Быстрые операции с выделением (зависит от версии) |

> **Важно:** точный список встроенных пунктов зависит от версии Cursor. Всегда смотрите актуальную палитру после ввода `/`.

Пользовательские команды из `.cursor/commands/` **дополняют**, а не заменяют встроенные.

---

## Файловая структура проектной команды

```
my-project/
└── .cursor/
    └── commands/
        ├── explain-diff.md
        └── add-tests.md
```

### Минимальный шаблон

```markdown
---
description: Объясни diff текущей ветки простым языком
---

Прочитай `git diff` относительно main.

Выдай:
1. Список изменённых файлов по смыслу (не по алфавиту)
2. Риски регрессии
3. Что стоит протестировать вручную

Пиши по-русски, без жаргона. Не коммить и не пушь.
```

### Поля frontmatter

| Поле | Обязательно | Назначение |
|------|-------------|------------|
| `description` | Да | Короткая строка в палитре `/` |
| Другие поля | Нет | Зависят от версии Cursor; держите файлы простыми |

Имя файла (`explain-diff.md`) задаёт имя команды: `/explain-diff`.

---

## Как вызвать команду

1. Откройте **Agent** (Composer) или **Chat**.
2. Введите `/` — появится список.
3. Начните печатать имя или выберите из списка.
4. При необходимости **допишите** текст после команды — аргументы в свободной форме.

Пример:

```text
/explain-diff только для пакета auth
```

Агент получит: тело `explain-diff.md` + ваше уточнение.

---

## Command vs @-упоминания

| Механизм | Что добавляет |
|----------|---------------|
| `/команда` | Инструкцию-сценарий из `.cursor/commands/` |
| `@file.ts` | Содержимое или ссылку на конкретный файл |
| `@.cursor/rules/` | Правила проекта |
| `@skill-name` | Навык (если настроен в skills) |

**Лучшая практика:** команда описывает *процесс*, `@` — *контекст*.

```text
/code-review @src/auth/login.ts фокус на SQL-инъекции
```

---

## Где хранить команды: проект vs пользователь

| Уровень | Путь (типично) | Когда |
|---------|----------------|-------|
| Проект | `.cursor/commands/` | Команды для команды, CI, стека репозитория |
| Пользователь | Глобальная конфигурация Cursor | Личные макросы для всех проектов |

Для учебных и open-source репозиториев предпочтителен **проектный** уровень — команды версионируются в Git.

---

## Безопасность

- **Не вставляйте** API-ключи, пароли, внутренние URL в тела команд.
- Явно пишите «не выполняй destructive git» для review-команд.
- Для команд, запускающих shell, укажите allowlist действий.

Плохо:

```markdown
Используй ключ sk-live-XXXX…
```

Хорошо:

```markdown
Читай API_KEY из переменных окружения. Если ключа нет — остановись и сообщи.
```

---

## Отладка: команда не появляется

| Симптом | Проверка |
|---------|----------|
| Нет в списке `/` | Файл в `.cursor/commands/`? Расширение `.md`? |
| Старая версия текста | Перезапустите окно Cursor (Reload Window) |
| Пустое описание | Заполнен ли `description` в frontmatter? |
| Конфликт имён | Два файла с одинаковым базовым именем |

---

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

1. Создайте `.cursor/commands/hello-lab.md` с `description` и телом на 5 строк.
2. Вызовите `/hello-lab` в Agent.
3. Измените тело — снова вызовите и убедитесь, что агент следует новой версии.

---

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

1. Из какой папки Cursor читает пользовательские команды?
2. Как передать команде дополнительный контекст одной строкой?
3. Почему секреты не должны быть в теле команды?
4. Чем `/команда` отличается от `@файл`?

---

## Дальше

→ [Команды ECC](ecc-commands.md)  
← [Оглавление раздела 07](README.md)