Как CLAUDE.md не раздуть: структура живого документа

Как CLAUDE.md не раздуть: структура живого документа

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 шага, которые можно сделать сегодня:

  1. Откройте CLAUDE.md и удалите всё, что длиннее двух строк и содержит примеры кода или SQL — вынесите это в отдельные файлы со ссылками из CLAUDE.md.
  2. Перечитайте список запретов и уберите пункты, которые уже неактуальны или не были нарушены ни разу — скорее всего, они избыточны.
  3. Если проект многомодульный, создайте отдельные CLAUDE.md в подпапках и оставьте в корне только то, что касается всего проекта целиком.