✔️ CLAUDE.md - это не README для людей. Это инструкция для AI-агента, который будет работать с вашим кодом.

Если файл написан плохо, Claude начинает гадать: какой стек, какие команды запускать, где лежат компоненты, какой стиль кода использовать и что вообще можно менять.

Нормальный CLAUDE.md держится на трёх уровнях.

Глобальный - ваши правила для всех проектов: стиль, предпочтения, запреты.

Проектный - правила конкретного репозитория: стек, команды сборки, тесты, архитектура, соглашения команды.

Папочный - локальный контекст для отдельных модулей: API, компоненты, utils, backend, frontend.

Главный принцип простой: чем ближе CLAUDE.md к файлу, тем важнее его правила. Если есть конфликт, побеждает последний уровень.

Хороший CLAUDE.md отвечает на три вопроса.

Что это за проект: название, цель, стек, структура, зависимости.

Зачем всё устроено именно так: архитектурные решения, стиль кода, naming, анти-паттерны.

Как с этим работать: команды build, test, lint, формат коммитов, деплой, CI/CD.

И самое важное - не пиши абстракции типа «пиши чистый код». Это бесполезно.

Пиши конкретно: «используй camelCase для переменных, PascalCase для компонентов, перед коммитом запускай npm test, не трогай server components без причины».

CLAUDE.md должен быть коротким, живым и практичным. Не больше 500 строк, обновлять раз в месяц, ссылки на package.json и tsconfig вместо копипаста.

Потому что AI-агенту не нужен красивый документ. Ему нужен рабочий контекст, который не даёт ломать проект.

https://www.youtube.com/shorts/63QIyLioafI?feature=share