Refactorización y mejora de código existente
En esta página
Transformación de código heredado en código moderno
La refactorización es una de las tareas que más tiempo consume en el desarrollo y, paradójicamente, de las menos reconocidas: nadie te felicita por dividir un archivo de 800 líneas. Precisamente por eso se va acumulando, sprint tras sprint, hasta convertirse en la causa real de tu ralentización. Codex reduce horas de trabajo manual a minutos manteniendo intacto el comportamiento existente, que es lo único que importa de verdad en una refactorización.
Refactorización estructural
El caso más habitual es ese archivo «cajón de sastre» que nadie se atreve a tocar porque está importado en todas partes.
"Refactoriza src/utils/helpers.ts: este archivo tiene 800 líneas.
Divídelo en módulos temáticos dentro de src/utils/ (string.ts,
date.ts, validation.ts, formatting.ts). Actualiza todas las
importaciones en todo el proyecto."
Codex gestiona excepcionalmente bien este tipo de tareas: identifica las funciones, las agrupa por temática, crea los nuevos archivos y, finalmente, actualiza cada importación del proyecto. Ese último paso suele ser lo que disuade de realizar la refactorización manual: cuarenta archivos por corregir, una sola importación olvidada y la compilación falla en el peor momento posible. Además, el resultado es objetivamente verificable: si las pruebas pasaban antes y siguen pasando, la división es correcta.
Modernización del código
El otro gran caso es la actualización a patrones modernos, donde la transformación es mecánica pero tan repetitiva que siempre se pospone en la lista de tareas pendientes.
"Migra todas las devoluciones de llamada (callbacks) en src/lib/database.ts
a async/await. Conserva el manejo de errores existente."
El punto de partida es JavaScript basado en devoluciones de llamada con su manejo de errores en cascada:
function getUser(id, callback) {
db.query("SELECT * FROM users WHERE id = ?", [id],
(err, rows) => {
if (err) return callback(err);
callback(null, rows[0]);
});
}
Esto es lo que produce Codex:
async function getUser(id: string): Promise<User> {
const rows = await db.query(
"SELECT * FROM users WHERE id = ?",
[id]
);
return rows[0];
}
Han ocurrido tres cosas en una sola pasada: han aparecido los tipos de TypeScript, las devoluciones de llamada han dado paso a async/await y el manejo de errores se ha simplificado, ya que las excepciones ahora se propagan de forma natural. La lógica de negocio permanece idéntica, y eso es exactamente lo que debes verificar en la revisión, no la elegancia del resultado.
Mejora de la calidad
También puedes apuntar a una dimensión específica de la calidad en lugar de a una transformación sintáctica, siempre que enumeres los requisitos.
"En src/api/, mejora el manejo de errores:
- Sustituye los bloques try/catch genéricos por errores tipados
- Añade códigos de error HTTP apropiados
- Incorpora registros (logging) con el contexto de la solicitud
- Asegúrate de que los errores de Prisma se mapeen correctamente"
Formulada así, la solicitud se vuelve verificable punto por punto durante la revisión. Una instrucción aislada como «mejora el manejo de errores» produciría algo plausible pero inutilizable, porque ni tú ni el agente sabríais cuándo se ha cumplido el objetivo.
Refactorización basada en patrones
La variante más potente consiste en designar un archivo que ya cumpla con el estándar solicitado y pedir su generalización.
"Todos los componentes de React en src/components/ que usen
useState para formularios deben migrar a react-hook-form.
Aplica el mismo patrón que src/components/LoginForm.tsx,
que ya está migrado."
Codex lee el componente de referencia, extrae el patrón y lo aplica a los componentes objetivo, gestionando los casos límite (validación personalizada, efectos secundarios) en lugar de realizar una sustitución ciega. La implicación práctica es interesante: el primer componente, el que migras tú mismo, paga el esfuerzo de todos los demás. Dedica cuidado a este archivo modelo; merece la pena tratarlo como una especificación.
Verificación de la refactorización
Codex ejecuta las pruebas después de cada refactorización, pero una refactorización que supera las pruebas no necesariamente está lista para producción. Cuatro comprobaciones forman el mínimo indispensable, y cada una aborda un riesgo diferente.
| Comprobación | Comando | Qué verifica |
|---|---|---|
| Pruebas unitarias | npm run test | Comportamiento conservado |
| Tipos | npx tsc --noEmit | Ausencia de errores de tipo |
| Linting | npm run lint | Respeto de las convenciones |
| Compilación | npm run build | Listo para producción |
El caso típico que justifica esta lista: mover archivos deja las pruebas en verde porque estas importan desde un archivo barril, pero rompe la compilación de producción debido a una importación circular que nada más revela. Añade estos cuatro comandos a tu archivo AGENTS.md y Codex los ejecutará después de cada cambio sin que tengas que pensarlo ni recordárselo.
Puntos clave
- La refactorización es la tarea donde Codex ofrece el mayor ahorro de tiempo
- Haz referencia a un archivo modelo para guiar el patrón de refactorización
- Codex actualiza importaciones y referencias en todo el proyecto
- Verifica siempre con pruebas, comprobación de tipos y compilación tras refactorizar
- Documenta los comandos de verificación en AGENTS.md