Понимание кодовой базы

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

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

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

Агентный поиск

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

Агенты могут использовать grep — инструмент для поиска точных строк, а также создавать более сложные регулярные выражения или искать совпадения по границам слов. Существуют и улучшенные версии grep, например ripgrep, поддерживающие рекурсивный поиск.

Оба инструмента отлично справляются со своей задачей. Однако Cursor ещё больше улучшил grep с помощью Instant Grep, который может значительно ускорить агентный поиск в больших кодовых базах по сравнению с ripgrep.

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

Поиск по смыслу

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

Как задавать хорошие вопросы

От формулировки вопросов зависит, какие инструменты поиска использует Agent и насколько полезными будут результаты. Диапазон — от конкретных вопросов к общим: можно начать с поиска точного текстового совпадения, например имени функции, и перейти к широким запросам вроде «Помогите понять, что происходит, когда пользователь совершает платёж в нашем приложении».

Начинайте с конкретики, если знаете, что ищете. Задавайте более общие вопросы, когда изучаете незнакомую область. Рассмотрим несколько примеров.

В первом примере Agent начинает с grep, поскольку промпт содержит конкретный запрос. Он ищет import.*PaymentService, чтобы найти все файлы, в которых используется этот сервис.

Если вы изучаете незнакомую область, задавайте более общие вопросы. В следующем примере мы спрашиваем, как приложение обрабатывает неуспешные платежи. Обратите внимание: первый вызов инструмента — «Поиск по кодовой базе». Agent находит релевантные файлы, а затем использует grep, чтобы уточнить детали.

Субагент Explore

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

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

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

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

Архитектурные диаграммы

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

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

Распространённая ошибка: менять код, не разобравшись

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

Прежде чем просить внести изменения, сначала попросите агента изучить код:

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

Что дальше

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