Файл CLAUDE.md: как настроить проект для Claude Code

Что такое файл CLAUDE.md, зачем он нужен и как написать рабочий файл настройки проекта. Примеры структуры и готовые шаблоны.

Зачем это нужно

Представь: ты каждый раз объясняешь новому помощнику одно и то же. Как называется проект. Про что он. Что ни в коем случае нельзя трогать. В каком стиле писать тексты.

С Claude Code то же самое. Без настройки ты тратишь первые минуты каждой сессии на контекст: объясняешь, что это за проект, где что лежит, что уже сделано. Claude не помнит прошлые разговоры — каждый раз начинает с нуля.

CLAUDE.md — это решение. Обычный текстовый файл в папке твоего проекта, который Claude Code читает автоматически при старте. Ты один раз описываешь проект — и больше не повторяешься.

Особенно критично, если:

ты работаешь над одним проектом несколько недель подряд
у проекта есть правила, которые не очевидны со стороны
ты хочешь, чтобы Claude не переделывал то, что ты явно не просил

Не получается с установкой или первым CLAUDE.md — напиши: /consult. Разберём на живом примере.

Как это работает

Claude Code ищет файл с именем CLAUDE.md в трёх местах, от общего к конкретному:

~/.claude/CLAUDE.md — твои личные правила, применяются ко всем проектам.
CLAUDE.md в корне проекта — правила этого конкретного проекта.
CLAUDE.md в подпапке — правила для части проекта (например, только для папки с текстами).

Когда ты открываешь папку проекта во вкладке Code, Claude читает все найденные CLAUDE.md файлы и соединяет в один контекст. Более конкретные правила перекрывают общие.

Формат файла — Markdown. Это простой текстовый формат с лёгкой разметкой: решётки # в начале строки — это заголовки, тире - — пункты списка, тройные бэктики ``` — блоки с командами или кодом. Всё. Никаких сложных настроек, никаких отдельных форматов — просто текст, который ты пишешь словами.

Что писать в CLAUDE.md

Хороший CLAUDE.md отвечает на три вопроса: что это за проект, как с ним работать, что нельзя делать.

Блок 1: О чём проект

Одно-два предложения. Claude должен понять, что это, для кого и зачем.

Блок 2: Как запускать и проверять

Какие команды Claude должен знать, чтобы сам мог запустить твой проект, собрать его, проверить. Без этого он будет гадать и зависать на ошибках.

Блок 3: Правила и ограничения

Самая важная часть. Что нельзя трогать, в каком стиле писать, какие паттерны использовать, на каком языке тексты.

Блок 4: Структура (для больших проектов)

Краткая карта: где что лежит. Claude перестаёт теряться в незнакомой папке.

Пример 1: CLAUDE.md для сайта-каталога

Допустим, ты делаешь личный сайт — портфолио или каталог своих клиентов. Вот как может выглядеть CLAUDE.md:

# Проект: Мой каталог клиентов

Личный сайт со списком клиентов, с которыми я работал. Один владелец (я),
публичная витрина для новых клиентов. Должен открываться на телефоне и ноутбуке.

## Как запускать
- Чтобы посмотреть сайт у себя: скажи мне "запусти сайт и открой в браузере"
- Чтобы собрать финальную версию: скажи "собери сайт для публикации"

## Правила
- Все тексты — на русском
- НЕ менять файлы в папке с готовой сборкой (dist) — это результат, а не исходник
- Новые страницы добавлять в папку pages/
- Картинки клиентов — в public/clients/
- Перед тем как предложить сложное решение — сначала проверь, нет ли в проекте
  чего-то похожего, чтобы не делать одно и то же дважды

## Структура
pages/      — страницы сайта
components/ — переиспользуемые блоки (шапка, карточка клиента, подвал)
content/    — тексты и данные о клиентах
public/     — картинки, иконки, файлы для скачивания

Что тут важно. В разделе «Как запускать» нет технических деталей — только то, как ты сам будешь говорить с Claude Code. Он сам знает, какие команды запускать, если ты один раз сказал ему, что этот сайт — например, на Astro.

Пример 2: CLAUDE.md для рабочего проекта без кода

CLAUDE.md нужен не только разработчикам. Вот пример для проекта, где ты ведёшь исследование или готовишь контент:

# Проект: Исследование рынка онлайн-школ

Я собираю данные о 20 онлайн-школах для клиента. Итог — отчёт на 15 страниц
и презентация. Работаю одна, клиент видит только финальный отчёт.

