ENGРУС

Как писать эффективный CLAUDE.md

Что писать в CLAUDE.md, что оставить auto memory и как удержать файл в размере, который дочитывают до конца.

Актуально на апрель 2026.

Каждый CLAUDE.md, который я писал, проходил через одну и ту же траекторию: начинаешь с “полного” файла, смотришь как Claude игнорирует половину, вырезаешь всё лишнее, злишься на время потраченное на остальное. Файл на этом проекте — 113 строк, и я до сих пор считаю, что он длинный. Глобальный — 29, вот его я готов защищать.

Приоритетный контекст, а не конфиг

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

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

Короткий и острый файл лучше “полного справочника проекта”. Если правило нужно мне в каждой сессии — оно живёт здесь. Всё что мягче — в auto memory.

Где размещать

Файл Scope Кто видит
./CLAUDE.md или ./.claude/CLAUDE.md Проект Команда через git
./CLAUDE.local.md Проект (локально) Только ты (gitignored)
~/.claude/CLAUDE.md Все проекты Только ты

CLAUDE.md загружается по дереву директорий вверх от текущей папки. Если запускаешь Claude в foo/bar/ — загрузятся и foo/bar/CLAUDE.md и foo/CLAUDE.md.

Именно поэтому маленькие локальные файлы почти всегда лучше, чем один гигантский универсальный.

Рабочий скелет

Лучшие CLAUDE.md скучные в хорошем смысле: практичные, конкретные и легко сканируются глазами.

# Project Overview
Короткое описание что это за проект и зачем.
Одно-два предложения.

# Tech Stack
- Runtime: Bun (не Node.js)
- ORM: Drizzle
- Linter: Biome (не ESLint/Prettier)
- Testing: Vitest

# Project Structure
src/
├── api/        # API handlers
├── db/         # database schema и migrations
└── utils/      # shared utilities

# Commands
- `bun run dev` — запустить dev сервер
- `bun test` — тесты
- `bun run lint` — линтинг
- `bun run build` — production сборка

# Coding Conventions
- 2-space indentation
- Именуй файлы kebab-case
- Предпочитай named exports над default
- Типизация обязательна, no `any`

# Workflow
- Создавай feature branch перед изменениями
- Запускай тесты перед коммитом
- Не коммить в main напрямую
- Commit messages на английском

Это форма, а не шаблон для копирования. Обязательными я бы назвал только Commands и неочевидные факты про стек — именно на них Claude ошибается без подсказки. Остальное либо оправдывает своё место, либо вырезается.

Принципы написания

Конкретность вместо расплывчатости

❌ "Format code properly"
✅ "Use 2-space indentation, no semicolons"

❌ "Test your changes"
✅ "Run `bun test` before every commit"

❌ "Keep files organized"
✅ "API handlers live in src/api/handlers/"

❌ "Write good commit messages"
✅ "Commit messages: type(scope): description — например feat(auth): add JWT refresh"

До 200 строк

Длиннее — это сразу две проблемы: слабее adherence и больше контекста тратится на сам файл. Если CLAUDE.md растёт, разбивай на .claude/rules/ или используй импорты.

Без противоречий

Если два правила конфликтуют, Claude выберет одно и не скажет какое. Периодически просматривай файл.

Заголовки и bullets

Claude сканирует структуру как человек. Стены текста воспринимаются как стены текста.

Что писать, что не писать

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

Пиши:

  • Команды запуска, тестов, линтинга
  • Нестандартные решения (“мы используем Bun а не Node”)
  • Структура проекта — где что лежит
  • Coding conventions специфичные для проекта
  • Архитектурные решения и почему они приняты
  • Вещи которые Claude не может обнаружить из кода

Не пиши:

  • Что Claude и так поймёт прочитав код
  • Общие best practices (Claude их знает)
  • Детали которые часто меняются
  • Личные предпочтения (они в ~/.claude/CLAUDE.md)

Сложнее всего удержаться от общих best practices, которые пишешь в любой onboarding-документации. Claude не нужно говорить “пиши чистый код”. Ему нужно знать, что в этом проекте используется Bun, а не Node — потому что именно здесь он реально ошибается без контекста.

Импорты для модульности

Используй @path синтаксис чтобы не дублировать контент:

# Git Workflow
@docs/git-workflow.md

# Personal preferences (не попадёт в git)
@~/.claude/my-preferences.md

Импорты разворачиваются и загружаются в контекст при старте, вложенность — до 5 уровней. Ловушка в том, что импорт тянет файл целиком: @package.json стоит тебе всех строк с зависимостями каждую сессию — ради того, чтобы не выписывать четыре команды руками.

Я импортами здесь не пользуюсь. Один файл на 113 строк — ниже того порога, где разбиение начинает окупаться.

