CLAUDE.md файл: настройка за 15 минут

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

Что такое CLAUDE.md и как он работает

Если ты уже пользуешься Claude Code как инструментом, то знаешь ситуацию: открываешь новую сессию — и агент снова не знает, что у тебя за проект. Приходится заново объяснять стек, команды, договорённости. Это не баг, это архитектура: каждая сессия начинается с чистого контекста.

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

Технически это просто Markdown-файл. Никакого специального синтаксиса, никаких JSON-схем. Пишешь обычный текст с заголовками — и агент его понимает.

Ключевое отличие от промптаТекст задачи, который вы пишете нейросети, — от него зависит, что она вам вернёт. в чате: CLAUDE.md живёт в репозитории. Это значит, он версионируется вместе с кодом, его видят все разработчики команды, и при клонировании репо новый человек сразу получает настроенного агента.

Структура: что писать в CLAUDE.md

Нет единого стандарта, но практика показала, что работают четыре секции. Всё, что за их пределами, — вода, которая разбавляет контекст.

Секция «Запреты» — самая недооценённая. Напиши: «не изменяй файлы в /dist», «не трогай конфиги в /infra», «не коммить в master без разрешения». Это не про ограничение, это про то, что агент не может видеть замысел: он отрефакторит сгенерированную папку и не поймёт, что она генерируется на CI.

Как писать: императивы вместо описаний

Самая частая ошибка в CLAUDE.md — общие фразы из вакансий. «Следуем современному подходу», «используем чистую архитектуру», «важно поддерживать качество кода». Это не работает, потому что агент не отличает «как надо в целом» от «как надо здесь».

Рабочее правило: пиши так, будто даёшь команду новичку на собеседовании. Никакой рефлексии — только действия.

Проверяется просто: замени слово «агент» на «стажёр». Если фраза звучит нормально как задача стажёру — она рабочая. Если звучит как мотивационная речь — переписывай.

Вторая часть — формат WHY/WHAT/HOW. Не обязательно для всего, но когда правило неочевидное, добавь одну строку почему оно есть:

- Не используем var в JS
  why: летающие скобочные ошибочки в старых вендорах

Агент запоминает причину и не будет спорить, когда правило кажется ему нелогичным.

Большой CLAUDE.md: как не сгореть в одном файле

Есть понятный страх: весь проект — в один файл, а он распух до 800 строк. Тогда каждое сообщение агента несёт в себе простыню, которая съедает и контекст, и внимание к деталям.

Решение — иерархия. Claude Code читает ближайший CLAUDE.md относительно рабочей папки. Поэтому раскладываешь правила по модулям:

• CLAUDE.md в корне — только общее: стек, версии, корневая сборка, глобальные запреты
• frontend/CLAUDE.md — правила по React: компонентные паттерны, стилизация, тесты
• api/CLAUDE.md — правила по бэкенду: слои, подключение к БД, аутентификация

Одну директорию можно разбить дальше: frontend/src/components/CLAUDE.md — только про компоненты, frontend/src/store/CLAUDE.md — только про стейт-менеджмент.

Когда ты находишься в /frontend, агент видит и корневой, и локальный файл. Кладёшь в локальный только то, что не касается остального проекта, — и никакой беготни с большим файлом.

Примеры: три типа проектов

Теперь самое вкусное — как это выглядит в реальности. Вот три шаблона под разные ситуации. Не копируй вслепую, подправь под свой стек.

API-бэкенд

# Проект
Python 3.12, FastAPI, SQLAlchemy, PostgreSQL.

## Команды
- Запуск: `uvicorn app.main:app --reload`
- Тесты: `pytest -q`
- Линтер: `ruff check .`
- Миграции: `alembic upgrade head`

## Соглашения
- 4 пробела. Без типизации не пишем.
- Слой API не импортирует SQL. Только через сервисы.
- Ошибки на русском, сообщения в логах — на английском.

## Нельзя
- Не трогать `/migrations` в PR руками — только через
alembic.
- Не менять контракты API без пометки в CHANGELOG.

React-фронт

# Проект
React 19, TypeScript, Vite, Tailwind.

## Команды
- Запуск: `npm run dev`
- Сборка: `npm run build`
- Тесты: `npm test`

## Соглашения
- Функциональные компоненты, hooks в начале.
- Стили — только через классы Tailwind, без встроенных
стилей.
- Всё, что тяжелее 20 строк и повторяется, — выносим в
`/components`.

## Нельзя
- Не добавлять новые зависимости без согласования.
- Не менять конфиги Vite без комментария.

Монорепо

# Проект
Монорепо: /apps/web, /apps/api, /packages/shared.

## Команды
- Установка: `pnpm install`
- Все тесты: `pnpm test`
- Один пакет: `pnpm --filter @app/web test`

## Соглашения
- Изменения в /packages/shared всегда коммичим отдельно.
- Версии пакетов — semver, minor не тянет breaking.
- CI запускается на все три пакета — проверяй локально весь.

## Нельзя
- Не импортировать /apps/web в /apps/api.
- Не пушить в main без открытого PR.

Видишь, как меняется фокус: у API главное — слои и миграции, у фронта — стили и связи, у монорепо — границы между пакетами. Это и есть настроенный агент.

Валидация: как проверить, что агент реально следует правилам

Всё хорошо, пока файл написан. Но откуда знать, что агент его читает, а не просто вежливо говорит «да, использую»?

Три проверки, дешевле и не требуют магии.

