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

# Создание своей slash-команды

## Цель

Самостоятельно спроектировать, записать и отладить пользовательскую команду в `.cursor/commands/`, согласованную с rules и skills проекта.

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

- [slash-commands-cursor.md](slash-commands-cursor.md)
- В проекте есть хотя бы одно [rule](../04-rules/README.md) (раздел 04)
- Учебный репозиторий под Git

## Время

~60 минут (включая тест на агенте).

---

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

Создавайте команду, если **третий раз подряд** пишете один и тот же промпт:

| Признак | Решение |
|---------|---------|
| Одинаковые шаги review | Команда `/my-review` |
| Сложная ветвящаяся логика | Лучше [skill](../05-skills/README.md) |
| Всегда применимо | [Rule](../04-rules/README.md) |
| Реакция на сохранение файла | [Hook](../08-hooks/README.md) |

---

## Проектирование (до кода)

Заполните шаблон на бумаге:

```text
Имя:            release-notes
Триггер:        перед релизом
Вход:           диапазон коммитов или ветка
Выход:          CHANGELOG-блок на русском
Запреты:        не пушить, не менять версию без запроса
Связь:          rule common-git-workflow
```

Имя файла: `release-notes.md` → команда `/release-notes`.

---

## Пошаговое создание

### Шаг 1 — каталог

```bash
mkdir -p .cursor/commands
```

### Шаг 2 — файл

`.cursor/commands/release-notes.md`:

```markdown
---
description: Черновик release notes из git log (без пуша)
---

## Задача

Сформируй черновик release notes для пользователей (не для разработчиков).

## Вход

Пользователь может указать ветку или тег после команды.
По умолчанию: коммиты от последнего тега до HEAD.

## Шаги

1. Выполни `git log` с нужным диапазоном (oneline + merge commits).
2. Сгруппируй изменения: Features, Fixes, Breaking.
3. Игнорируй chore/docs, если нет влияния на пользователя.
4. Выведи Markdown-блок для вставки в CHANGELOG.

## Ограничения

- Не создавай коммиты и теги.
- Не выдумывай изменения — только факты из git.
- Язык: русский.

## Формат ответа

### Features
- …

### Fixes
- …
```

### Шаг 3 — проверка в Cursor

1. Reload Window (если команда не видна).
2. `/release-notes с последнего тега v0.1.0`
3. Сверьте вывод с `git log` вручную.

### Шаг 4 — итерация

Если агент «забывает» шаги — добавьте нумерованный чеклист и секцию **«Остановись, если»**.

---

## Паттерны качественных команд

### Явный scope

```markdown
Работай только в каталоге `internal/api/`.
Не трогай `vendor/` и `*_generated.go`.
```

### Ссылка на rule, не дублирование

```markdown
Соблюдай правила из @.cursor/rules/common-security.mdc
```

### Критерий готовности

```markdown
Считай задачу выполненной, когда:
- [ ] все тесты `go test ./...` зелёные
- [ ] нет новых linter warnings
```

### Эскалация

```markdown
Если нужен доступ к секретам или прод-БД — остановись и спроси пользователя.
```

---

## Версионирование и команда

Добавьте команды в Git:

```bash
git add .cursor/commands/release-notes.md
git commit -m "docs: add release-notes slash command for agent"
```

В PR опишите: зачем команда, кто целевой пользователь.

---

## Антипаттерны

| Плохо | Почему | Лучше |
|-------|--------|-------|
| 500 строк в одной команде | Тяжёлый контекст, путаница | Skill + короткая команда-обёртка |
| «Сделай всё идеально» | Нет критериев | Чеклист и Definition of Done |
| Дублирование ECC `/plan` | Два источника правды | Вызов `/plan` или ссылка на skill |
| Секреты в теле | Утечка через Git | Env + rule о секретах |

---

## Лабораторная мини-задача

Создайте команду `/branch-summary`:

- читает текущую ветку и `git diff main...HEAD`;
- выдаёт 5 пунктов: что сделано, риски, что тестировать;
- явный запрет на `git push`.

Прогоните на feature-ветке с 2–3 коммитами.

---

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

1. Какие поля обязательны в frontmatter?
2. Когда команда хуже, чем skill?
3. Как связать команду с rule через `@`?
4. Что сделать, если команда не появляется в палитре?

---

## Дальше

→ Раздел [08 — Hooks](../08-hooks/README.md)  
← [Команды ECC](ecc-commands.md)