Как AI-агенты изучают большие репозитории

Почему чтение всего репозитория не стало решением

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

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

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

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

Репозиторий как карта, а не как набор файлов

Одним из наиболее распространённых инструментов такого подхода стали repository maps.

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

Задача repository map не в том, чтобы заменить код. Она выполняет другую функцию: помогает агенту понять общую структуру проекта и определить, где искать нужную информацию дальше.

Фактически карта отвечает на базовые вопросы:

• какие модули существуют;

• какие сущности являются центральными;

• где находятся точки входа;

• какие компоненты связаны между собой;

• какие части системы заслуживают дальнейшего изучения.

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

Поиск становится частью архитектурного анализа

После построения общей карты начинается второй этап — поиск релевантного контекста.

Sourcegraph Cody и Deep Search используют подход, при котором агент сначала выполняет поиск по репозиторию, а уже затем читает конкретные файлы. Вместо того чтобы анализировать весь проект, система пытается найти фрагменты, наиболее связанные с текущей задачей.

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

При этом поиск используется не только для поиска текста. Источники описывают работу с символами, ссылками между сущностями, историей изменений и связями между репозиториями.

Поиск превращается в инструмент исследования архитектуры, а не просто в механизм нахождения строк кода.

Dependency graph как источник архитектурных связей

Ещё один слой представления проекта — граф зависимостей.

Если repository map показывает общую структуру системы, то dependency graph помогает понять последствия изменений. Он позволяет определить, какие модули зависят друг от друга, какие компоненты используют конкретную библиотеку и какие части системы могут затронуть изменения.

В материалах OpenHands dependency-анализ используется для планирования миграций и крупных изменений. Вместо случайного обхода репозитория система сначала строит представление о зависимостях, а затем определяет порядок работы.

Однако исследование отдельно отмечает ограничения такого подхода.

Граф зависимостей хорошо показывает технические связи между компонентами, но не всегда помогает понять архитектурный замысел или бизнес-логику. Он может показать, что один модуль зависит от другого, но не объясняет, почему эта зависимость появилась и какие ограничения стоят за ней.

Поэтому dependency graph используется как часть архитектурной модели, но не как её полная замена.

Инструкции проекта как элемент навигации

Помимо структуры кода агенты всё чаще используют специальные файлы памяти и инструкций.

В исследовании регулярно упоминаются AGENTS.md и CLAUDE.md. Эти файлы содержат информацию о правилах проекта, соглашениях, способах запуска тестов, особенностях архитектуры и других аспектах, которые трудно восстановить только по коду.

С практической точки зрения такие документы выполняют роль путеводителя по системе.

Они позволяют агенту быстрее понять:

• какие части проекта считаются основными;

• какие архитектурные ограничения существуют;

• как�е инструменты используются;

• какие действия считаются допустимыми.

Важно, что подобные файлы рассматриваются не как замена архитектурной документации, а как дополнительный источник контекста.

Архитектурное понимание как задача исследования

Отдельный интерес представляет направление исследований, связанное с repository exploration.

В традиционных бенчмарках обычно оценивается результат: смог ли агент исправить ошибку или реализовать функцию. Однако в новых работах предлагается оценивать способность агента исследовать репозиторий как самостоятельный навык.

Такой подход основан на предположении, что между выполнением задачи и пониманием системы существует разница.

Агент может случайно найти правильное место для изменения и успешно завершить задачу. Но это ещё не означает, что он построил корректное представление об архитектуре проекта.

Поэтому исследователи всё чаще рассматривают навигацию по репозиторию как отдельную способность, которую можно измерять независимо от качества итогового патча.

Ограничения существующих подходов

Несмотря на развитие инструментов, исследование не говорит о решённой проблеме понимания архитектуры.

Во всех рассмотренных системах сохраняются ограничения.

Repository maps позволяют быстро ориентироваться в проекте, но могут терять детали. Dependency graphs показывают структуру зависимостей, но не объясняют архитектурные причины. Поиск помогает находить релевантные участки кода, но способен пропускать важные связи. Файлы памяти упрощают навигацию, однако быстро устаревают, если их не поддерживать.

Кроме того, несколько источников подчёркивают, что агент может понимать структуру системы значительно лучше, чем её назначение. Он способен обнаружить связь между компонентами, но не всегда понимает бизнес-мотивацию, стоящую за архитектурным решением.

Поэтому современные решения следует рассматривать скорее как инструменты построения рабочей модели проекта, чем как полноценное понимание системы в человеческом смысле.

Вывод

Материалы 2024–2026 годов показывают достаточно устойчивую тенденцию. AI-агенты не изучают большие репозитории путём последовательного чтения всех файлов. Вместо этого он� строят несколько уровней представления проекта: карты репозитория, графы зависимостей, индексы поиска и файлы памяти.

После этого агент постепенно исследует только те части системы, которые связаны с текущей задачей.

Поэтому архитектурное понимание в современных агентных системах выглядит не как задача чтения кода, а как задача навигации по сложной структуре проекта. Именно вокруг этой идеи сегодня строится значительная часть инструментов для работы с большими кодовыми базами.