CLAUDE.md примеры: 15 шаблонов под Next.js, FastAPI, Django, Laravel в 2026 году

Claude Code на голом старте знает синтаксис трёх десятков языков, но ничего не знает про ваш конкретный проект: где у вас лежат хендлеры, чем тестировать, какую команду нельзя запускать на проде. Каждую сессию приходится объяснять заново. CLAUDE.md в корне репозитория закрывает этот разрыв за один файл.

В этой статье собрали 15 готовых шаблонов CLAUDE.md под популярные стеки: Next.js, FastAPI, Django, Laravel, WordPress, Spring Boot и ещё девять. Каждый шаблон по 60–120 строк, копируется в корень проекта и работает с первой сессии. Плюс сравнительная таблица «что включать под разные типы проектов», разбор семи частых ошибок и ответы на живые вопросы из FAQ.

Если ещё не знакомы с самим инструментом, начните с обзорной статьи «Что такое Claude Code»: там разобрали интерфейс, тарифы и первый запуск.

А полный разбор slash-команд, которые работают в паре с CLAUDE.md, мы собрали в материале «37 команд Claude Code». Команда /init оттуда генерирует стартовый CLAUDE.md, который потом доводят руками.

Статья полезна не только разработчикам. CLAUDE.md одинаково хорошо работает в проектах контент-маркетологов, продактов и аналитиков: пара десятков строк инструкций экономит часы повторных объяснений Клоду в каждой новой сессии.

Если хочется освоить ремесло работы с Claude и другими AI-инструментами системно, загляните в нашу подборку курсов по нейросетям и искусственному интеллекту: там 316 программ, от коротких интенсивов на пару недель до годовых курсов с карьерным треком.

Что такое CLAUDE.md за 60 секундСкопировано

CLAUDE.md — это обычный markdown-файл, который Claude Code читает в самом начале каждой сессии. Файл превращается в system-prompt уровня проекта: команды сборки, конвенции именования, карта структуры репозитория, запретные зоны. Всё, что вы иначе бы объясняли Клоду в чате каждый раз заново.

По официальной документации Anthropic файл может лежать на трёх уровнях: глобальном (~/.claude/CLAUDE.md — личные предпочтения для всех проектов), проектном (./CLAUDE.md в корне репозитория, шарится через git) и локальном (./CLAUDE.local.md — личные настройки внутри проекта, в .gitignore). При запуске Claude Code обходит все три и склеивает их в один контекст.

Размер критичен. По исследованиям Anthropic, файлы до 200 строк дают compliance rate выше 92 %, после 400 строк он падает до 71 %. Поэтому в шаблонах ниже мы держимся в диапазоне 60–120 строк и всё детальное выносим в .claude/rules/ либо в agent_docs/.

Запускается просто: в корне проекта пишете claude и команду /init. Клод сам сканирует кодовую базу и создаёт черновик CLAUDE.md. Дальше дорабатываете руками или подставляете один из готовых шаблонов отсюда.

6 обязательных секций в любом CLAUDE.mdСкопировано

Прежде чем перейти к стек-специфичным примерам, зафиксируем минимальный каркас. Эти шесть секций встречаются во всех 15 шаблонах ниже, меняется только содержимое.

1. Стек и версии

Первое, что должен увидеть Клод. Не абстрактное «используем React», а конкретное «Next.js 15.0, React 19, TypeScript 5.6, Tailwind 4.0, Node 20». Версии нужны, чтобы Клод не предлагал API из будущих или прошлых релизов.

2. Команды для запуска и тестов

Каждую команду пишите отдельной строкой, с комментарием для чего. npm run dev, pytest tests/ -v, php artisan test. Если команда требует переменные окружения, указываем какие. Без этой секции Клод будет фантазировать имена скриптов.

3. Карта структуры проекта

Дерево директорий на 15–30 строк с однострочным описанием каждой папки: «src/api/handlers — REST-обработчики, по файлу на ресурс». Не всю файловую систему — только смысловые узлы.

4. Конвенции кода

Именование, отступы, обработка ошибок, стиль импортов. Конкретно: «2 пробела на отступ», «snake_case в Python, camelCase в TS», «ошибки логируем через structlog в ключи event/context, не через print».

5. Запретные зоны

Файлы и директории, которые Клод не должен трогать без явного запроса. Миграции, секреты, lock-файлы, конфиг продакшена. Лучше написать «НЕ РЕДАКТИРОВАТЬ: migrations/, .env*, package-lock.json» жирным или капсом.

6. Известные подводные камни

Один-два абзаца про неочевидности проекта. «Redis-кэш не инвалидируется автоматически — после правки моделей запускайте ./scripts/flush_cache.sh». Эта секция растёт со временем: туда падает всё, что Клод однажды сломал.

15 готовых шаблонов CLAUDE.md под разные стекиСкопировано

Каждый шаблон ниже работает как самодостаточный файл. Берёте, кладёте в корень репозитория, правите имена под свой проект, запускаете Claude Code. Все шаблоны держатся в рамках 60–120 строк, чтобы compliance rate оставался выше 90 %.

Next.js 15 + TypeScript + Tailwind

