Что такое CLAUDE.md
CLAUDE.md. Это текстовый файл, который Claude Code читает перед каждым ответом. Всё, что вы туда запишете, становится постоянной инструкцией для агента. Промпт приходится повторять. Системное сообщение теряется через 10 минут. А CLAUDE.md остаётся. Постоянная память проекта.
По сути это конституция: набор правил, которые Claude обязан соблюдать при работе с вашим кодом. Один раз написали, дальше агент сам знает ваш стек, ваши команды, ваши запреты.
Где лежит файл
Три уровня, от общего к частному:
- ~/.claude/CLAUDE.md (глобальный). Действует во всех проектах. Сюда идут ваши личные предпочтения: язык общения, стиль ответов, общие запреты.
- CLAUDE.md в корне проекта (проектный). Действует для всех, кто работает с этим репозиторием. Коммитится в git. Сюда идёт стек, архитектура, код-стайл.
- .claude/CLAUDE.md (локальный проектный). Ваши личные настройки для конкретного проекта. Добавляется в .gitignore.
Claude Code объединяет все три уровня. Проектный файл не перезаписывает глобальный, они работают вместе.
Минимальный рабочий CLAUDE.md
Не нужно писать роман. Вот файл, который уже приносит пользу:
# Проект: My App
## Стек
- Next.js 15 (App Router), TypeScript, Tailwind
- БД: Supabase (PostgreSQL)
- Деплой: Vercel
## Команды
- npm run dev # локальный сервер
- npm run build # проверка сборки
- npm run lint # линтер
## Правила кода
- Язык интерфейса: русский
- Компоненты: функциональные, без class components
- Импорты: абсолютные через @/15 строк. Claude теперь знает ваш стек и не предложит Express вместо Next.js или MySQL вместо Supabase.
Структура хорошего файла
Разбивайте на секции с понятными заголовками:
- Стек и архитектура. Фреймворк, ORM, основные библиотеки. Структура папок, если нестандартная.
- Команды. Как запустить dev-сервер, тесты, линтер, сборку. Claude будет использовать именно их.
- Код-стайл. Именование файлов, структура компонентов, предпочтения по импортам.
- Запреты. Чего Claude не должен делать. "Не используй any в TypeScript". "Не создавай файлы в корне". "Не коммить .env".
- Контекст проекта. Роли пользователей, ключевые сущности, бизнес-логика, которую агент должен учитывать.
Антипаттерны
Файл на 200+ строк
Чем длиннее CLAUDE.md, тем больше контекстного окна он съедает. Каждая строка отнимает место у вашего реального диалога. Будьте безжалостны к объёму.
Копирование чужого файла целиком
Чужой CLAUDE.md написан под чужой проект, чужой стек и чужие привычки. Скопировать и вставить = загрузить агента нерелевантными правилами. Берите идеи, но пишите под себя.
Противоречащие правила
"Пиши короткие функции" + "Не разбивай логику на мелкие функции". Claude не скажет вам об этом, просто будет хаотично выбирать одно из двух.
Главное правило
Если убрать строку из CLAUDE.md и Claude всё равно не ошибётся, эта строка не нужна.
Не пишите очевидное. "Используй TypeScript" в TypeScript-проекте. "Пиши чистый код". "Следуй best practices". Это мусор, который размывает действительно важные инструкции.
Пример для реального проекта
# Проект: AI Community Platform
## Стек
- Next.js 15 App Router, TypeScript strict, Tailwind + shadcn/ui
- Supabase: PostgreSQL, Auth через кастомные сессии
- Деплой: Vercel с ветки master
## Архитектура
- Route groups: (public) для открытых страниц, (members) для закрытых
- Сессии: кастомные JWT cookies через lib/session.ts
- Роли: free, member, admin
- Серверные компоненты по умолчанию, "use client" только при необходимости
## Команды
- npm run dev # локальная разработка
- npm run build # проверка перед деплоем
- npx supabase db push # применить миграции
## Запреты
- Не использовать any, только явные типы
- Не коммитить .env и ключи
- Не менять схему БД вручную, только через миграции в supabase/migrations/
- Не создавать API routes там, где достаточно Server Action
## Стиль
- Язык интерфейса: русский
- Компоненты: один файл = один компонент
- Именование файлов: kebab-caseЭтого достаточно, чтобы Claude Code работал с проектом так, будто он читал всю документацию. Начните с минимума, добавляйте правила только когда агент реально ошибается без них.