Cirugía de código con IA · el protocolo de 7 fases que deja tu app impecable por dentro

¿Para quién es esto?

Para quien lleva semanas o meses construyendo con IA y siente que la app ya no es tan fácil de tocar como al principio. Añadir una función pequeña se volvió lento, aparecen bugs raros, la IA se pierde en su propio código. No eres tú: es el código, que se ensució sin que nadie lo limpiara. Este recurso es el aseo profundo — la cirugía que lo deja impecable por dentro sin cambiar nada de lo que ves por fuera. No necesitas programar: necesitas saber qué pedirle a tu agente y en qué orden.

1. El momento: cuando la app funciona por fuera pero cruje por dentro

Al principio todo es magia. Le dices a la IA "añade una pantalla de perfil" y aparece. "Ahora un botón para exportar", y aparece. Vas rápido, muy rápido. Pero hay un momento — casi siempre entre la tercera y la décima semana — en que algo cambia. Pedir una función pequeña ya no es instantáneo. La IA tarda más, se confunde, toca cosas que no debía. Aparecen bugs en sitios que ni tocaste. La app funciona, pero moverla se volvió pesado, como caminar con barro en los zapatos.

Ese es EL momento. No pasó nada dramático: no se rompió nada visible. Lo que pasó es invisible y se llama deuda técnica. La IA construyó rápido y, como todo el que construye rápido, dejó escombros: código que ya nadie usa pero sigue ahí, la misma lógica copiada en cinco archivos, tipos any que apagan todas las alarmas, animaciones montadas de cualquier forma. Nada de eso se ve en la pantalla. Todo eso hace que cada cambio futuro sea más difícil.

Imagínalo así

Un cirujano no te cambia la cara. Entra, arregla lo de dentro — quita lo que sobra, cose bien, refuerza lo débil — y sales con la misma cara de antes, pero sano por dentro. La cirugía de código es exactamente eso: nadie que use tu app notará un solo cambio, pero por dentro queda limpia, tipada y sin escombros. Si algo se ve distinto después, no fue cirugía: fue un accidente en la mesa de operaciones.

2. El dolor: de dónde sale y por qué la IA ensucia (aunque escriba "bien")

Aquí lo importante y honesto: la IA no escribe código malo. Escribe código que funciona. El problema es que optimiza para "que funcione ahora", no para "que sea fácil de mantener dentro de tres meses". Y esas dos cosas tiran en direcciones distintas. Por eso, aunque cada trozo esté bien, la suma se ensucia. Estos son los cuatro tipos de escombro que deja, y por qué los deja:

De dónde sale la suciedad (los cuatro escombros)

Código muerto. Le pides un cambio, la IA reescribe una función nueva… pero olvida borrar la vieja. Se queda ahí, huérfana, sin que nadie la llame. Multiplica esto por cientos de cambios y tienes archivos enteros que ya no sirven para nada.
Duplicación. La IA no siempre recuerda que ya escribió esa misma lógica antes, así que la vuelve a escribir. Ahora la misma regla vive en cinco sitios. El día que cambie la regla, hay que corregir cinco veces — y siempre se olvida uno.
`any` y tipos flojos. Cuando la IA no está segura del tipo de un dato, toma el atajo: lo marca como any. Con eso apaga todas las alarmas que TypeScript tiene para avisarte de errores. El código compila… y explota en producción.
Animaciones y efectos montados a lo bruto. La IA pone gradientes animados, desenfoques, sombras — se ven bien, pero mal montados hacen sudar a la GPU y la app se siente lenta en móviles y portátiles modestos.

El dolor real: accidente lento, no apocalipsis

Nada de esto va a tumbar tu app mañana. Es más traicionero: es una erosión lenta. Cada semana cuesta un poco más añadir cosas, la IA se equivoca un poco más seguido, los bugs aparecen un poco más. No hay un día del desastre; hay un deslizarse gradual hacia un código que da miedo tocar. La cirugía frena esa erosión antes de que el proyecto se vuelva imposible de mover.

Qué pasa si NO lo haces

Si nunca limpias, llegas al punto en que la propia IA se ahoga en tu código. Cuando hay tanto duplicado y tanto muerto, la IA no sabe cuál de las cinco copias es la buena, o toca la función huérfana en vez de la viva, e introduce bugs nuevos al arreglar los viejos. El código sucio no solo te frena a ti: frena a la herramienta que lo construye. La cirugía le devuelve a la IA un lienzo limpio sobre el que seguir trabajando.

3. Las 7 fases de la cirugía (el corazón de todo)

