Хуки: автоматизация без вашего участия
📖 Теория
Хуки в 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"
📝 Домашнее задание
- SessionStart Hook: Создайте SessionStart hook, который автоматически загружает .env, проверяет git статус и выводит project-specific контекст.
- Safety Hook: Реализуйте BeforeToolCall hook, который блокирует опасные bash команды (rm -rf /, dd, mkfs) и требует подтверждения для изменения защищённых файлов (.env, package.json).
- Testing Hook: Создайте AfterToolCall hook, который автоматически запускает тесты после изменения исходного кода.
- Custom Commands: Создайте три пользовательские slash-команды для вашего проекта: /deploy, /test, /setup.
- Logging System: Реализуйте систему логирования всех tool calls в .claude/hooks/audit.log с timestamp, tool name и параметрами.
- Hook Manager: Доработайте HooksManager класс: добавьте priority для hooks, retry логику при временных ошибках, метрики производительности.
- 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
🔗 Дополнительные ресурсы
Рекомендуемые курсы
Продолжите обучение по смежным темам
ИИ-наставник по этому уроку
Задайте вопрос по теме урока «Хуки: автоматизация без вашего участия» — наставник ответит, опираясь на его содержание. Он помогает понять, но не делает домашку за вас.