Hooks: event, matcher і handler

Hook: event → matcher → handler

Hook — це локальна автоматизація, яка реагує на подію життєвого циклу Claude Code. На відміну від MCP, він не підключає зовнішнє джерело, а автоматично виконує локальну команду або скрипт.

Event визначає момент, matcher звужує умову, а handler виконує одну передбачувану дію.

Групи подій

• Before tool use — перевірити або заблокувати ризикову дію до запуску.
• After tool use / file changes — форматувати, перевірити або повідомити після зміни.
• Session lifecycle — показати правила, нагадування або зберегти стан сесії.

Matcher має бути вузьким

Matcher може фільтрувати шлях, тип інструмента, шаблон команди або інші підтримувані ознаки контексту. Форматуйте лише потрібні `src/**/*.ts` і `src/**/*.tsx`, а не кожен файл репозиторію.

Надто широкий matcher створює шум, зайві затримки та знижує довіру до automation.

{
  "event": "afterFileEdit",
  "matcher": {
    "paths": ["src/**/*.ts", "src/**/*.tsx"]
  },
  "handler": {
    "command": "prettier --write \{\{file\}\}"
  }
}

Один handler — одна зрозуміла дія

• formatter для зміненого файла;
• короткий guard для захищеного шляху;
• м’яка локальна перевірка;
• нагадування на початку сесії.
• Складну багатокрокову логіку виносьте в окремий script, tool або skill.

Чого hook не замінює

Hook не має планувати складну роботу, аналізувати всю кодову базу, ухвалювати бізнес-рішення, замінювати task spec, тести або human review. Не будуйте з нього прихованого оркестратора.

Проєктні hooks варто зберігати в репозиторії поруч із `CLAUDE.md`, skills і agents, щоб їх можна було переглядати в diff.