CLAUDE.md: правила проекта, которые агент действительно выполняет

Разбираю по документации Anthropic, где лежит файл и как он склеивается, почему инструкция в нём — просьба, а не гарантия, и какие правила давно пора держать не в тексте, а в хуках

Автор Ольга Гунько Опубликовано Обновлено Время чтения 17 мин Просмотров 0
Новичок
Белый робот с оранжевой антенной стоит между листом с надписью CLAUDE.md, к которому тянется рукой, и металлической табличкой на четырёх болтах с оранжевым крестом в белом восьмиугольнике
Слева просьба, которую можно не заметить, справа запрет, который не обойти

Что такое 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 его читает, четыре, и у каждого своя область действия.

Четыре уровня CLAUDE.md: где лежит файл и на кого действует
Уровень Где лежит На кого действует
Корпоративный /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 — ваши личные заметки агент читает последними на этом уровне.

Вниз работает другое правило: файлы из подпапок при старте не грузятся. Они подключаются в тот момент, когда Клод открывает файл в этой подпапке. Для монорепозитория это ровно то, что нужно: правила фронтенда не занимают контекст, пока агент правит бэкенд.

Как завести файл и убедиться, что он читается#

Быстрее всего — не с чистого листа.

  1. Запустите /init в корне проекта. Клод разберёт код и соберёт стартовый файл с командами, тестами и найденными соглашениями. Если CLAUDE.md уже есть, он не перезапишет его, а предложит правки.
  2. Вычеркните всё, что агент и так узнаёт из кода: дерево папок, список зависимостей, пересказ README.
  3. Допишите то, чего в коде нет: обходные пути, запретные папки, причины странных решений.
  4. Проверьте загрузку командой /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 его нет, обсуждать формулировки рано.

Что писать внутри и как это формулировать#

Содержимое сводится к четырём блокам: команды, соглашения, границы и то, что в проекте устроено не так, как агент ожидает по умолчанию.

markdownCLAUDE.md
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 ставится ссылка вида @путь/к/файлу, и содержимое подставляется на её место. Пути допускаются относительные и абсолютные, относительные считаются от файла с импортом, а не от рабочей папки. Импортированный файл может импортировать следующий, глубина — до четырёх переходов.

markdownCLAUDE.md
1См. @README для общего описания проекта.2 3# Дополнительно4- Порядок работы с git: @docs/git-workflow.md5- Правила безопасности: @docs/security.md

Ключевое про импорты: контекст они не экономят. Все импортированные файлы раскрываются и грузятся при старте вместе с основным. Файл на 500 строк, разложенный по пяти импортам, весит ровно столько же, сколько весил.

Правила — это про контекст. В папку .claude/rules/ кладутся отдельные файлы по темам, и у каждого во фронтматтере может быть поле paths. Правило с этим полем при старте не грузится: оно подключается, когда Клод открывает файл, подходящий под маску.

markdown.claude/rules/api.md
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 — это написано в документации прямым текстом. Подключается открытый формат одной строкой, а ниже дописывается то, что касается только Клода:

markdownCLAUDE.md
1@AGENTS.md2 3## Claude Code4Правки в `src/billing/` — только через режим планирования.

Если своих инструкций для Клода нет, хватит симлинка ln -s AGENTS.md CLAUDE.md; на Windows он потребует прав администратора, поэтому там остаётся импорт. Что вообще класть в открытый формат и какие агенты его читают — в отдельном разборе AGENTS.md.

Что вынести из файла наружу#

Это главный раздел статьи. Год назад CLAUDE.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.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?
Ориентир Anthropic — до 200 строк на файл. Жёсткого обрыва на этой цифре нет, файл грузится целиком любой длины, но длинный текст съедает контекст в каждом запросе и соблюдается хуже. Если файл перерос ориентир, разбирать его надо не импортами — они грузятся при старте так же, — а правилами под пути в .claude/rules/ и скиллами. Подрезать закоммиченный файл умеет /doctor: он вырезает то, что Клод выводит из кода сам, и оставляет подводные камни и соглашения.
Чем CLAUDE.md отличается от скилла и когда нужен скилл?
CLAUDE.md грузится в каждую сессию целиком, скилл — по требованию: при старте видно только его описание, полный текст приезжает при вызове. Отсюда и разделение. В CLAUDE.md — то, что нужно знать всегда: команды, соглашения, границы. В скилл — то, что нужно иногда: справочники вроде стайлгайда API и многошаговые процедуры вроде релиза или разбора бага. Признак, что пора заводить скилл, простой: вы третий раз вставляете в чат один и тот же порядок действий.
Что такое авто-память и надо ли её выключать?
Это второй механизм памяти, включённый по умолчанию: Клод сам записывает находки в ~/.claude/projects/<проект>/memory/, а в каждую сессию грузится индекс MEMORY.md — первые 200 строк или 25 КБ. Выключать её обычно незачем, но помнить о ней стоит: память машинная, в репозиторий не попадает и на команду не действует. Посмотреть и поправить записанное можно через /memory, там же тумблер выключения.
Ольга Гунько
Автор Ольга Гунько Веб-дизайнер и вайбкодер

Строю проекты на нейросетях и показываю всё как есть — цифры, затраты, результаты

18 лет в дизайне 600+ проектов Вау-сайты SEO-заводы Claude + Figma
Клодовая · Telegram-канал · 107 подписчиков

Больше цифр и разборов — в Telegram-канале

Черновики, промежуточные результаты и то, что не дошло до блога

Подписаться на Клодовую