← [Главная](../README.md)

# 08 — Hooks (хуки)

## Цель

Понять систему **хуков** в Cursor/ECC: автоматические скрипты на события сессии (старт, правка файла, shell, MCP), их отличие от commands и rules.

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

- Раздел [07 — Commands](../07-commands/README.md) (команды по запросу пользователя)
- Базовый опыт с терминалом и JSON
- Учебный репозиторий (не production)

## Время

**5–8 часов** (теория + настройка 1–2 хуков + изучение ECC)

---

## Что такое hook

**Hook (хук)** — программа или скрипт, который **среда Cursor вызывает автоматически** при определённом событии, до или после действия агента.

| Механизм | Кто инициирует | Когда |
|----------|----------------|-------|
| Промпт / `/команда` | Пользователь | Вручную |
| Rule | Среда (всегда в контексте) | Каждый запрос |
| **Hook** | Среда (событие) | Старт сессии, правка файла, shell… |

**Аналогия:** rule — «дресс-код офиса»; hook — «сигнализация при открытии двери».

---

## Где настраиваются хуки

Главный файл конфигурации в проекте:

```text
.cursor/hooks.json
```

В ECC эталонный пример:

```text
/Users/nazeebod/Projects/ECC/.cursor/hooks.json
```

На workspace уровня `Projects` также может быть общий `hooks.json` — проверьте политику команды перед копированием.

---

## Оглавление раздела

| Страница | Содержание |
|----------|------------|
| [tipy-hooks.md](tipy-hooks.md) | Типы событий: sessionStart, afterFileEdit, beforeShellExecution… |
| [primery-hooks.md](primery-hooks.md) | Разбор реальных скриптов ECC и Projects |
| [hookify-i-avtomatizaciya.md](hookify-i-avtomatizaciya.md) | Hookify, continuous-learning-v2, автоматизация без боли |

---

## Зачем hooks в агентной разработке

1. **Качество** — автоформатирование и typecheck после правки файла.
2. **Безопасность** — блокировка `git commit --no-verify`, предупреждение об опасных shell-командах.
3. **Память** — сохранение контекста сессии при `sessionEnd`.
4. **Обучение** — continuous-learning-v2 наблюдает за tool use и создаёт «инстинкты».

---

## Минимальный hooks.json

```json
{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "command": "node .cursor/hooks/session-start.js",
        "event": "sessionStart",
        "description": "Загрузка контекста и проверка окружения"
      }
    ]
  }
}
```

Каждый элемент массива — один обработчик. На одно событие может быть **несколько** хуков (выполняются по порядку).

---

## Hooks vs Commands vs Skills

```text
Пользователь нажал Enter с /plan     → Command
Агент сохранил файл                  → afterFileEdit Hook
Агент читает tdd-workflow            → Skill (по релевантности)
Всегда: «не мутируй объекты»         → Rule
```

---

## Риски и дисциплина

| Риск | Митигация |
|------|-----------|
| Медленная сессия | Лёгкие хуки; тяжёлое — в CI |
| Бесконечные циклы | Не вызывать агента из hook без guard |
| Случайный блок shell | Явные сообщения пользователю |
| Секреты в логах хука | Редактирование вывода, env-only |

Начинайте с **одного** хука `sessionStart`, затем добавляйте `afterFileEdit`.

---

## Практика на 20 минут

1. Откройте `ECC/.cursor/hooks.json` — перечислите 5 типов событий.
2. Сравните с `.cursor/hooks.json` в `/Users/nazeebod/Projects/` (если есть).
3. Запишите: какой хук вы бы добавили первым в учебный проект и почему.

---

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

1. Чем hook отличается от slash-команды?
2. Где лежит конфигурация хуков в проекте?
3. Можно ли повесить несколько обработчиков на одно событие?
4. Назовите два события, связанных с shell и с файлами.

---

## Дальше

→ [Типы hooks](tipy-hooks.md)  
← [07 — Commands](../07-commands/README.md)