102 lines
5.7 KiB
Markdown
102 lines
5.7 KiB
Markdown
# 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).
|
|
|
|
---
|
|
|
|
## 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.
|