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

В этом гайде разберём структуру, которая работает на реальных проектах - от мини-проектов до монолитов.

Зачем нужен CLAUDE.md

Anthropic рекомендует создавать CLAUDE.md в корне проекта. Файл загружается автоматически при каждой сессии и влияет на все ответы Claude. Это не документация - это инструкция по взаимодействию.

Без CLAUDE.md Claude не знает ваш стиль кода, соглашения, архитектурные решения. Он генерирует код, который технически работает, но не вписывается в проект. С файлом - код сразу соответствует проекту.

Структура рабочего CLAUDE.md

Избегайте длинных описаний и общих фраз. Лучше конкретные примеры и правила. Вот минимальная структура, которая работает:

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

## Описание
Кратко: что делает проект и для кого.

## Архитектура
- Основные компоненты и их связь
- Где что лежит
- Ключевые зависимости

## Стиль кода
- Соглашения по именованию (camelCase, snake_case и т.д.)
- Как именуются файлы
- Структура импортов

## Технические правила
- Тесты живут рядом с кодом (название.spec.ts)
- Все функции типизированы
- Обязательная проверка линтером перед коммитом

## Контекст команды
- Язык общения: русский
- Какой стек
- Версии ключевых библиотек

Эта структура - каркас. Добавляйте секции под свой проект.

Примеры вместо правил

Правила в виде примеров работают лучше чем абстрактные инструкции. Вместо:

MARKDOWN 
# Плохо:
Функции должны быть небольшими и делать одну вещь.

# Хорошо:
Функции не больше 30 строк. Если больше — разбить.
Пример хорошей функции:
```typescript
function parseUserId(id: string): number {
 return parseInt(id.split(':')[1], 10);
}
```

Конкретный пример сработает лучше, потому что Claude увидит паттерн, а не абстрактное правило.

Обязательные секции для продукта

Если у вас production-проект, добавьте:

MARKDOWN 
## Безопасность
- Никаких захардкоженных учетных данных
- Все секреты из .env или менеджера секретов
- Проверка ввода на SQL-инъекции и XSS

## Обработка ошибок
- Все ошибки логируются с контекстом
- Пользователю показываем общее сообщение
- Детали в логах

## Тестирование
- Unit-тесты для критических функций
- Минимальное покрытие: 80%
- Фикстуры в отдельной папке

Секция безопасности особенно важна. AI любят генерировать код с console.log(password) или захардкоженными ключами API.

CLAUDE.md для разных ролей

Вы можете создать несколько .md файлов для разных контекстов:

MARKDOWN 
CLAUDE.md # Общий для проекта
CLAUDE_BOARD.md # Для планирования архитектуры
CLAUDE_CODE.md # Только для ревью и написания кода
CLAUDE_DEBUG.md # Для отладки

Переключайтесь через команду /project в Claude Code. Полезно когда у проекта несколько назначений.

Практические советы

Начните с малого. Не пытайтесь написать идеальный CLAUDE.md сразу. Добавьте базу, посмотрите что Claude делает не так, добавьте правило. Итеративный подход работает лучше.

Держите файл в git. CLAUDE.md - такой же код как остальное. Коммитьте изменения, пишите в сообщении коммита что изменилось.

Обновляйте после ключевых решений. Добавили новую библиотеку, изменили архитектуру — обновите файл.

Официальные рекомендации от Anthropic по использованию CLAUDE.md доступны на сайте anthropic.com .

С чего начать

Создайте файл CLAUDE.md в корне проекта. Начните с описания проекта и архитектуры. Запустите Claude Code и дайте простую задачу: добавить новую функцию. Посмотрите что он сделал не так. Добавьте правило.

Через неделю у вас будет файл, который экономит время на каждой сессии.