Marcos Benítez
293c225819
Agrega: - AUTOMATION_STRATEGY.md: roadmap de 5 fases desde validación 100% humana hasta pipeline multi-agente - PATTERNS.md: patrón C.5 (validaciones programáticas en prompt) + nota en C.1 sobre evolución a fases superiores - PRINCIPLES.md: extensión del Principio 5 con distinción entre actividades irremplazables vs delegables del humano Decisión: InQ ROI Sprint 1.5 permanece en Fase 1. Evolución a Fase 2 después de Sprint 1.5 con criterios documentados.
9.2 KiB
Estrategia de automatización de validación
Documento de decisión sobre qué validaciones automatizar y cuándo. La automatización prematura de la validación humana destruye el aprendizaje del equipo. La automatización tardía deja al humano como cuello de botella.
Principio rector
El humano valida criterio y contexto. Los agentes y scripts validan facts y reglas.
Este principio se deriva de extender el Principio 5 (humano como director) con la observación de que existen actividades del humano que son irremplazables y otras que son delegables.
Actividades del humano irremplazables
- Criterio adversarial: detectar anomalías sutiles que no están codificadas como regla. Ejemplo: "este PDF pesa 36 KB con 4 páginas, eso es muy poco para el contenido que diseñé". No es lista de chequeo, es modelo mental del producto.
- Calibración contextual: "¿esto va a funcionar con un cliente de banca corporativa de InQuality?" Implica conocer al cliente, al sector, al contexto cultural.
- Decisión arquitectónica: cuándo cambiar el método mismo, cuándo aceptar un riesgo, cuándo postergar.
- Calibración del propio método: detectar cuándo el método actual ya no sirve y necesita evolución.
Actividades del humano delegables
- Verificación de presencia/ausencia de elementos (texto, colores, archivos)
- Verificación de cumplimiento de reglas explícitas (marca, paleta, accesibilidad)
- Transporte de contexto entre sesiones
- Formateo y estructuración de prompts/reportes
- Detección de anomalías estadísticas (tamaños, cantidades, tiempos)
- Validación de regresiones (tests previos siguen verdes)
La automatización debe atacar las delegables primero, nunca las irremplazables.
Roadmap escalonado de automatización
Fase 1 — Validación humana al final (estado actual recomendado)
Cuándo: durante los primeros 1-2 proyectos completos aplicando el método. Mientras el equipo aprende.
Qué se hace: el humano abre cada artefacto importante con sus ojos antes del OK. No hay agentes evaluadores. Las validaciones programáticas existen pero son aditivas, no sustitutivas.
Qué se gana: el equipo desarrolla el reflejo adversarial. Aprende qué es "raro pero técnicamente correcto". Construye modelo mental del producto.
Qué se pierde: velocidad. El humano es el cuello de botella explícito.
Cuándo salir de esta fase: cuando al menos 2 miembros del equipo cazan independientemente al menos 3 anomalías sutiles cada uno (no obvias, no en checklist) en proyectos reales.
Fase 2 — Validaciones programáticas explícitas en prompts
Cuándo: después de Fase 1 estabilizada. Idealmente Sprint 2 o 3 de un proyecto en evolución.
Qué se hace: cada ETAPA_X_PROMPT.md incluye sección "Validaciones automatizadas mandatorias" con criterios objetivos que el agente debe ejecutar antes de declarar terminada la etapa.
Ejemplo de validaciones automatizadas en un prompt:
## Validaciones automatizadas mandatorias (ejecutar antes de present_files)
PDFs generados deben cumplir:
- pdf-parse confirma palabras clave: ["InQ ROI", "Powered by InQuality"]
- pdf-parse rechaza términos prohibidos: ["Process Cost Platform"]
- Tamaño de cada página entre 15-80 KB
- Heatmap embebido tiene distribución de colores (verde + ámbar + rojo)
- Cantidad de páginas = 4 exacto
- Tests verdes >= 455
- Build sin warnings nuevos
Si CUALQUIER validación falla, NO uses present_files. Reportá el fallo
y esperá instrucciones.
Qué se gana: los problemas obvios se cazan automáticamente. El humano solo ve outputs que ya pasaron los filtros básicos.
Qué se pierde: el humano debe mantener actualizadas las validaciones cuando el producto evoluciona.
Cuándo salir de esta fase: cuando el conjunto de validaciones se vuelve repetitivo entre prompts (señal de que vale la pena modularizar).
Fase 3 — Agente revisor especializado (uno solo)
Cuándo: después de Fase 2 estabilizada. Cuando el equipo ya internalizó el método y las validaciones programáticas son rutina.
Qué se hace: introducir UN agente especializado que ejecuta una verificación específica. No varios al mismo tiempo. El primer agente revisor más útil suele ser el de marca y consistencia.
Ejemplo de prompt del Agente Auditor de Marca:
Sos el Auditor de Marca de InQuality. Te paso un artefacto (PDF,
screenshot, documento). Tu única tarea es verificar reglas de marca:
1. "InQ" se escribe siempre I-n-Q (I mayúscula, n minúscula, Q mayúscula).
Cualquier variante (INQ, Inq, inq, inQ) es BUG.
2. "Powered by InQuality" presente en footer de PDFs.
3. Color naranja InQ (#F59845) predominante en elementos de marca.
4. NO aparecen colores de CONCILIA (#572FA2 morado, #CB1889 magenta).
5. NO aparece el nombre técnico "Process Cost Platform" en ningún lado.
6. Tipografía consistente con sistema de diseño (sans-serif, sin serif).
Para cada criterio: PASS / FAIL con cita textual de lo encontrado.
Si HAY FAIL, devolvé al implementador con instrucciones específicas.
NO declares aprobado hasta que todos PASS.
Cómo se ejecuta concretamente:
- El Implementador (Claude Code) termina su trabajo y produce un PDF
- Se invoca al Auditor de Marca (sesión separada de Claude o API call)
- El Auditor recibe el PDF como input visual y el prompt de auditoría
- Si hay fails, vuelve al Implementador automáticamente
Qué se gana: verificación consistente de reglas no negociables. Captura errores que el humano puede dejar pasar por fatiga.
Qué se pierde: complejidad operativa. Hay que coordinar dos agentes. El humano debe mantener actualizados los criterios del auditor.
Cuándo salir de esta fase: cuando el agente revisor demuestra captura confiable de los errores que estaba diseñado para capturar, durante al menos 1 sprint completo sin falsos negativos importantes.
Fase 4 — Múltiples agentes revisores
Cuándo: solo después de Fase 3 validada en producción.
Qué se hace: agregar más agentes revisores especializados. Posibles agentes adicionales:
- Auditor de Accesibilidad: WCAG, contrast ratios, semantic HTML
- Auditor de Performance: bundle size, lighthouse score, tamaño de assets
- Auditor de Seguridad: secrets en código, dependencias vulnerables, exposición de PII
- Auditor de Consistencia: que el código nuevo no rompa convenciones existentes
Reglas críticas de esta fase:
- Agregar un agente a la vez, validar 1 sprint, antes de agregar el siguiente
- Cada agente tiene un rol acotado y único — si solapan, hay que decidir qué hace cada uno
- Cuando dos agentes discrepan, el humano decide, no se inventa lógica de "voto mayoritario"
Qué se pierde: mantener N agentes es N veces el costo de mantener uno. Si los criterios cambian, hay que actualizarlos en cada agente.
Fase 5 — Pipeline multi-agente completo
Cuándo: post-estabilización del producto. Cuando hay >5 proyectos aplicando el método.
Qué se hace: orquestación formal con frameworks como LangGraph, AutoGen, o Claude Agent SDK. El humano interviene solo cuando todos los agentes fallan o cuando aparece algo nuevo.
Cuando vale la pena: equipos de 10+ personas, productos en producción estables, donde el costo de la complejidad se amortiza con velocidad.
Cuando NO vale la pena: equipos chicos, productos en evolución activa, métodos aún en aprendizaje. La sofisticación se vuelve fricción.
Antes de pasar a la siguiente fase: criterios
Para saber cuándo subir de fase, verificar 3 condiciones:
- La fase actual está estable: los outputs son consistentes, el equipo no se sorprende negativamente
- El cuello de botella es la validación, no otra cosa: si tu cuello es definición de producto, automatizar validación no ayuda
- El equipo internalizó la fase actual: todos pueden aplicarla sin tu intervención
Si las 3 condiciones se cumplen, considerá subir. Si no, quedate.
Anti-patrón explícito: automatización prematura
Comportamiento: saltarse fases. Por ejemplo, ir directo a Fase 4 sin pasar por 1-2-3.
Daño concreto:
- El equipo nunca desarrolla criterio adversarial — depende de los agentes
- Cuando algo falla, nadie sabe diagnosticar porque nunca lo hicieron a mano
- Los agentes consumen tokens validando cosas obvias que un humano detectaría en 3 segundos
- La complejidad de mantenimiento supera el valor producido
Cómo detectarlo: si tu primera intuición ante un problema de validación es "agreguemos un agente que lo detecte", probablemente estás en este anti-patrón. Primero preguntá: ¿esto se resuelve con un script de 20 líneas? ¿Con una regla en CLAUDE.md? ¿Con un patrón documentado?
Cómo evitarlo: seguir el roadmap escalonado. No saltar fases.
Reflexión final
La automatización de la validación es un medio, no un fin. El fin es que el humano dedique tiempo a lo irremplazable (criterio, contexto, decisión arquitectónica) y delegue lo delegable.
Si automatizar te quita tiempo de pensar en producto, no lo estás haciendo bien. Si automatizar te libera para pensar en producto, estás escalando correctamente.