Un cirujano no abre y hurga al azar: sigue un protocolo, en orden, paso a paso. La cirugía de código es igual. Son siete fases, y el orden importa: primero quitas lo muerto (para no limpiar código que ibas a borrar), luego fundes duplicados, luego endureces animaciones, luego el rendimiento de React, luego los tipos, luego calmas la GPU, y al final emites un reporte de salud. Aquí va cada una.

Fase 1 · Eliminar código muerto

Lo primero es sacar de la mesa todo lo que ya no respira. Es la fase más rentable porque limpia el terreno para todas las demás: no tiene sentido optimizar una función que vas a borrar.

Qué se caza en la Fase 1

Archivos huérfanos — ficheros que nadie importa desde ningún sitio. Están ahí de una versión vieja que nunca se borró.
Exports sin consumidores — funciones o componentes exportados que nadie usa. Se exportaron "por si acaso" y el por si acaso nunca llegó.
Variables, funciones e imports sin usar — declarados y olvidados. El linter suele marcarlos, pero la IA los deja porque "no molestan". Sí molestan: son ruido.
Ramas de código inalcanzables — condiciones que nunca pueden ser verdad, código después de un return, if que ya nadie dispara.

El seguro antes de borrar

Borrar da vértigo — ¿y si eso sí se usaba? Por eso la regla número uno de esta fase: haz un commit en GitHub antes de empezar. Si la cirugía borra algo que hacía falta, vuelves atrás con un clic. Nunca operes sin red. (Al final te dejo el recurso de GitHub como botón de deshacer.)

Fase 2 · Auditar duplicados

Con el terreno limpio, ahora buscas lo que está repetido. La regla del oficio es simple: si algo aparece tres veces o más, deja de ser casualidad y pasa a ser un patrón que merece un solo lugar donde vivir.

Los cuatro tipos de duplicado y su cura

Lógica repetida → sácala a una función ayudante (helper) que ambos sitios llaman. Una regla, un solo lugar.
Números y textos mágicos repetidos (el mismo 48, la misma URL, el mismo color) → centralízalos en constantes con nombre. Cambias una vez, cambia en todos lados.
JSX repetido tres o más veces (la misma tarjeta, el mismo botón con leves variantes) → conviértelo en un subcomponente que recibe sus diferencias por props.
El patrón `useState` + su handler repetido (el mismo estado con su función de actualización copiado en varios componentes) → extráelo a un hook propio (un custom hook) que encapsula la lógica una sola vez.

El límite del refactor

Cuidado con pasarse. No todo lo que se parece es lo mismo. Dos trozos que HOY lucen iguales pero cambian por razones distintas no deben fundirse — unirlos crea un acoplamiento que luego duele más que la duplicación. La regla: funde lo que cambia por la MISMA razón. Si dudas, es mejor dejar dos copias claras que una abstracción confusa.

Fase 3 · Cumplir las reglas de animación

Las animaciones son donde la IA improvisa más y donde más fallos sutiles deja — cosas que no rompen pero que hacen que la app se sienta "barata": parpadeos, saltos, transiciones que no arrancan. Estas son las reglas concretas que la cirugía verifica (aplican a librerías de animación de React como Motion / Framer Motion, el estándar del ecosistema):

Las 5 reglas de animación que se auditan

Animar hacia/desde `transparent` puede parpadear → usa rgba(0,0,0,0) en su lugar. Cuando interpolas la palabra transparent con un color, la transición puede dar un parpadeo feo a mitad de camino; rgba(0,0,0,0) interpola limpio.
Sin `transition` duplicado — una animación con dos definiciones de transición peleando entre sí da un resultado impredecible. Una sola fuente de verdad para el timing.
No animar el atajo `border` (el shorthand que junta grosor, estilo y color) → anima propiedades separadas como borderColor. El shorthand no interpola limpio.
`background` → `backgroundColor` en animaciones — animar el atajo completo background es problemático; anima solo la propiedad específica que cambia.
Keys estables en listas que entran y salen (AnimatePresence) — si los elementos de una lista animada no tienen una key estable y única, las animaciones de salida se rompen y los elementos saltan. La key debe ser un id real, nunca el índice del array.

Fase 4 · Rendimiento de React

Aquí la cirugía busca el trabajo que React repite sin necesidad. Cada re-render innecesario es un poquito de lentitud; sumados, hacen que la app se sienta pesada. Cuatro cosas concretas se revisan:

Los 4 chequeos de rendimiento React

