AICodingLab
Claude Code лайфхаки · Урок 8 из 35

Хуки: автоматизация без вашего участия

🎯 Цель урока: Познакомить вас с хуками в Claude Code, которые помогут автоматизировать рутинные задачи, такие как автоматическая отправка и принятие команд, а также создание пользовательских команд. Освоить advanced техники настройки hooks для production workflow.

📖 Теория

Хуки в Claude Code — это мощные инструменты, которые позволяют автоматизировать рутинные процессы без вашего непосредственного участия. Используя хуки, вы можете настроить автоматическую отправку (auto-submit), автоматическое принятие (auto-accept) и создать свои собственные команды (custom commands). Это существенно ускоряет рабочий процесс и позволяет сосредоточиться на более важных задачах.

Что такое Hooks в Claude Code?

Hooks (хуки) — это механизм перехвата и модификации поведения Claude Code на различных этапах выполнения:

  • SessionStart: Выполняется при запуске сессии
  • BeforeToolCall: Перед выполнением инструмента
  • AfterToolCall: После выполнения инструмента
  • BeforeResponse: Перед отправкой ответа пользователю
  • CustomCommand: Создание новых slash-команд

Архитектура Hooks

User Input
    ↓
[SessionStart Hook] ← Инициализация, загрузка контекста
    ↓
Claude Processing
    ↓
[BeforeToolCall Hook] ← Валидация, логирование, модификация
    ↓
Tool Execution (Bash, Edit, Read, etc)
    ↓
[AfterToolCall Hook] ← Постобработка результатов
    ↓
[BeforeResponse Hook] ← Форматирование ответа
    ↓
User Output

Типы хуков и их применение

1. Auto-submit Hook

Назначение: Автоматически отправляет команды без подтверждения пользователя.

Применение: CI/CD pipeline, batch processing, автоматизированное тестирование.

⚠️ Риски: Может выполнить деструктивные операции без контроля.

2. Auto-accept Hook

Назначение: Автоматически принимает предложенные изменения.

Применение: Доверенные операции, автоматический рефакторинг.

⚠️ Риски: Может принять некорректные изменения.

3. Custom Commands Hook

Назначение: Создание собственных slash-команд (например, /deploy, /test).

Применение: Стандартизация команд в команде, упрощение сложных workflow.

4. Tool Interception Hook

Назначение: Перехват и модификация вызовов инструментов.

Применение: Логирование, rate limiting, кэширование, безопасность.

Реальные примеры использования

Сценарий Hook Выгода
Автоматический код-ревью BeforeToolCall (Edit/Write) Проверка стиля кода перед сохранением
Логирование всех команд AfterToolCall (все инструменты) Аудит действий для compliance
Автотесты перед коммитом BeforeToolCall (Bash git commit) Предотвращение broken commits
Кэширование API запросов BeforeToolCall (WebFetch) Снижение стоимости API calls
Автоформатирование кода AfterToolCall (Edit/Write) Консистентный code style

🛠 Практика

Базовая настройка hooks

Шаг 1. Создайте директорию для hooks:

mkdir -p .claude/hooks
cd .claude/hooks

Шаг 2. Создайте конфигурацию hooks:

# .claude/hooks/config.json
{
  "version": "1.0",
  "hooks": {
    "sessionStart": {
      "enabled": true,
      "script": "./session-start.sh"
    },
    "beforeToolCall": {
      "enabled": true,
      "script": "./before-tool.js",
      "filters": ["Bash", "Edit", "Write"]
    },
    "afterToolCall": {
      "enabled": true,
      "script": "./after-tool.py"
    }
  },
  "settings": {
    "autoSubmit": false,
    "autoAccept": false,
    "logLevel": "info"
  }
}

Пример 1: SessionStart Hook - Автоматическая загрузка контекста

#!/bin/bash
# .claude/hooks/session-start.sh

echo "🚀 Initializing Claude session..."

# Загрузка переменных окружения
if [ -f .env.local ]; then
    export $(cat .env.local | grep -v '^#' | xargs)
    echo "✅ Environment loaded from .env.local"
fi

