Когда я впервые начал всерьез работать с AI кодинг-агентами, казалось, что это магия: просишь поправить модуль, а через пару минут у тебя уже пулл-реквест. Но чем больше я ими пользовался, тем чаще ловил себя на одном и том же: агент то ломает билд, то игнорирует важные договоренности по архитектуре, то переписывает код "как ему удобнее". И каждый раз приходилось руками разгребать последствия "умной" автоматизации.
Со временем стало очевидно: проблема не в модели, а в том, как мы ее онбордим в проект. Один и тот же Claude в одном репозитории ведет себя как сильный мидл, а в другом как растерянный стажер. Разница почти всегда в том, что написано (или не написано) в CLAUDE.md и его аналогах для агентов.
Я перепробовал кучу подходов: от огромных "библий" с правилами до минималистичных заметок и автогенерации. Что-то работало, что-то категорически нет. Хотел уже писать эти принципы самостоятельно, но буквально сегодня утром нашел хорошо описанные и проверенные на практике принципы того, каким должен быть CLAUDE.md, чтобы не было мучительно больно ни вам, ни агенту и решил поделиться.
LLM – это (почти) stateless-функции
LLM – это stateless-функции. Веса заморожены к моменту инференса, модель не учится по ходу работы. Всё, что она знает о вашей кодовой базе – это токены, которые вы ей скормили.
Аналогично, кодинг-агенты типа Claude Code требуют явного управления памятью агента. CLAUDE.md (или AGENTS.md) – единственный файл, который по умолчанию попадает в каждую сессию с агентом.
Отсюда три важных следствия:
Кодинг-агенты не знают ничего о вашей кодовой базе в начале каждой сессии
Агенту нужно сообщать всё важное о проекте каждый раз при старте
CLAUDE.md– предпочтительный способ это делать
CLAUDE.md онбордит Claude в ваш проект
Раз Claude ничего не знает о вашем коде в начале сессии, используйте CLAUDE.md для онбординга. На высоком уровне файл должен покрывать:
ЧТО: расскажите про технологии, стек, структуру проекта. Дайте Claude карту кодовой базы. Особенно важно для монорепозиториев! Опишите, какие есть приложения, shared-пакеты и для чего всё это нужно – чтобы агент знал, где что искать.
ЗАЧЕМ: объясните назначение проекта и что делает каждая часть репозитория. Какова функция разных компонентов?
КАК: расскажите, как работать с проектом. Например, используете bun вместо node? Включите всю информацию, необходимую для реальной работы над проектом. Как Claude может проверить свои изменения? Как запустить тесты, проверку типов, сборку?
Но способ подачи важен! Не пытайтесь впихнуть в CLAUDE.md каждую команду, которая может понадобиться – получите так себе результаты.
Claude часто игнорирует CLAUDE.md
Независимо от используемой модели, вы можете заметить, что Claude регулярно игнорирует содержимое CLAUDE.md.
Можете проверить сами, поставив логирующий прокси между CLI claude code и Anthropic API через ANTHROPIC_BASE_URL. Claude Code добавляет следующий системный ремайндер с вашим CLAUDE.md в user message:
<system-reminder>
IMPORTANT: this context may or may not be relevant to your tasks.
You should not respond to this context unless it is highly relevant to your task.
</system-reminder>В результате Claude будет игнорировать содержимое CLAUDE.md, если решит, что оно не релевантно текущей задаче. Чем больше в файле информации, не применимой универсально к вашим задачам, тем выше вероятность, что Claude проигнорирует ваши инструкции.
Зачем Anthropic это добавили? Точно неизвестно, но можно предположить. Большинство CLAUDE.md-файлов, которые мы видели, содержат кучу инструкций, не применимых широко. Многие пользователи используют файл как способ добавлять «хотфиксы» для поведения, которое им не понравилось – накидывая инструкции, не обязательно применимые повсеместно.
Можно только предположить, что команда Claude Code обнаружила: если сказать Claude игнорировать плохие инструкции, AI-агент выдаёт лучшие результаты.
Как создать хороший CLAUDE.md
Дальше – рекомендации по написанию хорошего CLAUDE.md согласно best practices по context engineering.
Ваша кодовая база и принцтпы может отличаться. Не все эти правила оптимальны для каждого сетапа. Как и везде – можете нарушать правила, когда:
понимаете, когда и почему это нормально
у вас есть веская причина
Меньше инструкций – лучше
Соблазнительно попытаться впихнуть каждую возможную команду, а также стандарты кода и style guidelines в CLAUDE.md. Мы не рекомендуем.
Хотя тема не исследована супер-подробно, некоторые исследования показывают:
Ведущие thinking-модели могут следовать ~150-200 инструкциям с разумной консистентностью. Маленькие модели справляются с меньшим количеством, non-thinking модели – тоже хуже.
Маленькие модели деградируют НАМНОГО быстрее и НАМНОГО сильнее. Конкретно: они показывают экспоненциальный спад в следовании инструкциям при росте их числа, тогда как большие ведущие thinking-модели показывают линейный спад. Поэтому не рекомендуем использовать маленькие модели для многошаговых задач или сложных планов имплементации.
LLM смещены к инструкциям на периферии промпта: в самом начале (системный промпт Claude Code и
CLAUDE.md) и в самом конце (последние user messages)При росте числа инструкций качество их выполнения падает равномерно. То есть модель не просто игнорирует новые инструкции (ниже по файлу) – она начинает игнорировать все равномерно
Наш анализ Claude Code показывает, что системный промпт Claude Code содержит ~50 отдельных инструкций. В зависимости от модели – это почти треть инструкций, которые агент может надёжно выполнять, ещё до rules, plugins, skills или user messages.
Это значит: ваш CLAUDE.md должен содержать минимум инструкций – в идеале только универсально применимые к вашим задачам.
Длина и применимость CLAUDE.md
При прочих равных LLM работает лучше, когда контекстное окно заполнено сфокусированным, релевантным контекстом: примерами, связанными файлами, tool calls и результатами – в сравнении с ситуацией, когда в контексте много нерелевантного.
Раз CLAUDE.md попадает в каждую сессию, его содержимое должно быть максимально универсально применимым.
Например, не включайте инструкции о том, как структурировать новую схему БД – это не важно и будет отвлекать модель, когда вы работаете над чем-то несвязанным!
По длине – тот же принцип «меньше = лучше». У Anthropic нет официальной рекомендации по длине, но общий консенсус: < 300 строк – хорошо, короче – ещё лучше.
В HumanLayer корневой CLAUDE.md – меньше 60 строк.
Progressive Disclosure
Написать лаконичный CLAUDE.md, покрывающий всё нужное – сложно, особенно в больших проектах.
Чтобы решить это, используем принцип Progressive Disclosure: Claude видит task- или project-специфичные инструкции только когда они нужны.
Вместо включения всех инструкций по сборке проекта, запуску тестов, code conventions и прочего важного контекста в CLAUDE.md – держите task-специфичные инструкции в отдельных markdown-файлах с самоописывающими именами где-то в проекте.
Например:
agent_docs/
├── building_the_project.md
├── running_tests.md
├── code_conventions.md
├── service_architecture.md
├── database_schema.md
└── service_communication_patterns.mdЗатем в CLAUDE.md включите список этих файлов с кратким описанием каждого и инструктируйте Claude решать, какие (если вообще) релевантны, и прочитать их перед началом работы. Или попросите Claude сначала показать вам файлы, которые он хочет прочитать, для апрува.
Предпочитайте указатели копиям. Не включайте сниппеты кода в эти файлы если возможно – они быстро устаревают. Вместо этого используйте ссылки file:line, чтобы направить Claude к авторитетному контексту.
Концептуально это очень похоже на то, как работают Claude Skills, хотя skills больше про использование инструментов, чем про инструкции.
Claude – не дорогой линтер
Одна из самых частых вещей, которые люди пихают в CLAUDE.md – это code style guidelines. Никогда не посылайте LLM делать работу линтера. LLM сравнительно дорогие и невероятно медленные по сравнению с традиционными линтерами и форматтерами. Используйте классические инструменты когда можете.
Code style guidelines неизбежно добавят кучу инструкций и в основном нерелевантных сниппетов в контекстное окно, ухудшая производительность LLM, следование инструкциям и съедая контекст.
LLM – это in-context learners! Если ваш код следует определённым style guidelines или паттернам, агент с парой поисков по кодовой базе (или хорошим research-документом!) должен следовать существующим паттернам и конвенциям без явных указаний.
Если это принципиально важно – подумайте о настройке Claude Code Stop hook, который запускает форматтер и линтер и показывает ошибки Claude для исправления. Не заставляйте Claude самому искать проблемы форматирования.
Бонус: используйте линтер с автофиксом (нам нравится Biome) и аккуратно настройте правила о том, что можно безопасно автофиксить для максимального (безопасного) покрытия.
Можно также создать Slash Command, включающий ваши code guidelines и направляющий Claude на изменения в version control, или на git status, или подобное. Так вы обрабатываете имплементацию и форматирование отдельно. Оба этапа будут работать лучше.
Не используйте /init и не автогенерируйте CLAUDE.md
И Claude Code, и другие харнессы с OpenCode имеют способы автогенерации CLAUDE.md (или AGENTS.md).
Раз CLAUDE.md попадает в каждую сессию с Claude Code – это один из самых важных файлов в вашей кодовой базе. К лучшему или худшему, в зависимости от использования.
Плохая строка кода – это плохая строка кода. Плохая строка плана имплементации может создать много плохих строк кода. Плохая строка в research, неправильно понимающая систему – может привести к куче плохих строк в плане, и соответственно к ещё большему количеству плохого кода.
Но файл CLAUDE.md влияет на каждую фазу вашего воркфлоу и на каждый артефакт, производимый в нём. Поэтому потратьте время, тщательно обдумав каждую строку, которая туда попадает.
Выводы
CLAUDE.md– для онбординга Claude в вашу кодовую базу. Он должен определять ЗАЧЕМ, ЧТО и КАК вашего проектаМеньше инструкций – лучше. Не упускайте необходимые инструкции, но включайте минимально возможное их количество
Держите содержимое
CLAUDE.mdлаконичным и универсально применимымИспользуйте Progressive Disclosure – не рассказывайте Claude всё, что он мог бы захотеть знать. Лучше расскажите, как найти важную информацию – чтобы он мог найти и использовать её только когда нужно, не раздувая контекст и число инструкций
Claude – не линтер. Используйте линтеры и форматтеры, а также другие фичи вроде Hooks и Slash Commands по необходимости
CLAUDE.md– самая важная точка для AI-агента, поэтому не автогенерируйте его. Тщательно прорабатывайте содержимое для лучших результатов
Надеюсь, статья понравилась. Если интересно что-то похожее, добавляйтесь в ТГ.