Самый частый запрос. Шаблон рассчитан на App Router и Server Components, с Prisma и shadcn/ui.

# Project: ShopFront

## Stack
- Next.js 15.0 (App Router, Server Components)
- React 19, TypeScript 5.6 (strict mode)
- Tailwind 4.0, shadcn/ui
- Prisma 6 + PostgreSQL 16
- TanStack Query 5 (только на client components)
- Node 20, package manager: pnpm

## Commands
- `pnpm dev` — локальный dev-сервер на :3000
- `pnpm build` — production build
- `pnpm lint` — ESLint + Prettier check
- `pnpm typecheck` — tsc --noEmit
- `pnpm test` — Vitest (unit + integration)
- `pnpm db:migrate` — применить миграции Prisma
- `pnpm db:studio` — GUI для базы

Перед коммитом всегда: `pnpm lint && pnpm typecheck && pnpm test`.

## Layout
```
src/
  app/                 # App Router, по папке на route
    (marketing)/       # public-зона без auth
    (app)/             # auth-required, layout с Sidebar
    api/               # route handlers (не API Routes!)
  components/
    ui/                # shadcn-компоненты, не трогать вручную
    features/          # бизнес-компоненты по фичам
  lib/                 # хелперы, db-клиент, утилиты
  server/              # серверные actions, доменная логика
prisma/schema.prisma   # источник истины для БД
```

## Conventions
- Server Components по умолчанию, "use client" только когда нужен state/effects
- Data fetching — в Server Components через async/await, не в useEffect
- Формы — Server Actions + zod-валидация, не fetch к /api
- Стили — только Tailwind utility classes, никаких CSS-modules
- Импорты — абсолютные с алиасом `@/`, относительные запрещены

## Don't touch
- `prisma/migrations/` — миграции генерируются автоматически
- `components/ui/` — shadcn-компоненты, обновляются через CLI
- `.env*`, `next.config.mjs` — без явного запроса

## Gotchas
- Tailwind 4.0 использует CSS-imports вместо tailwind.config — настройки в `src/app/globals.css`
- Server Actions требуют `'use server'` в первой строке файла
- При изменении `schema.prisma` запускайте `pnpm db:migrate` локально, не пушьте миграции из CI

React + Vite + TanStack Query

Для SPA без SSR. Vite вместо Next.js, React Router для навигации, TanStack Query для серверного состояния.

# Project: AdminPanel

## Stack
- React 19, TypeScript 5.6 (strict)
- Vite 6, SWC compiler
- React Router 7 (data router API)
- TanStack Query 5, TanStack Table 8
- Tailwind 4, Radix UI primitives
- Vitest + Testing Library
- Node 20, npm

## Commands
- `npm run dev` — Vite dev-server на :5173
- `npm run build` — production bundle
- `npm run preview` — preview билда локально
- `npm run lint` — ESLint
- `npm run test` — Vitest watch mode
- `npm run test:ci` — Vitest run (для CI)

## Layout
```
src/
  routes/              # одна папка = один route, файл route.tsx
  components/
    ui/                # generic-компоненты, переиспользуемые
    forms/             # формы с react-hook-form
  api/
    client.ts          # axios instance с интерцепторами
    hooks/             # useQuery/useMutation обёртки
  store/               # zustand-сторы для UI-state
  lib/                 # утилиты, форматтеры
  types/               # глобальные TS-типы
```

## Conventions
- Серверное состояние — TanStack Query, локальное — Zustand или useState
- Формы — react-hook-form + zod, никаких controlled inputs руками
- Запросы к API — только через хуки из `api/hooks/`, не fetch в компонентах
- Имена файлов: kebab-case, имена компонентов: PascalCase
- Один компонент — один файл, не более 250 строк

## Don't touch
- `vite.config.ts`, `tsconfig.json` — менять только по согласованию
- `src/api/client.ts` — интерцепторы критичны для auth-flow

## Gotchas
- TanStack Query кэш живёт 5 минут по умолчанию, для критичных данных задавайте `staleTime: 0`
- React Router 7 — data router, используйте loaders/actions, не useEffect для загрузки
- Vite не делает code-split автоматически для динамических импортов из node_modules — выносите вручную

Vue 3 + Nuxt 3

Аналог Next.js на Vue. SSR из коробки, файловая маршрутизация, auto-imports.

# Project: CourseHub

## Stack
- Nuxt 3.14, Vue 3.5 (Composition API only)
- TypeScript 5.6
- Pinia 2 для глобального стора
- VueUse, @nuxt/image
- Tailwind 4 через @nuxtjs/tailwindcss
- Pinia Colada для серверного состояния
- pnpm, Node 20

## Commands
- `pnpm dev` — dev-сервер на :3000
- `pnpm build` — production build
- `pnpm generate` — статическая генерация
- `pnpm typecheck` — vue-tsc
- `pnpm test` — Vitest + @vue/test-utils

## Layout
```
pages/                 # auto-routing, файл = route
components/            # auto-imported в шаблонах
composables/           # auto-imported, useFoo()
server/api/            # серверные endpoints, по файлу на ресурс
stores/                # Pinia stores
plugins/               # nuxt plugins
```

