Добавить CLAUDE.md с документацией проекта на русском

CLAUDE.md

@@ -0,0 +1,185 @@
+# CLAUDE.md
+
+## О проекте
+
+Кратко опиши проект: что он делает, для кого, какую проблему решает.
+
+> Пример: веб-приложение для управления задачами команды. REST API на Node.js + React фронтенд.
+
+---
+
+## Стек технологий
+
+| Слой | Технология |
+|------|-----------|
+| Язык | TypeScript / Python / Go |
+| Фреймворк | Next.js / FastAPI / Gin |
+| БД | PostgreSQL + Redis |
+| Тесты | Jest / Pytest / Go test |
+| CI/CD | GitHub Actions |
+
+---
+
+## Структура проекта
+
+```
+src/
+  api/          — маршруты и контроллеры
+  services/     — бизнес-логика
+  models/       — схемы данных
+  utils/        — вспомогательные функции
+tests/          — тесты (зеркалируют src/)
+docs/           — документация
+```
+
+---
+
+## Окружение и установка
+
+```bash
+# Установка зависимостей
+npm install
+
+# Переменные окружения (скопировать и заполнить)
+cp .env.example .env
+
+# Запуск БД через Docker
+docker compose up -d
+```
+
+Обязательные переменные окружения:
+- `DATABASE_URL` — строка подключения к PostgreSQL
+- `REDIS_URL` — строка подключения к Redis
+- `JWT_SECRET` — секрет для подписи токенов
+
+---
+
+## Команды разработки
+
+```bash
+# Запуск в режиме разработки
+npm run dev
+
+# Сборка
+npm run build
+
+# Проверка типов
+npm run typecheck
+
+# Линтер
+npm run lint
+
+# Форматирование
+npm run format
+```
+
+---
+
+## Тестирование
+
+```bash
+# Запуск всех тестов
+npm test
+
+# Один тест по имени
+npm test -- --testNamePattern="название теста"
+
+# Только unit-тесты (быстро)
+npm run test:unit
+
+# Интеграционные тесты (медленно, нужна БД)
+npm run test:integration
+
+# С покрытием
+npm run test:coverage
+```
+
+**Правила:**
+- Перед коммитом запускать `npm run typecheck && npm run lint`
+- Не запускать полный suite при каждом изменении — используй фильтр по имени
+- Новый код = новые тесты; PR без тестов не принимается
+
+---
+
+## Стиль кода
+
+- ES-модули (`import/export`), не CommonJS
+- `async/await` вместо `.then()/.catch()`
+- `const` по умолчанию, `let` только когда нужна переменная
+- Именование: `camelCase` для переменных и функций, `PascalCase` для классов и типов
+- Не оставлять `console.log` в production-коде — использовать логгер
+- Форматирование контролирует Prettier — не прописывай стиль вручную
+
+---
+
+## Рабочие процессы
+
+### Новая фича
+1. Создать ветку от `main`: `git checkout -b feature/название`
+2. Реализовать изменения
+3. Написать тесты
+4. Запустить `npm run typecheck && npm run lint && npm test`
+5. Создать PR с описанием что и зачем изменено
+
+### Исправление бага
+1. Создать ветку: `git checkout -b fix/описание-бага`
+2. Воспроизвести баг тестом
+3. Исправить — убедиться что тест проходит
+4. PR с номером issue в заголовке
+
+### Рефакторинг
+- Не смешивать рефакторинг с новой функциональностью в одном PR
+- Покрытие тестами должно оставаться на том же уровне или расти
+
+---
+
+## Git и PR
+
+**Именование веток:**
+```
+feature/краткое-описание
+fix/что-сломано
+chore/что-делается
+docs/что-документируется
+```
+
+**Формат коммитов:**
+```
+feat: добавить авторизацию через OAuth
+fix: исправить утечку памяти в воркере
+chore: обновить зависимости
+docs: описать API эндпоинты
+```
+
+**PR:**
+- Заголовок: до 70 символов, описывает суть изменения
+- Тело: что изменено и почему, как проверить
+- Один PR — одна задача
+
+---
+
+## Архитектурные решения
+
+- **Сервисный слой** — вся бизнес-логика в `services/`, контроллеры только маршрутизируют
+- **Репозиторий-паттерн** — доступ к БД только через репозитории, не напрямую из сервисов
+- **Ошибки** — бросать типизированные ошибки (`AppError`), не возвращать `null`
+- **Валидация** — только на входе системы (HTTP / очередь), не дублировать внутри
+
+---
+
+## Важные особенности и подводные камни
+
+- Миграции БД запускаются автоматически при старте — не запускать вручную в production
+- Тесты используют отдельную БД (`DATABASE_URL_TEST`) — не трогай основную
+- Кэш Redis инвалидируется при деплое — первые запросы после деплоя будут медленнее
+- Rate limiting: 100 запросов/мин на IP — учитывай в нагрузочных тестах
+
+---
+
+## Что делать нельзя
+
+- Коммитить `.env` файлы и секреты
+- Делать прямые SQL-запросы в обход ORM без веской причины
+- Игнорировать ошибки TypeScript через `// @ts-ignore` без объяснения
+- Мерджить PR без прохождения CI
+- Деплоить напрямую в `main` — только через PR