# Руководство по настройке CLAUDE.md

`CLAUDE.md` — это **файл конфигурации уровня проекта** для Claude Code. При каждом запуске Claude Code автоматически читает `CLAUDE.md` в проекте, чтобы понять архитектуру проекта, стандарты кодирования и особые соглашения, что позволяет более точно разобраться в вашем проекте.

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

Без CLAUDE.md вам, возможно, придётся снова и снова объяснять в каждом диалоге:
- «В этом проекте используется pnpm, а не npm»
- «Команда тестирования — `yarn test:unit`, а не `npm test`»
- «Все компоненты используют TypeScript, не используйте any»

Запишите эту информацию в CLAUDE.md — Claude будет автоматически читать её при каждом запуске, без необходимости повторять.

## Иерархия файлов

Claude Code читает CLAUDE.md на нескольких уровнях и объединяет их:

| Расположение | Область применения |
|------|---------|
| `~/.claude/CLAUDE.md` | Глобальная конфигурация, применяется ко всем проектам |
| `CLAUDE.md` в корне проекта | Конфигурация проекта, коммитится в Git для совместного использования командой |
| `.claude/CLAUDE.md` | Приватная конфигурация проекта, можно добавить в `.gitignore` |
| `CLAUDE.md` в подкаталогах | Читается только когда Claude находится в этом каталоге |

## Быстрое создание

Используйте команду `/init` для автоматической генерации:

```
/init
```

Claude проанализирует текущую структуру проекта и автоматически создаст CLAUDE.md с информацией о проекте.

## Базовая структура

```markdown
# Название проекта

## Обзор
Краткое описание назначения и технологического стека проекта.

## Технологический стек
- Среда выполнения: Node.js 20
- Фреймворк: Next.js 15
- Стили: Tailwind CSS
- База данных: PostgreSQL + Prisma

## Часто используемые команды
- Запуск сервера разработки: `npm run dev`
- Запуск тестов: `npm test`
- Сборка продакшн-версии: `npm run build`
- Проверка кода: `npm run lint`

## Стандарты кодирования
- Использовать TypeScript, запрещён тип `any`
- Компоненты писать в функциональном стиле
- Стили только через Tailwind, без инлайн-стилей
- Формат сообщений коммитов: префиксы `feat:` / `fix:` / `docs:` и т.д.

## Структура проекта
- `src/app/` — страницы Next.js App Router
- `src/components/` — повторно используемые компоненты
- `src/lib/` — вспомогательные функции
- `prisma/` — схема базы данных и миграции

## Важные замечания
- Не изменяйте `prisma/migrations/`, только создавайте новые миграции
- Все маршруты API находятся в `src/app/api/`
- Ресурсы изображений размещайте в `public/images/`
```

## Практические советы

### 1. Указание менеджера пакетов

```markdown
## Управление пакетами
Использовать pnpm, не использовать npm или yarn.
Установка зависимостей: `pnpm install`
Добавление зависимости: `pnpm add <имя-пакета>`
```

### 2. Описание стандартов тестирования

```markdown
## Тестирование
- Модульные тесты: `vitest`, файлы с суффиксом `.test.ts`
- E2E-тесты: `playwright`, расположены в `tests/e2e/`
- Запуск модульных тестов: `pnpm test:unit`
- Запуск E2E: `pnpm test:e2e`
- Новые функции должны содержать тесты
```

### 3. Указание запрещённых операций

```markdown
## Запрещённые операции
- Не использовать `console.log`, использовать модуль `logger` проекта
- Не изменять `package-lock.json` напрямую
- Не коммитить напрямую в ветку `main`, использовать ветки функций
```

### 4. Предоставление архитектурного контекста

```markdown
## Описание архитектуры
В проекте используется гексагональная архитектура (Hexagonal Architecture):
- `domain/` — бизнес-логика, не зависит от внешних фреймворков
- `application/` — варианты использования, координирует domain и infrastructure
- `infrastructure/` — внешние адаптеры: база данных, HTTP и т.д.
- `interfaces/` — точки входа: веб-контроллеры, CLI и т.д.
Новые функции должны следовать этой многоуровневой структуре, не вводите внешние зависимости в слой domain.
```

### 5. Ссылки на другие документы

```markdown
## Дополнительная информация
- Документация по API: `docs/api.md`
- Процесс развёртывания: `docs/deploy.md`
- Схема базы данных: `prisma/schema.prisma`
```

## Практики командной работы

### Стратегия работы с Git

