Знакомство с чужим проектом — одна из самых дорогих задач в работе разработчика. Новый репозиторий, сотни файлов, неочевидные связи: на то, чтобы понять, где что лежит и как оно работает, уходят дни. Claude Code сокращает этот срок радикально, потому что умеет обходить кодовую базу быстрее человека и рассказывать о ней связно.

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

Что уже умеем / что добавим

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

Что вы узнаете в рамках статьи

• Какими инструментами Claude Code ищет файлы и текст в проекте
• Чем поиск по шаблону имени отличается от поиска по содержимому
• Как агент читает файлы и какие ограничения тут есть
• Как формулировать исследовательские запросы разной глубины
• Как проверять ответы агента и замечать неточности

Ключевые термины

• Glob — инструмент поиска файлов по шаблону имени и пути, например src/**/*.ts.
• Grep — инструмент поиска текста внутри файлов по регулярному выражению; построен на ripgrep.
• Read — инструмент чтения содержимого файла; возвращает текст с номерами строк.
• Шаблон glob — маска пути: * заменяет часть имени в одном сегменте, ** — любую вложенность директорий.
• Исследовательский запрос — запрос, который просит агента разобраться и объяснить, не внося изменений в код.
• Галлюцинация — правдоподобное, но неверное утверждение модели; в разговоре о коде проверяется сверкой с исходником.

Три инструмента, которыми агент смотрит на код

Когда вы просите разобраться в проекте, агент не «видит» его целиком. Он последовательно применяет три инструмента, и понимание их различий сразу объясняет поведение агента.

Glob ищет файлы по шаблону имени и пути. Он отвечает на вопрос «где лежат такие файлы»:

**/*.js          # все файлы .js на любой глубине
src/**/*.ts      # все .ts внутри src
*.{json,yaml}    # .json и .yaml в текущей папке

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

Grep ищет текст внутри файлов. Он отвечает на вопрос «где это упоминается». Работает на ripgrep, поэтому синтаксис — регулярные выражения ripgrep, а не POSIX; специальные символы нужно экранировать. Область поиска сужается по шаблону пути или по типу файлов. Важная деталь: Grep учитывает .gitignore и пропускает игнорируемые файлы, а Glob по умолчанию — нет.

Read читает конкретный файл и возвращает содержимое с номерами строк. Очень большие файлы возвращаются частями, а не целиком.

Типичная последовательность выглядит так: сначала Glob находит кандидатов, потом Grep сужает круг до файлов с нужным упоминанием, потом Read открывает два-три из них. Именно эту цепочку вы наблюдаете в интерфейсе, когда агент «думает».

Запросы на исследование: от общего к частному

Исследование удобно вести слоями. Первый слой — общая картина:

что делает этот проект и на каком стеке он написан?

объясни структуру папок: что за что отвечает

Второй слой — конкретная подсистема. Здесь стоит называть предметную область, а не файлы:

как устроена аутентификация: где выдаются токены,
где проверяются, что происходит при истечении срока

Третий слой — точечные вопросы, ответ на которые вы будете использовать в работе:

найди все места, где напрямую обращаются к таблице orders,
и перечисли их с указанием файла и строки

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

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

проследи путь HTTP-запроса от роутера до обращения к базе
и назови каждый слой, через который он проходит

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

Почему исследование стоит отделять от правок

Есть сильная привычка, которую стоит завести сразу: сначала спросить, потом менять. Причин две.

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

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

На практике это выглядит как два запроса подряд:

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

и только после того, как объяснение вас устроило:

исправь это

Формулировка «пока ничего не меняй» — обычная просьба на естественном языке. Позже мы разберём режим, который запрещает правки на уровне самого инструмента, а не просьбы.

Проверка ответов: доверяй, но сверяй

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

Практика проверки простая и быстрая:

• Просите ссылки на файлы и строки. Утверждение с адресом проверяется за десять секунд, утверждение без адреса — не проверяется никак.
• Открывайте один-два ключевых файла сами. Не весь список, а те, на которых держится вывод.
• Сверяйте с реальностью проекта. Если агент упоминает библиотеку, которой нет в зависимостях, — это сигнал.

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

Частые ошибки

• Просить прочитать «весь проект». Запрос «прочитай все файлы и расскажи» бесполезен: контекст ограничен, а список результатов усекается. Спрашивайте про конкретную подсистему — так и ответ точнее, и работа быстрее.
• Принимать ответ без ссылок за факт. Объяснение без указания файлов и строк невозможно проверить. Просите адреса и открывайте ключевые места сами.
• Считать, что агент помнит проект между сессиями. Каждая новая сессия начинается с чистого контекста: изученное вчера сегодня заново выясняется на месте.
• Смешивать исследование и правку в одном запросе. «Разберись и сразу почини» лишает вас точки контроля: вы увидите изменения раньше, чем поймёте логику. Разделяйте на два шага.

Наиболее частые вопросы

• Индексирует ли Claude Code проект заранее? — Нет. Файлы ищутся и читаются по ходу работы, каждый раз заново под конкретную задачу.
• Видит ли агент файлы из .gitignore? — Поиск по содержимому уважает .gitignore и пропускает такие файлы, тогда как поиск по именам файлов по умолчанию их не исключает. Прочитать игнорируемый файл можно, указав путь напрямую.
• Что делать, если агент не находит очевидно существующий файл? — Сначала проверьте рабочую директорию: файл может лежать вне неё. Затем убедитесь, что путь написан верно, и попробуйте назвать его явно.
• Можно ли дать доступ к соседнему проекту? — Да, область доступа расширяется, но это часть темы разрешений, к которой мы перейдём в следующем уроке.
• Насколько можно доверять описанию архитектуры? — Как черновику от нового коллеги: направление обычно верное, детали нужно проверить по исходникам.

Итоги

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

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