Claude Code and Codex: how to reduce token losses with three markdown files

AI-агенты для разработки сжигают контекст не потому, что плохо отвечают, а потому что почти всё время тратят на поиск нужного места в коде. Даже при окне в миллион токенов они снова обходят директории, перечитывают знакомые файлы и проверяют серверы, будто видят проект впервые. В разборе показано, что на простой вопрос о платежах агент потратил больше 80 тысяч токенов и 15 с лишним вызовов инструментов, хотя сам ответ занял около 800 токенов.

То есть почти весь бюджет ушёл не на мышление, а на навигацию. Проблема оказалась не локальной особенностью Claude Code, а общим ограничением современных coding-агентов. По той же схеме работают Cursor, Codex и Gemini CLI: без карты рабочего пространства они начинают каждую новую сессию с разведки.

Если проект один, это терпимо. Но когда у разработчика десятки репозиториев, VPS и staging-окружений, агент сначала grep'ит домашнюю директорию, находит похожие файлы в соседних проектах, читает их, потом понимает, что зашёл не туда, и запускает новый круг поиска. В реальном примере вопрос о способах оплаты в одном боте обернулся поиском по нескольким проектам, повторным чтением шести файлов и даже SSH-проверкой конфигурации на сервере.

Такой режим не только дорогой, но и хрупкий: модель тратит силы на ориентирование и легко пропускает релевантные места. Автор разбирает три популярных подхода, которые обычно предлагают в качестве лекарства. Первый — RAG и векторный поиск.

Он хорошо находит семантически похожие фрагменты, но плохо понимает структуру проекта: может вернуть чанки с auth, login и token, но не восстановить точную цепочку зависимости между middleware, refresh-логикой и конфигурацией JWT. К тому же RAG требует отдельной инфраструктуры, индекса и переиндексации, а каждый запрос добавляет задержку. Второй путь — статический анализ и граф зависимостей через AST и tree-sitter.

Это полезно внутри одного репозитория, но почти бесполезно на уровне портфеля проектов, где нужно ответить не только как работает функция, но и где вообще живёт нужный сервис, на каком сервере он запущен и какой у него статус. Третий вариант — держать CLAUDE.md в каждом проекте.

Это помогает, но лишь после того, как агент уже понял, в какой проект ему идти. Вместо этого предлагается иерархический контекст, который ведёт агента сверху вниз. На нулевом уровне лежит глобальная карта проектов: короткая таблица с названиями, путями, серверами и статусами, которая автоматически попадает в каждую сессию.

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

А в качестве третьего markdown-слоя автор предлагает хранить прошлые сессии и инженерные решения в виде markdown-файлов с YAML frontmatter, чтобы агент мог вспомнить, что уже обсуждалось, какие файлы менялись и какие решения по дебагу или платежам принимались неделей раньше. Идея простая: сначала карта, потом описание проекта, затем память прошлых обсуждений, и только после этого исходники. Замеры показывают, что такая схема даёт не косметический, а практический выигрыш.

На вопрос об архитектуре проекта слепому агенту понадобилось 12 tool calls против одного при наличии иерархии. На вопрос о том, какие проекты используют конкретную библиотеку, слепой режим сделал 44 вызова, просканировал весь диск и при этом пропустил один из трёх нужных проектов; иерархия уложилась в два точечных запроса и дала полный ответ. В случае с деплоем эффект ещё заметнее: без структуры агент читал конфиги и ходил по SSH, а с правильно заполненным CLAUDE.

md смог ответить прямо из контекста вообще без дополнительных вызовов. Важный вывод здесь в том, что более организованный контекст повышает не только скорость и экономию токенов, но и точность ответа. Почему это работает лучше, чем привычный RAG-пайплайн?

Потому что markdown-файлы дают агенту нулевую задержку, предсказуемость и простое обновление. Разработчик сам задаёт, что именно важно знать о проекте, а не надеется, что ранкер достанет нужные чанки из индекса. Если поменялся деплой или сервис переехал, достаточно исправить одну строку.

Масштабирование тоже выглядит разумно: карта проектов занимает около 2 КБ, а пятнадцать проектных файлов по 5 КБ дают меньше 80 КБ структурированного контекста вместо сотен килобайт сырых исходников. На фоне разговоров о миллионных окнах контекста это особенно важно: больше токенов не всегда значит лучше. Нерелевантная информация размывает внимание модели, а эффект lost in the middle никуда не делся.

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