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

# Типы hooks в Cursor

## Цель

Разобрать основные **события (events)** в `hooks.json`, понять порядок вызова «до» и «после» действий агента и выбирать правильный тип хука под задачу.

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

- [README раздела 08](README.md)
- Умение читать JSON
- Открыт эталонный файл `ECC/.cursor/hooks.json`

## Время

~45 минут.

---

## Структура hooks.json

```json
{
  "version": 1,
  "hooks": {
    "ИМЯ_СОБЫТИЯ": [
      {
        "command": "путь к скрипту",
        "event": "ИМЯ_СОБЫТИЯ",
        "description": "человекочитаемое описание"
      }
    ]
  }
}
```

- **`version`** — версия схемы (сейчас обычно `1`).
- **`hooks`** — объект: ключ = имя события, значение = массив обработчиков.
- **`command`** — исполняемая команда (часто `node .cursor/hooks/....js`).

---

## События жизненного цикла сессии

| Событие | Когда срабатывает | Типичное применение |
|---------|-------------------|---------------------|
| `sessionStart` | Начало чата/агент-сессии | Загрузка контекста, напоминания, детект стека |
| `sessionEnd` | Закрытие или сброс сессии | Сохранение заметок, оценка паттернов, метрики |

**Пример из ECC:** `session-start.js` подгружает прошлый контекст; `session-end.js` фиксирует итоги.

---

## События работы с файлами

| Событие | Когда | Применение |
|---------|-------|------------|
| `afterFileEdit` | После того как агент изменил файл | Форматирование, lint, typecheck |
| `beforeReadFile` | (если поддерживается) | Аудит доступа к чувствительным путям |

`afterFileEdit` — самый популярный хук для **качества кода**: агент написал → hook привёл файл к стандарту.

---

## События shell (терминал)

| Событие | Когда | Применение |
|---------|-------|------------|
| `beforeShellExecution` | Перед запуском команды в терминале | Блок опасных команд, напоминания |
| `afterShellExecution` | После выполнения | Логирование URL PR, разбор ошибок сборки |

**Пример:** блокировка флага `--no-verify` у git через пакет `block-no-verify` в `beforeShellExecution`.

---

## События MCP

| Событие | Когда | Применение |
|---------|-------|------------|
| `beforeMCPExecution` | Перед вызовом MCP-tool | Аудит, предупреждение о недоверенных серверах |
| `afterMCPExecution` | После вызова | Логирование, метрики |

MCP — протокол внешних инструментов (БД, Tracker, Figma). Хуки помогают **контролировать**, что агент вызывает.

---

## События инструментов агента (расширенные)

В продвинутых конфигурациях ECC и continuous-learning-v2 используются наблюдения за **PreToolUse / PostToolUse** (внутри skill, не всегда в корневом `hooks.json`). Это основа v2 обучения: надёжный захват каждого tool call.

---

## Порядок «before» и «after»

```text
sessionStart
    ↓
[пользовательский запрос]
    ↓
beforeShellExecution → shell → afterShellExecution
    ↓
beforeMCPExecution → MCP → afterMCPExecution
    ↓
[агент правит файл]
    ↓
afterFileEdit
    ↓
sessionEnd
```

**Before-хуки** могут **отменить** или изменить действие (в зависимости от API версии — проверяйте документацию Cursor для вашей сборки).

**After-хуки** — для побочных эффектов: формат, лог, уведомление.

---

## Синхронность и производительность

| Правило | Причина |
|---------|---------|
| Before-хуки — быстрые (<300 ms) | Блокируют действие агента |
| After-хуки — тяжёлые тесты лучше в CI | Иначе каждая правка = минуты ожидания |
| Идемпотентность | Повторный запуск не должен ломать дерево |

---

## Выбор типа: шпаргалка

| Задача | Событие |
|--------|---------|
| Напомнить про правила проекта при старте | `sessionStart` |
| Prettier/eslint после правок | `afterFileEdit` |
| Запрет `rm -rf /` | `beforeShellExecution` |
| Лог вызовов Stripe MCP | `beforeMCPExecution` |
| Сохранить summary в файл | `sessionEnd` |

---

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

Откройте `ECC/.cursor/hooks.json` и заполните таблицу:

| Событие | Скрипт | Одной фразой — зачем |
|---------|--------|----------------------|
| ? | session-start.js | ? |
| ? | after-file-edit.js | ? |
| … | … | … |

---

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

1. Какое событие подходит для автоформатирования?
2. Где в цепочке стоит `beforeShellExecution`?
3. Зачем нужен `sessionEnd` при обучении continuous-learning?
4. Почему тяжёлые тесты не стоит вешать на `afterFileEdit`?

---

## Дальше

→ [Примеры hooks](primery-hooks.md)  
← [Оглавление раздела 08](README.md)