CLAUDE.md: как задать правила проекта

Что такое CLAUDE.md и зачем нужны правила проекта?

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

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

Механика тут простая и объясняет всё остальное. Прошлый разговор агент не помнит: окно контекста, то есть вся память разговора, каждый раз пустое. Донести до него что-то через границу сессии можно двумя способами. Либо ты сам пишешь правила проекта в файл, либо разрешаешь агенту записывать за собой в автоматическую память. Эта статья про первый способ.

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

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

Если слово «агент» пока звучит расплывчато, загляни в короткое определение: что такое агент и что такое Claude Code.

Где лежит CLAUDE.md: четыре места

Коротко: мест четыре, и они складываются от самого общего к самому частному: управляемый организацией файл, твой личный на всю машину, проектный и локальный внутри проекта. Тебе нужен проектный: файл CLAUDE.md в корне рабочей папки, где правила проекта достаются всей команде. Остальные три пригодятся позже.

Места разложены в порядке загрузки, от самого широкого к самому узкому.

Репозиторий, он же общее хранилище проекта, - это место, откуда каждый в команде забирает актуальные файлы. Личным пометкам там не место, поэтому файл CLAUDE.local.md добавь в .gitignore: это список файлов, которые в общее хранилище не уезжают. Держат в нём адрес тестового стенда и прочее, что нужно тебе одному. Верхний уровень отличается от остальных: его не отключить своими настройками, что решила компания, то и действует. На домашней машине этого уровня у тебя просто нет.

Дальше про загрузку, потому что отсюда растёт половина жалоб «агент не знает правила проекта». Программа читает CLAUDE.md из текущей рабочей папки и из каждой папки выше неё. Допустим, проект лежит в ~/projects/shop/, а ты зашёл в ~/projects/shop/admin/ и запустился оттуда. Агент возьмёт и admin/CLAUDE.md, и shop/CLAUDE.md, и дальше вверх, до самого корня.

Ни один файл не отменяет другой: агент получает их все подряд, одним куском. Сверху вниз, сначала дальние папки, последней - та, из которой ты запустился. Значит, последнее слово всегда за ближним файлом. Внутри одной папки локальный дописывается после основного.

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

Шаг 1. Собрать заготовку командой /init

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

Переходишь в папку проекта, запускаешь агента, набираешь:

/init

Дальше агент читает папку и записывает первые правила проекта сам. Что в них окажется, зависит от проекта: у сайта это будут команды сборки, у папки с текстами - структура и договорённости об именах.

Заготовка - это только старт. Дополнять её нужно тем, чего агент не выведет сам. На практике это причины решений, попытки, которые не сработали, и запреты без исключений.

Есть и расширенный режим той же команды. Если задать переменную окружения CLAUDE_CODE_NEW_INIT=1 (это настройка, которую программа читает при запуске), команда работает диалогом: спрашивает, что именно заводить (файлы правил, скиллы, хуки), изучает папку отдельным субагентом - так называют вспомогательного агента, которого основной запускает под одну подзадачу, - задаёт уточняющие вопросы и показывает, что именно собирается записать, до того как что-то появится на диске.

Ещё команда подхватывает уже написанные правила Cursor (.cursor/rules/ и .cursorrules) и Copilot (.github/copilot-instructions.md). В расширенном режиме список шире, туда добавляются AGENTS.md, Windsurf, Devin и Cline. Переписывать свод правил заново не придётся.

Шаг 2. Какие правила проекта писать в файл?

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

Писать в файл можно что угодно, но работает узкий набор из трёх вещей.

Первое - чем проверять работу. Команда сборки, команда тестов, способ убедиться, что ничего не сломалось. Это первое, о чём агент спрашивает. Не найдя ответа, он его выдумывает.

Второе - куда не лезть. Папки с доступами, чужие модули, файлы, которые правятся только руками.

