CLAUDE.md — точка максимального рычага
Создатели Claude Code говорят:
CLAUDE.md — это самое важное, на что стоит инвестировать время при работе с Claude Code. Не промпты. Не настройки. Именно CLAUDE.md.
1 Что такое CLAUDE.md и как это работает
Механизм работы
Файл CLAUDE.md в корне проекта
Claude Code автоматически читает в начале каждой новой сессии. Это не просто комментарий —
это постоянная память агента о твоём проекте.
Загружается автоматически
При каждом старте сессии
Версионируется в git
История изменений сохраняется
Иерархический
Корень + папки = слои
Парадокс: чем лучше модель, тем меньше нужен CLAUDE.md
Это звучит контринтуитивно. Но модели быстро умнеют, и лучшие практики встраиваются прямо в них.
2 года назад нужно было писать:
- ✗ Всегда оборачивай API-вызовы в try-catch
- ✗ Используй async/await вместо callbacks
- ✗ Проверяй типы на входе функций
Сейчас Opus 4.5 делает сам:
- ✓ try-catch по умолчанию
- ✓ async/await — стандарт
- ✓ Типизация — автоматически
Правило обновления:
Каждый месяц пересматривай CLAUDE.md и убирай всё, что модель теперь делает сама. Оставляй только специфичное для твоего проекта.
2 Лимит инструкций и как его обойти
Исследование: сколько инструкций воспринимает модель
Научная работа «How Many Instructions Can LLMs Follow at Once?» показывает: Opus 4.1 (и похожие модели) теряют точность после примерно 150 инструкций.
Точность: ~98% — идеальная зона
Точность: снижается постепенно
Точность: резко падает — инструкции теряются
Стратегия: Вложенные CLAUDE.md
Вместо одного огромного файла — иерархия небольших. Claude автоматически читает оба уровня при работе с файлом из папки.
# Структура вложенных CLAUDE.md:
project/
├── CLAUDE.md ← 20 строк: проект, стек, главные правила
│
├── backend/
│ └── CLAUDE.md ← 15 строк: API паттерны, БД, безопасность
│
├── frontend/
│ └── CLAUDE.md ← 15 строк: компоненты, стейт, тесты
│
└── database/
└── CLAUDE.md ← 10 строк: схема, миграции, индексы
Корневой CLAUDE.md: 20 инструкций. Каждый локальный: ещё 10–15. Итого каждый агент получает 30–35 релевантных инструкций — хорошо в пределах лимита.
3 Анатомия идеального CLAUDE.md
Структура Ray Amjad
LLM-модели уделяют больше внимания началу и концу документа. Середина проходит менее заметно. Порядок критически важен.
Project Description (2–3 предложения)
Что за проект, какой стек, главная цель. Это читается первым.
FastAPI + PostgreSQL + pgvector. База знаний из YouTube-транскрипций с FTS и семантическим поиском. Русскоязычный контент.
Key Commands (3–5 команд)
Главные команды для запуска, тестов, деплоя. Агент будет их использовать.
poetry run harvester stats
poetry run harvester search "запрос" --hybrid
docker compose up -d
Critical Rules (5–10 правил)
Только специфичные для проекта. С мотивацией («почему»).
- Do NOT use Docker for PostgreSQL (uses systemd on VPS)
Why: Production uses native systemd service, not containers.
- Deploy via SCP, NOT git push
Why: /opt/ekstrakt is not a git repo on VPS.
Common Mistakes (3–5 ошибок)
Где агент раньше ошибался. Предотвращает повторение.
- --impersonate chrome breaks yt-dlp on VPS (missing TLS libs)
- /library/N routes are static templates, no DB query needed
References (ссылки на .claude/rules/)
Подробности в отдельных файлах — не загромождай главный CLAUDE.md.
DB schema: .claude/rules/db-models.md
Rate limits: .claude/rules/rate-limiting.md
Deploy: .claude/rules/deployment.md
4 Правила: как писать, чтобы они работали
Формула хорошего правила
[Rule statement]
**Why**: [Контекст и причина]
**Consequence**: [Что произойдёт если нарушить]
Когда модель понимает зачем правило существует, она может:
- → Обобщить принцип на похожие ситуации
- → Принять правильное решение при конфликте правил
- → Не следовать буквально, когда правило явно не применимо
❌ Голое правило:
✅ С контекстом:
**Why**: 46K+ segments. Without limit,
queries OOM the server.
**Default**: LIMIT 100.
❌ Абстрактное правило:
✅ Конкретное + причина:
**Why**: Production VPS uses systemd
service (not containers). Docker local
only. SCP deploy, not git push.
Что НЕ писать в CLAUDE.md
Выбрасывай всё это:
- × Общие best practices (Claude и так знает)
- × Правила без мотивации
- × Устаревшие инструкции (удаляй после апдейта модели)
- × Детали схемы БД (вынеси в .claude/rules/)
- × Весь API reference
Оставляй только это:
- ✓ Специфика твоего окружения (VPS, деплой)
- ✓ Проверенные ошибки агента в твоём проекте
- ✓ Нестандартные решения («почему не X, а Y»)
- ✓ Key commands (быстрый доступ)
- ✓ Ссылки на специализированные rules файлы
5 CLAUDE.md: Живой документ
Когда обновлять
| Событие | Действие |
|---|---|
| Агент ошибся одинаково 3 раза | Добавь правило с объяснением |
| Вышло обновление Claude Code | Проверь, что часть правил уже не нужна |
| Сменился деплой / стек | Обнови commands и deployment rules |
| Добавлен новый сервис / API | Создай .claude/rules/[service].md |
| Раз в месяц | Пересмотри всё, удали устаревшее |
Workflow обновления (Ray's подход)
Заметил новый паттерн ошибки
Записал в MEMORY.md или временный файл
Подтвердил 2–3 раза
Один случай — не правило. Три случая — закономерность.
Добавил правило в CLAUDE.md
С формулой: [Statement] + Why + Consequence
Сделал git commit
Теперь можно откатиться, если правило окажется вредным.
Быстрый старт за 10 минут
# 1. Создай минимальный CLAUDE.md в корне проекта:
# Project: [Название]
[Один абзац: что за проект, стек, главная цель]
## Key Commands
npm start / npm test / npm run build
# 2. Запусти сессию и дай первую задачу
# 3. Когда агент ошибётся — добавь правило
# 4. Коммить CLAUDE.md в git после каждого добавления
Не нужен идеальный CLAUDE.md с самого начала. Ray начинал с пустого файла и добавлял правила постепенно, когда возникали реальные проблемы. Так же должен начинать ты.