Как ИИ-агент разбирает чужой код без документации

Вы открываете незнакомый репозиторий на 400 файлов без документации. Coding-агент — Claude Code от Anthropic, агентный режим Cursor, Windsurf Cascade или GitHub Copilot — за пару минут отвечает на вопрос «где обрабатывается оплата» и предлагает патч. Ни README, ни архитектурных диаграмм при этом не было. Разберём, что происходит под капотом: агент не читает весь проект целиком, а собирает его модель по кускам, и от того, как именно он это делает, зависит, поверите вы ответу или нет.

Проблема: код не влезает в контекст

Средний проект — это сотни тысяч, а то и миллионы токенов. Даже большие контекстные окна¹ современных моделей (у Claude — до 200 тысяч токенов, у Gemini 1.5 Pro Google заявляет до 1–2 миллионов) не вмещают крупную кодовую базу целиком, а если и вмещают, забивать окно всем подряд дорого и вредно для качества ответа. Поэтому агент работает не как читатель, который проглотил книгу, а как следователь: задаёт вопросы, открывает нужные файлы, отбрасывает лишнее.

Ключевое отличие агента от обычного чата с моделью — доступ к инструментам. Агент может выполнить команду в терминале, прочитать файл, запустить поиск по коду и получить результат обратно в контекст. Дальше он решает, что делать со следующим шагом. Именно эта петля «действие — наблюдение — следующее действие» и позволяет понять архитектуру без документации.

С чего агент начинает

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

• Манифесты зависимостей. package.json, requirements.txt, go.mod, pom.xml, Cargo.toml — по ним видно язык, фреймворк, скрипты запуска и тестов.
• Конфиги сборки и запуска. Dockerfile, docker-compose.yml, Makefile, CI-файлы в .github/workflows — они показывают, как проект собирается и что считается точкой входа.
• Дерево каталогов. Папки src, api, migrations, components сами по себе — карта. Соглашения об именах у популярных фреймворков предсказуемы.
• Точка входа. main.py, index.ts, app/main.go — отсюда агент разматывает граф импортов.

По сути агент делает то же, что опытный разработчик в первые пять минут: не читает код построчно, а считывает соглашения. Фреймворк с жёсткой структурой (Django, Rails, NestJS) агент понимает почти мгновенно, потому что расположение файлов диктует смысл. С самописной архитектурой без явных конвенций сложнее — там приходится читать больше.

Как устроен поиск: grep против эмбеддингов

Дальше агенту нужно находить релевантные куски по запросу вроде «где проверяется JWT-токен». Здесь у инструментов расходятся подходы.

Агентный поиск (grep и обход файлов)

Claude Code и агентные режимы редакторов часто идут в лоб: запускают текстовый поиск (grep, ripgrep) по ключевым словам, читают найденные файлы, идут по импортам дальше. Это буквально повторяет то, как разработчик ищет через поиск по проекту. Плюс — свежесть: агент видит актуальное состояние файлов, ничего не устаревает. Минус — цена и скорость: каждый шаг тратит токены и время, а по неудачному ключевому слову можно промахнуться.

Семантический поиск (RAG по коду)

Другой подход — заранее проиндексировать репозиторий: разбить код на фрагменты, посчитать эмбеддинги и складывать в векторную базу. При запросе агент достаёт наиболее близкие по смыслу куски. Это классический RAG². Cursor, например, строит и хранит индекс проекта. Плюс — находит по смыслу, даже если точных слов в коде нет. Минус — индекс нужно поддерживать в актуальном состоянии, а нарезка кода на фрагменты рвёт логические связи между функциями.

Агент не «понимает» проект в человеческом смысле. Он строит рабочую гипотезу об архитектуре, достаточную для конкретной задачи, — и переспрашивает код, когда гипотезы не хватает.

Дерево синтаксиса

Поверх поиска многие инструменты используют разбор кода в AST — абстрактное синтаксическое дерево. Это позволяет извлекать сигнатуры функций, классы, импорты и связи между ними точнее, чем текстовым поиском. Библиотека tree-sitter, которую применяют в том числе редакторы на базе VS Code, умеет разбирать десятки языков и часто лежит в основе «карты символов» проекта.

Сравнение подходов

На практике инструменты комбинируют всё три: строят карту символов через AST, ищут релевантные места семантически или через grep, а затем дочитывают контекст обходом по импортам. Чистого «одного метода» почти ни у кого нет.

Где агент ошибается

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

• Мёртвый код. Агент может уверенно объяснить функцию, которая давно не вызывается, если по имени она выглядит центральной.
• Неявные связи. Вызовы через строковые имена, рефлексию, очереди сообщений или переменные окружения текстовый поиск не свяжет — граф вызовов рвётся.
• Магия фреймворка. Автоматическая маршрутизация, декораторы, dependency injection: логика есть, но в явном виде в файлах её не видно.
• Устаревший индекс. Если RAG-индекс не пересобрался после ваших правок, агент отвечает по старой версии кода.

Проверить гипотезу агента дёшево: попросите показать конкретные строки и файлы, на которые он опирается. Если он ссылается на реальные места в коде — доверия больше. Если пересказывает общими словами без ссылок — вероятно, догадывается.

Кому это пригодится и кому нет

Пригодится:

• Онбординг в чужой проект — быстро понять, где что лежит, вместо недели блуждания по файлам.
• Разбор legacy-кода без документации и без живых авторов.
• Локализация бага: «где формируется этот ответ API» — агент проходит по цепочке вызовов быстрее человека.
• Рутинные правки в понятной части кода: переименования, типизация, добавление тестов.

Не заменит вас:

• Проекты с тяжёлой скрытой логикой (кодогенерация, метапрограммирование, распределённые события) — агент теряет нить.
• Архитектурные решения, где важны договорённости команды, а не текст кода.
• Безопасность и приватность: если код нельзя выгружать наружу, проверьте, где именно инструмент обрабатывает данные и что уходит на серверы вендора.

Хорошая новость для тех, кто пишет код: минимальная документация всё ещё окупается. Файл ARCHITECTURE.md или комментарии-указатели в точках входа резко повышают точность агента, потому что он читает их первыми и достраивает карту от них. Агент понимает проект без документации, но с документацией понимает его правильнее.

¹ Контекстное окно — максимальный объём текста (в токенах), который модель удерживает одновременно: и ваш запрос, и прочитанные файлы, и собственный ответ. Всё, что не поместилось, модель «не видит».

² RAG (retrieval-augmented generation) — подход, при котором система сначала находит релевантные фрагменты во внешнем хранилище, а затем передаёт их модели как контекст для ответа, вместо того чтобы полагаться только на память модели.