`CLAUDE.md`, rules и auto memory

1. CLAUDE.md появляется именно сейчас

CLAUDE.md начинает работать только тогда, когда вокруг уже есть порядок: безопасный старт, понятная рабочая директория, внятная posture по правам. Напишете проектные инструкции раньше — при грязном working tree, без отдельной ветки и с режимом доступа «на авось» никакой markdown не спасёт.

Думайте о CLAUDE.md как о короткой записке рядом с кодовой базой. Это не документация и не замена README.md. README отвечает человеку: «как поднять проект и что это». CLAUDE.md отвечает Claude: «как работать здесь, чтобы не наделать лишнего».

Фраза «проект на Spring Boot и Next.js» в CLAUDE.md бесполезна — это видно из репозитория. А «исторические миграции в db/migration/ не переписываем, новые изменения только новым файлом» — полезна: это договорённость команды, из кода она не очевидна.

У Commerce OS такой файл выглядел бы так:

# CLAUDE.md

## Команды проекта
- run: `docker compose up`
- test: `./gradlew test`
- check: `./gradlew check`

## Договорённости
- не менять `/api/v1/**` без явного подтверждения
- не переписывать существующие файлы в `db/migration/`
- в ответе всегда перечислять изменённые файлы и запущенные проверки

Файл хорош тем, что короткий. Никакой экскурсии по архитектуре магазина — три вещи, которые Claude реально использует: как запускать проект, где опасные зоны и в каком виде отчитываться. Живёт в репозитории, воспринимается как часть проекта.

2. Полезное наполнение CLAUDE.md

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

Рабочая таблица для наполнения:

Особенно полезны команды. Claude очень охотно угадывает, чем запускать проект, и иногда угадывает не туда. Если у вас реально принято поднимать Commerce OS через docker compose up, а проверки гонять через ./gradlew check, лучше записать это явно. Одна точная строка экономит много лишних попыток.

Не менее полезны скрытые особенности проекта. Если в сервисе оплаты все суммы хранятся в копейках, а не в рублях или долларах, это нужно писать. Если удаление заказа означает не физическое удаление строки из базы, а soft delete, это тоже стоит записать. Если локально приложение нормально работает только при поднятом worker, а по одному npm run dev или bootRun всё выглядит живым, но часть логики молча не работает, это тоже хороший кандидат для CLAUDE.md.

Отдельно полезно записывать ожидания к формату ответа. Например, не просто «сделай правку», а «после изменений перечисли, какие файлы менял, какие проверки запускал и что осталось рискованным». Это уже не про запуск проекта, а про качество вашей повседневной работы. И такие строки очень быстро окупаются: вы меньше играете в археолога по diff’ам и реже ловите сюрпризы.

3. Лишнее в CLAUDE.md

Почти все проблемы с этим файлом начинаются не с того, что туда попало мало полезного, а с того, что туда попало слишком много лишнего. Как только CLAUDE.md начинает напоминать семейный архив, важные правила прячутся среди шума, а Claude перестаёт получать из него чёткий сигнал. Хороший файл читать скучно. И это, кстати, комплимент.

Самая частая ошибка — записывать туда то, что относится не к проекту, а к одной текущей задаче. Если сегодня вы чините сортировку заказов, это не повод прописывать в CLAUDE.md: «сейчас работаем только с RefundService». Это временная инструкция для конкретной сессии, а не постоянная договорённость проекта. Завтра задача будет другой, а мусор в файле останется.

Вторая частая ошибка — записывать очевидное. Строка «проект на Next.js» обычно ничего не даёт, если в репозитории уже лежат package.json, next.config.* и папка app/. А вот строка «не предлагай массовый рефакторинг форматирования в одном diff с фичей» — даёт, потому что это не про стек, а про рабочий режим команды.

Третья ошибка — писать абстрактные моральные лозунги. Фразы вроде «пиши хороший код», «будь аккуратен», «не ломай ничего» звучат очень воспитанно, но пользы дают мало. Чем конкретнее правило, тем лучше оно работает.

Сравните такие пары:

