Cleanup Fridays для AI-репозиториев с меньшим дрейфом

Почему AI-репозитории быстро расползаются

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

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

Работа через prompts тоже быстро меняет форму. Хелпер, который казался полезным во вторник, к четвергу может стать лишним, потому что изменился prompt, поменялась модель или workflow переехал в другой скрипт. Люди редко удаляют такие хвосты сразу. Они оставляют их «на всякий случай», и репозиторий тяжелеет, не становясь лучше.

Дублирование появляется так же незаметно. Кто-то копирует parser, formatter или retry-wrapper в новую папку, потому что так быстрее, чем искать старую версию. Потом кто-то ещё делает то же самое в другой части репозитория. В итоге одна и та же логика живёт в трёх местах, и в каждом — с маленькими правками. Так баги и начинают казаться случайными.

Названия тоже расползаются. Файл temp_runner вдруг становится частью реального workflow. Папка new_pipeline живёт уже полгода. На вывеске одно, в коде другое, и каждый новый teammate платит за эту путаницу.

Команды, которые строят работу с AI-инструментами, сталкиваются с этим ещё сильнее, потому что они создают больше кода, черновиков и почти удачных попыток за меньшее время. Oleg Sotnikov писал про AI-first development как про преимущество в скорости, и это действительно так. Но быстрый output тоже требует регулярной обрезки. Без неё репозиторий перестаёт ощущаться как система и начинает напоминать ящик с хламом, откуда старые идеи никак не уходят.

Выберите небольшой объём уборки

Еженедельная уборка работает только тогда, когда она остаётся маленькой. Cleanup Fridays для AI-репозиториев разваливаются, если команда пытается исправить всё сразу.

Ограничьте проход 30 минутами. Такое ограничение не даёт сессии превратиться в переписывание всего подряд и облегчает повторение привычки на следующей неделе.

Начинайте с файлов из активной работы. Свежие изменения ещё легко читать, и люди, которые их трогали, помнят, зачем они нужны. Если команда всю неделю правит agent prompts, API-обёртки или тестовые хелперы, сначала разбирайте именно эти файлы.

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

Короткий проход обычно выглядит так:

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

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

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

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

Проведите 30 минут на Cleanup Friday

Выберите один короткий слот в конце недели и относитесь к нему как к гигиене репозитория, а не как к спринту по refactor-у. Cleanup Fridays для AI-репозиториев работают потому, что они маленькие. Тридцати минут достаточно, чтобы уменьшить дрейф, но этого мало, чтобы кто-то превратил всё в отдельный проект.

Начните с папок, которые команда трогала на этой неделе. Не просматривайте весь репозиторий. AI-assisted работа создаёт много быстрого output, и большая часть беспорядка сидит рядом с недавними изменениями. Если трое людей работали с agents/, prompts/ и utils/, откройте сначала их и остальное пока не трогайте.

Простой проход обычно выглядит так:

• Сначала переименуйте самые неудачные файлы, особенно tmp_final_v2, new-flow или helper-old.
• Проверьте хелперы, которые подозрительно тихие, и удалите те, у которых нет живых вызовов.
• Найдите один повторяющийся паттерн, который встретился два или три раза на этой неделе, и сведите его к одному ясному пути.
• Оставьте короткую заметку в командном чате или трекере о том, что изменилось.

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

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

Переименуйте файлы так, чтобы было понятно, чем они занимаются

AI-репозитории очень быстро собирают вокруг себя туманные названия. Модель пишет хелпер, потом кто-то вручную его допиливает, и файл остаётся под именем temp2.ts, newFlow.py или finalFinal.jsx. Через месяц никто уже не помнит, что он делает, к какой функции относится и безопасно ли к нему прикасаться.

Хорошее имя файла отвечает на один простой вопрос: чем этот файл занимается? Если он обрабатывает экспорт счетов, назовите его invoice-export.ts. Если он рендерит настройки биллинга, назовите его billing-settings.tsx. Люди сначала читают дерево файлов, а уже потом код, так что имя должно брать на себя часть работы.

Ориентируйтесь на функцию, а не на момент создания файла. Разница хорошо видна:

• temp2.py -> lead-scoring.py
• finalFinal.ts -> customer-import.ts
• helper_new.go -> retry-policy.go
• test_copy.spec.ts -> customer-import.spec.ts

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

Связывайте файл с функцией, которую он поддерживает, а не с расплывчатой технической категорией. auth-token-refresh.ts понятнее, чем utils.ts. checkout-discounts.rb рассказывает о содержимом лучше, чем service_helper.rb. Идеальные названия не нужны. Нужны названия, которые помогают следующему человеку угадать правильно.

Переименовывайте связанные тестовые файлы в тот же проход. Если customer-import.ts меняет имя, его spec или test-файл тоже должен поменяться. Иначе репозиторий начинает раскалываться на две версии одной и той же идеи: одна в production-коде, другая в тестах. Эта путаница потом расползается в imports, результаты поиска и провалившуюся уборку.

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

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

AI-репозитории быстро собирают мелкие хвосты. Хелпер решает одну prompt-экспериментальную задачу, одну миграцию или один поспешный багфикс, а потом больше к нему никто не прикасается. Если таких хвостов оставить достаточно много, люди перестают доверять именам файлов и функциям.

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

Есть простое правило: если wrapper только переименовывает другую функцию, скорее всего, ему пора уйти. Когда run_customer_summary() делает не больше, чем вызывает generate_summary(), дополнительное имя добавляет ещё одно место для чтения и ещё одно место, которое можно забыть. Оставьте более понятное имя функции, обновите вызывающие места и удалите wrapper.