## Conventions
- Composition API + `<script setup>` — Options API запрещён
- Auto-imports включены — не пишите `import { ref } from 'vue'`
- Серверная логика — в `server/api/`, на клиенте обращаемся через `useFetch`/`$fetch`
- Один компонент — один файл .vue (template + script + style scoped)
- TypeScript строгий, `any` запрещён

## Don't touch
- `nuxt.config.ts` — без явного запроса
- `.output/`, `.nuxt/` — генерируются автоматически

## Gotchas
- `useFetch` кэширует по key — для динамических данных передавайте `watch: [...]` или используйте `$fetch` напрямую
- Composables должны начинаться с `use` — без префикса auto-import не сработает
- На SSR `window` и `document` недоступны — оборачивайте в `if (process.client)` или `onMounted`

FastAPI + SQLAlchemy + Alembic

Современный Python-бэкенд. Async-эндпоинты, типизация через Pydantic, миграции через Alembic.

# Project: PaymentsAPI

## Stack
- Python 3.12, FastAPI 0.115
- SQLAlchemy 2.0 (async, asyncpg)
- Alembic для миграций
- Pydantic v2 для схем
- Redis 7 для кэша и rate-limit
- pytest + pytest-asyncio + httpx
- poetry для зависимостей

## Commands
- `poetry install` — установить зависимости
- `make dev` — запустить uvicorn с reload на :8000
- `make test` — pytest -v
- `make test-cov` — pytest с покрытием
- `make lint` — ruff check + ruff format --check
- `make fmt` — ruff format
- `make migrate` — alembic upgrade head
- `make migration name=add_users` — создать новую миграцию

## Layout
```
app/
  api/
    v1/                # роутеры по версиям, один файл на ресурс
    deps.py            # FastAPI dependencies (auth, db session)
  core/
    config.py          # Settings через pydantic-settings
    security.py        # JWT, password hashing
  db/
    base.py            # declarative_base
    session.py         # async engine + sessionmaker
  models/              # SQLAlchemy ORM-модели
  schemas/             # Pydantic-схемы для request/response
  services/            # бизнес-логика, не зависит от FastAPI
  tasks/               # background tasks, celery jobs
alembic/               # миграции
tests/                 # pytest, по фиче на папку
```

## Conventions
- Async везде, синхронные хендлеры запрещены
- Бизнес-логика — в `services/`, роутеры только парсят запрос и возвращают ответ
- Pydantic-схемы отдельно от ORM-моделей — никакого orm_mode без необходимости
- Зависимости через Depends(), а не глобальные переменные
- Логи через structlog, JSON-формат на проде

## Don't touch
- `alembic/versions/` — миграции генерируются через `make migration`
- `pyproject.toml` lock-секцию — обновляем только через `poetry add`
- `.env`, `.env.prod`

## Gotchas
- Async session нельзя передавать между корутинами — открывайте новую в каждой
- При изменении модели ОБЯЗАТЕЛЬНО создавать миграцию через `make migration name=...` — autogenerate Alembic не всегда ловит изменения индексов
- pytest-asyncio требует `@pytest.mark.asyncio` на каждом async-тесте, иначе они пропускаются молча

Django + DRF

Классический Python-стек для проектов, где важна админка и готовые батарейки.

# Project: LMS Backend

## Stack
- Python 3.12, Django 5.1
- Django REST Framework 3.15
- PostgreSQL 16, Redis 7
- Celery 5 для очередей
- pytest-django, factory-boy
- poetry, Docker Compose для dev

## Commands
- `make up` — поднять docker-compose (postgres + redis + django)
- `make migrate` — python manage.py migrate
- `make makemigrations app=courses` — создать миграции для app
- `make shell` — django-shell с extensions
- `make test` — pytest --reuse-db
- `make test-fresh` — pytest --create-db (после изменений в моделях)
- `make lint` — ruff + mypy

## Layout
```
apps/
  users/               # каждое Django-app — отдельная папка
  courses/
  payments/
    models.py
    serializers.py     # DRF serializers
    views.py           # ViewSets
    permissions.py
    tasks.py           # Celery tasks
    tests/
config/
  settings/
    base.py
    dev.py
    prod.py
  urls.py
  celery.py
```

## Conventions
- ViewSets вместо APIView — для CRUD используем ModelViewSet
- Permission classes — отдельным файлом, не inline
- Бизнес-логика в `services.py` внутри app, не в моделях и не во вьюхах
- Все запросы к БД — через select_related/prefetch_related, голый ORM в циклах запрещён
- Сериализаторы валидируют, вьюхи маршрутизируют, сервисы делают работу

## Don't touch
- `apps/*/migrations/` — миграции автогенерируются
- `manage.py`, `config/settings/base.py` структуру — только содержимое

## Gotchas
- При добавлении модели всегда `make makemigrations app=...` ПЕРЕД коммитом — забытые миграции ломают CI
- DRF Browsable API включён только в dev — на проде только JSON
- Celery worker нужно перезапускать после изменений в tasks.py — autoreload работает только для Django

Flask + SQLAlchemy

Минималистичный Python-стек для маленьких сервисов и прототипов.

# Project: WebhookProxy

