CLAUDE.md — это файл с инструкциями, который Claude Code читает перед каждой задачей. Если он разрастается до сотен строк, агент тратит контекстное окно на устаревшие правила, а нужные инструкции теряются среди мусора. В этой статье разберём, как держать CLAUDE.md компактным и актуальным: какие разделы нужны, что туда точно не стоит писать и когда файл стоит разбить на несколько.
Почему CLAUDE.md перестаёт работать?
Файл начинает жизнь на пяти строках: «не удалять миграции», «всегда проверять типы». Через месяц туда добавляют примеры SQL, команды деплоя и скопированные куски из документации фреймворка. Результат — 800+ строк текста, который агент обязан прочитать целиком (Habr, pgkdigital). При таком объёме возникают внутренние противоречия: старая инструкция говорит одно, новая — другое, и Claude начинает следовать случайной из них.
Вторая проблема — устаревание. Инструкция «деплоим через Heroku» висит год после переезда на другой хостинг. Агент её честно исполняет, получает ошибку, тратит раунды на отладку того, что давно неактуально. Человек бы спросил. Claude — нет.
Третья — контекстное окно. Каждый символ CLAUDE.md — это символ, который не достался коду, тестам или описанию задачи. Раздутый файл не делает агента умнее, он просто отъедает место у полезной информации.
Какая структура не раздувается?
Рабочая структура — это четыре коротких блока, каждый с конкретной функцией.
Роль и контекст проекта. Одна-две строки: что это за проект, на каком стеке, какова основная цель. Не история проекта, не имена всех, кто когда-либо работал над ним. «Это интернет-магазин на Next.js + PostgreSQL. Основная задача: не ломать корзину и checkout.»
Запреты и ограничения. Список из пяти-восьми пунктов — то, что агент точно не должен делать никогда. Удалять миграции. Менять схему БД без явной просьбы. Коммитить напрямую в main. Такой список короткий и работает годами без правок.
Соглашения по коду. Три-четыре строки о стиле, который нельзя вывести из кода автоматически. Линтер и форматтер прочитает сам. Сюда — только то, что линтер не увидит: «все API-ответы оборачиваем в Result-тип», «логи пишем только через logger.ts».
Ссылки на внешние документы. Если нужна подробная инструкция по деплою или матрица доступов — не копируй её в CLAUDE.md, а дай путь к файлу. Агент умеет читать другие файлы проекта.
| Раздел | Максимальный объём | Что включать | Что исключить |
|---|---|---|---|
| Роль и контекст | 3–5 строк | Стек, цель, домен | История, имена, сроки |
| Запреты | 5–8 пунктов | Критичные ограничения | Советы и рекомендации |
| Соглашения | 4–6 строк | То, что не выводится из кода | Копии из документации |
| Внешние ссылки | 2–4 строки | Пути к файлам с деталями | Содержимое этих файлов |
Когда одного CLAUDE.md уже недостаточно?
Claude Code умеет читать CLAUDE.md не только из корня проекта, но и из подпапок. Если у вас монорепозиторий или несколько независимых модулей — разнесите инструкции по директориям. В корне держите только общие правила. В папке /backend — правила для API. В /frontend — правила для компонентов.
Это решает конфликт инструкций: фронтендовый агент не читает правила деплоя бэкенда, а бэкендовый — не знает о CSS-конвенциях. Каждый файл остаётся коротким, потому что отвечает за свою зону. Такая структура особенно помогает, когда над проектом работают несколько людей с разными зонами ответственности — каждый поддерживает свой файл, не трогая чужой.
Как поддерживать файл актуальным без бюрократии?
Простое правило: если инструкция в CLAUDE.md вызвала ошибку или привела к неожиданному поведению — её нужно либо удалить, либо уточнить прямо сейчас, а не откладывать. Два-три таких случая в неделю — и файл деградирует незаметно.
Удобный ритм — ревью раз в две недели, пять минут. Перечитать весь файл вслух. Если пункт непонятен без контекста или неактуален — убрать. Если хочется добавить новый пункт длиннее двух строк — написать отдельный файл и сослаться на него.
Хуки Claude Code помогают автоматизировать часть проверок: например, запускать линтер или тесты после каждой правки, не прописывая это в CLAUDE.md отдельной инструкцией. Подробнее о том, как это настроить — в статье о хуках Claude Code для запуска тестов при правках сайта.
Типичные ошибки при работе с CLAUDE.md
- Копировать в файл куски документации фреймворка — агент и так знает документацию, дублировать её незачем.
- Добавлять SQL-миграции и примеры кода прямо в CLAUDE.md — это съедает контекст и устаревает быстрее всего.
- Писать инструкции в формате «постарайся», «желательно» — агент воспринимает их как необязательные и игнорирует при давлении задачи.
- Держать противоречивые пункты: «всегда использовать TypeScript» и ниже «в тестах можно JavaScript» — агент выберет один из вариантов, и не факт что нужный.
- Не удалять инструкции после смены инфраструктуры или стека — устаревшие правила хуже, чем их отсутствие.
- Один глобальный файл на всё — в монорепозитории это гарантированно создаёт конфликты между модулями.
Если хотите разобраться, насколько хорошо ваш текущий CLAUDE.md справляется со своей задачей, полезно сравнить подходы разных harness-инструментов — в статье о сравнении Claude Code и других harness на задаче сайта есть конкретные критерии.
3 шага, которые можно сделать сегодня:
- Откройте CLAUDE.md и удалите всё, что длиннее двух строк и содержит примеры кода или SQL — вынесите это в отдельные файлы со ссылками из CLAUDE.md.
- Перечитайте список запретов и уберите пункты, которые уже неактуальны или не были нарушены ни разу — скорее всего, они избыточны.
- Если проект многомодульный, создайте отдельные CLAUDE.md в подпапках и оставьте в корне только то, что касается всего проекта целиком.