Третье - как у вас принято. Имена, порядок работы с ветками, формат сообщений. То, что нигде не записано и держится на памяти команды.

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

Конкретность проверяется просто: по правилу видно, выполнено оно или нет. Документация приводит пары:

Коммит - это сохранение порции правок в историю проекта; к нему и привязывают проверки вроде прогона тестов.

Структура - обычные заголовки и списки markdown. У Anthropic на этот счёт сказано прямо: агент читает разметку так же, как человек. По заголовкам и спискам он ориентируется, по сплошной простыне - нет.

Непротиворечивость - то, о чём вспоминают последним. Столкнулись два правила - какое сработает, предсказать нельзя. Не «победит то, что ближе», а как повезёт. Поэтому перечитывай файлы целиком раз в пару недель и выкидывай устаревшее, особенно когда правила проекта расползлись по нескольким папкам.

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

Шаг 3. Проверить, что файл дошёл до агента

Коротко: не угадывай, проверь. Команда /context печатает список Memory files, и в нём видно, какие правила проекта загрузились в текущую сессию. Нет твоего файла в списке - агент его не получил, и обсуждать формулировки бессмысленно. Эта проверка занимает секунду и снимает большую часть споров с инструментом, потому что отделяет вопрос «файл дошёл» от вопроса «правило сформулировано понятно». Открыть найденные файлы на правку помогает соседняя команда /memory.

Проверка загрузки - ключевой шаг всей инструкции, и его чаще всего пропускают. Человек пишет правила проекта, агент их не выполняет, человек переписывает формулировки. А файл всё это время лежал не в той папке.

Проверка занимает секунду:

/context

В выводе есть раздел Memory files. Там перечислены правила проекта, которые реально загрузились: проектный файл, локальный, пользовательский, подключённые правила.

Вторая команда открывает эти файлы на правку:

/memory

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

Есть и проверка по-человечески: попроси агента пересказать правила проекта своими словами. Пересказал - файл прочитан. Промолчал или начал сочинять - возвращайся к /context.

Что в CLAUDE.md писать не надо?

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

Тот же принцип заложен во встроенную проверку. В версии 2.1.206 в проверку /doctor добавили пункт, который предлагает подрезать закоммиченный CLAUDE.md: она вырезает то, что агент и так прочитает в папке, и оставляет то, чего он сам не узнает: где у вас опасные места, почему сделали именно так и в чём вы отступили от того, как ведут себя инструменты по умолчанию.

Что вынести из файла:

1. Пересказ структуры папок. Агент читает дерево каталогов сам.
2. Список зависимостей и версий. Он лежит в файлах проекта и устаревает быстрее, чем ты правишь правила проекта.
3. Общие пожелания без проверяемого признака. По «пиши хороший код» нельзя сказать, выполнено оно или нет.
4. Длинные пошаговые процедуры. Документация советует переносить их в скиллы: те подгружаются по вызову и в контексте постоянно не висят.
5. Правила, нужные одной части проекта. Для них есть правила с ограничением по путям в папке .claude/rules.

Отдельная мелочь, которая экономит место. Комментарий в HTML-скобках <!-- заметка --> вырезается из файла до того, как он попадёт в контекст агента. Заметки для людей можно держать прямо в файле, и токенов они не стоят. Внутри блоков кода комментарии сохраняются, и при обычном чтении файла инструментом они тоже видны. Поведение появилось в версии 2.1.72.

Как разрезать длинный файл импортами?

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

Синтаксис простой - символ @ и путь прямо в тексте:

Общее описание проекта лежит в @README.md, команды сборки - в @package.json.

# Что вынесено отдельно
- порядок работы с ветками @docs/vetki.md
- правила для тестов @docs/testy.md

Относительный путь считается от файла с импортом. Папка, из которой ты запустил агента, здесь ни при чём. Правило неочевидное: перенёс файл - импорты отвалились.