```
CLAUDE.md          → коммитить в Git (общий для команды)
.claude/CLAUDE.md  → добавить в .gitignore (личная конфигурация)
```

Добавьте в `.gitignore`:

```gitignore
# Личная конфигурация Claude Code
.claude/CLAUDE.md
.claude/settings.local.json
```

### Чек-лист для код-ревью

На каждом ревью PR проверяйте:
- Обновлён ли CLAUDE.md, если добавилась новая технология?
- Обновлён ли раздел «Структура проекта», если структура изменилась?
- Обновлён ли раздел «Команды», если появилась важная команда?

### Руководство для новичков

CLAUDE.md заодно служит лучшим вводным документом по проекту:
1. Новый разработчик после clone читает CLAUDE.md и получает общую картину
2. Запускает `claude` → Claude уже знает все соглашения проекта
3. Начинает разбираться с запроса `> помоги разобраться в этом проекте`

---

## Продвинутые приёмы

### Ссылайтесь, а не встраивайте

CLAUDE.md не должен разрастаться. Для подробных документов указывайте путь, а не содержимое:

```markdown
## Архитектура
Подробное описание архитектуры: `docs/architecture.md`
Соглашения по проектированию API: `docs/api-design.md`
Схема базы данных: `prisma/schema.prisma`
```

Claude прочитает эти файлы сам, когда они понадобятся.

### Связь с AGENTS.md

| | CLAUDE.md | AGENTS.md |
|---|---|---|
| Инструмент | Claude Code | Codex CLI |
| Формат | Markdown | Markdown |
| Содержимое | 80%+ можно переиспользовать | 80%+ можно переиспользовать |

Если вы используете и Claude Code, и Codex, оба файла могут сосуществовать:
- **Общее содержимое**: технологический стек, команды, правила кода, структура проекта
- **Специфичное для инструмента**: указания Claude по `/model` и `/plan` — в CLAUDE.md; настройка approval mode для Codex — в AGENTS.md

> Подробнее — [Руководство по AGENTS.md](/docs/usage/agents-md).

### Контроль расхода контекста

Содержимое CLAUDE.md всегда находится в контексте (`/compact` его не удаляет). Рекомендации:

- **Держите общий объём в пределах 500 строк**
- Для подробных документов используйте ссылки на пути, а не встраивание
- Не пишите туда часто меняющуюся информацию (например, текущий прогресс)
- Не пишите примеры кода (Claude сам прочитает исходники)

---

## Частые ошибки и отладка

### CLAUDE.md не читается

```bash
# Проверьте, что файл лежит в корне проекта
ls -la CLAUDE.md

# Проверьте, что Claude его видит
claude
> Ты видишь CLAUDE.md? Какой технологический стек там описан?
```

### Файл слишком длинный и съедает контекст

```bash
# Проверьте количество строк
wc -l CLAUDE.md
# Больше 500 строк — сократите

# Посмотрите расход контекста
/cost
```

### У разных участников команды разное поведение

Глобальный `~/.claude/CLAUDE.md` у каждого свой. Если поведение в команде расходится, проверьте:
1. Достаточно ли конкретен CLAUDE.md в корне проекта?
2. Не переопределил ли кто-то командные правила в `.claude/CLAUDE.md`?

---

## CLAUDE.md и управление контекстом

Содержимое CLAUDE.md занимает пространство контекста. Рекомендуется:
- Держать CLAUDE.md кратким, сосредоточившись на наиболее важной информации
- Для подробной архитектурной документации указывайте в CLAUDE.md пути к файлам, а не копируйте содержимое напрямую
- В длительных сеансах CLAUDE.md всегда остаётся видимым (не удаляется командой `/compact`)

## Шаблоны проектов

Ниже приведены проверенные на практике отправные точки для CLAUDE.md под распространённые типы проектов. Скопируйте подходящий вашему стеку и адаптируйте детали.

### Шаблон 1: Фронтенд на React + TypeScript

