раздел 04 · examples

Готовые примеры CLAUDE.md

Четыре стартера под типовые проекты. Скопируйте, положите в корень репо как CLAUDE.md, поправьте детали под себя. Каждый - реальные конвенции, а не выдуманные.

1. Python-проект (FastAPI)

# project-name

Backend на FastAPI с PostgreSQL и Redis.

## Стек
- Python 3.12
- FastAPI 0.115+ (async, lifespan handlers)
- SQLAlchemy 2.0 (async, типизированные модели)
- PostgreSQL 16, asyncpg
- Redis для кеша и rate-limit
- Alembic для миграций
- pytest + pytest-asyncio для тестов

## Структура
- `app/main.py` - FastAPI app, lifespan
- `app/routers/` - роуты, по файлу на ресурс
- `app/models/` - SQLAlchemy модели
- `app/schemas/` - Pydantic-схемы для запросов/ответов
- `app/services/` - бизнес-логика, без зависимостей от FastAPI
- `app/db.py` - сессия БД
- `tests/` - pytest, фикстуры в `conftest.py`
- `migrations/` - Alembic

## Команды
- Запуск: `uvicorn app.main:app --reload --port 8000`
- Тесты: `pytest -v`
- Миграция: `alembic revision --autogenerate -m "msg"`, потом `alembic upgrade head`
- Линт: `ruff check . && ruff format .`

## Конвенции
- Везде async, sync только в utility-функциях
- Pydantic v2 синтаксис: `model_config = ConfigDict(...)`
- В роутерах - только парсинг и вызов сервиса
- Бизнес-логика в `services/`, не знает про FastAPI
- Зависимости через `Depends(get_db)`, не глобальные сессии
- Pytest фикстуры async, БД - тестовая отдельная

## Запреты
- Никакого sync SQLAlchemy
- Не использовать `BackgroundTasks` для тяжёлых задач - там Celery
- Не комитить `.env`, только `.env.example`

2. Next.js-проект

# project-name

Next.js 16 приложение с App Router, серверным рендерингом, статической генерацией страниц курса.

## Стек
- Next.js 16 (App Router, RSC)
- React 19
- TypeScript 5 (strict mode)
- Tailwind CSS 4
- MDX для контентных страниц
- pnpm для зависимостей

## Структура
- `app/` - страницы и layouts, route-handlers
- `app/components/` - переиспользуемые компоненты
- `app/lib/` - утилиты, не привязанные к UI
- `public/` - статика (картинки, fonts)
- `content/` - MDX-источники, если есть

## Команды
- Dev: `pnpm dev` (порт 3000)
- Build: `pnpm build`
- Prod-локально: `pnpm start`
- Lint: `pnpm lint`
- Type-check: `pnpm tsc --noEmit`

## Конвенции
- Server Components по умолчанию
- `"use client"` только когда нужна интерактивность или хуки
- Не использовать `getServerSideProps`/`getStaticProps` - они от Pages Router
- Маршруты - папки в `app/`, страница - `page.tsx`
- Layouts - `layout.tsx`, оборачивают сегмент
- Стили - Tailwind utility, кастомные классы в `app/globals.css`
- Никаких `<img>` - только `next/image`

## Деплой
- Docker, прод-образ `node:20-alpine`
- Stage и prod - через GitHub Actions, `main` -> auto deploy
- Env: `NEXT_PUBLIC_*` для клиента, остальное только на сервере

3. Монорепо с pnpm workspace

# project-name

Монорепо: web (Next.js), api (FastAPI), shared (общие типы и утилиты).

## Стек
- pnpm workspaces (см. `pnpm-workspace.yaml`)
- Turborepo для оркестрации тасков
- TypeScript везде, где возможно
- changesets для версионирования shared-пакетов

## Структура
- `apps/web/` - Next.js фронтенд
- `apps/api/` - FastAPI бэкенд (Python, отдельная экосистема)
- `packages/ui/` - React-компоненты, общие на нескольких фронтах
- `packages/types/` - TS-типы, сгенерированные из OpenAPI
- `packages/config/` - shared конфиги (eslint, tsconfig)
- `infra/` - Dockerfile, docker-compose, terraform

## Команды
- Установка всех зависимостей: `pnpm install` в корне
- Запуск всего: `pnpm dev` (turbo поднимет web и api параллельно)
- Запуск только web: `pnpm --filter web dev`
- Билд всего: `pnpm build`
- Тесты: `pnpm test` (бежит по всем workspace где есть test script)
- Генерация типов из API: `pnpm --filter types generate`

## Конвенции
- Не делать прямых импортов между apps - только через `packages/`
- Версии packages - через changesets, не руками
- Общие конфиги (`tsconfig.base.json`, `eslint.config.js`) - в `packages/config`
- В каждом package свой `package.json` с минимальным набором deps
- Кросс-зависимости фиксируются через `workspace:*` в `package.json`

## Деплой
- Web и API деплоятся независимо
- Один общий Docker-network для локального запуска
- Прод - Kubernetes, манифесты в `infra/k8s/`

4. AI-проект с Anthropic SDK

# project-name

Сервис для классификации текстов и генерации ответов через Claude API.

## Стек
- Python 3.12
- anthropic SDK (актуальная версия)
- FastAPI как HTTP-обёртка
- Redis для prompt cache TTL и rate-limit
- pytest с моками для тестов без реальных API-вызовов

## Структура
- `app/main.py` - FastAPI app
- `app/llm/` - всё что связано с Claude: клиент, промпты, утилиты
- `app/llm/client.py` - инициализация `AsyncAnthropic`
- `app/llm/prompts/` - system prompts как отдельные файлы (.md или .txt)
- `app/services/` - бизнес-логика, использует `app/llm/`
- `app/routers/` - HTTP endpoints
- `tests/` - pytest, моки SDK через `pytest-mock`

## Модели
- Основная: `claude-haiku-4-5` для дешёвой и быстрой классификации
- Сложная логика: `claude-sonnet-4-7` для качественных ответов
- Не использовать deprecated модели (claude-3-*, claude-2-*) - они выведены

## Промпты и кеширование
- System prompts всегда кешируются (`cache_control: ephemeral`)
- Большие справочники - тоже в кешируемый блок
- Минимум 1024 токенов в блоке для кеша Haiku (для Sonnet/Opus - выше порог)
- Замеряем cache_read_input_tokens и cache_creation_input_tokens в ответе

## Конвенции
- Везде `AsyncAnthropic`, никаких sync клиентов
- API-ключ только через env: `ANTHROPIC_API_KEY`
- Retry на 429 и 529 - встроенный в SDK достаточный
- Graceful degradation: если API недоступен - возвращаем дефолт, не падаем
- Логировать `usage` (input/output tokens) для биллинга

## Прокси (если из РФ)
- Все вызовы Anthropic идут через DO-прокси
- Конфиг прокси в env: `HTTPS_PROXY=http://188.166.23.110:3128`
- На сервере прокси-доступ открыт только с whitelisted IP

## Запреты
- Не хранить промпт-историю клиента в logs (PII)
- Не использовать temperature > 1.0
- Не делать длинные цепочки tool_use без обрыва по таймауту

Полезные ссылки

  • Memory docs - официальная документация
  • Awesome Claude Code - подборка реальных CLAUDE.md из open-source проектов