## Stack
- Python 3.12, Flask 3.0
- SQLAlchemy 2.0 (sync), Flask-SQLAlchemy
- Flask-Migrate (Alembic под капотом)
- Marshmallow для сериализации
- gunicorn для prod, flask dev для локали
- pytest + pytest-flask

## Commands
- `flask --app app run --debug` — dev-сервер :5000
- `gunicorn 'app:create_app()' -w 4` — prod-запуск
- `flask db migrate -m "add users"` — новая миграция
- `flask db upgrade` — применить миграции
- `pytest tests/ -v` — тесты
- `ruff check . && ruff format --check .` — линт

## Layout
```
app/
  __init__.py          # create_app(), application factory
  models.py            # все модели в одном файле, проект маленький
  schemas.py           # marshmallow-схемы
  blueprints/
    auth.py
    webhooks.py
    health.py
  extensions.py        # db, migrate, ma — инициализация
  config.py
migrations/            # Alembic
tests/
```

## Conventions
- Application factory (`create_app`) — никаких глобальных Flask-app
- Blueprints по доменам, не по слоям
- Конфиги через переменные окружения, читаются в `config.py`
- Логи в stdout, формат JSON на проде

## Don't touch
- `migrations/versions/` — генерируется автоматически
- `.env*`

## Gotchas
- Flask-SQLAlchemy 3+ требует `db.session.execute(select(Model))` вместо `Model.query`
- При тестах нужен фикстура `app` с application context, иначе extensions падают
- gunicorn по умолчанию делает sync workers — для I/O-heavy эндпоинтов используйте `--worker-class gevent`

Node.js + Express + Prisma

Классика Node-бэкенда. Express для роутинга, Prisma для БД, TypeScript обязателен.

# Project: NotificationService

## Stack
- Node 20, TypeScript 5.6 (strict)
- Express 4
- Prisma 6 + PostgreSQL 16
- Zod для валидации
- Pino для логов
- Jest + Supertest для тестов
- pnpm

## Commands
- `pnpm dev` — tsx watch, dev-сервер :4000
- `pnpm build` — tsc в dist/
- `pnpm start` — node dist/index.js
- `pnpm test` — Jest
- `pnpm lint` — ESLint + Prettier
- `pnpm db:migrate` — prisma migrate dev
- `pnpm db:deploy` — prisma migrate deploy (для CI/prod)
- `pnpm db:generate` — генерация Prisma Client

## Layout
```
src/
  routes/              # express routers, по файлу на ресурс
  controllers/         # обработчики, валидация, ответ
  services/            # бизнес-логика
  middleware/          # auth, rate-limit, errors
  schemas/             # zod-схемы для запросов
  lib/
    prisma.ts          # singleton PrismaClient
    logger.ts          # pino-инстанс
  config/
    env.ts             # zod-валидация process.env
prisma/schema.prisma
tests/
```

## Conventions
- TypeScript strict, никакого `any`
- Контроллеры тонкие, вся логика в services
- Валидация входа через zod в middleware, не в контроллере
- Ошибки выбрасываем кастомные классы (`NotFoundError`, `ValidationError`), errorHandler ловит и форматирует
- Логи структурированные через pino, без console.log

## Don't touch
- `prisma/migrations/` — генерируется автоматически
- `tsconfig.json` — без согласования

## Gotchas
- PrismaClient — singleton, не создавайте новый в каждом запросе (memory leak)
- Async-ошибки в express нужно либо ловить try/catch в каждом контроллере, либо использовать `express-async-errors`
- При деплое сначала `prisma migrate deploy`, потом старт приложения — иначе схемы расходятся

NestJS + TypeORM

Enterprise-Node с DI-контейнером, декораторами и модульной архитектурой.

# Project: OrderingAPI

## Stack
- Node 20, TypeScript 5.6
- NestJS 10
- TypeORM 0.3 + PostgreSQL 16
- class-validator, class-transformer
- @nestjs/swagger для OpenAPI
- @nestjs/bull для очередей (Redis)
- Jest + Supertest

## Commands
- `pnpm start:dev` — watch mode на :3000
- `pnpm build` — компиляция
- `pnpm start:prod` — production
- `pnpm test` — unit-тесты
- `pnpm test:e2e` — e2e через Supertest
- `pnpm migration:generate src/migrations/AddUsers` — новая миграция
- `pnpm migration:run` — применить миграции

## Layout
```
src/
  modules/
    users/             # один модуль = одна папка
      users.module.ts
      users.controller.ts
      users.service.ts
      dto/             # request/response DTO
      entities/        # TypeORM entities
    orders/
    payments/
  common/
    guards/            # AuthGuard, RolesGuard
    interceptors/
    pipes/             # ValidationPipe
    filters/           # exception filters
  config/              # @nestjs/config
  migrations/
```

## Conventions
- Один контроллер — один ресурс, методы под HTTP-глаголы
- DTO с class-validator декораторами на каждый endpoint
- Бизнес-логика в services, контроллер только маршрутизирует
- Зависимости через DI (constructor injection), никаких new руками
- Swagger-декораторы на каждом endpoint — `@ApiTags`, `@ApiResponse`

