CLAUDE.md и инструкции уровня проекта
Перейти к разделу
Что такое CLAUDE.md и зачем он нужен
CLAUDE.md — это файл инструкций, который автоматически загружается в контекст каждого разговора в Claude Code. Это ваш способ сказать модели: «вот как мы работаем в этом проекте». Без него каждый разговор начинается с нуля. С ним у модели есть контекст ещё до вашего первого промпта.
Иерархия файлов CLAUDE.md
Может быть несколько уровней: глобальный (~/.claude/CLAUDE.md) для личных предпочтений, уровень проекта (в корне репозитория) для командных соглашений, и локальный (.claude/CLAUDE.md) для того, что не хотите коммитить. Модель объединяет их все — более конкретный имеет приоритет.
Глобальный CLAUDE.md идеален для такого: «общайся на русском», «используй функциональный стиль». Проектный CLAUDE.md — для «мы используем Next.js 16, Tailwind 4, тесты в Playwright».
Анатомия эффективного CLAUDE.md
# My Project
## Quick Start
npm run dev # Dev server
npm run test # Vitest
npm run lint # ESLint + Prettier
## Stack
- Next.js 16 (App Router), React 19, TypeScript 5.7
- Tailwind CSS 4, class-based dark mode
- Drizzle ORM + PostgreSQL
- Vitest + Playwright
## Conventions
- Functional components, no class components
- Server Components by default, 'use client' only when needed
- Collocate tests: `foo.ts` -> `foo.test.ts`
- Prefer named exports over default exports
- Error boundaries at route level, not component levelЧто не должно быть в CLAUDE.md
Самая распространённая ошибка — слишком длинный CLAUDE.md. Каждый токен в нём занимает место в контекстном окне. Не включайте: полную документацию API (вместо этого ссылайтесь на файлы), историю изменений (для этого есть git), подробные туториалы или то, что модель может вывести из кода.
Ключевое правило: CLAUDE.md должен содержать только информацию, которую модель не может вывести из кода или истории git. «Мы используем React» — она видит это в package.json. «Мы предпочитаем Server Components вместо Client Components из-за бюджетов производительности» — вот это нужно сказать.
Директивы vs. информация
Различайте два типа контента. Директивы — это инструкции: «никогда не используй any в TypeScript», «каждый коммит должен проходить lint». Информация — это факты: «API работает на порту 3001», «переменные окружения в .env.local». Пишите директивы повелительно и чётко — модель воспринимает их как инструкции.
Ссылки и обмен
CLAUDE.md поддерживает ссылки @file для загрузки дополнительных файлов — вместо копирования целой документации напишите '@docs/architecture.md'. Коммитьте CLAUDE.md уровня проекта в git как командный документ. Личные предпочтения помещайте в глобальный CLAUDE.md. Для других инструментов существуют аналоги: .cursorrules (Cursor), .github/copilot-instructions.md (Copilot), .windsurfrules (Windsurf).
Добавьте в CLAUDE.md раздел «Что НЕ делать» — явные запреты сильнее общих инструкций. «Никогда не использовать any» эффективнее, чем «использовать явные типы».
Возьмите ваш текущий проект и создайте CLAUDE.md с такими разделами: 1. Quick Start (3-5 команд для запуска проекта) 2. Stack (технологии + версии) 3. Conventions (5-10 правил, которые модель не может вывести из кода) 4. Architecture (1-2 параграфа о ключевых решениях) Затем откройте новый разговор и введите простой промпт. Сравните вывод с CLAUDE.md и без него.
Подсказка
Хороший тест: промпт «добавь новый API-роут» и сравните вывод. С CLAUDE.md модель должна использовать правильный фреймворк, правильные соглашения именования и правильный паттерн обработки ошибок.
Выберите open-source проект, в который вы вносите вклад (или хотите). Клонируйте репозиторий и создайте CLAUDE.md, который поможет AI-ассистенту понять проект. Включите: цель проекта, как запустить тесты, стиль кода, соглашения по PR, ключевые абстракции. Тест: попросите AI реализовать небольшую функцию, используя ваш CLAUDE.md как контекст.
Подсказка
Задокументируйте процесс и результаты — они послужат ориентиром для аналогичных задач в будущем.
Создайте две версии CLAUDE.md для вашего проекта — минимальную (стек + 3 соглашения) и детальную (стек + 10 соглашений + архитектура + антипаттерны). Выполните одно и то же задание с обеими версиями 5 раз. Сравните: 1) Как часто вывод был сразу пригоден к использованию? 2) Сколько правок вручную понадобилось? 3) Какая версия даёт более стабильный вывод? Выберите оптимальную версию на основе данных.
Подсказка
Детальный CLAUDE.md обычно выигрывает для сложных задач (мультифайловые, архитектурные), минимальный — для простых (утилитарные функции, форматирование).
- CLAUDE.md автоматически загружается в каждый разговор — самый мощный инструмент контекста
- Иерархия: глобальный > проектный > локальный, более конкретный имеет приоритет
- Пишите только то, что модель не может вывести из кода
- Директивы (инструкции) и информация (факты) — два разных типа контента
- Коммитьте проектный CLAUDE.md в git — это командный документ
В следующем уроке мы погружаемся в шаблоны промптов для генерации кода — техника, которая даёт вам явное преимущество. Откройте полный курс и продолжайте прямо сейчас.
2/7 завершено — продолжайте!