Правило остановки для AI-рефакторинга: задайте границы до того, как инструмент уйдёт вразнос

Почему AI-рефакторинг затягивается слишком надолго

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

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

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

Сами по себе эти изменения не обязательно плохие. Проблема в накоплении. Каждый дополнительный файл требует времени на ревью, повышает вероятность скрытой ошибки и усложняет откат, если позже в продакшене что-то пойдёт не так. Узкий коммит легко оценить. Широкий diff заставляет ревьюеров перечитывать всю историю просто чтобы понять, что на самом деле важно.

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

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

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

Что на самом деле делает правило остановки

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

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

Это защищает три вещи, которые команды теряют первыми при долгих рефакторингах: время на ревью, стабильность тестов и границы задачи. Исправлению на 40 строк и сюрпризу на 1200 строк не нужно одинаковое внимание. Как только ошибки начинают копиться, каждое новое изменение делает следующее ещё труднее оценить. А когда scope расползается, исходная задача тонет под кучей побочных дел.

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

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

Выберите сигналы до начала работы

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

Лучшие сигналы скучные и измеримые. Команды спорят меньше, когда правило говорит «остановиться после 12 файлов», а не «остановиться, если код кажется рискованным».

Начните с нескольких проверок, которые можно применять каждый раз:

• число файлов
• размер изменений
• количество падающих тестов после каждого раунда
• повторные переписывания последних правок самого инструмента
• обязательное ревью человеком для рискованных зон, таких как auth, billing, permissions или удаление данных

Точные цифры зависят от репозитория. В небольшом сервисе часто достаточно потолка в 8–12 файлов, 250–400 изменённых строк или более 2 новых падающих тестов. В большом кодовой базе лимиты могут быть выше, но потолок всё равно нужен.

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

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

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

Поставьте такие лимиты, с которыми команда сможет жить

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

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

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

Несколько практичных значений работают неплохо. Широкие рефакторинги могут останавливаться примерно на 5 файлах или 300 изменённых строках. Старым кодовым базам часто нужен лимит в 2–3 файла даже для небольших чисток. Срочные исправления в продакшене обычно должны укладываться в 1–2 файла и очень маленький diff. Общие библиотеки заслуживают такого же жёсткого лимита, потому что одно изменение может затронуть много команд. И если число падающих тестов растёт, а не уменьшается, остановитесь сразу.

Лимит на diff важнее, чем думают многие команды. Поставьте его на размер, который один ревьюер может прочитать за один заход без усталости. Для многих команд это значит что-то, что человек успевает разобрать за 20–30 минут, а не гигантский патч, который съедает полдня.

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

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

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

Проводите каждую сессию одинаково

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

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

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

Простой шаблон сессии вполне достаточен:

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

Цифры не обязаны быть идеальными. Они должны подходить вашей команде. Небольшая продуктовая команда может ограничить сессию 6 файлами, 300 изменёнными строками или любым новым падающим тестом. Большая команда с сильными тестами может разрешить 10 файлов, 600 изменённых строк или небольшое временное падение тестов в некритичной области.

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

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

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

Пример из спринта

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

Сначала патч выглядел аккуратно. Потом инструмент начал копать глубже. Он затронул 12 файлов вместо 4, которых ждала команда. Часть правок имела смысл. Часть — нет. Он переписал комментарии, поменял описания тестов и подправил хелперный код, который вообще не относился к переименованию.

Команда уже задала три лимита: остановиться, если инструмент редактирует больше 8 файлов, остановиться, если diff превышает 250 строк, и остановиться, если на первом запуске падает больше 1 теста.

Эти лимиты превратили неприятный момент в простое решение. После первого прогона тестов упали два теста. Само переименование было корректным. Ошибки появились из-за лишних правок в тестовых хелперах и переписанного mock-объекта, который изменил поведение тестов.

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

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

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

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

Ошибки, из-за которых правила остановки не работают

Правило остановки проваливается, когда команда относится к нему как к бумажке для галочки. Инструмент продолжает править код, diff растёт, а никто его не останавливает, потому что лимиты были настолько мягкие, что по-настоящему сработать им было почти невозможно.

Первая ошибка — задавать числа, которые звучат безопасно, но при этом сильно выше обычной работы. Если большинство аккуратных рефакторингов затрагивают 6–10 файлов, лимит в 40 файлов не защитит вас. То же самое касается размера diff. Лимит должен казаться немного строгим, а не вежливым.

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

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

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

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

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

Правило остановки работает только тогда, когда оно останавливает работу, которую людям особенно хочется оправдать.

Проверки перед тем, как разрешить ещё один проход

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

Сначала смотрите на время ревью. Один человек должен суметь прочитать весь diff за короткий проход и объяснить, почему изменился каждый файл. Если на маленькую задачу это уходит 20 минут, инструмент уже ушёл в сторону.

Потом проверьте scope и последствия. Спросите себя, всё ещё ли diff соответствует исходной задаче. Исправление одного API-обработчика не должно расползаться в конфиг, логирование или стили, если причина не очевидна. Посмотрите на упавшие тесты и сопоставьте их с предполагаемым изменением. Если обновление формы ломает billing или auth, инструмент залез не туда. Сканируйте и на несвязанные правки. Переименования, churn из-за форматирования, сгенерированные файлы и неожиданные изменения зависимостей часто прячут риск.

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

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

Представьте рефакторинг одного checkout-validator. Если инструмент меняет 6 файлов, один тест падает именно в этом валидаторе, а откат остаётся простым, ещё один проход может быть нормальным. Если та же задача превращается в 24 изменённых файла, шум в snapshot-тестах и сбои в account settings, остановите это сразу.

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

Что делать, когда сессия остановилась

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

Правило остановки полезно только тогда, когда остановка создаёт чистую передачу. Попросите короткое summary перед тем, как закрыть сессию: какие файлы изменились, что инструмент пытался улучшить, какие тесты упали и что всё ещё выглядит рискованным или неясным.

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

Одно простое правило экономит много боли: никогда не перезапускайте с того же широкого запроса, который уже упёрся в стоп-условие. Ужмите scope, назовите файлы и укажите ожидаемый результат.

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

Если ваша команда постоянно сталкивается с одними и теми же проблемами в AI-кодинге, внешняя помощь может быть полезна. Работа Oleg Sotnikov на oleg.is сосредоточена на Fractional CTO поддержке, советах для стартапов, AI-first рабочих процессах разработки и практических guardrails для небольших и средних команд. Такой разбор особенно полезен, когда можно показать реальные diff, реальные падения тестов и реальные стоп-точки вместо расплывчатых опасений.