Что такое CLAUDE.md и когда он попадает в контекст#
Первое, что стоит понять про этот файл, — он не команда, а фон. Anthropic пишет об этом прямо: агент относится к содержимому файла как к контексту, а не как к принудительной настройке. Формулировка в документации ещё жёстче: содержимое CLAUDE.md доставляется пользовательским сообщением после системного промпта, и строгого соблюдения никто не гарантирует.
Отсюда растёт половина разочарований. Человек пишет в файл «никогда не трогай .env», считает вопрос закрытым и удивляется, когда Клод однажды его трогает. Файл сработал ровно так, как задуман: он попросил. Просьба — не запрет, и дальше в статье будет про то, чем запреты ставят на самом деле.
Второе — цена. Файл грузится целиком при старте и уезжает в модель с каждым запросом, а не один раз за сессию. У Anthropic есть интерактивная симуляция сессии, откуда видно порядок величин. Системный промпт занимает там 4200 токенов, описания скиллов 450, данные об окружении 280, авто-память 680, имена MCP-инструментов 120, пользовательский CLAUDE.md 320, а проектный 1800. Стартовый контекст в этом примере набирает около 7850 токенов, и больше четверти из них приходится на ваш файл.
Строчка про MCP в этом списке скромная, но она растёт с каждым подключённым сервером: имена его инструментов приезжают в контекст в каждой сессии, нужны они сегодня или нет. Сколько это стоит и какие серверы того стоят — в статье про MCP в Claude Code.
Приятная мелочь оттуда же: блочные HTML-комментарии из файла вырезаются до попадания в контекст. Заметку для человека, который будет править файл после вас, можно оставить прямо в тексте, и она не будет стоить ни одного токена.
Четыре места, где может лежать файл#
Файл почти никогда не один. Мест, откуда Claude Code его читает, четыре, и у каждого своя область действия.
| Уровень | Где лежит | На кого действует |
|---|---|---|
| Корпоративный | /Library/Application Support/ClaudeCode/CLAUDE.md на macOS, /etc/claude-code/CLAUDE.md на Linux |
На всех в организации, отключить настройками нельзя |
| Пользовательский | ~/.claude/CLAUDE.md |
Только на вас, зато во всех проектах |
| Проектный | ./CLAUDE.md или ./.claude/CLAUDE.md |
На всю команду, едет в репозитории |
| Локальный | ./CLAUDE.local.md |
Только на вас и только в этом проекте, кладётся в .gitignore |
Порядок в таблице — это и порядок загрузки, от общего к частному. Личные предпочтения попадают в контекст раньше проектных, поэтому проектная инструкция читается последней и весит больше.
Корпоративный уровень нужен не всем, но знать про него полезно: файл по этому пути исключить своими настройками нельзя, а вместо файла администратор может положить текст прямо в ключ claudeMd управляемых настроек. Если агент упорно делает что-то, чего вы не просили, а в проектном файле этого нет, — стоит посмотреть выше по уровням.
Как файлы склеиваются и что делать в монорепозитории#
Файлы не перебивают друг друга. Claude Code идёт от рабочей папки вверх по дереву, собирает все найденные CLAUDE.md и CLAUDE.local.md и склеивает их в один текст. Содержимое выстраивается от корня файловой системы вниз, поэтому ближний к месту запуска файл читается последним. Внутри одной папки CLAUDE.local.md идёт после CLAUDE.md — ваши личные заметки агент читает последними на этом уровне.
Вниз работает другое правило: файлы из подпапок при старте не грузятся. Они подключаются в тот момент, когда Клод открывает файл в этой подпапке. Для монорепозитория это ровно то, что нужно: правила фронтенда не занимают контекст, пока агент правит бэкенд.
Как завести файл и убедиться, что он читается#
Быстрее всего — не с чистого листа.
- Запустите
/initв корне проекта. Клод разберёт код и соберёт стартовый файл с командами, тестами и найденными соглашениями. Если CLAUDE.md уже есть, он не перезапишет его, а предложит правки. - Вычеркните всё, что агент и так узнаёт из кода: дерево папок, список зависимостей, пересказ README.
- Допишите то, чего в коде нет: обходные пути, запретные папки, причины странных решений.
- Проверьте загрузку командой
/context— в разделе Memory files должны быть перечислены ваши файлы.
Про /init полезно знать ещё одно: он читает не только код. Правила Cursor из .cursor/rules и инструкции Copilot из .github/copilot-instructions.md он подхватывает и переносит в новый файл, а в расширенном режиме (CLAUDE_CODE_NEW_INIT=1) добирает ещё четыре набора: AGENTS.md, .devin/rules/, .windsurf/rules/ и .clinerules. Переезжать с другого инструмента руками не нужно.
Двух команд достаточно на всё остальное. /memory показывает список файлов памяти в пользовательской и проектной областях и открывает любой из них в редакторе, в том числе те, которых ещё нет: выбрали — файл создался. /context отвечает на единственный вопрос, который стоит задавать при отладке: файл вообще доехал? Если в Memory files его нет, обсуждать формулировки рано.
Что писать внутри и как это формулировать#
Содержимое сводится к четырём блокам: команды, соглашения, границы и то, что в проекте устроено не так, как агент ожидает по умолчанию.
1# Проект2 3## Команды4- Установка: `npm ci`5- Тесты: `npm test -- --run`6- Линтер: `npm run lint`7 8## Соглашения9- TypeScript в строгом режиме, без `any`10- Файлы в kebab-case, компоненты в PascalCase11- Импорты через алиас `@/`, глубокие пути запрещены12 13## Границы14- Папку `src/legacy/` не трогаем без отдельной задачи15- Файлы в `src/generated/` правит только генератор16- Миграции пишем руками, автогенерация выключена
Три требования к формулировкам документация называет прямо. Конкретность: «отступ два пробела» работает, «форматируй код правильно» — нет; «запускай npm test перед коммитом» работает, «проверяй свои изменения» — нет. Структура: заголовки и списки читаются лучше плотных абзацев, и агент разбирает их так же, как человек. Непротиворечивость: если два правила конфликтуют, Клод выберет одно из них произвольно — и вы не угадаете, какое.
Последний пункт стоит отдельного внимания в проектах, живущих не первый год. Конфликтовать могут не только соседние строки одного файла, но и проектный файл с пользовательским, а вложенный — с корневым. Раз в месяц открыть всё, что грузится, и вычеркнуть устаревшее — скучная, но окупающаяся привычка.
Чего в файле быть не должно: обзора архитектуры, дерева папок и списка зависимостей. Это не вкусовщина — ровно эти разделы вырезает встроенная проверка /doctor, и вырезает по понятному правилу: всё, что Клод может вывести из кода сам, в файле лишнее. Остаются подводные камни, обоснования и соглашения, отличающиеся от умолчаний инструментов. Замеры ETH Zurich на четырёх агентах говорят то же самое с другой стороны: сгенерированный нейросетью контекст-файл снижает долю решённых задач на 3% и поднимает стоимость прогона на 20–23%, а обзоры репозитория не помогают вовсе. Подробнее эти цифры разобраны в статье про AGENTS.md.
Отсюда и ориентир по длине — до 200 строк на файл. Жёсткого обрыва на этой цифре нет: CLAUDE.md грузится целиком независимо от размера. Хуже другое — чем длиннее файл, тем хуже он соблюдается, и вы платите за это в каждом запросе.
Как разгрузить файл: импорты и правила под пути#
Когда файл перерастает две сотни строк, есть два способа его разобрать. Они выглядят похоже, но делают разное, и перепутать их — обычная ошибка.
Импорты — это про порядок в файлах. В CLAUDE.md ставится ссылка вида @путь/к/файлу, и содержимое подставляется на её место. Пути допускаются относительные и абсолютные, относительные считаются от файла с импортом, а не от рабочей папки. Импортированный файл может импортировать следующий, глубина — до четырёх переходов.
1См. @README для общего описания проекта.2 3# Дополнительно4- Порядок работы с git: @docs/git-workflow.md5- Правила безопасности: @docs/security.md
Ключевое про импорты: контекст они не экономят. Все импортированные файлы раскрываются и грузятся при старте вместе с основным. Файл на 500 строк, разложенный по пяти импортам, весит ровно столько же, сколько весил.
Правила — это про контекст. В папку .claude/rules/ кладутся отдельные файлы по темам, и у каждого во фронтматтере может быть поле paths. Правило с этим полем при старте не грузится: оно подключается, когда Клод открывает файл, подходящий под маску.
1---2paths:3 - "src/api/**/*.ts"4---5 6# Правила для API7 8- Все эндпоинты валидируют вход9- Ошибки отдаём в едином формате10- К каждому эндпоинту — комментарий для OpenAPI
В той же симуляции сессии такое правило весит 380 токенов и появляется в контексте не на старте, а в момент, когда агент дошёл до файла в src/api/. Правило без поля paths грузится всегда, наравне с .claude/CLAUDE.md.
Личные правила кладутся в ~/.claude/rules/ и действуют во всех проектах; грузятся они раньше проектных, поэтому проектные имеют приоритет. Общий набор правил на несколько проектов удобно держать в одном месте и линковать симлинками — это поддержано штатно.
Если в проекте уже есть AGENTS.md#
Claude Code читает CLAUDE.md и не читает AGENTS.md — это написано в документации прямым текстом. Подключается открытый формат одной строкой, а ниже дописывается то, что касается только Клода:
1@AGENTS.md2 3## Claude Code4Правки в `src/billing/` — только через режим планирования.
Если своих инструкций для Клода нет, хватит симлинка ln -s AGENTS.md CLAUDE.md; на Windows он потребует прав администратора, поэтому там остаётся импорт. Что вообще класть в открытый формат и какие агенты его читают — в отдельном разборе AGENTS.md.
Что вынести из файла наружу#
Это главный раздел статьи. Год назад CLAUDE.md был единственным местом, куда можно было положить правило, — и привычка складывать туда всё осталась. Сейчас вокруг него выросли скиллы, хуки, субагенты и правила под пути, и половина типового файла живёт не на своём месте.
| Что за правило | Куда его класть | Почему |
|---|---|---|
| Запрет, который не должен нарушаться никогда | PreToolUse-хук или permissions.deny |
Хук срабатывает всегда, инструкция — просьба |
| Многошаговый порядок: релиз, ревью, разбор бага | Скилл | Полный текст грузится только при вызове |
| Правило для одной папки или одного типа файлов | Правило под пути в .claude/rules/ |
Не занимает контекст, пока агент туда не дошёл |
| Справочник: стайлгайд API, схема базы | Скилл | Нужен иногда, а не в каждой сессии |
| Побочная задача с горой промежуточного вывода | Субагент | Работает в своём окне, возвращает выжимку |
| Команды, соглашения, границы проекта | Остаётся в CLAUDE.md | Нужно в каждой сессии и каждому в команде |
Разница между первой и последней строкой таблицы — это разница между запретом и советом. Документация формулирует её без обиняков: строка «никогда не правь .env» в CLAUDE.md или в скилле — это просьба, а не гарантия; PreToolUse-хук, который блокирует правку, — это исполнение. Подробнее про то, что происходит, когда правила остаются просьбами, — в разборе семи причин, по которым Claude Code делает не то.
Второй довод в пользу разгрузки — цена. Каждый субагент грузит собственную копию проектного CLAUDE.md в своё окно: те же 1800 токенов, только считаются они отдельно. Запустили трёх параллельно — заплатили за файл четыре раза. Скиллы устроены иначе: при старте видны только их описания, полный текст приезжает, когда скилл вызвали. Хуки не стоят ничего вовсе — они выполняются вне контекста, и в переписку попадает только их вывод, если он есть.
Строка в CLAUDE.md — просьба, которую читают все и всегда. Хук ничего не просит: он просто не даёт сделать.
Авто-память: что Клод записывает сам#
Второй механизм памяти появился недавно и работает без вас. Клод сам записывает то, что счёл полезным на будущее: команду сборки, которую подобрал, причину странной ошибки, вашу поправку про формат коммитов. В интерфейсе это видно строками вроде «Saved 2 memories».
| CLAUDE.md | Авто-память | |
|---|---|---|
| Кто пишет | Вы | Клод |
| Что внутри | Инструкции и правила | Находки и замеченные закономерности |
| Где лежит | В проекте, едет в репозитории | ~/.claude/projects/<проект>/memory/, только на вашей машине |
| Что грузится | Файл целиком | Первые 200 строк или 25 КБ индекса MEMORY.md |
Устроено это папкой с файлами. MEMORY.md — индекс, он и грузится в каждую сессию; подробности лежат в тематических файлах рядом, и они при старте не читаются — Клод открывает их, когда они понадобились. Папка выводится из git-репозитория, поэтому все worktree одного проекта делят одну память.
Включена авто-память по умолчанию. Выключается тумблером в /memory, ключом autoMemoryEnabled в настройках проекта или переменной окружения CLAUDE_CODE_DISABLE_AUTO_MEMORY=1. Файлы — обычный Markdown: их можно открыть, поправить и удалить.
Частые вопросы#
Где должен лежать файл CLAUDE.md?
~/.claude/CLAUDE.md. Правила проекта, общие для команды, — ./CLAUDE.md или ./.claude/CLAUDE.md в корне репозитория, оттуда они уезжают в систему контроля версий. Личные заметки по конкретному проекту — ./CLAUDE.local.md, и его добавляют в .gitignore. Все найденные файлы склеиваются в один текст, а не заменяют друг друга: сначала общие, потом частные.Почему Claude Code не выполняет то, что написано в CLAUDE.md?
/context, раздел Memory files. Если файла там нет, формулировки обсуждать рано. Если есть — причин обычно три: правило написано расплывчато («пиши качественный код» вместо «не используй any»), оно конфликтует с другим правилом в соседнем файле, или файл разросся и правила в нём тонут. И отдельно: содержимое CLAUDE.md приходит модели пользовательским сообщением, строгого исполнения оно не гарантирует по устройству. Если правило обязано соблюдаться всегда, его место в хуке.Сколько строк должно быть в CLAUDE.md?
.claude/rules/ и скиллами. Подрезать закоммиченный файл умеет /doctor: он вырезает то, что Клод выводит из кода сам, и оставляет подводные камни и соглашения.Чем CLAUDE.md отличается от скилла и когда нужен скилл?
Что такое авто-память и надо ли её выключать?
~/.claude/projects/<проект>/memory/, а в каждую сессию грузится индекс MEMORY.md — первые 200 строк или 25 КБ. Выключать её обычно незачем, но помнить о ней стоит: память машинная, в репозиторий не попадает и на команду не действует. Посмотреть и поправить записанное можно через /memory, там же тумблер выключения.- Anthropic — память Claude Code: уровни файлов, порядок склейки, импорты, правила под пути, авто-память
- Anthropic — когда что использовать: CLAUDE.md, скиллы, хуки, субагенты, и цена каждого в контексте
- Anthropic — окно контекста: что грузится на старте и сколько это стоит в токенах
- Anthropic — команды
/init,/memory,/contextи/doctor - Anthropic — что выносить из CLAUDE.md в правила, скиллы, хуки и субагенты
- ETH Zurich и LogicStar.ai — Evaluating AGENTS.md, замеры влияния контекст-файлов на четырёх агентах
Больше цифр и разборов — в Telegram-канале
Черновики, промежуточные результаты и то, что не дошло до блога