Урок 4: Hooks и CLAUDE.md — Автоматизация и инструкции

Чему вы научитесь

• Что такое hooks и как они работают
• Создавать и настраивать hooks для автоматизации
• Написать CLAUDE.md файл с инструкциями проекта
• Использовать settings.json для конфигурации
• Применить best practices для документирования проекта

Что такое Hooks?

Hooks — это скрипты, которые автоматически запускаются, когда Claude выполняет определённые действия.

Думайте о hooks как о автоматических фильтрах:

flowchart LR
    A["pre-tool-use\nПроверка перед действием\n(синтаксис, безопасность)"] --> B["Выполнение\nClaude меняет файл"]
    B --> C["post-tool-use\nЛинтер, форматирование\nавтоматически"]
    C --> D["Результат\nФайл проверен и готов"]
    E["pre-commit\nПроверка перед коммитом"] --> F["git commit\nСоздание коммита"]
    F --> G["post-commit\nУведомление, деплой,\nобновление статуса"]

Типы Hooks

1. pre-tool-use (перед действием Claude)

Запускается перед выполнением операции:

Пример:
- Claude хочет удалить файл
- pre-hook проверяет: "это не критический файл?"
- Если OK → разрешить удаление
- Если NOT OK → заблокировать с объяснением

2. post-tool-use (после действия Claude)

Запускается после выполнения операции:

Пример:
- Claude создал Python файл
- post-hook запускает: python -m py_compile new_file.py
- post-hook запускает: black new_file.py (форматирование)
- Результат: файл создан и отформатирован

3. notification hooks (уведомления)

Отправляют результаты на внешние сервисы:

Пример:
- Claude завершил задачу
- Hook отправляет уведомление в Slack
- Hook создает коммит в git
- Hook обновляет статус в issue tracker

Структура: .claude/

Все конфигурационные файлы хранятся в .claude/ директории:

your-project/
├── .claude/
│   ├── settings.json          # Конфигурация hooks и моделей
│   ├── hooks/
│   │   ├── pre-lint.sh        # Проверить синтаксис перед коммитом
│   │   ├── post-format.py     # Форматировать код после изменения
│   │   └── notify-slack.sh    # Отправить уведомление
│   └── CLAUDE.md              # Инструкции для Claude (опционально)
├── src/
├── tests/
└── requirements.txt

Инициализация: /init

Команда /init создает шаблон конфигурации:

$ cd your-project
$ claude
> /init

Claude:
┌────────────────────────────────────────────────────────┐
│ Initializing Claude Code for this project...         │
│                                                       │
│ [+] Created .claude/ directory                          │
│ [+] Created CLAUDE.md template                         │
│ [+] Created settings.json template                     │
│ [+] Ready for customization                            │
│                                                       │
│ Next steps:                                          │
│ 1. Edit CLAUDE.md with project instructions          │
│ 2. Add hooks to .claude/hooks/ if needed             │
│ 3. Customize settings.json                           │
└────────────────────────────────────────────────────────┘

CLAUDE.md: Инструкции для Claude

CLAUDE.md — это файл, где вы объясняете Claude правила вашего проекта.

Зачем нужен CLAUDE.md?

Claude будет помнить эти правила на весь сеанс:

CLAUDE.md содержит:
→ Описание проекта
→ Архитектура и структура
→ Соглашения кодирования
→ Команды для тестирования и запуска
→ Правила и запреты (что Claude НЕ должен делать)
→ Рекомендуемые инструменты

Структура CLAUDE.md

# My Python Project

## Project Overview
Brief description of what the project does.
- Build status: [status badge]
- Main language: Python 3.10+
- Framework: FastAPI

## Architecture
[Short explanation of how code is organized]

### Directory Structure

src/ ├── api/ # FastAPI routes ├── models/ # Database models ├── services/ # Business logic └── utils/ # Helper functions

## Code Conventions

### Python Style
- Use type hints for all functions
- Follow PEP 8 (use black for formatting)
- Docstrings: Google style

