14 KiB
Patrones operativos
Aplicaciones concretas de los 5 principios. Estructurados por categoría operativa.
Estado de cada patrón: propuesto (validado en 1 proyecto) o estable (validado en 2+ proyectos).
A la fecha, todos los patrones aquí son propuestos. Caso de validación: InQ ROI Sprint 1.5.
Categoría A — Disciplina antes de codear
A.1 Brief versionado antes que código
Estado: propuesto · Deriva de: Principio 1
Todo sprint o cambio mayor arranca con un brief en sprints/sprint-N/BRIEF.md antes de pedirle algo a un agente. El brief define alcance, decisiones tomadas, criterios de éxito y lo que NO entra.
Indicador de aplicación correcta: podés iniciar una sesión nueva con Claude Code pasándole solo el path del brief y CLAUDE.md, sin contexto adicional, y empieza a trabajar correctamente.
Indicador de violación: el agente te hace preguntas que ya están respondidas en otro lugar (o peor, no las hace y asume).
A.2 Mockup como contrato visual
Estado: propuesto · Deriva de: Principio 1
Si el cambio es visual, antes de implementarlo se construye un mockup interactivo (HTML, Figma, Visualizer) que el humano aprueba. El mockup es el contrato: el agente lo replica, no lo interpreta libremente.
Indicador de aplicación correcta: cuando ves el output del agente, podés compararlo lado a lado con el mockup y la diferencia es marginal.
Indicador de violación: llegás a Etapa N de un rediseño visual y descubrís que el output "no tiene nada que ver" con lo que esperabas.
A.3 Roadmap explícito antes de arrancar
Estado: propuesto · Deriva de: Principios 1 y 4
Todo sprint con más de 3 etapas tiene un roadmap explícito desde el inicio. Cada etapa tiene expectativa calibrada de qué cambia y qué NO cambia respecto a la anterior.
Indicador de aplicación correcta: después de cada checkpoint, el resultado coincide con lo que esperabas ver, no te sorprende ni para bien ni para mal.
Indicador de violación: te sorprende negativamente un output intermedio porque pensabas que ya tenía X feature que en realidad está agendado 3 etapas después.
Categoría B — Operación con agentes
B.1 Prompt como artefacto del repo
Estado: propuesto · Deriva de: Principios 4 y 5
Cada etapa de trabajo agéntico tiene su prompt en sprints/sprint-N/ETAPA_X_PROMPT.md, versionado. El chat con el agente es puente entre el prompt y el reporte, no contenedor de la decisión.
Por qué: los prompts en archivo son auditables, editables antes de ejecutar, replicables, y no se pierden al cerrar la sesión.
Estructura mínima de un prompt de etapa:
- Objetivo
- Pre-requisitos / contexto previo
- Decisiones ya tomadas (no consultar de nuevo)
- Tareas concretas
- Entregables (DoD checklist)
- Qué reportar al final
- Qué NO hacer en esta etapa
B.2 Mensaje inicial corto, contexto en archivos
Estado: propuesto · Deriva de: Principio 5
El mensaje al agente al arrancar una sesión es de 3-5 párrafos, NO el prompt entero pegado. Estructura:
- "Procedé con etapa X"
- Archivos a leer en orden
- Confirmaciones que esperás antes de que empiece
- Restricción de alcance ("no avances a Y sin OK")
Por qué: el contexto en archivos sobrevive a la sesión, queda versionado, y el agente lo consulta cuando lo necesita en vez de tenerlo permanentemente en ventana.
B.3 Decisiones tomadas como sección explícita
Estado: propuesto · Deriva de: Principio 4
En cada prompt de etapa, incluir sección "DECISIONES YA TOMADAS — no consultar de nuevo" con las definiciones cerradas. Esto impide que el agente vuelva a preguntar lo ya resuelto.
Ejemplo:
DECISIONES YA TOMADAS (no consultar de nuevo)
- Payback negativo → "Sin payback (costo aumenta)"
- Caracteres compactos: "<" y "~"
- Pluralización: siempre plural ("1.0 meses")
B.4 Reglas no negociables en CLAUDE.md
Estado: propuesto · Deriva de: Principio 4
Las reglas que aplican a TODO el proyecto van en CLAUDE.md, no solo en briefs específicos. El agente carga CLAUDE.md en cada sesión nueva por defecto.
Ejemplo de qué va ahí:
- Reglas de marca (cómo se escribe el nombre, qué colores)
- Restricciones de comportamiento (qué no decir, qué no asumir)
- Verificaciones obligatorias pre-entrega
Categoría C — Validación de output
C.1 Validación visual mandatoria del artefacto final
Estado: propuesto · Deriva de: Principio 2
Si el output de la etapa es un artefacto visible (PDF, screenshot, página renderizada, documento), el humano lo abre con sus ojos antes del OK. Tests verdes no es suficiente.
Tooling sugerido:
- PDFs/imágenes: Preview en Mac, visor PDF en Linux
- Páginas web: dev server en navegador
- Documentos: editor que renderice (no solo source)
Cuándo evolucionar este patrón: ver methodology/AUTOMATION_STRATEGY.md. La validación visual humana es Fase 1. Puede complementarse con agentes auditores (Fase 3) pero NO se reemplaza completamente hasta que el equipo desarrolle criterio adversarial maduro.
C.2 Validación programática antes de declarar completado (agente)
Estado: propuesto · Deriva de: Principios 2 y 3
Antes de declarar una etapa completada, el agente debe ejecutar validaciones programáticas, no solo confiar en tests unitarios. Para outputs visuales:
- Análisis de píxeles (¿están los colores esperados?)
- Text extraction (¿están las palabras clave?)
- Tamaño de archivo (¿es razonable?)
- Cantidad de páginas (¿coincide con el diseño?)
Por qué: un test unitario puede pasar mientras el output final está roto. La validación programática del artefacto cierra ese gap.
C.3 Auditoría adversarial al reporte
Estado: propuesto · Deriva de: Principio 3
Cuando llega un reporte de agente "todo OK", aplicar 3 preguntas:
- ¿Los números reportados cuadran si recalculo o pido dump?
- ¿El artefacto es el que pedí?
- ¿Lo que no menciona podría ser relevante?
Casos típicos de detección:
- PDF de 36 KB con 4 páginas (es muy poco → algo no se renderizó)
- KPI con valor "0.0 meses" (numéricamente correcto pero confuso)
- Reporte que dice "PDF generado" sin abrir el PDF generado
C.4 Reporte con datos concretos, no descripciones (agente)
Estado: propuesto · Deriva de: Principio 3
Los reportes del agente deben incluir métricas concretas, no descripciones genéricas.
Mal reporte: "PDF generado correctamente, contiene todo lo esperado."
Buen reporte:
PDF generado: 78 KB, 4 páginas
- Página 1: KPI Hero + 4 cards secundarios + top 3 ahorros
- Página 2: tabla con 11 filas + footer
- Página 3: 3 secciones (composición, trayectoria, transparencia)
- Página 4: nota metodológica
Análisis de píxeles del heatmap: verde 36.329px, ámbar 3.889px, rojo 3.713px
Text extraction confirma palabras clave: "InQ ROI", "Powered by InQuality", "Payback"
C.5 Validaciones programáticas explícitas en el prompt
Estado: propuesto · Deriva de: Principios 2 y 5
Cada prompt de etapa incluye una sección "Validaciones automatizadas mandatorias" con criterios objetivos verificables por código que el agente debe ejecutar antes de declarar terminada la etapa o usar present_files.
Por qué: documenta explícitamente qué se va a auto-validar, hace transferible el conocimiento operativo al equipo, captura el aprendizaje sobre qué problemas son recurrentes y vale la pena chequear automáticamente.
Cómo se aplica:
## Validaciones automatizadas mandatorias
Antes de present_files, ejecutá y confirmá:
PDFs:
- pdf-parse confirma palabras clave esperadas: [lista]
- pdf-parse rechaza términos prohibidos: [lista]
- Cada página entre [N-M] KB
- Cantidad de páginas == [N exacto]
Tests:
- Tests previos verdes (>= [N])
- Tests nuevos verdes
Build:
- npm run build limpio
- Sin warnings TS ni lint nuevos
Indicador de aplicación correcta: los problemas que ya cazaste manualmente en sprints anteriores aparecen como validación automatizada en sprints siguientes. Aprendizaje acumulativo.
Indicador de violación: el agente declara etapa terminada y vos cazás el mismo tipo de problema que ya cazaste 3 etapas atrás. Significa que el aprendizaje no se está capturando como validación.
Relación con otros patrones:
- Extiende C.2 (validación programática) haciéndola explícita en el prompt
- No reemplaza C.1 (validación visual humana) — son complementarias
- Es Fase 2 del roadmap de
AUTOMATION_STRATEGY.md
C.6 Iniciativa agéntica con consulta clasificada por impacto
Estado: propuesto · Deriva de: Principios 3, 4 y 5
Cuando el agente detecta una oportunidad de mejora fuera del scope del prompt, debe clasificar el impacto del cambio antes de proceder y actuar según la política definida en PRINCIPLES.md sección "Política de iniciativa agéntica".
Niveles de impacto:
-
Trivial (cambio interno, no visible al usuario, reversible sin costo) → ejecutar y reportar al final como "decisión menor tomada"
-
Visible reversible (cambio visible al usuario pero sin afectar marca, datos, ni arquitectura) → ejecutar, mencionar explícitamente en el reporte final como "decisión proactiva, validar/revertir"
-
De marca, arquitectura o datos (cambio que afecta identidad, estructura, o información del usuario) → NO ejecutar. Consultar antes de proceder.
Por qué: los agentes producen mejor cuando tienen libertad para optimizar lo local. Pero esa libertad sin límites lleva a cambios silenciosos que el humano descubre por casualidad. Una clasificación explícita preserva la velocidad agéntica sin perder gobernanza.
Caso real: InQ ROI Sprint 1.5 Etapa 3. Claude Code agregó "Hecho desde Paraguay 🇵🇾" al footer del web app sin estar en el brief. El cambio era razonable, alineado con identidad de marca, pero el humano lo descubrió revisando screenshots, no porque se reportara. Decisión retroactiva: mantener, pero documentar el patrón para que en el futuro este tipo de cambios (impacto nivel 3, afecta marca) sean consulta previa, no decisión unilateral.
Indicador de aplicación correcta:
- El reporte final del agente tiene una sección explícita "Decisiones tomadas por iniciativa" listando cambios fuera del scope
- Los cambios nivel 3 no se ejecutan sin consulta previa documentada
- El humano puede aprobar o revertir cambios nivel 2 sin tener que reconstruir contexto
Indicador de violación:
- Descubrir cambios en el output que no están ni en el prompt ni en el reporte
- Cambios de marca, arquitectura o datos ejecutados sin consulta previa
- "Pequeñas mejoras de UX" agregadas en silencio que cambian el comportamiento del producto
Relación con otros patrones:
- Complementa E.2 (Hallazgos no esperados) — pero E.2 es para descubrimientos pasivos (cosas que el agente notó), C.6 es para decisiones activas (cosas que el agente hizo).
- Refuerza C.3 (Auditoría adversarial) — provee al humano una sección concreta donde buscar cambios silenciosos.
Categoría D — Estructura del repo
D.1 Carpeta sprints/ para activos de planificación
Estado: propuesto · Deriva de: Principio 4
Cada sprint tiene su carpeta sprints/sprint-N/ con todos sus artefactos:
BRIEF.mdETAPA_X_PROMPT.md(uno por etapa)ETAPA_X_REPORT.md(opcional, reporte del agente capturado)etapa-X-audit.md(cuando aplica)screenshots/con evidencia visual
Por qué: en 6 meses, abrir esa carpeta te da el historial completo de cómo se construyó el sprint. Sin esto, el conocimiento queda en commits + memoria, que es frágil.
D.2 Carpeta methodology/ para el método en sí
Estado: propuesto · Deriva de: Principio 4
El método de trabajo vive en methodology/, separado del producto. Esto permite que el método evolucione independiente de cualquier producto específico.
D.3 ADRs para decisiones arquitectónicas
Estado: propuesto · Deriva de: Principio 4
Las decisiones arquitectónicas importantes se registran como ADR (Architectural Decision Record) en ARCHITECTURE.md o docs/adr/. Estructura mínima:
- Contexto (qué problema teníamos)
- Decisión (qué elegimos)
- Alternativas consideradas
- Consecuencias (qué implica)
Categoría E — Comunicación humano ↔ agente
E.1 Separar lo validado de lo asumido
Estado: propuesto · Deriva de: Principios 2 y 3
En los reportes del agente, marcar explícitamente qué fue verificado vs qué se asume funcionando.
Ejemplo:
Verificado:
- Tests verdes (455/455)
- PDF generado y abierto con pdf-parse
- Análisis de píxeles confirma heatmap completo
Asumido:
- El componente se renderiza igual en Firefox (solo testeado en Chromium)
- La fuente Roboto está disponible en el sistema cliente (no validado)
E.2 Hallazgos no esperados como sección explícita
Estado: propuesto · Deriva de: Principios 3 y 5
Al final de cada etapa, el agente reporta "hallazgos no esperados" — cosas que descubrió durante la implementación que merecen decisión arquitectónica, aunque no formen parte del DoD.
Ejemplo: "El cambio de --primary propagó a focus rings de inputs (no estaba en el plan). Decisión necesaria: ¿se mantiene o se vuelve a slate?"
E.3 Anti-racionalización explícita
Estado: propuesto · Deriva de: Principio 3
Cuando un test revela algo raro, un cálculo no cuadra, o un output difiere de lo esperado: investigar causa raíz, no minimizar.
Patrón típico de violación: el agente dice "el cálculo es numéricamente correcto" cuando lo que está reportando es un problema de presentación (ej. "0.0 meses" es matemáticamente correcto pero un bug de UX).
Cómo agregar un patrón nuevo
- Identificar el patrón durante un proyecto real (no inventarlo en abstracto).
- Documentarlo con: nombre, categoría, principio del que deriva, descripción, indicador de aplicación correcta, indicador de violación.
- Marcarlo como propuesto con cita del proyecto donde apareció.
- Después de aplicarlo en un 2do proyecto distinto, promoverlo a estable.
Cómo retirar un patrón
Si un patrón no se sostiene en práctica o tiene falsos positivos frecuentes, se retira con un PR que documente:
- Por qué no funcionó
- Qué alternativa probamos
- Si hay un patrón nuevo que lo reemplaza