Рефакторинг легаси-кода — одна из задач, где агенты реально работают, но не все задачи одинаковы. Механические замены по базе — да, агент справляется за вечер. Архитектурные решения о том, какой интерфейс спрятать за абстракцией — нет, это по-прежнему работа человека. В этой статье — три конкретных паттерна рефакторинга с реальными цифрами, матрица «что агент делает хорошо / плохо» и пошаговый процесс, который экономит время и не ломает продакшен.
Если вы впервые сталкиваетесь с агентным кодингом — сначала стоит прочитать статью «Что такое агентный кодинг». Для большого масштаба (15-летний легаси на миллион строк) — разбор пайплайна planner→coding→reviewer в кейсе переписывания легаси с ИИ-агентами.
Три паттерна, которые реально работают
Паттерн 1: миграция Python 2 → 3
Python 2 ушёл с 31 декабря 2020 года, но legacy-проекты на нём до сих пор живут. Автоматический конвертер 2to3 справляется с базовым синтаксисом, но оставляет десятки вещей без внимания: print без скобок, unicode/str строки, has_key(), iteritems() → items(), модуль ConfigParser → configparser, commands.getoutput() → subprocess, разные семантики деления (/ vs //).
Агентный подход: дать агенту список правил и попросить проверить каждый файл в проекте. Не «переписать весь проект за один промпт» — а модуль за модулем, с запуском тестов после каждого.
Промпт, который работает:
Прочитай файл services/parser.py. Он написан на Python 2.
Найди и замени все использования Python 2-паттернов на Python 3:
- print → print()
- except Exception, e → except Exception as e
- unicode → str
- has_key() → in
- iteritems() → items()
- codecs.open → open
После правок запусти pytest tests/test_parser.py.
Не меняй логику — только синтаксис.
Что делает агент хорошо:
— Поиск и замена конкретных паттернов в десятках файлов;
— Исправление imports (urllib2 → urllib.request);
— Запуск тестов и исправление ошибок компиляции.
Что не делает:
— Не понимает, где str / bytes логика изменилась семантически;
— Не предсказывает, что print(x, file=sys.stderr) в Python 2 — это два аргумента, а в Python 3 — print(x, file=sys.stderr), и поведение зависит от запятой;
— Не разбирается в serialized data (pickle 2 vs 3 несовместимы).
Практический совет: прогоняйте pyupgrade перед агентом. Автоматические линтеры закрывают 60–70% мелких правок. Агент нужен для оставшихся 30% — семантически сложных замен, где print("hello", "world") означает разное в разных версиях.
Реальный кейс: инженер sannysanoff описал на Hacker News (март 2026) рефакторинг legacy Java-проекта с помощью LLM — конвертацию из строкового CSV в column-oriented формат ClickHouse с loop fusion. Результат — ускорение в 20 раз. Ключевой вывод: агенты работают на проверяемых трансформациях (формат данных, структура памяти), но не на архитектурных решениях (какую БД выбрать, когда отказаться от клише).
Паттерн 2: выделение модулей из монолита
Файл разросся до 2000 строк — понятно, что его надо разбить, но руки не доходят. Агент идеально подходит для этой задачи, потому что разбиение модуля — это проверяемая операция: после рефакторинга тесты должны пройти, а импорты — собраться.
Промпт, который работает:
Файл src/services/order_service.py — 2000 строк, содержит:
- обработку заказов
- работу с платёжной системой
- email-уведомления
- отчётность для бухгалтерии
Разбей на модули по ответственности:
- order_processing.py
- payment_handler.py
- notification_service.py
- reporting.py
Сохрани все публичные функции с теми же сигнатурами.
Добавь __init__.py с re-export'ами для обратной совместимости.
Запусти pytest и mypy.
Что делает агент хорошо:
— Находит группы связанных функций по паттернам вызовов;
— Создаёт модули с правильными импортами;
— Добавляет re-export’ы в __init__.py для обратной совместимости;
— Проверяет, что тесты проходят после каждого шага.
Что не делает:
— Не принимает решение о границах модулей (вы решаете, какие группы функций куда);
— Не предсказывает, какие внешние сервисы зависят от конкретных путей импортов;
— Может сломать lazy imports или циклические зависимости.
Пример из практики: Mitchell Hashimoto (создатель Terraform) описал 16 агентных сессий при рефакторинге Ghostty (октябрь 2025). Основная работа — реорганизация view-слоя: теговые объединения, разбиение монолитного UpdatePopoverView на отдельные fileprivate-классы, переименование типов, перемещение кода между файлами. Итог:21 файл, $15.98 токенов,8 часов времени. Но архитектурное решение — как разбить интерфейс и какие типы выделить — Hashimoto принял сам.
I had to step away and let the AI churn for 10-15 minutes at a time while I did other things.
«Мне приходилось отходить и давать ИИ поработать по 10–15 минут, пока я занимался другими делами.»
Паттерн 3: переименование API
Переименование четырёх продуктов в 695 файлах документации за 3 дня — кейс техрайтера Márcio Florindo из enterprise-компании (dev.to, 03.08.2026). Флориндо не программист — он собрал инструментарий, разговаривая с агентом.
Почему простой find-replace не работает:
Имя продукта встречается в десятках структур — YAML-файлах, frontmatter, URL-пути, redirect-правилах, MDX-пропсах, SVG-иконках и скриншотах. При этом API-поля, CLI-команды и исторические записи changelog менять нельзя. «Заменить всё» превращает рабочую документацию в сломанную.
Как Флориндо решил задачу:
| Инструмент | Что делает |
|---|---|
| Rename-агент | Двухпроходное переименование: сначала файлы продукта, потом перекрёстные ссылки. Safe-листы (то, что похоже на старое имя, но трогать нельзя). |
| Validator | 16 автоматических проверок: сломанные ссылки, пропущенные redirects, невалидные ID в frontmatter. |
| Image scanner | Vision-модель проверяет скриншоты на устаревшие имена. Все 113 SVG-диаграмм содержали имена «впаянными» в векторные данные — grep их не находил. |
| Redirect validator | Детерминированная Python-утилита без ИИ: проверяет 349 URL-маппингов. |
Ключевой вывод Флориндо — каждая ошибка превращалась в правило:
Each mistake became a rule. Each conversation refined the tool.
«Каждая ошибка становилась правилом. Каждый разговор оттачивал инструмент.»
Негативный пример: разработчик tlonny описал на Hacker News неудачную попытку переименовать API-сигнатуру в TypeScript-проекте. Агент начал хорошо, но через~5 файлов пошёл не по плану: переставлял ключи в объектах, менял несвязанные логи и добавлял неверные аргументы. Даже прямо запрет «STOP GOING OFF TASK» не помог. Все изменения пришлось откатить.
Вывод: переименование API по базе (документация, публичные имена, конфиги) — это зона агента. Переименование API в коде (сигнатуры функций, типы, аргументы) — требует отдельного подхода: валидация после каждого файла, запрет на промежуточные коммиты, проверка типов между шагами.
Что работает, а что нет: матрица решений
Simon Willison в своём руководстве по агентным паттернам прямо перечисляет задачи, где агенты работают идеально (Agentic Engineering Patterns, март 2026):
Refactoring tasks like this are an ideal application of coding agents. Fire up an agent, tell it what to change and leave it to churn away in a branch or worktree somewhere in the background.
«Задачи на рефакторинг — идеальное применение coding-агентов. Запустите агента, скажите, что изменить, и позвольте ему работать в ветке или worktree где-то на фоне.»
Он выделяет четыре категории:
— API-дизайн, требующий изменений в десятках мест — переименование, изменение сигнатур;
— Чистка номенклатуры — когда Early-stage решение по именам оказалось неудачным;
— Объединение дублирующегося кода — когда похожая логика размазана по модулям;
— Разбиение огромных файлов на модули — файл вырос до тысяч строк.
Ключевое ограничение: агенты не принимают решения, а выполняют проверяемые трансформации. Вы решаете «что», агент делает «как».
Пять шагов рефакторинга с агентом
Шаг 1: зондирование
Задача агента — прочитать кодовую базу и найти все точки, где встречается нужный паттерн. Без правок — только список файлов и строк. Это отдельная сессия или отдельный промпт.
Зачем: агент может пропустить файлы, если дать ему и зондирование, и правки в одном промпте. Разделив задачи, вы получаете точную карту изменений до начала работы.
Шаг 2: план
Агент предлагает план: какие файлы тронет, в каком порядке, какие тесты напишет. Вы утверждаете или правите. Для мелких задач (поменять print на logger) план избыточен. Для выделения модуля или миграции — обязателен.
Шаг 3: реализация
Агент правит файлы по утверждённому плану. Разбивайте на ветки по модулям — каждая ветка = один PR. Не пытайтесь рефакторить 200 файлов в одной сессии: контекст «плывёт», агент начинает забывать ранние инструкции.
Шаг 4: проверка
Тесты + линтер + типизация. Без прохождения всех проверок мерж запрещён. Это не пожелание — это правило: если агент не запустил проверки, он не знает, что сломал.
Шаг 5: ревью второй моделью
Codex проверяет код, написанный Claude (или наоборот). Это самый дорогой шаг — включайте его только на рискованных изменениях.
Реальный случай: Саймон Уиллисон использовал Claude Fable для ревью sqlite-utils перед релизом, а затем GPT-5.5 нашёл два дополнительных бага уровня P1. Итог —$149,25 за сессию, которая предотвратила выход бага с потерей данных.
I used to think that the idea of having one model review the work of another was somewhat absurd. The problem is it really does work.
«Раньше я считал, что идея ревью одной модели другой — абсурд. Проблема в том, что это реально работает.»
Когда рефакторинг агентами оправдан
Да, оправдан, если:
— задача проверяема: есть тесты, есть линтер, есть явные критерии «работает / не работает»;
— масштаб средний: десятки файлов, а не тысячи — или тысячи файлов, но с чётким паттерном замены;
— есть изоляция: отдельная ветка, отдельное окружение;
— кто-то ревьюит результат: агент не заменяет code review.
Нет, не оправдан, если:
— задача требует архитектурного решения (какую БД, какой паттерн, какую стратегию отката);
— рефакторинг затрагивает бизнес-логику (новые правила расчётов, изменения в предметной области);
— нет тестов и нет возможности их написать до начала изменений;
— рефакторинг затрагивает инфраструктуру (миграции БД, конфигурации деплоя, переменные окружения).
В кейсе thegreatkahuna (1М строк C#/React, HN 49045271) агентный пайплайн planner→coding→reviewer работал именно потому, что были:
— PRD и архитектурный документ как ограничители;
— отдельная ветка и отдельная БД;
— человек, который ежедневно прогонял end-to-end и решал эскалации.
Без этих трёх условий агентный рефакторинг превращается в дорогостоящий generate-and-hope.
Российские реалии
Инструменты из кейсов (Claude Code, Codex, Cursor) доступны из России с оговорками:
- Установка Claude Code, Codex CLI и Cursor работает штатно — GitHub, npm и Homebrew не блокированы;
- Вход: OpenAI ограничила доступ с российских IP с декабря 2022 года (подробности на Habr); Claude Code аналогично требует зарубежную точку входа;
- Оплата: российские Visa/Mastercard и Mir не принимаются. Рабочие схемы — виртуальные зарубежные карты или посредники (детали — в статье на Habr);
- Стоимость: задача рефакторинга на 1000 файлов — это тысячи токенов. Разбивайте на сессии: одна сессия = один модуль = одна ветка. Траты управляемы, если задача изолирована;
- Локальная альтернатива: Codex CLI и Claude Code можно переключить на российский инференс через API Яндекса (обзор на Habr).
Прямых кейсов «рефакторинг легаси агентами» в рунете пока немного — тема свежая. Механика пайплайна (зондирование → план → правки → тесты → ревью) от страны не зависит и работает с любым провайдером.
Дальнейшие чтения
- Большой масштаб: Переписываем 15-летний легаси-проект с ИИ-агентами: 1М строк C#/React — пайплайн planner→coding→reviewer, ревью второй моделью, грабли и 4-недельный срок.
- Ревью перед релизом: тот же кейс sqlite-utils 4.0 — агент нашёл data-loss баг, который автор не встретил за десятилетие работы.
- Артефакты для агентов: AGENTS.md — файл конвенций, который ограничивает поведение агента и экономит время на ревью.
- Обзор инструментов: Что такое агентный кодинг — отличия агента от чат-бота и автодополнения, обзор Claude Code, Codex, Gemini CLI, OpenCode.
