CLAUDE.md и система памяти

Иерархия файлов памяти (enterprise/project/user), авто-память, импорты через @path и шорткат #. Как писать CLAUDE.md, который реально улучшает поведение агента.

Два слоя памяти Claude Code

Каждая сессия Claude Code начинается с пустого контекстного окна. Никакой «долгосрочной памяти» в модели нет — зато есть два механизма, которые переносят знания между сессиями.

CLAUDE.md — файлы инструкций, которые вы пишете сами. Claude читает их в начале каждой сессии.

Авто-память — заметки, которые Claude записывает себе в процессе работы: найденные команды сборки, паттерны кода, ваши предпочтения.

Важный нюанс: оба механизма — это контекст, а не конфигурация. Claude читает CLAUDE.md и старается следовать инструкциям, но строгого исполнения нет. Для детерминированных действий (например, «всегда запускать линтер перед коммитом») используйте Hooks — события жизненного цикла.

---

Иерархия файлов CLAUDE.md

CLAUDE.md может лежать в нескольких местах с разным охватом. Загружаются все найденные файлы — от самого общего к самому конкретному.

flowchart TD A["🏢 Managed Policy\n/etc/claude-code/CLAUDE.md\nили managed-settings.json"] --> B B["👤 User\n~/.claude/CLAUDE.md\n~/.claude/rules/*.md"] --> C C["📁 Project\n./CLAUDE.md\n./.claude/CLAUDE.md\n.claude/rules/*.md"] --> D D["🔒 Local\n./CLAUDE.local.md"] style A fill:#e74c3c,color:#fff style B fill:#e67e22,color:#fff style C fill:#27ae60,color:#fff style D fill:#2980b9,color:#fff E["📝 Auto Memory\n~/.claude/projects/<project>/memory/MEMORY.md"] F["📖 В контекст каждой сессии:"] --> A F --> B F --> C F --> D F --> E style F fill:#8e44ad,color:#fff style E fill:#16a085,color:#fff

flowchart TD
    A["🏢 Managed Policy\n/etc/claude-code/CLAUDE.md\nили managed-settings.json"] --> B
    B["👤 User\n~/.claude/CLAUDE.md\n~/.claude/rules/*.md"] --> C
    C["📁 Project\n./CLAUDE.md\n./.claude/CLAUDE.md\n.claude/rules/*.md"] --> D
    D["🔒 Local\n./CLAUDE.local.md"]

    style A fill:#e74c3c,color:#fff
    style B fill:#e67e22,color:#fff
    style C fill:#27ae60,color:#fff
    style D fill:#2980b9,color:#fff

    E["📝 Auto Memory\n~/.claude/projects/&lt;project&gt;/memory/MEMORY.md"]
    F["📖 В контекст каждой сессии:"] --> A
    F --> B
    F --> C
    F --> D
    F --> E

    style F fill:#8e44ad,color:#fff
    style E fill:#16a085,color:#fff

Иерархия файлов памяти Claude Code: от enterprise до локального уровня. Все файлы конкатенируются в контекст в порядке от общего к частному.

