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

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

Коротко: главное за минуту

CLAUDE.md — обычный текстовый файл в корне репозитория (или в подпапках для монорепы), который Claude Code автоматически подхватывает в контекст. Туда пишут: описание проекта и стек, команды запуска и тестов, стиль кода, зоны «не трогать» и повторяющиеся грабли. Файл коммитится в git как обычный код и правится через пул-реквесты, если работаешь в команде. Без него Claude каждый раз угадывает контекст с нуля — с ним держит рамки проекта сессия за сессией.

Файл Claude md в структуре проекта рядом с package.json

Что такое Claude md и зачем он проекту

Формально это просто файл CLAUDE.md в корне репозитория. Никакой магии в синтаксисе — обычный markdown, который ты бы написал для нового джуна в команде. Разница в том, что Claude Code читает его автоматически при старте сессии и держит в контексте всё время, пока ты работаешь.

Без файла памяти каждая сессия с Claude Code начинается с нуля: он не знает, что у вас Vite, а не Webpack, что тесты гоняются через pnpm test, а не npm run test, и что ветку main трогать нельзя без ревью. Ты либо объясняешь это заново, либо получаешь код, который технически работает, но живёт по чужим правилам.

С CLAUDE.md ты один раз формулируешь контракт — и Claude ему следует. Это не гарантия идеального кода, но это разница между агентом, который угадывает, и агентом, который знает.

Что писать в Claude md: разделы и структура

Универсального шаблона нет — но есть блоки, которые встречаются в рабочих Claude md почти всегда. Вот структура, от которой можно отталкиваться:

Раздел Что туда идёт Пример
Описание проекта Что делает продукт, для кого «Внутренний CRM для отдела продаж, 15 пользователей»
Стек и структура Технологии, папки, где что лежит «Backend: Node + Fastify, папка src/api»
Команды Запуск, тесты, линт, сборка pnpm dev, pnpm test, pnpm lint
Стиль кода Конвенции, которых нет в линтере «Именуем компоненты PascalCase, хуки — с префиксом use»
Запреты Что Claude не должен трогать сам «Не менять миграции без явного запроса, не удалять .env.example»
Контекст-грабли Повторяющиеся ошибки прошлых сессий «Не используй moment.js, в проекте только date-fns»

Раздел «контекст-грабли» — самый живой и самый недооценённый. Именно туда попадают вещи, на которых Claude уже наступил у тебя лично: перепутал версию API, полез переписывать чужой модуль, предложил библиотеку, которую вы давно выкинули. Не пиши это абстрактно — пиши конкретный кейс, который реально был.

Хороший Claude md пример на 30–50 строк работает лучше, чем идеальный на 300: длинный файл Claude тоже читает, но внимание размывается, и важные пункты тонут среди воды. Пиши как для человека, который прочитает файл один раз и должен всё запомнить — коротко и по делу.

Про то, как вообще собираются такие рабочие инструкции для Claude, у меня есть отдельный разбор — почитай что такое скиллы Claude, CLAUDE.md и скиллы решают смежные задачи, но по-разному.

В канале «А.М. решает вопросы» я регулярно разбираю такие рабочие файлы на живых проектах — какие разделы реально спасают время, а какие только раздувают контекст без толку. Заходи, если хочешь смотреть на это не в теории.

Пример структуры Claude md с разделами стек, команды и запреты

Claude md для команды: как не превратить файл в поле битвы

Когда в проекте работает не один человек, а команда, CLAUDE.md быстро становится точкой конфликта: у каждого свои привычки, и все тянут файл в свою сторону. Работает то же правило, что для любого общего кода — файл коммитится в репозиторий, правки идут через пул-реквест, а не через личные договорённости в чате.

Практика, которая реально снимает напряжение:

  • Файл лежит в корне и виден всем — не в личных заметках, не в вики отдельно от кода.
  • Спорные правила обсуждаются в комментариях к PR, а не устно на созвоне (потом никто не вспомнит, о чём договорились).
  • Раз в пару недель кто-то один пробегается и убирает то, что устарело — иначе файл разрастается до простыни, которую никто не читает.
  • Для монорепы — общий CLAUDE.md в корне с правилами всего проекта плюс локальные файлы в каждом сервисе с деталями конкретно по нему. Claude Code подхватывает оба уровня одновременно.

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

Команда правит Claude md через пул-реквест как обычный код проекта

Частые ошибки в Claude md — и как их не повторить

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

  1. Слишком общие формулировки. «Пиши чистый код» — бесполезная строка, Claude не знает, что это значит именно в вашем проекте. «Функции не длиннее 40 строк, ранние return вместо вложенных if» — рабочая.
  2. Файл никто не обновляет. Написали один раз при старте проекта и забыли. Полгода спустя половина команд из файла устарела, а новые грабли туда не попали — доверия к файлу больше нет, Claude по нему путается не хуже, чем без него.
  3. Запреты без объяснений. «Не трогать legacy/» без причины Claude может проигнорировать в сложной задаче, если решит, что по-другому не получится. «Не трогать legacy/ — там висит старый биллинг, любые правки ломают начисления у текущих клиентов» — такое он уважает куда охотнее.

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

Как проверить, что Claude md реально работает

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

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

Проверка работы Claude md на новой сессии Claude Code

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

Читайте также

В телеграм-канале «А.М. решает вопросы» я показываю такие штуки не в теории, а на живых проектах — с реальными файлами, реальными косяками Claude и тем, как я их правила. Если хочешь видеть, как это выглядит вживую, а не в статье — заходи в канал, там разборы выкладываю регулярно.