## Структура
raw/        — сырые данные: скриншоты, выгрузки, ссылки
notes/      — мои заметки и черновики по каждой школе
drafts/     — черновики разделов отчёта
final/      — финальные версии (туда пишем только когда готово)
sources.md  — все использованные источники со ссылками

## Правила
- Язык всех текстов — русский
- Все утверждения о числах — только со ссылкой на источник в sources.md
- НЕ удалять файлы из raw/ — это исходные данные, они нужны для проверки
- Если я прошу переписать кусок отчёта — показывай сначала 2-3 варианта,
  не сразу финальный
- Цитаты из источников оформлять в кавычках с указанием школы

## Стиль отчёта
- Короткие абзацы (3-5 строк)
- Никаких оценочных слов типа "лучший", "ведущий" — только факты
- Сравнительные таблицы вместо списков, где это возможно

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

Чего НЕ писать

Распространённая ошибка — пытаться описать всё подряд. Хороший CLAUDE.md умещается на одну-две страницы. Больше — значит хуже: Claude тратит внимание на балласт, а не на реальную задачу.

Не дублируй очевидное:

Не надо объяснять, что такое Markdown или как работает веб-сайт. Claude это знает.
Не надо пересказывать стандартные правила хорошего стиля — они в него уже встроены.

Не пиши:

Историю проекта и как ты к нему пришёл.
Планы на будущее и список “хотелок”.
Личные предпочтения, которые не влияют на то, что Claude делает.

Принцип проверки. Перечитай каждую строку и спроси: “Claude сделает что-то не так, если этой строки не будет?” Если нет — удаляй.

Глобальный и проектный CLAUDE.md

Глобальный файл ~/.claude/CLAUDE.md — это твои личные правила, которые работают в любом проекте:

# Мои правила

## Как общаться
- Отвечай на русском
- Перед тем как делать большие изменения — коротко опиши, что собираешься сделать
- Если я написал что-то неоднозначное — переспроси, не угадывай
- Коммиты делай только когда я явно прошу (коммит = точка сохранения
  в истории изменений проекта)

## Стиль работы
- Сначала покажи план, потом действуй
- Не добавляй функции, о которых я не просил

Проектный CLAUDE.md — это то, что касается конкретного проекта: что за проект, правила именно для него, структура папок.

Оба файла читаются вместе. Если они противоречат друг другу — проектный сильнее.

Готовый шаблон

Скопируй и адаптируй под свой проект:

# Проект: [Название]

[1-2 предложения: что это, для кого, главная задача]

## Как запускать
- [Что сказать Claude, чтобы он запустил или собрал проект]

## Правила
- [важное правило или ограничение]
- [важное правило или ограничение]
- НЕ [что нельзя трогать]

## Структура
[папка/] — [что там]
[папка/] — [что там]

## Не трогать без явного запроса
- [файлы или папки]

Как улучшить существующий CLAUDE.md

Если файл уже есть, но Claude всё равно ведёт себя не так — проверь три вещи.

Команды актуальны? После того как ты перенёс проект или переименовал что-то, старые команды в CLAUDE.md будут ломать работу.

Правила конкретны? “Пиши чистый код” — это не правило. “Все тексты только на русском, английские термины в скобках” — правило. Чем конкретнее — тем предсказуемее результат.

Нет ли противоречий? Если в глобальном файле одно, а в проектном другое — Claude будет гадать, что важнее. Явно скажи, что главное.

Для тех, кто хочет разобраться в технических деталях

Зачем вообще отдельный файл, если можно писать всё в чате? У Claude ограничено “окно внимания” — сколько текста он может держать в голове одновременно. CLAUDE.md подгружается один раз и компактно занимает место в начале; если ты повторяешь то же самое в каждом сообщении чата, ты забиваешь окно балластом и у Claude остаётся меньше места на реальную задачу.

Что из настроек Claude читать не надо описывать? Если в проекте есть стандартные файлы с правилами форматирования (для программистов это, например, .eslintrc, prettier.config.js) — их не надо пересказывать в CLAUDE.md. Claude Code читает их напрямую.

Subagents — что это и при чём тут CLAUDE.md? Subagent (субагент) — это “помощник помощника”: Claude Code может запускать параллельные копии самого себя на отдельные куски задачи. Например, один субагент пишет тексты, другой проверяет ссылки. CLAUDE.md может задавать правила и для них тоже — про это будет отдельный гайд.

Следующий шаг

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

Застрял на настройке или не уверен, что писать в CLAUDE.md — напиши: /consult. Разберём на твоём проекте.