Измерьте, где репозиторий тормозит, до запуска пилота ассистента для программирования

Почему пилоты быстро буксуют

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

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

Большие файлы делают всё только хуже. Модуль на 2000 строк, где смешано всё подряд, сваливает слишком много путаного контекста в одно место. Вместо одной аккуратной правки ассистент может задеть не тот участок, пропустить локальное правило или предложить изменение, которое сломает что-то рядом. Команды часто винят инструмент, но путаницу создал сам репозиторий.

Простой пример хорошо показывает проблему. Новый инженер приходит в пилот и должен изменить одно правило валидации. Локальная настройка занимает три часа. На поиск правильной команды теста уходит ещё двадцать минут. Разобраться в модуле удаётся почти за час, потому что бизнес-логика, вспомогательные функции и вызовы API живут в одном файле. Если потом ассистент выдаёт посредственный ответ, люди говорят, что пилот провалился. На самом деле репозиторий сжёг большую часть времени ещё до того, как ассистент получил реальный шанс помочь.

Измерьте трение в репозитории до того, как судить о инструменте. Чистый репозиторий для пилота проверяет ассистента. Мусорный репозиторий в основном проверяет ваше терпение к настройке.

Как выглядит трение в репозитории

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

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

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

Тесты показывают ту же проблему. Здоровый упавший тест подсказывает, где сломалось поведение. Репозиторий с высоким трением выдаёт расплывчатый stack trace, падает во вспомогательной функции далеко от настоящей ошибки или требует специальных локальных данных, которые есть только у одного человека. Ассистент может прочитать ошибку, но ему всё равно не хватает недостающего контекста.

Небольшой пример из стартапа это хорошо иллюстрирует. Новый инженер пытается переименовать одно поле для биллинга. Настройка занимает 90 минут, приложение запускается только после того, как находят скрытый скрипт, правка задевает четыре папки, а падающий тест говорит не больше чем «ожидали 200, получили 500». Такой репозиторий не готов к широкому пилоту.

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

Что измерять в первую очередь

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

Время — самый понятный сигнал. Засеките, сколько минут проходит от клонирования до первого успешного запуска приложения, а потом сделайте то же самое для первого успешного прогона тестов. Если у одного человека это занимает 12 минут, а у другого 55, репозиторий уже многое вам сказал.

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

Для первой оценки достаточно пяти проверок:

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

Размер модуля важен, потому что ассистенты лучше работают, когда задача помещается в читаемый кусок кода. Файл на 300 строк с одной понятной задачей проще использовать, чем модуль на 4000 строк, где всё смешано и завязано друг на друга.

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

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

Проверьте время локальной настройки

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

Используйте чистый ноутбук, свежую виртуальную машину или пустое рабочее пространство. Старые пакеты, закешированные учётные данные и оставшиеся env-файлы скрывают проблемы. Вам нужен первый реальный опыт запуска, а не удачный.

Пока настраиваете проект, записывайте каждый шаг. Это включает установку пакетов, версии SDK, секреты, команды shell, создание тестовых данных для базы и каждую переменную окружения, которую пришлось угадывать или спрашивать. Мелкие пропуски быстро накапливаются.

Ведите короткий лог по ходу работы:

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

Разница между документацией и реальностью важнее, чем многие думают. Если в README написано «запустите одну команду», а на деле нужно установить ещё два инструмента, отредактировать конфиг и попросить доступ у ops, документация неверна. Это и есть трение, и ассистенты тоже упрётся в него.

Короткий пример это хорошо показывает. Разработчик открывает репозиторий в 9:00. Приложение наконец запускается в 10:10, но тесты не идут до 11:00, потому что одному приватному пакету нужен токен, который никто не задокументировал. Для старта пилота это слабое место. Ассистент может помочь с кодом, но он не исправит отсутствующий доступ или командную память.

Команды, которые сначала приводят в порядок настройку, обычно быстро получают первые результаты. Убрать лишние локальные сервисы, сделать документацию точнее и упростить первый запуск теста может сэкономить 30–60 минут на каждого нового инженера. Одного этого уже достаточно, чтобы пилот казался полезным, а не раздражающим.

Найдите точки входа в тесты

Ассистент для программирования особенно полезен, когда обратная связь приходит быстро. Если человек не может за несколько минут найти самый маленький полезный тест, пилот начинается не с прогресса, а с угадывания.

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

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

Ищите короткий путь после одной маленькой правки кода. Если разработчик изменил один вспомогательный метод, он должен быстро запустить только связанные тесты и получить результат. Именно в таком коротком цикле пилот чаще всего показывает настоящую ценность.

Хорошо работает быстрая проверка:

• Могут ли оба человека найти одну и ту же команду теста без помощи?
• Могут ли они запустить тесты для одного файла, пакета или модуля?
• Достаточно ли этот путь быстрый для обычной работы в редакторе?
• Совпадает ли документация с реально работающей командой?
• Требует ли каждое маленькое изменение полного набора тестов?

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

Если вы нашли хотя бы один чистый короткий путь к тестам, начинайте пилот там. Если нет, сначала исправьте именно этот путь. Репозиторий с понятной точкой входа в тесты даёт людям честную проверку ассистента, а не проверку их терпения.

Оцените размер модулей

Большие модули тормозят людей ещё до того, как к коду прикоснётся любой ассистент. Кроме того, они делают пилотные области плохим выбором, потому что в них трудно понять, помог ли инструмент или код просто сопротивлялся изменениям.

Начните с простого порога для «слишком большого» файла. Это число зависит от команды, но большинство людей чувствуют проблему задолго до 1000 строк. Файл на 700 строк, где смешаны вызовы API, бизнес-правила и логика интерфейса, уже трудно читать, трудно тестировать и опасно менять с помощью ассистента.

