Cómo preparar proyectos de modernización de código con IA

En nuestra serie Notas desde el Terreno, los ingenieros de despliegue avanzado de Anthropic comparten buenas prácticas inspiradas en implementaciones reales. Este artículo recoge nuestra experiencia gestionando grandes proyectos de modernización de código.

Las modernizaciones de código que antes eran proyectos plurianuales con toda la plantilla ya pueden terminar en meses (o semanas), pero el trabajo organizativo a ambos lados suele seguir igual.

Por ejemplo, todo cambio en un sistema bancario crítico debe pasar por gestión de cambios, revisión y aprobación. Es un proceso robusto porque lo exigen los reguladores, los auditores y el negocio.

Esos procesos hacen que los sistemas críticos sean fiables, y se diseñaron partiendo de que una persona escribía cada cambio y otra revisaba cada diff. Cuando los agentes aceleran la escritura de cambios, el cuello de botella pasa de generar cambios a movilizar a la organización en torno a ellos.

Este artículo aborda el trabajo que las empresas deben hacer antes de la modernización: definir qué se considera terminado, qué evidencias debe incluir un cambio, cómo llegarán a producción los cambios certificados y qué hay que preparar para iniciar la ejecución.

Dividimos este proceso en seis pasos:

1. Define el destino: el stack tecnológico y el comportamiento del código modernizado.
2. Crea el certificado: las condiciones que deben cumplir los cambios para considerarse correctos en el estado de destino.
3. Fija la política de promoción: la ruta por la que los cambios certificados llegan a producción al ritmo en que se generan.
4. Prepara los requisitos previos: entorno, CI/CD, capacidad de revisión y aprobaciones.
5. Construye y perfecciona el flujo de trabajo agéntico: el flujo de trabajo dinámico personalizado de Claude Code que reparte la modernización entre muchas líneas de trabajo paralelas de subagentes que generan los cambios. Se basa en el destino, el certificado y la política de promoción.
6. Ejecuta la modernización: valida el flujo de trabajo completo en una partición pequeña de la base de código y escala.

Paso 1: define el destino

El destino es el estado final de la modernización. El estado final deseado determina cuál de los tres tipos de modernización estás haciendo, como se detalla en la tabla.

Determina el tipo de modernización

Decidir qué tipo de modernización hacer suele generar debate dentro de una organización. Por experiencia, quienes están más cerca de producción quieren cambiar el stack sin alterar el comportamiento, para contener el riesgo (modernización de transformación). En el otro lado suelen estar los ingenieros que han convivido con la base de código y quieren que la modernización salde la deuda técnica, y otras partes interesadas del negocio que quieren aprovechar para plantear nuevos requisitos (modernización de reimaginación).

Ambas posturas son razonables, pero si la cuestión queda sin resolver, acaba reapareciendo como una discusión sobre si un cambio concreto es "correcto". Consensuar el camino a seguir genera fricción al principio, pero agiliza el proyecto en su conjunto.

Mapea la base de código y crea la especificación de comportamiento

Comprender el sistema actual suele ser un buen primer paso para definir el destino. Extraer lo que hace realmente el código antiguo y elaborar un inventario del comportamiento actual facilita decidir si hay que cambiar o descartar partes y, por tanto, si la modernización es una transformación o una reimaginación. Esto también suele revelar lógica de negocio desconocida y casos límite.

Claude puede asumir gran parte de ese descubrimiento mapeando dependencias y documentando flujos de trabajo que nadie recuerda haber creado. Los comandos del plugin de modernización de código; assess, map y extract-rules extraen reglas de negocio con citas de origen que los ingenieros pueden revisar.

Sin embargo, el descubrimiento de Claude puede no bastar para captar cómo se comporta un sistema heredado. Las entrevistas con usuarios de negocio y desarrolladores, y la documentación interna, pueden cubrir esas lagunas. Reunir contexto puede llevar tiempo al principio, pero su calidad condiciona cada decisión posterior del flujo de trabajo.

En una reimaginación, definir el destino exige más trabajo. Se debe redactar una especificación de comportamiento detallada y acordarla con los grupos de usuarios.

Establece la justificación y los objetivos del proyecto

Además de definir el destino, la organización debe plantearse por qué merece la pena emprender la modernización. Modernizar sistemas heredados puede reducir los costes de mantenimiento y operación, pero, por experiencia, reducir costes no ha sido el objetivo principal de la mayoría de los proyectos de modernización.

