Сегодня, когда код пишут не только люди, но и агенты — Claude Code, Cursor, OpenCode или локальные модели — файл CLAUDE.md превращается в нечто большее, чем просто справочник. Это фактически ядро всей инженерии контекста: мини-документ, который каждый раз загружается в «память» модели и определяет, как она будет мыслить, искать файлы, проверять изменения и даже понимать цель проекта.
Статья HumanLayer поднимает важный вопрос: как написать CLAUDE.md так, чтобы он не мешал ИИ, а помогал ему работать лучше. И вот что здесь действительно важно — мы впервые видим, что текст, который многие воспринимали как техническое приложение, на самом деле является самым влиятельным файлом репозитория в эпоху разработки, ориентированной на ИИ.
В этой статье я разберу, почему CLAUDE.md должен быть компактным, как работает принцип Постепенное раскрытие информации (Progressive Disclosure), и почему попытка заселить документ командами превращает Claude в потерянного стажёра, а не опытного агента.
LLM как функция без долгой памяти
Если упрощённо: Claude перед каждой новой сессией — будто стажёр, впервые пришедший в проект. Он ничего не знает, не помнит и не понимает без вашего контекста.
И тут вступает в игру CLAUDE.md — единственный файл, который загружается в каждую сессию агента по умолчанию.
👀 Отсюда вытекает несколько следствий:
- 🎯 LLM не знает о структуре и целях проекта, пока вы ему это не скажете.
- 📦 Весь фундамент контекста должен быть в одном месте — коротком, точном, без воды.
- 🧭 Любая лишняя строка в CLAUDE.md — как неверный дорожный указатель.
В статье отмечается интересная деталь: Claude сам решает, когда игнорировать ваш CLAUDE.md. Это не баг, а в качестве защиты от перегрузки управляющая обвязка (harness) добавляет скрытое системное напоминание:
"Не отвечай на этот контекст, если он не очень важен для задачи."
Причина очевидна: слишком многие пытались «воспитать» Claude, записывая в файл всё подряд — от пожеланий до хотфиксов поведения. В итоге модель учится… не читать CLAUDE.md.
Три кита хорошего CLAUDE.md
Сильный CLAUDE.md должен отвечать на три вопроса:
- 🗺️ ЧТО (WHAT) — стек, структура, назначение папок
- 💡 ПОЧЕМУ (WHY) — цель проекта, смысл архитектуры
- 🧪 КАК (HOW) — как запускать, тестировать, верифицировать изменения
Но ключевой принцип — минимализм. Чем больше вы загружаете инструкций, тем хуже работает агент. Фронтирные модели (Frontier) могут удерживать 150–200 инструкций, но Claude Code уже занимает около 50 инструкций на уровне системного промпта. Значит, ваш манёвр крайне ограничен.
По сути, CLAUDE.md — это ваш инструмент настройки режима мышления, а не список команд.
Почему длинные CLAUDE.md бесполезны
Работа инструкций у LLM устроена нетривиально:
- Модель сильнее всего учитывает первое и последнее в сообщении.
- Инструкциям из середины длинного документа уделяется гораздо меньше внимания.
- А при превышении порога — модель начинает игнорировать все правила равномерно, а не выборочно.
Получается такой эффект:
🧊 Чем длиннее документ — тем меньше модель соблюдает даже самые важные инструкции.
Именно поэтому рекомендация HumanLayer — до 300 строк, идеал — до 60.
Постепенное раскрытие информации — секретный соус хорошей документации
Вместо монолитного CLAUDE.md выстраивается чёткая архитектура:
agent_docs/
building_the_project.md
running_tests.md
service_architecture.md
code_conventions.md
...
Задача CLAUDE.md — не объяснять всё, а указать путь:
🔗 «Если хочешь узнать, как запускать тесты — вот документ. Если хочешь понять архитектуру — иди сюда.»
Это работает почти как ленивые вычисления: модель читает только то, что ей действительно нужно.
⚙️ Эмоджи-подсказки по смыслу:
- 📂 — для структуры проекта
- 🧭 — для навигации
- 🧪 — для процессов тестирования
Этот подход ускоряет работу и снижает когнитивные риски — модель получает контекст ровно в тот момент, когда он нужен.
Claude — плохой линтер, но отличный инженер
Одна из ключевых ошибок — пытаться заставить агента искать пробелы или следовать код-стайлу.
Авторы статьи настойчиво подчеркивают:
🛑 Не используйте LLM как линтер.
Причины:
- ❗ LLM дорогой и медленный в сравнении с ESLint/Biome
- ❗ Правила стиля засоряют CLAUDE.md
- ❗ В реальных проектах форматирование должно быть детерминированным
Гораздо лучше использовать:
- biome / eslint — как автоформаттер
- Claude Stop Hooks — чтобы агент устранял уже найденные ошибки
- Slash-команды — для точечного запроса стайлгайда при необходимости
Это превращает модель в настоящего помощника, а не в дорогостоящий инструмент проверки пробелов.
Моё мнение: CLAUDE.md — это новый README, но куда опаснее
Если README читают люди, то CLAUDE.md читает модель, которая будет генерировать вам код.
И это означает:
🧨 одна плохая строка в CLAUDE.md способна привести к сотне плохих строк в пулреквесте (PR).
Мы никогда ещё не имели документа, каждая буква которого буквально влияет на качество всех последующих ревизий кода. В эпоху агентных IDE этот файл становится элементом инженерной ответственности, почти как конфигурация продакшн-сервиса.
CLAUDE.md — это новая форма программирования, но — текстом инструкций. И как любой код, он требует ревью, итераций и архитектуры.
Вывод
Вот как можно кратко сформулировать идеальный подход:
- 🧩 CLAUDE.md — минималистичен и описывает только WHAT, WHY, HOW.
- ✂️ Меньше правил = больше точности.
- 📚 Детали — в отдельных файлах через Progressive Disclosure.
- ⚙️ Форматирование и стиль — не задача LLM, а детерминированных линтеров.
- 🧱 Каждая строка CLAUDE.md высокорисковая, авто-генерацию использовать нельзя.
В итоге появляется парадокс: чтобы ИИ стал «умнее», нужно писать меньше, но точнее.
Источники
- Оригинальная статья: https://www.humanlayer.dev/blog/writing-a-good-claude-md