Depuración y autocorrección

Tiempo: unos 20 min de lectura + 25 min de práctica

Lo esencial

La primera ejecución de cualquier workflow (flujo de trabajo) se parece al primer vuelo de prueba de un avión prototipo: casi siempre aparece algo que hay que ajustar. La diferencia entre Claude Code y Zapier es que, en la mayoría de los casos, Claude Code se sube él mismo a la cabina y lo arregla: no necesitas saber qué cable se soltó.

Conceptos clave

Los errores en la primera ejecución son normales, no un fracaso
Claude Code encuentra y corrige errores por su cuenta
Delegar la corrección: tú describes el síntoma y el agente (un ejecutor de IA autónomo) hace el diagnóstico y aplica el remedio
Después de la primera prueba exitosa, el workflow se vuelve confiable

Teoría

Por qué la primera ejecución casi siempre falla

🎨 Imagínalo así: la primera ejecución de un workflow es como la primera prueba de manejo de un coche nuevo: todo parece armado, pero solo en la carretera te das cuenta de que una llanta tiene un poco menos de aire.

No es una falla del sistema, es una característica de cualquier automatización. Cuando construyes un workflow, trabajas con suposiciones teóricas: "la API (interfaz de programación de aplicaciones) debería aceptar una solicitud así", "en esta tabla los datos vendrán en este formato", "el endpoint está en esta dirección". La realidad siempre hace ajustes.

En las herramientas tradicionales (Zapier, Make, n8n) eso significa: ves una cruz roja en los registros, copias el error, vas a Google, lees la documentación, regresas, intentas corregir, y así en círculo. Es especialmente frustrante si no sabes de código.

🎨 Imagínalo así: depurar (buscar y corregir errores) sin Claude es como buscar una fuga de gas con los ojos vendados: sabes que algo anda mal, hay olor, pero no sabes dónde exactamente. Claude Code te quita la venda y te señala el lugar con el dedo.

Con Claude Code el esquema es otro: solo describes lo que ves y el agente averigua las causas.

Tres escenarios reales de autocorrección

Escenario 1: Unicode encoding error

Ejecutaste un workflow que reúne noticias y les da formato. En la consola ves algo así:

Escribe esto en el chat

UnicodeDecodeError: 'utf-8' codec can't decode byte 0xe9 in position 14

No sabes qué es un UTF-8 codec ni por qué no decodifica algo. Le escribes a Claude Code: "ejecuté el workflow y me salió este error". El agente:

Lee el registro del error
Encuentra el archivo donde ocurrió
Ve que al trabajar con el texto no se indicó la codificación
Agrega encoding='utf-8' en el lugar correcto
Vuelve a ejecutar y el error desaparece

No escribiste ni una línea de código.

Escenario 2: Cambió el endpoint de la API

El servicio que usas se actualizó y la URL vieja de la API ya no funciona. El workflow devuelve 404 Not Found. Claude Code:

Ve el error 404
Consulta la documentación vigente del servicio (con Context7 MCP, un protocolo para conectar herramientas a la IA, o con una búsqueda)
Encuentra el endpoint nuevo
Actualiza la herramienta en tu proyecto
Prueba, y ahora funciona

Esto es literalmente lo que antes te costaba una hora peleándote con la documentación.

Escenario 3: El ID equivocado de una hoja de Google Sheets

Conectaste el workflow a Google Sheets, pero copiaste mal el ID de la hoja (lo tomaste de la URL, pero no la parte correcta). El agente intenta acceder a la hoja y recibe un error de acceso. Te avisa: "No encuentro una hoja con este ID, revisa que el ID sea correcto". Abres la hoja en el navegador, copias el ID correcto de la URL, se lo mandas al agente, y él actualiza la configuración y sigue.

Este es un ejemplo de cuando el agente no puede corregir solo (necesita un dato tuyo de un sistema externo), pero te dice con claridad qué hace falta, no solo "error".

Cómo reportar bien un error

🎨 Imagínalo así: llamas al médico. Tu papel es describir los síntomas: "me duele aquí, tengo tanta fiebre, ayer comí esto". No hacer el diagnóstico. El diagnóstico es trabajo del médico. Con el agente pasa lo mismo.

Cuando ves un error, tu tarea es describir lo que pasa. No necesitas analizar ni intentar explicar la causa. Simplemente:

Bien:

"Ejecuté el workflow newsletter y veo este texto en la consola: [pegas el error]"
"El workflow se detuvo, esto es lo que dice: [captura de pantalla o texto del error]"
"Parece que algo falló en el paso de Google Sheets; el agente escribió que no puede conectarse"

No hace falta:

Analizar el código tú
Intentar entender la causa técnica
Buscar la solución en Google (salvo que te interese)

Estás delegando. Delegar es decir "este es el síntoma", no "esta es mi teoría y mi plan de tratamiento".

La primera prueba exitosa: el punto de quiebre

