CLAUDE.md для вашего проекта: как настроить второй мозг за 30 минут
Каждый раз начинать сессию с нуля и объяснять агенту, кто вы, что делаете и как работает ваш проект — это потеря времени и токенов.
Файл CLAUDE.md решает эту проблему: он автоматически загружается в контекст при каждом старте. Агент читает его и сразу знает всё нужное.
Что такое CLAUDE.md
CLAUDE.md — это файл в корне вашего проекта, который Claude Code читает в начале каждой сессии. Это не README и не документация. Это инструкция для агента: кто вы, что делаете, как работает кодовая база и каким правилам следовать.
Одна хорошо написанная CLAUDE.md экономит 10–15 минут на каждой сессии и убирает целый класс ошибок — когда агент делает что-то не так, потому что не знал контекста.
Структура хорошего CLAUDE.md
Мы в QuboLab попробовали несколько форматов. Вот что работает лучше всего:
1. Технологический стек — таблицей
Первое, что нужно агенту — понять, с чем он работает:
## Стек
| Проект | Frontend | Backend | БД | Деплой |
|---|---|---|---|---|
| Сайт | Next.js + Tailwind | API Routes | PostgreSQL + Prisma | VPS + nginx |
| Astara | React Mini App | FastAPI | PostgreSQL + Redis | Docker + systemd |
Агент видит это и сразу знает: не предлагать MongoDB если везде Postgres, не тащить Redux если проект на простом React, не советовать Vercel если деплой на VPS.
2. Карта проекта — куда смотреть
Агенту нужно знать, где искать нужную информацию:
## Карта проекта
| Нужен контекст о... | Куда смотреть |
|---|---|
| Бизнесе и аудитории | business/INDEX.md |
| Стиле и голосе бренда | ai-clone/voice/tone.md |
| Текущих задачах | plans/2026-06-07-*.md |
Это особенно важно для монорепозиториев или проектов со сложной структурой.
3. Правила работы — явно и коротко
Не описание процессов, а конкретные правила:
## Правила
1. Не выдумывай факты — если не знаешь, спроси
2. Не хардкоди цифры, которые могут устареть
3. Используй рус. язык для комментариев и сообщений об ошибках
4. Перед сложной задачей — сохрани план в plans/
Каждое правило должно быть из реальной боли. Если правило никогда не нарушалось — оно не нужно.
4. Что запрещено
Самый недооценённый раздел. Агент должен знать, чего не делать:
## Запрещено
- Дублировать информацию, видную из кода
- Создавать файлы без согласования структуры
- Использовать npm пакеты без проверки их актуальности
- Игнорировать правила из ai-clone/feedback/
Как мы используем CLAUDE.md в QuboLab
У нас два уровня контекста:
Проектный CLAUDE.md — общий для всего монорепо. Стек, структура, технические правила. Агент читает его при работе с любой частью проекта.
Продуктовый CLAUDE.md — в каждом подпроекте. Например, something_projects/CLAUDE.md описывает специфику продуктового кода: как деплоить, как работает очередь задач, особенности FastAPI-бекенда.
Распространённые ошибки
Слишком длинный файл. Агент загружает всё в контекст. 200–300 строк — разумный предел. Больше — начинает теряться важное.
Только технический контекст. Агент работает не только с кодом. Если он помогает писать тексты — добавьте информацию о голосе бренда. Если работает с данными — добавьте бизнес-контекст.
Устаревшая информация. CLAUDE.md — живой документ. Смените стек, поменяли правила — обновите файл. Иначе агент будет давать советы на основе того, чего больше нет.
Дублирование кода. Если что-то видно из кода, не пишите это в CLAUDE.md. Не нужно объяснять, что используется TypeScript — агент это видит. Пишите то, что из кода не видно: почему, а не что.
Шаблон для быстрого старта
# CLAUDE.md
## Стек
[Таблица с технологиями]
## Структура проекта
[Краткая карта директорий]
## Карта контекста
[Таблица: что нужно узнать → где смотреть]
## Правила работы
1. [Правило из реальной боли]
2. [Правило из реальной боли]
## Запрещено
- [Конкретный запрет]
- [Конкретный запрет]
Итог
CLAUDE.md — это инвестиция 30 минут, которая окупается с первой же сессии. Агент перестаёт делать ошибки «из-за незнания» и начинает работать как человек, который уже знает проект.
Начните с малого: опишите стек и 3–5 ключевых правил. Добавляйте разделы по мере того, как обнаруживаете, что агенту не хватает контекста.