Saltar al contenido

Cómo reportarle un bug a la IA para que lo arregle bien

Guía/ 12 min de lectura

Deja de escribir «arregla el bug». Dale a la IA el error exacto, cómo reproducirlo y dónde buscar, y pídele la causa antes del cambio.

  • IA
  • Claude Code
En este artículo (9)
  1. Por qué «arregla el bug» no funciona
  2. 1. El error exacto: mensaje completo y stack trace
  3. 2. Cómo reproducirlo: qué hiciste, qué esperabas, qué pasó
  4. 3. Dónde buscar: archivo, función o commit sospechoso
  5. El extra: pedirle a la IA la causa antes del cambio
  6. Ejemplo completo: antes y después del pedido
  7. Errores comunes
  8. Preguntas frecuentes
  9. Checklist

Para reportarle un bug a la IA y que lo arregle bien, dale tres cosas: el error exacto con su stack trace, los pasos para reproducirlo (qué hiciste, qué esperabas y qué pasó) y dónde buscar. Después pídele que te explique la causa antes de cambiar código. Con eso deja de adivinar.

Sirve para Claude Code, Cursor o cualquier agente que lea tu repositorio. Lo vas a ver con un bug real que creamos y ejecutamos en el carrito de una tienda de prueba: el error que dio, el pedido vago, el pedido completo y el arreglo con sus pruebas. Si tu agente todavía no tiene contexto fijo del proyecto, empieza por qué contexto necesita un agente de IA.

Por qué «arregla el bug» no funciona

Cuando escribes «arregla el bug», la IA no sabe qué error viste, cómo provocarlo ni qué significa «arreglado» para ti. Tiene que adivinar las tres cosas. La guía de prompting de Anthropic lo explica así: Claude responde mejor a instrucciones claras y explícitas, y conviene pensar en él como un empleado brillante pero nuevo, que no conoce tus normas ni tu flujo de trabajo. Su prueba rápida: enséñale tu pedido a un colega sin contexto; si él se confunde, Claude también.

Las buenas prácticas de Claude Code usan justo un bug como ejemplo. En lugar de «fix the login bug», proponen describir el síntoma, decir dónde buscar y pedir un test que falle antes del arreglo. Y la receta para arreglar bugs de la misma documentación recomienda darle el comando que reproduce el problema y muestra el stack trace, los pasos para reproducirlo y si el error es intermitente o constante.

El riesgo de un pedido vago no es solo perder tiempo. Es que la IA arregle el síntoma: que el error deje de salir en la línea donde salta mientras la causa sigue ahí. Más abajo lo vas a ver con salidas reales.

el mismo bug, dos pedidospedido vago«arregla el bugdel carrito»la IA tiene que adivinar:· qué error· cómo se reproduce· dónde está· qué es «arreglado»pedido completoerrorTypeError: Cannot read propertiesof undefined (reading 'precio')at totalCarrito (carrito.js:15:20)pasosagrego TAZA y CAFE, quito TAZAesperaba 18000; el total falladóndequitarLinea() en src/carrito.jsfalla desde el botón «quitar»pideprimero la causa, sin editar;luego un test y el arreglocada línea le quita a la IA una suposicióncon el pedido vago puede tapar el síntoma y dejar la causa

Desliza la figura para verla completa

Lo que falta en «arregla el bug»Qué hace la IA sin esoQué le das
El error exactoBusca por todo el repositorio o supone cuál esEl mensaje completo y el stack trace
La reproducciónNo puede comprobar que lo arreglóQué hiciste, qué esperabas, qué pasó y el comando
Dónde buscarLee archivos hasta orientarseArchivo, función o commit sospechoso
Qué es «arreglado»Se detiene cuando parece arregladoUn test que hoy falla y tiene que pasar

1. El error exacto: mensaje completo y stack trace

Copia el error tal como sale, completo. «Sale algo de undefined» no sirve; el mensaje exacto y el stack trace dicen el tipo de error, la propiedad que falló y la línea. Esto es lo que imprimió la tienda de prueba al correr sus pruebas con Node 22 (la tienda vive en la carpeta T:\tienda):