Плохо: «Делай всё аккуратно и современно».
Хорошо: «Не меняй сигнатуры публичных методов в src/api/** без явного подтверждения».

Плохо: «Соблюдай стиль проекта».
Хорошо: «Не предлагай форматирующие правки вне текущего scope задачи».

Плохо: «Следи за безопасностью».
Хорошо: «Не читай и не редактируй .env* без прямого запроса».

И ещё одна очень важная мысль: CLAUDE.md — это context, not enforcement.

Если вы написали в файле «не трогать .env», это полезная инструкция. Но это не жёсткий запрет. Если у вас есть действительно опасная зона, которую нельзя трогать случайно, защищать её нужно не только словами в markdown, а ещё и другими механизмами: Git baseline, permissions, .gitignore, защищённые пути, дополнительные проверки. Иначе вы будете ждать от памятки поведения сейфа. Памятка так не умеет.

4. CLAUDE.local.md — локальные заметки

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

Именно для этого полезен CLAUDE.local.md. Это ваш локальный файл для заметок по этому проекту. Он не должен коммититься в репозиторий и не должен подменять общие договорённости проекта. Если CLAUDE.md — это табличка на двери мастерской, то CLAUDE.local.md — это ваш стикер на ноутбуке.

Вот типичный локальный пример:

# CLAUDE.local.md

## Заметки о workspace
- локальная БД работает на порту 5454
- тестовые CSV для импорта лежат в `~/projects/data/subscriptions/`

## Личные предпочтения
- предлагай изменения небольшими diff-блоками
- если затронуто больше двух файлов, сначала коротко опиши план

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

CLAUDE.local.md не коммитится, и это хорошо. Но Claude всё равно может его читать в вашей локальной среде. Значит, класть туда реальные токены, пароли и чувствительные данные всё равно не надо. Локальность спасает от случайного коммита, но не превращает файл в сейф.

Разницу между двумя файлами удобно видеть так:

CLAUDE.md

CLAUDE.local.md

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

5. Разница CLAUDE.md, rules и auto memory

Когда рядом встречаются CLAUDE.md, rules и auto memory, легко решить, что это просто три варианта одного и того же. На самом деле у них разная роль. Один механизм описывает проект целиком, другой сужает поведение до конкретной зоны, а третий хранит то, что Claude запомнил по ходу работы сам. Если их смешать, файл быстро становится шумным, а полезные правила теряются.

Удобно держать в голове такую схему:

flowchart TD
    A[Появилась новая инструкция или заметка] --> B{Она нужна всей команде и почти всем сессиям?}
    B -->|Да| C[Положить в CLAUDE.md]
    B -->|Нет| D{Она нужна только вам в этом проекте?}
    D -->|Да| E[Положить в CLAUDE.local.md]
    D -->|Нет| F{Она относится только к одной папке или типу файлов?}
    F -->|Да| G[Это кандидат на отдельное rule]
    F -->|Нет| H{Это временный или недавно узнанный факт?}
    H -->|Да| I[Пусть живёт в auto memory до проверки]
    H -->|Нет| J[Скорее всего, записывать вообще не нужно]

Самая полезная часть этой схемы — ветка про rules. Если правило относится только к узкой области проекта, не надо тащить его в общий файл. Представьте, что у вас есть строгая договорённость только для db/migration/** или только для каталога payments/. Если половина CLAUDE.md посвящена двум опасным папкам, общий файл перестаёт быть общим и начинает мешать чтению. В таком случае логичнее вынести узкое правило отдельно, а в CLAUDE.md оставить только короткое напоминание, что такие чувствительные зоны существуют.

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

6. auto memory требует перепроверки

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

Представьте простой сценарий. Неделю назад вы временно держали старый путь /api/v0/refunds, потому что миграция маршрутов ещё не закончилась. Claude это запомнил. Через неделю вы маршрут починили, а память не пересмотрели. И вот в новой сессии Claude уверенно тянется к уже неактуальному пути, потому что когда-то честно это выучил. Ошибка не в том, что память плохая. Ошибка в том, что её никто не проверил.

Поэтому полезно держать очень простой рефлекс проверки памяти:

Точная slash-команда для просмотра или очистки памяти зависит от версии Claude Code, поэтому здесь правильная привычка очень простая: заглянуть в /help и найти актуальную команду в вашей среде. Нам важен не конкретный синтаксис, а сам рабочий ритуал.

И есть одно очень полезное правило, которое стоит запомнить почти дословно: если факт настолько важен, что вы расстроитесь при его нарушении, не держите его только в auto memory. Выносите его уровнем выше — в CLAUDE.md или в отдельное правило. Память хороша для вспомогательных вещей. Основа проекта должна жить в явном файле.

7. Короткий baseline для pet-проекта

Самый хороший первый CLAUDE.md — не тот, который «идеально покрывает всё», а тот, который вы действительно будете открывать и поддерживать. Для pet-проекта лучше начать с маленького baseline: команды, две-три неочевидные договорённости, одна-две опасные зоны и понятный формат ответа Claude. Этого уже достаточно, чтобы перестать повторять одни и те же инструкции из сессии в сессию.

Например, для маленького проекта по учёту подписок такой baseline мог бы выглядеть так:

# CLAUDE.md

## Команды
- run: `npm run dev`
- test: `npm test`

## Договорённости проекта
- все суммы храним в копейках
- не отключать TypeScript strict mode
- в ответе перечисляй изменённые файлы и запущенные проверки

## Не делать
- не трогать `.env*` без прямого запроса
- не делать массовый рефакторинг вне текущего запроса

Если ваш pet-проект на Java и Gradle, файл останется таким же по смыслу, поменяются только команды. Например, run станет ./gradlew bootRun, а test — ./gradlew test. Логика не меняется: вы не описываете весь мир, вы кладёте на стол короткую рабочую памятку.

Полезно ещё и то, что такой файл не обязан быть окончательным с первого дня. Он живой. Если замечаете, что Claude уже третий раз предлагает править исторические миграции, — это сигнал добавить короткое правило. Если какая-то строка перестала быть актуальной, её лучше удалить, чем хранить «на всякий случай». У хорошего CLAUDE.md нет цели стать толще. У него есть цель стать точнее.

Именно поэтому короткий baseline почти всегда выигрывает у «умного», но раздутого файла. Когда вы завтра откроете проект, Claude уже будет знать, чем запускать код, какие зоны у вас чувствительные и в каком виде вы хотите видеть результат. А вы не будете в четвёртый раз писать одно и то же в чат. Для рабочего процесса это очень приятное ощущение: будто в мастерской наконец появились подписанные ящики, и молоток больше не хранится в холодильнике.

1

Задача

Claude code, 2 уровень, 3 лекция

Недоступна

Применение memory review

Применение memory review

Открыть