Por ejemplo, un sistema con vulnerabilidades sin parchear puede sufrir una brecha de seguridad o una caída lo bastante graves como para poner en riesgo al propio negocio. Un entorno de ejecución sin soporte o un grupo cada vez menor de ingenieros que conocen el sistema agrava el riesgo.

Las herramientas de programación agéntica como Claude Code han acortado los plazos de modernización, pero los presupuestos aún son difíciles de estimar, lo que genera inercia. Hemos publicado los costes de algunas de nuestras modernizaciones a gran escala, como otros han hecho. Pueden servir como referencia aproximada, y al final de esta guía ofrecemos más orientación sobre proyecciones presupuestarias.

El principal reto al iniciar estos proyectos suele ser lograr el consenso interno y el compromiso de los equipos propietarios del sistema y de los que dependen de él. Elaborar el caso de negocio y fijar los objetivos del proyecto, a menudo desde la dirección, facilita esta parte del proceso. Esto también ayuda a anclar las contrapartidas del certificado y la política de promoción que siguen. Cuando las partes interesadas no están de acuerdo sobre cuánto riesgo puede conllevar un cambio, el riesgo de no modernizar es el contrapeso.

Paso 2: define el certificado

El certificado es el conjunto de condiciones o pruebas que debe cumplir cada cambio de modernización. Elige las condiciones que aporten la evidencia acumulada más sólida de que el cambio es correcto respecto al destino.

Cada condición debe poder verificarse sin personas implicadas en el proceso, para que el flujo de trabajo agéntico itere sobre un cambio hasta cumplir el certificado o lo derive a revisión humana si no puede.

Lo que incluya el certificado depende del destino, pero suele elegirse de esta lista:

• Pasa la suite de pruebas original
• Pasan todas las pruebas escritas por Claude durante la modernización
• Se alcanza el umbral de cobertura acordado
• Los benchmarks de rendimiento respetan el límite acordado
• Revisiones adversarias independientes de Claude, cada una en una ventana de contexto nueva, no hallan problemas bloqueantes
• En interfaces de usuario, el uso de ordenador con Claude no detecta regresiones
• Las versiones actual y de destino generan la misma salida a partir de la misma entrada, que puede ser en vivo, grabada o generada por Claude
• El estado persistido y los formatos de transmisión funcionan de ida y vuelta entre versiones
• Los cambios se ejecutan en preproducción un periodo acordado sin regresiones en tasa de errores, latencia ni alertas
• Los análisis estático y de seguridad no muestran nuevos hallazgos
• En destinos compilados, compila sin errores ni fallos de tipos

Su experiencia define lo que mide el certificado, y su participación temprana es lo que asegura su apoyo cuando los cambios llegan a revisión. Una buena forma de comprobar el certificado terminado es ver si se sentirían cómodos aprobando la fusión solo con la evidencia que aporta. Si ven reflejado su listón, la política de promoción del Paso 3 puede ser más ligera.

Con qué compara el certificado, y cómo, depende del tipo de modernización.

• En una modernización de actualización, la paridad se mide con la base de código original, y la suite de pruebas original puede ser el núcleo del certificado.
• En una modernización de transformación, la paridad también es con la base de código original, pero su suite de pruebas rara vez se ejecuta en el nuevo stack. Lo cubren sobre todo la reproducción del tráfico de producción, las pruebas diferenciales entre versión antigua y nueva y una implementación prod-parallel.
• En una reimaginación, el certificado se ancla en la especificación de comportamiento. Es el caso más difícil. Una especificación es menos objetiva que un sistema existente con el que hacer un diff, así que interviene más el criterio del modelo, lo que puede dar resultados más variables. Aquí, el certificado se apoya en pruebas derivadas de la especificación, revisiones adversarias independientes de Claude que contrastan cada cambio con ella y comprobaciones diferenciales donde el sistema nuevo mantiene el comportamiento del antiguo. Espera revisar el certificado según se aclare la especificación: sus lagunas afloran aquí primero.

Los sistemas antiguos suelen tener poca cobertura de pruebas, pruebas inestables y poca telemetría. Parte de definir el certificado es identificar estas lagunas. Si resulta difícil respaldar un certificado sólido, una de las cosas más útiles en este paso es usar Claude para generar la evidencia que falta, ya sea montando una configuración prod-parallel, creando un arnés de reproducción o escribiendo más pruebas.

Paso 3: fija la política de promoción

Los agentes generan cambios mucho más rápido de lo que un equipo humano puede revisar diff a diff. La política de promoción es una ruta de revisión por niveles, escrita y acordada de antemano, que fija la profundidad de la revisión humana de un cambio para que la modernización pueda terminar en un plazo aceptable.

