CLAUDE.md — правила и память

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

Короткий ответ

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

/init

Она анализирует твой проект и генерит стартовый CLAUDE.md. Дальше правила дописываешь на ходу — набираешь символ #, а за ним правило, и агент сам добавит его в файл:

# всегда запускай тесты перед коммитом

Всё. Файл лежит в корне проекта, агент читает его каждую сессию, ты перестаёшь повторяться.

Что понадобится

• Установленный и работающий Claude Code (команда claude доступна в терминале).
• Проект — обычная папка с кодом, из которой ты запускаешь claude. CLAUDE.md ляжет в её корень.
• Пять минут. Стартовый файл генерит /init, дальше он растёт сам по мере работы.

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

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

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

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

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

Как создать — команда /init

Не нужно писать файл с нуля вручную. В Claude Code есть команда, которая делает стартовую версию за тебя. Открой проект (запусти claude в его папке) и набери прямо в чате:

/init

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

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

Что писать внутрь

Структура свободная, но обычно в CLAUDE.md держат несколько типовых блоков:

• Краткое описание проекта. Одна-две строки: что это вообще за штука и для чего.
• Стек и технологии. Языки, фреймворки, база данных, менеджер пакетов.
• Команды. Чем собирать, чем тестировать, чем запускать. Самое ценное — агент перестаёт угадывать, как гонять твои тесты.
• Стиль и конвенции. Язык комментариев и коммитов, правила именования, формат кода.
• Важные правила «всегда / никогда». Твёрдые границы, которые агент не должен переступать.

Блок правил — сердце файла. Формулируй их коротко и как чёткие черты, а не пожелания. Пример:

## Правила
- Всегда запускай тесты перед коммитом
- Комментарии и коммиты на русском
- В main напрямую не писать — только через PR
- Не трогай папку legacy без явного разрешения

Каждая строка — одно понятное правило, которое агент может применить без интерпретации. «Пиши хороший код» он проигнорирует, потому что не поймёт, что от него хотят. «Функции короче 40 строк» — выполнит.

Совет: держи файл коротким и конкретным. CLAUDE.md грузится в контекст каждый запуск, и чем он длиннее, тем дороже каждая сессия и тем хуже фокус — важные правила тонут среди второстепенных. Лей сюда только то, что реально влияет на работу. Хороший тест перед добавлением строки: «это правило сэкономит мне повторное объяснение в будущем?» Если нет — ему здесь не место.

Как пополнять на ходу

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

Прямо в сессии набери символ #, а за ним — правило обычными словами:

# всегда запускай npm test перед коммитом

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

Когда хочешь посмотреть или отредактировать память руками — есть отдельная команда:

/memory

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

Частые ошибки

FAQ

Чем CLAUDE.md отличается от обычного промпта?

Промпт — разовый: сказал в чате, агент учёл здесь и сейчас, в новой сессии этого уже нет. CLAUDE.md — постоянный: он автоматически подгружается в контекст в каждой сессии, ничего повторять не надо. Промпт — для конкретной задачи, CLAUDE.md — для правил, которые верны всегда.

Где он лежит?

Проектный CLAUDE.md — в корне проекта, рядом с кодом. Есть и глобальный, на уровне пользователя — ~/.claude/CLAUDE.md: он применяется ко всем твоим проектам сразу. В глобальный идёт то, что верно везде (как ты любишь общаться, общие запреты), в проектный — всё специфичное для конкретного репозитория. Проектный дополняет глобальный, а в спорных местах перебивает его.

Надо ли править файл вручную?

Как удобнее. Можно пополнять на ходу через #, не отрываясь от работы, а можно открыть файл в редакторе (или через /memory) и переписать руками — почистить, переформулировать, выкинуть устаревшее. Оба пути рабочие, чаще всего используют оба: # для быстрых добавлений, ручная правка для гигиены.

А если я работаю в Codex, а не в Claude Code?

Тогда файл-карта называется AGENTS.md, а не CLAUDE.md. Принцип ровно тот же — вводный инструктаж в корне проекта, — меняется только имя файла.

Что ты увидишь

Быстрый способ дописать правило в память проекта — строка через # прямо в чате. Агент подтверждает, куда записал:

> # всегда запускай тесты через bun, не npm
✔ Добавлено в CLAUDE.md (память проекта)

Итог

Claude Code каждую сессию забывает твой проект. CLAUDE.md — файл в корне проекта, который агент подгружает в контекст каждый раз и держит как постоянную память правил: стек, команды, стиль, границы. Создаёшь через /init, пополняешь на ходу через #, чистишь через /memory, общее для всех проектов кладёшь в глобальный ~/.claude/CLAUDE.md. Держи его коротким и конкретным — каждая лишняя строка стоит тебе контекста.

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