CLAUDE.md — это файл в корне проекта, который Claude Code автоматически читает при запуске. Он выполняет роль инструкции для AI: описывает стек, архитектуру, конвенции, команды сборки. Хорошо заполненный CLAUDE.md — это разница между AI, который знает ваш проект, и AI, который каждый раз начинает с нуля.
Зачем нужен CLAUDE.md
Без CLAUDE.md вы каждую сессию тратите время на объяснения: какой стек, как запустить, какие конвенции. С CLAUDE.md AI сразу знает: это Next.js 14 + TypeScript + Payload CMS, запуск через npm run dev, тесты через vitest, код на русском языке. Экономия — 5-10 минут на каждую сессию.
Вторая причина — консистентность. Без инструкций AI может написать один компонент с функциями, другой — с классами, третий — с другим стилем именования. CLAUDE.md фиксирует паттерны один раз, и AI следует им всегда.
Структура CLAUDE.md
Обязательные секции
Название проекта и краткое описание (1-2 строки). Стек: фреймворки, язык, БД, ORM. Команды: dev, build, test, lint. Структура папок (верхний уровень). Ключевые правила (3-5 строк).
Рекомендуемые секции
Паттерны кода: именование, стиль, обработка ошибок. Git workflow: формат коммитов, ветвление. Переменные окружения: какие нужны (без значений). Ссылки на документацию проекта. Прогресс текущей работы.
Примеры для разных стеков
Next.js + TypeScript
Укажите версию Next.js, используется ли App Router или Pages Router, какой CSS-фреймворк (Tailwind, CSS Modules), ORM (Prisma, Drizzle), CMS (Payload, Sanity). Пример: "Next.js 14, App Router, Tailwind CSS, Payload CMS, PostgreSQL. Деплой через Docker на VPS."
Python + FastAPI
Укажите версию Python, зависимости (requirements.txt или pyproject.toml), как запустить виртуальное окружение, структуру (handlers, services, models). Пример: "Python 3.12, FastAPI, SQLAlchemy 2.0, Alembic, PostgreSQL. Запуск: uvicorn app.main:app --reload."
Telegram-бот на aiogram
Укажите версию aiogram (3.x), паттерн (Router-based), FSM-стратегию, middleware. Пример: "aiogram 3.7, PostgreSQL через asyncpg, Redis для FSM, Docker Compose. Запуск: python -m bot."
Хорошие практики
Держите CLAUDE.md компактным — максимум 200 строк. Если информации больше, выносите в отдельные файлы (docs/architecture.md) и ссылайтесь. Claude Code прочитает ссылки при необходимости.
Обновляйте CLAUDE.md после каждого значимого изменения архитектуры. Устаревший CLAUDE.md хуже, чем его отсутствие — AI будет следовать неактуальным инструкциям.
Добавьте секцию ПРОГРЕСС с текущим состоянием работы. При компактификации контекста (когда окно заполняется) Claude сохранит эту секцию и продолжит с правильного места.
CLAUDE.md vs .cursorrules
CLAUDE.md — для Claude Code. .cursorrules — для Cursor. Содержание похожее, но формат отличается. Если работаете с обоими инструментами — ведите оба файла. Или создайте один PROJECT.md и ссылайтесь из обоих.
Ключевая разница: CLAUDE.md может ссылаться на другие файлы проекта, и Claude Code их прочитает. .cursorrules ограничен одним файлом. Поэтому для Cursor всё описание должно быть в одном месте.
Типичные ошибки
Слишком длинный файл (>500 строк) — Claude тратит контекст на чтение, меньше остаётся на работу. Слишком короткий файл (2-3 строки) — AI не получает достаточно контекста. Устаревшая информация — AI следует старым паттернам. Дублирование — одно и то же в CLAUDE.md и в README.