## Don't touch
- `src/migrations/*.ts` — генерируются через migration:generate
- `nest-cli.json`, `tsconfig.build.json`

## Gotchas
- TypeORM 0.3 — `Repository.findOne()` принимает объект `{ where: {...} }`, не id напрямую
- Circular deps между модулями ломают DI — используйте `forwardRef(() => Module)`
- E2e-тесты требуют отдельной БД — настройте `test.env` с другой схемой

Laravel 11

PHP-стек номер один. Eloquent, Artisan, Blade и вся обвязка из коробки.

# Project: BillingPortal

## Stack
- PHP 8.3, Laravel 11
- MySQL 8 / PostgreSQL 16
- Redis 7 для кэша и очередей
- Livewire 3 для интерактива
- Tailwind 4 + Vite для ассетов
- Pest 3 для тестов
- composer 2

## Commands
- `php artisan serve` — dev-сервер :8000
- `npm run dev` — Vite для ассетов
- `php artisan migrate` — миграции
- `php artisan make:migration create_invoices_table` — новая миграция
- `php artisan make:model Invoice -m` — модель + миграция
- `php artisan test` — Pest
- `./vendor/bin/pint` — code style fix (Laravel Pint)
- `php artisan queue:work` — обработка очередей

## Layout
```
app/
  Http/
    Controllers/       # тонкие контроллеры
    Requests/          # FormRequest для валидации
    Resources/         # API resources
    Middleware/
  Models/              # Eloquent-модели
  Services/            # бизнес-логика
  Jobs/                # очереди
  Mail/                # mailables
  Policies/            # авторизация
database/
  migrations/
  factories/
  seeders/
resources/
  views/               # Blade-шаблоны
  js/, css/
routes/
  web.php
  api.php
tests/
```

## Conventions
- FormRequest для всей валидации, не Validator::make в контроллере
- Тонкие контроллеры, бизнес-логика в Services или Actions
- Eager loading через `with()` — N+1 запрещён, проверяется через Laravel Debugbar
- Очереди обязательны для всего, что дольше 200 мс (email, webhook, отчёты)
- Code style — Laravel Pint, запускается в pre-commit hook

## Don't touch
- `database/migrations/` — без явного запроса на изменение существующей миграции
- `.env`, `.env.testing`
- `bootstrap/cache/`, `storage/framework/`

## Gotchas
- Кэш конфига на проде: после правок `.env` обязательно `php artisan config:cache` либо `:clear`
- Очереди не подхватывают изменения автоматически — `php artisan queue:restart` после деплоя
- Eloquent `update()` НЕ триггерит события модели — используйте `save()` если нужны events

WordPress (тема и плагины)

Шаблон под кастомную WP-тему с плагинами. Учитывает специфику хуков, REST API и wp-cli.

# Project: ShopTheme

## Stack
- PHP 8.3, WordPress 6.9
- MySQL 8
- Custom theme + 4 кастомных плагина
- ACF Pro для метаполей
- WP-CLI обязателен
- Composer для PHP-зависимостей плагинов
- Webpack 5 для ассетов темы

## Commands
- `wp --allow-root db export backup.sql` — бэкап БД
- `wp --allow-root cache flush` — сброс object cache
- `wp --allow-root rewrite flush` — пересоздать permalinks
- `npm run build` — собрать ассеты темы
- `composer install --working-dir=wp-content/plugins/shop-core` — зависимости плагина
- `vendor/bin/phpcs --standard=WordPress wp-content/themes/shop/` — линт WP coding standards

## Layout
```
wp-content/
  themes/shop/
    functions.php       # точка входа, подключение всех inc/*.php
    inc/                # модули темы, по файлу на фичу
    template-parts/     # переиспользуемые блоки
    assets/             # webpack-собранные css/js
  plugins/
    shop-core/          # кастомный плагин с CPT и таксономиями
    shop-api/           # REST endpoints
    shop-pinterest/     # интеграция
    shop-feeds/         # XML/JSON фиды
```

## Conventions
- Никакого raw SQL — только WP_Query, get_posts, wpdb через prepare()
- Кастомные таксономии и поля — через WP-хуки, не INSERT в БД (иначе ломаются индексы)
- Все строки переводимые через __() / _e() с textdomain темы
- Хуки регистрируем в `inc/hooks.php`, не разбрасываем по template-parts
- Ассеты подключаем через wp_enqueue_*, не <link> в header.php

## Don't touch
- `wp-config.php`, `.htaccess`
- `wp-content/uploads/`
- Любые core-файлы WP в `wp-admin/`, `wp-includes/`

## Gotchas
- После правки PHP темы ОБЯЗАТЕЛЬНО три сброса кеша: `systemctl reload php-fpm`, плагин кеша, Redis FLUSHALL
- При добавлении таксономий и метаполей курсу — только через `wp post term add` / `wp post meta update`, raw SQL не обновит индексы
- Транзиенты в БД накапливаются — раз в неделю чистите wp_options через `wp transient delete --expired`

Spring Boot 3 (Java)

Enterprise-Java. Spring Boot 3, JPA, Maven или Gradle.

# Project: InventoryService

