English

A.I. Can't Fix What You Can't Diagnose

Un agente de IA escribe cien líneas de código que funcionan y luego produce una línea que está mal para la versión del framework que realmente estás usando. Eso no es lo interesante: todas las herramientas tienen fallos. Lo interesante es lo que pasa después: el agente no lo sabe. No tiene ninguna señal que diga "estoy atascado". Lo único en la sala capaz de romper ese bucle es una persona que reconozca el fallo y sepa nombrarlo.

El agente no sabe cuándo está atascado

La confianza de un modelo no está calibrada con su exactitud. Cuando genera código para una librería que apenas recuerda —una versión cuya API cambió después del entrenamiento, un método que se renombró, un valor que antes era síncrono y ya no lo es— el resultado se ve exactamente igual de seguro que el código que ha visto diez mil veces. No hay ninguna alarma interna que se dispare.

Dale el mensaje de error y probará cosas. A veces funciona. Pero cuando el error es el síntoma de un desajuste de versión y no de un error de lógica, el agente tiende a atacar el síntoma: agrega una validación de nulo, envuelve todo en un try/catch, reestructura el componente. Cada intento es plausible y cada uno apunta a la capa equivocada, porque su modelo mental del framework va una versión atrás y nada en el error se lo advierte.

Un caso concreto: Next.js 15 convirtió los params de ruta en promesas

Esto no es hipotético y se puede verificar. En el App Router de Next.js 15, las props params y searchParams que reciben páginas y layouts pasaron a ser asíncronas: ahora son promesas, mientras que en Next.js 14 eran objetos normales que podías desestructurar directamente. Un modelo entrenado sobre todo con código de la época de Next.js 14 escribe la forma antigua, y la forma antigua falla.

// Next.js 14 (App Router) — params es un objeto normal
export default function Page({ params }: { params: { id: string } }) {
  return <h1>Product {params.id}</h1>;
}

// Next.js 15 (App Router) — params es una Promise; hay que esperarla
export default async function Page({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
  return <h1>Product {id}</h1>;
}

Fíjate en las dos cosas que cambian juntas: el componente pasa a ser async y la prop se espera con await antes de leer un campo de ella. Lo mismo aplica a searchParams y a params dentro de generateMetadata.

Un desarrollador que construía una tienda en vivo con Cursor se topó exactamente con esto. Las páginas generadas desestructuraban params a la manera antigua, la aplicación lanzaba errores y el agente no tenía idea de por qué. Él reconoció el cambio gracias a su propio conocimiento del framework, le pidió al agente aplicar await a params en todos los lugares donde lo usara, y el agente recorrió el proyecto y lo corrigió. Tiempo total: una frase. El agente podía hacer el trabajo; lo que no podía era identificarlo.

Tu conocimiento es la red de seguridad, no la mano de obra

Fíjate en el reparto de tareas de esa historia. El desarrollador no escribió nada del código. No rastreó cada archivo que tocaba params, no refactorizó los componentes, no escribió los tipos. Todo eso quedó en manos del agente, que es genuinamente bueno en ello.

Lo que él aportó fue lo único que el agente, por estructura, no puede aportar: el diagnóstico. Sabía en qué versión del framework estaba el proyecto, sabía que esa versión había cambiado ese comportamiento concreto y pudo enunciar la solución en una frase accionable.

Esa es la forma de toda la relación. El agente es un compañero rápido, incansable y competente en muchos frentes, con una limitación dura: no puede señalar sus propios puntos ciegos. Tú eres la parte del sistema que nota cuándo el resultado se torció en silencio. Ese trabajo exige conocer el stack, pero mucho menos de lo que exigiría escribirlo todo tú.

Sus propias palabras, de aquella sesión: si yo no fuera desarrollador y no supiera esto, seguiría sentado frente a ese error y probablemente no habría podido avanzar.

Si no eres desarrollador, esto es un camino, no un muro

Es fácil leer lo anterior como "primero tienes que ser ingeniero". Esa es la lección equivocada, y además desalentadora. La versión realista es más acotada y mucho más alcanzable: necesitas suficiente conocimiento práctico del stack concreto sobre el que construyes como para reconocer cuándo algo va mal y describirlo. No lo suficiente para escribir el framework. Lo suficiente para dirigirlo.

• Sabe en qué versiones estás. Lee tu package.json (o su equivalente). Cuando algo se rompa de forma rara, la primera pregunta es "¿qué versión mayor es esta y qué cambió en ella?", y las notas de la versión suelen responderlo en un párrafo.
• Lee la guía de migración de la versión mayor que usas. Los frameworks las publican justamente porque los cambios incompatibles sorprenden a todo el mundo. Veinte minutos con una guía de actualización te dan el vocabulario para nombrar la mitad de los bugs que te va a entregar un agente.
• Aprende a leer el error, no solo a pegarlo. No necesitas arreglarlo. Necesitas notar si apunta a tu lógica o a cómo el framework espera ser invocado: esas dos cosas se piden de forma distinta.
• Pídele al agente que te enseñe mientras trabaja. "Explícame por qué esto necesita await" es una clase gratis a mitad de tarea, y la explicación suele poder contrastarse con la documentación en treinta segundos.
• Dale la versión explícitamente. Un "estamos en Next.js 15 App Router" en tu archivo de reglas o en el prompt elimina toda una familia de conjeturas de sintaxis vieja antes de que ocurran.

Cuándo sospechar de un problema de versión

• El error aparece en la fontanería que genera el framework (rutas, obtención de datos, configuración) y no en tu lógica de negocio.
• Los arreglos del agente dan vueltas sin converger: tres intentos distintos, el mismo fallo.
• El código se ve correcto de manual y aun así falla. Ese suele ser el indicio: es correcto de manual, pero para la versión mayor anterior.
• Acabas de actualizar, creaste un proyecto nuevo sobre la última versión, o elegiste una librería que publicó una versión mayor este año.

Cuando eso se alinea, deja de pedirle al agente que lo arregle y ve a leer qué cambió. Después, entrégale la respuesta.