5.7 KiB
Anti-patrones
Comportamientos que producen daño concreto y deben evitarse. Cada uno está documentado con el caso real donde apareció.
A diferencia de los patrones (que son propuestos hasta validación), los anti-patrones se documentan estables porque el daño ya está observado.
AP.1 — Tests verdes como aprobación final
Comportamiento: declarar una etapa terminada porque los tests pasaron, sin abrir el artefacto final con los ojos.
Daño concreto: llegás a producción con outputs visuales rotos. Caso real (InQ ROI MVP): los tests E2E verificaban que el PDF se generaba y tenía las páginas esperadas, pero nadie abrió el PDF. El heatmap embebido estaba en blanco por un bug de timing en html2canvas. Se descubrió 2 días después cuando un consultor lo abrió.
Cómo detectarlo: el reporte del agente dice "tests verdes, build limpio, PDF generado en X path" pero no incluye observaciones visuales del PDF.
Cómo evitarlo: aplicar Principio 2 (validación humana es ojo) y Patrón C.1 (validación visual mandatoria).
AP.2 — Pasamanos invertido (humano como operador)
Comportamiento: el humano traduce manualmente entre dos agentes o entre agente y código. Copia outputs, formatea, transporta contexto entre sesiones.
Daño concreto: el humano se vuelve cuello de botella del sistema. Lo peor: deja de pensar en arquitectura/producto y se concentra en operación. Caso real (InQ ROI Sprint 1.5, Etapa 5): el director del proyecto sintió "soy pasamanos" después de varios checkpoints transportando reportes de Claude Code al arquitecto.
Cómo detectarlo: preguntate si lo que estás haciendo lo podría hacer un script o un prompt mejor estructurado. Si la respuesta es sí, estás en este anti-patrón.
Cómo evitarlo: aplicar Principio 5 (humano director). Mover lo operativo a archivos (prompts pre-armados, templates) y reservar el chat para decisiones reales.
AP.3 — Racionalización de output anómalo
Comportamiento: cuando un output del agente tiene una métrica anómala (PDF inusualmente liviano, número muy redondo, payback "0.0 meses"), el agente o el humano racionalizan ("numéricamente correcto", "es el caso esperado") en lugar de investigar la causa raíz.
Daño concreto: bugs latentes que se descubren en producción. Caso real (InQ ROI Sprint 1.5, Etapa 4): el PDF de ROI pesaba 36 KB con 4 páginas (9 KB/página), comparado con 78 KB/3 páginas (26 KB/página) de los otros PDFs. El agente reportó "PDF generado". El humano paró y pidió investigar — había secciones que no se renderizaban.
Cómo detectarlo: cualquier número que parezca "anómalo pero técnicamente válido". Especialmente: tamaños de archivo, payback inmediato, ROI extremo, métricas con muchos ceros.
Cómo evitarlo: aplicar Principio 3 (auditoría adversarial) y Patrón E.3 (anti-racionalización explícita).
AP.4 — Decisión recurrente no registrada
Comportamiento: el agente vuelve a preguntar lo mismo en cada sesión nueva, o miembros del equipo asumen distinto porque la decisión no está documentada.
Daño concreto: outputs inconsistentes entre etapas, tiempo perdido re-debatiendo, deriva del producto. Caso real (InQ ROI Sprint 1.5, varias etapas): cada vez que Claude Code iba a aplicar formato de cifras, había que recordarle si usaba separador europeo o americano. Hasta que se documentó en CLAUDE.md.
Cómo detectarlo: el agente te hace una pregunta que ya respondiste en alguna sesión anterior.
Cómo evitarlo: aplicar Principio 4 (decisiones como contratos) y Patrón B.3 (decisiones tomadas explícitas en cada prompt).
AP.5 — Improvisación sin gobernanza
Comportamiento: un equipo (o miembros individuales) usa agentes de IA sin método compartido. Cada uno improvisa con su herramienta preferida, sin briefs, sin validación estructurada, sin documentar decisiones.
Daño concreto:
- Deuda técnica invisible: artefactos producidos por IA que nadie puede auditar después
- Aprendizaje no se acumula: descubrimientos individuales no se transfieren
- Calidad inconsistente y no atribuible
- Imposibilidad de mejorar sistemáticamente
Cómo detectarlo: preguntá al equipo "¿cómo hicieron este artefacto con IA?" — si las respuestas son distintas y vagas, estás acá.
Cómo evitarlo: este método entero está diseñado para evitarlo. Específicamente: empezar con Principios 1 y 4.
AP.6 — Brief grande pegado en chat
Comportamiento: pegar un brief de 800+ líneas en el chat del agente como mensaje inicial.
Daño concreto:
- Consume contexto innecesariamente
- No es auditable después
- Se pierde si la sesión se corta
- Cuesta tokens repetirlo
Caso real (InQ ROI Sprint 1.5): el primer intento fue pegar el BRIEF.md completo en chat. Se reemplazó por la estructura sprints/sprint-N/ con archivos versionados, mensaje inicial corto referenciando paths.
Cómo detectarlo: si tu mensaje inicial al agente tiene más de 30 líneas, probablemente estás en este anti-patrón.
Cómo evitarlo: aplicar Patrón B.1 (prompt como artefacto del repo) y Patrón B.2 (mensaje inicial corto).
Cómo agregar un anti-patrón
Solo se agregan anti-patrones con daño concreto observado, no especulativo. Estructura obligatoria:
- Nombre breve (forma de "AP.N — Descripción")
- Comportamiento: descripción de la acción problemática
- Daño concreto: qué pasa cuando ocurre, con caso real citado
- Cómo detectarlo: señal observable
- Cómo evitarlo: principio o patrón que lo previene
No agregar anti-patrones de "esto sería malo si pasara" — solo de cosas que pasaron en proyectos reales del equipo.