Como con el certificado, trabaja este paso con los revisores e intégralo, siempre que puedas, en el proceso de gestión de cambios que ya tenga tu organización. Los detalles variarán según la organización y sus contrapartidas de riesgo, pero algunas reglas valen para todas:

• Clasifica los cambios por radio de impacto y confianza del agente. Usa la clasificación de cambios o riesgos de tu organización, si la tiene. Mantén revisión humana completa en rutas críticas.
• Corrige en origen las marcas recurrentes. Agrupa y analiza con el tiempo los cambios marcados. Cuando se repite el mismo tipo de marca, corrige la causa en el flujo de trabajo agéntico o en el certificado en lugar de revisar cada una.
• Diseña el formato de salida con los revisores. Acuerda qué información y formato agilizan más la revisión y qué señales dan más confianza que otras. Pídeles revisar las primeras muestras en el Paso 5.
• Optimiza el tiempo de los expertos. Los expertos no leerán cada diff final, pero su criterio sigue siendo el recurso escaso. Haz que puedan ir directos a los cambios de los niveles de mayor riesgo y a las decisiones marcadas de los agentes en cada uno, sin abrirse paso entre diffs enormes. Así, unas pocas horas de expertos bastan para cubrir los cambios de mayor riesgo.

Muchas reglas adelantan las horas de los expertos implicándolos desde el inicio. Sus comentarios afinan el certificado y el flujo de trabajo agéntico antes de que empiece la modernización completa.

Su visto bueno a las muestras también justifica una ruta de revisión más ligera donde hay mucha confianza. Es lo contrario del patrón tradicional, no agéntico, en el que la revisión llega al final.

La política de promoción también debe reflejar en qué punto se sitúa la modernización entre la velocidad y la profundidad de revisión. Una modernización contrarreloj, como cuando un entorno de ejecución pierde soporte, necesita una política más rápida con revisión humana más ligera y un acuerdo explícito para aceptar más riesgo por cambio.

Con más plazo, una modernización admite revisión humana más profunda y una transición más lenta. Las partes interesadas se ubicarán en puntos distintos de este espectro según su apetito de riesgo y sus limitaciones, por lo que conviene fijarlo antes de empezar el trabajo.

En un entorno regulado, aplicar una revisión humana más ligera a cualquier cambio puede generar una incomodidad real. Cada aprobador duda en dar su visto bueno porque asume el riesgo de un mal cambio, mientras que la dirección asume el riesgo mayor de un sistema que envejece.

Por experiencia, lo mejor es que la directriz de la política de promoción venga de la cúpula de la organización. También conviene acordarla de antemano para que la responsabilidad de un error que llegue a producción sea compartida y no recaiga en quien aprobó el cambio.

Paso 4: prepara los requisitos previos

Gran parte de este paso depende de equipos ajenos a la modernización: plataforma o infraestructura para el host, QA o ingeniería de lanzamientos para la capacidad de prueba, seguridad y cumplimiento para las aprobaciones. Cada uno de esos equipos suele tener su propio backlog o proceso de aprobación, así que abre las conversaciones cuanto antes, en cuanto hayas identificado los requisitos, a menudo mientras los Pasos 1 a 3 siguen en marcha.

Entorno

• Un host remoto dedicado para ejecutar el flujo de trabajo, con la base de código y otras fuentes relevantes accesibles para Claude
• Capacidad de prueba que exija el certificado
• Todo lo que refuerce el certificado: telemetría de producción, una configuración prod-parallel o datos de producción para reproducción

Base de código y CI/CD

• Un mapa de dependencias de la base de código basado en registros de compilación, análisis de importación o trazas de ejecución. Nota: el comando map del plugin es un buen punto de partida, pero según el tamaño y la antigüedad de la base de código, puede hacer falta más trabajo previo
• Tratamiento planificado de las dependencias o paquetes, como parte de la definición del destino
• Comprobación de compatibilidad lista para CI/CD, si hace falta
• Política de congelación de código acordada, si modernizas in situ
• Plan de comunicación para desarrolladores activos sobre congelaciones de código y nuevos requisitos de compatibilidad

Equipos y revisión

• Acuerdo con otros equipos que dependen de la base de código sobre cómo participan, como dar el visto bueno al certificado o revisar según la política de promoción, con tiempo de revisión reservado

Seguridad y cumplimiento

