Debugging cuando el agente se desvía del spec
A veces el agente implementa algo que funciona pero no es lo que pediste. La causa casi nunca es el agente — es el spec. Debug de desviaciones es menos "corregir código" y más "detectar dónde el spec fue ambiguo".
Desviación del agente = spec ambiguo; corregir el spec es el arreglo de raíz.
Los cuatro tipos de desviación
1. Scope creep del agente: implementó más de lo pedido.
Ejemplo: pediste invitaciones, agregó también gestión de roles.
Causa: spec no listaba "fuera de scope".
Fix: spec agrega sección "fuera de scope del feature".
2. Interpretación sesgada: implementó una versión plausible pero no la que querías.
Ejemplo: pediste "búsqueda", implementó exact match; tú querías fuzzy.
Causa: spec usó palabras con múltiples interpretaciones.
Fix: spec especifica técnica concreta.
3. Decisión silenciosa: tomó una decisión no pedida y no la comunicó.
Ejemplo: decidió usar cookies en vez de JWT porque "es más simple".
Causa: spec no especificó; agente decidió.
Fix: spec decide explícitamente, o agente obligado a preguntar.
4. Ignorancia de contexto existente: implementó feature que ignora patrón del proyecto.
Ejemplo: creó nuevo sistema de errores, existe uno en lib/errors.
Causa: agente no leyó código existente antes de escribir.
Fix: skill del agente "siempre leer dominio antes de escribir".
El debug efectivo
Para cada desviación, pregunta: ¿qué decisión estaba implícita en el spec? Hazla explícita. El arreglo está en el spec, no en el código. El código se re-genera; el spec es lo que debe mejorar.
De las últimas 3 desviaciones del agente, ¿cuáles venían de spec ambiguo? Actualiza los specs retroactivamente. El spec que no se actualiza queda obsoleto en días.
- Desviación del agente = spec ambiguo, casi siempre.
- Cuatro tipos: scope creep, interpretación sesgada, decisión silenciosa, ignorancia de contexto.
- Arregla en el spec, no solo en el código. El código se regenera.