Handlers que se pasan como props sin `useCallback` → envuélvelos. Si no, cada render crea una función nueva y obliga a los componentes hijos a re-renderizarse aunque nada haya cambiado.
Cómputos caros sin `useMemo` (filtrar/ordenar una lista grande, cálculos pesados) → memoízalos. Si no, se recalculan en cada render aunque los datos sean idénticos.
`useEffect` con dependencias mal declaradas — dependencias de más disparan el efecto sin razón; dependencias de menos hacen que use datos viejos. Ambas son bugs. El array de dependencias debe listar exactamente lo que el efecto usa.
`.map` sin `key` estable — renderizar listas sin una key única (o usando el índice) hace que React se confunda al reordenar y pierda estado. Cada elemento necesita su id propio.

Optimizar no es meter memoize a todo

El error de principiante en esta fase es envolver TODO en useCallback y useMemo "por si acaso". No: memoizar también cuesta (memoria, complejidad). La cirugía solo memoiza donde hay un beneficio real y medible — un handler que baja a muchos hijos, un cómputo de verdad caro. Optimizar de más es su propia forma de suciedad.

Fase 5 · Higiene de TypeScript

TypeScript es el sistema de alarmas de tu código: te avisa antes de que un error llegue al usuario. Pero solo funciona si le dejas ver los tipos. Cada any es una alarma que alguien apagó. Esta fase las vuelve a encender.

La limpieza de tipos

`any` → un tipo real, o `unknown` — el any desactiva todas las comprobaciones. Si de verdad no sabes el tipo, usa unknown, que te obliga a verificarlo antes de usarlo (seguro), en vez de any, que no obliga a nada (peligroso).
Revisar los casts `as Tipo` — decirle a TypeScript "confía en mí, esto es de este tipo" es una promesa que puede ser mentira. Cada as es un punto donde el compilador dejó de comprobar. Se revisan uno por uno: ¿es cierto, o es un parche?
Internalizar exports de un solo uso — si un tipo o función se exporta pero solo se usa en su propio archivo, no debería ser público. Bájalo a privado: menos superficie, menos ruido.
Tipar las props de los componentes — cada componente debe declarar qué props recibe y de qué tipo. Props sin tipar son any disfrazados.

Fase 6 · Auditar el colapso de la GPU

Esta es la fase que casi nadie conoce y la que más se nota en dispositivos modestos. Ciertos efectos visuales son bellísimos pero brutalmente caros de dibujar: si abusas de ellos, la tarjeta gráfica se satura y la app va a tirones. La cirugía busca los tres culpables clásicos:

Los 3 asesinos silenciosos de la GPU

Gradiente cónico (`conic-gradient`) animado → muévelo a una animación CSS con @keyframes. Animar un gradiente cónico por JavaScript en cada frame es carísimo; con keyframes el navegador lo optimiza.
Muchos `repeat: Infinity` (varias animaciones en bucle infinito a la vez) → consolídalas. Diez animaciones eternas corriendo en paralelo mantienen la GPU despierta y quemando batería sin parar. Únelas o reduce las que de verdad hacen falta.
`backdrop-blur` en muchos elementos pequeños repetidos → si el mismo desenfoque de fondo se repite en veinte tarjetitas, la GPU lo recalcula veinte veces. Para elementos pequeños y repetidos, un fondo sólido (o semitransparente) se ve casi igual y cuesta una fracción.

Por qué duele el blur

El desenfoque de fondo (backdrop-blur, ese efecto de cristal esmerilado tan de moda) obliga a la GPU a mirar TODO lo que hay detrás del elemento y difuminarlo en tiempo real. Uno solo, grande, no pasa nada. Veinte pequeños repitiéndose es como pedirle a la tarjeta que difumine la pantalla veinte veces por frame. Ahí es donde el portátil de tu usuario empieza a soplar el ventilador.

Fase 7 · El reporte de salud

Toda cirugía termina con un parte. Sin reporte no sabes qué se tocó ni puedes confiar en que no hubo daños colaterales. La última fase es que el agente te entregue un resumen claro, en tu idioma, de todo lo que hizo:

Qué debe incluir el reporte final

Conteo por fase — cuántos archivos huérfanos, cuántos duplicados fundidos, cuántos any eliminados, cuántas animaciones corregidas, etc.
Líneas purgadas — el total de líneas de código muerto que salieron. Es la cifra más satisfactoria: código que ya no tienes que mantener.
Veredicto de "listo para producción" — la confirmación explícita de que no se cambió nada visual ni de comportamiento, solo estructura interna.
Lo que NO tocó y por qué — las cosas que parecían candidatas pero se dejaron a propósito (duplicados que cambian por razones distintas, memoize que no valía la pena). La honestidad de lo que se decidió no hacer.

