CLAUDE.md — главный файл правил проекта

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. Итерируй — удаляй то, что не работает, усиливай то, что работает