Cómo usar Cursor AI para refactorizar código heredado en Python paso a paso

Si alguna vez has tenido que meterle mano a un proyecto Python con más de cinco años de antigüedad, sabes que el código heredado (legacy code) puede ser una auténtica pesadilla. Funciona, pero está lleno de funciones de 200 líneas, variables con nombres como var1, tmp o a, y esa mezcla mortal de tabs y espacios. Refactorizar manualmente es tedioso y arriesgado, pero con Cursor AI podemos hacerlo de forma segura y mucho más rápida.

Cursor AI es un editor de código con inteligencia artificial integrada que entiende el contexto de tu proyecto. No solo te sugiere código, sino que puede analizar funciones complejas, detectar patrones y proponer refactorizaciones completas. En este artículo te voy a enseñar, paso a paso, cómo usar Cursor AI para transformar ese código heredado en Python en algo limpio, mantenible y moderno.

Preparar el Entorno y el Contexto

Antes de lanzarte a refactorizar, necesitas que Cursor AI entienda bien tu proyecto. No basta con abrir un archivo suelto; la IA necesita ver las dependencias, las importaciones y la estructura general para no romper nada.

1. Abre el proyecto completo en Cursor

Cursor funciona mejor cuando tiene acceso a todo el repositorio. Arrastra la carpeta del proyecto a la ventana de Cursor o usa File > Open Folder. Asegúrate de que el archivo que quieres refactorizar esté abierto en el editor.

2. Usa el comando de contexto global

Para que la IA tenga una visión completa, usa el atajo Cmd+K (Mac) o Ctrl+K (Windows) y selecciona la opción "Edit code" o "Ask a question". Antes de pedir la refactorización, escribe un prompt de contexto:

PROMPTAnaliza este archivo Python. Es parte de un proyecto heredado. Identifica las funciones principales, las dependencias externas y los patrones de diseño que se usan actualmente. Dame un resumen de 5 líneas. Esto fuerza a Cursor a leer todo el archivo y generar un resumen. Luego, podrás hacer preguntas más específicas sobre partes concretas.

💡 Tip: Si tu proyecto tiene tests unitarios, ábrelos también en una pestaña. Cursor puede usar los tests como referencia para asegurarse de que la refactorización no rompe la funcionalidad esperada.

El Prompt Completo para Refactorizar una Función

Vamos al grano. Imagina que te encuentras una función monstruosa como esta:

CÓDIGO HEREDADOdef process_data(x, y, z): a = [] for i in range(len(x)): if x[i] > 10: b = x[i] * 2 if y[i] == 'active': c = b + z[i] a.append(c) else: a.append(b) else: a.append(0) return a Esta función mezcla lógica de negocio, tiene nombres poco descriptivos y es difícil de testear. Con Cursor AI, selecciona toda la función y usa el siguiente prompt:

PROMPTRefactoriza esta función siguiendo los principios SOLID y el estilo moderno de Python (Python 3.10+). Divide la lógica en funciones más pequeñas con nombres descriptivos. Usa type hints. No cambies la funcionalidad externa. Si es posible, usa list comprehensions o funciones map/filter. Cursor te devolverá algo como esto:

RESULTADOfrom typing import List, Union def _is_above_threshold(value: int, threshold: int = 10) -> bool: return value > threshold def _calculate_active_value(base: int, extra: int) -> int: return base 2 + extra def _calculate_inactive_value(base: int) -> int: return base 2 def process_data(values: List[int], statuses: List[str], extras: List[int]) -> List[int]: return [ _calculate_active_value(values[i], extras[i]) if _is_above_threshold(values[i]) and statuses[i] == 'active' else _calculate_inactive_value(values[i]) if _is_above_threshold(values[i]) else 0 for i in range(len(values)) ] La función ahora es más legible, tiene type hints y cada responsabilidad está encapsulada en una función separada. El comportamiento externo sigue siendo el mismo.

Refactorizar Clases Grandes con el Patrón Estrategia

Otro clásico del código heredado son las clases que hacen de todo: procesan datos, se conectan a la base de datos, generan informes y hasta envían emails. Vamos a usar Cursor AI para aplicar el patrón Estrategia.

1. Selecciona la clase completa

Selecciona desde class MiClase: hasta el final. Luego usa este prompt:

