Зачем вообще нужен CLAUDE.md
Когда ты открываешь Claude Code в новом проекте, AI не знает: что это, какой стек, какие конвенции, кого нельзя трогать, какие клиенты, что в production. У него только имя папки и список файлов.
Без CLAUDE.md каждый разговор начинается с одного и того же:
— Что за проект? — Next.js, App Router. — А база какая? — Postgres через Prisma. — А деплой? — rsync на VPS. — А вот этот файл что делает? — Это конфиг nginx, не трогай.
Через минуту ты сам устаёшь. AI всё равно забудет к следующей сессии.
CLAUDE.md — это файл в корне проекта, который Claude Code читает автоматически при входе. Десять раз написал — десять раз сэкономил.
Что туда обязательно класть
1. Одна строка — что это вообще
В самом верху, без воды:
# ErgonLab — студия AI-решений
> Сайт + Telegram-боты + AI-автоматизация для бизнеса.
> Домен: ergonlab.ru, бот: @ergonlab_bot
Это первое, что AI видит. Если эту строку не написать — он будет догадываться по названиям файлов.
2. Стек коротко
Не перечислять все зависимости. Только основное:
## Стек
- Сайт: Next.js 14+ App Router, TypeScript strict, Tailwind 4, shadcn/ui
- Боты: Python 3.13+, aiogram 3.22+, aiosqlite
- БД: SQLite (боты), Postgres + Prisma (платформа)
- AI: Claude Sonnet 4 через OpenRouter, Whisper.cpp локально
- Деплой: rsync + PM2 на VPS Ubuntu 24.04
Зачем точные версии: AI не позовёт aiogram 2.x API, если знает что у тебя 3.22+.
3. Структура папок
Не дерево от find, а карта смыслов:
## Структура
- ergonlab-site/ — Next.js сайт
- bots/<name>/ — Telegram-боты, у каждого своя папка с .env
- content/blog/, content/kb/ — markdown контент
- clients/<name>/ — карточки клиентов с переписками
- scripts/ — Telethon-скрипты
- archive/ — старые версии (НЕ редактировать)
Когда AI слышит «обнови карточку клиента», он уже знает где искать.
4. Что НЕ трогать
Самое важное и при этом самое забываемое. Именованный список:
## Ключевые файлы — НЕ менять без согласования
- ИДЕЯ.md — исходная стратегия
- CLAUDE.md — этот файл
- production.env — секреты
- archive/ — историческая ценность
Без этого AI охотно «улучшит» твою стратегию переписав её под свою логику.
5. Активные клиенты / задачи
Часто меняется, но это и есть твой текущий контекст:
## Активные клиенты
- Клиент A — обучение Claude Code, S2 завтра
- Клиент B — сайт v3, ожидает ревью капсулы
- Клиент C — на паузе, ждём ответ
Без этого блока AI не понимает, почему ты вдруг работаешь над папкой конкретного клиента в clients/.
6. Правила работы с файлами
Конвенции, которые повторяются:
## Правила
- Один клиент = одна папка clients/<имя_фамилия>/
- Один кейс = один файл cases/<название>.md
- Шаблоны — _ШАБЛОН.md в каждой рабочей папке
- Тон: «дружелюбные эксперты» — без менторства
- Язык: русский в документах, английский в коде
Как писать, чтобы реально работало
Пиши на «ты» к AI, не описательно
Плохо: «В проекте используется конвенция именования файлов через подчёркивание».
Хорошо: «Файлы именуй через подчёркивание: client_card.md, не ClientCard.md».
Императив работает лучше — AI воспринимает как инструкцию, а не как пассивную справку.
Запреты — отдельным блоком
Не «старайся не», а НИКОГДА:
## НИКОГДА
- Не коммитить .env, credentials.json
- Не отправлять сообщения людям без явного "отправь"
- Не выдумывать данные — если не знаешь, спрашивай
Запреты на отдельной полке, не размазанные по тексту, AI лучше держит в голове.
Размер — 100–300 строк, не больше
Если CLAUDE.md разросся до 800 строк — пора выносить детали в отдельные файлы и оставлять в основном ссылки:
- Качество кода: см. ~/.claude/rules/python.md
- Безопасность: см. ~/.claude/rules/security.md
- Деплой: см. deploy/README.md
Это работает, потому что Claude Code умеет переходить по ссылкам и подтягивать нужное по запросу — а не грузить всё сразу.
Не оставляй устаревшее
Если клиент закрыт — убери из «Активные». Если стек поменялся — обнови. Устаревший CLAUDE.md хуже, чем его отсутствие: AI будет уверенно опираться на ложные факты.
Раз в две недели открывай — пробегись глазами, выбрось мёртвое.
Чек-лист готового CLAUDE.md
Возьми свой текущий и проверь:
- В первых 5 строках понятно, что это за проект и кому он нужен?
- Есть точные версии ключевых либ?
- Есть карта папок с смыслами, а не просто tree?
- Есть блок «не трогать»?
- Есть активные клиенты или задачи с короткими статусами?
- Запреты собраны в отдельный блок и помечены НИКОГДА?
- Размер под 300 строк?
Если на 1-2 пунктах ответил «нет» — это и есть причина, почему AI каждый раз тратит 10 минут на «понимание контекста». Поправь — и следующий разговор начнётся с дела, а не с допросов.
Минимальный шаблон, чтобы начать
# <Название проекта> — <одна строка о чём это>
> <Цель в одном предложении>
> Домен/репо: <ссылки>
## Стек
- ...
## Структура
- ...
## Ключевые файлы — НЕ менять
- ...
## Активные клиенты / задачи
- ...
## НИКОГДА
- Не коммитить секреты
- Не отправлять сообщения без явного "отправь"
- Не выдумывать данные
Скопируй, заполни за 15 минут — и следующий разговор с Claude в этом проекте будет в разы эффективнее.