.claude/rules/ — модульные правила

Для больших проектов вместо одного монолитного файла:

.claude/rules/
├── testing.md       # правила тестирования
├── api-design.md    # правила API
├── security.md      # требования безопасности
└── frontend.md      # правила фронтенда

Path-specific rules

Блок paths: во фронтматтере означает, что правило загружается только когда Claude трогает подходящие файлы — всё остальное время оно не стоит ничего:

---
paths:
  - "src/api/**/*.ts"
---

# API Rules
- Валидация на все inputs обязательна
- Стандартный формат ошибок: { error, code, message }
- Все endpoints документировать через JSDoc

Glob-паттерны обычные — **/*.ts, src/**/*, src/**/*.{ts,tsx}.

На проекте такого размера мне это ни разу не понадобилось. Штука начинает окупаться, когда у разных частей репозитория реально разные правила и ты устал смотреть, как Claude применяет фронтендовые конвенции к миграциям базы.

Глобальный CLAUDE.md для личных предпочтений

~/.claude/CLAUDE.md — загружается во всех проектах. Хорошее место для персональных предпочтений которые не нужно шарить с командой:

# My Working Style
- Объясняй что собираешься делать перед тем как делать
- Предпочитай маленькие атомарные коммиты
- Если задача неоднозначна — спроси прежде чем начинать
- При ошибках показывай полный stack trace

# Code Preferences
- Предпочитаю функциональный стиль над ООП
- Явные типы везде, никакого any
- Комментарии только для неочевидной логики

# Workflow
- Всегда запускай линтер после изменений
- Commit messages на английском в формате conventional commits

Мой — 29 строк, и большая часть это вообще не предпочтения, а факты про окружение. macOS с BSD-юзерлендом, поэтому sed -i требует аргумент. Homebrew лежит в /opt/homebrew. Использовать fd и rg, а не find и grep. Вот это соблюдается всегда — потому что это то, на чём Claude на моей машине ошибается без подсказки. Стилевые предпочтения под ними подхватываются в лучшем случае через раз.

Auto memory

Auto memory — поддерживающий слой: Claude сам записывает заметки по ходу работы, команды билда, паттерны отладки, выведенные предпочтения. Работает пока остаётся маленьким и скучным. Думай о нём как об индексе “что стоит помнить”, а не как о журнале всего, что происходило.

При старте Claude Code подхватывает MEMORY.md примерно до первых 200 строк (или ~25KB) — это и есть настоящий аргумент держать его индексом, а не свалкой.

Я держу его выключенным на общих проектах и включённым на личных. Для соло-работы заметки реально полезны — quirks сборки, вещи упомянутые вскользь, которые не хочется повторять. В командных проектах начинается странное: memory накапливает шум из разных контекстов и превращается в “память” с устаревшей информацией.

Хранится в:

~/.claude/projects/<project>/memory/
├── MEMORY.md          # индекс, загружается каждую сессию
├── debugging.md       # паттерны отладки
└── ...

Посмотреть, отредактировать или выключить:

/memory

Говоришь Claude “запомни что…” → сохраняет в auto memory. Говоришь “добавь это в CLAUDE.md” → добавляет в файл.

Что стоит знать до того, как начнёшь на неё полагаться: memory локальная и не синхронизируется между машинами, а все worktrees одного репо шарят одну папку памяти.

Генерируем первую версию

Если у тебя ещё нет CLAUDE.md, не пытайся сразу написать идеальную версию.

/init    # Claude проанализирует кодовую базу и сгенерирует CLAUDE.md

После /init агрессивно редактируй результат: вырезай воду, оставляй команды, добавляй только те правила, которые Claude не смог бы сам вывести из репозитория. Сгенерированный файл — это отправная точка, не цель. Относись к нему как к драфту от нового человека в команде, который только что прочитал README: полезно, но не отфильтровано.

После /compact

Это и есть практический тест, должна ли инструкция жить в CLAUDE.md.

CLAUDE.md переживает компакцию, потому что Claude перечитывает его с диска. Если инструкция “исчезла” после /compact, обычно это значит, что она существовала только в чате и так и не стала проектной памятью.

Debugging

Если Claude не следует CLAUDE.md:

/memory    # проверить что файл вообще загружен

Если файла нет в списке, Claude его не видит. Сначала проверь расположение, а уже потом переписывай содержимое.

Для подробного логирования какие файлы загружаются и когда — используй hook InstructionsLoaded в settings.json.

AGENTS.md совместимость

Если в репо уже есть AGENTS.md для других AI инструментов — импортируй его в CLAUDE.md:

@AGENTS.md

## Claude-specific
- Используй plan mode для изменений в src/billing/