Triage de Hallucinations y Causa Raíz

1. Visión general del concepto y problema sistémico

Cuando un agente emite un método inexistente o utiliza una biblioteca que no está en el proyecto, la reacción típica de un vibecoder inexperto es la ira y gritos emocionales en el chat: "¿Eres tonto?! ¡Te dije que usaras Drizzle, no Prisma!".

• Esto lleva a la acumulación de contexto en el chat con basura emocional.
• El modelo comienza a disculparse, pero sigue cometiendo errores, ya que la causa raíz no ha sido eliminada.

Triage de Hallucinations es un enfoque ingenieril frío: tratar la alucinación del modelo no como "estupidez de IA", sino como un defecto del sistema de entrega de contexto (Context Delivery Bug), que debe ser clasificado y corregido sistemáticamente.

2. Taxonomía arquitectónica y modelo mental

┌─────────────────────────────────────────────────────────────┐
│                 MATRIZ DE TRIAGE DE HALLUCINACIONES         │
├─────────────────────────────────────────────────────────────┤
│ 1. DETECCIÓN: El modelo emitió un método o tipo inventado   │
│    • Ejemplo: `db.user.findFirstOrThrow()` en Drizzle ORM   │
├─────────────────────────────────────────────────────────────┤
│                          │                                  │
│                          ▼ DIAGNÓSTICO DE LA CAUSA RAÍZ   │
│    ┌───────────────────────────────────────────────────┐    │
│    │ Tipo A: ¿Falta el archivo? ➔ El modelo no vio schema│    │
│    │ Tipo B: ¿Conflicto de reglas? ➔ En las reglas se menciona Prisma│   │
│    │ Tipo C: ¿Pesos obsoletos? ➔ Conocimiento del modelo de 2023│    │
│    └───────────────────────────────────────────────────┘    │
│                          │                                  │
│                          ▼ ELIMINACIÓN SISTÉMICA           │
│ 1. Añadir el archivo de tipos exacto al prompt             │
│ 2. Fijar la prohibición en rules: "NEVER use Prisma syntax" │
│ 3. Añadir validación con el compilador `tsc --noEmit`      │
└─────────────────────────────────────────────────────────────┘

3. Pipeline técnico y mecánica interna

01. Eliminación de alucinaciones a través de archivos de declaración

El agente constantemente inventaba props para un componente interno de botón. En lugar de explicaciones, el desarrollador creó un archivo src/components/ui/button.d.ts con tipos de TypeScript claros y lo añadió a la lista de contexto automático. Los errores desaparecieron al 100%.

02. Protocolo "Post-Mortem para Bugs de IA"

Después de resolver un bug complicado, el ingeniero dedica 2 minutos a actualizar .agents/rules/learnings.md: "En este proyecto, el enrutador Next.js utiliza Server Actions sin llamada manual a fetch. No generes manejadores de ruta innecesarios para mutaciones simples."

4. Errores comunes, trampas y seguridad

• Over-Correction (Hipercorrección): Al intentar corregir una pequeña alucinación, el ingeniero escribe una regla gigante de 50 líneas en mayúsculas que prohíbe al modelo usar patrones auxiliares útiles. Las reglas deben ser quirúrgicamente precisas.
• Ignorar versiones de modelos: Si el modelo tiene una capacidad de razonamiento demasiado baja (por ejemplo, un modelo 3B obsoleto), ningún triage le ayudará a resolver tareas complejas. A veces, el único tratamiento es cambiar a un modelo más potente.

5. Estrategia final para el ingeniero de 2026

La alucinación es un espejo de la calidad de tu documentación ingenieril. Si el modelo alucina, significa que tu sistema no ha sido lo suficientemente determinista. El triage sistemático convierte cada error en un ladrillo en los cimientos de la fiabilidad de tu repositorio.