### Naming
- Functions: snake_case
- Classes: PascalCase
- Constants: UPPER_CASE

## Testing
```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=src

Running the Project

# Start dev server
uvicorn src.main:app --reload --port 8000

# Run migrations
alembic upgrade head

Important Rules

• Never commit directly to main branch
• Never hardcode secrets or API keys
• [+] Always write tests for new features
• [+] Update CHANGELOG.md for each release
• [+] Keep docstrings up to date

Dependencies

pip install -r requirements.txt
pip install -r requirements-dev.txt  # For development

Useful Commands

• pytest - Run tests
• black src/ - Format code
• flake8 src/ - Lint code
• mypy src/ - Type checking

### Пример CLAUDE.md для реального проекта

```markdown
# Chat API Backend

## Overview
RESTful API для приложения чата, написанный на FastAPI.
- HTTP API с JWT аутентификацией
- WebSocket поддержка для real-time сообщений
- PostgreSQL база данных

## Technology Stack
- FastAPI 0.100+
- SQLAlchemy ORM
- Pydantic v2
- PostgreSQL 15
- Redis для кеширования
- Docker для deployment

## Project Structure

src/ ├── api/ │ ├── auth.py # Аутентификация и регистрация │ ├── messages.py # CRUD операции с сообщениями │ ├── users.py # Пользователи и профили │ └── ws.py # WebSocket эндпоинты ├── models/ # SQLAlchemy ORM модели ├── schemas/ # Pydantic схемы валидации ├── services/ # Бизнес-логика ├── database.py # Подключение к БД └── main.py # Точка входа приложения

## Coding Standards

### Python
- Python 3.10+ only
- Type hints everywhere (use mypy for checking)
- Use `from __future__ import annotations` in all files

### Imports
```python
# Order: standard library, third-party, local
import os
from typing import Optional

import fastapi
from sqlalchemy import create_engine

from src.models import User

Naming Conventions

• get_user() not getUser()
• class UserSchema not class user_schema
• API_KEY = ... not api_key = ...

Docstrings (Google style)

def create_message(user_id: int, content: str) -> Message:
    """Create a new message for the given user.

    Args:
        user_id: ID of the user creating the message
        content: Message content (max 500 chars)

    Returns:
        Created Message object

    Raises:
        UserNotFoundError: If user_id doesn't exist
        ValidationError: If content is empty
    """

Testing & Quality

Run Tests

# All tests with coverage
pytest --cov=src --cov-report=html

# Just unit tests
pytest tests/unit/

# Integration tests (needs DB)
pytest tests/integration/

Code Quality

# Format code
black src/ tests/

# Check style
flake8 src/

# Type checking
mypy src/

Running Locally

# 1. Setup environment
python -m venv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows

# 2. Install dependencies
pip install -r requirements-dev.txt

# 3. Setup database
docker run -e POSTGRES_PASSWORD=dev -p 5432:5432 postgres:15
alembic upgrade head

# 4. Run server
uvicorn src.main:app --reload --port 8000

Important Rules

[-] NEVER:

• Commit sensitive data (.env, secrets, API keys)
• Add to requirements.txt without testing
• Write code without type hints
• Skip tests for new features

[+] ALWAYS:

• Write tests before/alongside code
• Update docstrings when changing functions
• Check with mypy before pushing
• Review diffs carefully

## Размер и лучшие практики CLAUDE.md

В официальном руководстве [Claude Code Best Practices](https://code.claude.com/docs/en/best-practices) приведена чёткая матрица того, что усиливает работу агента в `CLAUDE.md`, а что только раздувает контекст и заставляет модель игнорировать важные правила:

| [+] Что включать в `CLAUDE.md` | [-] Что исключать из `CLAUDE.md` |
|--------------------------------|----------------------------------|
| Команды, которые Claude не угадает сам (`npm run test:unit`, нестандартные флаги сборки) | То, что агент легко поймёт по коду сам (очевидные паттерны фреймворка) |
| Исключения из стандартного код-стайла (только те правила, которые отличаются от дефолта языка) | Общие советы вроде «пиши чистый код» или «следуй PEP 8» |
| Инструкции по запуску тестов и предпочтительный раннер (`pytest tests/unit -q`) | Подробную документацию API (лучше дать ссылку на `docs/` или подключить через `@docs/api.md`) |
| Правила репозитория: именование веток (`feat/<slug>`), конвенции PR и запрет коммитов в `main` | Часто меняющуюся информацию (текущие задачи спринта, история версий) |
| Архитектурные решения и неочевидные ловушки окружения (обязательные переменные `.env`, порты, слоты деплоя) | Пофайловое перечисление всего дерева репозитория — оно быстро устаревает |

- **Держите файл коротким (до `200` строк):** если `CLAUDE.md` разрастается, запускайте `/doctor` (команда находит раздутые файлы инструкций) и выносите узкоспециализированные правила в `.claude/rules/*.md` или импортируйте через синтаксис `@path/to/file.md`.
- **Если правило нельзя нарушать ни при каких обстоятельствах — ставьте Hook, а не абзац текста.** Инструкции в `CLAUDE.md` носят рекомендательный характер (модель может ошибиться на длинном контексте), тогда как хук (`PreToolUse`, `PostToolUse` или `Stop`) выполняется детерминированно со 100%-ной гарантией.
- **Повторяющиеся сценарии выносите в Skills (`.claude/skills/<name>/SKILL.md`):** чтобы редкие инструкции (например, чеклист релиза или миграции) не занимали токены в каждой сессии, оформите их как навык с флагом `disable-model-invocation: true` и вызывайте вручную через `/skill-name`.

## settings.json: Конфигурация Hooks

Пример конфигурации (включая `Stop`-хук, который не даёт агенту завершить задачу при падающих тестах — основа автономного режима `/goal`):

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit|GitCommit",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/prevent-main.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/format-python.py"
          }
        ]
      }
    ],
    "FileChanged": [
      {
        "matcher": "src/**/*.py",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/run-tests.sh"
          }
        ]
      }
    ]
  },
  "models": {
    "default": "claude-sonnet-5-5",
    "fast": "claude-haiku-5-5"
  },
  "permissions": {
    "deny": [
      ".git/**",
      "__pycache__/**",
      "*.pyc",
      "venv/**"
    ]
  }
}