✖ total después de quitar un producto (0.253ms)
  TypeError: Cannot read properties of undefined (reading 'precio')
      at totalCarrito (file:///T:/tienda/src/carrito.js:15:20)
      at TestContext.<anonymous> (file:///T:/tienda/test/carrito.test.js:17:16)
      at Test.runInAsyncScope (node:async_hooks:214:14)
  1. La primera línea dice qué prueba falló y cuánto tardó.
  2. TypeError: Cannot read properties of undefined (reading 'precio'): el código intentó leer precio de algo que vale undefined. Es la línea que hay que copiar sin cambiar ni una palabra, porque se puede buscar tal cual.
  3. at totalCarrito (…/src/carrito.js:15:20): el primer marco del stack trace. Función, archivo, línea 15 y columna 20. Ahí salta el error, que no siempre es donde nace.
  4. at TestContext.<anonymous> (…/carrito.test.js:17:16): quién llamó a esa función, la línea 17 de la prueba.
  5. Las líneas con node: son internas del runner de pruebas de Node. Puedes pegarlas; casi nunca hacen falta.

Si el error sale en el navegador, copia el texto de la consola de DevTools. Si viene de una petición, agrega el código de estado y el cuerpo de la respuesta de la pestaña Network. Una captura ayuda (Claude Code acepta imágenes pegadas en el prompt), pero el texto se puede buscar en el código. Desde la terminal también puedes pasar la salida directo, como sugiere la documentación: cat error.log | claude -p "...".

2. Cómo reproducirlo: qué hiciste, qué esperabas, qué pasó

Con el error, la IA sabe qué falló. Con la reproducción, puede provocarlo ella misma y comprobar después que ya no pasa. Son tres líneas:

  • Qué hiciste, en orden: «Agrego TAZA (2 piezas) y CAFE (1), quito TAZA y pido el total».
  • Qué esperabas, con números si los hay: «Total de 18000 centavos y una sola línea en el carrito».
  • Qué pasó: «TypeError en totalCarrito; el total no se calcula».

Agrega el comando que lo reproduce (npm test, una URL, un curl) y si pasa siempre o solo a veces. Esa última pista la pide la documentación de Claude Code, y por experiencia cambia la búsqueda: un error intermitente suele apuntar a tiempos, caché o datos, no a una sola línea.

La mejor reproducción es una prueba que falle. Esta es la de la tienda:

test("total después de quitar un producto", () => {
  const carrito = { lineas: [] };
  agregarLinea(carrito, { sku: "TAZA", precio: 25000, cantidad: 2 });
  agregarLinea(carrito, { sku: "CAFE", precio: 18000, cantidad: 1 });
  quitarLinea(carrito, "TAZA");
  assert.equal(totalCarrito(carrito), 18000);
});
  1. Empieza con un carrito vacío: { lineas: [] }.
  2. Las dos llamadas a agregarLinea son el «qué hiciste»: dos productos, con precios en centavos.
  3. quitarLinea(carrito, "TAZA") es el paso que dispara el bug.
  4. assert.equal(…, 18000) es el «qué esperabas», escrito de forma que una máquina lo compruebe.

3. Dónde buscar: archivo, función o commit sospechoso

La IA puede leer todo el repositorio, pero cada archivo que lee para orientarse cuesta tiempo y contexto. Tú sabes cosas que el código no dice: qué cambió ayer, qué botón es nuevo, qué archivo tocaste al último. Dilo: «El error salta en totalCarrito, pero empezó cuando agregamos el botón de quitar. Revisa quitarLinea en src/carrito.js».

En Claude Code puedes escribir @ y la ruta (por ejemplo @src/carrito.js) para incluir el archivo en el mensaje. Si usas git, el commit sospechoso es una pista excelente: git log --oneline -5 te da los últimos cinco para citarlos. Cómo dejar commits pequeños que sirvan para esto está en git para trabajar con agentes de IA.

«Dónde buscar» es una pista, no un diagnóstico. Si no tienes idea, dilo, y pide que busque primero sin editar.

las 3 piezas de un buen reporte de bug01el error exactomensaje + stack traceTypeError: Cannot read properties ofundefined (reading 'precio')at totalCarrito (src/carrito.js:15:20)02cómo reproducirlohiciste · esperabas · pasóhice: agregar TAZA y CAFE, quitar TAZAesperaba: total 18000, una líneapasó: el total falla con TypeError03dónde buscararchivo · función · commitsrc/carrito.js · quitarLinea()empezó con el botón «quitar»el error salta en totalCarrito()con las tres, la IA empieza por la causasin la tercera, empieza por leer medio repositorio

Desliza la figura para verla completa

El extra: pedirle a la IA la causa antes del cambio

Las tres piezas le dicen a la IA qué pasa. Falta decirle cómo trabajar: primero la causa, después el cambio. La guía de Anthropic explica que los modelos actuales siguen las instrucciones con precisión: si pides sugerencias, a veces solo sugieren; si pides cambios, cambian. Así que, si escribes «arréglalo», va a editar. Pedir la causa por separado te da un punto para revisar antes de que exista el arreglo:

Antes de cambiar código, explícame la causa: qué línea la provoca y por qué.
No edites archivos todavía.

La misma guía trae un fragmento para que Claude no especule sobre código que no ha abierto y lea los archivos antes de responder. Cuando la explicación te convence, pide el arreglo con su prueba: «Arregla la causa, no el síntoma. Agrega un test que hoy falle y corre npm test al terminar». Las buenas prácticas de Claude Code insisten en eso: darle algo que pueda correr y que responda pasa o falla, y pedirle evidencia, el comando que corrió y su salida, en lugar de un «ya quedó». Si usas Claude Code, plan mode hace este paso de forma natural: lee y propone, pero no edita hasta que apruebas.

primero la causa, después el cambiocausaexplica por qué fallasin editar archivosarreglocambio mínimoen la causa, no en el síntomapruebatest que reproduce+ la suite completa¿falla? vuelve a la causa con la salida nuevaen el carrito de pruebadelete deja un huecoen carrito.lineassplice(i, 1) si i !== -1si i es -1, no toca nada4 de 4 en verdenode --testun arreglo sin causa suele tapar el síntomael test que reproduce el bug es la prueba de que se fue

Desliza la figura para verla completa

Ejemplo completo: antes y después del pedido

Este es el carrito de la tienda de prueba. Node 22, sin dependencias, precios en centavos:

// Carrito de la tienda de prueba. Precios en centavos.

export function agregarLinea(carrito, linea) {
  carrito.lineas.push(linea);
}

export function quitarLinea(carrito, sku) {
  const i = carrito.lineas.findIndex((l) => l.sku === sku);
  delete carrito.lineas[i];
}

export function totalCarrito(carrito) {
  let total = 0;
  for (const linea of carrito.lineas) {
    total += linea.precio * linea.cantidad;
  }
  return total;
}
  1. agregarLinea agrega la línea al final del arreglo con push.
  2. quitarLinea busca el índice del SKU con findIndex y lo borra con delete. Aquí está el bug.
  3. totalCarrito recorre las líneas con for...of y suma precio por cantidad. Aquí, en la línea 15, salta el error.

El pedido vago:

El total del carrito falla, arregla el bug.

El pedido completo, con las tres piezas y el extra:

Error al correr npm test:
TypeError: Cannot read properties of undefined (reading 'precio')
    at totalCarrito (file:///T:/tienda/src/carrito.js:15:20)
    at TestContext.<anonymous> (file:///T:/tienda/test/carrito.test.js:17:16)

Cómo reproducirlo: agrego TAZA (2) y CAFE (1), quito TAZA y pido el total.
Esperaba: total 18000 y una sola línea en el carrito. Falla siempre.
Dónde buscar: salta en totalCarrito, pero empezó con el botón de quitar.
Revisa quitarLinea en @src/carrito.js.

Antes de cambiar código, explícame la causa. No edites todavía.

La causa, en una frase: delete carrito.lineas[i] borra el elemento, pero no cambia la longitud del arreglo. MDN lo explica: borrar un elemento de un arreglo con delete no afecta length y deja un espacio vacío; para quitarlo de verdad se usa splice(). Después, for...of recorre ese hueco como undefined, y leer precio de undefined lanza el TypeError de la línea 15. El error salta en totalCarrito, pero nace en quitarLinea. Lo comprobamos en Node: forEach y reduce se saltan el hueco y for...of no, por eso el bug puede esconderse hasta que alguien cambia el ciclo.

Un arreglo que solo mira la línea del error se ve así, y hace pasar la prueba del total:

  for (const linea of carrito.lineas) {
    if (!linea) continue;
    total += linea.precio * linea.cantidad;
  }

Pero el hueco sigue ahí. Con una prueba más, que el carrito quede con una sola línea (lo que mostraría el contador del carrito), el parche falla:

✖ quitar un producto deja una sola línea (0.7698ms)
  AssertionError [ERR_ASSERTION]: Expected values to be strictly equal:

  2 !== 1

El arreglo de la causa cambia una línea de quitarLinea:

export function quitarLinea(carrito, sku) {
  const i = carrito.lineas.findIndex((l) => l.sku === sku);
  if (i !== -1) carrito.lineas.splice(i, 1);
}
  1. findIndex devuelve el índice del SKU, o -1 si no está.
  2. if (i !== -1): sin esta guarda, splice(-1, 1) quitaría el último producto del carrito. Lo comprobamos en Node y lo fija una cuarta prueba.
  3. splice(i, 1) quita el elemento y recorre los demás: la longitud baja y no quedan huecos.

Con el arreglo, pasan las cuatro pruebas:

✔ total con dos productos (0.9207ms)
✔ total después de quitar un producto (0.2106ms)
✔ quitar un producto deja una sola línea (0.1404ms)
✔ quitar un SKU que no está no cambia el carrito (0.1219ms)
ℹ tests 4
ℹ pass 4
ℹ fail 0

Una aclaración: el bug, los dos arreglos y las pruebas los escribimos y corrimos nosotros para que veas salidas reales. Lo que enseña el ejemplo es el pedido. Con el vago, el parche de una línea era una respuesta razonable; con el completo, que exige una sola línea en el carrito y la causa primero, deja de serlo.

Errores comunes

  • Resumir el error. «Sale algo de undefined» obliga a adivinar. Copia el mensaje y el stack trace completos.
  • Pegar solo la última línea del stack trace. La más útil suele ser la primera que menciona un archivo tuyo.
  • Decir qué pasó sin decir qué esperabas. Sin el resultado correcto, la IA no sabe cuándo terminó.
  • Mandar solo una captura recortada. Ayuda, pero el texto se puede buscar y copiar en el código.
  • Pedir el arreglo sin pedir la causa. Así es como un parche tapa el síntoma.
  • Aceptar «ya quedó» sin evidencia. Pide el comando que corrió y su salida.
  • Juntar tres bugs en un mensaje. Uno por pedido, cada uno con su prueba.

Preguntas frecuentes

¿Sirve igual con Claude Code, Cursor o ChatGPT?

Sí. Las tres piezas son información que ningún modelo puede sacar de tu código. Lo que cambia es cómo adjuntas archivos (en Claude Code, con @) y si el agente puede correr por su cuenta el comando que reproduce el bug.

¿Qué hago si no hay mensaje de error?

Entonces el resultado incorrecto es tu error: describe qué viste y qué esperabas, con datos, y agrega lo que sí hay, como la petición en la pestaña Network, un valor en la consola o un log. Un bug sin mensaje es justo donde una prueba que falle vale más.

¿Tengo que encontrar yo dónde está el bug?

No. «Dónde buscar» es lo que sabes y el código no dice: qué cambió, desde cuándo falla, qué parte es nueva. Si no sabes nada, dilo y pide a la IA que investigue primero sin editar.

¿Cuánto del stack trace pego?

Todo, si es corto. Si es muy largo, pega el mensaje, las primeras líneas que mencionan archivos de tu proyecto y aclara que el resto es del framework. Mejor que sobre a que falte la línea clave.

Checklist

  • Copiaste el mensaje de error completo, sin resumirlo.
  • Incluiste el stack trace, al menos las líneas con archivos de tu proyecto.
  • Escribiste qué hiciste, qué esperabas y qué pasó.
  • Diste el comando que reproduce el bug y si falla siempre o a veces.
  • Señalaste el archivo, la función o el commit sospechoso.
  • Pediste la causa antes del cambio.
  • Pediste un test que hoy falle y la salida de las pruebas al terminar.

Un buen reporte de bug es contexto puntual; el contexto fijo de tu proyecto va en qué contexto necesita un agente de IA. Antes de pedir el arreglo, deja un commit limpio para poder volver atrás, como explico en git para trabajar con agentes de IA. Y el método completo, del pedido a la revisión, está en mi flujo de 4 pasos con Claude Code.

¿Viste esto en Instagram? Comenta BUG en el Reel y te mando la guía.

Escrito por

Luis Morales

Luis Morales

Desarrollador frontend y Shopify, EcomLabs

@luismoralesdev en Instagram

Publicado el 30 de octubre de 2026 · actualizado el 1 de noviembre de 2026

← Blog