Разработчик месяц наблюдал за агентами в своём коде: дерево файлов дороже JSON

Год назад автор материала на Habr копировал файлы в окно чата по одному. Сегодня агенты сами читают его проект через MCP-сервер, а он месяц наблюдал, что именно они берут в контекст. Выводы получились практичными. Текстовое дерево файлов стоит дороже JSON, папку build нельзя исключать по имени, пароли можно спрятать так, что код перестанет работать, а агент без контроля распоряжается контекстом куда расточительнее, чем ожидаешь.

Оригинальная статья доступна в виде анонса, поэтому ниже разобраны заявленные тезисы и инженерная логика, которая за ними стоит. Точные замеры автора стоит смотреть в первоисточнике.

Почему дерево дороже JSON

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

У MCP здесь особая роль. Протокол превращает чтение проекта в набор вызовов инструментов: список файлов, содержимое, поиск. Формат ответа каждого такого вызова попадает в контекст целиком, и его цену платит каждый запрос агента.

Папка build и пароли

Второй урок касается фильтрации. Правило «пропускать папки с именем build» выглядит разумно, пока в проекте не появляется каталог с таким же названием, где лежит исходный код, а не артефакты сборки. Надёжнее смотреть на то, что делает папка: попадает ли она в .gitignore, генерируется ли сборкой, как давно менялась.

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

Агент без присмотра

Самый любопытный сюжет автор описывает коротко: что агент делает с контекстом, когда за ним никто не следит. Типичные симптомы известны всем, кто запускал длинные сессии: повторное чтение одних и тех же файлов, подгрузка лишних каталогов, раздувание окна старыми результатами инструментов. Каждый такой шаг стоит токенов и ухудшает качество ответов, потому что полезный сигнал тонет в шуме.

• Формат описания проекта: текстовое дерево дороже JSON.
• Фильтры: имя папки не годится как единственный критерий.
• Секреты: маскировка значений вместо удаления строк.
• Транспорт: MCP-сервер как единая точка контроля над тем, что видит агент.
• Риск: бесконтрольный рост контекста в длинных сессиях.

С чего начать проверку своего проекта

Сначала посмотрите, что реально уходит в контекст. Если ваш MCP-сервер или агентская обвязка не логирует объём ответов, добавьте счётчик токенов на каждый вызов. Без него оптимизировать нечего.

Затем сравните форматы. Прогоните один и тот же репозиторий через дерево и через компактный JSON и сопоставьте число токенов. Потом пересмотрите правила исключений: опирайтесь на .gitignore и признаки сгенерированных файлов, а не на список имён.

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