Qué hago cuando mis agentes IA fallan (protocolo de debugging real)

Mis agentes fallan. Los 6. Cada semana.

Ariel a veces publica un post de LinkedIn con una cifra que no existe. Rafiki — el que escribe este blog — de vez en cuando genera un frontmatter mal formateado y los bloques GEO no se renderizan. Lentejo ha mandado newsletters con links rotos. Es lo que hay.

Lo que diferencia a un solopreneur que escala con agentes de uno que los abandona después de un mes no es la calidad de sus agentes. Es que tiene un sistema para detectar y arreglar los fallos en 15 minutos. Hoy te enseño el mío.

Los agentes IA fallan — y eso es completamente normal

Debugging de agentes IA

Proceso sistemático de detectar, diagnosticar y corregir fallos en agentes de inteligencia artificial. Incluye revisión de logs, reproducción del error, identificación de la causa raíz — prompt, contexto, herramienta o modelo — y verificación del fix. Para solopreneurs con agentes en producción, es mantenimiento rutinario, no emergencia.

Voy a decirte algo que nadie que venda herramientas de IA te va a decir: tus agentes van a fallar. Regularmente. Y está bien.

Mis 6 agentes procesan entre 30 y 50 tareas al día. De esas, 2-3 a la semana salen mal. Eso es una tasa de error del 1-2 %. En software empresarial, un uptime del 99 % se considera excelente. Pero como los fallos de un agente son visibles — un post con datos falsos, un email con formato roto — los percibes como si todo se estuviera desmoronando.

No se desmorona. Es mantenimiento normal.

El problema real no es el fallo. Es no tener protocolo. Si cada vez que algo sale mal te sientas durante una hora a investigar sin sistema, pierdes la ventaja que los agentes te dan. Si tienes un protocolo de 15-20 minutos, el fallo se convierte en una pequeña tarea rutinaria — como vaciar la bandeja de entrada.

Un agente que falla 2 veces por semana pero se arregla en 15 minutos sigue ahorrándome 30 horas al mes. Las cuentas salen de sobra.

Mi protocolo de debugging en 5 pasos

Después de 4 meses con agentes en producción, lo he destilado a 5 pasos. Los sigo siempre, en orden, sin excepciones. Cada vez que me he saltado uno, he tardado el doble.

Cada paso tiene un tiempo máximo. Si me paso, escalo — normalmente significa que el fallo es más profundo de lo que parece y necesito cambiar de enfoque.

Paso 1: Detectar (diario, 5 min). Reviso el output de cada agente cada mañana. No leo todo — escaneo buscando anomalías. Un post sin bloques GEO, una newsletter con subject raro, un post de LinkedIn que suena genérico. Si algo chirría, paso al siguiente paso.

Paso 2: Reproducir (3 min). Antes de tocar nada, reproduzco el fallo. Si Rafiki generó un frontmatter malo, le pido que lo genere otra vez con las mismas instrucciones. Si Ariel escribió algo raro, reviso el prompt exacto que recibió. El 40 % de las veces el fallo no se reproduce — fue un glitch puntual del modelo, no un problema sistémico. Si no se reproduce, lo apunto pero no toco nada.

Paso 3: Diagnosticar (5 min). Si se reproduce, busco la causa raíz. Hay 4 categorías — las vemos en la siguiente sección — pero el 70 % de las veces es un problema de contexto: el CLAUDE.md no cubre ese caso, o el prompt es ambiguo. Aquí Claude Code es brutal: le digo "¿por qué crees que el output salió así?" y me señala dónde falta instrucción.

Paso 4: Corregir (5-10 min). Edito lo que toque: el CLAUDE.md, el prompt del script, o la configuración de la herramienta. Nunca parcheo — corrijo la causa raíz. Un parche hoy es dos fallos mañana.

Paso 5: Verificar (2 min). Lanzo la tarea de nuevo y compruebo que el output es correcto. Si funciona, documento qué cambié y por qué en una línea. Si no funciona, vuelvo al paso 3 con la nueva información.

Tiempo total medio: 15-20 minutos. El 80 % de fallos quedan resueltos en una sola pasada.

Los 4 tipos de fallo que veo cada semana

No todos los fallos son iguales, y diagnosticar rápido depende de saber qué estás mirando. Después de cientos de incidencias, los he clasificado en 4 tipos claros.

El fallo de contexto es el rey. Y tiene sentido — es el más difícil de prevenir porque depende de anticipar todos los casos posibles en un documento de texto. Cada vez que mi CLAUDE.md crece con una nueva regla, es porque un fallo de contexto me enseñó que faltaba esa instrucción.

Las alucinaciones son el fallo más peligroso. Un agente que inventa una estadística puede hacer que publiques algo falso con tu nombre. Según un análisis de la Universidad de Stanford (2025), los modelos de lenguaje grandes producen afirmaciones factuales incorrectas en un 3-10 % de sus outputs, dependiendo del dominio y la complejidad. En mi experiencia, con buenos prompts ese porcentaje baja al 1-2 %, pero nunca llega a cero. Mi regla de oro: cualquier dato o cifra en un output de agente se verifica antes de publicar. Sin excepciones.

Los fallos de herramienta son los más fáciles de diagnosticar y los más frustrantes — no puedes hacer nada cuando una API está caída. Mi enfoque: reintentar una vez, y si no funciona, hacer la tarea manualmente o posponerla. No pierdo 30 minutos peleando con algo que se arreglará solo en una hora.

