Code Modernization — плагин Claude Code для модернизации старого кода с доказательством результата

Code Modernization — это плагин для Claude Code, который берёт старый код и доводит его до нового состояния по шагам. Он даёт четыре вещи: разбор того, что это за система и что она делает; план, который вы утверждаете; переписанный код; и доказательство, что новое поведение совпадает со старым.

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

Установка

Нужен Claude Code. Дальше одна команда:

/plugin install code-modernization@claude-plugins-official

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

С чего начать

Откройте папку под работу и введите /code-modernization:modernize. Плагин задаст несколько коротких вопросов о том, что вы хотите сделать с кодом. Потом он найдёт сам код, запишет ваши ответы один раз, покажет маршрут и даст точную первую команду. Все следующие команды читают то, что вы уже ответили, поэтому повторных вопросов не будет.

Если вы пока не понимаете, что хотите делать, выберите режим «сначала разобраться». Тогда вы получите оценку, карту, бизнес-правила и план — и ни строчки кода переписано не будет.

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

/code-modernization:modernize-preflight <name> --source <path to your code>
/code-modernization:modernize-status <name>

<name> — короткая метка на ваше усмотрение: буквы, цифры, дефис и подчёркивание. Флаг --source создаёт ссылку legacy/<name> и ничего не копирует, поэтому огромное хранилище остаётся на месте.

Важное правило: команды ничего не меняют в исходниках. Они пишут только в analysis/<name>/ и modernized/. Каждое обновление пересобирает analysis/<name>/REPORT.html — одну страницу со всем, что найдено на этот момент. Её можно открыть или передать коллегам. Часть шагов требует человека, который знает, как система устроена и запускается, поэтому к первым вопросам лучше подключать инженера.

Маршрут: шаги от 0 до 8

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

Дополнительно есть два варианта. assess --portfolio <parent-dir> обследует много систем и ранжирует их на одной странице. modernize-status <name> отвечает, где вы сейчас, и выдаёт точную команду для вставки.

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

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

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

Шаг modernize-verify запускают после сборки, лучше в чистой сессии. Он переделывает работу заново, а не доверяет записям, которые оставила сборка.

Вот из чего состоит проверка:

• Тесты, запущенные заново с чистого листа. Результаты сборки удаляются, прогоняется весь набор, а числа берутся из файлов результатов самого раннера или из сохранённого лога. Прогон, где тесты не выполнились или были пропущены, считается провалом. Число, которое команда просто напечатала, не засчитывается.
• Старое и новое на одинаковых входах. Там, где старый код запускается, оба запускаются на одинаковых данных, а скрипт сравнивает вывод побайтово. Маскируются только поля, которые обязаны отличаться: метки времени, созданные идентификаторы. Вывод с плавающей точкой сравнивается с заявленной погрешностью. Каждое замаскированное поле попадает в результат.
• Входы, которых никто не использовал. Плагин придумывает минимум десять новых входов: граничные значения, пустые данные, огромные объёмы, необычный порядок, а если вы просили точное поведение — и некорректные записи со странностями исходной системы. Так ловится набор тестов, который проходит только на примерах, выбранных моделью.
• Тесты, которые умеют падать. В новый код намеренно вносится поломка в одну строку — это канарейка. Тесты обязаны покраснеть. Само сравнение тоже проверяется: в вывод меняется один байт.
• Каждое критичное правило подтверждено прогнанным тестом. На каждое правило P0 должен ссылаться тест, который выполнился и прошёл. Правило, которое упомянуто только пропущенным или отложенным тестом, попадает в список «упомянуто, но не выполнено».
• Исходники не тронуты. Это проверяется по времени изменения файлов, без запуска чего-либо внутри разбираемого дерева.

Каждый модуль получает один вердикт, который считает scripts/proof_pack.py по этим файлам, а сами правила записывает прямо в вывод: PROVEN, PARTLY PROVEN (с указанием, чего не хватило) или NOT PROVEN (ничего не выполнилось, есть расхождения, падает тест).

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

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

Три способа переписать код

План рекомендует один из трёх путей. Выбор за вами.

Переход на новую версию сохраняет код, поэтому может пропустить шаги extract-rules и review: связки preflight, assess, uplift, verify уже образуют полный путь. Шаги map и brief добавят порядок блоков и утверждённый план для большой системы.

Если список различий показывает, что «uplift» перепишет большую часть кода, команда сообщит об этом и предложит transform.

На чём это уже прогоняли

Команды запускали по-настоящему, без человека, на публичных кодовых базах — пока плагин собирали. Каждая цифра ниже взята из файлов, которые оставили эти прогоны.

Одна и та же команда может дать другие числа при повторном запуске: скан безопасности кода osCommerce нашёл сначала 48 подтверждённых находок, потом 52. Читайте эти числа как типичные, а не точные. Там, где нужно было решение человека, его играл тестировщик. Часть прогонов остановилась рано из-за ограничений тестовой машины. Плагин сообщил об этом и не обошёл проблему.

Ниже — часть прогонов. Полный список в README плагина.

Сколько времени это занимает

Шаги выполняются агентами, тяжёлые запускают много агентов сразу. Примерные времена на системах в десятки тысяч строк: подготовительный шаг — 3–4 минуты, оценка — 5–8, карта — 5–15, извлечение правил — 5–15, план — около 5 минут. Сборка одного модуля занимает 15–30 минут, пилотный uplift — около 15.

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

Словарь терминов

Настройка рабочего пространства

