Ошибка 2 — отсутствие CLAUDE.md

Что такое CLAUDE.md

CLAUDE.md — это обычный markdown-файл в корне вашего проекта. Когда Claude Code открывает проект, он первым делом читает этот файл и держит его в контексте на протяжении всей сессии. По сути это инструкция для агента: вот мой проект, вот мои конвенции, вот что нельзя делать. Заполняется она один раз, а экономит время в каждой последующей сессии, потому что контекст больше не нужно пересказывать вручную.

Базовый шаблон CLAUDE.md

# <Название проекта> — Project Context

## Что это
Короткое описание: что за продукт, для кого, что делает.

## Стек
- Next.js 16 (App Router)
- TypeScript
- Tailwind CSS v4
- shadcn/ui
- Auth.js + Postgres
- OpenRouter (ИИ)
- Vercel (хостинг)

## Структура
- src/app — страницы (App Router)
- src/components — UI компоненты
- src/lib — утилиты, клиенты, типы
- src/lib/auth — Auth.js v5 конфиг (auth.ts, callbacks)
- src/lib/db — Prisma client (db.ts)
- src/lib/ai — обёртка над OpenRouter

## Стиль
Тёмная тема. Бирюзовый акцент (#14b8a6). Тексты на русском.
Адаптив: mobile 1 колонка, планшет 2, десктоп 3.

## Конвенции
- Компоненты — PascalCase (Button.tsx, не button.tsx)
- Только Tailwind, не CSS-модули
- UI из shadcn/ui, не из других библиотек
- API routes — src/app/api/<name>/route.ts
- Prisma client используем только на сервере (никогда не импортируем в клиентские компоненты)

## Запрещено
- localStorage для пользовательских данных (только Postgres через Prisma)
- Хранение токенов в коде (только env)
- Использовать setTimeout для polling — только WebSocket-подключение

## Команды
- npm run dev — локальный сервер
- npm run build — продакшен сборка
- npm run lint — линт

## Проверки перед коммитом
npm run build && npm run lint

## Что не подтверждено / решается
- Использовать ли streaming для ИИ-генерации
- Какую модель по умолчанию: Claude Haiku или Sonnet

Какие секции добавлять под нишу

Базовый шаблон — это только старт. Дальше под свой проект добавляют собственные секции. Раздел про Git описывает, какие ветки вы используете и как именуете коммиты. Раздел про тестирование — какие тесты пишутся (модульные, интеграционные, сквозные) и как их запускать. Раздел про базу данных хранит схему, порядок миграций и правила доступа к боевой версии. Отдельно стоит описать окружения — как устроены dev, staging и prod и как между ними переключаться, — аналитику, то есть что отслеживается и где это смотреть, а в командных проектах ещё и контактные лица, к кому обращаться по конкретным вопросам.

Что не писать в CLAUDE.md

У файла есть и обратная сторона — в него легко натащить лишнего. Секретам тут не место: пароли, токены и ключи живут в .env, а не в markdown. Длинные истории вида «раньше было так, потом мы поменяли» только раздувают файл — в нём должно быть только текущее состояние. Подробные инструкции по отдельным функциям лучше выносить в собственные файлы (docs/auth.md, docs/payments.md) и ссылаться на них, а не пересказывать целиком. И личные предпочтения стоит формулировать через причину: вместо «не люблю className» полезнее написать «используем cn-helper для условных классов, см. lib/utils.ts». Хороший CLAUDE.md остаётся коротким; как только он начинает разрастаться, подробности выносят в отдельные docs/*.md.

Поддержка CLAUDE.md

Этот файл живой и обновляется вместе с проектом. Добавили новую зависимость или технологию — поправьте раздел «Стек». Создали новую папку — обновите «Структуру». Приняли решение «всегда делаем вот так» — закрепите его в «Конвенциях». А когда что-то ломается из-за того, что агент сделал не так, как нужно, — добавьте соответствующий запрет в раздел «Запрещено», чтобы это не повторилось. Claude Code и сам нередко предлагает дописать CLAUDE.md, когда замечает, что какое-то правило неочевидно, — с такими предложениями стоит соглашаться.

Иерархия CLAUDE.md

В одном проекте может быть сразу несколько таких файлов. В корне лежит CLAUDE.md с общим контекстом проекта, в src/app/CLAUDE.md — конвенции для страниц, в src/components/CLAUDE.md — правила для интерфейсных компонентов. Claude Code читает все файлы по пути от корня до текущего, поэтому такая иерархия особенно полезна в больших проектах, где у каждой директории свои особенности.

Пример из реальной жизни

Иногда достаточно одной строки. Разработчик добавил в CLAUDE.md правило:

Не использовать `git add -A` или `git add .` — добавлять только конкретные файлы.

До этого агент время от времени коммитил случайные файлы — логи, временные скрипты. После — перестал. Минимальная правка CLAUDE.md избавляет от долгих разборов потом.

Что в следующем уроке

Промпты структурированы, контекст лежит в CLAUDE.md. Следующая частая ошибка — попытка решить огромную задачу одним запросом: контекст переполняется, и агент теряет нить. На следующем уроке разберём, как правильно разбивать большие задачи.