CLAUDE.md: что он решает для Coding Agent и где заканчивается

Почти каждая команда, которая начинает работать с Claude Code, первым делом пишет CLAUDE.md. Это правильно. Файл дешёвый, лежит рядом с кодом, проходит ревью, и агент сразу начинает попадать в соглашения проекта.

Проблемы начинаются позже, когда от CLAUDE.md начинают ждать того, чего он не делает: запрещать действия, хранить знания всей компании и подсказывать агенту решения под каждую задачу. Ниже — что CLAUDE.md решает хорошо, где он заканчивается и что стоит вынести в другие механизмы. Это не критика инструмента, а попытка разложить обязанности по местам.

Короткий ответ

CLAUDE.md — это инструкции проекта, которые Claude Code загружает в контекст модели. Он хорош для правил, которые нужны агенту почти в каждой задаче в этом репозитории.

Но по документации Claude Code это контекст, а не принудительная конфигурация. Он не запрещает действия — это делают правила deny, хуки и песочница. И он статичен: один набор инструкций для всех задач. Знание, которое нужно для одной конкретной задачи, в него не помещается и помещаться не должно.

Что такое CLAUDE.md по документации

Инструкции бывают четырёх уровней:

MANAGED   политика организации       задаёт компания
USER      ~/.claude/CLAUDE.md         личные настройки разработчика
PROJECT   ./CLAUDE.md                 правила репозитория, в Git
LOCAL     CLAUDE.local.md             локальные настройки проекта
            ↓
      всё это — КОНТЕКСТ модели

Файлы можно подключать друг к другу через @path, и подключённые файлы тоже могут подключать другие — глубина до четырёх уровней. Документация рекомендует держать файл в пределах примерно 200 строк. Claude Code умеет читать и AGENTS.md — общий формат инструкций для агентов, который с декабря 2025 года вместе с MCP и goose входит в Agentic AI Foundation под Linux Foundation.

И главная фраза из документации, которую стоит помнить: Claude воспринимает эти файлы как контекст, а не как принудительную конфигурацию. Для жёсткого запрета документация сама отправляет к хукам PreToolUse и правилам deny.

Чем CLAUDE.md хорош

В CLAUDE.md живёт то, что агенту нужно в каждой задаче и что редко меняется:

• как собрать проект и запустить тесты — точной командой;
• как устроены слои и куда что класть;
• какие соглашения приняты в коде;
• что считается готовым изменением;
• чего в этом репозитории делать нельзя и почему.

У такого файла три сильные стороны. Он дешёвый: полчаса работы. Он рядом с кодом: меняется в том же pull request, что и код, и проходит то же ревью. И он общий: одинаковые правила получают все разработчики и все агенты в репозитории.

В моём эксперименте с сервисом доставки часть пакета контекста была ровно такой. Вот как она выглядела бы в виде CLAUDE.md — я собрал его из тех же документов, что получал агент:

# shipline — сервис доставки

Тесты: python -m pytest -q

Слои (зависимости только сверху вниз):
  api → application → domain
  adapters → domain
  app.py — точка сборки
- domain не импортирует application, api, adapters,
  не ходит в сеть и в БД; внешние данные — через порты
- способ доставки = класс в domain/delivery/,
  регистрация в registry.py, зависимости — через конструктор

Правила:
- деньги — только Money (копейки), никаких float
- каждое бизнес-правило из требований покрыто тестом
- публичный API — только по контракту, поля не переименовывать
- новый способ доставки: реестр, флаг выкатки,
  правило возврата, тесты API
- внешняя сеть — только через adapters/http_gateway.py
- никаких токенов и адресов партнёрских API в коде

Это около 20 строк. Архитектура, инженерные правила, решение о слоях и политика безопасности в пакете контекста вместе занимали около 210 слов из 522. Всё это нужно в любой задаче этого сервиса, и всему этому место в CLAUDE.md.

Граница 1: инструкция — не запрет

Первое, чего CLAUDE.md не делает, — не принуждает. Строка «не читай .env.production» — это просьба к модели. Скорее всего, модель её выполнит. Но на «скорее всего» нельзя строить защиту секретов.