Первая — контрольный вопрос. После старта сессии спроси без контекста: «Какой стек у проекта?» или «Какая команда запускает тесты?». Если он отвечает из CLAUDE.md — то, что надо, файл работает. Если отвечает «не уверен» — файл не подхватился, проверяй путь и название.

Вторая — нестандартное правило. Добавь в CLAUDE.md правило, которое выглядит глупо, но проверяемо: «В этом проекте все названия функций в camelCase с префиксом app». Затем попроси написать простую функцию. Если она с префиксом — агент прочитал файл. Если нет — он его игнорирует.

Третья — бекдор через git. Смотри на изменения, которые агент предлагает. Если он уважает запреты из CLAUDE.md, в диффах не будет захода в запрещённые папки. Начнёт переписывать /dist — значит правило не дочитано, даже если он на вопросы отвечает правильно.

Версионирование и команда: чтобы правила не расходились

Одна из самых противных вещей — когда CLAUDE.md есть, а команда им не пользуется потому, что каждый сидит на своей версии. Синхронизация решается той же механикой, что и код.

• Храни CLAUDE.md в git — тогда у всех одна версия, diff по правилам виден в обычном git diff.
• Обновляй после крупных изменений — выкинули ORM, добавили новый фреймворк — сначала в CLAUDE.md, потом в код. Иначе агент будет советовать старое.
• Кладём изменения правил в тот же PR, что и изменение стека. Реально помогает: непонятно, зачем правила меняются — смотришь PR и всё ясно.
• В крупных командах — один владелец файла. Не «все могут менять, кто хочет», а один человек согласует правки. Иначе за месяц правила превратятся в свалку.

Частые ошибки: три случая, когда CLAUDE.md вредит

Иногда файл не помогает, а мешает. Вот что я видела на чужих проектах чаще всего.

Слишком много текста. 200 строк общих рассуждений о «быть лучше» — и агент реально начинает отвечать в этом духе, вместо работы. Рабочий файл — это не манифест, а чек-лист.

Правила-зубодробилки, противоречащие сами себе: в одном месте «инлайн-стили не использовать», в другом — «для быстрых решений оставляй инлайн». Агент в тупике, потому что не умеет «чувствовать разницу». Если противоречие — решай и пиши однозначно.

Секреты в файле. CLAUDE.md лежит в репо. Если положишь туда пароль или ключ — он уедет в git и найдёт всех. Секреты только в переменных окружения. И в CLAUDE.md напиши правило: «ключи и пароли читать только из env, не логировать» — это и инструкция для агента, и защита от случайного вывода токенов в лог.

Чек-лист: что у тебя теперь есть

• Знаю, что такое CLAUDE.md и зачем он нужен в проекте
• Понимаю, из каких секций состоит рабочий файл
• Умею написать его под три разных типа проектов
• Знаю, как проверить, что агент реально следует инструкциям
• Понимаю, как разбивать большой CLAUDE.md на модули
• Храню файл в git и обновляю его вместе с кодом

Вывод

CLAUDE.md — это не «ещё один конфиг», это способ один раз объяснить агенту, как устроен твой проект, и забыть о повторениях. Полчаса на настройку — и Claude Code больше не переспрашивает стек, не смотрит в пустоту и не сносит запрещённые папки. Это первый шаг к тому, чтобы агент реально работал, а не просто помогал.

Я, Арина Михална, всегда начинаю любой новый проект именно с этого файла — раньше, чем с кода. Потому что потом, когда просишь что-то поменять, агент уже знает контекст, а не заново вытаскивает его из твоих сообщений. Остальное дело за привычкой обновлять его вместе с развитием проекта. А чтобы постоянно быть в курсе, как выстраивать работу с Claude и кодом — заглядывай в мой канал. Там разбираю на живых примерах, что реально меняет работу: переходи в канал.

Читайте также

• Claude загрузить PDF файл за минуты
• Claude проекты и память: настроить под себя
• Второй мозг в Obsidian: зачем нужен, кому не подходит и как настроить за 5 минут
• Субагенты Claude Code: как поручить рутину
• В личном блоге Арины Михалны: Настройка проекта в Claude Code в 2026: структура и конфиги

По материалам: официальная документация Claude Code, тарифы Claude.## FAQ

Что такое CLAUDE.md файл и зачем он нужен?

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

Как проверить, что Claude Code следует инструкциям из CLAUDE.md?

Попроси агента назвать стек проекта или команду для запуска тестов — если он берёт данные из файла, ответит точно. Ещё проверка: добавь нестандартное правило (например, «не использовать var в JS») и посмотри, соблюдает ли он его в следующем изменении кода.

Что писать в CLAUDE.md для Claude code настройки проекта?

Стек и версии, команды сборки и тестов, соглашения по коду, структуру папок, что нельзя трогать. Чем конкретнее — тем лучше. Избегай описаний в стиле «используется современный подход», пиши императивами: «запускай тесты через npm test», «не изменяй файлы в /dist».

Можно ли хранить Claude code инструкции для проекта в нескольких файлах?

Да. Кладёшь общий CLAUDE.md в корень, а дополнительные правила для отдельных модулей — в поддиректории, например frontend/CLAUDE.md или api/CLAUDE.md. Claude Code читает ближайший CLAUDE.md от текущего рабочего каталога.

Что делать, если CLAUDE.md большой и агент путается?

Разбей на модули: CLAUDE.md в корне — только общее (стек, запрет на прямую запись в prod), а специфика по компонентам — в поддиректориях. Ещё помогает разделение на секции с чёткими заголовками: агент лучше находит нужный раздел.