Исследование кодовой базы: решение проблемы

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

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

Исследование без вопроса бесконечно и дорого. Запрос «изучи проект» — враг: он заливает контекст всем подряд и гонит сессию за продуктивную границу ещё до начала работы. Вместо него задавайте узкий вопрос, на который исследование должно ответить.

1. Что я ищу. «Где в проекте лежит логика валидации email?»
2. Зачем оно мне. «Чтобы переиспользовать существующую функцию, а не писать свою».
3. Что считается успехом. «Конкретный файл и имя функции».
4. Где искать нельзя. «Точно вне папки node_modules и сгенерированных артефактов».

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

Чтобы ответить на узкий вопрос, агенту не нужно читать файлы целиком. Ему нужны точечные команды поиска, которые есть у него благодаря запуску команд из оболочки. Классический набор прост и дёшев по контексту.

1. Поиск по имени. grep по сигнатуре функции или имени модуля показывает все места, где сущность упоминается.
2. Поиск по типу. grep по объявлению класса или типа находит единственный файл с определением, а не десятки мест использования.
3. Список файлов. быстрый обход структуры проекта показывает, какие модули существуют, без чтения их содержимого.
4. История изменений. взгляд в историю по одному файлу раскрывает, кто и зачем менял логику раньше.

Сила этого подхода в том, что вывод команды — это короткая строка, а не большой файл. Несколько таких строк дают агенту достоверные факты: «функция validateEmail определена в utils/validation.ts». Найдите так, и агент перестанет выдумывать существующие сущности — вопрос, был ли он вообще знаком с проектом, отпадает сам собой.

Главный соблазн после поиска — вывалить найденные файлы целиком в контекст «для уверенности». Не делайте так. Чтение — это затратная операция: каждый прочитанный файл оседает в сессии и приближает её к границе Smart Zone, где рассуждения агента теряют качество.

Дисциплина такая: читаем ровно тот файл, который ответил на исследовательский вопрос, и только тот кусок, который нужен. Обнаружили, что validateEmail живёт в utils/validation.ts? Прочитайте определение функции, а не весь файл и не соседние модули. Если по ходу выясняется, что функция опирается на ещё один модуль, прочитайте и его, но не больше.

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

Работает это так: вы делегируете субагенту узкий исследовательский вопрос, он ходит по файлам, делает grep, читает один-два файла и приносит короткий ответ. Основная сессия при этом не разбухает — в неё попадает итог, а не все промежуточные шаги. Благодаря этому даже широкое исследование не выталкивает вас за границу продуктивной зоны и не распаляет счёт за контекст.

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

Любое исследование завершается не текстом, а проверяемым фактом. Самый быстрый тест на то, действительно ли агент опирался на код, а не достроил картину из вероятностей, — попросить его назвать источники. Если он отвечает «validateEmail определена в utils/validation.ts, строка 41» — это факт. Если он говорит «наверное, где-то есть функция» — это догадка, близкая к галлюцинации.

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

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

Если стало очевидно, что агент намешал в контекст слишком много и застрял, не пытайтесь «докрутить» поверх накопленного мусора. Остановитесь и начните сессию заново, зафиксировав уже известные факты. Здесь выручает умение откатываться назад: вернуть состояние до неудачной попытки и продолжить с чистой головой дешевле, чем биться с испорченным контекстом.

Решение проблемы исследования кодовой базы — это порядок действий, а не вера в модель: узкий исследовательский вопрос на старте, точечные команды поиска вместо чтения всего, ограничение объёма рамками Smart Zone, делегирование широкого поиска субагентам и проверка фактов через названные файлы и строки. Выполненное по этому порядку, исследование превращается из источника велосипедов в надёжный фундамент любых изменений.

В следующем уроке соберём изученные приёмы в единый рабочий процесс — от постановки задачи через исследование к готовому изменению без дублей и лишних трат.

1. Исследовательский вопрос — узкий запрос, на который должно ответить исследование, с критерием успеха.
2. Точечная команда — команда поиска, возвращающая короткий факт вместо большого файла.
3. Факт проекта — проверяемое утверждение о коде, например «функция живёт в таком-то файле на такой-то строке».
4. Источники — конкретные файлы и строки, которыми агент подтверждает свои выводы.
5. Субагент — независимый контекст, выполняющий подзадачу, в том числе исследование, не засоряя основную сессию.
6. Smart Zone — продуктивный диапазон заполнения context window, в котором агент рассуждает качественно.
7. Избыточность контекста — наличие в контексте информации, не нужной для текущей задачи.
8. Галлюцинация — правдоподобный, но не соответствующий реальности вывод модели.
9. Harness — программа-оболочка, через которую пользователь взаимодействует с LLM и управляет агентом.
10. Откат — возврат к предыдущему состоянию после неудачной попытки.