> ## Content Index
> Fetch the complete content index at: https://matveev.tech/llms.txt
> Use this file to discover other available public pages before exploring further.

# CLAUDE.md — как писать инструкции для Claude Code
- URL: https://matveev.tech/claude-md-instruktsii-claude-code/
- Published: 2026-02-10T08:54:48.000Z
- Updated: 2026-02-10T08:54:48.000Z
- Description: CLAUDE.md — файл с инструкциями, который Claude Code загружает при старте. Разбираемся, как его правильно написать.
- Author: Pavel Matveev
- Tags: Claude Code, Claude, Dev Tools, Гайд

> **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 не видит весь код сразу — он подгружает файлы по мере необходимости. Краткое описание помогает ему ориентироваться.

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

```

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

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

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

```

### Правила кода

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

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

```

### Запреты

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

```markdown
## Запрещено
- НЕ используй `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 его игнорирует.

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

- [Настройка Claude Code — полный гайд по settings.json](https://matveev.tech/claude-code-settings-json/) — общая настройка Claude Code
- [Разрешения в Claude Code — allow, deny и sandbox](https://matveev.tech/claude-code-permissions-sandbox/) — что Claude может и чего не может
- [MCP серверы для Claude — что это и как настроить](https://matveev.tech/claude-mcp-nastrojka/) — расширение возможностей через MCP
- [Claude Code для нетехнарей — 50 способов применения](https://matveev.tech/claude-code-bez-koda/) — если используешь Claude Code не для программирования