## Stack
- Java 21 (LTS)
- Spring Boot 3.3
- Spring Data JPA + Hibernate 6
- PostgreSQL 16, Flyway для миграций
- MapStruct для DTO-маппинга
- JUnit 5 + Mockito + Testcontainers
- Gradle 8

## Commands
- `./gradlew bootRun` — dev-запуск :8080
- `./gradlew build` — сборка jar
- `./gradlew test` — unit + integration
- `./gradlew flywayMigrate` — миграции
- `./gradlew spotlessApply` — формат кода
- `./gradlew dependencyCheckAnalyze` — security audit

## Layout
```
src/main/java/com/company/inventory/
  controller/          # @RestController, тонкие
  service/             # @Service, бизнес-логика
  repository/          # @Repository, JpaRepository
  entity/              # JPA-сущности
  dto/                 # request/response DTO
  mapper/              # MapStruct мапперы
  config/              # @Configuration
  exception/           # кастомные исключения + @ControllerAdvice
src/main/resources/
  application.yml
  application-dev.yml
  db/migration/        # Flyway скрипты V1__init.sql
src/test/java/         # параллельная структура
```

## Conventions
- DTO отдельно от Entity, маппинг через MapStruct
- Транзакции на уровне service, не репозитория
- Lombok для геттеров/билдеров, но не для @Data на entity (ломает hashCode)
- Все @RestController методы возвращают ResponseEntity
- Логи через SLF4J + Logback, JSON-формат на проде

## Don't touch
- `src/main/resources/db/migration/V*__*.sql` — миграции иммутабельны, новые через V{N+1}
- `gradle/wrapper/`, `build.gradle.kts` без согласования

## Gotchas
- JPA LazyLoading вне транзакции — LazyInitializationException, либо открывайте транзакцию, либо тяните через JOIN FETCH
- Flyway не откатывает миграции — для отката пишите новую V{N+1} с обратными операциями
- Testcontainers поднимает Docker — в CI нужен docker-in-docker или удалённый daemon

Ruby on Rails 7

Классика для rapid development и MVP. Hotwire вместо тяжёлого JS, минимум сторонних пакетов.

# Project: CommunityHub

## Stack
- Ruby 3.3, Rails 7.2
- PostgreSQL 16, Redis 7
- Hotwire (Turbo + Stimulus), без React
- Sidekiq для очередей
- RSpec + FactoryBot + Capybara
- Tailwind 4 через tailwindcss-rails
- bundler 2

## Commands
- `bin/dev` — Foreman (web + jobs + css)
- `bin/rails s` — только web
- `bin/rails db:migrate` — миграции
- `bin/rails g migration AddRoleToUsers role:string`
- `bundle exec rspec` — тесты
- `bin/rubocop -a` — линт + автофикс
- `bundle exec brakeman` — security audit

## Layout
```
app/
  controllers/         # тонкие, RESTful action set
  models/              # ActiveRecord, скоупы и валидации
  views/               # erb-шаблоны
  components/          # ViewComponent (опционально)
  services/            # бизнес-логика, plain Ruby objects
  jobs/                # Sidekiq jobs
  mailers/
  javascript/
    controllers/       # Stimulus controllers
config/
  routes.rb
  database.yml
db/
  migrate/
  schema.rb
spec/                  # RSpec параллельно app/
```

## Conventions
- Fat models, skinny controllers — но логика длиннее 20 строк уходит в service
- Запросы к БД — через named scopes, не where в контроллерах
- N+1 проверяем через bullet gem в dev
- Strong params обязательны для всех create/update
- Background jobs для всего, что >100 мс

## Don't touch
- `db/migrate/*` — миграции иммутабельны после деплоя
- `db/schema.rb` — генерируется автоматически из миграций
- `config/credentials.yml.enc`, master.key

## Gotchas
- Rails 7 на Ruby 3.3 требует bootsnap — без него старт медленный
- Sidekiq jobs нужно перезапускать после изменений в коде — capistrano deploy:restart
- Hotwire Turbo перехватывает все ссылки и формы — для <a target="_blank"> добавляйте `data-turbo="false"`

Go + Gin + sqlc

Минималистичный Go-стек. Gin для роутинга, sqlc для типобезопасных SQL-запросов, миграции через goose.

# Project: AnalyticsAPI

## Stack
- Go 1.23
- Gin 1.10 (router)
- sqlc 1.27 (генерация типобезопасного БД-кода)
- pgx 5 как драйвер PostgreSQL 16
- goose для миграций
- zerolog для логов
- testify + dockertest для тестов
- go modules

## Commands
- `go run ./cmd/api` — запуск
- `make dev` — air для hot reload
- `go build -o bin/api ./cmd/api` — бинарь
- `make sqlc` — sqlc generate (после правки query.sql)
- `make migrate-up` — goose up
- `make migrate-new name=add_events` — новая миграция
- `go test ./... -race -cover` — тесты
- `golangci-lint run` — линт

## Layout
```
cmd/api/main.go        # точка входа
internal/
  api/                 # gin handlers
    middleware/
    router.go
  service/             # бизнес-логика
  repository/          # обёртки над sqlc
  db/                  # сгенерированный sqlc-код
    query.sql          # источник: пишем SQL руками
    schema.sql         # CREATE TABLE для sqlc
    sqlc.yaml
  config/
migrations/            # goose
pkg/                   # переиспользуемые библиотеки
```