Старые варианты prompts — ещё одна частая куча. Команды часто хранят файлы вроде prompt_v2.txt, prompt_v2_final.txt и prompt_v2_final_really_final.txt намного дольше, чем код ими пользуется. Если ни один скрипт их не загружает, ни один тест их не проверяет и никто не собирается снова сравнивать результаты, убирайте их из репозитория.

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

Перед удалением используйте короткую проверку:

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

Одна небольшая команда, с которой я работал, держала шесть prompt-файлов для одного и того же support reply flow и три хелпер-функции вокруг одного API-вызова. Они оставили один prompt, который использовался в production, удалили заброшенные варианты и убрали две обёртки. Следующий человек тратил меньше времени на догадки и примерно на 15 минут меньше на каждое изменение.

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

Сведите повторяющиеся паттерны к одному простому пути

Во время Cleanup Fridays для AI-репозиториев повторяющиеся паттерны часто проще всего исправить. AI-код любит копировать сам себя: один prompt runner для summaries, другой для tags, третий для drafts — и у всех немного разные retries, logging и очистка output.

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

Каждый раз проверяйте одни и те же вещи:

• как каждый поток формирует input перед вызовом модели
• где находятся retries и timeouts
• как каждый из них разбирает output модели
• какое logging или error handling люди скопировали и подправили

Оставляйте ту версию, которую уставший teammate прочитает быстрее всего. Простое лучше хитрого. Если в одном файле одна хелпер-функция и шесть маленьких callback-ов, а в другом та же работа делается в 25 прямых строках, оставляйте прямой вариант.

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

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

Останавливайтесь после одного паттерна. Если за один 30-минутный проход вы попытаетесь объединить prompt builder-ы, фоновые задачи и тестовые хелперы, вы проведёте остаток пятницы, распутывая побочные эффекты. Один паттерн, один чистый путь, один маленький commit.

Простой пример из небольшой команды

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

К пятнице репозиторий всё ещё работает, но никто не видит его ясно. Во время короткого Cleanup Fridays для AI-репозиториев команда замечает простую вещь: две папки почти одинаково обрабатывают review flow. Одна папка оценивает output модели для внутренних проверок. Другая делает почти то же самое для regression-тестов, только с немного другими именами файлов и одним дополнительным хелпером.

Они перестают поддерживать оба пути и выбирают один. Команда оставляет более чистую папку, переносит туда общую логику и переименовывает файлы так, чтобы назначение было понятно с первого взгляда. Вместо названий вроде check_final.py и review_new.ts они используют review_runner.ts, review_prompt.md и review_cases.json.

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

Уборка занимает около 30 минут:

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

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

Ошибки, которые зря съедают время уборки

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

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

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

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

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

• останавливайтесь, когда уборка превращается в redesign
• переименовывайте файлы только вместе с правками imports в том же изменении
• проверяйте использование, прежде чем что-то удалять
• объединяйте дублирование только после сравнения edge cases
• оставляйте короткую заметку о том, зачем была сделана правка

Последний пункт важнее, чем кажется. Когда вы удаляете хелпер или сводите два паттерна в один, добавьте короткую заметку в commit message или командный чат. Фраза вроде «объединили два JSON parser-а, потому что теперь оба используют одни и те же правила валидации» экономит следующему человеку время на догадки. Без такой заметки репозиторий может выглядеть чище, но команда всё равно теряет время.

Быстрые проверки перед тем, как закончить пятницу

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

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

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

Потом прочитайте diff так, будто вы его не писали. Ищите случайные правки, debug-логи, шум форматирования или сгенерированные изменения, смешанные с реальной уборкой. Если вы собирались тронуть четыре файла, а diff показывает двадцать, сократите его прямо сейчас.

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

Оставьте короткую заметку на понедельник. Пишите просто: что переименовали, что удалили, какие тесты запускали и что ещё требует второго взгляда. В Cleanup Fridays для AI-репозиториев эта маленькая привычка важнее, чем кажется. Записка вроде «переименовали prompt_utils в prompt_formatting, удалили два неиспользуемых хелпера, прогнали parser-тесты, проверьте admin import в понедельник» экономит реальное время и убирает повторную работу.

После четырёх пятниц задайте несколько правил

К четвёртому проходу Cleanup Fridays для AI-репозиториев должны перестать ощущаться как случайная уборка. У вас уже достаточно данных, чтобы увидеть, что возвращается снова и снова. Может быть, люди всё время добавляют расплывчатые имена вроде utils2, может быть, старые prompt-хелперы копятся, а может быть, одна и та же логика появляется в трёх папках с небольшими изменениями.

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

Обычно хорошее начало — вот такое короткое правило:

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

Эти правила работают, потому что их легко запомнить. Люди следуют простым правилам. Длинные документы они игнорируют.

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

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

У некоторых команд дрейф всё равно продолжается, потому что сама структура репозитория провоцирует захламление. Папки могут быть устроены неудачно, сгенерированный код может смешиваться с написанным вручную, или AI-output может попадать в слишком много мест. Если это происходит снова и снова, внешний взгляд может сэкономить время. Oleg Sotnikov может посмотреть на setup как Fractional CTO и помочь вашей команде выстроить простую уборку, которая подходит тому, как вы реально работаете, а не абстрактному процессу, который никто не соблюдает.