К этому моменту мысль прозвучала уже несколько раз: постоянные правила проекта нельзя держать в переписке. Они теряются при сжатии контекста, исчезают при очистке и не переживают перезапуск сессии. Каждый новый заход начинается с того, что вы заново объясняете агенту, какой командой запускаются тесты, где лежат обработчики API и почему в этом проекте не используется определённая библиотека.

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

Что уже умеем / что добавим

Вы знаете, что CLAUDE.md попадает в контекст при старте, видели его в разделе Memory files команды /context и убедились, что он переживает сжатие. Теперь создадим его: разберём команду /init, места хранения файлов инструкций и принципы, по которым пишутся работающие правила.

Что вы узнаете в рамках статьи

• Что делает команда /init и что она генерирует
• Где могут лежать файлы CLAUDE.md и как они складываются друг с другом
• Что стоит записывать в файл, а что только вредит
• Как проверить, что файл загрузился и правила работают
• Почему CLAUDE.md — это контекст, а не жёсткая настройка

Ключевые термины

• CLAUDE.md — markdown-файл с постоянными инструкциями для Claude, загружаемый в контекст в начале каждой сессии.
• /init — команда, которая анализирует кодовую базу и создаёт стартовый CLAUDE.md с найденными командами сборки, тестирования и соглашениями.
• Пользовательский CLAUDE.md — файл ~/.claude/CLAUDE.md с личными предпочтениями, действующими во всех ваших проектах.
• Проектный CLAUDE.md — файл ./CLAUDE.md или ./.claude/CLAUDE.md, общий для команды и хранящийся в системе контроля версий.
• CLAUDE.local.md — личные предпочтения для конкретного проекта; добавляется в .gitignore и не попадает в репозиторий.
• Импорт — подключение содержимого другого файла синтаксисом @путь/к/файлу внутри CLAUDE.md.
• /memory — команда для просмотра и редактирования файлов инструкций во всех областях видимости.

Что делает /init

Начинать с чистого листа не нужно. Команда /init анализирует проект и создаёт стартовый файл сама:

> /init

Claude Code изучает кодовую базу и записывает в CLAUDE.md то, что смог обнаружить: команды сборки и запуска тестов, структуру проекта, замеченные соглашения. Если файл уже существует, /init не перезаписывает его, а предлагает улучшения.

Заодно команда подхватывает конфигурацию других инструментов, если она есть в репозитории: правила Cursor из .cursor/rules/ или .cursorrules и инструкции Copilot из .github/copilot-instructions.md. Их относящиеся к делу части попадают в сгенерированный файл.

Важно понимать, что результат /init — это черновик, а не готовый документ. Команда записывает то, что можно вывести из кода, а самое ценное содержимое CLAUDE.md — как раз то, чего из кода не видно: почему в проекте принято одно решение вместо очевидного другого, какие переменные окружения обязательны, где спрятаны нетипичные подводные камни. Это дописываете вы.

Где лежат файлы инструкций

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

• ~/.claude/CLAUDE.md — ваши личные предпочтения, действующие во всех проектах на этой машине.
• ./CLAUDE.md или ./.claude/CLAUDE.md — инструкции проекта, общие для команды. Этот файл коммитится в репозиторий.
• ./CLAUDE.local.md — ваши личные заметки по конкретному проекту: адреса песочниц, предпочитаемые тестовые данные. Добавляется в .gitignore.

Claude Code загружает CLAUDE.md и CLAUDE.local.md из рабочей директории и всех директорий выше неё. Если вы запустились в foo/bar/, загрузятся инструкции и из foo/, и из foo/bar/. Порядок — от корня файловой системы вниз, поэтому инструкции ближе к месту запуска читаются последними.

Файлы в поддиректориях ниже рабочей тоже обнаруживаются, но загружаются не сразу: они подключаются, когда Claude читает файлы из этих поддиректорий.

Файл можно разбить на части через импорты:

См. @README для обзора проекта.

# Дополнительные инструкции
- рабочий процесс git: @docs/git-instructions.md

Оговорка: импорт помогает организации, но не экономит контекст — импортированные файлы загружаются при старте вместе с основным. Чтобы упомянуть путь без импорта, оберните его в обратные кавычки.

Что писать, а что не писать

Это самая важная часть урока. CLAUDE.md загружается в каждую сессию, поэтому каждая строка платится контекстом при любом запуске. Ориентир по размеру — до 200 строк на файл. Длиннее — хуже: файл занимает больше места, а соблюдение правил падает, потому что важное теряется среди второстепенного.