## Conventions
- Errors оборачиваем через `fmt.Errorf("context: %w", err)`, всегда с %w
- Контекст первым аргументом во всех функциях, которые ходят в БД или по сети
- Структуры маленькие, методы только если есть состояние
- Никаких init() — конструкторы явные
- Логи через zerolog, без log.Println

## Don't touch
- `internal/db/*.sql.go` — сгенерированы sqlc, не редактируйте руками
- `migrations/*.sql` — после первого применения иммутабельны
- `go.sum` — обновляется через go mod tidy

## Gotchas
- sqlc нужно регенерировать после правки query.sql, иначе старый код в db/ будет компилироваться без ошибок, но падать в рантайме
- pgx requires context на всех вызовах — без него запросы не отменяются при отмене запроса
- goose up не транзакционный для DDL — пишите миграции так, чтобы откат был ручной

.NET 8 + C#

Современный .NET-бэкенд. Minimal API или контроллеры, EF Core для БД, xUnit для тестов.

# Project: ReportingAPI

## Stack
- .NET 8 (LTS)
- C# 12
- ASP.NET Core Web API (controllers, не Minimal API)
- Entity Framework Core 8 + PostgreSQL 16
- MediatR для CQRS
- FluentValidation
- Serilog для логов
- xUnit + Moq + Testcontainers
- dotnet CLI

## Commands
- `dotnet run --project src/Api` — dev :5000
- `dotnet build` — сборка
- `dotnet test` — все тесты
- `dotnet ef migrations add AddUsers --project src/Infrastructure --startup-project src/Api`
- `dotnet ef database update --project src/Infrastructure --startup-project src/Api`
- `dotnet format` — code style

## Layout
```
src/
  Api/                 # ASP.NET-проект, controllers + Program.cs
  Application/         # CQRS handlers, validators, DTOs
  Domain/              # entities, value objects, domain events
  Infrastructure/      # EF Core DbContext, repositories, external APIs
tests/
  Application.Tests/
  Api.IntegrationTests/
```

## Conventions
- Clean Architecture — Domain ничего не знает, Application знает Domain, Infrastructure реализует интерфейсы из Application
- CQRS через MediatR: команды меняют состояние, queries только читают
- DTO != Entity, маппинг через AutoMapper или явно
- Async везде, никакого .Result или .Wait()
- Логи через ILogger<T>, структурированные

## Don't touch
- `src/Infrastructure/Migrations/` — генерируются через dotnet ef
- `*.csproj` — добавление пакетов через `dotnet add package`

## Gotchas
- EF Core lazy loading отключён по умолчанию — используйте Include() или Explicit loading
- Async-методы должны заканчиваться на Async (соглашение)
- DbContext не thread-safe — не делите его между параллельными задачами, используйте IDbContextFactory

Монорепо на Turborepo

Для проектов, где в одном репо живут frontend, backend и общие пакеты. Turborepo даёт кэш сборок и параллельное выполнение.

# Project: PlatformMonorepo

## Stack
- Node 20, TypeScript 5.6
- Turborepo 2, pnpm 9 workspaces
- Frontend: Next.js 15 в `apps/web`
- Backend: NestJS в `apps/api`
- Shared: пакеты в `packages/` (ui, types, eslint-config)

## Commands
- `pnpm dev` — turbo dev (все апы параллельно)
- `pnpm build` — turbo build с кэшем
- `pnpm lint` — turbo lint
- `pnpm test` — turbo test
- `pnpm --filter web dev` — запустить только web
- `pnpm --filter api test` — только API
- `pnpm changeset` — отметить изменения для версионирования пакетов

## Layout
```
apps/
  web/                 # Next.js приложение
  api/                 # NestJS API
  admin/               # React admin panel
packages/
  ui/                  # shared shadcn-компоненты
  types/               # shared TS types
  eslint-config/       # shared ESLint config
  tsconfig/            # base tsconfig.json
turbo.json             # pipeline и кэш
pnpm-workspace.yaml
```

## Conventions
- Все shared-код через packages/, никаких `../../../` импортов между apps/
- Внутренние пакеты обозначаем `@workspace/*` через workspace:* в зависимостях
- TypeScript строгий во всех пакетах, общий tsconfig через extends
- Каждый пакет имеет свой package.json со scripts, turbo дёргает их

## Don't touch
- `turbo.json` — pipeline без согласования
- `pnpm-workspace.yaml`, `pnpm-lock.yaml`

## Gotchas
- Turborepo кэширует по хешу входов — если результат не зависит от файла, добавьте его в `inputs` в turbo.json иначе кэш будет «слепым»
- pnpm workspaces требует `workspace:*` в version range, не `*` — иначе lock-файл ломается
- При установке нового пакета указывайте scope: `pnpm --filter web add lodash`, не `pnpm add lodash` из корня

Сравнительная таблица: какие секции включать под разные типы проектовСкопировано

Базовые шесть секций нужны всем, но акценты разные. Маленькому Flask-сервису не обязательна развёрнутая «карта структуры», монорепо без неё развалится. Ниже компактный гайд.

