Как быстро разобраться в чужой кодовой базе

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

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

Коротко:

• Сначала запуск и точки входа, не «прочитаю все сервисы».
• Учитесь на маленькой задаче: один баг или один путь запроса.
• Тесты, git blame и переход к определению экономят часы блуждания.
• 15 минут самостоятельной попытки, потом конкретный вопрос с тем, что уже проверили.
• Ведите личную карту: сервисы, команды запуска, «кто знает модуль».

Почему «прочитать всё» не работает

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

Команде от вашего полного конспекта пользы мало. Польза — когда вы можете провести изменение по одному срезу и не сломать соседний. Поэтому погружение оценивают по первому аккуратному PR и по тому, как вы спрашиваете, а не по толщине заметок. Как этот PR оформить — в материале про первый pull request.

Сначала карта: запуск, входы, папки

Первый рабочий день в коде — не архитектура в Miro. Это ответы на пять вопросов.

1. Как поднять локально или на dev-стенде? Какая команда тестов?
2. Где лежит конфигурация: env, флаги, секреты (без копирования секретов в чат)?
3. Где вход пользовательского запроса: HTTP-ручка, воркер, крон, бот?
4. Какие 5–10 верхних папок и зачем каждая, своими словами?
5. Кто в команде «держит» какой кусок? Имена, не «где-то бэкенд».

README, docker-compose, Makefile, схема в Confluence — читайте их как карту метро, не как роман. Если README врёт, это ваш будущий маленький вклад, а не повод бросить запуск. Зафиксируйте, на каком шаге падает: так вопрос ментору будет точным.

Не рисуйте идеальную диаграмму всех микросервисов в первый день. Нарисуйте тот контур, в который вас посадили: один сервис, одна база, один клиент. Остальное — пунктиром «существует, трогать не буду, пока не придёт задача».

Один запрос — один срез

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

Держите открытыми: лог запроса, точку входа, слой, который ходит в базу, тест, который описывает похожий случай. Идите по вызовам, не по алфавиту папок. Когда путь оборвался на магии фреймворка — тогда и спрашивайте, а не «объясните весь Django».

Если задачи ещё нет, попросите ментора: «дай баг с понятным воспроизведением в нашем сервисе». Без задачи карта остаётся туристической. Первая неделя как ритуал — в плане первой недели разработчика.

Инструменты чтения кода

Три привычки закрывают большую часть блуждания.

• Переход к определению и поиск по символу. Не гадайте, откуда сущность. Прыгайте. Если прыжков больше семи и вы потерялись — остановитесь, запишите развилку, спросите.
• Тесты как спецификация. Имя теста часто яснее комментария 2019 года. Прочитайте arrange/act/assert, потом код. Если теста нет — воспроизведите руками и подумайте, стоит ли добавить один в том же PR, если так принято.
• История и blame. Странный if часто родился из инцидента. Сообщение коммита и тикет экономят спор «давайте удалим, не используется». Иногда используется, просто редко.

Логи и трассировки на dev — четвёртый инструмент, если они уже настроены. Не подключайте новую наблюдаемость в первую неделю «чтобы понять систему»: это уже отдельный проект.

Пример 1. Баг: пустой список заказов отдаёт 500

Junior backend, сервис заказов. Тикет: кабинет падает, если у пользователя ещё нет заказов.

1. Воспроизвели на пустой базе: GET /orders → 500. Зафиксировали тело ошибки.
2. Нашли ручку поиском по пути. Увидели контроллер → сервис → репозиторий.
3. В репозитории None вместо списка. Теста на пустой список нет, есть только на «один заказ».
4. Blame на строке — старый коммит «hotfix npe», без теста. Вывод: дыра известного класса, не мистика.
5. Карта пополнилась: слой репозитория возвращает None, сервис этого не ждёт. Первый PR — вернуть пустой список и тест.

За полдня вы узнали больше, чем за два дня чтения папки utils. Срез выбран задачей, не любопытством.

Пример 2. Шпаргалка после трёх дней

Так может выглядеть личная карта. Её не нужно никому показывать в идеальном виде — она для вас и для вопросов на 1:1.

Сервис: orders-api. Вход: HTTP, воркер outbox. Запуск: make up, тесты make test-orders.

Путь заказа: ручка → OrderService → OrderRepo → таблица orders. Статусы: created / paid / failed. Paid ставит воркер платежей, не ручка.

Конфиг: DATABASE_URL, флаг ORDERS_EMPTY_LIST_FIX — не трогать, пока не скажут.