La degradación de calidad es la más sutil. Todo "funciona" pero el resultado es mediocre. Suele pasar cuando el contexto del agente se comprimió demasiado o cuando hay tantas reglas en el CLAUDE.md que el modelo empieza a priorizarlas mal. La solución: simplificar, no añadir más reglas. Menos es más.

Cómo detecto fallos antes de que lleguen al usuario

La revisión manual funciona pero no escala. Cuando tienes un agente, puedes revisar todo a ojo. Con seis, necesitas capas de detección.

Capa 1: Checks post-build. Cada vez que Rafiki genera un post, ejecuto un grep que verifica que los bloques GEO se renderizan correctamente. Si da menos de 4 coincidencias, algo falló en el frontmatter. Es un check de 2 segundos que me ha salvado de publicar posts rotos al menos 10 veces.

Capa 2: Revisión rápida del output. Cada mañana, 5 minutos. Escaneo los resultados de todos los agentes que corrieron el día anterior. No leo todo — busco red flags: cifras redondas sospechosas (un agente que dice "exactamente 10.000 €" probablemente está inventando), repetición de frases entre posts, links rotos, formatos raros. Con práctica, detectas anomalías en segundos.

Capa 3: Métricas semanales. Una vez por semana analizo datos con Claude Code para buscar patrones: ¿están bajando las tasas de apertura de las newsletters? ¿Hay posts con cero impresiones después de una semana? ¿Algún agente está tardando más de lo normal? Los fallos graduales no se detectan día a día — se ven en la tendencia semanal.

Mi equipo de agentes me cuesta menos de 100 €/mes en total. Un equipo humano equivalente para las mismas tareas — blog, LinkedIn, newsletter, research, analítica — serían 12.000-16.000 €/mes. ¿Valen la pena 20 minutos de debugging unas pocas veces por semana? Ni lo dudo.

Ejemplo real: cuando Rafiki publicó un post con datos fantasma

Te cuento uno de este mes. Rafiki publicó un post sobre ROI de agentes con una cifra específica que decía venir de un informe de McKinsey. Sonaba perfecto. El número era creíble, la fuente era creíble, el contexto era creíble.

El problema: el informe no existía.

Lo detecté en la revisión matutina porque la cifra era demasiado redonda — "el 47 % de empresas que adoptan agentes IA ven ROI positivo en 90 días". Busqué la fuente. No existía. Rafiki la había alucinado con una confianza impresionante.

Mi protocolo en acción:

1. Detectar: revisión matutina, cifra sospechosa por redondeo excesivo
2. Reproducir: le pedí que citara la fuente exacta con URL → no pudo
3. Diagnosticar: fallo de alucinación. El CLAUDE.md no tenía regla explícita sobre verificación de fuentes
4. Corregir: añadí al CLAUDE.md: "Cuando uses estadísticas de terceros, SIEMPRE citar fuente verificable. Si no encuentras la fuente exacta, NO uses el dato"
5. Verificar: regeneré la sección con datos reales y verifiqué cada fuente manualmente

Tiempo total: 22 minutos. El post se corrigió ese mismo día. Sin esa revisión, habría estado publicado con datos falsos y mi nombre debajo. Eso no te lo puedes permitir.

Cómo ha evolucionado mi tasa de fallos en 4 meses

El debugging no es un problema que resuelves una vez. Es mantenimiento continuo, como el aceite del coche. Pero la tendencia es clara: cada mes hay menos fallos, porque el CLAUDE.md de cada agente crece con cada incidencia.

El primer mes fue caótico. Mis agentes fallaban 8-10 veces por semana. El CLAUDE.md de cada uno era básico — un par de párrafos describiendo qué hacer. No cubría casos límite, no tenía reglas de verificación, no definía qué NO hacer.

Hoy, 4 meses después, estoy en 2-3 fallos semanales. El CLAUDE.md de Rafiki tiene más de 200 líneas. No porque sea complejo, sino porque cada fallo me enseñó una instrucción que faltaba. Según Gartner (2026), el 40 % de aplicaciones empresariales integrarán agentes IA para finales de este año. Las empresas grandes tendrán equipos de 20 personas gestionando esto. Yo lo hago solo con un buen CLAUDE.md y 20 minutos de mantenimiento.

Tres cosas que cambiaría si empezara hoy:

Documentar cada fallo desde el día 1. Cada corrección, cada regla nueva. Lo hice tarde y perdí contexto sobre por qué algunas reglas existían. Ahora cada cambio en el CLAUDE.md lleva un comentario de una línea explicando el porqué.

No sobrecargar el CLAUDE.md. Hubo un momento en que el archivo de Rafiki tenía tantas reglas que el modelo empezó a contradecirse. Simplifiqué, agrupé por categoría y eliminé duplicados. El resultado: menos reglas pero mejor cumplimiento.

Aceptar el 1-2 % de fallo como coste operativo. Intentar llegar a cero errores es una trampa. El coste de pasar del 98 % al 99,5 % de precisión es desproporcionado respecto al beneficio. Mejor invertir ese tiempo en crear valor nuevo que en perseguir la perfección.

Si tienes agentes en producción — o estás pensando en montarlos — no te asustes cuando fallen. Asústate si no tienes un sistema para delegar sin perder el control. Eso sí que es un problema real.