Если файл уезжает за 200 строк, выносите детали в .claude/rules/ с path-scoped загрузкой, как описано в официальной документации Anthropic. Тогда правила загрузятся только когда Клод откроет файлы из нужной директории, и контекст не будет забит ненужным.

7 ошибок при написании CLAUDE.mdСкопировано

Все эти ошибки мы собрали из разбора реальных репозиториев. Каждая ломает работу Клода тихо: внешне кажется, что инструкции есть, но компиляция не следует им.

Ошибка 1 — файл длиннее 200 строк

Самая частая. Команда дописывает в CLAUDE.md всё подряд, файл разрастается до 500–800 строк. Compliance rate падает с 92 % до 71 %, и Клод начинает игнорировать половину инструкций. Лечится разбиением: ядро в CLAUDE.md, специфика в .claude/rules/*.md с path-фильтрами.

Ошибка 2 — описания вместо императивов

Claude Code интерпретирует приказы «используй X», «запускай Y перед коммитом» как обязательные. А описания вроде «в проекте принято использовать X» — как информацию к сведению. Пишите в повелительном наклонении.

Ошибка 3 — копи-паст code-style гайда на 200 строк

Code style — задача линтеров. ESLint, Prettier, Ruff, Pint работают детерминированно и дешево. CLAUDE.md, который пытается заменить линтер, тратит контекст впустую. Достаточно одной строки: «Перед коммитом запускать npm run lint».

Ошибка 4 — слепое доверие /init

Команда /init генерирует черновик за 30 секунд, но этот черновик обычно мусорный: 200+ строк общих фраз, треть из них не применима. Используйте /init как стартовую точку и урезайте вдвое: всё, что не даёт конкретного действия, удаляйте.

Ошибка 5 — нет секции «Don’t touch»

Без явного запрета Клод спокойно отредактирует миграцию, перепишет lock-файл или подкрутит prod-конфиг. Один абзац с запретными зонами экономит часы откатов. Пишите капсом или жирным: НЕ РЕДАКТИРОВАТЬ: …

Ошибка 6 — устаревший CLAUDE.md

Через полгода файл описывает архитектуру, от которой команда ушла. Клод выдаёт советы «по памяти» о несуществующих сервисах. Хуже, чем отсутствие файла. Заведите ритуал: после каждого крупного рефакторинга проводите пятиминутную ревизию CLAUDE.md.

Ошибка 7 — попытка зашить в CLAUDE.md рабочий процесс

«Перед коммитом обязательно запустить тесты, потом линт, потом проверить, что миграции применились». Если шаг должен выполняться гарантированно, это не инструкция в markdown, это git-хук или CI-job. CLAUDE.md про контекст, а не про принуждение.

Как обновлять CLAUDE.md без болиСкопировано

CLAUDE.md живёт вместе с кодом. Чем активнее меняется проект, тем чаще файл устаревает. Несколько рабочих практик из разбора десятков репозиториев:

• Ревизия раз в спринт. 10 минут, открыли файл, прошли по секциям, удалили лишнее. Если в команде есть тех-лид, эта ревизия его задача.
• Запись по факту. Клод второй раз делает ту же ошибку → добавляем строку в CLAUDE.md. Это правило окупает себя за неделю.
• Синхронизация с .cursorrules и AGENTS.md. Если в команде используют несколько AI-инструментов, держите один источник истины. Anthropic поддерживает синтаксис @AGENTS.md внутри CLAUDE.md, чтобы файл подтягивался автоматически.
• Code review для CLAUDE.md. Изменения в файле проходят через PR с двумя ревьюерами, как обычный код. Это отсеивает попытки записать туда личные предпочтения вместо команды.
• Метрика compliance. Раз в месяц прогоняйте репрезентативный набор задач через Клода и считайте, сколько раз он нарушил CLAUDE.md. Если больше 15 %, пора чистить файл.

Глоссарий технических терминов, которые встречаются в шаблонах, мы собрали в словаре айтишника: полезно держать под рукой, если только начинаете работать с инструментами уровня Claude Code.

Где научиться работать с Claude Code и AI-инструментами системноСкопировано

CLAUDE.md — это только один кирпич. Чтобы освоить полный стек инструментов AI-разработки (Claude Code, Cursor, MCP, специализированные модели для кода и данных), нужны системные знания: как устроены большие языковые модели, как писать промпты, как встраивать ИИ в ежедневный workflow без потери качества.

В подборке ниже 316 курсов по нейросетям и искусственному интеллекту, от двухнедельных интенсивов для разработчиков до годовых программ с карьерным треком. Мы собрали туда всё, что закрывает три типичных запроса: «освоить инструменты», «понять как они устроены», «применить в своём проекте».

Больше программ — в полном каталоге курсов по нейросетям и искусственному интеллекту

Если хочется сначала разобраться с Claude Code глубже, почитайте сравнительный обзор «Claude Code vs Cursor: что выбрать» и разбор «MCP в Claude Code»: MCP-серверы расширяют возможности Клода доступом к БД, API и внешним сервисам поверх того, что задано в CLAUDE.md.