• Una vía de acceso al modelo para Claude Code aprobada para código fuente
• Acceso de mínimo privilegio para el flujo de trabajo agéntico: escritura solo en ramas de modernización y sin credenciales de producción
• Secretos y PII eliminados o enmascarados de la rama de modernización
• Cada cambio trazable y PR vinculada a la transcripción del agente y la evidencia del certificado
• Comprobación de licencias y vulnerabilidades en nuevas dependencias

Paso 5: construye y perfecciona el flujo de trabajo agéntico

Usa Claude Code para crear un flujo de trabajo dinámico personalizado que modernice la base de código.

Recomendamos empezar con el plugin de modernización de código y poner todo lo que el flujo de trabajo pueda necesitar en el sistema de archivos o en MCP, donde Claude pueda acceder. Esto incluye el destino, el certificado, la política de promoción, la base de código, la documentación y las fuentes de datos o herramientas que requiera el certificado. También puedes dar este artículo a Claude como contexto. Esto constituye la base de conocimiento central del proyecto.

Con eso listo, crear el flujo de trabajo de modernización es la parte fácil. Pide a los expertos que revisen el trabajo de Claude, incluidas las Skills específicas de la base de código y las reglas extraídas, antes de que algo dependa de ello.

Refina lo que has construido aplicándolo a partes pequeñas de la base de código, con expertos que revisen los cambios que produce, el proceso de los agentes y la evidencia de que se cumplió el certificado.

Paso 6: Ejecuta la modernización

Primero, completa la modernización de principio a fin en una parte pequeña de la base de código, incluida la revisión e integración de los cambios según la política de promoción. Corrige lo que no funcione mientras aún sea barato, repite el proceso hasta tener confianza y escala después a toda la base de código.

Las modernizaciones de transformación y reimaginación implican construir el destino junto al sistema existente y hacer la transición al terminar; la de actualización tiene otra opción: modernizar in situ la base de código en vivo mientras sigue el desarrollo.

Es la opción habitual cuando el sistema no puede detenerse o cuando la base de código cambia tan rápido que resulta difícil mantener al día una copia modernizada aparte. Lo que hemos visto funcionar aquí es dividir la base de código en particiones lógicas, de las hojas hacia dentro; congelar y modernizar una partición cada vez; y bloquear en CI/CD que los nuevos commits deshagan una partición ya modernizada.

Nota sobre costes

A menudo nos preguntan cuánto cuesta en tokens una modernización así. Cada modernización es distinta, pero los principales factores de coste incluyen:

• Qué parte de la base de código se lee y cuál se cambia;
• Lo complejo que es el certificado (la verificación, y no escribir el cambio, suele ser la mayor parte en un entorno regulado);
• Cuánta escritura y reparación de pruebas nuevas exige el certificado; y
• Cuánto trabajo de reconciliación generan otros equipos al integrar cambios a tu alrededor durante la ejecución.

Las mediciones del piloto también muestran dónde optimizar el coste de tu flujo de trabajo agéntico. Localiza las partes del flujo de trabajo que más tokens consumieron y piensa cómo hacerlas más eficientes. Pon las verificaciones de mucho cómputo tras filtros más baratos, para que solo se ejecuten si pasan las comprobaciones sencillas.

Valora usar modelos como Sonnet, que equilibran coste y capacidad, para el trabajo mecánico y de gran volumen que el certificado verifica por completo. Reserva los modelos más inteligentes para transformaciones difíciles y revisiones adversarias que verifican la corrección.

También puedes escalar a un modelo más caro cuando uno más barato no cumpla el certificado, pero analiza bien las tasas de reintentos durante el piloto, porque varios intentos baratos pueden costar más que uno caro. Si das a Claude acceso al flujo de trabajo y a los datos del piloto, puede hacer buena parte de este análisis contigo.

Más allá de la modernización

La base de código modernizada es un resultado. Los otros son el flujo de trabajo que lo produjo, un certificado escrito de lo que se considera correcto, una política de promoción que tu proceso de gestión de cambios ya ha aceptado y un rastro de evidencias de cada cambio integrado. Programa el manual de estrategias como activo reutilizable, para tener el patrón listo en la próxima actualización o reescritura.

Nuestros ingenieros de despliegue avanzado recorren estos pasos con los clientes en sus sistemas más críticos. Si estás preparando una modernización, habla con nuestro equipo.

Recursos adicionales

• El plugin público de codemod para Claude Code
• Manual de estrategias de SDLC nativo de IA
• Manual de estrategias de modernización de código
• Modernización de COBOL con IA: rompiendo la barrera del coste