PROMPTEsta clase viola el principio de responsabilidad única. Refactorízala usando el patrón Strategy. Identifica las diferentes responsabilidades (procesamiento, persistencia, notificación) y crea clases separadas para cada una. Mantén la interfaz pública original para no romper el código que la usa. Cursor te generará varias clases en el mismo archivo o te sugerirá cómo dividirlas en módulos. Puedes pedirle que las coloque en archivos separados con un prompt adicional:

PROMPTAhora mueve cada nueva clase a su propio archivo. Crea los imports necesarios en el archivo principal. Dame el contenido de cada archivo. 💡 Tip: Después de una refactorización grande, usa el comando Cmd+Shift+P y escribe "Cursor: Run tests" si tienes tests configurados. Si no, pídele a Cursor que genere tests unitarios para el nuevo código antes de eliminar el antiguo.

Eliminar Código Muerto y Variables Obsoletas

El código heredado suele acumular funciones que ya no se usan, variables que se asignan pero nunca se leen, y comentarios que ya no tienen sentido. Cursor AI puede ayudarte a limpiar todo eso.

1. Detecta código no utilizado

Selecciona el archivo completo y usa este prompt:

PROMPTAnaliza este archivo en busca de código muerto: funciones que no se llaman, variables que se asignan pero no se usan, importaciones innecesarias y parámetros de función que nunca se utilizan. Dame una lista de lo que puedo eliminar de forma segura. No modifiques el código todavía, solo dime qué eliminar. Cursor te devolverá una tabla como esta:

ElementoLíneaRazónSeguro de eliminar función old_calc()45Nunca se llamaSí variable temp_val78Se asigna pero no se usaSí import os3No se usa en el archivoSí parámetro verbose12Siempre se pasa como FalseRequiere verificación

2. Aplica la limpieza

Una vez que tengas la lista, puedes pedirle a Cursor que elimine todo lo seguro de una sola vez:

PROMPTBasándote en el análisis anterior, elimina todo el código muerto que marcaste como "Seguro de eliminar". No toques nada que requiera verificación adicional. Después de eliminar, optimiza los imports para que queden ordenados.

Modernizar Sintaxis y Estilo

El código heredado en Python suele usar sintaxis antigua: print sin paréntesis (en Python 2), % para formateo de cadenas, bucles manuales donde podrían usarse comprensiones, etc. Cursor AI puede actualizar todo esto a Python 3.12+ en segundos.

1. Actualiza la sintaxis global

Selecciona todo el archivo y usa este prompt:

PROMPTModerniza este archivo a Python 3.12+. Aplica estos cambios: - Convierte f-strings donde haya formateo con % o .format() - Reemplaza bucles for manuales por list comprehensions o generadores cuando sea más legible - Usa el operador match-case para cadenas largas de if-elif - Añade type hints a todas las funciones y métodos (usa los tipos de typing) - Reemplaza Union[X, None] por X | None - Si hay código Python 2 (print sin paréntesis, etc.), conviértelo a Python 3 Cursor aplicará los cambios directamente en el archivo. Puedes revisar cada cambio con el control de versiones integrado de Cursor (usa el botón "Diff" para ver antes y después).

💡 Tip: No confíes ciegamente en la IA. Después de una modernización masiva, ejecuta el proyecto entero para detectar errores de sintaxis o lógica. Cursor a veces cambia nombres de variables si no le das instrucciones explícitas de no hacerlo.

Errores Comunes y Cómo Evitarlos

Refactorizar con IA no es magia. Aquí tienes los errores más típicos al usar Cursor AI con código heredado:

• No dar suficiente contexto: Si solo seleccionas una función sin decirle que es parte de un proyecto más grande, Cursor puede cambiar nombres de funciones que se usan en otros archivos. Siempre incluye en el prompt que no debe cambiar la interfaz pública.
• Confiar en la primera respuesta: A veces Cursor genera código que parece correcto pero tiene errores lógicos. Pídele siempre que te explique los cambios que ha hecho y revisa los casos borde.
• Olvidar los tests: Si no tienes tests, pídele a Cursor que genere tests unitarios para el código refactorizado antes de eliminar el original. Así puedes verificar que todo funciona igual.
• Refactorizar todo de golpe: Es mejor ir archivo por archivo o función por función. Si intentas refactorizar 10 archivos a la vez, Cursor puede perder el contexto y generar inconsistencias.

Con estos pasos, podrás transformar ese código heredado en Python en un proyecto moderno, mantenible y mucho más agradable de trabajar. La clave está en ser específico con los prompts, revisar los cambios y usar los tests como red de seguridad. Cursor AI no te va a sustituir, pero te va a multiplicar la velocidad de refactorización por diez.