Внутри обратных кавычек и блоков кода строка с @ не считается импортом. Она остаётся обычным текстом. Так и упоминают путь, когда подтягивать файл не нужно: без кавычек та же строка сработает как импорт.

Файл снаружи рабочей папки требует подтверждения. Когда проектный файл импортирует что-то за пределами папки проекта, агент в первый раз покажет список таких файлов и спросит разрешения. Откажешься - импорты выключатся, и спрашивать он больше не будет. Защита понятная: в общий репозиторий файл может положить кто угодно.

Разрез на части наводит порядок в голове, а места не экономит: документация отдельно уточняет, что импортированные файлы всё равно грузятся при старте. Правила проекта, вынесенные в соседний файл, займут в контексте ровно столько же. Реально экономят место два других механизма - правила с ограничением по путям и скиллы.

Почему агент не выполняет правила из CLAUDE.md?

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

Самая массовая жалоба на файл правил звучит одинаково: «я же написал». Беда не только твоя. В репозитории Claude Code с 24 июня 2025 года висит открытым обращение 2544 с заголовком «обязательные правила из CLAUDE.md последовательно игнорируются», и на 18 сентября 2026 года оно собрало два десятка комментариев и больше сорока реакций. Поиск по заголовкам обращений того же репозитория даёт больше сотни записей со словами «CLAUDE.md instructions» (снято 18 сентября 2026 года).

Разбирается жалоба сверху вниз, по четырём причинам.

Первая. Файл не дошёл. Открываешь /context, ищешь раздел Memory files. Нет файла в списке - остальное неважно. Причины обычно бытовые: файл назван иначе, лежит в подпапке ниже рабочей, агент запущен не из той папки. Отдельно про имя: документация везде пишет его заглавными буквами, а в обсуждениях на Hacker News автора разбора поправляют: имя чувствительно к регистру, и Claude.md со строчными может не подхватиться. Прямой оговорки про регистр в документации нет, поэтому проще писать заглавными и не проверять.

Вторая. Формулировка не проверяется. «Пиши аккуратно» агент выполнить не может, потому что не существует признака, по которому это видно. Переписывай в проверяемую форму.

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

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

Дальше приём, которого в инструкциях почти нет. У Claude Code есть ключ запуска, который отключает все твои настройки сразу - файлы правил, скиллы, плагины, хуки, серверы MCP, свои команды и агентов. Это ответ на вопрос «дело вообще в правилах или нет»:

claude --safe-mode

Вывод справки на установке, которую я проверял (версия 2.1.211), описывает ключ именно так: старт с отключёнными настройками для разбора сломанной конфигурации, при этом политики организации продолжают действовать. Сам ключ появился в версии 2.1.169. Проверка читается так: если в этом режиме поведение изменилось, причина в твоих настройках, и начинать разбор надо с файла правил. Если не изменилось, копай в другую сторону.

Остаётся выбор между текстом и хуком. Текст в CLAUDE.md агент может и проигнорировать. Если действие обязано происходить в конкретный момент (перед каждым коммитом, после каждой правки), документация советует записать его хуком.

Сколько строк держать в файле?

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

Работает это так: файл правил грузится в окно контекста при старте сессии и лежит там всё время, даже когда ты занят совсем другим. Сто строк правил - это сто строк, которых не будет под задачу. Подробный разбор расхода лежит в статье про лимиты Claude Code.

Разбор команды HumanLayer «Writing a good CLAUDE.md» рекомендует оставаться в пределах 300 строк и уточняет, что их собственный корневой файл занимает меньше шестидесяти. Обоснование там же: передовые рассуждающие модели справляются примерно со 150-200 инструкциями, и часть этого запаса уже занята системным промптом самой программы. То есть твой бюджет правил меньше, чем кажется, и каждая лишняя строка вытесняет нужную.

Что делать, когда файл перерос ориентир:

1. Вынести частные инструкции в правила с ограничением по путям (.claude/rules) - они грузятся, только когда агент работает с подходящими файлами.
2. Длинные процедуры перенести в скиллы, которые подгружаются по вызову.
3. Прогнать /doctor и посмотреть, что проверка предлагает подрезать.
4. Выкинуть устаревшее. Правило, которое описывает порядок годичной давности, вредит: агент учитывает его наравне со свежими.

Чем CLAUDE.md отличается от памяти и скиллов?

Коротко: три разных механизма, которые легко перепутать по названиям. Файл правил пишешь ты, и он грузится всегда. Автоматическую память пишет агент сам из твоих поправок, и она тоже грузится всегда. Скилл - это папка с инструкцией, которая подгружается, только когда ты её вызвал или когда агент счёл её подходящей к задаче.

Постоянное требование («всегда проверяй сборку») идёт в файл правил. Разовая поправка («не npm, а pnpm») уедет в автоматическую память сама, если ты её просто скажешь. А длинная процедура на две страницы - это скилл, и держать её в файле правил дорого.

Автоматическая память устроена отдельно от твоего файла: она включена по умолчанию, хранится в папке ~/.claude/projects/<проект>/memory/, индексом в ней работает файл MEMORY.md. Тумблер и просмотр записей - в той же команде /memory.

Здесь возникает путаница, на которой спотыкаются и опытные. У индекса MEMORY.md есть жёсткий предел загрузки: первые 200 строк или 25 КБ, смотря что кончится раньше. Остальное в сессию не попадает. Цифра «200 строк» для CLAUDE.md означает другое: там это рекомендация по размеру, и жёсткого обрезания за ней не стоит. Совпадение чисел случайное, механизмы разные.

Готовые скиллы с порядком установки лежат в каталоге скиллов, а как устроен сам скилл - в статье про скиллы Claude Code.

Что делать, если в проекте уже есть AGENTS.md?

Коротко: с версии 2.1.277 Claude Code читает AGENTS.md сам, но по умолчанию - только когда ни в рабочей папке, ни в папках выше нет ни CLAUDE.md, ни CLAUDE.local.md. Появился CLAUDE.md рядом, и агент переключается на него. Поведение переключается настройкой Project instructions в команде /config.

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

Отсюда ловушка, на которую документация указывает отдельно: локальный файл CLAUDE.local.md тоже считается за файл правил Claude Code. Завёл его для личных пометок в проекте на AGENTS.md - и агент перестал читать общий файл команды.

А вот что чтению AGENTS.md не мешает: твой личный ~/.claude/CLAUDE.md, управляемый организацией файл и правила из .claude/rules. Они грузятся рядом и переключателем не работают.

Настройка Project instructions в /config разводит эти случаи: можно читать оба файла, только CLAUDE.md или только управляемые организацией правила.

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

@AGENTS.md

Содержимое подтянется, а вести придётся один файл вместо двух.

Если ты держишь у себя обоих агентов, сравнение их устройства лежит рядом: Codex или Claude Code.

Готовый шаблон CLAUDE.md

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

# Правила проекта

### Что это за проект
Одна-две строки: что делаем и для кого. Без пересказа структуры папок.

### Как проверить работу
- Сборка: npm run build
- Тесты: npm test
- Перед коммитом выполняй оба

### Чего делать нельзя
- Не трогать папку backup
- Не править файлы с доступами
- Не удалять миграции

### Как у нас принято
- Отступ в два пробела
- Имена файлов в нижнем регистре через дефис
- Сообщение коммита одной строкой на русском

### Что мы уже пробовали
- Отказались от библиотеки X: ломается на сборке

Раздел «что мы уже пробовали» почти никто не заводит. Причины решений нигде не записаны, а агент раз за разом предлагает то, что у вас в команде уже отвергли.

Правило заполнения одно: строка появляется в файле после того, как ты объяснил её агенту второй раз. Так CLAUDE.md растёт по факту: каждая строка появилась из реального повтора.