# Проверка Git статуса
if git rev-parse --git-dir > /dev/null 2>&1; then
    BRANCH=$(git branch --show-current)
    UNCOMMITTED=$(git status --porcelain | wc -l)
    echo "📂 Git branch: $BRANCH"
    [ $UNCOMMITTED -gt 0 ] && echo "⚠️  $UNCOMMITTED uncommitted changes"
fi

# Проверка зависимостей
if [ -f package.json ]; then
    if [ ! -d node_modules ]; then
        echo "⚠️  node_modules not found. Run: npm install"
    fi
fi

# Загрузка project-specific контекста
if [ -f .claude/context.md ]; then
    echo "📖 Project context available: .claude/context.md"
fi

echo "✨ Session ready!"

Пример 2: BeforeToolCall Hook - Валидация и безопасность

#!/usr/bin/env node
// .claude/hooks/before-tool.js

const fs = require('fs');
const path = require('path');

// Получаем информацию о вызове инструмента
const toolCall = JSON.parse(process.argv[2]);
const { tool, params } = toolCall;

console.log(`🔍 Intercepting: ${tool}`);

// Безопасность: блокируем опасные команды
if (tool === 'Bash') {
    const command = params.command;
    const dangerousPatterns = [
        /rm\s+-rf\s+\/(?!tmp|var\/tmp)/,  // rm -rf / (кроме /tmp)
        /dd\s+if=\/dev\/zero/,              // перезапись диска
        /mkfs\./,                           // форматирование диска
        /:\(\)\{\s*:\|:&\s*\};:/           // fork bomb
    ];

    for (const pattern of dangerousPatterns) {
        if (pattern.test(command)) {
            console.error(`🚨 BLOCKED: Dangerous command detected`);
            console.error(`Command: ${command}`);
            process.exit(1);
        }
    }
}

// Валидация: проверка путей для Edit/Write
if (tool === 'Edit' || tool === 'Write') {
    const filePath = params.file_path;

    // Блокируем изменение критичных файлов без подтверждения
    const protectedFiles = [
        '.env',
        'package.json',
        'Dockerfile',
        'docker-compose.yml'
    ];

    const basename = path.basename(filePath);
    if (protectedFiles.includes(basename)) {
        console.warn(`⚠️  WARNING: Modifying protected file: ${basename}`);
        console.warn(`Review changes carefully!`);
    }
}

// Логирование всех операций
const logEntry = {
    timestamp: new Date().toISOString(),
    tool: tool,
    params: params
};

fs.appendFileSync(
    '.claude/hooks/tool-calls.log',
    JSON.stringify(logEntry) + '\n'
);

console.log(`✅ Validation passed`);
process.exit(0);

Пример 3: AfterToolCall Hook - Автоматическое тестирование

#!/usr/bin/env python3
# .claude/hooks/after-tool.py

import sys
import json
import subprocess
import os

# Получаем результат вызова инструмента
tool_result = json.loads(sys.argv[1])
tool = tool_result.get('tool')
success = tool_result.get('success', False)

print(f"📊 Processing result: {tool}")

# После изменения кода - запускаем тесты
if tool in ['Edit', 'Write'] and success:
    file_path = tool_result.get('params', {}).get('file_path', '')

    # Проверяем что изменили исходный код
    code_extensions = ['.py', '.js', '.ts', '.go', '.java']
    if any(file_path.endswith(ext) for ext in code_extensions):
        print("🧪 Running tests after code change...")

        # Определяем тестовую команду
        test_cmd = None
        if os.path.exists('package.json'):
            test_cmd = 'npm test'
        elif os.path.exists('pytest.ini') or os.path.exists('setup.py'):
            test_cmd = 'pytest'
        elif os.path.exists('go.mod'):
            test_cmd = 'go test ./...'

        if test_cmd:
            result = subprocess.run(
                test_cmd,
                shell=True,
                capture_output=True,
                text=True,
                timeout=60
            )

            if result.returncode != 0:
                print("❌ Tests failed!")
                print(result.stdout)
                print(result.stderr)
                sys.exit(1)
            else:
                print("✅ Tests passed!")

# После git commit - запускаем pre-push проверки
if tool == 'Bash' and success:
    command = tool_result.get('params', {}).get('command', '')
    if 'git commit' in command:
        print("🔍 Running pre-commit checks...")

        # Линтеры
        if os.path.exists('.eslintrc.js') or os.path.exists('.eslintrc.json'):
            subprocess.run('npm run lint', shell=True)

        # Type checking
        if os.path.exists('tsconfig.json'):
            subprocess.run('npm run type-check', shell=True)

        print("✅ Pre-commit checks complete")

