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 ключевых правил. Добавляйте разделы по мере того, как обнаруживаете, что агенту не хватает контекста.