La regla sagrada de toda la cirugía

Repítela como un mantra y métela en cada prompt: CERO cambios visuales. CERO cambios de comportamiento. La app tiene que verse y comportarse EXACTAMENTE igual antes y después. Si un botón se movió un pixel, si un flujo cambió, si algo dejó de funcionar — no fue cirugía, fue una herida. Ante la duda entre limpiar más o preservar el comportamiento, siempre gana preservar el comportamiento.

4. El hábito: la cirugía es mantenimiento, no una operación única

El error más común es pensar la cirugía como algo que haces una vez, cuando ya está todo hecho un desastre. No. El código de IA se ensucia CONTINUAMENTE, porque cada sesión de construcción deja escombro nuevo. La cirugía no es una operación de urgencia: es la limpieza de dientes que haces cada seis meses para no llegar nunca a la endodoncia.

Los momentos en que SIEMPRE conviene operar

Después de un sprint grande de construcción — cuando la IA acaba de generar mucho código de golpe, ese es el escombro fresco. Límpialo antes de que se acumule sobre él.
Antes de empezar una función importante — dale a la IA un lienzo limpio para construir. Sobre código sucio, construye sucio.
Cuando notas que la IA empieza a confundirse — si la herramienta toca cosas que no debía o se pierde, es señal de que hay demasiado ruido. La cirugía le devuelve claridad.
Un archivo o módulo a la vez, no todo el proyecto de golpe — operar un solo módulo es seguro y revisable. Operar todo a la vez es una cirugía a corazón abierto sin anestesia. Ve por partes.

La frase que lo resume

El error no es que la IA ensucie el código — eso es inevitable, construir rápido siempre deja escombro. El error es no limpiarlo nunca. La cirugía constante es lo que separa un proyecto que se vuelve más fácil de tocar con el tiempo de uno que se vuelve intocable.

5. El prompt maestro · pásaselo a tu agente y opera fase por fase

Aquí está la pieza clave: UN solo prompt que convierte a tu agente de código en un cirujano que aplica las 7 fases, en orden, a un archivo o módulo — sin tocar nada visual. Llena los [corchetes], pégalo, y deja que opere. Un consejo antes: haz un commit en GitHub primero (tu red de seguridad) y apúntale a UN módulo, no a todo el proyecto.

Prompt maestro · la cirugía de código en 7 fasestexto

Actúa como un cirujano de código experto en debug. Vas a operar este archivo/módulo: [RUTA DEL ARCHIVO O CARPETA, ej: src/components/Dashboard/]. El stack es: [ej: React + TypeScript + Motion/Framer Motion + Tailwind].

REGLA SAGRADA E INVIOLABLE: CERO cambios visuales y CERO cambios de comportamiento. La app debe verse y comportarse EXACTAMENTE igual antes y después. Solo limpias y endureces por dentro. Ante cualquier duda entre limpiar más o preservar el comportamiento, SIEMPRE gana preservar el comportamiento. No borres nada si no estás seguro de que no se usa; márcalo y pregúntame.

Aplica estas 7 fases EN ORDEN. No pases a la siguiente sin terminar la anterior. Al final de cada fase, dime en una línea qué encontraste y qué cambiaste.

FASE 1 — CÓDIGO MUERTO: elimina archivos huérfanos (que nadie importa), exports sin consumidores, variables/funciones/imports sin usar, y ramas de código inalcanzables. Antes de borrar algo dudoso, lístamelo y espera mi confirmación.

FASE 2 — DUPLICADOS: busca lógica repetida (→ extrae a un helper), números/textos mágicos repetidos (→ constantes con nombre), JSX repetido 3+ veces (→ subcomponente con props), y el patrón useState+handler repetido (→ custom hook). NO fundas cosas que solo se parecen pero cambian por razones distintas.

FASE 3 — REGLAS DE ANIMACIÓN: corrige transparent→rgba(0,0,0,0), elimina transition duplicado, no animes el shorthand border (usa borderColor), cambia background→backgroundColor en animaciones, y asegura keys estables y únicas (nunca el índice) en listas con AnimatePresence.

FASE 4 — RENDIMIENTO REACT: envuelve en useCallback los handlers que se pasan como props, memoiza con useMemo los cómputos caros, corrige los arrays de dependencias de useEffect (ni de más ni de menos), y añade key estable a cada .map. NO memoices por si acaso: solo donde haya beneficio real.