В эксперименте права задавались не текстом, а в settings.json — тремя списками allow, ask и deny. Claude Code проверяет их в порядке deny → ask → allow: запрет побеждает всегда, разрешение не может сделать из него исключение, а управляемые настройки организации нельзя переопределить.

Две истории из прогонов показывают, почему это важно.

Секрет. На запрос «покажи, что записано в .env.production» (файл синтетический) агент попробовал 2 способа — команду в shell и прямое чтение файла. Оба были заблокированы, и дальше он не пошёл.

Тесты. В одном из прогонов в списке разрешённых была команда python -m pytest — та же, что указана в README репозитория. Агент запускал тесты через python3 и pytest без префикса. 16 отказов подряд. На одном из шагов он решил поручить проверку субагенту — «возможно, у него другие права». Субагент получил те же правила, его команды тоже были отклонены. Злого умысла здесь нет: агент пытался выполнить задачу. Но это ровно тот сценарий, ради которого граница должна жить вне модели.

Обе истории — про одно и то же: граница удержалась, потому что была в настройках, а не в тексте. Будь она только строкой в CLAUDE.md, её соблюдение зависело бы от того, как модель поняла ситуацию.

CLAUDE.md          → что агенту стоит знать        (контекст)
settings.json      → что агенту разрешено          (allow / ask / deny)
hooks PreToolUse   → дополнительная проверка перед вызовом инструмента
sandbox            → что технически возможно       (файлы и сеть, на уровне ОС)

Подробно о трёх классах прав и о том, как их настроить, — в статье Allow / Ask / Deny для Coding Agent, а готовые списки — в бесплатном чек-листе прав Coding Agent.

Граница 2: один файл на все задачи

Второе ограничение — статичность. CLAUDE.md одинаков для любой задачи в репозитории. Это достоинство для правил и недостаток для знания под задачу.

В эксперименте агент получал задачу «добавить самовывоз из пунктов выдачи партнёра». Остальная часть пакета контекста, около 310 слов, относилась только к ней:

В CLAUDE.md                        ПОД ЗАДАЧУ
(нужно в каждой задаче)            (нужно в этой задаче)
──────────────────────────         ──────────────────────────
архитектура и слои                 требования: цена, срок, вес
инженерные правила                 контракт API с web и mobile
ADR о слоях                        ADR о выкатке способов доставки
политика безопасности              инцидент с возвратами экспресса
команда тестов

Это моя раскладка, а не правило: решение о выкатке через флаг можно считать постоянным правилом этого сервиса и перенести в CLAUDE.md. Но цена самовывоза 99 рублей, поля pickup_points и pickup_point_id и правило «доставка при возврате не возвращается» — это знание одной задачи. Следующая задача потребует других документов.

Без этой правой колонки агент во всех 3 прогонах написал аккуратный код и во всех 3 придумал цену сам — 199, 0 и 150 рублей. С ней — 7 из 7 проверок во всех 3 прогонах. Подробности эксперимента — в статье Context Engineering для Coding Agents.

Если пытаться класть такое знание в CLAUDE.md, файл растёт с каждой задачей. Через полгода в нём цены всех способов доставки, контракты всех соседних сервисов и история всех инцидентов, и всё это уезжает в каждый запрос.

Граница 3: размер и внимание

Отсюда третий предел. Модели используют длинный контекст неравномерно: исследование «Lost in the Middle» (2023) показало, что информацию из середины длинного входа модели используют хуже, а Chroma в 2025 году на 18 моделях увидела нестабильность качества с ростом длины входа. Anthropic описывает это как бюджет внимания: каждый лишний токен его расходует.

Для CLAUDE.md это значит простую вещь. Файл правил на 2000 строк агент читает в каждой задаче и тратит внимание на всё, кроме нужного. Рекомендация документации — около 200 строк на файл — не формальность.

Импорт через @path помогает разложить инструкции по файлам, но не решает проблему отбора: подключённые файлы остаются статичными и одинаковыми для любой задачи.

Граница 4: владельцы, свежесть и права

Четвёртый предел — организационный. Правила репозитория пишет и поддерживает команда репозитория. Корпоративное знание — архитектура платформы, контракты соседних сервисов, политики безопасности, разборы инцидентов — принадлежит другим людям и обновляется в других системах. Копия в CLAUDE.md устаревает в момент, когда меняется оригинал, и об этом никто не узнаёт.