Уровень	Путь	Охват	Попадает в git
Managed policy (enterprise)	macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md`<br>Linux: `/etc/claude-code/CLAUDE.md`	Все пользователи машины	Нет (деплоится IT)
User	`~/.claude/CLAUDE.md`	Все проекты конкретного пользователя	Нет
Project	`./CLAUDE.md` или `./.claude/CLAUDE.md`	Весь проект, общий для команды	Да
Local	`./CLAUDE.local.md`	Проект, только для вас	Нет (добавить в .gitignore)

Порядок загрузки: managed → user → project → local. Файлы не перекрывают друг друга — они конкатенируются в контекст. Файлы из поддиректорий загружаются лениво: только когда Claude читает файлы в этой директории.

Практика: project CLAUDE.md коммитится в репозиторий и разделяется с командой. В нём — архитектурные решения, coding conventions, типовые команды. Личные предпочтения (ваши sandbox-URL, локальные пути) — в CLAUDE.local.md, добавленном в .gitignore.

---

Импорты через @path

CLAUDE.md поддерживает импорт других файлов через синтаксис @path/to/file. Импортированные файлы раскрываются в контекст при старте сессии.

# CLAUDE.md

См. @README.md для обзора проекта.
Доступные команды: @package.json

Git workflow

@docs/git-conventions.md


Несколько правил:
- Пути могут быть относительными (от файла с импортом) и абсолютными
- Поддерживается рекурсивный импорт до 4 уровней вложенности
- Импортированные файлы **полностью** попадают в контекст при запуске — импорт помогает с организацией, но не экономит токены

Если вы работаете в нескольких git worktrees одного репозитория и хотите разделить личные инструкции — импортируйте файл из домашней директории:

В CLAUDE.local.md текущего проекта

@~/.claude/my-project-prefs.md


При первой встрече с внешними импортами Claude Code покажет диалог подтверждения со списком файлов.

---

## Директория .claude/rules/

Для больших проектов можно разбить инструкции на тематические файлы в `.claude/rules/`:

.claude/

├── CLAUDE.md

└── rules/

├── code-style.md # соглашения по стилю

├── testing.md # требования к тестам

└── api-design.md # стандарты API


Файлы правил поддерживают **path-scoped** режим через YAML-фронтматтер. Такие правила загружаются только когда Claude работает с совпадающими файлами:

---

paths:

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

- "lib/**/*.ts"

---

API Rules

Все эндпоинты обязаны валидировать входные данные
Использовать стандартный формат ошибок из src/api/errors.ts


Path-scoped правила — мощный инструмент для монорепо: инструкции для фронтенда не загрязняют контекст при работе с бэкендом и наоборот.

---

## Авто-память

Авто-память хранится в `~/.claude/projects/<project>/memory/` и включает:

- `MEMORY.md` — главный файл-индекс; **первые 200 строк или 25KB** загружаются в каждую сессию
- Тематические файлы (`debugging.md`, `api-conventions.md`) — загружаются по запросу

Claude решает сам, что стоит запомнить: нестандартную команду сборки, найденный баг-паттерн, ваше предпочтение по именованию. Когда видите «Writing memory» в интерфейсе — Claude активно обновляет эти файлы.

Важно: авто-память **локальная**. Все worktrees одного git-репозитория делят одну директорию памяти. На другую машину или в облачные агенты она не переносится автоматически.

Чтобы попросить Claude запомнить что-то прямо сейчас: напишите в чате «запомни, что мы всегда используем pnpm, не npm» — Claude сохранит это в авто-память. Чтобы добавить в CLAUDE.md: «добавь это в CLAUDE.md».

Просмотреть и отредактировать всё сохранённое: команда `/memory` в сессии.

Показать ответ

Нет. Из MEMORY.md загружаются только первые 200 строк или 25KB (что наступит раньше). Всё, что выходит за этот предел, в начале сессии не загружается. Именно поэтому Claude старается держать MEMORY.md кратким индексом, перемещая детальные заметки в тематические файлы (debugging.md, api-conventions.md и т.д.), которые загружаются по требованию.

---

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

CLAUDE.md — не документация для людей. Это инструкции для модели, которая читает их при каждом старте. Несколько правил, которые реально влияют на качество следования:

Размер: до 200 строк. Больше — больше токенов и ниже adherence. Если файл разрастается, переносите специфичные вещи в .claude/rules/ с path-scoping.

Конкретность, не абстракции. Сравните:

# ❌ Плохо
Форматируй код аккуратно и тестируй изменения.

# ✅ Хорошо
- Отступы: 2 пробела (не табы)
- Запускать `npm test` перед каждым коммитом
- Обработчики API живут в src/api/handlers/

Структура через Markdown. Headers и bullets Claude сканирует как читатель — структурированные секции работают лучше плотных параграфов.

Консистентность. Два противоречащих правила — Claude выберет одно произвольно. Периодически ревьюйте CLAUDE.md, особенно после добавления вложенных файлов.

Что класть в CLAUDE.md:

Команды сборки, тестирования, деплоя
Naming conventions и coding standards
Архитектурные решения, которые не видны из кода
«Всегда делай X» правила

Что не класть:

Многошаговые процедуры — их лучше упаковать в Skills — переносимые навыки
Инструкции, нужные только для одной части кодовой базы — используйте path-scoped rules
Личные предпочтения — в ~/.claude/CLAUDE.md или CLAUDE.local.md

Примечание о HTML-комментариях:  в CLAUDE.md вырезаются перед инъекцией в контекст. Пользуйтесь ими для служебных пометок — они не тратят токены.

Вы добавляете в project CLAUDE.md: «Всегда запускай `make lint && make test` перед коммитом». Это хорошая идея?
CLAUDE.md проекта вырос до 450 строк и содержит отдельные разделы для фронтенда (React), бэкенда (Go) и базы данных. Что лучше сделать?
Новый разработчик спрашивает, куда положить свой любимый стиль кавычек (одинарные vs двойные), который отличается от командного стандарта?
Вы хотите добавить примечание «этот файл редактировал Иван, не менять без обсуждения» в CLAUDE.md так, чтобы Claude это не читал и токены не тратились?

---

Быстрый старт: /init и /memory

/init — запускает автоматическое создание CLAUDE.md. Claude анализирует кодовую базу и генерирует файл с командами сборки, конвенциями и структурой проекта. Если CLAUDE.md уже есть — предложит улучшения. С флагом CLAUDE_CODE_NEW_INIT=1 запускается интерактивный режим: Claude проведёт вас через несколько вопросов и покажет предложение перед записью.

/memory — открывает список всех загруженных файлов памяти (CLAUDE.md, CLAUDE.local.md, rules). Позволяет переключить авто-память и открыть любой файл в редакторе. Используйте как быстрый диагностический инструмент: если инструкция не соблюдается, первый шаг — проверить через /memory, что файл вообще загружается.