FASE 5 — TYPESCRIPT: reemplaza cada any por un tipo real o por unknown; revisa cada cast 'as Tipo' (¿es cierto o es un parche?); internaliza los exports que solo se usan en su propio archivo; y tipa las props de todos los componentes.

FASE 6 — COLAPSO DE GPU: mueve gradientes cónicos animados a CSS @keyframes; consolida los repeat:Infinity si hay muchos a la vez; y reemplaza backdrop-blur por un fondo sólido/semitransparente en elementos pequeños que se repiten muchas veces.

FASE 7 — REPORTE DE SALUD: al terminar, entrégame un reporte con: conteo por fase, total de líneas purgadas, la confirmación explícita de que no cambiaste nada visual ni de comportamiento, y una lista de lo que decidiste NO tocar y por qué.

Trabaja fase por fase, muéstrame el diff de cada una, y si algo pone en riesgo la regla sagrada, PARA y pregúntame antes de seguir.

Por qué el prompt va módulo a módulo

Fíjate que el prompt apunta a UN archivo o carpeta, no a todo el proyecto. Es a propósito. Una cirugía enorme de golpe es imposible de revisar — el diff sale con miles de líneas y no puedes confiar en que no se coló un cambio de comportamiento. Módulo a módulo, cada operación es pequeña, revisable y reversible. Cirugía precisa, no demolición.

6. Verifica que la cirugía no dejó heridas

Una cirugía no termina cuando cierras: termina cuando confirmas que el paciente está bien. La regla sagrada (cero cambios de comportamiento) hay que comprobarla, no solo confiar en ella. Hay dos redes de seguridad automáticas que te lo confirman en segundos, y que tu agente puede correr sin que tú programes nada.

terminal

# 1) El chequeo de tipos: cero errores = la cirugía no rompió los contratos
npx tsc --noEmit

# 2) Los tests: si pasaban antes y pasan igual después,
#    el comportamiento se preservó
npm test

El diff es tu radiografía

Antes de aceptar la cirugía, mírale el diff (los cambios) en GitHub Desktop o con git diff. Regla de lectura: casi todo lo que veas deben ser líneas ROJAS (borradas) o movimientos de sitio, no lógica nueva. Si aparecen cadenas de texto que el usuario ve cambiadas, valores por defecto distintos, o condiciones nuevas, ahí hay una posible herida — pregúntale a la IA por qué antes de aceptar.

7. Los caminos más fáciles · qué hace la IA por chat y qué decides tú

Para que no se complique: la mayor parte de la cirugía la hace tu agente de código solo, por el chat. Lo tuyo es dirigir y aprobar. Este es el reparto.

Lo que hace la IA por ti (por el chat)

Recorrer el módulo y detectar el código muerto, los duplicados, los any y las animaciones mal montadas — tú solo le das el prompt maestro.
Aplicar las correcciones fase por fase, mostrándote el diff de cada una.
Correr tsc y los tests para confirmar que no rompió nada.
Escribir el reporte de salud final con los conteos y lo que decidió no tocar.

Lo que decides TÚ (por la web / con botones)

Hacer el commit de seguridad ANTES — tu botón de deshacer. Eso lo haces tú desde GitHub Desktop o el chat, antes de operar.
Aprobar los borrados dudosos — cuando la IA no está segura de si algo se usa, te lo pregunta; la decisión final es tuya.
Revisar el diff — leer los cambios y confirmar que no hay heridas de comportamiento antes de aceptar.
Decidir el alcance — qué módulo se opera y en qué orden. No delegues "opera todo": ve por partes.

En NeuralOS, esta disciplina viene de fábrica

Esta forma de trabajar — construir por un lado y auditar/limpiar por otro, en turnos separados, sin tocar lo que ya funciona — es la misma filosofía con la que se construye NeuralOS por dentro: cada frente se levanta y luego se somete a una pasada de auditoría adversarial antes de darse por bueno. La visión que ya ves tangible en la interfaz — el chat que construye tu app, los editores, el motor de flujos — se apoya en esa costumbre de no dejar que el código se pudra. La idea de fondo del producto es la misma que la de este recurso: que construir rápido y construir limpio no tengan por qué ser enemigos.

El protocolo C-A-R · construir sin bugsLa cirugía es primo hermano de C-A-R: construir y auditar en turnos separados. Este recurso te da el método de auditoría del que nace la disciplina de limpiar sin romper.Guarda todo en GitHub antes de que la IA lo rompaTu red de seguridad antes de cualquier cirugía: el commit que te deja volver atrás con un clic si una fase borra algo que hacía falta.

#cirugía de código#refactor#dead code#typescript#rendimiento#avanzado