🎨 Imagínalo así: la primera ejecución exitosa de un workflow es como el primer despegue de un avión prototipo. Los ingenieros no sabían con certeza qué iba a pasar; ahora lo saben: vuela. Todos los vuelos siguientes serán más confiables, porque el avión ya pasó por condiciones reales.

Cuando el workflow recorre por primera vez todo el camino de principio a fin sin errores, es un momento que vale la pena recordar. A partir de ahí:

Sabes que el workflow funciona en condiciones reales
Tienes la confianza de que se puede desplegar
Todos los errores encontrados ya están corregidos

Los desarrolladores profesionales lo llaman "pasar el smoke test". Tú llegaste ahí no peleándote con el código, sino conversando con el agente.

Claude Code vs. Zapier/n8n: la diferencia clave

🎨 Imagínalo así: Zapier es un juego de LEGO: potente, pero tienes que saber qué bloque va dónde. Claude Code es un maestro de obras al que le dices "quiero un cuarto así" y él se encarga de los bloques.

Situación	Zapier/n8n	Claude Code
Error en los registros	Lo investigas tú	Se lo describes al agente
Cambió la API	Buscas la documentación nueva	El agente la encuentra solo
Hay que ajustar la lógica	Arrastras bloques	Lo dices con palabras
Error incomprensible	Lo copias en Google	Se lo pegas al agente

Lo principal: Zapier y n8n, en su modo habitual, son herramientas para quienes saben configurarlas. Claude Code es una herramienta para quienes saben qué quieren obtener. Los constructores visuales también están recibiendo asistentes de IA, así que la comparación describe la forma habitual de trabajar, no una frontera rígida.

Práctica

Tarea: un error a propósito

Toma el workflow de la lección Primer workflow EN VIVO (automatización de un newsletter). Mete un error a propósito: por ejemplo, cambia el endpoint de la API por uno que no existe (agrega un carácter de más en la URL de la herramienta). Ejecuta el workflow. Obtén el error. Ahora dile al agente: "el workflow falló, aquí está el error, encuéntralo y corrígelo". Observa el proceso: el agente lee el registro, encuentra el problema, lo corrige y vuelve a ejecutar.

Objetivo: comprobar que sabes delegar la corrección de errores en lugar de resolverlos tú.

Extra: prueba darle al agente solo una captura de pantalla del error, sin explicaciones, y mira qué tanto entiende la situación por su cuenta.

Herramientas y recursos

La terminal de Claude Code (la terminal es un programa para escribir comandos): el lugar principal donde se ven los errores (la consola)
/context: te ayuda a entender en qué estado está el agente mientras depura
/compact: si la depuración se alargó y el contexto (el texto que la IA "ve" en ese momento) se llenó, comprime el historial antes de seguir
El archivo de registro del workflow: el agente lo lee automáticamente al analizar errores
/doctor: revisa la instalación y la configuración del propio Claude Code, por si el error no está en tu workflow sino en el entorno
Claude Code CLI Reference: la lista completa de comandos de la CLI (interfaz de línea de comandos)
Context7 MCP (cuando está conectado): el agente busca documentación vigente ante errores del tipo "endpoint not found"
Stack Overflow / GitHub Issues: el agente puede buscar soluciones con WebSearch si el error no es trivial

Errores comunes

🎨 Imagínalo así: un warning (advertencia) en la consola es como el testigo amarillo del aceite en el tablero. El coche avanza, pero no puedes ignorarlo: 500 km después el motor se detiene. Mejor revisarlo a tiempo.

Error 1: Intentar arreglarlo tú en lugar de delegar

Ves un error, te vas a Google y pasas una hora leyendo Stack Overflow. En lugar de eso, copias el error al agente: "esto sale en la consola, revísalo". Te ahorras de 30 a 60 minutos.

Error 2: No guardar el registro de errores

El agente lo arregló, todo funciona, pero no sabes qué estaba mal. Pídele: "explícame en corto qué estaba roto y cómo lo arreglaste". Te sirve para entender el sistema.

Error 3: Ignorar los warnings

El workflow funciona, pero en la consola hay advertencias amarillas. Más adelante pueden volverse errores. Dile al agente: "aquí están los warnings, ¿vale la pena corregirlos?"

Lecciones relacionadas

Primer workflow EN VIVO: el workflow que depuramos en esta lección
Context Rot y técnicas contra la degradación: si la sesión de depuración se alargó y el contexto se llenó
Headless Mode y CI/CD (CI/CD: integración y entrega continuas, armado y entrega automáticos): depuración automática en un pipeline (una cadena de pasos consecutivos) sin intervención humana

Ideas clave

El primer error en un workflow no es un fracaso, es parte del proceso. Espéralo.

Tu papel al depurar es describir el síntoma, no hacer el diagnóstico. El agente averigua las causas por su cuenta.

Después de la primera ejecución exitosa tienes la prueba de que el workflow funciona en condiciones reales. Eso ya es un producto terminado.

Siguiente lección

→ Tokens y manejo del contexto (un token es una unidad de texto para la IA, unos 4 caracteres de texto en inglés): qué consume recursos y cómo controlarlo