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.