Незнакомый старый проект удобнее изучать через один пользовательский сценарий. Просьба «объясни весь репозиторий» часто приводит к общим словам о слоях и паттернах, которые ещё не подтверждены кодом. Выберите конкретный вопрос: как формируется счёт, почему меняется статус заказа или откуда берётся настройка. ИИ помогает проследить путь данных, если каждое утверждение привязано к существующему символу.
Подготовьте карту доступного контекста
Укажите язык, способ запуска, точку входа и версию исходников. Дайте структуру релевантных каталогов, конфигурацию сборки и существующие тесты. Не загружайте весь проект без разбора: большой объём вспомогательных файлов может скрыть важные ветки. Сначала попросите модель перечислить, чего ей не хватает для ответа на выбранный вопрос.
Разделяйте три вида утверждений: видно непосредственно в коде, подтверждается тестом и предположено по названию. Функция calculateTotal может учитывать скидки, а может просто возвращать сохранённое поле. Имя является подсказкой для поиска, но не доказательством поведения. Для каждого шага цепочки полезны путь файла, имя функции и краткое описание входа и выхода.
Разбор по одному маршруту
- Найдите точку входа сценария: HTTP-обработчик, команду, событие или задачу планировщика.
- Проследите прямые вызовы и преобразования данных до сохраняемого результата.
- Отметьте внешние зависимости: базу, очередь, файловую систему и сторонние API.
- Проверьте условия ветвления, обработку ошибок, повторные попытки и побочные эффекты.
- Сопоставьте рассказ модели с тестами и одним наблюдаемым запуском в безопасной среде.
- Запишите неизвестные участки отдельно, не достраивая их из предполагаемой архитектуры.
Учебный маршрут заказа
Предположим, обработчик принимает заказ на две позиции, передаёт его в pricing, затем сохраняет итог через repository. В иллюстративном примере товары стоят 700 и 300 рублей, а скидка 10 процентов применяется только к первой позиции. Ожидаемый итог — 930 рублей. Если модель пишет 900, она предположила общую скидку и неверно поняла правило.
Попросите показать конкретную ветку, которая определяет область скидки. Затем проверьте, не применяется ли округление до суммирования и не добавляется ли доставка позднее. Такой числовой пример заставляет объяснение стать проверяемым. Он также помогает отличить фактическое поведение от того, как код, по мнению читателя, должен работать.
Промпт для изучения
Разбери только сценарий расчёта заказа в предоставленных файлах. Построй цепочку от точки входа до сохранения результата. Для каждого шага укажи файл, символ, вход, выход и побочный эффект. Раздели доказанные факты и предположения. Не придумывай отсутствующие вызовы. Покажи один пример прохождения данных и перечисли ветки, которые он не покрывает. Изменения кода пока не предлагай.История изменений как дополнительный контекст
Если поведение странное, сравните соответствующий участок с предыдущей версией. Официальная документация git diff описывает сравнение деревьев и рабочих изменений. История помогает увидеть момент изменения, но сообщение коммита не заменяет проверку текущего кода. После рефакторинга старое описание может уже не отражать реальную последовательность действий.
Не запускайте неизвестные установочные скрипты только ради объяснения. Сначала прочитайте команды запуска и конфигурацию. Для понимания бизнес-правила часто достаточно исходников и небольшого изолированного теста. Если нужен доступ к внешней системе, отметьте это как границу исследования и подготовьте конкретный вопрос человеку, который отвечает за интеграцию.
Как оформить результат
Хорошая заметка содержит назначение сценария, краткую схему вызовов, инварианты, точки изменения состояния и список нерешённых вопросов. Избегайте каталогов из сотен функций: следующему разработчику важнее понять путь одной операции. Добавьте дату и ревизию проекта, чтобы читатель знал, к какому состоянию относится объяснение.
Частые вопросы
Можно ли сразу попросить переписать старый модуль?
Сначала зафиксируйте текущее поведение и проверки. Иначе исправление стиля может случайно изменить правила, которые нигде не описаны, но используются клиентами.
Что делать, если тестов нет?
Соберите небольшие примеры входа и наблюдаемого выхода. Такие проверки характеризуют существующее поведение и помогают обнаружить изменения при дальнейшем рефакторинге.
Как проверить рассказ без глубокого знания языка?
Просите короткие цепочки, конкретные значения и ссылки на символы. Неясный шаг превращайте в отдельный вопрос, а не принимайте целую архитектурную историю на доверии.
Гайд подготовлен для Tarasov Code — проекта Ильи Тарасова и TarasovWeb.