CLAUDE.md — главный файл правил проекта (гайд и обучение Claude Code)
Claude Code читает CLAUDE.md при старте каждой сессии и подхватывает правила проекта. Без него ты каждый раз объясняешь одно и то же: где фронт, где бэк, какие либы запрещены, как называть коммиты. С ним — модель сразу вписывается в проект.
Канал с гайдами и контентом по claude code, выкладываем новости (когда режут лимиты в 10 раз) и какие инструменты через claude реализуем для проектов, канал: https://t.me/claudedevolper
Где лежит и как работает
Claude Code подгружает CLAUDE.md из трёх точек в порядке приоритета:
- ~/.claude/CLAUDE.md — глобальные правила для всех проектов
- <проект>/CLAUDE.md — правила для текущего репо, коммитятся в git
- <проект>/<модуль>/CLAUDE.md — вложенные правила для отдельных модулей
Все три мёржатся, приоритет у вложенных. Это даёт гибкость: в корне — общие правила команды, в src/payments/ — специфика PCI-модуля.
Что писать внутрь
Не надо вставлять сюда документацию проекта — для этого README. CLAUDE.md — это директивы для модели: что делать, чего избегать, какого стиля придерживаться.
Минимальный шаблон:
CLAUDE.md ## Стек - Next.js 15, App Router, Server Actions - PostgreSQL + Prisma - Tailwind + shadcn/ui - Тесты: Vitest + Playwright ## Правила - TypeScript strict — any запрещён - Никаких any, никаких @ts-ignore без комментария - Все API-роуты — в app/api, типы запроса в zod - Тесты обязательны для любого файла в lib/ ## Запреты - Не использовать moment.js (только date-fns) - Не лить ключи в env.ts, только process.env - Не коммитить без прогона npm run check ## Стиль коммитов Conventional commits: feat(auth): add OAuth flow
Что реально работает
Опыт показывает: модель намного лучше следует конкретным коротким правилам, чем длинным туманным описаниям. Вместо «пиши чистый код» пиши:
- Функции длиннее 50 строк — декомпозировать - Не больше 3 уровней вложенности - Переменные — camelCase, константы — SCREAMING_SNAKE
Модели нужны якоря, а не философия.
Подгрузка runtime-правил
Можно использовать @file — подтягивать другие файлы прямо в контекст:
Архитектура @docs/architecture.md ## Схема БД @prisma/schema.prisma
При старте сессии Claude прочитает эти файлы и зафиксирует как контекст. Удобно для больших проектов, где архитектура уходит в отдельный документ.
Подводные камни
- Длинный CLAUDE.md ест контекст. Если у тебя там 500 строк правил — это минус 10K токенов на каждую сессию. Держи до 150 строк.
- Правила игнорируются на длинных сессиях. Когда контекст под завязку, модель начинает забывать верхние инструкции. Лечится /clear и периодическим реминдом правил.
- Hook надёжнее правила. Если критично (линтер, тесты) — ставь hook в .claude/settings.json, а не полагайся на CLAUDE.md.
Как попробовать
1. Создай CLAUDE.md в корне репо 2. Начни с трёх секций: Стек, Правила, Запреты 3. Добавь 5-10 конкретных правил под твой проект 4. Протестируй: дай Claude фичу, посмотри, следует ли он правилам 5. Итерируй — удаляй то, что не работает, усиливай то, что работает
Канал с гайдами и контентом по claude code, выкладываем новости (когда режут лимиты в 10 раз) и какие инструменты через claude реализуем для проектов, канал: https://t.me/claudedevolper