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

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

Что это за файл простыми словами

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

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

Проектный и глобальный

Файлов может быть два уровня, и они складываются.

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

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

Зачем он вообще нужен

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

• Тон и формат ответов. Коротко или подробно, на каком языке, с примерами кода или без.
• Стек и инструменты. Какие технологии в проекте, чем собирать, чем тестировать, какой менеджер пакетов.
• Границы. Что агенту делать можно без спроса, а что — только с твоего согласия.
• Важные пути. Где живёт код, где конфиги, где тесты, что вообще не нужно открывать.

Что класть и что НЕ класть

Главное искушение новичка — навалить в файл всё подряд «на всякий случай». Не делай так. CLAUDE.md грузится в контекст каждый раз, когда агент начинает работать. Чем он длиннее, тем дороже каждый запуск и тем хуже фокус — важные правила тонут среди второстепенных, и агент перестаёт их замечать.

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

Не клади: то, что агент и так выяснит из кода за пару секунд; длинные пересказы документации; одноразовые задачи («сегодня почини баг X»); устаревшие заметки «на память». Файл — это правила, а не дневник и не свалка контекста.

Хороший тест перед добавлением строки: «Это правило сэкономит мне повторное объяснение в будущих сессиях?» Если нет — ему здесь не место.

Как писать правила, которые работают

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

Конкретно вместо общего

Не «делай аккуратно», а «функции короче 40 строк, имена переменных полными словами без сокращений». Чем измеримее формулировка, тем меньше места для интерпретации.

Запрет надёжнее пожелания

Жёсткая граница «никогда не пиши напрямую в ветку main, только через pull request» соблюдается лучше, чем мягкое «старайся работать через PR». Если правило важное — формулируй его как чёткую черту, а не как рекомендацию.

Формулируй позитивно

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

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

• Слишком длинно. Простыня на тысячу строк, где правила тонут. Короткий сфокусированный файл побеждает длинный всегда.
• Размыто. Общие слова без конкретики, которые агент не может применить.
• Противоречиво. В одном месте «всегда X», в другом «никогда X». Агент выберет наугад, и виноват будешь ты.
• Мёртвые правила. Проект переехал на другой фреймворк, а в файле всё ещё инструкции про старый. Устаревшее правило хуже отсутствующего — оно активно вредит.

Как развивать файл по ходу

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

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

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

Короткий пример структуры

# Проект: сервис заметок

## Стек
- Backend: Python 3.12, FastAPI
- Frontend: React + TypeScript
- БД: PostgreSQL

## Команды
- Тесты: pytest
- Сборка фронта: npm run build
- Линтер перед коммитом: ruff check

## Структура
- src/api — эндпоинты
- src/db — модели и миграции
- tests — тесты (новый код = новый тест)

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

Это скелет, а не образец на копирование: у твоего проекта будут свои разделы. Важна не форма, а принцип — короткие конкретные блоки под заголовками, которые легко читать и человеку, и агенту.

Мостик дальше

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