CLAUDE.md: Пусть ИИ действительно поймёт ваш проект
Один файл для хранения спецификаций, архитектурных решений и командных соглашений — Claude читает его при каждом запуске
Обновлено 2026-10-08
Что такое CLAUDE.md?
CLAUDE.md — специальный файл в корне проекта, который Claude Code автоматически читает при запуске. Это «проектный брифинг» для AI — технологический стек, кодовые соглашения, структура каталогов и ключевые команды, чтобы Claude понимал контекст без повторных объяснений. На 2026-10-07: если в репозитории есть AGENTS.md, но нет CLAUDE.md, Claude Code начиная с 2.1.277 читает AGENTS.md.
В официальной документации это место, куда записывают то, что иначе приходится объяснять заново: держать нужно только факты, нужные в каждой сессии, разовые детали остаются в самом запросе (проверено 2026-09-21).
Обычный текстовый файл
Это обычный markdown-файл в репозитории: вы его пишете, коммитите, читаете и сравниваете как любой другой. По документам Claude Code читает его при каждом запуске сессии (проверено 2026-09-21).
Загружается при старте
CLAUDE.md рабочего каталога и всех каталогов выше грузится при старте; файлы из подкаталогов подключаются, когда Claude читает там файлы (проверено 2026-09-21).
Контекст, не конфиг
Он попадает в контекстное окно каждую сессию и расходует токены наравне с диалогом, причём строгое исполнение не гарантировано: в документах это контекст, а не обязательная настройка (проверено 2026-09-21).
Зачем нужен CLAUDE.md?
Польза измерима тремя вещами: больше не нужно печатать контекст в начале каждой сессии, ответ у разных людей выглядит одинаково, а новичок входит в проект без устных преданий.
Без повторений
Больше не нужно каждую сессию объяснять «мы используем TypeScript» или «тесты на Jest» — напишите один раз, работает всегда
Единообразный вывод
Определите стиль кода, соглашения об именах и архитектурные ограничения — Claude будет генерировать код по стандартам проекта
Обмен знаниями
Для новых членов команды CLAUDE.md — одновременно конфигурация AI и руководство по проекту
Рекомендуемый шаблон
Хороший CLAUDE.md обычно содержит следующие разделы
# Обзор проекта
- Бэкенд заказов: REST API для веба и мини-приложения
- Новым: сначала этот файл, затем гайд по онбордингу
- Перед правкой API — проверить синхронизацию клиентов
## Технологический стек
- Язык — TypeScript, среда — Node.js, пакеты — pnpm
- Данные — PostgreSQL, частые чтения — Redis
- Тесты — Vitest, покрытие проверяет CI
## Структура каталогов
- src/api: только HTTP и проверка аргументов
- src/domain: бизнес-правила, без фреймворка
- tests: зеркало src, чтобы быстрее искать упавшее
## Соглашения по коду
- Отступ в два пробела, кавычки одинарные, ; не убирать
- Имена без сокращений
- Типы фреймворка в domain не появляются
## Частые команды
- npm run dev: локальный запуск
- npm test: полный прогон юнит-тестов, обязан проходить
- npm run lint: перед коммитом
## Важные замечания
- Секреты и внутренние URL — только в переменных
- Миграции БД сначала на теневой базе
- Неясный пограничный случай уточняем, а не выдумываемПродвинутые приёмы
Эти пять пунктов решают, будут файл соблюдать или он превратится в шум, который никто не перечитывает. Каждый даёт критерий, который можно применить к своему файлу.
Только повторяемое
Критерий простой: пригодится ли строка в следующей сессии? Команды сборки, правила именования и старые грабли — да; перечисление каталогов и зависимостей — нет, Claude выведет это из кода (проверено 2026-09-21).
Не более 200 строк
Ориентир из документации — до 200 строк на файл: дальше выше расход контекста и хуже соблюдение (проверено 2026-09-21). Не помещается — разбейте на правила с областью по пути, они грузятся при совпадении файлов.
Формулировать проверяемо
«Форматируй код красиво» не несёт информации, а «отступ в два пробела, одинарные кавычки, npm test перед коммитом» выполнимо. Группируйте строки подзами и списками: Claude идёт по структуре как читатель (проверено 2026-09-21).
Сначала сгенерировать
Не начинайте с чистого листа: /init разберёт кодовую базу и запишет черновиком команды сборки, тесты и найденные соглашения; дальше по логике /doctor срезает лишнее, оставляя грабли с обоснованием; в конце /context (проверено 2026-09-21).
Без секретов
Файл попадает в Git и читается всеми в каждой сессии. Секреты, внутренние адреса и тестовые аккаунты — в переменные окружения; личные предпочтения — в CLAUDE.local.md под gitignore, чтобы командная копия оставалась чистой (проверено 2026-09-21).
Стандарты командной работы
Лучшие практики CLAUDE.md для многопользовательских проектов
Правки через PR
Командный файл — не личные заметки: правьте в том же PR, что и код, с объяснением причины и с ревью от владельца каталога. По документам проектные инструкции делятся через контроль версий (проверено 2026-09-21).
Порядок загрузки и конфликты
Файлы из каталогов выше попадают в контекст первыми, из подкаталогов — по мере необходимости; содержимое склеивается, а не перекрывается. Если два файла описывают одно поведение по-разному, Claude может выбрать любой случайно: формулировку сводят к одной (проверено 2026-09-21).
Делить по модулям
В большом репозитории не набивайте корневой файл: модульные заметки — в CLAUDE.md подкаталога или в правило с областью по пути, они попадают в контекст только при работе там (проверено 2026-09-21).
Проверка в CI
Два действия делаем обязательными: CI проверяет наличие корневого CLAUDE.md и соблюдение размера, а каждый архитектурный PR пересматривает старые пункты. Документы тоже требуют убирать устаревшие и противоречащие (проверено 2026-09-21).
Типичные ошибки
Все четыре превращают файл из подспорья в помеху, и ни одно не требует переписывания с нуля.
Заметки вместо правил
Вставленные шаги воспроизведения одного бага или выводы одного рефакторинга занимают контекст и в следующей сессии, а общее правило так и не записано. Этому место в issue или описании PR (проверено 2026-09-21).
Он только растёт
Документы ставят планку на 200 строках: дальше файл стоит дороже в контексте и хуже соблюдается (проверено 2026-09-21). Лечение разрастания ещё одним правилом не работает — выносите специфичное для отдельных каталогов.
Правила противоречат
В корне — pnpm, в подкаталоге — npm: Claude выполнит любой из вариантов (проверено 2026-09-21). На тему оставляем одно авторитетное утверждение, остальные места ссылается на него, а не копирует.
Его забросили
Стек и раскладка каталогов поменялись, а команды в файле старые. Документы просят периодически пересматривать все уровни и убирать устаревшее и противоречащее (проверено 2026-09-21) — проще всего приложить к архитектурному PR.
Частые вопросы
CLAUDE.md давать каждый раз?
Нет. CLAUDE.md в рабочем каталоге или любом вышележащем загружается автоматически при старте; файлы подкаталогов подтянутся, когда Claude начнёт там читать. Что загрузилось видно в /context в списке Memory files (проверено 2026-09-21).
Какой размер уместен?
Ориентир из документации — до 200 строк на файл: выше растёт расход контекста и падает соблюдение (проверено 2026-09-21). Модульное содержимое — в правила с областью по пути, чтобы грузилось только при совпадении файлов.
А как же AGENTS.md?
По умолчанию — либо/либо: если в рабочем каталоге или выше есть хоть один CLAUDE.md, AGENTS.md не читается. Чтобы работали оба, задайте в панели /config значение Project instructions на оба вида файлов либо явно импортируйте их из CLAUDE.md через @AGENTS.md (проверено 2026-09-21). Дополнение 2026-10-07: так работает Claude Code с 2.1.277 (выпуск 2026-09-18), в журнале изменений: «Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead»; с 2.1.281 (2026-09-23) это действует и в сессиях через LLM-шлюзы.
Кто его ведёт?
Как с кодом: командная версия в контроле версий, ревью вместе с изменением, обновляет тот, кто трогает архитектуру. Личные предпочтения — в отдельный локальный файл под gitignore; документы требуют и периодической чистки устаревшего (проверено 2026-09-21).
Командная практика с QCode.cc
Один API-ключ QCode.cc + единый CLAUDE.md = согласованный и эффективный AI-кодинг для всей команды
Один ключ на команду
Команде достаточно одного ключа QCode.cc: расход записывается на один аккаунт, отдельный ключ для каждого не нужен (проверено 2026-09-21).
Смена модели без правок
CLAUDE.md читает клиент внутри проекта, и от выбора модели он не зависит: при смене модели переписывать его не нужно.
Общая отправная точка
Старт у всех общий: новичок и опытный инженер задают вопрос с одинаковыми вводными, и результат не зависит от автора запроса.
Три типа проектов
Один шаблон не должен давать один и тот же файл: у этих трёх типов репозиториев разное требует явной записи, остальное сокращайте.
Командный бэкенд
Явно опишите команды сборки и миграций, жёсткие правила совместимости API и запрещённые каталоги: здесь дороже всего то, что каждый повторяет каждому.
Открытая библиотека
Порядок контрибуций, требования к тестам, что считается ломающим изменением: внешние авторы и мейнтейнеры читают один текст, поэтому строку надо уметь проверить.
Личный инструмент
Не копируйте все разделы. Оставьте способ запуска, политику версий зависимостей и жёсткие запреты вроде «не форматировать весь файл».
Напишите качественный CLAUDE.md и кодируйте эффективнее
Память проекта + тариф QCode.cc = лучшие практики командного AI-кодирования