CLAUDE.md: один файл, который меняет качество работы агента

Самая частая жалоба на ИИ-агента звучит так: «он пишет код не как у нас в проекте». Обычно это не проблема модели, а проблема вводных. Агент не знает, что тесты у вас запускаются одной командой, а не тремя, что в проекте только ESM-импорты и что папку с миграциями трогать нельзя. Всё это можно сказать один раз — в файле CLAUDE.md.

Что это такое

CLAUDE.md — обычный текстовый файл в формате Markdown, который Claude Code читает в начале каждой сессии. Это не магия и не конфиг с хитрым синтаксисом: вы пишете человеческим языком то, что рассказали бы новому разработчику в первый день. Разница только в том, что новому разработчику вы рассказываете один раз, а агенту приходилось бы повторять в каждой задаче.

Файлов может быть несколько. Главный лежит в корне проекта и обычно коммитится в репозиторий — тогда правила действуют у всей команды. Личный файл в домашней папке хранит ваши привычки и работает во всех проектах. В монорепозиториях удобно класть отдельные файлы в подпапки.

Что писать: четыре блока

Команды. Самое ценное. Как собрать, как запустить локально, как прогнать тесты, как проверить стиль. Без этого агент будет угадывать по содержимому package.json и иногда угадывать неверно.

Устройство проекта. Две-три фразы о стеке и о том, что где лежит. Не пересказ архитектуры на десять экранов, а карта: роуты здесь, бизнес-логика там, шаблоны вот тут.

Соглашения. Всё, за что вы обычно возвращаете правки на ревью: стиль импортов, обработка ошибок, работа с базой, язык комментариев и коммитов.

Запреты. Самый недооценённый блок. Прямо перечислите, чего делать нельзя: какие файлы не трогать, какие команды не запускать, что нельзя менять без вашего явного слова.

Пример короткого CLAUDE.md

Так может выглядеть рабочий файл для веб-проекта — он занимает меньше страницы и уже закрывает 80% недоразумений:

• Стек: Node.js, Express, PostgreSQL, шаблоны EJS. Прод разворачивается через PM2.
• Команды: npm run dev — локальный запуск, npm test — тесты, npm run lint — стиль, npm run build — сборка перед выкладкой.
• Структура: маршруты в src/routes, бизнес-логика в src/services, в контроллерах логики нет — только вызовы сервисов.
• Соглашения: только ESM-импорты; SQL — параметризованные запросы, склейка строк запрещена; каждый новый POST-эндпоинт проходит валидацию схемой; сообщения коммитов на русском.
• Запреты: не править старые файлы миграций, не менять .env, не выполнять команды на боевом сервере, не коммитить без прогона тестов.
• Больные места: модуль оплаты покрыт тестами частично — правки в нём только после плана и подтверждения.

Как его вести

Начать проще всего с готового черновика: у Claude Code есть команда инициализации, которая осматривает проект и сама собирает первую версию файла. Дальше правило одно: каждый раз, когда вы поправили агента словами, спросите себя — не должно ли это лежать в CLAUDE.md. Сказали «у нас тесты запускаются иначе» — строчка в файл. Сказали «не трогай этот каталог» — ещё строчка. Через неделю такой практики поправок становится заметно меньше.

Держите файл коротким. Он попадает в контекст каждой сессии, поэтому раздутый документ на несколько сотен строк не только тратит лимит, но и размывает важное среди второстепенного. Если материала много, выносите детали в отдельные документы и оставляйте ссылку на них.

Три ошибки, из-за которых файл не работает

• Пересказ README. Агент и так прочитает README. В CLAUDE.md нужно то, чего в репозитории нет: неписаные договорённости и грабли.
• Устаревшие команды. Файл, где написано npm test, а тесты давно переехали, хуже, чем пустой: агент будет уверенно делать не то.
• Общие слова. «Пиши качественный код» не значит ничего. «Не бросать необработанные исключения в маршрутах, ошибки логировать через logger.error» — значит.

Проверить, что всё работает, легко: начните новую сессию и попросите агента прогнать тесты, ничего не объясняя. Если он взял верную команду с первого раза — файл живой. Если пошёл искать по проекту — там чего-то не хватает. Если вы ещё не начинали работать с агентом, начните с первого дня в Claude Code, а CLAUDE.md заведите сразу после первой задачи.

Где купить Claude

Оплатить подписку из России напрямую не получится — карты РФ не проходят. Мы держим готовые варианты в каталоге: Claude Pro (2 090 ₽/мес), Max 5x (11 010 ₽/мес), Max 20x (22 010 ₽/мес) и пополнение API-баланса от $20. Оплата российской картой или через СБП, оформление на вашу почту, поддержка на русском языке.