# 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.