Файл CLAUDE.md: как правильно писать память проекта

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

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

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

Агент не помнит предыдущих сессий. Каждый раз он начинает с чистого листа: изучает проект, угадывает, как запускать тесты, выбирает стиль кода по образцам, которые попались первыми. Без файла памяти вы раз за разом повторяете одно и то же: «тесты запускаются через make test», «не трогай папку legacy», «коммиты пишем на русском». CLAUDE.md записывает эти договорённости один раз.

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

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

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

Где лежат файлы и в каком порядке загружаются

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

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

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

Что писать в CLAUDE.md, а что нет

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

Писать: команды сборки, тестов, линтера и запуска проекта; соглашения, которые не очевидны из кода (как называем ветки, на каком языке комментарии и коммиты); устройство проекта в двух-трёх строках — где что лежит; запреты («не меняй файлы в migrations/ вручную», «не добавляй зависимости без согласования»); особенности окружения (переменные, сервисы, которые должны быть запущены).

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

Удобно помнить, что у Claude Code 5 мест для разных видов знаний, и каждое загружается по-своему. CLAUDE.md — всегда, в начале каждой сессии. Правила в .claude/rules/ с полем paths — только при работе с подходящими файлами. Скиллы — только когда задача требует их или вы вызываете их сами. Хуки — не текст для модели, а программы, которые срабатывают всегда. Автопамять — то, что Claude записал сам, первые 200 строк или 25 КБ. Если знание нужно в каждой сессии — CLAUDE.md, если иногда — правило или скилл, если без исключений — хук.

Как писать инструкции, которым агент следует

Конкретность. Инструкция должна быть проверяемой. «Используй отступ в 2 пробела» вместо «форматируй код правильно», «запускай npm test перед коммитом» вместо «проверяй изменения», «обработчики API лежат в src/api/handlers/» вместо «соблюдай структуру». Расплывчатое правило модель трактует по-своему, конкретное — выполняет.

Непротиворечивость. Если два правила противоречат друг другу, Claude может выбрать любое. Противоречия появляются незаметно: в корневом файле написано одно, во вложенном — другое, в папке правил — третье. Раз в месяц полезно перечитать все файлы памяти подряд и убрать устаревшее. Модель помогает и здесь: попросите её найти противоречия и дубли во всех файлах памяти проекта и предложить, какое из двух правил оставить.

Причина рядом с правилом. Короткое объяснение «почему» помогает агенту применять правило в ситуациях, которые вы не предусмотрели. «Не используй библиотеку X — она несовместима с нашей версией Node» работает лучше, чем «не используй X»: агент поймёт, что и похожие библиотеки стоит проверить на совместимость. И то же объяснение через полгода поможет решить, актуально ли ещё правило.

Структура. Заголовки и короткие списки читаются моделью лучше сплошного текста. Разделы вроде «Команды», «Устройство проекта», «Соглашения», «Запреты» делают файл удобным и для людей: новый сотрудник прочитает его за пять минут и сразу поймёт, как в проекте принято работать.

Пример хорошего CLAUDE.md

Пример для небольшого веб-проекта. Он короткий, конкретный и содержит только то, что нельзя быстро вывести из кода.

Обратите внимание на правило про цены в копейках: оно объясняет причину, и агент применит ту же логику к скидкам и налогам. Правило про миграции предотвращает самую неприятную ошибку. Запрет на push оставляет последнее слово за человеком, который проверит изменения перед отправкой. Такой файл пишется быстрее, чем объясняются те же правила агенту в трёх сессиях подряд.

Готовый файл полезно прогнать по короткому чек-листу. Его можно отдать и самому Claude: «проверь CLAUDE.md по этим 8 пунктам и предложи правки».

Правила для папок, импорты и личные настройки

Для больших проектов инструкции удобно разбить по темам в папке .claude/rules/: отдельный файл на тему — тестирование, стиль API, безопасность. Все .md-файлы в папке находятся рекурсивно, можно раскладывать по подпапкам. Правило может действовать всегда или только для определённых файлов: в начале файла указывается поле paths со списком шаблонов путей, например src/api/**/*.ts. Такие правила подгружаются, только когда агент работает с подходящими файлами, и не занимают контекст впустую.

Файлы памяти могут подключать другие файлы через @путь: например, @README для описания проекта или @docs/git-instructions.md для правил работы с git. Подключённые файлы загружаются вместе с CLAUDE.md. Если путь ведёт за пределы рабочей папки, при первой встрече Claude Code покажет диалог подтверждения со списком таких файлов.

Личные настройки для проекта — адрес тестового сервера, любимые тестовые данные — кладите в CLAUDE.local.md в корне и добавьте его в .gitignore. Он загружается вместе с CLAUDE.md, но не попадает к коллегам. Личные привычки для всех проектов — в ~/.claude/CLAUDE.md: например, «объясняй изменения кратко» или «перед большими изменениями показывай план».

Автопамять, AGENTS.md и что делать, если агент не слушается

Автопамять включена по умолчанию. Claude сам записывает четыре вида заметок: о вас (роль, опыт, предпочтения), ваши поправки и подтверждённые подходы, сведения о текущей работе, которые нельзя вывести из кода, и ссылки на внешние ресурсы. В начале сессии загружаются первые 200 строк или 25 КБ основного файла автопамяти. Посмотреть, что записано, отредактировать или отключить автопамять можно командой /memory.

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

Если агент не следует инструкциям, проверьте по порядку. Загружен ли файл — команда /memory покажет, какие файлы памяти активны. Нет ли противоречий между уровнями и файлами правил. Не слишком ли файл длинный — важное может теряться среди второстепенного. Конкретна ли инструкция. И если правило должно выполняться всегда, без исключений, — переведите его из текста в хук, который Claude Code запускает сам. Почему длинный контекст ухудшает следование инструкциям, разобрано в гайде контекстное окно нейросети.

Автор: Артём Беспалов, маркетинговое ИИ-агентство «Термос Беспалова», Калининград.

Источники: документация Claude Code о памяти: CLAUDE.md, правила, импорты, автопамять, AGENTS.md (проверено 27.09.2026).