По соглашению команды никогда не правят ваш код. Подкрепите это правилом в .claude/settings.json в рабочей папке: запретите запись в исходники и разрешите запись в результаты.

{
  "permissions": {
    "allow": ["Read(**)", "Edit(analysis/**)", "Edit(modernized/**)"],
    "deny": ["Edit(/legacy/**)"]
  }
}

• Записи файлов проходят через правило Edit, поэтому оно покрывает и инструмент Write. Правило вида Write(path) не проверяется никогда. Ведущий слэш привязывает правило к корню рабочей папки.
• Если legacy/<name> — символическая ссылка (её делает --source), разрешите ещё и чтение цели: "additionalDirectories": ["/path/to/code"], и запретите её настоящий путь: "Edit(//path/to/code/**)".
• Правило покрывает файловые инструменты Claude и узнаваемые команды оболочки. Скрипт, который открывает файлы сам, под правило не попадает. Поэтому оставьте Bash с запросом для двух шагов, которые распараллеливают много пишущих агентов: шага 5b в uplift и фазы E в reimagine.
• Команды оболочки спрашивают даже в режиме accept-edits.

Полезно, но необязательно (всё это проверит preflight): scc или cloc для метрик размера; Python 3.8 или новее в виде python3 — нужен для карты, доказательства и отчёта; сборочная обвязка под ваш стек, она даёт самое сильное доказательство — запуск старого и нового рядом; и вся система в дереве, включая описания развёртывания и DDL. Без сборочной обвязки плагин переходит на тесты с записанными результатами и говорит об этом.

Безопасность

Анализируемый код считается недоверенным вводом. Враждебная кодовая база может посадить комментарий вида «ignore previous instructions», README с требованием запустить скрипт или имя файла с синтаксисом командной строки. Агенты считают содержимое файлов данными, перечисляют найденные инструкции и не выполняют их. Сборка и тесты старого кода запускаются по возможности во временной копии. Агенты проверки заново выводят каждое правило из указанного кода, а brief — это пропуск, который человек закрывает до начала сборки.

Секреты не попадают в общие файлы. Найденные учётные данные маскируются (AKIA****) и складываются в SECRETS.local.md, который не коммитится, либо в ~/.modernize/<name>/ за пределами git. Флаг --show-secrets кладёт открытые значения только в карантинный файл.

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

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

Телеметрия

Плагин считает, как его используют, чтобы следующая версия стала лучше. Он отправляет только целые числа: никогда — код, имена файлов или систем, пути, промпты и то, что вы набирали. Числа от 100 округляются до двух значащих цифр: 17 727 уходит как 18 000. Поэтому число показывает примерный размер, а не конкретную систему. Всё уходит через телеметрию самого Claude Code, так что при выключенной телеметрии ничего не отправляется. Единственный файл, который пишет сам плагин, — небольшой telemetry-state.json с хешами в его папке данных, чтобы не отправлять одни и те же числа дважды.

Понять, что уходит, можно до отправки:

python3 scripts/telemetry.py show /path/to/workspace

Отключить можно тремя способами: опцией Usage counts в плагине, переменной CODE_MODERNIZATION_TELEMETRY=0 в окружении или DISABLE_TELEMETRY=1 самого Claude Code. Пока задан хоть один из них, ничего не отправляется.

Работа в команде

Состояние лежит в файлах, а не в переписке. Последующие команды читают план, намерения и PREFLIGHT.md, а не ваш диалог, поэтому работу можно продолжить вторым человеком или в новой сессии через status. Команды никогда не делают коммит в вашем репозитории, поэтому analysis/ и modernized/ вы коммитите сами.

Живая панель (early access)

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

Ей нужны функции-хуки в режиме early access: запускайте Claude Code с CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude. Без флага ничего не меняется. Три команды вводятся без префикса: /modernize-panel показывает или прячет панель, /modernize-review-pane проверяет помеченные карточки правил, /modernize-sign заполняет блок утверждения в плане. Подробности — в описании хуков.

Полезно знать

• Извлечение делает модель, поэтому два прогона находят разные правила. Считайте BUSINESS_RULES.md результатом ревью, а не повторяемым артефактом сборки.
• Крупные прогоны можно продолжить. На сборках Claude Code с инструментом Workflow шаги extract-rules, harden, assess --portfolio, reimagine и uplift выполняются как сценарии с множеством агентов, которые проверяют находки в спорном режиме. Остановленный прогон возобновляется в той же сессии.
• Запуск без интерфейса. Длинные шаги работают как фоновые сценарии, а сессия без интерфейса перестаёт ждать фоновую работу через 10 минут. Поставьте CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS=0, чтобы параллельные шаги успевали завершиться, и закрывайте запрос на утверждение, продолжая сессию с --resume.
• Плагин можно менять под себя. Команды, агенты и сценарии — это markdown и JavaScript под лицензией Apache 2.0. Форкните их и поправьте промпты или шаги под свой стек.
• Агенты. Команды вызывают legacy-analyst, business-rules-extractor, architecture-critic, security-auditor, test-engineer, version-delta-analyst, uplift-migrator и scaffolder. Последние двое пишут только внутрь своего блока.
• Похожий набор. Репозиторий code-migration-kit-with-claude-code — отдельный набор промптов и скриптов для массовых миграций. Этот плагин даёт ведомый процесс от разбора и плана до сборки и доказательства.

Лицензия

Apache 2.0, текст лицензии — в файле LICENSE.