- Дата публикации
Как не сжечь половину контекста ИИ-агента на поиске файлов
Что появилось / что изменилось
Разработчик несколько месяцев гонял локальных AI‑агентов по большому репозиторию кода и заметил системный баг в рабочих процессах. На каждую задачу вроде «добавь новый API‑эндпоинт» агент тратил 15–20 вызовов инструментов только на ориентацию в проекте: grep по роутам, чтение middleware, типов, ещё файлов.
Результат — 20–40% доступного контекста уходило не на написание кода, а на блуждание по репозиторию. После перестройки документации и структуры знаний о проекте этот оверхед удалось стабильно снизить до менее чем 10%.
Ключевое изменение — трёхуровневая иерархия документации:
- Индексный файл: карта задач к нужным документам.
- Каталоги по намерению: директории и материалы, сгруппированные не по модулям, а по типам задач.
- Документация по глубине: короткий обзор на верхнем уровне, более подробные справки дальше по ссылкам.
В итоге агенту хватает 1–3 вызовов инструментов, чтобы понять, что где лежит, вместо прежних 15–20.
Как это работает
Исследование Liu et al. «Lost in the Middle» показало: модели вроде Llama и Claude лучше всего рассуждают в начале контекстного окна. Ближе к середине и концу качество внимания падает.
Когда агент тратит первые десятки шагов на grep и чтение файлов, он расходует «острый» участок контекста на навигацию. До момента, когда пора писать код, модель уже работает в менее выгодной части окна — и качество ответов заметно проседает. Автор видел, как один и тот же агент после 20 «ориентационных» вызовов пишет ощутимо худший код, чем после трёх.
Он описывает поведение агента как задачу восхождения на холм из теории оптимизации. Агент стартует с нулевым знанием, делает шаг (поиск по коду), оценивает, делает ещё шаг (чтение файла), снова оценивает — и так до тех пор, пока не почувствует, что готов действовать. Пропустить шаги он не может: он не знает, чего не знает.
Трёхслойная документация сокращает количество таких шагов. Вместо десятков «слепых» grep агент быстро находит нужный раздел через индекс, затем — нужную директорию по типу задачи, и уже там получает ровно тот объём информации, который ему нужен.
Что это значит для вас
Если вы используете AI‑агентов для работы с крупным кодом (локальные Llama‑подобные модели, Claude, GPT‑подобные решения), главный вывод простой: качество кода зависит не только от модели и промптов, но и от структуры вашей документации.
Практические шаги:
-
Сделайте индексный файл в репозитории. Это может быть
AGENT_INDEX.mdилиREADME_AGENTS.md, где вы явно сопоставляете типовые задачи с нужными разделами кода и документации: «добавить эндпоинт → см. docs/api/index.md и routes/». Агенту будет проще начать с него, чем сgrepпо всему проекту. -
Организуйте каталоги по намерению, а не только по архитектуре. Например:
docs/api/,docs/billing/,docs/auth/,docs/frontend/. Агенту важно быстро понять, куда идти для конкретной задачи, а не разбираться в вашей исторически сложившейся структуре. -
Разбейте документы по глубине. На верхнем уровне — короткий обзор: где лежат роуты, как устроен middleware, где типы. Ниже по ссылкам — подробные справочники и примеры. Агенту не нужен весь мануал на 50 страниц сразу.
-
Следите за числом инструментальных вызовов. Если агент делает 15–20 шагов, прежде чем написать первую строку кода, вы теряете контекст и качество. Цель — сократить это до 1–3 шагов навигации.
Где такой подход особенно полезен:
- Большие монорепозитории с десятками сервисов.
- Проекты, где вы часто поручаете агенту «вклиниться» в существующую архитектуру: новые эндпоинты, интеграции, миграции.
- Команды, которые активно используют локальные модели с ограниченным окном контекста.
Где эффект будет меньше:
- Маленькие проекты, где весь код помещается в одно окно контекста.
- Одноразовые скрипты и прототипы, где агенту проще перечитать весь файл целиком.
Если вы работаете из России и запускаете локальные модели (через ollama, LM Studio, vLLM и т.п.), такой подход не требует VPN и не зависит от внешних API. Это чисто организационная работа с вашим репозиторием.
Место на рынке
Речь не о новом продукте, а о методике работы с уже существующими AI‑агентами поверх моделей вроде Llama или Claude. Здесь нет новых скоростных бенчмарков или сравнений цен: выигрывает не сама модель, а способ подачи ей информации.
По сути, это ещё один слой поверх любых код‑агентов: вы оптимизируете не только промпты и настройки, но и структуру знаний в репозитории. Для команд, которые уже упёрлись в лимит контекста и замечают деградацию качества ответов на длинных сессиях, это может дать более предсказуемый результат, чем очередной тюнинг промптов.
Если вы довольны текущими агентами и у вас нет проблем с тем, что они «заблудились в репозитории», можно ничего не менять. Но если вы видите, что после десятка шагов агент начинает писать странный код, стоит начать не с замены модели, а с перестройки документации по описанной трёхуровневой схеме.