inq-roi-simulador-web/methodology/ANTI_PATTERNS.md

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:

1. Deuda técnica invisible: artefactos producidos por IA que nadie puede auditar después
2. Aprendizaje no se acumula: descubrimientos individuales no se transfieren
3. Calidad inconsistente y no atribuible
4. 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).

---

AP.7 — Bypass total de permisos en desarrollo local

Comportamiento: usar --dangerously-skip-permissions (o equivalente) rutinariamente en máquinas de desarrollo donde corren proyectos reales. El motivo declarado suele ser "evitar la fricción de aprobar cada comando".

Daño concreto:

1. Pérdida de auditoría en tiempo real: cuando un agente ejecuta una acción no intencionada (borrar archivos, modificar git history, instalar dependencias rotas), el humano lo descubre por consecuencia, no por la pausa de aprobación.

2. Datos perdidos en repos en evolución: un rm -rf accidental sobre el directorio equivocado puede borrar trabajo no comiteado, configuraciones locales, o assets generados que no están en git.

3. Confianza falsa en el agente: el dev se acostumbra a "todo funciona" y deja de auditar. Cuando aparece un comando raro, el reflejo de pausar ya no existe.

4. Imposibilidad de saber cuándo empezó un problema: sin puntos de control, debuggear "¿cuándo pasó X?" requiere reconstruir desde logs en vez de tener una traza de aprobaciones.

Caso real (no en este equipo, observado en otros proyectos): un desarrollador con bypass total dejó al agente refactorizar carpetas con mv masivos. Una iteración movió archivos a una ruta equivocada por un typo del agente en la ruta destino. Sin permisos, los mv se ejecutaron en cadena. Recuperar tomó 4 horas porque los archivos no estaban en stash ni en commits.

Cómo detectarlo:

• El dev menciona "skipeo todos los permisos para ir más rápido"
• No existe .claude/settings.json ni equivalente en el repo
• El dev no sabe explicar qué hace --dangerously-skip-permissions

Cómo evitarlo:

• Aplicar Patrón D.4 (permisos versionados en .claude/)
• Configurar allow para comandos rutinarios (que es lo que daba fricción)
• Configurar deny para comandos críticos (rm -rf con paths absolutos, git push --force, npm publish, git reset --hard)
• Aceptar la fricción ocasional como precio de la gobernanza

Cuándo SÍ es aceptable usar bypass total:

• Sandboxes efímeros (contenedores Docker que se destruyen post-ejecución)
• CI/CD donde no hay datos del dev
• Máquinas virtuales dedicadas para experimentación

Cuándo NO es aceptable:

• Máquina personal del dev con repos reales
• Cualquier entorno donde haya datos no replicables
• Cualquier entorno con credenciales o secretos

---

Cómo agregar un anti-patrón

Solo se agregan anti-patrones con daño concreto observado, no especulativo. Estructura obligatoria:

1. Nombre breve (forma de "AP.N — Descripción")
2. Comportamiento: descripción de la acción problemática
3. Daño concreto: qué pasa cuando ocurre, con caso real citado
4. Cómo detectarlo: señal observable
5. 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.