print("✨ Post-processing complete")
sys.exit(0)

Пример 4: Custom Commands - Создание своих slash-команд

# .claude/skills/custom-commands.md
---
name: custom-commands
description: Custom slash commands for this project
---

# Custom Commands

## /deploy
Deploy application to production

**Steps:**
1. Run tests: `npm test`
2. Build: `npm run build`
3. Deploy: `./scripts/deploy.sh production`
4. Verify: curl https://api.example.com/health

## /test
Run all tests with coverage

**Steps:**
1. Run unit tests: `npm run test:unit`
2. Run integration tests: `npm run test:integration`
3. Generate coverage report: `npm run coverage`
4. Open coverage report in browser

## /setup
Setup development environment

**Steps:**
1. Install dependencies: `npm install`
2. Copy environment: `cp .env.example .env.local`
3. Setup database: `npm run db:setup`
4. Run migrations: `npm run db:migrate`
5. Seed data: `npm run db:seed`

## /review
Code review checklist

**Steps:**
1. Run linter: `npm run lint`
2. Check types: `npm run type-check`
3. Run tests: `npm test`
4. Check bundle size: `npm run analyze`
5. Review security: `npm audit`

Production-Ready Hook System

#!/usr/bin/env python3
"""
Claude Hooks Manager - centralized hook management system
"""
import os
import json
import subprocess
import logging
from pathlib import Path
from typing import Dict, Any, Optional
from datetime import datetime

class HooksManager:
    def __init__(self, project_root: str = "."):
        self.project_root = Path(project_root)
        self.hooks_dir = self.project_root / ".claude" / "hooks"
        self.config_file = self.hooks_dir / "config.json"
        self.log_file = self.hooks_dir / "hooks.log"

        self._setup_logging()
        self._load_config()

    def _setup_logging(self):
        """Настройка логирования"""
        self.hooks_dir.mkdir(parents=True, exist_ok=True)

        logging.basicConfig(
            level=logging.INFO,
            format='%(asctime)s [%(levelname)s] %(message)s',
            handlers=[
                logging.FileHandler(self.log_file),
                logging.StreamHandler()
            ]
        )
        self.logger = logging.getLogger(__name__)

    def _load_config(self):
        """Загрузка конфигурации hooks"""
        if self.config_file.exists():
            with open(self.config_file) as f:
                self.config = json.load(f)
        else:
            self.config = self._default_config()
            self._save_config()

    def _default_config(self) -> Dict:
        """Конфигурация по умолчанию"""
        return {
            "version": "1.0",
            "hooks": {
                "sessionStart": {"enabled": False},
                "beforeToolCall": {"enabled": False, "filters": []},
                "afterToolCall": {"enabled": False}
            },
            "settings": {
                "autoSubmit": False,
                "autoAccept": False,
                "logLevel": "info",
                "timeout": 30
            }
        }

    def _save_config(self):
        """Сохранение конфигурации"""
        with open(self.config_file, 'w') as f:
            json.dump(self.config, f, indent=2)

    def execute_hook(self, hook_name: str, context: Dict[str, Any]) -> Optional[Dict]:
        """Выполнить hook"""
        hook_config = self.config["hooks"].get(hook_name, {})

        if not hook_config.get("enabled", False):
            self.logger.debug(f"Hook {hook_name} is disabled")
            return None

        script_path = hook_config.get("script")
        if not script_path:
            self.logger.warning(f"No script defined for hook {hook_name}")
            return None

        script_full_path = self.hooks_dir / script_path
        if not script_full_path.exists():
            self.logger.error(f"Hook script not found: {script_full_path}")
            return None

        self.logger.info(f"Executing hook: {hook_name}")

        try:
            result = subprocess.run(
                [str(script_full_path), json.dumps(context)],
                capture_output=True,
                text=True,
                timeout=self.config["settings"]["timeout"],
                cwd=self.project_root
            )

            if result.returncode != 0:
                self.logger.error(f"Hook {hook_name} failed:")
                self.logger.error(result.stderr)
                return {"success": False, "error": result.stderr}

            self.logger.info(f"Hook {hook_name} completed successfully")
            return {"success": True, "output": result.stdout}

        except subprocess.TimeoutExpired:
            self.logger.error(f"Hook {hook_name} timed out")
            return {"success": False, "error": "Timeout"}
        except Exception as e:
            self.logger.error(f"Hook {hook_name} error: {e}")
            return {"success": False, "error": str(e)}

    def session_start(self):
        """Hook при старте сессии"""
        return self.execute_hook("sessionStart", {
            "timestamp": datetime.now().isoformat(),
            "project_root": str(self.project_root)
        })

    def before_tool_call(self, tool: str, params: Dict) -> bool:
        """Hook перед вызовом инструмента"""
        hook_config = self.config["hooks"].get("beforeToolCall", {})
        filters = hook_config.get("filters", [])

        # Проверяем фильтры
        if filters and tool not in filters:
            return True  # Пропускаем

        result = self.execute_hook("beforeToolCall", {
            "tool": tool,
            "params": params,
            "timestamp": datetime.now().isoformat()
        })

        # Если hook вернул ошибку - блокируем выполнение
        return result is None or result.get("success", True)

    def after_tool_call(self, tool: str, params: Dict, result: Any):
        """Hook после вызова инструмента"""
        return self.execute_hook("afterToolCall", {
            "tool": tool,
            "params": params,
            "result": result,
            "timestamp": datetime.now().isoformat()
        })

    def enable_hook(self, hook_name: str, script_path: Optional[str] = None):
        """Включить hook"""
        if hook_name not in self.config["hooks"]:
            self.config["hooks"][hook_name] = {}

        self.config["hooks"][hook_name]["enabled"] = True
        if script_path:
            self.config["hooks"][hook_name]["script"] = script_path

        self._save_config()
        self.logger.info(f"Enabled hook: {hook_name}")

    def disable_hook(self, hook_name: str):
        """Выключить hook"""
        if hook_name in self.config["hooks"]:
            self.config["hooks"][hook_name]["enabled"] = False
            self._save_config()
            self.logger.info(f"Disabled hook: {hook_name}")