```markdown
# MyApp Frontend

## Технологический стек
- React 19 + TypeScript 5.x
- Инструмент сборки: Vite 6
- Стили: Tailwind CSS v4 (utility-first, без инлайн-стилей)
- Управление состоянием: Zustand (глобальное), TanStack Query (серверное состояние)
- Маршрутизация: React Router v7
- Тестирование: Vitest + Testing Library + MSW

## Команды
- Разработка: `pnpm dev` (порт 3000)
- Тесты: `pnpm test` (режим watch Vitest)
- Однократный запуск: `pnpm test:run`
- Сборка: `pnpm build`
- Lint: `pnpm lint` (ESLint + Prettier)
- Проверка типов: `pnpm typecheck`

## Стандарты кодирования
- Компоненты: функциональные компоненты + Hooks, классовые компоненты запрещены
- Props: определять через `interface` (не `type`)
- Имена файлов: компоненты в PascalCase (UserProfile.tsx), утилиты в camelCase (formatDate.ts)
- Порядок импортов: React → сторонние → внутренние → стили
- Тип `any` запрещён, обязательны явные аннотации типов
- Асинхронные операции через TanStack Query, а не напрямую `useEffect` + `fetch`

## Структура проекта
- src/components/ — повторно используемые UI-компоненты
- src/pages/ — страницы маршрутов
- src/hooks/ — пользовательские Hooks
- src/api/ — обёртки API-запросов (queryFn для TanStack Query)
- src/stores/ — хранилища Zustand
- src/lib/ — вспомогательные функции
- src/types/ — глобальные определения типов

## Важные замечания
- Менеджер пакетов: pnpm (не npm и не yarn)
- Node.js 22+
- Все API-запросы проходят через src/api/client.ts (с интерсепторами)
- Изображения хранятся в public/images/, ссылаться через путь /images/
```

### Шаблон 2: Бэкенд на Python + FastAPI

```markdown
# MyApp Backend

## Технологический стек
- Python 3.12 + FastAPI
- ORM: SQLAlchemy 2.0 (async) + миграции Alembic
- База данных: PostgreSQL 16
- Кэш: Redis 7
- Тестирование: pytest + httpx + factory_boy

## Команды
- Разработка: `uvicorn app.main:app --reload --port 8000`
- Тесты: `pytest -xvs`
- Миграция: `alembic upgrade head`
- Новая миграция: `alembic revision --autogenerate -m "описание"`
- Lint: `ruff check .`
- Форматирование: `ruff format .`
- Проверка типов: `mypy app/`

## Стандарты кодирования
- Аннотации типов: все параметры функций и возвращаемые значения должны иметь type hints
- async/await: все операции ввода-вывода используют async
- Pydantic v2: схемы запросов/ответов — через Pydantic BaseModel
- Внедрение зависимостей: подключения к БД, аутентификацию и т.д. внедрять через FastAPI Depends()
- Обработка ошибок: бизнес-исключения наследуются от app.exceptions.AppError

## Структура проекта
- app/main.py — точка входа приложения
- app/api/ — маршруты (по одному файлу на ресурс)
- app/models/ — модели SQLAlchemy
- app/schemas/ — схемы Pydantic
- app/services/ — бизнес-логика
- app/core/ — конфигурация, база данных, безопасность и другие базовые модули
- tests/ — тестовые файлы (зеркалируют структуру app/)
- alembic/ — миграции базы данных

## Важные замечания
- Не изменяйте существующие файлы миграций в alembic/versions/
- Файл .env не коммитится в Git, загружается через класс Settings в app/core/config.py
- Виртуальное окружение: `python -m venv venv && source venv/bin/activate`
```

### Шаблон 3: Микросервис на Go

```markdown
# MyService

## Технологический стек
- Go 1.23
- HTTP-фреймворк: Echo v4
- База данных: PostgreSQL + sqlc (типобезопасный SQL)
- Очередь сообщений: NATS JetStream
- Контейнеризация: Docker + docker-compose

## Команды
- Запуск: `go run ./cmd/server`
- Тесты: `go test ./...`
- Сборка: `go build -o bin/server ./cmd/server`
- Генерация sqlc: `sqlc generate`
- Lint: `golangci-lint run`

## Стандарты кодирования
- Обработка ошибок: всегда проверяйте err, не игнорируйте через _
- Именование интерфейсов: интерфейсы с одним методом получают суффикс -er (Reader, Writer)
- Именование пакетов: строчные слова, без подчёркиваний
- Логирование: использовать структурированное логирование slog
- Контекст: передавать context.Context первым параметром каждой функции

## Структура проекта (стандартная раскладка Go)
- cmd/server/ — точка входа основной программы
- internal/handler/ — HTTP-обработчики
- internal/service/ — бизнес-логика
- internal/repository/ — слой доступа к данным
- internal/model/ — модели данных
- sql/ — файлы SQL-запросов (используются sqlc)
```

### Шаблон 4: Monorepo (Turborepo)

