Claude como revisor de código legacy: el flujo exacto para modernizar bases de código sin romper nada

Tienes 80.000 líneas de PHP 5.6 en producción. Funciona. Nadie quiere tocarlo. Y sin embargo, cada sprint nuevo te cuesta el doble porque cualquier cambio puede romper algo que nadie recuerda haber escrito. Ese es el problema del código legacy, y Claude puede ser el revisor más disciplinado que hayas tenido para atacarlo de forma sistemática.

No hablo de pedirle que "refactorice esto" y esperar magia. Hablo de un flujo concreto que convierte a Claude en un revisor técnico con contexto, memoria de sesión y criterio para priorizar qué tocar primero y qué dejar quieto.

Por qué el código legacy necesita un revisor, no un reescritor

El error más común al modernizar código legacy es atacarlo de arriba a abajo como si fuera una hoja en blanco. Los equipos reescriben módulos enteros, rompen dependencias implícitas que nadie documentó, y acaban con dos sistemas a medias que no se comunican bien. La tasa de fracaso en proyectos de reescritura total supera el 70% según múltiples estudios del sector.

La alternativa es la revisión incremental guiada. Claude funciona bien aquí porque puede analizar fragmentos, mantener el contexto de las decisiones tomadas dentro de la sesión, identificar patrones de riesgo y sugerir cambios que no rompan la interfaz externa del módulo. No ejecuta código, pero razona sobre él con precisión suficiente para ser útil en la fase de auditoría y planificación.

El flujo paso a paso

Paso 1: Establece el contrato de contexto al inicio de la sesión

Antes de pegar una sola línea de código, dale a Claude el marco de trabajo. Un prompt de inicio efectivo tiene esta forma:

Eres un revisor técnico senior especializado en modernización de código legacy.
El proyecto es una aplicación PHP 5.6 migrada parcialmente a PHP 8.1.
Las reglas del juego son:
- No proponer cambios que alteren las firmas públicas de métodos sin indicarlo explícitamente.
- Priorizar corrección de bugs sobre elegancia.
- Señalar las dependencias ocultas antes de sugerir cualquier refactor.
- Si algo es ambiguo, pregunta antes de asumir.
Empecemos con la revisión del módulo de autenticación.

Este contrato convierte a Claude de generador de texto a revisor con restricciones explícitas. Marca la diferencia entre respuestas genéricas y análisis accionable.

Paso 2: Auditoría de riesgos antes de tocar nada

Pega el módulo o función y pide un análisis de riesgos estructurado, no una lista de mejoras. La distinción importa.

Analiza este código e identifica:
1. Bugs activos o latentes que podrían estar en producción ahora mismo.
2. Dependencias implícitas (variables globales, constantes mágicas, efectos secundarios).
3. Deuda técnica que bloquea la testabilidad del código.
No propongas refactors todavía. Solo diagnóstico.

Separar el diagnóstico del tratamiento evita que Claude salte a reescribir cuando lo que necesitas es entender primero qué está roto y por qué sobrevivió tanto tiempo.

Paso 3: Priorización por impacto y riesgo

Una vez tienes el diagnóstico, pide a Claude que clasifique los hallazgos con una matriz sencilla. Por ejemplo:

Con base en el diagnóstico anterior, clasifica cada hallazgo en esta matriz:
- Alto impacto / Bajo riesgo de cambio → hacer primero
- Alto impacto / Alto riesgo → planificar con tests antes
- Bajo impacto / Bajo riesgo → backlog técnico
- Bajo impacto / Alto riesgo → no tocar por ahora
Justifica cada clasificación en una línea.

Esto te da un roadmap de modernización en minutos, con criterio técnico detrás de cada decisión.

Paso 4: Refactor incremental con tests de contrato

Aquí Claude trabaja como copiloto de escritura de tests antes de cualquier cambio. El principio es simple, no refactorices sin cobertura. Pide esto:

Para la función `procesarPago()` identificada como alto riesgo, 
escribe los tests de contrato mínimos en PHPUnit que capturen 
el comportamiento actual, incluyendo los casos límite que detectaste. 
No optimices la función todavía.

Los tests de contrato capturan el comportamiento existente, no el comportamiento ideal. Son tu red de seguridad para validar que el refactor no cambia lo que el sistema espera de ese módulo.

Paso 5: Revisión del diff, no del archivo completo

Una vez tienes el refactor propuesto, no pidas a Claude que revise el archivo entero de nuevo. Pega el diff y pide revisión específica:

Revisa este diff y dime:
- ¿Algún cambio rompe las precondiciones que identificaste en el diagnóstico?
- ¿La firma pública del método sigue siendo compatible?
- ¿Hay algún edge case no cubierto por los tests que escribimos?

Revisar diffs en lugar de archivos completos mantiene el foco y aprovecha el contexto acumulado en la sesión.

Lo que Claude no puede hacer por ti

Claude no ejecuta el código, no corre los tests ni accede a tu repositorio. No detectará fallos de runtime que solo aparecen bajo carga específica ni condiciones de carrera en sistemas concurrentes complejos. Para eso necesitas tu pipeline de CI y herramientas de análisis estático como PHPStan o SonarQube corriendo en paralelo.

Tratar a Claude como el único validador de un refactor es un error. Tratar a Claude como el revisor técnico que estructura el proceso antes de que el código llegue a producción, ahí es donde genera valor real.

El siguiente paso concreto

Elige el módulo más temido de tu base de código, ese que nadie quiere tocar en las planning. Abre Claude, pega el prompt de contexto del Paso 1, adapta el lenguaje y el stack a tu proyecto, y ejecuta los cinco pasos en orden. El objetivo no es tener el código perfecto al final de la sesión, es tener un diagnóstico documentado y un primer test de contrato escrito. Desde ahí, el refactor incremental tiene base firme para avanzar sin sustos.