Вход в незнакомый проект

Прочитать и понять — разные действия

Вам дали проект, который писали не вы. Сто, пятьсот, три тысячи файлов. Первое побуждение — открыть и начать читать; второе, с агентом, — попросить его «разобраться в проекте и рассказать». Оба ведут не туда, и по одной причине.

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

Разница видна на простом примере. Вы прочитали, что есть функция calcDiscount. Это факт из левой колонки. Из правой: вызывается ли она вообще, или рядом лежит вторая такая же и живая — вторая; почему их две; какая из них считает правильно; и что случится, если поправить не ту.

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

Правильный вход устроен наоборот: сначала вопросы, потом чтение ради ответа на них. Это тот же приём, что в чтении научной статьи: сначала спрашиваешь, что хочешь узнать, потом читаешь выборочно.

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

Пересказ полезен, но на своём месте: как указатель, куда смотреть. Про него в третьей главе будет отдельный разговор — там же про то, где он уверенно врёт.

Семь вопросов на входе

Вот те вопросы, ответы на которые и составляют карту проекта. Их семь, и они идут в таком порядке не случайно: каждый следующий опирается на предыдущий.

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

2. Куда приходит работа. Где та точка, с которой всё начинается: обработчик запроса, обработчик сообщения, запуск по расписанию, команда в консоли. От неё можно проследить путь до любого места, и наоборот — от любого места вверх до неё.

3. Где лежат данные. Какое хранилище, какие таблицы или коллекции главные, что в них уникально, что на что ссылается. Данные меняются медленнее кода, поэтому карта данных устаревает реже и служит дольше.

4. Чем это проверяется. Есть ли тесты, запускаются ли они, сколько идут, что именно покрывают. Проект с живыми тестами и проект с тестами, которые год как красные, — это два разных проекта с точки зрения того, как в них работать.

5. Как это попадает к людям. Что происходит между «правка готова» и «люди это видят»: ветка, ревью, сборка, выкладка, ручной шаг. Сколько времени занимает, кто нажимает кнопку, что бывает, когда что-то пошло не так.

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

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

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

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

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

Что поручать агенту, а что нет

Теперь про агента. Во входе в проект он полезен по-настоящему — но не там, где его обычно пробуют.

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

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

Отсюда правило, которое стоит принять как привычку: вопрос, ответ на который вы не можете проверить за минуту, задавать не стоит. «Где обработчик» — проверяется. «Как устроен проект» — не проверяется, потому что проверка и есть та самая работа, которую вы пытались обойти.

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

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

Первая правка как проверка карты

Карта собрана. Проверяется она не пересказом и не ощущением, а первой правкой — и правка эта выбирается особым образом.

Берите мелкую правку, которая проходит весь путь. Подпись на кнопке, поле в отчёте, строка в письме. Ценность не в самой правке — ценность в том, что вы пройдёте по всем слоям: найдёте место, поправите, запустите, прогоните тесты, оформите, отдадите на ревью, выложите.

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

Про размер первой правки: чем меньше, тем лучше, и это ровно противоположно инстинкту. Хочется показать себя и взять что-то содержательное. Но содержательная правка смешивает два вопроса: «правильно ли я понял проект» и «правильно ли я решил задачу», — и когда что-то не сходится, непонятно, какой из двух.

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

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

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

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