Claude

CLAUDE.md — как писать инструкции для Claude Code

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

Pavel Matveev

Pavel Matveev

— 3 min read
CLAUDE.md — как писать инструкции для Claude Code
TL;DR: CLAUDE.md — это файл, который Claude Code читает при каждом запуске. В нём ты описываешь проект, стек, правила и контекст. Без него Claude работает вслепую. С ним — понимает, что можно, а что нельзя, и пишет код так, как принято у тебя в проекте.

Есть одна штука, которую многие пропускают при настройке Claude Code. Claude что-то генерит, но результат — мимо. Не тот стиль кода, не те библиотеки, не те конвенции. Проблема не в модели. Проблема в том, что ты не рассказал ей про свой проект.

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

Где хранить CLAUDE.md

У Claude Code есть система скоупов. Файл можно положить в разные места, и это меняет его область действия:

  • ~/.claude/CLAUDE.md — глобальный. Работает для всех проектов. Сюда стоит писать общие предпочтения: язык ответов, стиль кода, персональные правила.
  • CLAUDE.md в корне репозитория — проектный. Работает для этого конкретного проекта. Коммитится в git, доступен всей команде.
  • .claude/CLAUDE.md — альтернативное расположение проектного файла. Если не хочешь засорять корень.
  • CLAUDE.local.md — локальный. Только для тебя, git его игнорирует. Для личных заметок и экспериментов.

Приоритет: глобальный загружается первым, потом проектный, потом локальный. Все три работают одновременно и дополняют друг друга.

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

Нет жёсткого формата. Это просто markdown-файл, и Claude интерпретирует его содержимое как инструкции. Но есть проверенная структура, которая работает хорошо.

Описание проекта

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

## Проект
Бэкенд API для маркетплейса на Python 3.12 + FastAPI + SQLAlchemy 2.0.
База данных — PostgreSQL 16. Деплой через Docker + Kubernetes.

Команды для разработки

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

## Команды
- Тесты: `pytest tests/ -v`
- Линтер: `ruff check . --fix`
- Формат: `ruff format .`
- Миграции: `alembic upgrade head`

Правила кода

Конвенции, которые сложно вывести из кода автоматически. Например, что у вас принято использовать dataclasses вместо Pydantic для внутренних моделей, или что все API-эндпоинты должны возвращать JSON в определённом формате.

## Правила
- Все эндпоинты возвращают `{"data": ..., "error": null}` формат
- Используй `loguru` вместо стандартного `logging`
- Тесты через `pytest` с фикстурами, без моков где возможно
- Коммиты на русском языке

Запреты

Иногда важнее сказать, чего делать не нужно. Claude склонен предлагать популярные решения, даже если в проекте принято иначе.

## Запрещено
- НЕ используй `print()` для логирования
- НЕ добавляй `type: ignore` комментарии
- НЕ меняй конфиги в `deploy/` без явного запроса

Антипаттерны

Несколько вещей, которые я пробовал и которые не работают:

Слишком длинный CLAUDE.md. Если файл на 3000 строк — он сжирает контекстное окно. Лучше быть лаконичным. 100-300 строк обычно достаточно.

Противоречивые инструкции. Если в глобальном CLAUDE.md написано «используй tab», а в проектном «используй spaces» — Claude запутается. Проверяй, чтобы скоупы не конфликтовали.

Копипаст документации. Не нужно вставлять в CLAUDE.md всю документацию по фреймворку. Claude и так знает Python, React, Go. Пиши только то, что специфично для твоего проекта.

Отсутствие обновлений. CLAUDE.md — живой документ. Если ты поменял стек или конвенции — обнови файл. Устаревшие инструкции хуже, чем никаких.

Auto Memory — автоматическое запоминание

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

Auto memory сохраняет контекст из сессий: что за проект, какие решения принимались, какие паттерны предпочитаете. Управляется переменной CLAUDE_CODE_DISABLE_AUTO_MEMORY — если не нравится, можно отключить.

Но я бы не полагался только на auto memory. Явный CLAUDE.md с продуманной структурой всегда лучше, чем автоматически собранные обрывки из разговоров.

Часто задаваемые вопросы

Claude Code не видит мой CLAUDE.md — что делать? Проверь расположение файла. Он должен быть в корне проекта, в ~/.claude/ для глобального, или в .claude/ для проектного. Claude Code загружает файлы при старте — перезапусти сессию после создания.

Можно ли использовать CLAUDE.md в дополнительных директориях? По умолчанию нет. Но если выставить переменную CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1, Claude Code будет загружать CLAUDE.md из директорий, указанных через --add-dir.

Какой максимальный размер CLAUDE.md? Формального лимита нет, но каждое слово занимает контекстное окно. Рекомендую держаться в пределах 100-300 строк. Если нужно больше — скорее всего, стоит вынести часть в отдельные файлы и ссылаться на них.

Видит ли команда мой CLAUDE.md? Зависит от расположения. CLAUDE.md в корне проекта коммитится в git — команда его увидит. CLAUDE.local.md — только для тебя, git его игнорирует.

Что ещё почитать