Быстрый просмотр обычно даёт достаточно информации:

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

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

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

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

Оцените один репозиторий за одно утро

Выберите одну реальную задачу, которая часто встречается. Лучше всего работает небольшое изменение: обновить подпись, поправить правило валидации или слегка изменить одно бизнес-условие. Если задача слишком большая, ваша оценка скажет больше о планировании, чем о трении в репозитории.

Если можете, запустите задачу с нуля. Используйте ноутбук, на котором ещё не настроены все инструменты, кэши и секреты. Так вы получите более честную базу до старта пилота.

Отслеживайте четыре момента с помощью таймера:

• Настройка локальной среды завершена
• Приложение или сервис запустились впервые
• Связанный тест запустился впервые
• Первая правка кода была внесена и сработала

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

Записывайте одно короткое предложение каждый раз, когда что-то тормозит. «Нет названия env-файла». «Три команды тестов, и ни одна не очевидна». «Сборка идёт 14 минут ради одной строчки изменения». Эти заметки важнее аккуратной таблицы, потому что они показывают, почему репозиторий неудобен.

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

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

Пример простого выбора пилота

Небольшая команда хочет сравнить два репозитория перед запуском пилота. Оба важны для бизнеса, но только один даёт честную первую проверку.

Репозиторий A запускается примерно за 15 минут на новом ноутбуке. Заметки по настройке короткие, приложение стартует без догадок, а команды тестов легко найти. Большинство файлов остаются примерно по 300 строк, поэтому разработчик может прочитать файл, понять его и проверить совет ассистента, не теряясь.

Репозиторий B выглядит важнее, поэтому команду тянет начать именно с него. Обычно это ошибка. Чистый старт занимает полдня, один старший инженер должен объяснять порядок команд, а несколько тестов имеют смысл только если вы уже знаете кодовую базу. Некоторые файлы близки к 2000 строк. Ассистент всё ещё может помочь, но команда потратит больше времени на борьбу с репозиторием, чем на оценку пилота.

Репозиторий A — лучший первый выбор, потому что он даёт команде чистые сигналы. Если ассистент экономит 20 минут на одной правке, это легко увидеть. Если он пишет слабый тест, проблему тоже можно быстро заметить. Если рабочий процесс ломается, команда понимает, что проблема в процессе пилота, а не в грязной настройке.

Репозиторий B должен подождать. Сначала сократите настройку, запишите точки входа в тесты и разбейте слишком большие файлы на более мелкие части. Потом запустите там тот же пилот и сравните результаты.

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

Ошибки, которые искажают оценку

Большинство плохих оценок появляется из-за скрытой привычности. Репозиторий может казаться простым, если человек, который его проверяет, уже знает каждый скрипт, каждую папку и каждую мелкую правку, которая так и не попала в документацию.

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

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

Некоторые ошибки повторяются снова и снова:

• Выбирать самый запутанный участок, потому что он кажется серьёзным или важным
• Тестировать на ноутбуке, где уже есть старые SDK, закешированные секреты или глобальные инструменты
• Считать один удачный запуск базовой линией, хотя второй уже падает
• Игнорировать время, потраченное на поиск правильных точек входа в тесты
• Позволять командным знаниям закрывать пробелы, с которыми столкнётся новый участник

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

Выбор модуля тоже может исказить оценку. Команды часто берут самую большую или самую сложную часть репозитория, потому что кажется, будто там максимальная отдача. Обычно это неправильная отправная точка. Выберите область с понятными входами, небольшими файлами и тестами, которые реально можно запустить.

Быстрая проверка перед стартом

Перед тем как что-то оценивать, дайте репозиторий человеку, который не трогал его несколько недель. Попросите его сделать маленькую обычную задачу, а сами смотрите, где он останавливается, начинает гадать или открывает чат, чтобы попросить помощи. Эти паузы говорят больше, чем длинное обсуждение в команде.

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

• Может ли новый человек поднять приложение с нуля по текущим документам и командам?
• Может ли он запустить один узкий тест, а не весь набор, за минуту или две?
• Может ли он изменить один файл для небольшой задачи без цепной реакции по половине кодовой базы?
• Всё ещё ли заметки по настройке совпадают с тем, что репозиторий реально ожидает сегодня?
• Вы уже выбрали один модуль для первой попытки или всё ещё говорите обо всём продукте сразу?

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

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

Что делать дальше

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

Сделайте пилот маленьким. Выберите одну область репозитория, один рабочий поток и один тип изменений. Хорошее начало — небольшая ошибка в модуле среднего размера или задача на чистку кода с понятными тестами. Миграции, общий auth-код и логика биллинга могут подождать, пока команда не увидит стабильные результаты.

Используйте одни и те же две пробные задачи для каждого ассистента, который вы тестируете:

• Небольшая правка ошибки с очевидным ожидаемым результатом
• Небольшая задача на чистку, например убрать дублирование или разделить слишком выросший файл

Потом сравнивайте не только diff. Измеряйте и всю работу вокруг него. Отмечайте, сколько времени заняла настройка, как часто ассистент выбирал не тот файл, находил ли он правильные тесты и сколько времени на ревью требовало изменение. Десять минут экономии во время кодинга могут исчезнуть в двадцати минутах доработок.

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

Если вам нужен внешний взгляд перед более широким запуском пилота, Oleg Sotnikov на oleg.is работает как fractional CTO и startup advisor и может помочь оценить проблемы с настройкой, пути тестов и архитектурные проблемы, которые исказят результаты. Короткий разбор часто дешевле, чем месяц пилота не в том репозитории.