На чём спотыкаются в первый месяц

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

1. Класть файл не в ту папку. Правила действуют из рабочей папки и папок выше неё. Файл в подпапке подтянется, только когда агент откроет что-то оттуда.
2. Писать пожелания вместо правил. Агент не выполняет то, про что нельзя сказать, выполнено оно или нет.
3. Переписывать в файл структуру проекта. Агент читает её сам, а место в контексте расходуется в каждой сессии.
4. Держать противоречащие правила в разных файлах. Личное правило и проектное расходятся, дальше лотерея.
5. Ждать от файла гарантий. Гарантию даёт только хук: он выполняется как команда, независимо от решения агента.
6. Записывать правило решёткой. Приём убран в версии 2.0.70, и журнал изменений прямо советует вместо него попросить агента отредактировать файл правил. Проверить это можно и с другой стороны: в действующем справочнике по горячим клавишам и режимам ввода решётки среди сокращений памяти уже нет. Если инструкция предлагает такой способ, она написана до середины декабря 2025 года (версия 2.0.70 вышла 15 декабря), и остальное в ней стоит перепроверить.

Седьмой пункт вынесу отдельно, потому что он не про технику. Файл правил не заводят один раз и навсегда. Он меняется вместе с проектом. Устаревшую строку агент учитывает наравне со свежей, и в этом её вред.

Что дальше

Коротко: заведи файл в одном рабочем проекте, проверь через /context, что он загрузился, и дальше дописывай по одной строке за каждое повторное объяснение. Этого хватает на первые месяцы работы. Правила проекта не пишут за один вечер: они набираются из реальных случаев, когда агент ошибся или не угадал договорённость, принятую в команде.

Три ближайших дела, в порядке отдачи:

1. Выполни /init в проекте, с которым работаешь чаще всего. Десяти строк хватает, чтобы перестать объяснять одно и то же в каждой сессии.
2. Проверь загрузку через /context. Один раз увидев список Memory files, ты перестанешь гадать, читает агент твои правила или нет.
3. Заведи раздел «что мы уже пробовали». Это то, чего нет ни в коде, ни в документации, и то, что агент сам не выведет.

Что почитать рядом:

• Claude Code - настройка с нуля - весь порядок настройки, где файл правил только первый шаг.
• Лимиты Claude Code - из чего складывается расход контекста и где он виден.
• Codex или Claude Code - чем различаются два агента, включая файлы правил.
• Скилл - куда переносить длинные процедуры из файла правил.

Разборы, шаблоны и правила, которые я собираю по ходу работы с агентами, попадают в ClaudeBase: там они разложены по темам и обновляются, когда меняется сам инструмент.

Источники

• How Claude remembers your project, документация Anthropic - места размещения файла, порядок загрузки, импорты, размер, раздел про то, почему правила не соблюдаются.
• Claude Code commands, документация Anthropic - справочник слэш-команд, включая /init, /memory, /context и /doctor.
• Interactive mode, документация Anthropic - горячие клавиши и режимы ввода в сессии.
• Журнал изменений Claude Code, репозиторий anthropics/claude-code - удаление записи через решётку в 2.0.70, ключ --safe-mode в 2.1.169, пункт про подрезку CLAUDE.md в /doctor в 2.1.206, поддержка AGENTS.md в 2.1.277.
• Skills, документация Anthropic - механизм, куда выносят длинные инструкции из файла правил.
• Hooks guide, документация Anthropic - как задать действие, которое выполняется независимо от решения агента.
• Writing a good CLAUDE.md, разбор команды HumanLayer - планка в 300 строк, собственный файл короче шестидесяти строк, потолок в 150-200 инструкций.
• Обращение 2544 в репозитории anthropics/claude-code - открыто с 24 июня 2025 года, статус и счётчики сняты 18 сентября 2026 года.