24 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.
Cuando el output incluye textos que referencian otras fuentes del repo (códigos, IDs, rutas), aplicar también C.8.
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.
Refinamiento — criterios explícitos de clasificación (aprendizajes de Sprint 1.5)
Durante Sprint 1.5 InQ ROI se detectaron dos casos de mala clasificación de impacto. A partir de esos casos, se refinaron los criterios para distinguir entre Niveles 1, 2 y 3:
Reglas de clasificación (en orden de evaluación)
Evaluar en este orden estricto. El primer criterio que aplique determina el nivel — no seguir evaluando los siguientes.
1. ¿El cambio resuelve un ítem listado en TECH_DEBT.md, BACKLOG.md, o archivos de planificación?
→ Nivel 3 (consulta previa). Sin importar el tamaño técnico.
Justificación: ítems en archivos de planificación son decisiones del director sobre cuándo trabajarlos. El agente no puede promover ítems al sprint en curso por iniciativa.
2. ¿El cambio choca con una restricción explícita del prompt de la etapa? → Nivel 3 (consulta previa). Sin excepciones.
Ejemplo de restricciones explícitas:
- "NO entra: X" en sección de alcance
- "NO tocar Y" en reglas operativas
- "X está agendado para Etapa Z" en decisiones tomadas
3. ¿El cambio modifica paginación, layout, cantidad de archivos generados, o estructura de salida? → Nivel 2 mínimo. Reportar.
4. ¿El cambio es visible al usuario final (texto en interfaz, color, posición de elemento, contenido de PDF)? → Nivel 2 mínimo. Reportar.
5. ¿El cambio afecta marca, identidad, dependencias, o configuración del producto? → Nivel 3 (consulta previa).
6. Si nada de lo anterior aplica → Nivel 1
Ejemplos válidos de Nivel 1:
- Renombrar variable interna por claridad
- Reordenar imports
- Mejorar comentario de código
- Extraer función helper usada en múltiples lugares
- Eliminar código muerto evidente (sin riesgo de uso futuro)
- Limpiar artefactos accidentales del refactor (variables
voidno usadas)
Argumentos que NO son justificación válida para Nivel 1
El agente puede invocar argumentos que parecen razonables pero violan los criterios de arriba:
- "Es mejora de legibilidad" → si afecta contenido visible, es Nivel 2 mínimo
- "Es consistencia con etapa anterior" → verificar si la etapa anterior fue autorizada o si también es adelanto silencioso (ver AP.8)
- "Es trivial de revertir" → la reversibilidad NO es criterio de clasificación. Cambios reversibles también pueden ser Nivel 3.
- "Resuelve un bug menor" → si el bug está documentado en TECH_DEBT.md, es Nivel 3
- "Es lo que el usuario esperaría" → eso es asumir. La política existe para no asumir.
Casos reales documentados (Sprint 1.5 InQ ROI)
Caso 1 (Etapa 5): compactación de páginas reportada como Nivel 1.
- Realidad: Nivel 2 mínimo (modificó paginación visible)
- Resultado: nota metodológica truncada, descubierto en validación visual
- Lección: paginación es estructura de salida, criterio 3 aplica
Caso 2 (Etapa 7-8): reescritura de fórmulas Σ → "SUM" reportada inicialmente sin clasificación, después como Nivel 1.
- Realidad: Nivel 3 (resolvía ítem de TECH_DEBT.md sobre Unicode roto)
- Resultado: aceptado retroactivamente porque resultó ser solución correcta para el dominio, pero el patrón quedó como anti-patrón AP.8
- Lección: ítem en TECH_DEBT.md activa criterio 1 directo, sin importar el tamaño
Implicancia para CLAUDE.md del proyecto
En el CLAUDE.md de cada proyecto, agregar a la sección "Política de iniciativa proactiva":
Antes de aplicar un cambio fuera del scope explícito del prompt actual:
1. Verificá si el cambio está listado en TECH_DEBT.md, BACKLOG.md, o
archivos de planificación equivalentes. Si está, es Nivel 3 — consultá.
2. Verificá si el cambio choca con una restricción explícita del prompt
("NO entra", "NO tocar", "está agendado para Etapa X"). Si choca,
es Nivel 3 — consultá.
3. Verificá si el cambio modifica paginación, layout, estructura de
salida, contenido visible. Si lo hace, es Nivel 2 mínimo — reportá.
4. Solo si nada de lo anterior aplica, ejecutá como Nivel 1.
Argumentos NO válidos para evitar la consulta:
- "Es mejora de legibilidad"
- "Es consistencia con etapa anterior" (verificar si esa etapa fue
autorizada o también fue adelanto silencioso)
- "Es trivial de revertir"
- "Resuelve un bug menor"
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)
D.4 Permisos del agente versionados en .claude/
Estado: propuesto · Deriva de: Principios 4 y 5
Las decisiones sobre qué comandos puede ejecutar el agente sin consultar al humano se versionan en archivos de configuración del repo. Esto evita dos extremos: la fricción de aprobar cada comando manualmente, y el bypass total que abre la puerta a acciones no intencionadas.
Estructura recomendada:
repo/
└── .claude/
├── settings.json ← commitable: deny patterns críticos
└── settings.local.json ← gitignored: allow personales del dev
Reglas:
-
settings.jsones del proyecto — contiene patronesdeny(comandos peligrosos prohibidos para todos:rm -rf /,git push --force,npm publish, etc.). Se comitea al repo. -
settings.local.jsones del desarrollador — contiene patronesallowpersonales (cada uno decide qué comandos pre-aprueba). Va en.gitignore. Cuando un dev nuevo arranca, debe construir su propio archivo siguiendo el template, no copiar el de otro. -
El equipo hereda las protecciones, no las preferencias — los
denyson compartidos, losallowson individuales.
Por qué:
- La fricción de aprobar cada
npm installdestruye el flow de trabajo - Pero el bypass total elimina los puntos de control donde se detectan acciones no intencionadas
- La gobernanza está en clasificar comandos por riesgo, no en aprobar todo o aprobar nada
Indicador de aplicación correcta:
- En cada sesión de Claude Code, los comandos rutinarios pasan sin pedir aprobación
- Los comandos no rutinarios siguen pidiendo aprobación (es bueno — ahí prestás atención)
- Si un comando peligroso aparece, está bloqueado por
denyo pide aprobación explícita
Indicador de violación:
- El dev usa
--dangerously-skip-permissionsrutinariamente - El archivo
settings.jsoncontieneallowque deberían ser personales (paga la complejidad de mantenerlo sincronizado entre devs) - No hay archivo de configuración y cada dev aprueba todo manualmente cada vez (fricción crónica, señal de que falta este patrón)
Template: ver methodology/TEMPLATES/CLAUDE_PERMISSIONS_TEMPLATE.md.
Relación con otros patrones:
- Complementa B.4 (reglas no negociables en CLAUDE.md) — pero B.4 es sobre comportamiento del agente, D.4 es sobre permisos del sistema operativo
- Refuerza Principio 5 (humano director) — sin permisos configurados, el dev se vuelve operador de aprobación
Casos reales que valida:
- InQ ROI: el director identificó fatiga de aprobación después de ~30 etapas. Configurar permisos eliminó la fricción sin perder gobernanza.
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.7 Control preventivo de scope — git diff antes de reportar
Estado: propuesto · Deriva de: Principios 3 y 4 · Origen: Sprint 2 Etapa 1
Incluir en todo prompt de Claude Code la siguiente verificación como paso obligatorio antes de reportar:
git diff --name-only HEAD
El resultado debe contener únicamente los archivos listados como autorizados en el prompt. Si aparece un archivo no autorizado:
- Revertirlo:
git checkout HEAD -- <archivo> - Listarlo bajo "Conflictos de scope" en el reporte
- No incluirlo en el entregable de la etapa
Por qué es preventivo, no detectivo: los controles detectivos (grep de tipos, build, tests) verifican que el código resultante funciona, pero no detectan archivos modificados fuera del scope. Un agente puede tocar ActivityPanel.tsx y los tests seguir verdes si el cambio no rompe nada. El git diff captura el cambio antes de que se declare la etapa terminada.
Indicador de aplicación correcta: el reporte del agente incluye explícitamente la salida de git diff --name-only HEAD y todos los archivos listados son los autorizados.
Indicador de violación: el reporte no incluye la salida del git diff, o el diff contiene archivos no listados sin explicación.
Relación con otros patrones:
- Es respuesta directa al daño documentado en AP.9 (resolución unilateral de restricciones contradictorias).
- Complementa C.3 (auditoría adversarial) dándole al humano una checklist concreta de qué verificar.
C.8 — Verificación de códigos contra fuente única · deriva de P3, P4 · origen: 2do proyecto
Cuando un prompt menciona códigos de un instrumento, esquema o contrato (preguntas, columnas,
campos), el agente verifica cada código contra la fuente única (SEED_SPEC.md, schema.sql,
ADRs) antes de ejecutar. Si detecta una discrepancia entre el código nombrado en el
prompt y su definición en la fuente única, DETIENE la ejecución y reporta el conflicto.
Ejecutar "literalmente" y delegar la verificación semántica al director es AP.10.
- ✅ Correcto: el reporte del agente incluye una sección "Verificación C.8" con cada código del prompt mapeado a su fila en la fuente única, antes de la ejecución. Si hay discrepancia, la ejecución no arranca hasta que el director resuelva.
- ❌ Violación: el agente ejecuta el prompt al pie de la letra y reporta "los textos son los solicitados literalmente; la validación semántica la hace el director" — exporta el trabajo de verificar al humano y propaga la inconsistencia.
Cómo se incorpora a un prompt: agregar un paso "Verificación C.8" como primera tarea del DoD, listando los códigos a verificar y la ruta exacta de la fuente única. Casos reales en Datos País: Etapa 2D (no se aplicó — daño AP.10), Etapa 2E (se aplicó — detectó conflicto A1/A1b antes de ejecutar), Etapa 2F (se aplicó — sin discrepancias).
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