```markdown
# MyPlatform Monorepo

## Технологический стек
- Управление пакетами: pnpm workspace
- Система сборки: Turborepo
- Язык: TypeScript на всём стеке

## Команды
- Глобальная разработка: `pnpm dev`
- Глобальные тесты: `pnpm test`
- Глобальная сборка: `pnpm build`
- Разработка одного пакета: `pnpm --filter @myplatform/web dev`
- Добавление зависимости: `pnpm --filter @myplatform/api add express`

## Структура пакетов
- apps/web/ — фронтенд на Next.js
- apps/api/ — бэкенд на Express
- apps/admin/ — административная панель
- packages/ui/ — общая библиотека UI-компонентов
- packages/config/ — общая конфигурация (eslint, tsconfig)
- packages/types/ — общие определения типов

## Важные замечания
- Общий код размещать в packages/; не импортировать напрямую между apps
- При создании нового пакета следуйте формату packages/ui/package.json
- Кэш Turborepo: артефакты сборки кэшируются в node_modules/.cache/turbo
```

### Шаблон 5: Data Science / ML-проект

```markdown
# ML Pipeline

## Технологический стек
- Python 3.12
- Фреймворк: PyTorch 2.5 + Lightning
- Обработка данных: Polars (не Pandas)
- Отслеживание экспериментов: MLflow
- Управление зависимостями: uv

## Команды
- Обучение: `python -m src.train --config configs/experiment.yaml`
- Оценка: `python -m src.evaluate --checkpoint runs/latest`
- Предобработка данных: `python -m src.preprocess --data-dir data/raw`
- Jupyter: `jupyter lab`
- Тесты: `pytest tests/`

## Стандарты кодирования
- Конфигурация в YAML (не хардкодить гиперпараметры)
- Обработка данных через Polars (быстрее Pandas, типобезопасно)
- Все эксперименты должны логироваться в MLflow
- Notebook только для исследований, production-код обязан находиться в src/

## Структура проекта
- configs/ — YAML-конфигурации экспериментов
- data/raw/ — сырые данные (не коммитятся в Git, управляются через DVC)
- data/processed/ — обработанные данные
- src/ — основной код (model, data, train, evaluate)
- notebooks/ — исследовательский анализ
- runs/ — выходные данные обучения (checkpoints, логи)
```

## CLAUDE.md и AGENTS.md — как выбрать

Claude Code читает `CLAUDE.md` нативно (вместе с файлами памяти и правилами с привязкой к путям). При этом большинство **других** инструментов — Cursor, Codex, GitHub Copilot, Cline, Gemini / Antigravity, Aider, Zed и другие — читают `AGENTS.md`. Какой файл вести, зависит от того, сколько инструментов использует ваша команда.

| Сценарий | Рекомендация |
|----------|--------------|
| **Один инструмент (только Claude Code)** | `CLAUDE.md` достаточно — AGENTS.md не нужен |
| **Команда с несколькими инструментами** | Держите `AGENTS.md` как общий источник истины плюс тонкий `CLAUDE.md`, который его импортирует |

### Один инструмент: только CLAUDE.md

Если вся команда использует Claude Code, помещайте всё в `CLAUDE.md`. Второй файл не даёт никаких преимуществ.

### Несколько инструментов: AGENTS.md как источник истины

Когда команда сочетает Claude Code с Cursor, Codex, Copilot и др., держите общие правила — технологический стек, команды, стандарты кодирования, структуру проекта — в `AGENTS.md`, а `CLAUDE.md` сделайте тонким файлом, который импортирует его и добавляет специфичные для Claude дополнения:

```markdown
# Правила проекта

@AGENTS.md

## Особенности Claude Code
- Для крупных рефакторингов переключайтесь на Opus 4.8 через /model
- Ссылайтесь на docs/architecture.md по пути, не вставляйте его содержимое
```

Строка `@AGENTS.md` подтягивает общее содержимое в контекст Claude Code, поэтому Claude получает правила команды **и** свои специфичные дополнения. **Избегайте ведения двух расходящихся копий** одних и тех же правил — это главная ловушка, потому что два файла неизбежно со временем рассинхронизируются.

> Подробнее о формате AGENTS.md и его инструментарии см. в [Руководстве по AGENTS.md](/docs/usage/agents-md).

## Следующие шаги

- Узнайте об [управлении контекстом](/docs/usage/context-management) — освойте приёмы управления контекстным окном
- Узнайте о [настройке разрешений](/docs/usage/permissions) — контролируйте, какие операции может выполнять Claude
- Узнайте о [советах по рабочему процессу](/docs/usage/workflow-tips) — выстройте эффективный рабочий процесс с Claude Code