2 апреля 2026 г. Read in English

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

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

Что такое CLAUDE.md

Многие относятся к CLAUDE.md как к случайной заметке для модели. Обычно это заканчивается одинаково: слишком расплывчато, слишком длинно, слишком много общих советов, а потом Claude игнорирует половину файла.

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

Моё правило: короткий и острый файл почти всегда лучше, чем “полный справочник проекта”.

CLAUDE.md и auto memory

Если правило должно жить в каждой сессии, ему место в CLAUDE.md.

Auto memory это поддерживающий слой. Claude сам записывает заметки по ходу работы: команды билда, паттерны отладки, твои предпочтения. При старте Claude Code подхватывает MEMORY.md примерно до первых 200 строк (или ~25KB), так что относись к нему как к короткому индексу, а не как к свалке. Подробнее — в секции 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

Лучшие 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 на английском

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

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

❌ "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 синтаксис чтобы не дублировать контент:

# Project Overview
@README.md

# Available Commands
@package.json

# Git Workflow
@docs/git-workflow.md

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

Импорты разворачиваются и загружаются в контекст при старте. Глубина — до 5 уровней вложенности.

Осторожно с большими файлами: @package.json подтянет весь файл в контекст. Для больших файлов это расходует токены — импортируй только то, что Claude действительно нужно видеть каждую сессию.

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

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

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

Path-specific rules

Правила загружаются только когда Claude работает с matching файлами — экономит контекст:

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

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

---
paths:
  - "**/*.test.ts"
  - "**/*.spec.ts"
---

# Testing Rules
- Один describe блок на файл
- Названия тестов: should + действие
- Мокать только внешние зависимости

Паттерны glob:

Паттерн	Что матчит
`*/.ts`	Все TypeScript файлы
`src/*/`	Всё в src/
`src/*/.{ts,tsx}`	TS и TSX в src/
`*.md`	Markdown в корне

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

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

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

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

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

Auto memory

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

Хранится в:

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

Управление:

/memory    # просмотр, редактирование, toggle on/off

Говоришь 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/