CLAUDE.md
Файл памяти проекта для AI-агента — экономит токены и обеспечивает консистентность
Определение
CLAUDE.md — файл в корне проекта, который Claude Code автоматически читает при входе в папку. Содержит правила проекта, описание архитектуры, стек, паттерны и известные решения ошибок. Экономит токены: агент не тратит контекст на повторный анализ проекта при каждом запуске.
Аналогия: CLAUDE.md — это бриф для нового сотрудника. Вместо того чтобы каждый раз объяснять «что за проект, какой стек, какие правила» — всё записано в одном месте.
Уровни
CLAUDE.md работает на трёх уровнях:
| Уровень | Путь | Что содержит |
|---|---|---|
| Глобальный | ~/.claude/CLAUDE.md | Правила для всех проектов: стиль коммитов, язык ответов, персональные предпочтения |
| Проектный | ./CLAUDE.md | Правила конкретного проекта: стек, архитектура, границы |
| Модульный | .claude/rules/*.md | Правила для отдельных доменов: бизнес-логика, деплой, тесты |
Агент объединяет все три уровня при запуске. Модульные правила подгружаются по контексту задачи.
Что писать в CLAUDE.md
# My Project
## Стек
- Python 3.12 + python-telegram-bot 20.x
- PostgreSQL на Railway
- Деплой: Railway (worker, не web)
## Правила
- async/await везде, не sync
- Type hints обязательны
- Коммиты на английском: feat:, fix:, docs:
## Известные проблемы
- Railway требует Procfile с `worker:` для ботов
- При обновлении БД — сначала миграция, потом деплой
## Чего НЕ делать
- Не трогать config/production.yml напрямую
- Не коммитить .env файлы
Чеклист: что должно быть
- Стек технологий и версии
- Архитектурные решения и почему они такие
- Стандарты кодирования и именования
- Известные баги и их решения
- Границы проекта (что НЕ делать)
- Связи между модулями
Anti-patterns
- Слишком длинный CLAUDE.md — если больше 500 строк, разбить на
.claude/rules/ - Дублирование README — CLAUDE.md для агента, README для людей
- Устаревшая информация — хуки могут автоматически обновлять CLAUDE.md после каждой сессии
- Отсутствие секции «чего НЕ делать» — агент будет принимать решения без ограничений
Аналоги в других инструментах
| Инструмент | Файл | Формат |
|---|---|---|
| Claude Code | CLAUDE.md, .claude/rules/*.md | Markdown |
| Cursor | .cursor/rules/*.md | Markdown |
| Windsurf | .windsurfrules | Markdown |
| VS Code Copilot | .github/copilot-instructions.md | Markdown |
Концепция одна: дать агенту карту проекта, чтобы он не тратил контекст на разведку.
В курсе
| Урок | Контекст |
|---|---|
| Урок 3 | Подробно разобрана система CLAUDE.md: агент автоматически подтягивает файл при входе в папку, экономит токены, фиксирует найденные решения ошибок. Возникла из вопроса Полины про документацию для агента |
| Урок 4 | CLAUDE.md в контексте скиллов и правил: .claude/rules/ даёт агенту карту проекта сразу при запуске. Модульные правила подгружаются по контексту задачи |
Ссылки
Связанное
- Claude Code — инструмент, который читает CLAUDE.md
- Контекст — CLAUDE.md экономит контекстное окно
- Skills — переиспользуемые команды, живут рядом с CLAUDE.md
- Hooks — могут автоматически обновлять CLAUDE.md
- Compact — CLAUDE.md снижает потребность в compact