10 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)
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"
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