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

Полный перевод статьи из блога Claude на русский. Оригинал — по ссылке.

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

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

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

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

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

Мы разделяем этот процесс на шесть этапов:

1. Определите целевое состояние: технологический стек и поведение, которыми должен обладать модернизированный код. 
2. Создайте сертификат: условия, которым должны соответствовать изменения, чтобы считаться корректными в целевом состоянии. 
3. Установите политику продвижения: путь, по которому сертифицированные изменения попадают в производственную среду с той скоростью, с которой они создаются. 
4. Обеспечьте необходимые предварительные условия: среду, непрерывную интеграцию и непрерывную доставку, возможности для проверки и согласования.
5. Создайте и совершенствуйте агентный рабочий процесс: пользовательский динамический рабочий процесс Claude Code, который распределяет модернизацию между множеством небольших параллельных рабочих потоков подагентов, создающих изменения. Он строится вокруг целевого состояния, сертификата и политики продвижения.
6. Проведите модернизацию: докажите работоспособность рабочего процесса от начала до конца на небольшой части кодовой базы, затем масштабируйте. 

Шаг 1: Определите целевое состояние

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

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

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

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

Составьте карту кодовой базы и создайте спецификацию поведения

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

Claude может выполнить значительную часть такого исследования, сопоставляя зависимости и документируя рабочие процессы, о создании которых никто не помнит. Команды assess, map, и extract-rules плагина для модернизации кода извлекают бизнес-правила с указанием источников, которые затем могут проверить инженеры. 

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

Для переосмысления определение целевого состояния требует дополнительной работы: необходимо подготовить подробную спецификацию поведения и согласовать её с группами пользователей.

Определите обоснование и цели проекта

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

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

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

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

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

Шаг 2: Определите сертификат

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

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

Содержание сертификата зависит от целевого состояния, но обычно включает элементы из этого списка:

• Исходный набор тестов проходит успешно
• Все тесты, созданные Claude в ходе модернизации, проходят успешно
• Покрытие тестами соответствует согласованному порогу
• Показатели производительности остаются в согласованных пределах
• Независимые состязательные проверки, проводимые Claude, каждая в новом контекстном окне, не выявляют блокирующих проблем
• Для пользовательских интерфейсов использование компьютера под управлением Claude не выявляет регрессий
• Текущая и целевая версии выдают одинаковый результат при одинаковом входе, который может быть реальным, записанным или сгенерированным Claude
• Сохраняемое состояние и форматы передачи данных корректно преобразуются туда и обратно между текущей и целевой версиями
• Изменения работают в промежуточной среде в течение согласованного периода без регрессий в показателях ошибок, задержек или оповещений
• Статический анализ и сканирование безопасности не выявляют новых находок
• Для компилируемых целей сборка выполняется без ошибок, а проверки типов проходят успешно

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

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

То, с чем и как сопоставляется сертификат, зависит от типа модернизации. 

• Для модернизации с повышением уровня, сопоставление выполняется с исходной кодовой базой, и исходный набор тестов может составлять основу сертификата. 
• Для модернизации с преобразованием, сопоставление также выполняется с исходной кодовой базой, но исходный набор тестов редко запускается в новом стеке. Вместо этого основную работу выполняют воспроизведение производственного трафика, дифференциальное тестирование между старой и новой версиями и развертывание, работающее параллельно с производственной средой. 
• Для модернизации с переосмыслением сертификат опирается на спецификацию поведения. Это самый сложный случай. Спецификация менее объективна, чем существующая система, с которой можно сравнивать различия, поэтому требуется более высокая степень суждения модели, что может приводить к более вариативным результатам. Здесь сертификат опирается на тесты, написанные на основе спецификации, независимые состязательные проверки Claude, которые сверяют каждое изменение со спецификацией, и дифференциальные проверки, при которых новая система сохраняет поведение старой. Ожидайте, что Вам потребуется пересматривать сертификат по мере уточнения спецификации: пробелы в спецификации проявляются здесь прежде всего.

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

Шаг 3: Установите политику продвижения

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

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

• Распределяйте изменения по уровням в зависимости от радиуса воздействия и уверенности агента. Используйте собственную классификацию изменений или рисков Вашей организации, если она существует. Сохраняйте полную человеческую проверку для критически важных путей.
• Устраняйте повторяющиеся сигналы у источника. Группируйте и анализируйте отмеченные изменения с течением времени. Когда один и тот же тип сигнала продолжает повторяться, устраняйте причину в агентном рабочем процессе или сертификате, а не проверяйте каждое изменение.
• Разрабатывайте формат вывода вместе с проверяющими. Согласуйте, какая информация и какой формат делают проверку наиболее быстрой, а также какие сигналы дают больше уверенности, чем другие. Попросите их проверить ранние примеры результатов на шаге 5.
• Эффективно распределяйте время экспертов предметной области (SME). Эксперты предметной области не будут читать каждое итоговое сравнение изменений, но их суждение по-прежнему остаётся дефицитным ресурсом. Упростите для них переход непосредственно к изменениям на уровнях с наивысшим риском и к отмеченным решениям агента внутри каждого из них, без необходимости продираться через большие сравнения изменений. Тогда небольшое количество часов экспертов охватит изменения, несущие наибольший риск.

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

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

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

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

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

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

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

Шаг 4: Обеспечьте выполнение предварительных условий

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

Среда

• Выделенный удалённый хост для выполнения рабочего процесса, с кодовой базой и другими релевантными источниками, доступными для Claude
• Тестовые мощности в соответствии с требованиями сертификата
• Всё, что укрепляет сертификат: телеметрия из рабочей среды, среда, параллельная рабочей, или рабочие данные для воспроизведения

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

• Карта зависимостей кодовой базы, основанная на журналах сборки и компиляции; анализе импортов; или трассировках времени выполнения. Примечание: команда плагина map является хорошей отправной точкой, но в зависимости от размера и возраста кодовой базы может потребоваться провести более обширную предварительную работу
• Запланированная обработка любых зависимостей или пакетов как часть определения целевого состояния
• Проверка совместимости, готовая к добавлению в непрерывную интеграцию и непрерывную поставку, если потребуется
• Согласованная политика заморозки кода, если Вы проводите модернизацию на месте
• План коммуникаций для активных разработчиков, охватывающий любые заморозки кода и новые требования к совместимости

Команды и проверка

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

Безопасность и соответствие требованиям

• Путь доступа к модели для Claude Code, одобренный для исходного кода
• Доступ с наименьшими привилегиями для агентного рабочего процесса: запись только в ветки модернизации и отсутствие учётных данных для рабочей среды
• Секреты и персональные данные удалены или замаскированы в ветке модернизации
• Каждое изменение можно отследить, а запрос на включение изменений связан со стенограммой агента и доказательствами в сертификате
• Проверки лицензий и уязвимостей в новых зависимостях

Шаг 5: Создайте и доработайте агентный рабочий процесс

Используйте Claude Code для разработки настраиваемого динамического рабочего процесса для модернизации кодовой базы. 

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

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

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

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

Шаг 6: Выполните модернизацию

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

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

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

Примечание о стоимости

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

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

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

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

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

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

Помимо модернизации

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

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

Дополнительные ресурсы

• Публичный плагин codemod для Claude Code
• Практическое руководство по жизненному циклу разработки программного обеспечения, ориентированному на искусственный интеллект
• Практическое руководство по модернизации кода
• Модернизация COBOL с помощью искусственного интеллекта: преодоление ценового барьера