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

/init

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

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

## Технологический стек

- Среда выполнения: 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/`

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

## Тестирование

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

## Запрещённые операции

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

## Описание архитектуры
В проекте используется гексагональная архитектура (Hexagonal Architecture):

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

## Дополнительная информация

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

# 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/

# 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`

# 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)

# 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

# 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, логи)

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

@AGENTS.md

## Особенности Claude Code

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