Как правильно писать файлы CLAUDE.md для эффективной работы

Прочитал интересный разбор того, почему большинство CLAUDE.md файлов не эфективны. Проблема не в том, что Claude их не читает — проблема в том, что мы их неправильно пишем.

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

Современные модели могут стабильно следовать примерно 150-200 инструкциям. Claude Code в системном промпте уже использует около 50 из них — то есть треть бюджета уходит до того, как модель увидит ваш код. При этом по мере роста числа инструкций качество их выполнения падает не точечно, а равномерно по всем пунктам.

Короче, держите CLAUDE.md коротким и универсальным. Вместо того чтобы описывать все команды сборки, настройки тестов и паттерны кода, используйте метод прогрессивного погружения: создайте папку agent_docs/ с отдельными файлами (building_project.md, testing_guidelines.md, architecture.md) и в CLAUDE.md просто перечислите их с кратким описанием. Пусть Claude сам решает, что ему нужно прочитать для текущей задачи.

Для повседневных задач это тожже работает. Я после прочтения статьи попросил агента разобрать мой CLAUDE.md и раскидать все не нужное по разным документам. И он сразу вынул из него примерно половину. Правда, выкинуть придется еще примерно 500 строк :)

Правда, авторы статьи категорически призывают не использовать /init для автогенерации CLAUDE.md и вообще писать там всё вручную. Но так далеко заходить я, конечно, не буду :)

—

Пономарь

Подписывайтесь на Telegram Сергей Булаев AI 🤖.