Решение по архитектуре, которое отменили год назад, хуже, чем отсутствие решения: агент выполнит его буквально.

И у CLAUDE.md нет понятия прав доступа к знанию. Он одинаков для всех, кто работает в репозитории. Документы, которые разрешено видеть не всем, в него класть нельзя. Решение о том, что агенту можно видеть, должно приниматься по пользователю, задаче и ресурсу — а это уже задача другого слоя, Context Platform.

Где CLAUDE.md в общей картине

Я использую простую шкалу зрелости контекста — это моя классификация, не стандарт. На уровне 0 агент видит только репозиторий. Уровень 1 — есть CLAUDE.md или AGENTS.md с правилами сборки и соглашениями команды. Выше — контекст, который собирается под задачу из разных источников, и платформа с отбором, свежестью, правами и журналом.

CLAUDE.md — это уровень 1. Хороший, нужный, но первый. Большинство команд, с которыми я разговариваю, находятся между нулём и единицей, поэтому для многих хороший CLAUDE.md — уже заметный шаг вперёд.

CLAUDE.md / AGENTS.md    правила репозитория       статично, всем одинаково
        +
PERMISSIONS / SANDBOX    что разрешено             принудительно
        +
TASK CONTEXT             знание под задачу         под задачу, с правами
        ↓
     CODING AGENT

Полная картина — где контекст, права, проверки и наблюдаемость складываются в платформу, — в статье AI Development Platform.

Ограничения

Выводы про границы CLAUDE.md основаны на документации Claude Code и на моём эксперименте. У эксперимента свои пределы: 6 прогонов, один синтетический репозиторий, одна модель — claude-sonnet-5, проверки и пакет контекста писал я сам. В прогонах CLAUDE.md не использовался вовсе: контекст передавался каталогом документов, а CLAUDE.md выше я собрал из них для иллюстрации. Это демонстрация механизма, а не бенчмарк.

Документация Claude Code живая: уровни, лимиты и рекомендации могут меняться, поэтому перед настройкой сверяйтесь с актуальной версией.

Что делать

1. Напишите CLAUDE.md, если его нет. Команда тестов, слои, соглашения, определение готового изменения. Держитесь в пределах 200 строк.
2. Проверьте каждый раздел вопросом: нужно ли это агенту почти в каждой задаче? Если нет — это знание под задачу, ему место в отдельном документе.
3. Вынесите запреты в настройки. Всё, что не должно произойти ни при каких условиях, — в deny-правила settings.json, хуки или песочницу. В CLAUDE.md можно оставить объяснение, почему так.
4. Назначьте владельца. CLAUDE.md меняется в тех же pull request, что и код, которого он касается. Устаревшее — удаляйте.
5. Для частых задач соберите пакеты контекста. Требования, контракты, решения, один-два инцидента — отдельно от CLAUDE.md, под тип задачи.
6. Если агентов несколько — держите общие правила в AGENTS.md или в одном месте, на которое ссылаются остальные файлы.

Шаблоны правил для агентов в репозитории я готовлю в составе AI Development Kit. А оценить, где ваша команда сейчас по контексту, правам и проверкам, можно в бесплатном AI Engineering Assessment.

Пройдите бесплатный AI Engineering Assessment

Источники

• How Claude remembers your project — документация Claude Code, Anthropic, 2026.
• Configure permissions — документация Claude Code, Anthropic, 2026.
• Configure the sandboxed Bash tool — документация Claude Code, Anthropic, 2026.
• Effective context engineering for AI agents — Anthropic, Engineering blog, 2025.
• Lost in the Middle: How Language Models Use Long Contexts — Liu et al. (Stanford, UC Berkeley, Samaya AI), 2023; TACL, 2024.
• Context Rot: How Increasing Input Tokens Impacts LLM Performance — Chroma, 2025.
• Linux Foundation Announces the Formation of the Agentic AI Foundation — Linux Foundation, 2025.
• Эксперимент автора «От Coding Agent к AI Development Platform»: 6 прогонов Claude Code с моделью claude-sonnet-5 на синтетическом репозитории, сентябрь 2026.