CLAUDE.md разросся и агент перестал слушаться: держим контекст для AI-агентов ссылками, а не простынёй

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

Почему агент перестаёт читать длинный CLAUDE.md

Технически агент его читает - но перестаёт слушаться. Документация Claude Code говорит прямо: "раздутые CLAUDE.md заставляют Claude игнорировать ваши реальные инструкции". Дело не в лени модели, а в том, как работает длинный контекст: чем больше токенов на входе, тем сильнее плывёт качество. Нужное правило теряется в шуме, и агент делает по-своему.

Это подтверждают не только доки. Исследование Chroma "Context Rot" (2025) прогнало 18 фронтир-моделей и показало, что деградируют все без исключения: точность падает на 30-50% ещё до заявленного лимита окна. Модель с окном на 200K токенов может заметно тупить уже на 50K. То есть проблема не в переполнении контекста, а в том, что качество проседает задолго до потолка. Официальная дока Claude Code формулирует это так же: "производительность падает по мере заполнения контекста", и агент начинает "забывать" ранние инструкции.

Вывод неприятный, но честный: длинный CLAUDE.md - это не "больше контроля", это меньше контроля.

Сколько инструкций AI-агент реально держит в голове

Есть конкретная прикидка. Разбор от HumanLayer говорит, что фронтир-модели с рассуждением уверенно следуют примерно 150-200 инструкциям. Из них штук 50 уже съедает системный промпт самого Claude Code. Остаётся 100-150 на ваш CLAUDE.md плюс на сами сообщения в чате. Всё, что сверху, - это лотерея: что-то сработает, что-то потеряется, и вы не угадаете что.

Отсюда и рекомендации по длине. Общий консенсус - держать файл короче 300 строк, а корневой CLAUDE.md у той же HumanLayer вообще меньше 60. Ключевая мысль тут даже не в строках, а в бюджете инструкций: каждая строка что-то стоит, и этот бюджет вы тратите на каждой сессии.

Хорошее правило для чистки от Claude Code: на каждую строку спроси себя "если это убрать, агент начнёт ошибаться?". Нет - режь без сожаления.

Как хранить знание о репозитории ссылками, а не простынёй

Главный приём в разработке с ии простой: указатели вместо копий. HumanLayer называет это "prefer pointers to copies" - вместо того чтобы копировать кусок кода или длинное описание в доку, дай ссылку на файл и строку. Копия устаревает через пару коммитов, а ссылка ведёт на актуальный исходник.

Дальше - прогрессивное раскрытие. Не всё знание о проекте нужно агенту одновременно. То, что требуется иногда, выносим наружу:

• Отдельные markdown-доки под конкретные темы: как собирать проект, как гонять тесты, конвенции кода, архитектура сервиса. В CLAUDE.md - только короткое описание и ссылка, где взять детали.
• Скиллы. Доменные знания и повторяющиеся workflow живут в скиллах, и Claude Code грузит их по требованию, не раздувая каждый разговор. Это и есть способ дать агенту много контекста, но платить за него только когда он реально нужен.

Механически это держится на импортах. CLAUDE.md умеет подтягивать другие файлы через синтаксис @путь/к/файлу - например, @docs/git-instructions.md или @README.md. Файл остаётся коротким, а детали лежат рядом и подключаются адресно.

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

Что выкинуть из CLAUDE.md, чтобы кодинг с ии не буксовал

Самая частая ошибка - пихать в файл то, что агент и так знает или может прочитать сам. Официальная дока Claude Code прямым текстом даёт список "не клади сюда":

• Гайды по стилю кода. Это работа линтера и форматтера, а не LLM. Стилевые правила тащат в контекст кучу почти бесполезных строк и роняют качество. Для стиля есть Biome, ruff, prettier - дешевле и надёжнее.
• Всё, что агент выведет сам, прочитав код. Пофайловые описания репозитория, стандартные конвенции языка, самоочевидные "пиши чистый код".
• Детальную документацию API. Дай ссылку на доки вместо копии.
• То, что часто меняется. Устаревшая инструкция хуже отсутствующей.

В CLAUDE.md имеет смысл держать обратное: команды, которые агент не угадает, нестандартные для языка правила стиля, как запускать тесты, конвенции веток и PR, архитектурные решения именно вашего проекта, квирки окружения (нужные переменные) и неочевидные грабли.

Кстати, про то, как скиллы Claude Code сами по себе могут сжирать лимит, если их не причесать, я писал отдельно - в разборе про экономию лимита. Раздутый контекст бьёт и по деньгам, не только по качеству.

Кто и когда обновляет агентскую документацию

Тут два лагеря, и оба по-своему правы.

Первый лагерь - руками и бережно. Дока Claude Code советует относиться к CLAUDE.md как к коду: коммитить в git, регулярно чистить, пересматривать, когда что-то пошло не так. HumanLayer идёт дальше и говорит не автогенерировать этот файл вообще: это точка слишком высокого рычага, она влияет на каждую сессию, поэтому каждую строку лучше писать вдумчиво. Стартер через /init сгенерить можно, но дальше его надо допиливать головой, а не оставлять как есть.

Второй лагерь - автоматизация. Пост, из которого выросла эта статья, был как раз про OpenWiki - опенсорсный агент от LangChain. Он индексирует репозиторий и держит документацию как базу ссылок-знаний, а не как один длинный файл, и обновляет её сам через CI/CD (GitHub Actions и аналоги). Логика понятна: если доку не обновлять, она гниёт быстрее кода, а руками за этим никто не следит.

Моё примирение этих лагерей такое: автоматизация хороша для справочной базы знаний по репозиторию (её много, она меняется, её незачем держать в голове агента постоянно). А вот сам CLAUDE.md - тот самый короткий файл с правилами - лучше держать руками. Он маленький, он высокорычажный, и цена ошибки в нём размазывается на все ваши сессии. Автогенерить стену, которую агент всё равно проигнорирует, - это лечить симптом длины ещё большей длиной.

Как это выглядит на практике

Если свести всё в короткий чек-лист для llm в разработке:

• CLAUDE.md - короткий (ориентир до 300 строк, а лучше меньше сотни). Только то, без чего агент ошибётся.
• Детали - в отдельные доки и скиллы, подключаются через @import и грузятся по требованию.
• Ссылки вместо копий: файл:строка, а не вставленный кусок кода.
• Стиль - линтеру, не агенту.
• Ресёрч по репозиторию - сабагентам, чтобы не топить основной контекст.
• Обновление: короткий файл - руками и в git, большую базу знаний - можно автоматом через CI.

У себя в пайплайне я как раз перевожу проекты на эту схему: короткий CLAUDE.md на входе, а всё остальное - скиллами и ссылками. Побочный эффект - агент реже "забывает" правила и реже устраивает сюрпризы вроде того, как однажды снёс мне папку проекта. Меньше контекста в голове у агента - меньше поводов для творчества не в ту сторону.

Такие дела. Файл, который вы пишете для агента, - это не свалка всего, что вы про проект знаете. Это короткая карта с указателями, куда пойти за подробностями. Указатели, а не простыня.