# Использование
if __name__ == "__main__":
    manager = HooksManager()

    # Session start
    manager.session_start()

    # Before tool call
    allowed = manager.before_tool_call("Bash", {
        "command": "git commit -m 'test'"
    })

    if allowed:
        print("✅ Tool call allowed")
        # ... выполнение инструмента ...
        manager.after_tool_call("Bash", {}, {"success": True})
    else:
        print("🚫 Tool call blocked by hook")

⚠️ Troubleshooting

Проблема 1: Hook не выполняется

Симптомы: Hook настроен, но не запускается.

Решение:

# Проверить права на выполнение
chmod +x .claude/hooks/*.sh

# Проверить конфигурацию
cat .claude/hooks/config.json

# Проверить enabled флаг
jq '.hooks.sessionStart.enabled' .claude/hooks/config.json

# Проверить логи
tail -f .claude/hooks/hooks.log

Проблема 2: Hook блокирует все команды

Симптомы: BeforeToolCall hook отклоняет все вызовы.

Решение:

# Временно отключить hook
# В .claude/hooks/config.json:
{
  "hooks": {
    "beforeToolCall": {
      "enabled": false
    }
  }
}

# Добавить debug logging в hook скрипт
echo "DEBUG: tool=$tool, params=$params" >&2

# Проверить return code (0 = success, non-zero = block)
# Убедитесь что скрипт возвращает 0 для разрешённых операций

Проблема 3: Hook выполняется слишком долго

Симптомы: Каждая команда ждёт выполнения hook.

Решение:

# Добавить timeout в config
{
  "settings": {
    "timeout": 5
  }
}

# Оптимизировать hook - использовать кэш
# Пример: кэшировать результаты lint проверок
CACHE_FILE=".claude/hooks/lint-cache.json"
FILE_HASH=$(md5sum "$file" | cut -d' ' -f1)

if grep -q "$FILE_HASH" "$CACHE_FILE"; then
    echo "✅ Using cached lint result"
    exit 0
fi

# Run lint...
echo "$FILE_HASH" >> "$CACHE_FILE"

Проблема 4: Hook ломает CI/CD

Симптомы: Pipeline падает из-за hook.

Решение:

# Отключить hooks в CI через переменную окружения
# В .claude/hooks скриптах:
if [ "$CI" = "true" ]; then
    echo "Skipping hook in CI environment"
    exit 0
fi

# Или использовать отдельную конфигурацию
if [ -f .claude/hooks/config.ci.json ]; then
    CONFIG_FILE=".claude/hooks/config.ci.json"
else
    CONFIG_FILE=".claude/hooks/config.json"
fi

Проблема 5: Hooks конфликтуют между собой

Симптомы: Несколько hooks модифицируют одни и те же данные.

Решение:

# Использовать priority в конфигурации
{
  "hooks": {
    "beforeToolCall": [
      {"script": "./security-check.sh", "priority": 1},
      {"script": "./logger.sh", "priority": 2},
      {"script": "./formatter.sh", "priority": 3}
    ]
  }
}

# Hooks выполняются по порядку priority
# Если один hook возвращает ошибку - цепочка прерывается

Проблема 6: Hook не находит зависимости

Симптомы: Hook падает с "command not found".

Решение:

# Добавить PATH в начало hook скрипта
#!/bin/bash
export PATH="/usr/local/bin:/usr/bin:/bin:$PATH"

# Или использовать абсолютные пути
/usr/bin/node .claude/hooks/before-tool.js

# Для Python hooks - использовать виртуальное окружение
#!/usr/bin/env python3
import sys
sys.path.insert(0, '/path/to/project/venv/lib/python3.9/site-packages')

Проблема 7: Hook не обновляется после изменений

Симптомы: Изменения в hook скрипте не применяются.

Решение:

# Перезапустить Claude Code session
# Hooks загружаются при старте сессии

# Проверить что скрипт не кэшируется
# Убедитесь что нет старых процессов:
ps aux | grep claude

# Убрать shebang кэш (если используется)
hash -r

# Добавить version checking в hook
HOOK_VERSION="1.2.3"
echo "Hook version: $HOOK_VERSION"

📝 Домашнее задание

  1. SessionStart Hook: Создайте SessionStart hook, который автоматически загружает .env, проверяет git статус и выводит project-specific контекст.
  2. Safety Hook: Реализуйте BeforeToolCall hook, который блокирует опасные bash команды (rm -rf /, dd, mkfs) и требует подтверждения для изменения защищённых файлов (.env, package.json).
  3. Testing Hook: Создайте AfterToolCall hook, который автоматически запускает тесты после изменения исходного кода.
  4. Custom Commands: Создайте три пользовательские slash-команды для вашего проекта: /deploy, /test, /setup.
  5. Logging System: Реализуйте систему логирования всех tool calls в .claude/hooks/audit.log с timestamp, tool name и параметрами.
  6. Hook Manager: Доработайте HooksManager класс: добавьте priority для hooks, retry логику при временных ошибках, метрики производительности.
  7. Integration: Попробуйте использовать несколько hooks вместе в одном проекте. Убедитесь что они не конфликтуют.

🎓 После урока вы умеете

  • Создавать и настраивать hooks в Claude Code
  • Использовать SessionStart hooks для автоматической инициализации
  • Реализовывать BeforeToolCall hooks для валидации и безопасности
  • Создавать AfterToolCall hooks для автоматического тестирования
  • Разрабатывать custom slash-команды для упрощения workflow
  • Строить production-ready hook management систему
  • Диагностировать и решать проблемы с hooks
  • Интегрировать hooks в CI/CD pipeline
  • Оптимизировать производительность hooks
  • Управлять приоритетами и конфликтами между hooks

🔗 Дополнительные ресурсы

Рекомендуемые курсы

Продолжите обучение по смежным темам

ИИ-наставник по этому уроку

Задайте вопрос по теме урока «Хуки: автоматизация без вашего участия» — наставник ответит, опираясь на его содержание. Он помогает понять, но не делает домашку за вас.

Привет! Я наставник по этому уроку. Спросите что угодно по теме — объясню простыми словами. 🙂
Ответы генерирует ИИ и может ошибаться — сверяйтесь с уроком.
ИИ-консультант
Помогу выбрать курс