Проверочный вопрос для каждой строки: привело бы её удаление к ошибке со стороны Claude? Если нет — строка лишняя.

Стоит записывать:

• Команды, которые нельзя угадать по коду: как именно в этом проекте запускается один тест, как поднимается окружение.
• Правила стиля, отличающиеся от общепринятых по умолчанию.
• Инструкции по тестированию и предпочитаемый прогонщик тестов.
• Соглашения репозитория: именование веток, требования к pull request.
• Архитектурные решения, специфичные для проекта.
• Особенности среды разработки: обязательные переменные окружения.
• Неочевидные подводные камни.

Не стоит записывать:

• Всё, что Claude выяснит, просто прочитав код.
• Стандартные соглашения языка, которые модель и так знает.
• Подробную документацию по API — вместо неё ссылку.
• Описания файлов по одному.
• Общие пожелания вроде «пиши чистый код».

Хорошо написанный файл выглядит скромно:

# Стиль кода
- Только ES modules (import/export), не CommonJS
- Деструктурировать импорты, где возможно

# Рабочий процесс
- После серии правок запускать проверку типов
- Запускать одиночные тесты, а не весь набор: он идёт 8 минут

Обратите внимание на конкретность. «Используй отступ в 2 пробела» работает, «форматируй код правильно» — нет. Правило должно быть проверяемым.

Ещё один приём: если Claude стабильно игнорирует одну конкретную инструкцию, добавьте к ней пометку вроде «IMPORTANT». Но именно к одной. Если выделить половину файла, не выделено ничего.

Проверка и сопровождение

Создать файл мало — нужно убедиться, что он работает. Порядок проверки уже знаком:

# 1. Файл на месте?
ls -la CLAUDE.md

# 2. Загрузился в сессию?
> /context
# ищем его в разделе Memory files

# 3. Посмотреть и отредактировать файлы инструкций
> /memory

Команда /memory перечисляет файлы инструкций во всех областях видимости, включая те, которых ещё не существует, и открывает выбранный в редакторе.

Помните про важное свойство: проектный и пользовательский файлы читаются один раз при старте. Правка посреди сессии не подействует — новое содержимое загрузится при следующем запуске, после /clear или после /compact.

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

Частые ошибки

• Оставлять результат /init как есть. Команда записывает выводимое из кода, а самое ценное — то, чего из кода не видно. Без вашей доработки файл наполовину бесполезен.
• Раздувать файл. Длинный CLAUDE.md платится контекстом в каждой сессии и хуже соблюдается: важные правила теряются в объёме. Держитесь в пределах 200 строк.
• Писать размытые формулировки. «Соблюдай хороший стиль» невозможно проверить и потому бесполезно. Пишите так, чтобы соблюдение правила можно было увидеть в диффе.
• Помещать личные заметки в общий файл. Адреса своих песочниц и тестовые данные — это CLAUDE.local.md в .gitignore, а не коммит в общий CLAUDE.md.

Наиболее частые вопросы

• /init перезапишет мой существующий CLAUDE.md? — Нет. Если файл уже есть, команда предложит улучшения вместо перезаписи.
• ./CLAUDE.md или ./.claude/CLAUDE.md — что выбрать? — Оба варианта работают одинаково. Выбирайте по тому, хотите ли вы видеть файл в корне проекта или собрать конфигурацию в одной директории.
• Что произойдёт, если два файла дают противоречащие указания? — Claude может выбрать любое из них. Противоречия стоит вычищать: периодически перечитывайте свои файлы инструкций.
• Экономят ли импорты контекст? — Нет. Импортированные файлы загружаются при старте вместе с основным. Импорты помогают организации, но не размеру.
• Нужно ли коммитить CLAUDE.md в репозиторий? — Проектный — да, он для всей команды и со временем становится ценнее. CLAUDE.local.md — нет, он для вас и должен быть в .gitignore.

Итоги

Отличная работа: у вашего проекта появилась постоянная память. Вы умеете сгенерировать стартовый файл через /init и довести его руками, знаете, какие файлы инструкций где лежат и как складываются, понимаете принцип отбора содержимого — писать то, без чего Claude ошибётся, и вычёркивать всё остальное. Отдельно ценно понимание границ: CLAUDE.md направляет поведение, но не гарантирует его.

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