Зачем это нужно#

Представьте, что вы наняли помощника для работы с кодом. Хуки — это как инструкции, которые вы оставляете этому помощнику: «Перед тем как удалить файл — проверь дважды», «После каждого изменения — убедись, что ничего не сломалось».

Хук (от англ. hook — «крючок») — это скрипт или инструкция, которая автоматически запускается в определённый момент работы Claude Code. Хуки позволяют:

• 🛡️ Блокировать опасные команды (например, удаление важных файлов)
• ✅ Проверять код перед сохранением
• 📋 Добавлять контекст в начале сессии
• 🔍 Контролировать качество работы

Когда срабатывают хуки#

Claude Code поддерживает несколько событий (моментов), к которым можно «прицепить» хук:

Два типа хуков#

1. Командные хуки (command)#

Запускают скрипт (программу). Подходят для быстрых, точных проверок:

{
  "type": "command",
  "command": "bash ./scripts/check.sh",
  "timeout": 10
}

2. Промпт-хуки (prompt) — рекомендуемый вариант#

Используют ИИ для анализа ситуации. Подходят для сложных проверок:

{
  "type": "prompt",
  "prompt": "Проверь, безопасна ли эта операция с файлом. Верни 'approve' или 'deny'.",
  "timeout": 30
}

Пошаговая инструкция: настройка хуков#

Шаг 1: Где хранятся хуки#

Хуки можно настроить в двух местах:

• В настройках пользователя — файл .claude/settings.json (действует для всех проектов)
• В плагине — файл hooks/hooks.json внутри папки плагина

Шаг 2: Создаём простой хук — блокировка опасных команд#

Создайте файл .claude/settings.json в вашем проекте:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/block-rm.sh"
          }
        ]
      }
    ]
  }
}

Теперь создайте скрипт .claude/hooks/block-rm.sh:

#!/bin/bash
# Читаем данные о команде, которую хочет выполнить Claude
COMMAND=$(cat | jq -r '.tool_input.command')

# Если команда содержит rm -rf — блокируем!
if echo "$COMMAND" | grep -q 'rm -rf'; then
  echo '{"hookSpecificOutput": {"permissionDecision": "deny", "permissionDecisionReason": "Опасная команда rm -rf заблокирована хуком"}}' 
else
  exit 0  # Всё в порядке, разрешаем
fi

Шаг 3: Хук безопасности из плагина security-guidance#

Плагин security-guidance содержит хук, который напоминает о безопасности при редактировании файлов:

{
  "description": "Security reminder hook",
  "hooks": {
    "PreToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/security_reminder_hook.py"
          }
        ],
        "matcher": "Edit|Write|MultiEdit"
      }
    ]
  }
}

Обратите внимание:

• matcher — фильтр: хук сработает только для операций Edit, Write или MultiEdit
• ${CLAUDE_PLUGIN_ROOT} — переменная, которая указывает на папку плагина (используйте её всегда для переносимости)

Шаг 4: Хуки из плагина Hookify#

Плагин Hookify — это мощный инструмент, который позволяет создавать хуки через простые .local.md файлы. Вот пример блокировки опасной команды rm:

---
name: block-dangerous-rm
enabled: true
event: bash
pattern: rm\s+-rf
action: block
---

⚠️ **Опасная команда rm обнаружена!**

Эта команда может удалить важные файлы. Пожалуйста:
- Проверьте, что путь указан правильно
- Рассмотрите более безопасный вариант
- Убедитесь, что у вас есть резервная копия

А вот пример хука, который требует запуск тестов перед завершением:

---
name: require-tests-run
enabled: false
event: stop
action: block
conditions:
  - field: transcript
    operator: not_contains
    pattern: npm test|pytest|cargo test
---

**Тесты не обнаружены!**

Перед завершением запустите тесты, чтобы убедиться, что изменения работают.

Hookify перехватывает все основные события: PreToolUse, PostToolUse, Stop, UserPromptSubmit.

Матчеры (Matchers) — фильтры для хуков#

Матчер — это фильтр, который определяет, когда именно сработает хук:

"matcher": "Write"           // Только для записи файлов
"matcher": "Read|Write|Edit" // Для чтения, записи и редактирования
"matcher": "Bash"            // Только для bash-команд
"matcher": "*"               // Для всех операций
"matcher": "mcp__.*"         // Для всех MCP-инструментов

Важно помнить#

⚠️ Хуки загружаются при старте сессии. Если вы изменили хук, нужно перезапустить Claude Code, чтобы изменения вступили в силу.

Для отладки используйте:

claude --debug

Проверить загруженные хуки можно командой /hooks внутри Claude Code.

Итоги урока#

• Хуки — это автоматические скрипты, которые срабатывают в определённые моменты работы Claude Code
• Существуют командные (скрипты) и промпт-хуки (на основе ИИ)
• Хуки позволяют блокировать опасные операции, проверять качество кода и добавлять контекст
• Матчеры фильтруют, для каких инструментов сработает хук
• Плагин Hookify позволяет создавать хуки через простые Markdown-файлы
• Всегда используйте ${CLAUDE_PLUGIN_ROOT} для путей в плагинах