Люди: Марина — домен заказов, Илья — платежи, Денис — CI. Вопросы по миграциям — в канал #backend, не в личку всем.

Дыры: README врёт про migrate. Тикет заведу, когда соберу точную команду из Makefile.

Через две недели карта обрастёт исключениями. Это нормально. Не переписывайте её в «полную архитектуру компании» — вы сюда не на это наняты в месяц 1.

Как спрашивать, чтобы отвечали

Плохой вопрос: «как тут всё устроено?» Хороший вопрос занимает шесть-восемь строк и показывает работу.

Разбираю JS-1842: пустой список заказов даёт 500.

Проверил: ручка GET /orders, падение в OrderRepo при None. Теста на пустой список нет.

Не понял: пустой список должен быть 200 и [] или 404 «нет заказов»? В соседней ручке товаров — 200 и пустой массив.

Могу сделать возврат [] плюс тест. Ок, или у заказов другой контракт?

Так ментор отвечает одной фразой, а не читает вам курс. Если 15 минут поиска ни к чему не привели, так и напишите: где искали (README, тест, blame), что не нашли. «Я ничего не смотрел, объясните» на удалёнке быстро портит кредит доверия — как раз то, что смотрят на испытательном сроке.

Где остановиться, чтобы не утонуть

Остановитесь, если:

• Прыжки по коду идут по кругу, а задача не продвинулась час.
• Вы читаете третий соседний сервис «на всякий случай».
• Заметки длиннее, чем тикет, и в них нет следующего шага.

Тогда — вопрос, прогулка, другая маленькая задача. Глубина придёт от повторения срезов, не от марафона в субботу. План, куда эту глубину класть по месяцам, — в 30/60/90.

Чек-лист первых трёх дней в репозитории

• Проект поднимается или есть точный лог, на каком шаге нет.
• Знаете команду тестов своего сервиса.
• Нарисован один пользовательский путь: 5–10 узлов, не вся компания.
• Записаны 3 человека «к кому с чем».
• Есть маленькая задача или явный запрос ментору её выдать.
• В личной шпаргалке есть входы, конфиг, дыры README.
• Ни одного секрета из .env не уехало в чат и в PR.

Что можно не читать в первую неделю

Время на карту конечное. Явно вычеркните:

• Генераторы кода и внутренние DSL, до которых ваша задача не доходит. Встретите — вернётесь.
• Исторические ADR старше вашей зоны, если ментор не сказал, что инвариант живой. Один актуальный документ важнее архива за пять лет.
• Фронтенд, мобильное приложение, биллинг соседней юрлица — пока ваш тикет в orders-api.
• «Красивый» рефакторинг в ветке, которую никто не мёржил. Это черновик, не карта продакшена.
• Все флаги в конфиге. Нужны те, что на пути вашего запроса. Остальные — по имени, когда всплывут.

Вычёркивание — тоже работа. На 1:1 можно сказать: «карту платежей не строил, граница — событие paid, детали у Ильи». Это выглядит взрослее, чем «я почти всё прочитал». Почти всё прочитать в живом продукте нельзя; можно честно назвать край своего контура.

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

Практический якорь: после каждого среза допишите в шпаргалку одну строку «теперь я могу изменить X, не ломая Y». Если такой строки нет — срез был туристическим. Вернитесь к тикету или попросите тикет. Код без изменения быстро забывается; код, через который прошёл ваш diff, остаётся.

Ещё один рабочий приём — «обратный путь» от падающего теста. Если тесты зелёные, сломайте локально ожидаемое поведение (временно) и посмотрите, какой тест покраснел. Так вы узнаете, какие инварианты команда уже зафиксировала, и не начнёте чинить баг способом, который ломает скрытый контракт. Не оставляйте сломанный тест в незакоммиченном виде на ночь и не пушьте это «для эксперимента». Это учебный жест на своей машине, не вклад.

Когда карта из пяти узлов стабильно совпадает с тем, что вы видите в логах, остановите коллекционирование папок. Следующий час лучше потратить на описание будущего PR: что меняете, как проверите, какой риск. Если описание не пишется, вы ещё не поняли срез — и это сигнал вернуться к ручке, а не открыть соседний сервис «для ясности».

Частые вопросы

Что сделать сейчас

Сегодня поднимите сервис или соберите точный лог падения. Завтра проведите один пользовательский запрос от ручки до базы и запишите путь в шпаргалку. Послезавтра возьмите маленький баг или дыру в README и доведите до PR.

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