Два слоя памяти 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

Порядок загрузки: 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


::widget{id="rc-3"}

## 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 в сессии.

Как писать эффективный 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 вырезаются перед инъекцией в контекст. Пользуйтесь ими для служебных пометок — они не тратят токены.

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

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

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

See also

• Управление контекстным окном — как CLAUDE.md взаимодействует с контекстом: что выживает после /compact, бюджет токенов и гигиена контекста
• Настройки и иерархия конфигурации — settings.json идёт рука об руку с CLAUDE.md; их иерархии схожи и дополняют друг друга
• Hooks — события жизненного цикла — когда CLAUDE.md не достаточно и нужна детерминированная, а не контекстная гарантия выполнения
• Skills — переносимые навыки — альтернатива для процедурных инструкций, которые не нужны в каждой сессии
• Субагенты и контекстная изоляция — субагенты могут иметь собственную авто-память
• Настройки и иерархия конфигурации — enterprise managed policy работает аналогично для settings.json и для CLAUDE.md
• Плановый режим и разработка через тесты — CLAUDE.md с инструкцией «всегда начинать в плановом режиме» — частый паттерн в командах