Исследование кодовой базы

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

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

Только чтение

Исследование не должно ничего менять. Запустите Codex в режиме только для чтения:

codex --sandbox read-only

Или переключитесь в текущей сессии через /permissions. Агент сможет читать файлы и запускать команды, которые ничего не пишут (поиск, git log, git blame), а на любое изменение запросит одобрение. Подробно о режимах — в уроке «Песочница и одобрения».

Лестница вопросов

Вопрос «расскажи про проект» даёт пересказ README. Полезнее спускаться по ступеням — от общего к частному.

Карта. «Опиши структуру: какие плагины, где бизнес-логика, где интеграции с внешними сервисами, как запускаются тесты. По каждому пункту — пути».

Поток. Самый полезный тип вопроса — проследить путь данных. «Что происходит после отправки формы заявки на /contacts — от AJAX-обработчика до записи в CRM? Перечисли шаги с файлами и номерами строк». Для мобильного приложения: «Как пуш-токен попадает на бэкенд и где он обновляется при смене пользователя?»

Точка. «Почему в LeadService::send() отправка идёт через очередь, а не сразу? Найди коммит, в котором это появилось, и его описание». Агент сам запустит git log -S или git blame.

Влияние. Перед изменением: «Кто вызывает PriceCalculator::calculate()? Что сломается, если добавить в него обязательный параметр?»

Каждая ступень опирается на предыдущую. Ответ на вопрос о потоке точнее, если агент уже построил карту в этой же сессии.

Требуйте доказательств

Модель может сочинить правдоподобное объяснение — особенно если код похож на типичный Laravel, а в проекте всё устроено иначе. Защита простая: требуйте ссылки и проверяйте их.

Отвечай только по коду этого репозитория. Для каждого утверждения
дай путь и номер строки. Если не нашёл или предполагаешь — так и пиши:
«не нашёл», «предположение».

Откройте две-три ссылки сами. Если они ведут не туда, остальной ответ тоже под вопросом. Хорошая привычка — просить подтвердить вывод запуском: существующим тестом или маленьким скриптом. Если команде нужна запись (кэш, логи), агент в режиме только для чтения запросит одобрение — решите, разрешать ли.

Свою догадку тоже можно проверить, не выходя из сессии: !rg -n "LeadService" выполнит команду локально с текущими настройками песочницы и одобрений.

Субагенты для широкого поиска

Если вопрос охватывает весь проект — «где мы обращаемся к внешним API и как обрабатываем их ошибки?» — основной чат быстро заполнится содержимым десятков файлов. Codex умеет запускать субагентов по прямой просьбе. Среди встроенных есть explorer — агент для исследования кода, который в основном читает.

Запусти трёх субагентов-исследователей: первый ищет обращения к внешним
HTTP API в plugins/, второй — в app/, третий — в мобильном клиенте
в mobile/. Каждый возвращает список: файл, сервис, как обрабатываются
ошибки и таймауты. Потом сведи всё в одну таблицу.

В основной чат вернутся только выводы. Субагенты тратят больше токенов, чем один агент, поэтому берегите их для по-настоящему широких вопросов. Настройка своих агентов — в уроке «Субагенты».

Побочные вопросы и документация

По ходу исследования возникают вопросы в сторону: «что делает этот фильтр Twig?» Чтобы они не засоряли основной контекст, задавайте их в побочном чате /side (алиас /btw): ответ не попадёт в историю основной сессии.

Если вопрос не про ваш код, а про библиотеку — например, как ведёт себя метод Eloquent в вашей версии Laravel, — агенту нужна документация нужной версии. Веб-поиск по умолчанию работает по кэшированному индексу, живой поиск включается флагом --search. Проверьте, что агент сверился с версией из composer.lock или package.json, а не с последней.

Сохраните выводы

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

Запиши то, что мы выяснили про поток заявок, в docs/architecture/leads.md:
шаги с файлами, неочевидные решения и их причины, известные проблемы.
Пиши для разработчика, который видит проект впервые.

Если в выводах есть то, что агент должен знать в каждой сессии, — например, «заявки никогда не отправляются в CRM синхронно», — добавьте в AGENTS.md одну строку со ссылкой на документ. Сам документ в AGENTS.md не копируйте: файл инструкций должен оставаться коротким. Почему это важно и как устроить документацию под агента — в уроке «AGENTS.md как оглавление».