Aprende a refactorizar componentes React con Claude Code usando pruebas de caracterización, pasos pequeños y seguros, y desenredando estado para mejorar la estructura sin cambiar el comportamiento.
Los refactors en React se sienten arriesgados porque la mayoría de los componentes no son pequeños bloques limpios. Son montones vivos de UI, estado, efectos y “una prop más” para arreglar algo. Cuando cambias la estructura, a menudo cambias el timing, la identidad o el flujo de datos sin querer.
Un refactor cambia el comportamiento más a menudo cuando, por accidente:
Los refactors también se convierten en reescrituras cuando “limpiar” se mezcla con “mejorar”. Empiezas extrayendo un componente, luego renombras un montón de cosas, luego “arreglas” la forma del estado y luego reemplazas un hook. Pronto estás cambiando lógica y diseño a la vez. Sin guardarraíles, es difícil saber qué cambio causó el bug.
Un refactor seguro tiene una promesa simple: los usuarios ven el mismo comportamiento y el código queda más claro. Props, eventos, estados de carga, estados de error y casos límite deberían actuar igual. Si el comportamiento cambia, debe ser intencional, pequeño y señalado claramente.
Si vas a refactorizar componentes React con Claude Code (o con cualquier asistente), trátalo como un par de programación rápido, no como piloto automático. Pídele que describa los riesgos antes de editar, proponga un plan con pasos pequeños y explique cómo verificó que el comportamiento se mantuvo. Luego valida tú mismo: ejecuta la app, recorre los caminos raros y apóyate en pruebas que capturen lo que el componente hace hoy, no lo que desearías que hiciera.
Elige un componente que realmente te esté costando tiempo. No toda la página, no “la capa UI” y no un vago “limpieza”. Escoge un solo componente difícil de leer, difícil de cambiar o lleno de estado y efectos frágiles. Un objetivo concreto también hace que las sugerencias del asistente sean más fáciles de verificar.
Escribe un objetivo que puedas comprobar en cinco minutos. Buenos objetivos hablan de estructura, no de resultados: “dividir en componentes más pequeños”, “hacer el estado más fácil de seguir” o “hacerlo testeable sin mockear media app”. Evita metas como “mejorarlo” o “mejorar rendimiento” a menos que tengas una métrica y un cuello de botella conocido.
Define límites antes de abrir el editor. Los refactors más seguros son aburridos:
Luego lista las dependencias que pueden romper el comportamiento silenciosamente al mover código: llamadas a APIs, providers de contexto, params de routing, feature flags, eventos de analytics y estado global compartido.
Un ejemplo concreto: tienes un OrdersTable de 600 líneas que hace fetch, filtra, gestiona selección y muestra un drawer con detalles. Un objetivo claro sería: “extraer renderizado de filas y UI del drawer en componentes, y mover el estado de selección a un reducer, sin cambios en la UI.” Ese objetivo dice qué es “hecho” y qué queda fuera de alcance.
Antes de refactorizar, trata el componente como una caja negra. Tu trabajo es capturar lo que hace hoy, no lo que querrías que hiciera. Esto evita que el refactor se convierta en un rediseño.
Empieza escribiendo el comportamiento actual en lenguaje llano: dadas estas entradas, la UI muestra esa salida. Incluye props, params de URL, feature flags y cualquier dato que venga de contexto o store. Si usas Claude Code, pega un fragmento pequeño y enfocado y pídele que reformule el comportamiento en frases precisas que puedas comprobar después.
Cubre los estados de UI que la gente realmente ve. Un componente puede verse bien en el camino feliz y romper justo al entrar en loading, vacío o error.
También captura reglas implícitas fáciles de pasar por alto, y que suelen causar fallos en refactors:
Ejemplo: tienes una tabla de usuarios que carga resultados, soporta búsqueda y ordena por “Última actividad”. Escribe qué sucede cuando la búsqueda está vacía, cuando la API devuelve lista vacía, cuando la API falla y cuando dos usuarios tienen la misma “Última actividad”. Anota detalles pequeños como si el orden es case-insensitive o si la tabla mantiene la página actual cuando cambia un filtro.
Cuando tus notas te parezcan aburridas y específicas, estás listo.
Las pruebas de caracterización son tests de “esto es lo que hace hoy”. Describen el comportamiento actual, aunque sea raro o inconsistente. Suena al revés, pero evita que un refactor se convierta en una reescritura silenciosa.
Al refactorizar componentes React con Claude Code, estas pruebas son tus rieles de seguridad. La herramienta puede ayudar a reorganizar código, pero tú decides qué no debe cambiar.
Céntrate en lo que los usuarios (y otro código) esperan:
Para mantener los tests estables, aserta resultados, no implementación. Prefiere “el botón Guardar queda deshabilitado y aparece un mensaje” sobre “se llamó a setState” o “este hook se ejecutó”. Si un test se rompe por renombrar un componente o reordenar hooks, no estaba protegiendo comportamiento.
El comportamiento asíncrono es donde los refactors suelen cambiar el timing. Trátalo explícitamente: espera a que la UI se estabilice y luego aserta. Si hay timers (búsqueda con debounce, toasts retrasados), usa timers falsos y avanza el tiempo. Si hay llamadas de red, mockea fetch y aserta lo que el usuario ve tras éxito y tras fallo. Para flujos tipo Suspense, prueba tanto el fallback como la vista resuelta.
Ejemplo: una tabla de “Usuarios” muestra “No results” solo después de que la búsqueda termina. Una prueba de caracterización debe fijar esa secuencia: indicador de carga primero, luego filas o el mensaje vacío, independientemente de cómo luego dividáis el componente.
El objetivo no es “cambios más grandes más rápidos”. Es obtener una imagen clara de lo que hace el componente y cambiar una cosa pequeña a la vez manteniendo el comportamiento.
Empieza por pegar el componente y pedir un resumen en lenguaje natural de sus responsabilidades. Insiste en concretar: qué datos muestra, qué acciones de usuario maneja y qué efectos colaterales dispara (fetches, timers, suscripciones, analytics). Esto suele exponer trabajos escondidos que hacen los refactors riesgosos.
Luego pide un mapa de dependencias. Quieres un inventario de cada entrada y salida: props, lecturas de context, hooks personalizados, estado local, valores derivados, efectos y cualquier helper a nivel de módulo. Un mapa útil también señala qué es seguro mover (cálculos puros) versus qué es “pegajoso” (timing, DOM, red).
Después, pídele que proponga candidatos para extraer, con una regla estricta: separar piezas puras de presentación de piezas de control con estado. Secciones con mucho JSX que solo necesitan props son buenos candidatos primero. Secciones que mezclan handlers, llamadas asíncronas y actualizaciones de estado normalmente no lo son.
Un flujo que funciona en código real:
Los puntos de control importan. Pide a Claude Code un plan mínimo donde cada paso se pueda commitear y revertir. Un checkpoint práctico podría ser: “Extraer <TableHeader> sin cambios lógicos” antes de tocar la ordenación.
Ejemplo concreto: si un componente renderiza una tabla de clientes, controla filtros y hace fetch, extrae primero el marcado de la tabla (headers, filas, estado vacío) en un componente puro. Solo después mueve el estado de filtros o el efecto de fetch. Este orden evita que los bugs viajen con el JSX.
Al dividir un componente grande, el riesgo no es tanto mover JSX como cambiar flujo de datos, timing o cableado de eventos. Trata la extracción primero como copiar y cablear, y la limpieza después.
Empieza detectando límites que ya existen en la UI, no en la estructura de archivos. Busca partes que puedas describir como su propia “cosa” en una frase: un header con acciones, una barra de filtros, una lista de resultados, un footer con paginación.
Un primer movimiento seguro es extraer componentes presentacionales puros: props entran, JSX sale. Manténlos aburridos a propósito. Sin nuevo estado, sin efectos, sin llamadas a APIs. Si el componente original tenía un handler que hacía tres cosas, mantenlo en el padre y pásalo.
Límites seguros que suelen funcionar: área de header, lista y fila, filtros (solo inputs), controles de footer (paginación, totales, acciones masivas) y diálogos (abrir/cerrar y callbacks pasados como props).
El nombre importa más de lo que crees. Elige nombres específicos como UsersTableHeader o InvoiceRowActions. Evita nombres genéricos como “Utils” o “HelperComponent” porque ocultan responsabilidades e invitan a mezclar preocupaciones.
Introduce un componente contenedor solo cuando haya una necesidad real: un trozo de UI que debe poseer estado o efectos para mantenerse coherente. Aun así, mantenlo estrecho. Un buen contenedor tiene un propósito (por ejemplo, “estado de filtros”) y pasa todo lo demás como props.
Los componentes desordenados suelen mezclar tres tipos de datos: estado de UI real (lo que el usuario cambió), datos derivados (lo que puedes calcular) y estado del servidor (lo que viene de la red). Si tratas todo como estado local, los refactors se vuelven riesgosos porque puedes cambiar cuándo se actualiza cada cosa.
Empieza etiquetando cada pieza de datos. Pregunta: ¿el usuario lo edita o puedo calcularlo desde props, estado y datos fetchados? También pregunta: ¿este valor se posee aquí o simplemente se pasa?
Separar estado de valores derivados
Los valores derivados no deberían vivir en useState. muévelos a una función pequeña o a un selector memoizado cuando sea caro. Esto reduce actualizaciones de estado y hace el comportamiento más predecible.
Un patrón seguro:
useState solo los valores editados por el usuario.useMemo.Haz los efectos aburridos y específicos
Los efectos fallan cuando hacen demasiado o reaccionan a las dependencias equivocadas. Apunta a un efecto por propósito: uno para sincronizar con localStorage, otro para fetch, otro para suscripciones. Si un efecto lee muchos valores, suele ocultar responsabilidades extra.
Si usas Claude Code, pide un cambio pequeño: dividir un efecto en dos, o mover una responsabilidad a un helper. Luego ejecuta las pruebas de caracterización después de cada movimiento.
Ten cuidado con el prop drilling. Reemplazarlo con contexto solo ayuda cuando elimina cableado repetido y aclara propiedad. Un buen indicador es cuando el contexto tiene sentido a nivel de app (usuario actual, tema, feature flags), no como parche para una rama de componentes.
Ejemplo: un componente de tabla podría almacenar rows y filteredRows en estado. Mantén rows como estado, calcula filteredRows a partir de rows + query y pon el filtrado en una función pura para que sea fácil de probar y difícil de romper.
Los refactors suelen fallar cuando cambias demasiado antes de darte cuenta. La solución es simple: trabaja en checkpoints pequeños y trata cada checkpoint como un mini-release. Aunque trabajes en una rama, mantén los cambios del tamaño de un PR para ver qué falló y por qué.
Después de cada movimiento significativo (extraer un componente, cambiar cómo fluye el estado), para y demuestra que no cambiaste el comportamiento. Esa prueba puede ser automatizada (tests) y manual (chequeo rápido en el navegador). La meta no es perfección, es detección rápida.
Un bucle de checkpoint práctico:
Si usas una plataforma como Koder.ai, snapshots y rollback pueden actuar como rieles de seguridad mientras iteras. Aun así, quieres commits normales; los snapshots ayudan a comparar una versión “conocida buena” con la actual o cuando un experimento sale mal.
Lleva un ledger de comportamiento simple conforme avanzas. Es solo una nota corta de lo que verificaste, y evita que repitas las mismas comprobaciones una y otra vez.
Por ejemplo:
Cuando algo se rompe, el ledger te dice qué volver a comprobar y tus checkpoints hacen barato revertir.
La mayoría de los refactors fallan en formas pequeñas y aburridas. La UI aún funciona, pero desaparece una regla de espaciado, un handler se ejecuta dos veces o una lista pierde el foco al escribir. Los asistentes pueden empeorar esto porque el código parece más limpio incluso cuando el comportamiento deriva.
Una causa común es cambiar la estructura. Extraes un componente y envuelves cosas en un \u003cdiv\u003e extra, o sustituyes un \u003cbutton\u003e por un \u003cdiv\u003e clickable. Selectores CSS, layout, navegación por teclado y queries de tests pueden cambiar sin que nadie lo note.
Las trampas que más rompen comportamiento:
{} o () => {}) puede disparar re-renders extra y resetear estado hijo. Vigila props que antes eran estables.useEffect, useMemo o useCallback puede introducir valores obsoletos o bucles si cambian las dependencias. Si un efecto antes corría “en click”, no lo conviertas en algo que corra “cuando cualquier cosa cambie”.Ejemplo concreto: dividir un componente de tabla y cambiar las keys de filas de un ID a índice puede parecer bien, pero rompe la selección cuando las filas se reordenan. Considera “limpio” como un bonus; “mismo comportamiento” es el requisito.
Antes de mergear, necesitas pruebas de que el refactor mantuvo el comportamiento. La señal más fácil es aburrida: todo sigue funcionando sin que hayas tenido que “arreglar” las pruebas.
Haz este chequeo rápido tras el último cambio pequeño:
onChange sigue disparándose en input de usuario, no en mount).Una comprobación rápida: abre el componente y recorre un flujo raro, por ejemplo provocar un error, reintentar y luego limpiar filtros. Los refactors suelen romper transiciones incluso cuando la ruta principal funciona.
Si algo falla, revierte el último cambio y reházlo en un paso más pequeño. Suele ser más rápido que depurar un diff grande.
Imagina un ProductTable que lo hace todo: fetch de datos, gestiona filtros, controla paginación, abre un diálogo de confirmación para borrar y maneja acciones por fila como editar, duplicar y archivar. Empezó pequeño y creció hasta 900 líneas.
Los síntomas son familiares: estado repartido en varios useState, un par de useEffect que se disparan en un orden específico y un cambio “inocuo” que rompe la paginación solo cuando un filtro está activo. La gente deja de tocarlo porque es impredecible.
Antes de cambiar la estructura, fija el comportamiento con algunas pruebas de caracterización. Céntrate en lo que hacen los usuarios, no en el estado interno:
Ahora puedes refactorizar en commits pequeños. Un plan de extracción limpio podría ser: FilterBar renderiza controles y emite cambios de filtro; TableView renderiza filas y paginación; RowActions posee el menú de acciones y la UI del diálogo de confirmación; y un hook useProductTable posee la lógica enmarañada (params de query, estado derivado y efectos).
El orden importa. Extrae UI tonta primero (TableView, FilterBar) pasando props sin cambios. Deja lo arriesgado para el final: mover estado y efectos a useProductTable. Cuando lo hagas, conserva los nombres de props y las formas de eventos para que las pruebas sigan pasando. Si un test falla, has detectado un cambio de comportamiento, no un problema de estilo.
Si quieres que refactorizar componentes React con Claude Code sea seguro cada vez, convierte lo que hiciste en una plantilla pequeña que puedas reutilizar. La meta no es más proceso, es menos sorpresas.
Mantén una plantilla simple de refactorización
Escribe un playbook corto que puedas seguir en cualquier componente, incluso cuando estés cansado:
Guarda esto como un snippet en tus notas o en el repo para que el siguiente refactor empiece con los mismos rieles de seguridad.
Decide qué hacer una vez que el comportamiento esté bloqueado
Cuando el componente es estable y más legible, elige la siguiente pasada según impacto en usuarios. Un orden común: accesibilidad primero (labels, foco, teclado), luego rendimiento (memoización, renders caros), y por último limpieza (types, nombres, código muerto). No mezcles los tres en un mismo PR.
Si usas un flujo tipo vibe-coding como Koder.ai (koder.ai), el modo de planificación puede ayudarte a esbozar pasos antes de tocar código, y snapshots/rollback sirven como checkpoints mientras iteras. Al terminar, exportar el código facilita revisar el diff final y mantener un historial limpio.
Sabe cuándo parar y entregar
Para cuando entregar:
Si dividir un gran formulario quitó estado enmarañado y tus tests cubren validación y envío, publícalo. Guarda las ideas restantes en un pequeño backlog para más adelante.
Los refactors en React suelen cambiar identidad y tiempos sin que lo notes. Los fallos de comportamiento más comunes incluyen:
key.Asume que un cambio estructural puede ser un cambio de comportamiento hasta que las pruebas demuestren lo contrario.
Usa un objetivo ajustado y comprobable, centrado en la estructura, no en “mejoras”. Un buen objetivo puede leerse así:
Evita metas como “mejorarlo” a secas, salvo que tengas una métrica concreta y un cuello de botella identificado.
Trata al componente como una caja negra y anota lo que los usuarios pueden observar:
Si tus notas son aburridas y específicas, son útiles.
Añade pruebas de caracterización que describan lo que el componente hace hoy, incluso si es raro.
Objetivos prácticos:
Asegura resultados en la UI, no llamadas internas de hooks.
Pídelo que actúe como un compañero cuidadoso:
No aceptes un diff tipo “re-escritura” grande; exige cambios incrementales que puedas verificar.
Empieza por extraer piezas presentacionales puras:
Primero copia y conecta; luego limpia. Tras separar la UI de forma segura, afronta estado y efectos en pasos más pequeños.
Usa claves estables ligadas a la identidad real (por ejemplo, un ID), no índices de array.
Las claves por índice pueden “funcionar” hasta que ordenas, filtras, insertas o borras filas; entonces React reutiliza instancias equivocadas y aparecen bugs como:
Si tu refactor cambia las keys, considéralo de alto riesgo y prueba los casos de reordenado.
Evita guardar en useState valores derivados cuando se pueden calcular.
Enfoque seguro:
Usa puntos de control para que cada paso sea reversible:
Si trabajas en Koder.ai, los snapshots y rollback complementan los commits normales cuando un experimento sale mal.
Deténte cuando el comportamiento esté bloqueado y el código sea claramente más fácil de cambiar. Buenas señales para parar:
Mete las ideas restantes en un backlog (accesibilidad, rendimiento, limpieza) como trabajo futuro.
filteredRowsrowsqueryuseMemo solo si la computación es cara.Esto reduce comportamientos extraños y hace el componente más predecible.