Примеры Hooks

Hook 1: Проверка линтера (Python)

Hook 2: Форматирование кода (Python)

Hook 3: Запуск тестов

#!/bin/bash
# .claude/hooks/run-tests.sh

echo "Running tests..."

pytest tests/ -v --tb=short

if [ $? -eq 0 ]; then
    echo "[+] All tests passed"
    exit 0
else
    echo "[-] Tests failed - review before proceeding"
    exit 1
fi

Попробуйте сами

Задание 1: Инициализация

cd your-project
claude
> /init

# Изучите созданные файлы
ls -la .claude/
cat .claude/CLAUDE.md
cat .claude/settings.json

Задание 2: Создание CLAUDE.md Отредактируйте .claude/CLAUDE.md:

# My Project

## Overview
[Краткое описание]

## Technology Stack
[Основные технологии]

## Project Structure
[Структура папок]

## How to Run
[Команды для запуска]

## Important Rules
[Что Claude должен помнить]

Задание 3: Настройка простого hook Создайте файл .claude/hooks/format.sh:

#!/bin/bash
echo "Formatting code..."
# Добавьте свою команду форматирования

Ключевые выводы

• Hooks автоматизируют повторяющиеся задачи (линтинг, тестирование, форматирование)
• CLAUDE.md файл содержит правила и инструкции для Claude
• /init команда инициализирует конфигурацию проекта
• settings.json управляет hooks и настройками моделей
• Хороший CLAUDE.md улучшает качество работы Claude на 50%+
• Hooks экономят время и гарантируют соответствие стандартам

Следующий урок

Урок 5: Tips and Tricks

В следующем уроке мы разберём продвинутые техники, работу с git, оптимизацию затрат и частые ошибки.