Un pool por entorno, no un pool por aplicación

Un pool existe para amortizar algo caro. Abrir una conexión a PostgreSQL cuesta: handshake TCP, TLS, autenticación, y el servidor levanta un proceso dedicado por conexión. En un backend de larga vida —un Nest en Fargate, por ejemplo— abres diez conexiones al arrancar y las reutilizas durante días. El coste se paga una vez.

En Lambda no existe ese "al arrancar" en el sentido que asumes. Hay un arranque por entorno de ejecución, y AWS crea tantos entornos como invocaciones concurrentes tengas. Si tu pico son 200 invocaciones a la vez, tienes 200 procesos Node independientes, cada uno con su propio pool. Un pool de 10 por entorno son 2.000 conexiones llamando a la puerta de una base de datos que aguanta 100.

La cuenta es de una simplicidad brutal:

conexiones = concurrencia de Lambda × tamaño del pool por entorno

Una db.t4g.medium ronda las 220 max_connections. Con 50 invocaciones concurrentes y un pool de 5 ya estás en el límite. Y a diferencia de un servidor, aquí la concurrencia no la decides tú: la decide el tráfico.

El fallo que multiplica el daño: abrir el pool dentro del handler

Antes de tocar infraestructura, mira dónde se crea el cliente. Este patrón es el que más veces me he encontrado, y convierte un problema de escala en un problema inmediato:

// MAL: un pool nuevo por invocación, y muchas conexiones quedan colgando
export const handler = async (event) => {
  const pool = new Pool({ connectionString: process.env.DATABASE_URL });
  const { rows } = await pool.query('SELECT id FROM users WHERE email = $1', [event.email]);
  return rows[0];
};

Cada invocación abre un pool nuevo. Si además falta el end() —y casi siempre falta— la conexión queda ocupada hasta que PostgreSQL la recicla por timeout. Acabas de convertir cada petición en una fuga.

Lo correcto es sacarlo del handler, al ámbito del módulo. Ese código corre una vez por entorno de ejecución, y el entorno se reutiliza entre invocaciones mientras siga caliente:

// El pool vive en el entorno de ejecución y sobrevive entre invocaciones
const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  max: 1,                       // un entorno atiende una invocación a la vez
  idleTimeoutMillis: 30000,     // suelta la conexión si el entorno queda ocioso
  connectionTimeoutMillis: 5000,
});

export const handler = async (event) => {
  const { rows } = await pool.query('SELECT id FROM users WHERE email = $1', [event.email]);
  return rows[0];
};

max: 1 sorprende a quien viene de servidores, pero es exactamente lo que quieres: un entorno de Lambda procesa una invocación cada vez, así que un pool de 10 son nueve conexiones que nunca trabajan en paralelo y que sí cuentan contra tu límite.

Reserved concurrency: el techo que sí controlas

Con max: 1, tu número de conexiones pasa a ser exactamente tu concurrencia. Y esa sí se puede acotar, función por función:

resource "aws_lambda_function" "api" {
  function_name                  = "api-handler"
  reserved_concurrent_executions = 40   # techo duro de 40 conexiones
  # ...
}

Es una decisión incómoda porque significa aceptar throttling: pasadas 40 invocaciones simultáneas, Lambda rechaza. Pero prefiero mil veces un error acotado en una función concreta que una base de datos que deja de aceptar conexiones y tumba de paso a los workers, las migraciones y el panel de administración, que no tenían nada que ver. Un límite no es una restricción: es decidir de antemano quién sufre primero cuando algo se rompe.

RDS Proxy: qué resuelve y qué no

RDS Proxy se sienta entre Lambda y la base de datos, y mantiene su propio conjunto de conexiones ya abiertas. Tus funciones hablan con el proxy, y él multiplexa: muchos clientes efímeros contra unas pocas conexiones reales reutilizadas.

Lo que gana de verdad:

• Absorbe los picos. Cuando la base de datos está al límite, el proxy encola en vez de rechazar.
• Elimina el coste de abrir conexión en cada arranque en frío. Se nota más de lo que parece en la latencia p99.
• Failover más limpio. Mantiene viva la conexión del cliente mientras el motor conmuta.

Lo que conviene saber antes de meterlo:

• No es gratis. Se factura por vCPU de la instancia de base de datos, y en cargas pequeñas puede salir más caro que subir de tamaño la propia base.
• El pinning te arruina la fiesta. Si usas transacciones largas, sentencias preparadas a nivel de sesión, SET de variables o tablas temporales, el proxy fija una conexión a tu sesión y deja de multiplexar. Terminas pagando por un proxy que no reutiliza nada. Se ve en CloudWatch con DatabaseConnectionsCurrentlySessionPinned, y es lo primero que miro cuando alguien dice que el proxy "no hizo nada".
• Vive dentro de la VPC. Lo que implica meter la Lambda en subredes privadas, con todo lo que eso arrastra en arranques y en factura de red.

Lo que haría hoy

El orden importa, y casi nadie lo respeta:

1. Saca el pool del handler y pon max: 1. Cinco minutos, cero coste, y resuelve la mayoría de los casos.
2. Pon reserved_concurrent_executions en las funciones que tocan la base de datos. También gratis, y convierte una caída total en una degradación acotada.
3. Mide antes de comprar. Mira DatabaseConnections en CloudWatch durante un pico real. Si estás lejos del techo, no necesitas un proxy.
4. Añade RDS Proxy cuando el tráfico sea genuinamente irregular y hayas comprobado que tus consultas no provocan pinning.

Y una nota que no es técnica: si el 90% de tu aplicación es un CRUD contra PostgreSQL con tráfico razonablemente constante, es probable que la respuesta correcta no sea ninguna de estas cuatro, sino un contenedor de larga vida con un pool normal y aburrido. Lambda es espectacular para trabajo a ráfagas. Contra una base relacional bajo carga sostenida, muchas veces estás pagando complejidad para resolver un problema que no tenías.

El spinner centrado es la peor respuesta por defecto

Un spinner en medio de la pantalla dice una sola cosa: "algo está pasando, no sé qué, no sé cuánto falta". Borra toda la estructura que ya conocías y la reemplaza por una ruedita. Cuando los datos llegan, la interfaz aparece de golpe en una posición distinta y tu ojo tiene que volver a orientarse.

El problema de fondo es que trata la pantalla como una unidad atómica: o está todo, o no hay nada. Pero casi nunca es cierto. En un dashboard típico, el título, la navegación, los filtros y la estructura de las tarjetas se conocen antes de pedir un solo byte al servidor. Lo único que falta son los números. Bloquear el 90% de la interfaz que ya podías pintar para esperar al 10% que no, es tirar rendimiento percibido a la basura.

La regla que aplico: pinta todo lo que ya sabes, y marca como pendiente solo lo que de verdad depende del servidor.

Skeletons que no saltan: reservar el espacio real

Un skeleton es un placeholder con la forma del contenido final. Funciona por dos razones: comunica qué va a aparecer y, sobre todo, reserva el espacio para que nada salte cuando llegue. Si tu skeleton mide 40px y la fila real mide 72px, has cambiado un spinner por un salto de layout, que es peor.

Por eso los construyo a partir del mismo componente, no como una maqueta paralela que se desincroniza a la primera:

function FilaCandidato({ datos }) {
  return (
    <li className="fila">
      <span className="avatar">{datos ? <img src={datos.avatar} alt="" /> : null}</span>
      <span className="nombre">{datos ? datos.nombre : <Bloque w="60%" />}</span>
      <span className="puesto">{datos ? datos.puesto : <Bloque w="35%" />}</span>
    </li>
  );
}

La fila tiene la misma altura y el mismo grid en ambos estados, así que el paso de skeleton a datos es un cambio de contenido, no de layout. El CSS hace el resto del trabajo pesado:

.fila { display: grid; grid-template-columns: 40px 1fr 1fr; min-height: 72px; }
.avatar { aspect-ratio: 1; border-radius: 50%; background: var(--gris-200); }

@media (prefers-reduced-motion: no-preference) {
  .bloque { animation: pulso 1.4s ease-in-out infinite; }
}

Dos detalles que se olvidan siempre: min-height en la fila (evita el CLS cuando el contenido real es más alto) y respetar prefers-reduced-motion, porque una pantalla llena de bloques pulsando es exactamente el tipo de animación que marea a alguna gente.

Streaming con Suspense: no esperes al dato más lento

Cuando una página pide cuatro cosas, lo normal es que tarden 80ms, 120ms, 150ms… y 900ms. Si esperas a todas para pintar, tu página tarda 900ms. Con streaming, el servidor manda el HTML de lo que ya está listo y el resto llega después por la misma conexión.

En React esto se expresa con fronteras de Suspense. Cada frontera es una promesa al usuario: "esta parte va a llegar más tarde, el resto ya está aquí".

export default function Panel() {
  return (
    <Layout>
      <Cabecera />                        {/* instantáneo, sin datos */}
      <Suspense fallback={<KpisSkeleton />}>
        <Kpis />                          {/* rápido */}
      </Suspense>
      <Suspense fallback={<TablaSkeleton filas={8} />}>
        <TablaInformes />                 {/* el lento: 900ms */}
      </Suspense>
    </Layout>
  );
}

Lo importante no es la sintaxis, es dónde pones las fronteras. Una frontera por página no sirve de nada: vuelves al spinner global con más pasos. Una frontera por componente diminuto tampoco: acabas con una pantalla que parpadea por trozos durante dos segundos y se siente rota. Mi criterio es poner la frontera alrededor de bloques que el usuario percibe como una unidad —una tarjeta, una tabla, un panel lateral— y sobre todo aislar lo lento para que no contagie a lo rápido.

El detalle que más quejas me quitó: retrasar y sostener

Si una petición tarda 90ms y muestras un skeleton, el usuario ve un parpadeo: aparece y desaparece antes de que el ojo lo procese. Ese flash se percibe como un glitch, no como velocidad. Y si el skeleton se muestra 40ms, molesta más que si no hubiera aparecido.

La solución no es técnica, es de tiempos: no muestres el estado de carga antes de ~200ms, y si lo muestras, sostenlo al menos ~400ms.

export function useCargaVisible(cargando: boolean) {
  const [visible, setVisible] = useState(false);

  useEffect(() => {
    if (!cargando) return;
    const espera = setTimeout(() => setVisible(true), 200);
    return () => clearTimeout(espera);      // terminó antes: nunca se vio
  }, [cargando]);

  useEffect(() => {
    if (cargando || !visible) return;
    const minimo = setTimeout(() => setVisible(false), 400);
    return () => clearTimeout(minimo);      // ya visible: aguanta 400ms
  }, [cargando, visible]);

  return visible;
}

Con esto, las respuestas rápidas no muestran nada —que es lo que quieres, porque ya son rápidas— y las lentas muestran un estado estable en vez de un parpadeo. Es el cambio más pequeño que he hecho con más impacto directo en "oye, la app va mucho mejor ahora".

Lo que hago hoy en cada pantalla nueva

Antes de escribir el primer fetch, me hago tres preguntas: qué puedo pintar sin datos (eso va fuera de cualquier frontera), qué bloques percibe el usuario como unidades (ahí van las fronteras de Suspense y sus skeletons), y cuál es el dato lento (ese se aísla siempre, aunque sea el más importante de la pantalla).

El error mental que me costó años corregir fue pensar en la carga como un momento binario —cargando o cargado— cuando en realidad es una secuencia que puedes coreografiar. La misma petición de 900ms puede sentirse como una app rota o como una app viva, y la diferencia no está en el backend: está en qué decides mostrar durante esos 900ms. Optimizar la petición de 900 a 600 cuesta una tarde de trabajo y casi nadie lo nota; diseñar bien lo que se ve mientras tanto cuesta una hora y lo nota todo el mundo.

La cache key es el 90% del problema

Un CDN guarda respuestas indexadas por una clave. Si dos peticiones generan la misma clave, la segunda es un hit. Todo lo que metas en esa clave multiplica el número de entradas posibles y divide tu hit rate.

El caso que más veces he visto: alguien reenvía la cookie de sesión al origen "porque la app la necesita" y, sin querer, la mete también en la cache key. A partir de ahí cada usuario tiene su propia copia de cada recurso. Técnicamente hay caché; en la práctica no cachea nada. Lo mismo pasa con reenviar todas las query strings: los utm_source de una campaña convierten una URL en cincuenta.

La pieza que arregla esto es entender que CloudFront tiene dos políticas distintas y separadas: la cache policy define qué entra en la clave, y la origin request policy define qué se le manda al origen. No son lo mismo. La cookie puede viajar al origen sin fragmentar la caché.

resource "aws_cloudfront_cache_policy" "estaticos" {
  name        = "static-assets"
  min_ttl     = 0
  default_ttl = 86400
  max_ttl     = 31536000

  parameters_in_cache_key_and_forwarded_to_origin {
    enable_accept_encoding_brotli = true
    enable_accept_encoding_gzip   = true

    cookies_config { cookie_behavior = "none" }
    headers_config { header_behavior = "none" }

    query_strings_config {
      query_string_behavior = "whitelist"
      query_strings { items = ["v"] }
    }
  }
}

Regla que aplico sin excepciones: la cache key empieza vacía y se le añade lo que se pueda justificar. Nunca al revés.

El Cache-Control manda; la distribución solo pone límites

Los TTL de la distribución confunden a mucha gente porque parecen la configuración principal, y no lo son. default_ttl solo se aplica cuando el origen no manda cabeceras de caché. max_ttl es un techo. min_ttl, un suelo. El que decide de verdad es tu origen, ruta por ruta.

Y ahí está la cabecera que más rendimiento me ha dado por carácter escrito: s-maxage.

# Bundle con hash en el nombre: inmutable de verdad
Cache-Control: public, max-age=31536000, immutable

# HTML de una página que cambia: el navegador no lo guarda, el CDN sí
Cache-Control: public, max-age=0, s-maxage=300, stale-while-revalidate=86400

max-age habla con el navegador; s-maxage habla con las cachés compartidas —el CDN— y tiene prioridad sobre el anterior. Esa separación es lo que te permite publicar cambios rápido: el navegador del usuario no retiene nada, el edge retiene cinco minutos, y purgar el edge está bajo tu control. Purgar el navegador de alguien no lo está, nunca.

💡 Si tu HTML sale del origen con max-age=3600, no tienes un problema de CDN: tienes usuarios con una versión vieja durante una hora y ninguna forma de arreglarlo. max-age=0, s-maxage=3600 cachea igual de bien y sí se puede revertir.

Invalidar es el plan B; versionar es el plan A

Las invalidaciones son la herramienta que todo el mundo usa primero y la que menos debería hacer falta. Son asíncronas, tardan, tienen las primeras 1.000 rutas al mes gratis y luego se facturan, y sobre todo: un /* en cada despliegue vacía la caché entera y manda todo el tráfico a tu origen a la vez, justo en el momento en el que acabas de desplegar. Es la peor combinación posible.

La alternativa es que la invalidación deje de ser necesaria. Si tus assets llevan el hash del contenido en el nombre, un despliegue no modifica ficheros: publica ficheros nuevos, con URLs nuevas, que nadie tiene cacheadas. No hay nada que invalidar. Lo único que cambia de sitio es el documento de entrada, y ese ya tiene un s-maxage corto.

Cuando aun así hace falta, la acoto:

# Plan B, y acotado: solo los documentos de entrada
aws cloudfront create-invalidation \
  --distribution-id E2XXXXXXXXXXXX \
  --paths '/index.html' '/blog/*'

stale-while-revalidate: que el origen deje de sufrir

Sin stale-while-revalidate, el momento en que expira el TTL es un acantilado: la petición que llega justo después espera a que el origen responda entero. Con tráfico alto, varias peticiones llegan a la vez y todas van al origen por la misma URL.

Con SWR, el edge sirve la copia caducada inmediatamente y revalida por detrás. El usuario nunca paga la latencia del refresco, y tu p99 deja de tener picos periódicos que no correlacionan con nada. Añade stale-if-error y además tienes un modo degradado gratis: si el origen devuelve 5xx, se sigue sirviendo lo último bueno en lugar de propagar el error.

Si el origen sigue notando el tráfico de revalidación, Origin Shield añade una capa de caché intermedia que consolida esas peticiones. Es un coste extra: lo activo cuando los datos lo piden, no por defecto.

Cómo lo mido antes de tocar nada

La métrica CacheHitRate de la consola sirve para saber que tienes un problema, no para saber dónde. Para eso están los logs: cada línea trae x-edge-result-type con Hit, RefreshHit, Miss, Error. Agrupar por URI y por ese campo te da el diagnóstico en una consulta.

SELECT uri, x_edge_result_type, count(*) AS n
FROM cloudfront_logs
WHERE date >= current_date - interval '7' day
GROUP BY 1, 2
ORDER BY n DESC
LIMIT 50;

Si la misma URI aparece arriba con Miss y mucho volumen, solo hay dos explicaciones: la cache key la está fragmentando, o el origen manda un Cache-Control que impide cachearla. Las dos se arreglan en diez minutos cuando sabes cuál de las dos es.

Lo que haría hoy, en este orden

Decidir el Cache-Control en el origen por tipo de ruta antes que nada. Empezar la cache key vacía y añadir solo lo justificable. Poner hash en el nombre de los assets para que invalidar sea excepcional. stale-while-revalidate en todo lo que sea HTML. Y medir con x-edge-result-type antes de tocar la siguiente palanca.

Un CDN mal configurado no es neutral: añade un salto, una capa donde el bug se esconde y una factura de transferencia que pagas dos veces. Bien configurado es de las pocas cosas en AWS donde el ahorro y la latencia mejoran en la misma dirección. La diferencia entre las dos versiones no es el producto: son tres decisiones que caben en una tarde.

Qué mide INP y por qué el LCP no lo cubre

El LCP (Largest Contentful Paint) responde a "¿cuánto tardó en aparecer el contenido principal?". Es un problema de arranque: sucede una vez, al principio. INP es otra cosa: durante toda la sesión, cada clic, cada tap, cada tecla dispara un ciclo de "el navegador recibe el evento → corre tu JavaScript → repinta". INP se queda con la peor de esas latencias y esa es tu nota.

La diferencia importa porque las apps modernas viven en la interacción, no en la carga. Un dashboard, un editor, un panel de filtros: el usuario carga una vez y luego interactúa mil. Si cada filtro que activa congela la interfaz 300ms, tu LCP perfecto no lo salva. El umbral bueno de INP es 200ms; por encima de 500ms se siente roto.

El culpable casi siempre es el mismo: tareas largas

El navegador es de un solo hilo para tu JavaScript. Cuando corre una función, no puede repintar ni atender otro evento hasta que esa función termina. Si al hacer clic disparas un cálculo o un render que tarda 250ms, durante esos 250ms la interfaz está muerta: el botón no muestra su estado activo, nada se mueve. Eso es una "tarea larga" y es el 90% de los problemas de INP que he depurado.

El patrón típico: un input de búsqueda que en cada tecla filtra y re-renderiza una lista de 2.000 elementos. Cada pulsación reconstruye el árbol entero antes de dejar que el navegador repinte el propio texto que estás escribiendo. El resultado es un input que va a tirones aunque el filtrado sea trivial.

// Mide dónde se va el tiempo: registra cualquier tarea que bloquee >50ms
new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    console.warn('Tarea larga:', Math.round(entry.duration), 'ms', entry);
  }
}).observe({ type: 'longtask', buffered: true });

Antes de optimizar nada, mido. La PerformanceObserver de longtask te dice qué interacciones bloquean el hilo y cuánto. No adivines: casi nunca es lo que crees.

Arreglarlo en React: separar lo urgente de lo que puede esperar

La clave conceptual es que no todo lo que dispara una interacción es igual de urgente. Cuando escribes en un buscador, mostrar la letra que tecleaste es urgentísimo; recalcular la lista filtrada puede esperar 50ms sin que nadie lo note. React 18 me dio las herramientas para decir exactamente eso.

useDeferredValue marca un valor como "de baja prioridad": React pinta primero la entrada urgente (el texto del input) y recalcula lo derivado después, sin bloquear.

function Buscador({ items }) {
  const [query, setQuery] = useState('');
  const diferido = useDeferredValue(query);

  // Se recalcula con el valor diferido, no con cada tecla
  const filtrados = useMemo(
    () => items.filter((i) => i.nombre.includes(diferido)),
    [items, diferido],
  );

  return (
    <>
      <input value={query} onChange={(e) => setQuery(e.target.value)} />
      <Lista items={filtrados} />
    </>
  );
}

El input responde instantáneo porque su render no espera al filtrado. Para acciones más pesadas —cambiar de pestaña, aplicar un filtro que reordena media pantalla— uso useTransition, que envuelve la actualización costosa y deja que el clic muestre su feedback antes de arrancar el trabajo:

const [pending, startTransition] = useTransition();

function onFiltrar(nuevo) {
  setFiltroActivo(nuevo);              // urgente: el botón se marca ya
  startTransition(() => {
    setResultados(recalcular(nuevo));  // no urgente: no bloquea el clic
  });
}

Cuando no hay React de por medio: cede el hilo

A veces el trabajo pesado no es un render, es un bucle: procesar un CSV, transformar un JSON grande. Ahí la solución es cortar la tarea larga en trozos y devolverle el control al navegador entre uno y otro, para que pueda atender clics y repintar. La forma moderna es scheduler.yield(); el fallback de siempre es un setTimeout(0).

async function procesar(filas) {
  for (let i = 0; i < filas.length; i++) {
    trabajar(filas[i]);
    if (i % 100 === 0) await yieldAlHilo(); // respira cada 100 filas
  }
}

const yieldAlHilo = () =>
  'scheduler' in window && 'yield' in scheduler
    ? scheduler.yield()
    : new Promise((r) => setTimeout(r, 0));

Si el trabajo es de verdad CPU-intensivo y no necesita el DOM, la respuesta correcta no es trocear sino sacarlo a un Web Worker: otro hilo, cero bloqueo del principal. Pero para la mayoría de casos, ceder el hilo cada N iteraciones ya convierte un congelamiento en algo imperceptible.

Lo que aprendí midiendo, no adivinando

INP me enseñó a dejar de confundir "rápido de cargar" con "rápido de usar". Son ejes distintos y el usuario siente sobre todo el segundo, porque pasa el 99% del tiempo interactuando, no cargando. La buena noticia es que casi siempre se arregla sin reescribir nada: encuentras la tarea larga con longtask, decides qué es urgente y qué puede esperar, y usas la herramienta que toca —useDeferredValue, useTransition, ceder el hilo o un worker—. Mi regla es simple: si una interacción bloquea el hilo más de 200ms, no es una micro-optimización opcional, es un bug de percepción de calidad. Y los bugs de percepción son los que hacen que la gente diga "no sé, se siente lento" y no vuelva.

Los dos ejes: dimensiones y precisión

Cuando quieres que un embedding ocupe menos, hay exactamente dos palancas. La primera es truncar dimensiones: quedarte con las primeras N componentes del vector en lugar de todas. La segunda es cuantizar: bajar la precisión de cada componente, de float32 a int8 o incluso a un solo bit.

Estas palancas se multiplican. Un vector de 1024 dimensiones en int8 ocupa 1 KB frente a los 4 KB del mismo vector en float32, y frente a los 12 KB del vector completo de 3072 en float32. Doce veces menos memoria. La pregunta no es si eso ahorra —evidentemente sí—, sino cuánto recall pierdes por el camino.

Truncar dimensiones no es tan bárbaro como suena

Truncar un vector arbitrario destruye información de forma impredecible: no hay ninguna garantía de que las primeras componentes sean las importantes. Lo que cambió el panorama es el entrenamiento tipo matryoshka, donde el modelo se entrena explícitamente para que los prefijos del vector sean, por sí solos, representaciones útiles. Las primeras dimensiones cargan la señal gruesa; las últimas afinan matices.

Si tu modelo soporta este esquema —los principales de OpenAI y varios abiertos lo hacen—, truncar es literalmente cortar el array y renormalizar:

function truncar(vector: number[], dims: number): number[] {
  const corte = vector.slice(0, dims);
  const norma = Math.hypot(...corte);
  return corte.map((v) => v / norma); // renormalizar es obligatorio
}

Ese renormalizar no es opcional. Si usas similitud coseno con vectores normalizados y truncas sin volver a normalizar, las magnitudes dejan de ser comparables y las distancias se ensucian. Es el error más común y el más silencioso: no revienta nada, solo empeora los resultados.

Si tu modelo no está entrenado con matryoshka, no trunques. Ahí la reducción honesta pasa por PCA o por un proyector aprendido, y eso ya es un componente más que mantener, versionar y reindexar.

Cuantizar: int8 casi gratis, binario con matices

Bajar de float32 a int8 conserva un recall sorprendentemente alto —en mis pruebas la pérdida ha sido marginal— a cambio de un cuarto de la memoria. El truco es la calibración: necesitas conocer el rango real de tus componentes para mapearlo al rango de int8, y ese rango se calcula sobre una muestra representativa de tu corpus, no sobre el primer lote que tengas a mano.

La cuantización binaria es otra historia. Reduces cada componente a un bit según su signo, ocupas 32 veces menos y comparas con distancia de Hamming, que es un XOR y un popcount: brutalmente rápido. Pero pierdes recall de forma visible. Nadie serio usa binario como respuesta final; se usa como filtro.

💡 La pregunta correcta no es "¿qué precisión uso?" sino "¿qué precisión uso en cada fase?". Buscar y decidir son problemas distintos y merecen representaciones distintas.

El patrón que uso: buscar barato, decidir caro

En lugar de elegir un único formato, guardo dos. Un vector pequeño y cuantizado para recorrer el índice, y el vector completo en float32 —o algo cercano— para reordenar los pocos candidatos que sobreviven.

La primera fase recupera, digamos, los 200 candidatos más cercanos usando el vector barato. Es una fase de recall: solo tiene que garantizar que los buenos estén dentro de esos 200, no que estén bien ordenados. La segunda fase toma esos 200, calcula la similitud con el vector de precisión completa y los ordena de verdad. Esa segunda fase toca 200 vectores, no un millón, así que la memoria del índice no la limita: los vectores completos pueden vivir en disco o en una tabla normal de Postgres.

-- Fase 1: recall barato sobre el vector cuantizado (indexado)
WITH candidatos AS (
  SELECT id
  FROM documentos
  ORDER BY embedding_int8 <=> $1::vector
  LIMIT 200
)
-- Fase 2: reordenar los 200 con el vector de precisión completa
SELECT d.id, d.titulo, d.embedding_full <=> $2::vector AS distancia
FROM documentos d
JOIN candidatos c ON c.id = d.id
ORDER BY distancia
LIMIT 10;

Esto es exactamente la misma idea que aplicar un reranker encima de la búsqueda semántica, pero un piso más abajo: en vez de un modelo caro reordenando, es un vector caro reordenando. Y se pueden combinar los dos.

Cómo decido el punto de corte

No hay número mágico. Lo que hago es medir. Congelo un conjunto de consultas con sus resultados relevantes conocidos, defino como referencia el recall@10 con el vector completo en float32, y voy probando configuraciones: 3072/float32, 1024/float32, 1024/int8, 512/int8, binario+rerank. Cada una da un par (recall, memoria). Con esa tabla delante la decisión deja de ser una discusión de opiniones y pasa a ser una elección de trade-off explícita.

Mi sesgo por defecto, cuando el corpus es grande: dimensiones medias con int8 en el índice, vector completo guardado aparte para la segunda fase. Elegí eso porque el coste de memoria del índice cae casi un orden de magnitud, a cambio de una consulta con dos pasos en vez de uno y de mantener dos columnas sincronizadas cuando reindexas. Ese es el precio real, y hay que decirlo: cada esquema de compresión es una migración pendiente. El día que cambies de modelo de embeddings, reindexas ambas columnas.

Y una advertencia final: no optimices esto antes de tener el problema. Con cien mil vectores, float32 completo cabe en memoria sin despeinarse y no vas a notar la diferencia. La compresión es una respuesta a una restricción concreta, no una virtud en sí misma.

El caso base: un <form> que ya funciona

Un formulario con action y method envía datos al servidor y navega al resultado. Sin JS. Los inputs con required, type="email", minlength o pattern validan en el cliente sin una línea de código. El <label> asociado da accesibilidad gratis. El botón de submit muestra un estado de carga nativo del navegador.

<form action="/api/contacto" method="post">
  <label for="email">Correo</label>
  <input id="email" name="email" type="email" required />
  <button type="submit">Enviar</button>
</form>

Eso funciona en un móvil con la red a medias, mientras tu bundle todavía se descarga, con JS deshabilitado, o cuando un script de terceros revienta y se lleva por delante la hidratación. En un sitio Astro, donde la mayoría de las islas ni siquiera se hidratan, esto no es una hipótesis: es el comportamiento normal de la página.

La validación no puede vivir en un solo sitio

Aquí es donde suele romperse la disciplina. La gente valida en el cliente con una librería, y en el servidor vuelve a validar con otra lógica escrita a mano. Dos fuentes de verdad, que divergen en cuanto alguien cambia una regla.

Lo que hago es tener un único esquema —Zod— y usarlo en los dos lados. En el servidor es la verdad; el cliente es una cortesía para dar feedback rápido. Y crucialmente: si el JavaScript no cargó, el servidor sigue validando y devolviendo una página con los errores. El caso base nunca queda desprotegido.

// compartido
export const contacto = z.object({
  email: z.string().email('Correo no válido'),
  mensaje: z.string().min(10, 'Cuéntame un poco más'),
});

// servidor: la única verdad
export async function POST({ request }: { request: Request }) {
  const datos = Object.fromEntries(await request.formData());
  const res = contacto.safeParse(datos);
  if (!res.success) {
    // sin JS: renderiza la página de vuelta con los errores
    return renderConErrores(datos, res.error.flatten().fieldErrors);
  }
  await guardar(res.data);
  return new Response(null, { status: 303, headers: { Location: '/gracias' } });
}

Fíjate en el 303 con Location. Ese redirect después de un POST exitoso es el patrón POST/Redirect/GET, y evita que refrescar la página reenvíe el formulario. Es de 1998 y sigue siendo correcto.

💡 Si tu formulario se rompe cuando falla el JavaScript, no tenías un formulario. Tenías un widget que se parecía a uno.

Añadir JavaScript encima, no debajo

Con el caso base sólido, el JS entra a mejorar. Y lo hace escuchando el submit del formulario que ya existe, no construyendo uno nuevo.

form.addEventListener('submit', async (e) => {
  e.preventDefault(); // solo se ejecuta si este script cargó
  const datos = new FormData(form);
  const res = contacto.safeParse(Object.fromEntries(datos));
  if (!res.success) return pintarErrores(res.error.flatten().fieldErrors);

  boton.disabled = true;
  const r = await fetch(form.action, { method: 'POST', body: datos });
  boton.disabled = false;
  if (r.redirected) location.assign(r.url);
});

La clave está en el orden mental: el preventDefault() es una optimización opcional que solo ocurre si el script se ejecutó. Si no se ejecuta, el navegador hace su trabajo de siempre. No hay ruta rota, hay una ruta menos pulida.

Y fíjate en algo más: uso new FormData(form) en vez de leer un estado de React. El DOM ya es el estado del formulario. Mantener una copia en useState sincronizada con cada onChange es trabajo que la plataforma hace gratis, y es la causa de la mitad de los bugs de formularios que he depurado: inputs controlados que pierden el cursor, autocompletado del navegador que no dispara el evento, gestores de contraseñas que rellenan campos y el estado de React no se entera.

Lo que gano y lo que pago

Gano robustez real: el formulario funciona antes de la hidratación, con red mala, con JS caído. Gano accesibilidad casi gratis, porque los elementos nativos ya traen su semántica. Gano menos código: no hay reducer de estado de formulario, no hay librería de formularios, no hay validación duplicada.

Lo que pago es que ciertas interacciones muy ricas cuestan más. Un campo con autocompletado remoto, arrastrar y soltar archivos, o un asistente de varios pasos con estado complejo no salen de un <form> pelado. Ahí sí monto un componente controlado, pero de forma localizada: la isla compleja es controlada, y el resto del formulario sigue siendo la plataforma. Elegí esto porque la complejidad se queda contenida donde la necesito, a cambio de tener dos estilos de manejo de campos conviviendo en el mismo archivo, lo cual es feo si no lo documentas.

También pago que el caso "sin JS" hay que probarlo. Si no lo pruebas, se pudre. En los proyectos donde esto me importa, tengo un test que envía el formulario con una petición HTTP plana, sin navegador, y comprueba que la respuesta trae los errores renderizados. Es un test barato y es el único que garantiza que el caso base sigue vivo.

La conclusión no es "no uses JavaScript". Es que el JavaScript debería ser la segunda capa, no los cimientos. Un formulario que solo existe cuando el bundle carga es un formulario con una dependencia que nunca acordaste asumir.

Primero: el historial de los profetas

Repasemos predicciones famosas y su estado real a julio de 2026:

El patrón es clarísimo y es la clave de todo este post: los optimistas aciertan la dirección y fallan el plazo, sistemáticamente por exceso en lo social y por defecto en lo técnico. Nadie predijo que los agentes escribirían código tan bien tan pronto; todos sobreestimaron la velocidad a la que las organizaciones lo absorberían.

El dato que ancla cualquier predicción seria

Si solo puedes mirar una métrica, mira la de METR: la duración de las tareas que un agente completa de forma autónoma (con 50% de éxito) se duplica cada pocos meses — 196 días de media histórica, pero acelerando hacia ~3 meses en los datos desde 2024. En enero de 2026, los mejores modelos completaban tareas de ~5 horas de trabajo humano; trackers no oficiales ya sitúan a los modelos actuales por encima de las 14 horas.

Si la tendencia aguanta — y lleva seis años aguantando — a mediados de 2027 hablamos de agentes completando tareas de una semana de trabajo humano. Esa única curva explica casi todo lo que sigue.

Próximos meses (resto de 2026): consolidación agéntica

Lo que veo prácticamente seguro de aquí a diciembre, porque ya está en marcha:

• La orquestación se vuelve el trabajo. Karpathy lo bautizó «agentic engineering» y acertó: la conversación ya no es «qué editor usas» sino «cuántos agentes diriges en paralelo». Las herramientas de flotas (workflows dinámicos, tareas remotas, agentes en la nube) se convierten en estándar.
• El shock de las facturas. Los cambios de billing de este año (créditos de Copilot, límites por uso en todos lados) son el síntoma: el coste del compute agéntico se vuelve una línea seria del presupuesto de cualquier equipo. Aparecerá tooling de FinOps para agentes.
• MCP se cierra como estándar universal. La spec de julio (apps embebidas, tareas de larga duración, OAuth serio) más la gobernanza de la Linux Foundation lo convierten en el TCP/IP de los agentes. Si tu producto no expone MCP en 2027, no existe para los agentes.
• La verificación se convierte en el cuello de botella oficial. Con benchmarks como SWE-bench saturados (95% el mejor modelo), el problema ya no es generar código: es revisarlo. El 66% de los devs dice que pierde más tiempo arreglando código de IA «casi correcto» que escribiendo. Ahí está la próxima ola de herramientas.

2027: el año de la interfaz

Mi apuesta central para 2027 no va de código, va de interfaces. Las piezas ya están sobre la mesa: navegadores agénticos (Atlas, Comet, Dia) con decenas de millones de usuarios, ChatGPT como plataforma de apps con checkout integrado, y WebMCP para que los sitios expongan acciones directamente a los agentes.

Lo que eso significa en la práctica:

• Tu web tendrá dos públicos: humanos y agentes. Igual que hubo mobile-first, viene el agent-first: APIs limpias, semántica explícita, acciones expuestas por MCP/WebMCP. Una parte creciente de tus «visitas» no verá tu CSS jamás.
• La UI generativa encontrará su sitio — que no es todas partes. El sueño de «la app se genera al vuelo y se borra» chocará con lo que Nielsen lleva años avisando: una interfaz que cambia cada vez es una interfaz que no se puede aprender. El punto de equilibrio: tu UI como implementación de referencia, con los datos y acciones abiertos para que el agente del usuario componga la suya.
• El e-commerce agéntico se normaliza. Con cientos de millones de usuarios semanales en asistentes y protocolos de compra estandarizados, «se lo pedí a mi agente» deja de sonar raro. El SEO muta: de posicionar páginas a posicionar acciones y datos.

💡 Si mantienes un producto web, la pregunta para 2027 no es «¿tengo app móvil?» sino «¿puede un agente usar mi producto sin pantalla?». El que tenga buena API y buena semántica gana el canal nuevo gratis.

2027–2028: qué pasará con los programadores

Aquí es donde más ruido hay y donde los datos dicen algo más matizado que los titulares:

• La pirámide se reestructura, no desaparece. Los ingenieros de software son hoy el 55% de las contrataciones de Big Tech — más que en 2019 (46%). Pero los recién graduados son solo el 7% de esas contrataciones, la mitad que antes de la pandemia. Se contrata más senior y menos junior: la pirámide se está invirtiendo.
• El empleo se movió, no se esfumó. Las vacantes de dev en EE.UU. suben 14% interanual, pero el 71% de esa subida es de roles senior y el 37% lleva «IA» en el título. La compensación de un AI engineer ronda los $242K de media y los perfiles de agentes crecen +136% interanual.
• La escasez de 2029 se está fabricando hoy. Matrícula de informática cayendo 8% anual, bootcamps cerrando en cadena, empresas sin contratar juniors. Nadie está formando a los seniors de dentro de cinco años. Predicción concreta: hacia 2028–2029, pánico por escasez de talento senior y programas de «AI apprenticeship» por todas partes, contratando juniors otra vez — con otro perfil: diseño de sistemas y verificación, no sintaxis.
• Seguirán los recortes «por IA» que no son solo por IA. 2026 lleva ~120.000 despidos tech con la IA como excusa parcial — mezcla de automatización real, sobrecontratación pasada y presión de márgenes. Distinguir cuánto es cada cosa será imposible, y el relato «la IA me quitó el trabajo» convivirá con récords de demanda de ingenieros que sepan dirigirla.

2028–2030: los tres escenarios

A más de dos años vista, lo honesto es hablar de escenarios con probabilidades, no de certezas. Las mías:

• Aceleración continua (~35%). La curva de METR aguanta sin techo: agentes con semanas de autonomía en 2027, «empleado digital» funcional hacia 2028–29. Es el escenario de los laboratorios (aunque hasta Amodei y Altman han suavizado el discurso apocalíptico este año — curiosamente, camino de sus salidas a bolsa).
• Meseta útil (~50%). El que veo más probable. La generación de código sigue mejorando pero los problemas duros — memoria persistente, aprendizaje continuo, coherencia en horizontes largos — resultan resistentes, como avisan Marcus y LeCun (que se fue de Meta a fundar una startup de world models precisamente por esto). Los agentes se vuelven infraestructura como lo fue la nube: transformadora, no apocalíptica. Los pronósticos tipo «AI 2027» ya se han deslizado a «principios de los 2030», y Metaculus da 50% a AGI en 2033.
• Invierno parcial (~15%). El gasto en compute no encuentra retorno al ritmo prometido, corrección fuerte de valoraciones, consolidación. Ojo: incluso aquí, las capacidades ya desplegadas no se van — nadie va a volver a escribir CRUD a mano.

Mis predicciones concretas, para poder fallar en público

Como me he pasado el post auditando las predicciones de otros, lo justo es dejar las mías por escrito, con fecha, para que me las auditen:

// Predicciones — julio 2026 (revisar en julio 2027)
// 1. Para dic 2026: los agentes completan tareas de ~2 días
//    de trabajo humano de forma fiable.            [80%]
// 2. Para jun 2027: >50% del código nuevo en empresas tech
//    es generado por IA (media industria, no solo labs). [70%]
// 3. Para 2027: al menos una app del top-100 elimina su UI
//    tradicional en favor de interfaz agéntica/conversacional. [60%]
// 4. Para 2028: la contratación de juniors se recupera con
//    formato aprendiz-de-IA tras el pánico de escasez.  [65%]
// 5. Para 2030: sigue habiendo MÁS gente trabajando en
//    software que en 2025 (contando nuevos roles).      [75%]
// 6. AGI/trabajador digital drop-in antes de 2030.      [25%]

El cierre honesto

La predicción número 5 es la que de verdad importa y la que más convencido estoy de que se cumple. Cada vez que el coste de crear software ha caído — compiladores, open source, la nube — el mundo no ha querido menos software: ha querido órdenes de magnitud más. La demanda de software siempre ha estado limitada por la oferta, y acabamos de hacer la oferta casi infinita.

Lo que desaparece no es el programador; es el programador definido como «persona que traduce especificaciones a sintaxis». Lo que nace es algo más parecido a un director de sistemas que decide, verifica y responde. Los próximos tres años van a ser incómodos, desiguales y llenos de titulares exagerados en ambas direcciones. Pero si tuviera que elegir un momento de la historia para saber construir software, elegiría exactamente este.

Por qué existe el NAT Gateway

Una subred privada, por definición, no tiene ruta a un Internet Gateway. Eso es lo que la hace privada: nada de fuera puede iniciar una conexión hacia dentro. Pero tus contenedores sí necesitan salir: a descargar una imagen de ECR, a leer un secreto, a llamar a una API de terceros.

El NAT Gateway resuelve eso: vive en una subred pública, las privadas enrutan su tráfico saliente hacia él, y él traduce las direcciones para que las respuestas vuelvan. Funciona, es gestionado, es altamente disponible dentro de su AZ. Y por eso todo el mundo lo pone y se olvida.

El problema es su modelo de precios. Pagas una tarifa por hora por cada NAT Gateway —y como cada uno vive en una AZ, la práctica recomendada de alta disponibilidad te pide uno por AZ, así que multiplica— más una tarifa por cada gigabyte que lo atraviesa. Ese cargo por gigabyte se aplica al tráfico procesado, y se acumula sin que nadie lo esté mirando.

El descubrimiento incómodo: buena parte de ese tráfico es interno

Aquí está el detalle que cambia el análisis. Cuando tu tarea de Fargate en una subred privada escribe un objeto en S3, ese tráfico sale por el NAT Gateway, va al endpoint público de S3 y vuelve. Estás pagando transferencia por hablar con un servicio de AWS que está en la misma región que tú.

Lo mismo con DynamoDB, con SQS, con Secrets Manager, con CloudWatch Logs —y CloudWatch Logs es el gran sospechoso silencioso, porque si tienes logs verbosos, cada línea es tráfico facturado— y con ECR cada vez que arranca una tarea y baja capas de imagen.

En arquitecturas serverless o de contenedores bien pobladas, la mayoría del tráfico saliente no va a internet de verdad. Va a AWS.

VPC endpoints: dos sabores, precios muy distintos

Un VPC endpoint permite que tu subred privada hable con un servicio de AWS sin pasar por internet ni por el NAT. Hay dos tipos, y confundirlos es caro.

Los gateway endpoints existen solo para S3 y DynamoDB. Son una entrada en la tabla de rutas. No cuestan nada: ni por hora, ni por gigabyte. No hay ninguna razón defendible para no tenerlos si usas S3 o DynamoDB desde subredes privadas. Es dinero tirado.

Los interface endpoints (PrivateLink) son para todo lo demás: SQS, Secrets Manager, ECR, CloudWatch, KMS. Crean una interfaz de red en tu subred con una IP privada. Estos sí cuestan: una tarifa por hora por endpoint y por AZ, más un cargo por gigabyte —bastante más barato que el del NAT, pero no cero.

💡 Los gateway endpoints de S3 y DynamoDB son gratis. Si tus subredes privadas no los tienen, estás pagando NAT Gateway por hablar con S3. Ese es el primer sitio donde mirar, y suele ser el más rentable.

Cómo decido qué endpoints crear

Con interface endpoints la cuenta no es automática, porque tienen coste fijo por hora y por AZ. Un endpoint vale la pena cuando el ahorro en tráfico NAT supera esa tarifa fija. La forma de saberlo es mirar los datos, no adivinar: activo Flow Logs en la interfaz elástica del NAT Gateway y agrupo por IP destino, resolviendo esas IPs contra los rangos publicados de AWS para saber qué servicio es cuál.

Con esa tabla delante la decisión es aritmética. Si el 60% de tu tráfico NAT es a S3, un gateway endpoint gratis se lo lleva entero. Si otro 20% es CloudWatch Logs, el interface endpoint se paga solo. Si hay un 5% a KMS, probablemente no compense el coste fijo.

En OpenTofu es tan poco código que casi da vergüenza no tenerlo:

# Gratis. Sin excusas.
resource "aws_vpc_endpoint" "s3" {
  vpc_id            = aws_vpc.main.id
  service_name      = "com.amazonaws.${var.region}.s3"
  vpc_endpoint_type = "Gateway"
  route_table_ids   = aws_route_table.private[*].id
}

# De pago: crea una ENI por subred. Justifícalo con datos.
resource "aws_vpc_endpoint" "logs" {
  vpc_id              = aws_vpc.main.id
  service_name        = "com.amazonaws.${var.region}.logs"
  vpc_endpoint_type   = "Interface"
  subnet_ids          = aws_subnet.private[*].id
  security_group_ids  = [aws_security_group.endpoints.id]
  private_dns_enabled = true # sin esto, tu SDK sigue yendo al endpoint público
}

Ese private_dns_enabled es el que hace que funcione sin tocar el código: resuelve el nombre público del servicio a la IP privada del endpoint. Si lo dejas en false, creas el endpoint, pagas por él, y tu aplicación sigue saliendo por el NAT tan tranquila. Es un error que solo se ve en la factura.

La pregunta más incómoda: ¿necesitas el NAT?

Antes de optimizar el NAT Gateway conviene preguntarse si hace falta. Si tus contenedores solo hablan con servicios de AWS y nunca llaman a una API de terceros, puedes cubrir todo con endpoints y quitarlo. Es la única optimización que lleva ese coste a cero.

En la práctica casi siempre hay algo que sale a internet: un webhook, una pasarela de pagos, un proveedor de LLM. Entonces el NAT se queda, pero con la mayoría del tráfico desviado, y su factura pasa de ser un misterio a ser una línea pequeña y explicable.

El trade-off honesto: añades componentes de red que hay que mantener, versionar en tu IaC y depurar cuando un security group mal configurado hace que un endpoint tire timeouts en vez de errores claros. A cambio, el tráfico interno deja de tocar internet —lo que además es mejor postura de seguridad— y la factura deja de crecer con tu volumen de logs. Para mí ha compensado siempre. Pero decídelo con Flow Logs, no con este artículo.

Esto no es un post motivacional ni una lista de «5 cursos para no quedarte atrás». Es lo que veo desde dentro — trabajando cada día con agentes que escriben la mayor parte de mi código — sobre qué está cambiando de verdad, qué se devalúa, qué sube de precio y qué haría yo hoy según el punto de la carrera en el que estés.

Lo primero: separar el ruido de la señal

La confusión viene de mezclar dos preguntas distintas. «¿Puede la IA escribir código?» — sí, desde hace tiempo, y mejor que la mayoría de nosotros en tareas acotadas. «¿Puede la IA hacer el trabajo de un ingeniero?» — no, porque el trabajo nunca fue escribir código.

El trabajo siempre fue otro: entender un problema ambiguo, decidir qué construir (y qué no), negociar restricciones, detectar que el ticket pide una cosa pero el negocio necesita otra, y responder por lo que se despliega. Nada de eso ha sido automatizado. Lo que se automatizó es la parte que estaba en medio: traducir decisiones a sintaxis.

💡 La frase que me ordena la cabeza: la IA no viene a por tu trabajo, viene a por tus tareas. Si tu trabajo era la suma de esas tareas, sí tienes un problema. Si tu trabajo era el criterio que las ordenaba, acabas de multiplicarte.

Qué se devalúa (y duele decirlo)

Seamos honestos con lo que ya vale menos en el mercado:

• Escribir código correcto y limpio a mano. Era nuestra identidad. Hoy es la línea base que produce cualquier agente bien dirigido.
• Saberse un framework de memoria. El conocimiento enciclopédico de una API era una ventaja competitiva; ahora está a un prompt de distancia de cualquiera.
• El junior que solo ejecuta tickets. Este es el golpe más duro y el más real: el trabajo de «toma esta tarea bien definida y tráemela hecha» es exactamente lo que mejor hace un agente.
• La velocidad de tecleo como métrica de productividad. Producir más líneas ya no distingue a nadie. Distingue producir menos líneas que sobrevivan más tiempo.

Qué sube de precio

La lista contraria es más interesante, porque es donde hay que invertir:

• Criterio de revisión. El código generado por IA se ve impecable — está formateado, nombrado con sentido, comentado. El peligro vive en lo que parece correcto. Saber leer código con sospecha vale hoy más que saber escribirlo.
• Arquitectura y descomposición. Un agente rinde en proporción directa a lo bien acotado que esté el problema. Trocear un sistema en piezas que una IA pueda ejecutar sin romper nada es la nueva habilidad senior.
• Contexto de negocio. Entender por qué se construye algo es lo único que la IA no puede inferir de tu repo. El ingeniero que habla con producto y con clientes se vuelve imposible de reemplazar.
• Verificación. Tests, evals, observabilidad, entornos de staging que se parecen a producción. Cuando el volumen de código se multiplica, el cuello de botella se muda a la confianza: ¿cómo sé que esto funciona?
• Responsabilidad. Alguien tiene que firmar el despliegue. La IA no va a la reunión de postmortem. Ese «alguien» cotiza al alza.

El nuevo flujo de trabajo (el mío, al menos)

Mi día a día ya no se parece al de hace tres años. El patrón que me funciona tiene tres fases, y ninguna es «escribir código»:

// Mi división del trabajo con agentes
// 1. ANTES  — invertir en contexto: specs claras, convenciones
//             documentadas, criterios de aceptación explícitos.
// 2. DURANTE — dirigir, no dictar: el agente propone, yo corto
//              alcance, corrijo rumbo, pido alternativas.
// 3. DESPUÉS — verificar con hostilidad: leer el diff como si
//              lo hubiera escrito alguien que quiere engañarme,
//              correr los tests, probar los bordes.

La proporción sorprende a quien no lo ha vivido: paso más o menos un 40% del tiempo en la fase 1. La calidad de lo que sale de un agente es una función casi lineal de la calidad del contexto que entra. Los equipos que adoptan IA y no ven mejora casi siempre fallan ahí: delegan la escritura pero no invierten en la especificación.

Si estás empezando: el consejo incómodo

El escalón de entrada se rompió, y no ayuda a nadie negarlo. Pero fíjate en el matiz: se rompió el escalón, no la escalera. Las empresas siguen necesitando seniors, y los seniors no nacen — se hacen. Tarde o temprano el mercado tendrá que reconstruir la cantera, y los juniors que sobrevivan a esta transición serán los que llegaron distinto:

• Usa la IA para aprender, no para evitar aprender. Pídele que te explique cada línea que genera. La diferencia entre «funciona y no sé por qué» y «funciona y sé por qué» es tu carrera entera.
• Construye cosas completas. Un side project desplegado, con usuarios reales y bugs reales, enseña lo que ningún tutorial: la parte del oficio que la IA no cubre.
• Aprende a depurar de verdad. Cuando el agente se atasca — y se atasca — la persona que sabe bajar al log, al breakpoint y al protocolo es la que desbloquea al equipo.
• Los fundamentos no caducan. Redes, sistemas operativos, bases de datos, complejidad. Los frameworks que la IA domina cambian cada año; aquello sobre lo que se apoyan, no.

Si llevas años en esto: tu riesgo es otro

El senior no compite contra la IA; compite contra el senior que la usa bien. Y ahí veo dos errores simétricos. El primero es el rechazo: «yo reviso mejor que cualquier modelo» — cierto hoy, irrelevante en dos ciclos de mejora. El segundo es la rendición: aceptar todo lo que genera el agente sin leerlo, hasta que un incidente en producción te recuerda quién firmaba.

El punto medio tiene nombre aburrido: gestión. Diriges una pequeña flota de agentes igual que antes coordinabas personas — con specs, con revisión, con estándares. Si alguna vez pensaste en pasar a management pero no querías dejar de tocar código, la buena noticia es que ese puesto híbrido acaba de inventarse y nadie tiene diez años de experiencia en él.

Lo que no cambia

Después de todo el vértigo, hay algo que me tranquiliza: el software sigue siendo la disciplina de decidir qué debe pasar y asegurarse de que pasa. Las herramientas para lograrlo han cambiado más en tres años que en los veinte anteriores, pero la naturaleza del oficio — criterio, responsabilidad, traducción entre lo que la gente necesita y lo que la máquina hace — sigue intacta.

Sobrevivir a esta era no va de correr más que la IA. Va de moverse un nivel por encima de ella, que es exactamente el mismo movimiento que hizo quien pasó del ensamblador al compilador, y del servidor físico a la nube. Los que se quedaron abrazados a la capa que se automatizaba lo pasaron mal. Los que subieron de capa, no dieron abasto con tanto trabajo.

Aviso previo: no hay stack perfecto, hay stacks adecuados a tu equipo y a tu etapa. Lo que sigue está sesgado hacia lo que optimiza una startup pequeña: velocidad de iteración, poco mantenimiento y facturas predecibles.

Agentes de código: la decisión más importante

La herramienta con la que escribes código define tu velocidad más que cualquier framework. El panorama actual:

Mi lectura: la categoría ya no compite en «autocompletar mejor», compite en orquestación — cuántos agentes puedes dirigir a la vez y con qué confianza. Claude Code es mi driver diario por eso mismo; Cursor sigue siendo el mejor editor si quieres IDE tradicional con agente dentro.

💡 Trampa del mes: GitHub cambió en junio los Premium Requests por «AI Credits» y hay equipos reportando facturas 10 veces mayores en flujos agénticos. Sea cual sea tu herramienta, pon alertas de gasto antes de soltar agentes en paralelo.

Modelos: precios de julio de 2026

Si construyes producto sobre LLMs, esto es lo que cuesta hoy el millón de tokens (entrada/salida):

La estrategia sensata para un SaaS: modelo barato (Sonnet 5, Terra, Gemini) para el 90% de las llamadas, y escalar al tope de gama solo cuando el caso lo justifique. Un router de modelos de 30 líneas te ahorra miles de dólares al mes.

Frameworks web: menos drama del que parece

• Next.js 16.2 sigue siendo el default racional para SaaS: Turbopack ya es estable y por defecto, React Compiler integrado, y el ecosistema de ejemplos es imbatible. Aburrido y correcto.
• Astro — recién adquirido por Cloudflare en enero — sigue siendo mi elección para todo lo que sea contenido (este blog corre en Astro). Sigue MIT y con gobernanza abierta.
• TanStack Start llegó a v1.0 estable en marzo y es la alternativa seria si quieres type-safety extremo sin la magia de Next.
• SvelteKit y React Router 7 están maduros y son excelentes; elegirlos es más una cuestión de gusto de equipo que de capacidades.

La verdad incómoda: con agentes escribiendo la mayoría del código, la elección de framework importa menos que hace tres años. Los agentes rinden mejor en frameworks con más corpus público — otro punto para Next y Astro.

Backend e infra: el dato del año

El dato que mejor resume 2026: Supabase reportó que la mayoría de sus bases de datos nuevas ya las despliegan agentes de IA, no humanos — creación de bases de datos creciendo 600% interanual. Tu infraestructura ya no la elige solo tu equipo; la «eligen» también los agentes, y van a lo que saben usar.

• Postgres gana por goleada: Supabase (acaba de levantar $500M a valoración de $10.5B) como backend completo, o Neon (ya dentro de Databricks) si solo quieres la base de datos.
• Vercel para el despliegue si vas con Next: Fluid Compute eliminó los cold starts de verdad.
• Cloudflare Workers + D1 + R2 es la alternativa cost-effective, y con Astro en casa, cada vez más pulida.
• Runtimes: Node 24 sigue siendo el default empresarial. Bun — adquirido por Anthropic en diciembre — completó su reescritura en Rust en mayo y es mi elección para proyectos nuevos: velocidad y tooling integrado.

La capa de IA de tu producto

Aquí es donde veo más errores de sobre-ingeniería. Lo que de verdad necesita una startup:

// La capa de IA mínima viable en 2026
// 1. SDK: Vercel AI SDK 6 (TypeScript) o Claude Agent SDK
//    si el producto ES un agente. LangGraph 1.0 si necesitas
//    grafos de estado complejos (Uber, Klarna lo usan así).
// 2. Contexto: MCP. Ya es estándar de la Linux Foundation,
//    97M de descargas mensuales. No inventes tu protocolo.
// 3. Vectores: pgvector hasta ~10M de vectores (~$30/mes).
//    No pagues un vector DB dedicado antes de tener el problema.
// 4. Evals desde el día uno: si no mides la calidad del LLM,
//    cada deploy es una apuesta.

El punto 3 merece énfasis: pgvector en tu Postgres de siempre cubre a casi cualquier startup con latencias de 8–25ms. Notion recortó ~60% su coste de búsqueda migrando de vector DB dedicado a almacenamiento sobre objetos; tú probablemente no necesitas ni eso todavía.

Vibe coding: úsalo para lo que es

Lovable ($400M ARR en febrero, en conversaciones para levantar a valoración de dos dígitos en miles de millones), Replit ($9B de valoración en marzo), v0, Bolt. Son máquinas de validar ideas: de prompt a prototipo desplegado en una tarde. Lo que no son — todavía — es la base de un producto que tenga que escalar con requisitos serios de seguridad y datos. El patrón que veo funcionar: prototipa en Lovable o v0, valida con usuarios reales, y reconstruye sobre tu stack cuando haya señal.

Mi receta concreta

Si mañana empezara un SaaS B2B, sin más contexto que «quiero validar rápido y no quemar dinero»:

• Código: Claude Code como agente principal + revisión humana de todo lo que toque dinero, permisos o datos.
• App: Next.js 16 + TypeScript en Vercel. Contenido/marketing: Astro.
• Datos: Supabase (Postgres + auth + storage + pgvector).
• IA: Vercel AI SDK 6, Sonnet 5 por defecto con escalado a Opus 4.8, MCP para integraciones, evals con casos reales desde la primera semana.
• Runtime: Bun en local y CI; Node 24 donde la plataforma lo pida.

¿Es el stack más potente posible? No. Es el que te deja iterar cada día con dos personas y media, que en 2026 es exactamente el juego: la ventaja ya no está en la infraestructura que montas, sino en la velocidad con la que aprendes qué construir.

Antes de empezar, transparencia metodológica: uso solo cifras con fuente pública. Cuando un dato es estimación de terceros (y no cifra confirmada por la empresa) lo marco como tal. Y aun con ese filtro, lo que queda es difícil de creer.

La curva que resume la era: Cursor

Anysphere (Cursor) fue en su momento el SaaS más rápido de la historia en llegar a $100M de ARR. Eso fue en enero de 2025. Lo que pasó después es la gráfica que define esta era:

De $100M a ~$4.000M de ingresos anualizados en 17 meses, con unos $2.600M viniendo de empresa (B2B). Su Serie D de noviembre de 2025 la valoró en $29.300M, y en abril de 2026 se reportaban conversaciones para levantar a ~$50.000M. Para calibrar: Salesforce tardó más de una década en facturar lo que Cursor alcanzó en tres años.

Los multiplicadores de 2026

Cursor no es un caso aislado. Esta es la tabla de lo que va de año:

Y el contexto de fondo: Anthropic pasó de un run-rate de $9.000M a final de 2025 a $47.000M en mayo de 2026, y Claude Code por sí solo facturaba $1.000M anualizados a los seis meses de salir. La demanda de construir con IA es la marea que sube todos estos barcos.

El dato más disruptivo: ingresos por empleado

Lo que de verdad rompe los modelos mentales no es cuánto facturan, sino con cuánta gente. Facturación anual por empleado, en millones de dólares:

Para poner esto en perspectiva: una empresa de software tradicional bien gestionada ronda los $200.000–400.000 por empleado. Los casos de arriba están entre 5 y 40 veces por encima:

• Gamma pasó los $100M de ARR con unas 50 personas, rentable desde hace más de dos años.
• Midjourney factura ~$500M con menos de 110 empleados y sin haber levantado un dólar de capital riesgo. Nunca.
• Mercor cruzó los $1.000M de ARR con ~200 personas y flujo de caja positivo.
• Cursor opera ~$4.000M con unos 300 empleados (estimación; la cifra no es oficial).

Los pequeños: fundadores en solitario que salieron por la puerta grande

Los titulares se los llevan los unicornios, pero las historias más replicables son otras:

• Base44 (Maor Shlomo). Un solo fundador, bootstrapped, construyendo con IA. Lanzó a principios de 2025, llegó a $1,5M de ARR en 4 semanas y a $3,5M con 300.000 usuarios en 6 meses. Wix la compró por $80M en cash a los seis meses del lanzamiento — y los hitos posteriores le pagaron $38M adicionales. Ocho empleados en el momento de la venta.
• Cal AI (Zach Yadegari y Henry Langmack). Dos fundadores que empezaron con 17 años: una app que cuenta calorías a partir de fotos con IA. $30M de ingresos en 2025, $5,7M solo en enero de 2026, y en marzo — con $50M de ARR — la compró MyFitnessPal.

💡 El patrón común de ambos: no inventaron tecnología nueva. Aplicaron modelos que cualquiera puede usar por API a un problema aburrido y concreto, y ejecutaron más rápido que nadie. La ventaja ya no es el acceso a la IA — es la velocidad de iteración sobre un caso de uso.

Y por debajo de todo: el código ya lo escribe la IA

Estos éxitos flotan sobre un cambio estructural medible. Google lo ha ido publicando con fechas:

En Anthropic la cifra interna reportada supera el 90%. Y en Y Combinator, que es donde mejor se ve el futuro inmediato: ya en el batch W25 un 25% de las startups tenía el 95% del código generado por IA; en el Demo Day de W26 (marzo 2026), 14 startups llegaron con más de $1M de ARR antes del Demo Day — el triple que el año anterior y récord histórico — con un crecimiento medio del 14% semanal, el más alto que YC ha registrado en 20 años.

Los patrones que se repiten

Después de mirar todos estos casos, los denominadores comunes que veo:

• Equipos diminutos por diseño, no por falta de dinero. Lovable levantó cientos de millones y sigue en ~250 personas. La restricción de headcount es estrategia: menos coordinación, más agentes.
• Velocidad como único foso. Casi ninguno tiene tecnología defendible per se; tienen ritmo de shipping que la competencia no iguala.
• Distribución primero. Cal AI creció por redes sociales antes de tener producto maduro; Lovable convirtió a cada usuario en marketing con el «mira lo que construí».
• El B2B paga las curvas. La aceleración de Cursor y Devin viene de contratos enterprise (Goldman Sachs, Citi y la NASA son clientes de Cognition), no de developers individuales.

La letra pequeña

Para ser justos con los datos: varias cifras de ARR de 2026 (Lovable ~$500M, Replit ~$525M, Claude Code) son estimaciones de trackers como Sacra, no confirmaciones oficiales; la ronda de Lovable a ~$12.000M seguía en negociación al cierre de esto; y por cada caso de éxito hay cientos de wrappers de GPT que murieron sin titular — el sesgo de supervivencia en esta lista es máximo.

Pero incluso descontando todo eso, la señal es clara: en 2026 ya no hay correlación entre tamaño de equipo y tamaño de negocio. Y esa, para cualquiera que sepa construir software, es la mejor noticia en décadas: nunca ha sido tan barato intentarlo.

Primero pregunto: ¿es un problema de conocimiento o de comportamiento?

Esta es la bifurcación que ordena todo lo demás. Si el modelo falla porque no sabe algo —datos de tu dominio, documentación interna, hechos posteriores a su corte de entrenamiento— es un problema de conocimiento, y el conocimiento se inyecta por contexto, no se hornea en pesos. Ahí RAG es la respuesta por defecto.

Si el modelo sabe lo que necesita pero responde con el formato, el tono o la estructura equivocados de forma consistente, es un problema de comportamiento. Y el comportamiento sí es candidato a fine-tuning… pero solo después de que el prompting se quede corto, que es más tarde de lo que la gente cree.

Confundir estas dos ramas es el error más caro que veo. Nadie arregla con fine-tuning que el modelo no conozca tu catálogo de productos: lo entrenas hoy y mañana el catálogo cambió. Y nadie arregla con RAG que el modelo se niegue a devolver JSON limpio: por muchos documentos que le metas, el problema es de forma, no de datos.

Prompting: el escalón que casi siempre subestimo

Mi punto de partida es siempre prompting, porque es el único cambio que despliego en minutos y revierto en segundos. Antes de tocar nada más, exprimo instrucciones claras, ejemplos few-shot representativos y una estructura de salida explícita. En JXBS, buena parte de lo que parecía pedir un modelo afinado se resolvió con tres ejemplos bien elegidos en el prompt y un esquema de salida estricto.

El coste de esta rama es el contexto: cada ejemplo que metes ocupa tokens que pagas en cada llamada, y un prompt de 20 ejemplos se vuelve caro y lento a escala. Ese es exactamente el síntoma de que quizá toca subir de escalón: cuando necesitas tantos ejemplos que el prompt es la mitad de tu factura, el patrón ya está ahí y puede valer la pena hornearlo.

💡 Si no has intentado resolverlo con prompting durante al menos una tarde, no tienes datos para justificar fine-tuning. "Probamos un prompt y no salió" no es prompting, es una anécdota.

RAG: para conocimiento que cambia y debe ser citable

Cuando el problema es de conocimiento, RAG gana casi siempre por una razón que va más allá de lo técnico: la trazabilidad. Un sistema RAG puede decirte de qué documento salió la respuesta. Un modelo afinado te da la respuesta desde dentro de sus pesos, sin fuente, y cuando alucina no tienes dónde mirar.

// El conocimiento vive fuera del modelo y se actualiza sin reentrenar
const contexto = await buscarFragmentos(pregunta, { topK: 5 });
const respuesta = await llm.completar({
  system: 'Responde solo con la información de <contexto>. Si no está, dilo.',
  contexto,
  pregunta,
});

El trade-off que acepto con RAG es operativo: ahora mantengo un pipeline de ingesta, embeddings, un índice vectorial y una estrategia de chunking. Es más infraestructura que un prompt. A cambio, actualizo el conocimiento cambiando documentos, no reentrenando, y eso en un dominio que se mueve vale oro.

Fine-tuning: el último escalón, y sé por qué subo

Llego a fine-tuning solo cuando se cumplen tres cosas a la vez: el comportamiento que quiero es estable y repetido, prompting me lo da pero a un coste de tokens insostenible, y tengo suficientes ejemplos reales de calidad para entrenar. Si me falta cualquiera de las tres, no subo.

Lo que compro con fine-tuning es un modelo que hace lo que quiero con un prompt corto, más barato y más rápido por llamada. Lo que pago es rigidez: cada cambio de comportamiento es un reentrenamiento, el dataset se convierte en un activo que hay que versionar y cuidar, y he introducido un artefacto que puede quedar obsoleto en silencio. El fine-tuning no elimina RAG, además: lo más potente que he montado combina un modelo afinado en cómo responder con RAG para qué saber.

El error de saltarse escalones

El antipatrón que más me ha costado es empezar por el final. Equipos que montan fine-tuning para un problema que un prompt resolvía, y acaban con un modelo caro de mantener que no rinde mejor que la línea base que nunca midieron. Empezar barato no es ser conservador: es generar la evidencia que justifica el siguiente paso. Cuando por fin haces fine-tuning tras agotar prompting y RAG, sabes exactamente qué estás comprando y por qué. Esa claridad es la diferencia entre una decisión de ingeniería y una compra por moda.

El problema: la orquestación escondida en el código

Cuando una Lambda invoca a la siguiente, la lógica del proceso —el orden, los reintentos, qué hacer si el paso tres falla— vive repartida entre funciones. No hay un sitio donde leer "así funciona este flujo completo". Para entenderlo abres cinco archivos y reconstruyes el grafo en tu cabeza.

El día que ese proceso falla en producción a mitad de camino, la pregunta clave es "¿en qué paso se quedó y con qué datos?". Con Lambdas encadenadas, la respuesta está enterrada en logs de cinco funciones distintas que tienes que correlacionar a mano. Con un orquestador, la respuesta es una pantalla: ves la ejecución, el estado exacto donde murió y el input que recibió.

La máquina de estados como documentación ejecutable

Lo que más valoro de Step Functions es que la definición del flujo es el diagrama. No hay un doc en Confluence que se desactualiza: la fuente de verdad del proceso es la máquina de estados que corre en producción.

{
  "StartAt": "ValidarPedido",
  "States": {
    "ValidarPedido": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:...:validar",
      "Retry": [{ "ErrorEquals": ["Timeout"], "MaxAttempts": 3 }],
      "Next": "CobrarPago"
    },
    "CobrarPago": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:...:cobrar",
      "Catch": [{ "ErrorEquals": ["States.ALL"], "Next": "Compensar" }],
      "Next": "Confirmar"
    },
    "Compensar": { "Type": "Task", "Resource": "arn:aws:lambda:...:revertir", "End": true },
    "Confirmar": { "Type": "Task", "Resource": "arn:aws:lambda:...:confirmar", "End": true }
  }
}

Fíjate en dónde vive la política de reintentos y la de compensación: en la definición, declarativa, no repartida por try/catch en cada función. Cada Lambda vuelve a hacer una sola cosa y el orquestador se encarga del resto. Ese es el reparto de responsabilidades que perseguía.

Reintentos y compensación sin escribirlos a mano

El motivo por el que más migro flujos a Step Functions es el manejo de fallos. En Lambdas encadenadas, reintentar con backoff, distinguir errores transitorios de permanentes y compensar pasos ya ejecutados cuando algo falla a mitad es código que escribes, testeas y mantienes tú, mal, en cada función.

En la máquina de estados, Retry y Catch son parte de la definición. Un timeout se reintenta tres veces con backoff exponencial sin que yo escriba un bucle. Y el patrón saga —si el pago falla tras reservar inventario, revierte la reserva— se expresa con un estado de compensación al que saltas con Catch, en vez de con banderas repartidas por medio backend.

💡 La pregunta que uso para decidir: ¿necesito saber en qué paso exacto se quedó una ejecución que falló, semanas después? Si la respuesta es sí, la orquestación explícita se paga sola en el primer incidente.

Dónde NO uso Step Functions

Ser honesto con los trade-offs es lo que separa una decisión de un acto de fe. No meto Step Functions en todo.

Para un flujo síncrono y simple donde el usuario espera una respuesta en la pantalla, un orquestador solo añade latencia y una capa que nadie pidió; una Lambda directa es lo correcto. Tampoco lo uso para procesos de altísimo volumen y baja duración donde cada transición de estado se factura: el modelo Standard cobra por transición y a millones de ejecuciones cortas eso escala en tu factura de formas que sorprenden. Para ese caso miro Express, que cambia el modelo de precio y la garantía de durabilidad, o directamente una cola SQS con un consumidor que hace todo el trabajo de una vez.

Y hay un coste humano: el lenguaje de definición es una cosa más que el equipo tiene que aprender y leer. Si tu flujo tiene dos pasos y nunca crecerá, esa curva no vale la pena.

El precio real que pagué

Lo más caro de adoptar Step Functions no fue el servicio, fue reescribir la mentalidad del equipo. Pasamos de "la lógica está en el código" a "la lógica está en la definición del estado", y durante un tiempo la gente seguía metiendo coordinación dentro de las Lambdas por costumbre, duplicando lo que la máquina ya hacía. La regla que fijé fue clara: las Lambdas hacen trabajo, la máquina de estados decide el orden. Cuando el equipo interiorizó esa frontera, depurar un proceso largo dejó de ser arqueología de logs y pasó a ser mirar un diagrama que te dice exactamente dónde estás. Ese cambio, y no la sintaxis JSON, es lo que hace que valga la pena.

El síntoma que delata que necesitas un worker

No todo cómputo va a un worker. La señal concreta que busco es un long task: una función síncrona que ocupa el hilo principal más de unos 50 ms y durante la cual la página deja de responder. Si abres el panel de rendimiento y ves bloques largos amarillos justo cuando la UI se traba, ahí tienes al culpable.

Casos típicos que me han llevado a un worker: parsear y transformar archivos grandes que el usuario sube, ordenar o filtrar en cliente un dataset de decenas de miles de filas, cálculos de geometría o imagen, y correr modelos ligeros en el navegador. Lo que tienen en común es que son CPU pura y prolongada, no esperas de red. Para lo que es esperar a un servidor no necesitas un worker: async/await ya libera el hilo. El worker es para trabajo que quema CPU, no para trabajo que espera.

El coste que la gente olvida: la frontera de mensajes

Un worker no comparte memoria con el hilo principal. Se comunican pasando mensajes, y esos datos se copian al cruzar la frontera (structured clone). Ese detalle es el que decide si el worker compensa o no: si mandas un objeto enorme al worker, esperas un cálculo trivial y recibes otro objeto enorme de vuelta, el coste de serializar y copiar se come la ganancia.

La regla que sigo es meter mucho trabajo por cada cruce de frontera. Un worker rinde cuando le mandas datos una vez y hace un cálculo grande, no cuando lo llamas en un bucle apretado para operaciones pequeñas. Cuando los datos son de verdad grandes, uso objetos transferibles: un ArrayBuffer se transfiere en vez de copiarse, cambiando de dueño sin duplicar memoria.

// Hilo principal: transfiere el buffer, no lo copia
const worker = new Worker(new URL('./procesar.ts', import.meta.url), { type: 'module' });
worker.postMessage({ buffer }, [buffer]); // el segundo arg transfiere la propiedad
worker.onmessage = (e) => pintarResultado(e.data);

El patrón que uso para no sufrir con postMessage

La API cruda de postMessage y onmessage se vuelve un espagueti de eventos en cuanto tienes más de dos tipos de mensaje. Lo que hago es envolver el worker en una promesa, para que desde el resto del código llamar al worker se sienta como un await normal y no como cablear un bus de eventos.

function ejecutarEnWorker<T>(worker: Worker, payload: unknown): Promise<T> {
  return new Promise((resolve, reject) => {
    worker.onmessage = (e) => resolve(e.data as T);
    worker.onerror = (e) => reject(e);
    worker.postMessage(payload);
  });
}

Para casos serios uso Comlink, que hace exactamente esto pero bien: te deja llamar funciones del worker como si fueran locales, con await, y esconde toda la mensajería. La primera vez que envuelves un worker así, la barrera mental de "esto es complicado" desaparece: el worker pasa a ser una función asíncrona más.

💡 Un worker no hace tu código más rápido; hace tu UI más fluida. El cálculo tarda lo mismo o un poco más por la copia de datos. Lo que ganas es que el usuario puede seguir haciendo scroll y clicando mientras tanto. Es una mejora de percepción, no de throughput.

Dónde NO meto un worker

Ser honesto con el trade-off importa. No uso worker cuando el cómputo es corto: si tarda 5 ms, moverlo a otro hilo solo añade latencia de mensajería y una capa de complejidad para nada. Tampoco cuando el trabajo es esperar red, porque eso ya no bloquea. Y evito el worker si el algoritmo necesita tocar el DOM: los workers no tienen acceso al DOM por diseño, y si tu "cálculo" en realidad manipula la interfaz, no es candidato.

El otro coste es de tooling y mantenimiento: un worker es otro archivo, otro punto de entrada para el bundler, otra pieza que alguien tiene que entender al leer el código. Con Vite o el bundler moderno de turno la fricción bajó mucho, pero no es cero. Por eso mi umbral es claro: worker solo cuando hay un long task medible que traba la UI de forma perceptible. Si no puedo señalar ese bloque amarillo en el profiler, no hay worker. Optimizar un bloqueo que nadie nota es añadir complejidad para presumir de arquitectura, y eso no es ingeniería, es decoración.

La mecánica: pgvector es suficiente

No necesitas infraestructura nueva. Si ya usas PostgreSQL con pgvector para búsqueda semántica — que es mi caso habitual con Prisma —, el caché es una tabla más:

CREATE TABLE llm_cache (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  query_text TEXT NOT NULL,
  query_embedding vector(1536) NOT NULL,
  response TEXT NOT NULL,
  model TEXT NOT NULL,
  hit_count INT DEFAULT 0,
  created_at TIMESTAMPTZ DEFAULT now(),
  expires_at TIMESTAMPTZ NOT NULL
);

CREATE INDEX ON llm_cache
  USING hnsw (query_embedding vector_cosine_ops);

El flujo de lectura es un query de vecino más cercano con umbral:

const [hit] = await prisma.$queryRaw<CacheHit[]>`
  SELECT response, 1 - (query_embedding <=> ${embedding}::vector) AS similarity
  FROM llm_cache
  WHERE expires_at > now()
  ORDER BY query_embedding <=> ${embedding}::vector
  LIMIT 1
`;

if (hit && hit.similarity >= 0.92) {
  return hit.response; // cache hit: cero tokens gastados
}

Si no hay hit, llamas al modelo, guardas la respuesta con su embedding, y el siguiente usuario que pregunte lo mismo con otras palabras ya no paga.

El umbral es la decisión de producto, no un detalle técnico

Todo el patrón vive o muere en ese 0.92. Demasiado bajo, y sirves respuestas equivocadas a preguntas que solo se parecen superficialmente — "¿cómo cancelo mi suscripción?" y "¿cómo cancelo un pago?" tienen embeddings incómodamente cercanos. Demasiado alto, y tu hit rate se desploma y el caché no paga su propia complejidad.

Mi enfoque: empezar en 0.95, loguear cada hit con la pregunta original y la cacheada, y revisar una muestra a mano cada semana. Bajar el umbral solo cuando los falsos positivos de la franja siguiente sean aceptables. En dominios con vocabulario cerrado (soporte de un producto concreto) he llegado a 0.90; en dominios abiertos no bajaría de 0.93.

💡 El umbral de similitud no es un hiperparámetro que se ajusta una vez: es una política de producto que define cuánta imprecisión toleras a cambio de costo. Trátalo como tal — con logging, revisión periódica y un owner.

Invalidación: el precio oculto

El caché semántico hereda el problema clásico de los cachés y le añade uno propio. El clásico: las respuestas caducan. Si tu producto cambia el flujo de facturación, todas las respuestas cacheadas sobre facturación son ahora mentiras bien escritas. Por eso cada entrada lleva expires_at y, más importante, un mecanismo de invalidación por categoría: etiqueto las entradas con el área funcional que tocan y cuando despliego un cambio en esa área, borro la categoría entera. Es brusco, pero es predecible.

El problema propio: las respuestas personalizadas. Si la respuesta del modelo incluye datos del usuario ("tu plan actual es Pro"), cachearla y servírsela a otro usuario es una fuga de datos, no una optimización. Mi regla es binaria: solo entra al caché lo que pasa por un clasificador previo de "pregunta genérica". Todo lo que dependa del contexto del usuario se queda fuera, sin excepciones ni casos especiales.

Cuándo no hacerlo

Los trade-offs mandan. Un caché semántico compensa cuando el tráfico tiene alta redundancia semántica (soporte, FAQs, onboarding), el costo por llamada es relevante y la latencia importa — un hit responde en ~50ms contra los 2-4 segundos de un modelo grande. No compensa cuando cada pregunta es única (herramientas creativas, análisis de documentos del usuario), cuando las respuestas dependen de contexto personal, o cuando el volumen es tan bajo que la factura del LLM es ruido.

En mi caso, la señal para construirlo fue mirar los logs: cuando ves la misma intención expresada de veinte formas distintas un día tras otro, el caché se justifica solo. Si no has mirado tus logs todavía, empieza por ahí — es posible que no necesites nada de esto, y esa también es una buena noticia.

La mentira del media query

El problema es de nivel de abstracción. Un componente bien hecho no sabe nada del mundo exterior: recibe props, se pinta, y se supone que se adapta a donde lo coloques. Pero un media query rompe ese encapsulamiento por completo, porque consulta un estado global —el ancho del viewport— que el componente no controla ni debería conocer.

El resultado es que el mismo componente necesita saber en qué layout va a vivir. La tarjeta que se ve perfecta en la grid principal de tres columnas se rompe en el sidebar, no porque esté mal hecha, sino porque su breakpoint asume un ancho de ventana que no se corresponde con el ancho que realmente tiene. Acabas metiendo props como variant="compact" para decirle a mano lo que debería poder deducir solo. Cada uno de esos props es una fuga de la abstracción.

Cómo funciona: el contenedor declara, el hijo consulta

El mecanismo tiene dos partes. Primero declaras que un elemento es un contenedor de consulta. Después, dentro, consultas su tamaño en vez del de la pantalla.

.card-wrapper {
  container-type: inline-size;
  container-name: card;
}

.card {
  display: grid;
  grid-template-columns: 1fr;
}

@container card (min-width: 400px) {
  .card {
    grid-template-columns: 120px 1fr;
  }
}

Lo que cambia respecto al media query es sutil y enorme a la vez: @container card (min-width: 400px) no pregunta "¿es la pantalla ancha?" sino "¿tiene mi contenedor al menos 400px?". La misma tarjeta, sin una sola prop extra, se pinta en una columna dentro de un sidebar de 300px y en dos columnas dentro de una grid amplia. El componente por fin se adapta a su realidad, no a una suposición sobre la ventana.

El caso que me convenció: una card en tres sitios distintos

En el design system tenía una ProductCard que aparecía en tres contextos: la grid de catálogo (ancha), un carrusel de recomendados (medio) y un sidebar de "vistos recientemente" (estrecho). Con media queries tenía tres variantes y un if en el consumidor decidiendo cuál usar según dónde iba. Tres caminos de código para una sola tarjeta.

Con container queries borré las variantes. La ProductCard pasó a ser una sola implementación que consulta su contenedor y se reorganiza sola. El componente dejó de necesitar contexto sobre su ubicación, que es exactamente lo que un componente debería no necesitar. Menos props, menos ramas, menos superficie donde algo se puede desincronizar.

💡 Si tu componente necesita una prop variant solo para caber en distintos anchos, no tienes un problema de diseño de API: tienes un media query donde debería haber una container query. Arréglalo abajo y la prop desaparece sola.

Trade-offs que acepté

No todo es gratis. Declarar container-type: inline-size crea un contexto de contención de tamaño, y eso tiene una consecuencia que hay que entender: el contenedor deja de dimensionarse según su contenido en el eje consultado. En la práctica esto rara vez muerde si envuelves con un wrapper dedicado en lugar de convertir en contenedor un elemento que ya hacía otras cosas, pero es un pie de página real, no un detalle que puedas ignorar.

También acepté un poco más de anidamiento en el marcado. El patrón limpio es un wrapper que es el contenedor y un hijo que es lo que se estiliza; consultar el tamaño de un elemento y a la vez estilizar ese mismo elemento con la consulta no funciona bien. Un div más por componente es un precio que pago con gusto a cambio de borrar toda una categoría de props de contexto.

Por qué esto es más que una comodidad

Lo que de verdad cambió no fue el CSS, fue dónde vive la responsabilidad. Con media queries, la responsabilidad de que un componente se vea bien está repartida entre el componente y quien lo coloca: el consumidor tiene que elegir la variante correcta para el hueco. Con container queries, la responsabilidad vuelve entera al componente, que es donde pertenece.

Esa es la diferencia entre un design system que escala y uno que se convierte en un catálogo de casos especiales. Cada vez que un componente necesita saber dónde va para verse bien, has creado un acoplamiento entre la pieza y su contexto. Las container queries cortan ese acoplamiento, y con él, la clase de deuda que no aparece en ningún ticket pero te ralentiza en cada pantalla nueva.

El problema que resuelve: el productor no debería conocer a sus consumidores

Imagina un evento de dominio simple: PedidoConfirmado. Cuando se confirma un pedido, hay que facturar, notificar al cliente, reservar inventario y actualizar analítica. La versión ingenua es que el servicio de pedidos llame a los cuatro. El día que marketing quiere enterarse también, alguien tiene que abrir el código de pedidos, añadir la quinta llamada, testearla y desplegarla. El productor acumula responsabilidades que no son suyas.

Con un bus de eventos, el servicio de pedidos emite un único evento y termina. Cada consumidor decide si le interesa. Añadir marketing es crear una regla nueva que apunta a su target, sin tocar pedidos. El acoplamiento pasa de "código a código" a "esquema de evento a esquema de evento", que es mucho más barato de mantener.

El patrón de reglas: filtrar en el bus, no en el consumidor

Lo que más me gustó de EventBridge frente a un SNS clásico es que el filtrado vive en la regla, declarativo, sobre el contenido del evento. No entrego el evento a una Lambda para que ella decida si le importa: el bus solo entrega lo que hace match.

{
  "source": ["pedidos.service"],
  "detail-type": ["PedidoConfirmado"],
  "detail": {
    "total": [{ "numeric": [">", 500] }],
    "pais": ["ES", "MX", "CO"]
  }
}

Esa regla solo dispara para pedidos confirmados de más de 500 en tres países. El consumidor no ejecuta ni una vez para el resto. Antes ese if vivía dentro de la función, invocada millones de veces para descartar la mayoría; ahora el descarte es gratis y no aparece en mi factura de Lambda ni en mis logs.

Dónde EventBridge NO es la respuesta

Ser honesto con los trade-offs es lo que separa una decisión de arquitectura de un acto de fe. EventBridge no es gratis en complejidad.

Si necesitas la respuesta del consumidor, no uses un bus. Es fire-and-forget: emites y no sabes qué pasó después salvo que montes otro evento de vuelta. Para un flujo request/response —el usuario espera un resultado en pantalla— una llamada síncrona directa sigue siendo lo correcto. Meter un event bus ahí solo añade latencia y una máquina de estados que nadie pidió.

Tampoco lo uso cuando el orden estricto es un requisito duro. EventBridge no garantiza orden, y puede entregar el mismo evento más de una vez. Si tu caso necesita procesar cosas en secuencia exacta, una cola FIFO de SQS encaja mejor. De hecho, un patrón que me funciona es EventBridge para el fan-out y SQS como buffer delante de cada consumidor lento, combinando lo mejor de ambos.

💡 La pregunta que decide todo: ¿el productor necesita saber qué le pasó al consumidor? Si la respuesta es sí, no tienes un evento, tienes una llamada. No lo disfraces de event-driven.

La entrega "al menos una vez" te obliga a ser idempotente

Este es el detalle que la gente descubre en producción y no en el diseño. EventBridge garantiza entrega at-least-once, lo que significa que tu consumidor puede recibir PedidoConfirmado dos veces por el mismo pedido. Si facturas en cada recepción, acabas de cobrar dos veces.

La solución no es rezar para que no pase: es diseñar el consumidor para que procesar el mismo evento dos veces dé el mismo resultado que procesarlo una. Una clave de idempotencia por evento, una tabla que registra "ya procesé este ID", y un INSERT ... ON CONFLICT DO NOTHING en Postgres antes de hacer el trabajo con efectos.

async function handle(event: PedidoConfirmado) {
  const inserted = await db.processedEvents.createIfAbsent(event.id);
  if (!inserted) return; // ya lo procesamos, salimos limpio
  await facturar(event);
}

No es código elegante, es código que sobrevive a la realidad. Cualquier arquitectura event-driven que no trate la idempotencia como requisito de primera clase está construyendo sobre arena.

Observabilidad: el precio real que pagué

Lo más caro de adoptar EventBridge no fue el servicio, fue la observabilidad. En una llamada síncrona sigues el stack trace y ves todo el camino. En un bus, el productor emitió y se fue; el consumidor falló tres saltos después; y correlacionar ambos requiere que hayas propagado un correlationId en el detail de cada evento desde el día uno.

Lo aprendí tarde y lo pagué en incidentes que costaron horas de más solo por no poder unir la causa con el efecto. Ahora todo evento lleva su ID de correlación, todos los consumidores lo loguean, y una DLQ por regla captura lo que falla para que ningún evento se pierda en silencio. Con eso, el desacoplamiento sale a cuenta. Sin eso, cambias un problema de acoplamiento por uno de depuración a ciegas, y no está claro que ganes.

Donde brillan: la mutación de formulario de toda la vida

El caso feliz es un formulario que muta datos y revalida la vista. Con action, validación con Zod compartido y estado pendiente del propio React:

// app/proyectos/actions.ts
'use server';

import { revalidatePath } from 'next/cache';
import { proyectoSchema } from '@/schemas/proyecto';

export async function crearProyecto(formData: FormData) {
  const session = await getSession();
  if (!session) throw new Error('No autorizado');

  const parsed = proyectoSchema.safeParse(Object.fromEntries(formData));
  if (!parsed.success) {
    return { error: parsed.error.flatten().fieldErrors };
  }

  await prisma.proyecto.create({
    data: { ...parsed.data, ownerId: session.userId },
  });

  revalidatePath('/proyectos');
  return { ok: true };
}

Cero endpoints, cero cliente HTTP, el tipo de retorno viaja inferido hasta el componente. Para el 80% de las mutaciones de un panel interno, esto es todo lo que necesitas, y volver a escribir route handlers para esos casos es nostalgia, no ingeniería.

La línea roja: lógica de negocio que vive en la action

El problema empieza cuando la action deja de ser un adaptador y se convierte en el hogar de la lógica. Una action que calcula precios, orquesta tres servicios y decide reglas de negocio es código que solo puede invocarse desde un componente React de ese proyecto Next.js. El día que llega la app móvil, el cron job o el equipo que quiere un endpoint público, esa lógica hay que exhumarla.

Mi regla estructural: la action llama a un servicio, y el servicio no sabe que Next.js existe.

// services/proyectos.ts — framework-agnostic, testeable en aislamiento
export async function crearProyectoParaUsuario(
  input: ProyectoInput,
  userId: string
) {
  // toda la lógica de negocio vive aquí
}

La action queda en tres líneas: autenticar, parsear, delegar. Si mañana necesito exponer lo mismo por route handler o por un worker de SQS, el servicio ya está listo. Elegí esta separación aun sabiendo que duplica un poco de ceremonia; a cambio, ninguna decisión de negocio queda rehén del framework.

💡 Una Server Action es un mecanismo de transporte con azúcar sintáctico, no una capa de arquitectura. Si borras Next.js de tu proyecto y con él se va lógica de negocio, tenías la lógica en el sitio equivocado.

Los límites operativos que nadie te cuenta hasta producción

Son POST secuenciales. Las Server Actions se ejecutan en serie por defecto desde el mismo cliente: si el usuario dispara tres, se encolan. Para un formulario da igual; para interacciones de alta frecuencia (autoguardado, drag and drop de un tablero) es un cuello de botella que descubres tarde.

No son cancelables ni cacheables. Un GET a un route handler puede cachearse en CDN y abortarse con AbortController. Una action, no. Todo lo que sea lectura — búsqueda, autocompletar, filtros — no tiene nada que hacer en una action: eso es un route handler o directamente un Server Component que lee de la base de datos.

El error handling es opaco. Un throw en una action llega al cliente como un error genérico en producción (por diseño, para no filtrar internals). Eso obliga a modelar los errores esperables como valores de retorno — el { error } del ejemplo — y reservar el throw para lo verdaderamente excepcional. Es más Result que Exception, y conviene decidirlo desde el día uno para no mezclar estilos.

El criterio en una frase

Mutación iniciada por un usuario desde la UI de ese mismo proyecto: Server Action que delega en un servicio. Lecturas, APIs consumidas por terceros, webhooks, alta frecuencia, cualquier cosa que un día pueda necesitar otro cliente: route handler o backend propio. Con esa línea trazada, las Server Actions son una herramienta excelente — pequeña, aburrida y en su sitio, que es exactamente como me gustan las herramientas.

Logs como datos, no como prosa

El cambio fundamental es dejar de escribir logs para humanos y empezar a escribirlos para máquinas. Un log de prosa ("Error procesando pedido 123 del usuario 456") es agradable de leer pero imposible de consultar en masa. Un log estructurado es un objeto JSON con campos consistentes:

logger.error('order_processing_failed', {
  orderId: order.id,
  userId: user.id,
  errorCode: err.code,
  correlationId: ctx.correlationId,
  durationMs: Date.now() - start,
});

CloudWatch Logs Insights entiende JSON de forma nativa. Con logs estructurados, "¿cuántos pedidos fallaron esta semana con este código de error, y de qué usuarios?" deja de ser un grep heroico y pasa a ser una consulta:

fields @timestamp, orderId, userId
| filter level = 'error' and errorCode = 'PAYMENT_TIMEOUT'
| stats count(*) by userId
| sort count(*) desc

No uso un logger casero: AWS Lambda Powertools para TypeScript ya resuelve la serialización, los niveles, y añade automáticamente el contexto de la invocación (request ID, nombre de función, cold start). Reinventar eso es tiempo perdido.

El ID de correlación: el hilo que une el sistema

En una arquitectura orientada a eventos, el problema no es loguear: es correlacionar. La request del usuario dispara una Lambda que encola un mensaje en SQS que procesa otra Lambda que escribe en DynamoDB. Cuatro grupos de logs distintos, cuatro request IDs distintos, ninguna relación visible entre ellos.

Mi regla: el primer punto de entrada genera un correlationId (o adopta el que venga en el header X-Correlation-Id), y ese ID viaja con todo. En los mensajes SQS va dentro de los message attributes; en las llamadas entre servicios, en un header; en cada log, como campo obligatorio. Powertools permite inyectarlo una vez en el logger y olvidarte: todo log de esa invocación lo lleva.

Con eso, reconstruir la historia completa de una request es una sola consulta en Logs Insights cruzando todos los log groups implicados. Lo que antes era una tarde de arqueología ahora son treinta segundos.

💡 La observabilidad no se añade cuando hay un incidente: se diseña antes. El día que algo se rompe en producción, tus logs ya son los que son. Cada campo que no logueaste es una pregunta que no puedes responder.

Métricas sin martillo: EMF

Para métricas de negocio (pedidos procesados, matchings generados, colas que crecen) no uso llamadas a la API de CloudWatch, que añaden latencia y cuestan dinero por request. Uso Embedded Metric Format: escribes la métrica como parte del log JSON con un formato especial, y CloudWatch la extrae de forma asíncrona. Coste marginal cero en el camino caliente, y las métricas aparecen en dashboards y alarmas como cualquier otra.

metrics.addMetric('MatchingCompleted', MetricUnit.Count, 1);
metrics.addMetric('MatchingDurationMs', MetricUnit.Milliseconds, elapsed);

La disciplina que me impongo: cada Lambda emite al menos una métrica de éxito y una de fallo con nombre de negocio, no técnico. "Errors" no me dice nada a las 3 de la mañana; "PaymentTimeouts" sí.

Lo que decidí no hacer

No monté X-Ray en todo. Lo probé, y para mi escala el tracing distribuido completo era más ruido que señal: la mayoría de mis flujos tienen dos o tres saltos, y el correlation ID en logs estructurados los cubre de sobra. X-Ray lo reservo para los flujos con más saltos o cuando sospecho de latencias entre servicios que los logs no explican. Es un trade-off honesto: menos visibilidad automática a cambio de menos coste y menos configuración que mantener.

Tampoco centralizo logs en una herramienta externa. CloudWatch Logs Insights tiene una UX regular y consultas que se pagan por GB escaneado, pero añadir un tercero significa otro pipeline de envío, otro contrato, y otra factura. Mientras el volumen lo permita, prefiero el dolor conocido. El día que las consultas se vuelvan lentas o caras de verdad, esa decisión se revisa con datos: GB escaneados al mes y minutos perdidos por incidente.

El resultado

Nada de esto es glamuroso. Son tres hábitos: JSON en vez de prosa, un ID que viaja con la request, y métricas de negocio embebidas en los logs. Pero la diferencia operativa es enorme: los incidentes pasaron de "a ver si consigo reproducirlo" a "dame el correlation ID y te digo qué pasó". En serverless no puedes hacer SSH al servidor, así que más te vale que el sistema cuente su propia historia.

Por qué el bi-encoder se queda corto

Un embedding comprime todo un documento en un vector fijo antes de saber qué le vas a preguntar. Esa es su gran ventaja (puedes precalcularlo e indexarlo) y su límite estructural: la compresión pierde los matices que solo importan frente a una query concreta. Dos perfiles de candidato pueden estar igual de "cerca" de una vacante en el espacio vectorial por razones distintas, y el coseno no distingue si la cercanía viene de lo esencial o de lo accesorio.

Un reranker es un cross-encoder: recibe la query y el documento juntos, y produce un score de relevancia mirando la interacción entre ambos. Es mucho más preciso ordenando, y mucho más caro: no puedes precalcular nada, cada par query-documento es una inferencia. Por eso nadie rankea un corpus entero con un cross-encoder. El patrón es recuperar barato y reordenar caro sobre pocos candidatos.

La arquitectura: recuperar 50, reordenar a 10

Mi pipeline quedó en dos etapas. La primera es la que ya tenía: pgvector recupera los 50 vecinos más cercanos. La segunda pasa esos 50 por el reranker y se queda con los 10 mejores según el nuevo score.

-- Etapa 1: recuperación barata, sobre-recuperando a propósito
SELECT id, titulo, contenido
FROM documentos
ORDER BY embedding <=> $1
LIMIT 50;

// Etapa 2: reranking sobre los candidatos
const scored = await rerank({
  query: userQuery,
  documents: candidates.map((c) => c.contenido),
});

const top = scored
  .sort((a, b) => b.relevanceScore - a.relevanceScore)
  .slice(0, 10);

El número 50 no es sagrado. Es el equilibrio que encontré entre dos fallos: si recuperas pocos, el documento correcto ni siquiera llega al reranker y no hay nada que reordenar; si recuperas demasiados, pagas latencia e inferencia por candidatos que no tenían ninguna opción. Elegí 50 porque en mis pruebas el resultado correcto estaba dentro del top 50 del bi-encoder prácticamente siempre; a cambio, acepto que si la recuperación falla de raíz, el reranker no la rescata. Garbage in, garbage out, pero mejor ordenado.

Latencia: el precio real y cómo lo contuve

El reranking añade una llamada de red y una inferencia por request. En mi caso eso significó pasar de ~80ms a ~350ms en p50. Para una búsqueda interactiva era demasiado, y lo contuve con tres decisiones:

La primera, rerankear solo cuando importa. Si el score del primer candidato del bi-encoder saca mucha ventaja al segundo, el orden ya está claro y me salto la segunda etapa. La segunda, truncar documentos: el reranker no necesita las 3.000 palabras del documento, con el título y el primer fragmento relevante le basta para discriminar, y el coste crece con los tokens. La tercera, cachear pares query-documento normalizados; en un producto real las queries se repiten mucho más de lo que uno cree.

💡 El reranker no mejora tu recuperación: mejora tu precisión en el top. Si tu problema es que los buenos resultados no aparecen ni en el top 50, tu problema está en los embeddings o en el chunking, y ningún reranker te va a salvar.

Cómo medí que valía la pena

Antes de integrar nada monté un set de evaluación pequeño: ~100 queries reales con el resultado que un humano consideraba correcto marcado a mano. La métrica que me importaba era MRR (mean reciprocal rank): si el resultado correcto está primero vale 1, si está segundo 0.5, y así. Con solo bi-encoder tenía un MRR mediocre; con reranker subió de forma clara y consistente. No doy las cifras exactas porque dependen brutalmente del dominio y del dataset, pero el patrón se repite en casi cualquier corpus: el bi-encoder encuentra, el cross-encoder ordena.

Lo que sí es generalizable es el método: no integres un reranker porque está de moda. Monta primero las 100 queries con juicio humano, mide tu baseline, y que la decisión la tome el número. En mi caso el número fue contundente y la latencia extra estaba pagada.

Trade-offs que acepté

Elegí un reranker gestionado vía API en lugar de servir un cross-encoder propio, porque a mi escala el coste por request era menor que el coste fijo de mantener una GPU caliente. A cambio, acepté una dependencia externa en el camino crítico de la búsqueda, mitigada con un fallback: si el reranker no responde en 500ms, devuelvo el orden del bi-encoder tal cual. Búsqueda algo peor es infinitamente mejor que búsqueda caída.

También acepté que el sistema es más difícil de razonar: ahora hay dos modelos que pueden degradarse por separado. Por eso las evals corren contra el pipeline completo, no contra cada pieza aislada. Lo que le llega al usuario es el resultado de la cadena entera, y eso es lo único que tiene sentido medir.

El flujo en tres pasos

El patrón tiene tres actores: el navegador, tu API y S3. La API nunca ve el archivo.

// 1. El backend genera la URL firmada (Lambda o endpoint normal)
import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
import { getSignedUrl } from '@aws-sdk/s3-request-presigner';

const s3 = new S3Client({});

export async function crearUrlDeSubida(userId: string, contentType: string) {
  if (!TIPOS_PERMITIDOS.has(contentType)) {
    throw new Error('Tipo de archivo no permitido');
  }

  const key = `uploads/${userId}/${crypto.randomUUID()}`;

  const url = await getSignedUrl(
    s3,
    new PutObjectCommand({
      Bucket: process.env.UPLOADS_BUCKET,
      Key: key,
      ContentType: contentType,
      ContentLength: undefined, // se limita con condiciones en POST policy si hace falta
    }),
    { expiresIn: 300 } // 5 minutos, ni uno más
  );

  return { url, key };
}

El navegador hace un PUT directo a esa URL con el archivo como body. Cuando termina, notifica a tu API con la key, y ahí registras el archivo en PostgreSQL vía Prisma, disparas el procesamiento asíncrono, o lo que toque.

Las tres decisiones de seguridad que importan

La key la genera el servidor, siempre. Si dejas que el cliente elija el nombre del archivo, estás dejando que elija dónde escribe en tu bucket. La key incluye el userId autenticado y un UUID: el cliente no aporta ni un carácter.

Expiración corta y content-type fijado. Cinco minutos es suficiente para iniciar cualquier subida. Y firmar el ContentType en la URL obliga a que lo que se sube sea lo que se declaró — no evita que alguien renombre un ejecutable a .jpg, pero cierra la vía fácil.

El bucket de subidas no es el bucket final. Todo cae en un bucket de staging con una regla de ciclo de vida que borra objetos a las 24 horas. Un proceso posterior — en mi caso una Lambda disparada por el evento s3:ObjectCreated — valida el archivo de verdad (magic bytes, tamaño, escaneo si aplica) y lo mueve al bucket definitivo. Lo que nadie valida, se autodestruye solo.

💡 Una presigned URL no es "acceso a S3": es UNA operación, sobre UNA key, durante UN intervalo. Si tu URL firmada permite más que eso, no has entendido el patrón — has abierto un agujero con extra de pasos.

El evento de confirmación: no te fíes del cliente

El error clásico de este patrón es marcar el archivo como "subido" cuando el navegador dice que terminó. El navegador miente: se cierra la pestaña, falla la red, el usuario cancela. La fuente de verdad es S3, no el cliente.

Por eso el registro en base de datos tiene dos fases: la API crea la fila en estado pendiente al firmar la URL, y la Lambda del evento ObjectCreated la pasa a disponible cuando el objeto existe de verdad. Las filas que se quedan en pendiente más de una hora las limpia un job. El cliente puede notificar para acelerar la UX, pero su notificación es una optimización, nunca la verdad.

Cuándo no usar este patrón

Como siempre, hay trade-offs. Si los archivos son pequeños (JSON, avatares de pocos KB) y el volumen es bajo, pasar por el backend es más simple y la simplicidad gana. Si necesitas transformar el archivo en línea antes de guardarlo (redimensionar, transcodificar de forma síncrona), el backend tiene que verlo de todos modos. Y si tu frontend es una PWA offline-first, la subida directa complica la cola de sincronización: ahí a veces prefiero encolar el archivo localmente y subirlo desde un service worker cuando hay red, lo que cambia el diseño entero.

Para todo lo demás — documentos, imágenes, cualquier cosa que pese megabytes y llegue con concurrencia — dejar que S3 haga el trabajo pesado es de las pocas decisiones de arquitectura que no he lamentado nunca.

La frontera que lo cambia todo

Cuando le das herramientas a un modelo, el ciclo real es: le pasas la petición del usuario y el esquema de las herramientas disponibles; el modelo responde o bien con texto, o bien con una o más tool calls (nombre + argumentos en JSON); tu código ejecuta las que decida ejecutar; le devuelves el resultado al modelo; y el modelo continúa. El LLM nunca toca tu base de datos ni tu API. Es un generador de intenciones estructuradas.

Esa frontera es la mejor noticia de la arquitectura, porque significa que todo el control de seguridad vive en tu lado. El modelo puede pedir borrar un registro; que se borre o no depende de un if tuyo. Tratar la tool call como una solicitud sujeta a autorización, y no como una orden, es lo que separa un agente que puedes poner en producción de una demo que da miedo.

Los esquemas son tu contrato, y el modelo los lee

La calidad de un agente con herramientas depende brutalmente de lo bien descritas que estén las herramientas. El modelo elige qué llamar basándose en el nombre, la descripción y el esquema de parámetros. Descripciones vagas producen llamadas erróneas; descripciones precisas producen llamadas correctas.

const tools = [{
  name: 'buscar_candidatos',
  description: 'Busca candidatos por habilidades y seniority. ' +
    'Úsala solo cuando el usuario pida perfiles concretos, ' +
    'no para preguntas generales sobre el mercado.',
  input_schema: {
    type: 'object',
    properties: {
      skills: { type: 'array', items: { type: 'string' } },
      seniority: { type: 'string', enum: ['junior', 'mid', 'senior'] },
    },
    required: ['skills'],
  },
}];

Ese enum no es decoración: restringe el espacio de salida y hace mucho menos probable que el modelo invente un valor que tu backend no sabe manejar. Cada restricción que pones en el esquema es una clase de bug que eliminas antes de que ocurra. He aprendido a invertir en esquemas estrictos con la misma seriedad con la que diseño una API pública, porque para el modelo eso es exactamente lo que son.

Validar la salida como si viniera de un cliente hostil

Aquí está el punto que más gente se salta. El modelo genera los argumentos como texto, y aunque le des un esquema, no hay garantía dura de que respete tus invariantes de negocio. Puede pasarte un seniority válido según el enum pero un array de skills vacío, o una fecha con formato correcto pero en el pasado.

Por eso valido cada tool call con Zod antes de ejecutarla, con la misma desconfianza que aplicaría a un input de usuario. La tool call es un input de usuario, solo que generado por un modelo. Si no valida, no ejecuto: devuelvo el error al modelo como resultado de la herramienta y dejo que reintente con argumentos corregidos. Ese bucle de "fallaste la validación, aquí está por qué, prueba otra vez" es sorprendentemente eficaz y mantiene el sistema seguro sin intervención humana.

💡 Una tool call es una petición no confiable que resulta venir de un LLM en vez de un navegador. Valídala, autorízala y regístrala exactamente igual que cualquier entrada externa. El modelo no es parte de tu perímetro de confianza.

Efectos secundarios: separa leer de escribir

No todas las herramientas son iguales, y tratarlas como si lo fueran es pedir problemas. Distingo dos categorías con reglas distintas. Las de solo lectura —buscar, consultar, calcular— las ejecuto sin fricción: si el modelo se equivoca de query, el coste es una respuesta pobre, nada irreversible. Las de escritura —crear, actualizar, borrar, enviar— pasan por un filtro mucho más estricto.

Para las de escritura con impacto real, el patrón que me funciona es no darle al modelo la herramienta destructiva directamente, sino una que propone la acción y la deja pendiente de una confirmación explícita. El modelo puede redactar el email; enviarlo requiere un paso que mi código controla, muchas veces con un humano en el lazo. Elegí esta cautela a cambio de agentes menos "mágicos", y volvería a elegirla: un agente que puede mandar mensajes sin supervisión es un incidente esperando su turno.

Por qué este modelo mental escala y el otro no

Cuando piensas que el LLM ejecuta, cada nueva herramienta te da miedo, porque estás ampliando lo que un sistema no determinista puede hacer solo. Cuando entiendes que el LLM solo propone, añadir herramientas es barato: cada una es una intención más que tu código sabe validar, autorizar y ejecutar bajo tus reglas.

El agente deja de ser una caja negra a la que le rezas y pasa a ser un planificador cuyas propuestas atraviesan una capa de control que tú escribiste y entiendes. Toda la creatividad del modelo, ninguna de su capacidad de hacer daño sin permiso. Esa división de responsabilidades no es un detalle de implementación: es la diferencia entre un agente que puedes defender en una revisión de seguridad y uno que no.

El problema real: dos fuentes de verdad que divergen

La validación duplicada no falla el día que la escribes: falla seis meses después, cuando alguien cambia una regla en el backend (mínimo de caracteres, un formato nuevo de código postal) y nadie toca el frontend. A partir de ahí tienes dos comportamientos: lo que el formulario dice que es válido y lo que la API acepta de verdad. El usuario sufre la diferencia.

La solución no es disciplina ("acordaos de cambiar los dos sitios"), porque la disciplina no escala. La solución es estructural: que solo exista un sitio.

El esquema como contrato compartido

En un monorepo, el esquema vive en un paquete propio, sin dependencias de React ni de Node:

// packages/schemas/src/registro.ts
import { z } from 'zod';

export const registroSchema = z.object({
  email: z.string().email('Email inválido'),
  telefono: z
    .string()
    .transform((v) => v.replace(/\s+/g, ''))
    .pipe(z.string().regex(/^\+?\d{9,15}$/, 'Teléfono inválido')),
  password: z.string().min(12, 'Mínimo 12 caracteres'),
});

export type RegistroInput = z.input<typeof registroSchema>;
export type RegistroOutput = z.output<typeof registroSchema>;

Dos detalles importan aquí. El primero, el transform + pipe: la normalización (quitar espacios del teléfono) es parte del esquema, así el "teléfono con espacios" es válido en los dos mundos y se normaliza igual en los dos mundos. El segundo, exportar z.input y z.output como tipos separados: lo que entra (con espacios) y lo que sale (normalizado) son tipos distintos, y TypeScript te obliga a no confundirlos.

En el cliente: el mismo esquema alimenta el formulario

Con react-hook-form y su resolver de Zod, el formulario valida contra el esquema compartido sin escribir ni una regla más:

const form = useForm<RegistroInput>({
  resolver: zodResolver(registroSchema),
});

Los mensajes de error que definiste en el esquema aparecen bajo cada campo. Si mañana el mínimo de la contraseña sube a 14, cambias un número en un archivo y el formulario y la API se enteran a la vez.

En el servidor: parsear, no confiar

En la API, el mismo esquema es la frontera entre el mundo exterior y tu código tipado:

export async function POST(req: Request) {
  const parsed = registroSchema.safeParse(await req.json());
  if (!parsed.success) {
    return Response.json(
      { errors: parsed.error.flatten().fieldErrors },
      { status: 422 },
    );
  }
  // parsed.data es RegistroOutput: normalizado y tipado
  await crearUsuario(parsed.data);
}

Uso safeParse y devuelvo fieldErrors con la misma estructura que consume el formulario. Así, incluso si un cliente malicioso salta la validación del navegador, el error que devuelve el servidor encaja en la misma UI de errores por campo. La validación del cliente es UX; la del servidor es seguridad. Misma lógica, roles distintos.

💡 "Parse, don't validate": el esquema no solo comprueba que los datos son correctos, los transforma en un tipo que ya no puede ser incorrecto. Después de la frontera, ninguna función vuelve a preguntarse si el email es válido: el tipo lo garantiza.

Los límites del patrón

No todo es compartible, y fingir que lo es genera esquemas monstruosos. Las validaciones que dependen de estado del servidor (¿este email ya existe?, ¿este cupón sigue activo?) no pertenecen al esquema compartido: son reglas de negocio del backend y se comprueban ahí, devolviendo errores con el mismo formato de fieldErrors para que la UI las pinte igual.

También decidí no compartir esquemas de respuesta de la API con el mismo entusiasmo. Los esquemas de entrada cambian despacio y los controlas tú; tipar cada respuesta con Zod en runtime añade un coste de parseo que en la mayoría de endpoints no compra nada. Ahí me basta el contrato de tipos de TypeScript generado del propio esquema.

El trade-off global del patrón es el acoplamiento: frontend y backend comparten un paquete, lo que exige monorepo o publicar el paquete versionado. Elegí monorepo con pnpm workspaces porque el coste de coordinar versiones entre repos separados era exactamente el tipo de fricción que intentaba eliminar. A cambio, un cambio de esquema obliga a desplegar ambos lados coordinados. Lo acepto: prefiero un despliegue coordinado explícito a una divergencia silenciosa que descubre un usuario.

El modelo mental: HTML por defecto, JS bajo demanda

En una SPA clásica todo es JavaScript: el framework se monta entero en el cliente, hidrata todo el árbol y desde ahí gobierna la página. Es cómodo para el desarrollador y caro para el usuario, porque paga el coste de arrancar el framework aunque el 90% de la pantalla sea texto que nunca cambia.

Astro invierte la premisa. Renderiza tus componentes a HTML en el servidor o en el build, y por defecto descarta el JavaScript que los generó. Lo que llega al navegador es HTML plano que pinta al instante. Las "islas" son las zonas concretas que sí necesitan vida propia —un carrusel, un formulario con validación, un menú desplegable— rodeadas de un mar de HTML estático que no cuesta nada. Cada isla se hidrata de forma independiente; el resto de la página ni se entera.

Las directivas client: son la decisión, no un detalle

La palanca es la directiva que le pones al componente al usarlo. Cada una describe cuándo se hidrata esa isla, y elegir bien es donde está el rendimiento:

---
import Carousel from '../components/Carousel.jsx';
import NewsletterForm from '../components/NewsletterForm.jsx';
import HeavyChart from '../components/HeavyChart.jsx';
---

<!-- Se hidrata en cuanto carga la página: para lo que se ve arriba -->
<Carousel client:load />

<!-- Se hidrata cuando entra en el viewport: para lo que está más abajo -->
<HeavyChart client:visible />

<!-- Se hidrata cuando el navegador está ocioso: para lo no urgente -->
<NewsletterForm client:idle />

client:load hidrata de inmediato: úsalo solo para lo que es interactivo desde el primer pixel visible. client:idle espera a que el hilo principal respire. client:visible es mi favorita: no gasta un byte de JavaScript hasta que el componente entra en pantalla, ideal para todo lo que vive por debajo del fold. La directiva no es un adorno de sintaxis: es literalmente la política de carga de cada isla, y ponerlas a la ligera es cómo se cuela JavaScript que el usuario no necesita.

Cuándo NO hidratar (que es casi siempre)

El error más común de quien llega desde React es tratar cada componente como si necesitara estado. No lo necesita. Una tarjeta, un encabezado, una lista de posts, un pie de página: todo eso es HTML que se pinta una vez y no vuelve a cambiar. Si no hay evento, no hay estado y no hay interacción, no hay isla. Se queda como componente estático de Astro y envía cero JavaScript.

La pregunta que me hago ante cada componente no es "¿puede ser interactivo?", sino "¿tiene que responder a algo del usuario en el cliente?". Un botón que solo es un enlace no es una isla, es una etiqueta <a>. Un acordeón se puede hacer con <details> y <summary> nativos sin una línea de JS. Cuanto más empujo la interactividad hacia HTML y CSS nativos, menos islas necesito y más ligera queda la página.

💡 En Astro, cada client: que escribes es JavaScript que el usuario descarga. La mejor optimización no es hidratar más rápido, es no hidratar.

Las islas no comparten estado, y eso es a propósito

Aquí está el trade-off que hay que tener claro antes de casarse con el modelo. Cada isla es un componente aislado: se hidrata sola y no comparte estado con las demás por arte de magia. Si vengo de una SPA donde un store global lo conecta todo, esto se siente como una limitación. Dos islas que necesitan hablar entre sí no lo hacen a través de props, porque son árboles independientes montados por separado.

La solución existe —eventos del navegador, nanostores compartidos, señales— pero es fricción real, y esa fricción es la señal de que quizá estás usando la herramienta a contrapelo. Si tu página es básicamente una aplicación con estado muy entrelazado, muchas partes hablando entre sí constantemente, Astro te va a pedir gimnasia para algo que un framework de SPA te da gratis. Ahí no fuerzo Astro: elijo la herramienta adecuada.

Por qué elegí este modelo igualmente

Astro brilla cuando el contenido manda y la interactividad es puntual: blogs, sitios de marketing, documentación, portfolios, e-commerce con islas de producto. Es exactamente la forma de la mayoría de la web, y de este sitio. Acepto la fricción de coordinar islas a cambio de que, por defecto, cada página nazca sin peso, y que sea yo quien decide y justifica cada kilobyte de JavaScript que añado.

Ese cambio de default lo es todo. En una SPA el JavaScript es la norma y quitarlo cuesta trabajo; en Astro el JavaScript es la excepción y añadirlo es una decisión consciente. Prefiero un sistema donde lo barato es lo fácil y lo caro requiere que yo lo pida a propósito. Esa inversión de la carga por defecto es, para el tipo de webs que construyo, la mejor decisión de rendimiento que puedo tomar sin optimizar una sola línea.

Qué problema resuelven de verdad

En un sitio MPA tradicional cada navegación es una recarga completa del documento. Funciona, es robusto y es lo que Astro hace de serie, pero se siente tosco: entre página y página hay un instante en blanco, el navegador reinicia el scroll y cualquier cosa que estuviera sonando o reproduciéndose se corta. En una SPA eso no pasa porque nunca recargas: un router intercepta el clic y reemplaza el contenido con JavaScript. El precio es que te llevas todo el aparato de la SPA —el router, la hidratación, el estado en cliente— aunque tu sitio sea mayormente contenido.

Las View Transitions se colocan en medio. Astro intercepta la navegación, pide la siguiente página, intercambia el contenido del <body> sin recargar el documento y anima la transición usando la API de View Transitions del navegador. Sigues sirviendo páginas HTML normales, pero la navegación entre ellas deja de parpadear. Activarlo es una línea en el layout.

---
// src/layouts/Layout.astro
import { ClientRouter } from 'astro:transitions';
---
<html lang="es">
  <head>
    <ClientRouter />
  </head>
  <body>
    <slot />
  </body>
</html>

Con ese <ClientRouter /> en el <head>, cada enlace interno pasa a navegarse sin recarga y con una transición suave por defecto. No has escrito un router ni has convertido nada en SPA: sigue siendo Astro sirviendo HTML.

Animaciones con nombre: el detalle que lo vende

La transición por defecto es un fundido discreto, pero lo que engancha es poder animar elementos concretos de una página a otra. Si marco dos elementos en páginas distintas con el mismo transition:name, el navegador entiende que son "el mismo" y anima el cambio de posición y tamaño entre ambos. El caso típico es la miniatura de un artículo que crece hasta convertirse en la cabecera del detalle.

<!-- En el listado -->
<img src={post.cover} transition:name={`cover-${post.slug}`} />

<!-- En la página de detalle -->
<img src={post.cover} transition:name={`cover-${post.slug}`} />

El nombre tiene que ser único por elemento en cada página; por eso lo derivo del slug. Si repites un mismo transition:name para varios elementos visibles a la vez, el navegador no sabe cuál es cuál y la animación se rompe. Es el error más común al empezar.

El estado que quieres que sobreviva

Aquí está la ganancia menos obvia. Como no hay recarga completa, puedo pedir que ciertos elementos persistan entre navegaciones en lugar de recrearse. Un reproductor de audio, un mapa pesado, un menú con su estado abierto: con transition:persist el elemento se conserva tal cual al pasar de página, sin reiniciarse.

<audio src={cancion} controls transition:persist />

Sin esto, cada navegación destruiría el <audio> y volvería a crearlo, cortando la reproducción. Con transition:persist, el mismo nodo del DOM viaja a la página siguiente y sigue sonando. Es exactamente el tipo de continuidad por la que la gente monta una SPA entera, y aquí lo consigo con un atributo.

💡 Cada elemento persistido es un nodo que decides no recrear. Úsalo para lo que debe tener continuidad real —audio, vídeo, un mapa caro— y no como parche para no recalcular algo que sí debería refrescarse con la nueva página.

Los bordes que hay que conocer

Nada de esto es gratis, y es honesto decir dónde aprietan. El primero es el scripting. Como la página no recarga, el <script> que corría en DOMContentLoaded no se vuelve a ejecutar en cada navegación: se ejecutó una vez y la nueva página no lo dispara de nuevo. Cualquier inicialización que dieras por hecha en cada carga hay que reengancharla al evento astro:page-load, que Astro emite en la carga inicial y después de cada transición.

// Se ejecuta en la primera carga y tras cada navegación
document.addEventListener('astro:page-load', () => {
  inicializarWidgets();
});

Este es el fallo que más cuesta detectar, porque el sitio funciona perfecto al recargar a mano y solo se rompe al navegar entre páginas: los scripts simplemente no se reengancharon.

El segundo borde es la degradación. Las View Transitions se apoyan en una API que no todos los navegadores implementan igual; donde no está, Astro cae con elegancia a una navegación normal con recarga. Eso significa que no puedes tratar la transición como garantizada: es una mejora progresiva, no una base sobre la que construir lógica. Y el tercero, más de criterio que técnico, es no pasarse: animarlo todo marea. Reservo las animaciones con nombre para una o dos conexiones visuales que de verdad aporten continuidad, y dejo el resto en el fundido discreto.

Por qué me sale a cuenta

Elegí View Transitions en Astro en vez de saltar a una SPA porque me quedo con lo que quería del framework —HTML servido, JavaScript mínimo, páginas independientes que cachean y se indexan bien— y encima gano la fluidez que antes obligaba a cambiar de modelo entero. A cambio acepto un puñado de bordes concretos: reenganchar scripts en astro:page-load, tratar la transición como progresiva y ser disciplinado con las animaciones. Es un intercambio que casi siempre acepto, porque el coste es acotado y conocido, mientras que meterme en una SPA por conseguir una animación sería pagar en bundle, complejidad y SEO un precio muy superior al problema que resuelve.

Por qué encolo en vez de responder en línea

Cuando un reclutador publica una vacante, la respuesta HTTP no debería esperar a que se generen embeddings, se recalculen matches y se disparen notificaciones. Eso lo mando a una cola y devuelvo la respuesta de inmediato. El usuario percibe una app rápida; el trabajo pesado ocurre detrás, a su ritmo.

La cola me da tres cosas concretas. Absorbe picos: si entran cien vacantes de golpe, se procesan al ritmo que aguante el consumidor, no todas a la vez. Aísla fallos: si el proveedor de correo está caído, la tarea se reintenta sola sin tumbar la petición original. Y desacopla: el productor no sabe ni le importa quién consume.

El problema real: "al menos una vez"

SQS estándar garantiza entrega, pero no unicidad. El mismo mensaje puede llegar dos veces: porque el consumidor tardó más que el visibility timeout y SQS lo re-entregó, porque hubo un reintento de red, o porque el proceso murió justo después de trabajar pero antes de borrar el mensaje.

Si mi consumidor manda un correo por cada mensaje sin más, un candidato recibe dos. Si crea un cargo, cobro doble. La entrega duplicada no es un caso raro que ocurre una vez al año: es el comportamiento normal del sistema, y hay que diseñarlo asumiendo que pasará.

Idempotencia: la única defensa que escala

La solución no es evitar los duplicados, es hacer que procesarlos dos veces dé el mismo resultado que procesarlos una. Eso es idempotencia, y la implemento con una clave estable por unidad de trabajo.

CREATE TABLE processed_message (
  idempotency_key TEXT PRIMARY KEY,
  processed_at    TIMESTAMPTZ NOT NULL DEFAULT now()
);

El consumidor, antes de trabajar, intenta insertar la clave. Si ya existe, el mensaje es un duplicado y lo descarto sin efectos.

async function handle(msg: Job) {
  const inserted = await db.processedMessage
    .create({ data: { idempotencyKey: msg.id } })
    .catch(() => null); // choca con la PK si ya se procesó

  if (!inserted) return; // duplicado: no hago nada

  await doTheActualWork(msg);
}

La clave no la invento al azar: la derivo de la intención del mensaje. Para un correo de bienvenida es welcome-email:{candidateId}, no un UUID nuevo por cada intento. Así, dos mensajes que representan la misma acción colisionan y solo uno gana.

💡 Un reintento seguro no es el que nunca se repite; es el que puede repetirse sin que a nadie le importe.

Visibility timeout y la DLQ

Dos piezas de SQS hay que afinar. El visibility timeout debe ser mayor que el peor tiempo de proceso realista: si tardo más, SQS asume que fallé y re-entrega mientras yo sigo trabajando. Lo mido contra el p99 del consumidor, no contra el promedio.

Y la dead-letter queue: tras N intentos fallidos, el mensaje sale de la cola principal y cae en una DLQ. Sin ella, un mensaje envenenado —uno que siempre falla— se reintenta para siempre y tapa la cola. La DLQ es donde reviso qué se rompió sin que bloquee todo lo demás. Le pongo una alarma: si algo aterriza ahí, quiero enterarme.

Lo que haría diferente

Al principio metí la lógica de idempotencia dentro de cada handler. Terminé repitiéndola y equivocándome distinto en cada uno. Hoy vive en un wrapper único: recibe la clave, verifica, ejecuta, y ningún handler vuelve a pensar en duplicados. El patrón importa más que la infraestructura. SQS es reemplazable; la disciplina de asumir que todo mensaje puede llegar dos veces es lo que de verdad te salva.

Por qué DynamoDB no es Postgres con otra piel

En Postgres normalizo, creo tablas por entidad y dejo que el planificador resuelva los joins en tiempo de consulta. Es flexible: si mañana necesito una consulta nueva, la escribo y el motor se las arregla, quizá con un índice extra. Esa flexibilidad la pago en que el rendimiento depende del plan que elija el motor.

DynamoDB invierte el trato. No hay joins ni planificador: cada acceso es una búsqueda por clave, y si no diseñaste la clave para esa consulta, esa consulta o es imposible o te obliga a un Scan que recorre toda la tabla. A cambio, un acceso bien diseñado tiene latencia predecible sin importar cuántos datos haya. La consecuencia es brutal: en DynamoDB no puedes empezar por el modelo de datos, tienes que empezar por la lista de consultas que tu producto va a hacer.

Empieza por los access patterns, siempre

Antes de tocar una tabla, escribo la lista de accesos en lenguaje llano. Para un producto de pedidos sería algo así: dame un usuario por su id; dame todos los pedidos de un usuario; dame un pedido con sus líneas; dame los pedidos de un usuario ordenados por fecha. Esa lista no es documentación, es el diseño. Cada patrón tiene que corresponder a un Query de partition key, no a un Scan.

Este paso es el que la gente que viene de SQL se salta, y es exactamente el que no puedes saltarte. Si más adelante aparece un patrón que no previste, en Postgres es una consulta nueva; en DynamoDB puede ser un rediseño de claves o un índice secundario global. El coste de equivocarse aquí es alto, así que aquí es donde pongo el pensamiento.

Claves genéricas: PK y SK que no significan una sola cosa

El truco del single-table es que la partition key y la sort key no se llaman user_id ni order_id. Se llaman PK y SK a secas, y su contenido cambia según la entidad. Un usuario vive en PK = USER#123, SK = PROFILE. Sus pedidos viven en la misma partición, PK = USER#123, SK = ORDER#456. Así, pedir un usuario y todos sus pedidos es un único Query sobre PK = USER#123: la partición ya trae el perfil y los pedidos juntos, sin join.

// Todos los ítems de un usuario (perfil + pedidos) en una sola query
const res = await ddb.query({
  TableName: 'app',
  KeyConditionExpression: 'PK = :pk',
  ExpressionAttributeValues: { ':pk': 'USER#123' },
});

// Solo los pedidos: acoto por prefijo de la sort key
const orders = await ddb.query({
  TableName: 'app',
  KeyConditionExpression: 'PK = :pk AND begins_with(SK, :prefix)',
  ExpressionAttributeValues: { ':pk': 'USER#123', ':prefix': 'ORDER#' },
});

El begins_with sobre la sort key es la palanca: al prefijar los tipos (ORDER#, PROFILE, ADDRESS#) puedo traer justo el subconjunto que quiero de una partición, ordenado, en una sola llamada.

💡 En DynamoDB la sort key no ordena datos, diseña consultas. El prefijo que le pones es lo que decide qué preguntas podrás hacer barato.

GSIs: cuando necesitas mirar los datos por otro eje

Los patrones que no encajan en la clave principal se resuelven con índices secundarios globales. Un GSI es, en esencia, una proyección de la tabla con otra PK y otra SK, mantenida por DynamoDB de forma asíncrona. Si necesito "todos los pedidos con estado PENDING ordenados por fecha", creo un GSI cuya PK sea el estado y cuya SK sea la fecha, y ese acceso vuelve a ser un Query limpio.

El patrón que uso es la sobrecarga de índice: los mismos atributos genéricos GSI1PK y GSI1SK significan cosas distintas según la entidad, igual que la clave principal. Con un par de GSIs bien pensados cubro casi cualquier producto. Lo que no hago es crear un GSI por capricho: cada índice cuesta escritura y almacenamiento, porque cada put en la tabla se replica en los índices que apliquen.

Los trade-offs que nadie te cuenta al principio

El single-table es potente, pero es honesto reconocer lo que cuesta. Lo primero es la curva mental: modelar así es incómodo hasta que interiorizas pensar en accesos, y un equipo nuevo tarda en leer una tabla donde todo se llama PK y SK. Lo segundo es la rigidez: si aparece un patrón de acceso realmente imprevisto, adaptarte cuesta más que en SQL, donde una consulta ad-hoc siempre es posible aunque sea lenta.

Por eso no uso single-table para todo. Cuando el producto tiene consultas exploratorias, informes cambiantes o relaciones que no sé anticipar, Postgres me da una flexibilidad que DynamoDB me cobraría carísima. Elijo DynamoDB cuando los patrones de acceso son conocidos, acotados y necesito latencia predecible a escala sin operar un motor relacional. Ahí el single-table brilla: menos piezas, latencia plana y una factura que escala con el uso real y no con el tamaño de la tabla. Como todo en AWS, no es la mejor herramienta, es la mejor herramienta para un problema con la forma correcta.

No es serverless contra contenedores

El primer malentendido es tratarlo como serverless contra contenedores. Fargate también es serverless: defines una task, AWS la ejecuta y no tocas una sola instancia EC2. La diferencia real está en el modelo de ejecución. Lambda es efímero e invocado por evento: llega una petición, se levanta un entorno, corre tu handler, responde y se apaga. Fargate es un proceso de larga vida: tu contenedor arranca una vez, se queda escuchando y atiende peticiones hasta que lo escalas o lo matas.

Esa diferencia lo tiñe todo. En Lambda no controlas el ciclo de vida: no hay un "arranque" tuyo donde abrir un pool de conexiones y reutilizarlo tranquilo, porque el entorno puede reciclarse en cualquier momento. En Fargate sí tienes un proceso estable con su arranque, su memoria caliente y su pool de conexiones vivo entre peticiones. Elegir es, en el fondo, elegir cuánto control quieres sobre ese ciclo de vida.

La forma del tráfico manda

Lo primero que miro es cómo llega el trabajo. Si el tráfico es intermitente, a ráfagas o impredecible —un webhook que salta a veces, un cron que procesa cuando toca, un endpoint con picos raros— Lambda encaja de forma natural. Escala de cero a muchas invocaciones en paralelo sin que configures nada, y cuando no hay tráfico no pagas nada. Ese "de cero a mil sin avisar" es exactamente donde Fargate sufre: mantener capacidad para el pico significa pagar contenedores encendidos esperando, y escalar reactivo tarda más que un arranque de Lambda.

Si el tráfico es sostenido y constante, el cálculo se invierte. Un servicio con carga estable durante todo el día, en Lambda, es un goteo continuo de invocaciones que se factura por cada milisegundo y termina saliendo caro frente a un puñado de contenedores Fargate a pleno rendimiento. Ahí un proceso de larga vida aprovecha mejor cada CPU: no repite el coste de arrancar en cada petición y mantiene calientes recursos que Lambda tendría que rehacer una y otra vez.

💡 Lambda cobra por invocación y duración: brilla cuando a veces el tráfico es cero. Fargate cobra por contenedor encendido: brilla cuando el tráfico casi nunca es cero. Antes de decidir, dibuja la curva de tráfico de un día.

Duración y límites: el reloj de los 15 minutos

El segundo eje es cuánto dura cada unidad de trabajo. Lambda tiene un tope duro de quince minutos por invocación. Para una API o un procesamiento de eventos sobra, pero cualquier trabajo que pueda pasarse —una migración larga, un procesado de vídeo, un job que recorre un dataset grande— no cabe, y trocearlo para que quepa es complejidad que no siempre compensa. Fargate no tiene ese reloj: una task puede correr minutos u horas, lo que la hace el sitio natural para trabajo por lotes largo o procesos que simplemente tienen que estar vivos.

También está el arranque en frío. Cuando Lambda levanta un entorno nuevo, la primera invocación paga el coste de inicializar el runtime. Para cargas tolerantes a latencia da igual; para un endpoint sensible a la cola de latencias, ese frío ocasional se nota. Se mitiga —concurrencia aprovisionada, runtimes ligeros— pero es un factor real. Fargate no tiene arranque en frío por petición: el arranque lo pagas una vez cuando escalas una task nueva, no en cada invocación.

Estado, conexiones y dependencias

El tercer eje es cuánto estado y qué dependencias necesita el proceso. El caso clásico es la base de datos. Un pool de conexiones vive de reutilizar conexiones entre peticiones, y eso encaja con un proceso de larga vida como Fargate. En Lambda, cada entorno concurrente abre las suyas, y bajo un pico puedes agotar las conexiones de PostgreSQL sin darte cuenta; la solución pasa por un proxy de conexiones intermedio, otra pieza más en el diagrama. No es imposible hacer Lambda contra una base relacional, pero es fricción que Fargate no tiene.

// En Fargate esto se inicializa UNA vez al arrancar el
// contenedor y el pool se reutiliza en cada petición.
import { Pool } from 'pg';

const pool = new Pool({ max: 10 }); // vive entre peticiones

export async function handler(req: Request) {
  const client = await pool.connect(); // reutiliza, no reabre
  try {
    return await consulta(client, req);
  } finally {
    client.release();
  }
}

Ese mismo patrón en Lambda es traicionero: el pool sobrevive mientras el entorno se reutiliza, pero se multiplica por cada entorno concurrente, y ahí es donde revienta la base bajo carga.

Mi regla, y por qué mezclo los dos

Al final mi criterio es simple. Empiezo en Lambda cuando el trabajo es corto, disparado por eventos, con tráfico irregular y poco estado: webhooks, tareas asíncronas, glue entre servicios de AWS. Me muevo a Fargate cuando el trabajo es sostenido, de larga duración, o necesita conexiones vivas y control del ciclo de vida: APIs con carga constante, workers de cola que procesan sin parar, batch largo.

Y no elijo uno para todo el sistema. En el mismo producto convive un servicio HTTP en Fargate con conexión estable a Postgres y, al lado, funciones Lambda para los webhooks entrantes y los jobs asíncronos. Elegí mezclar en vez de forzar un único modelo porque cada carga tiene su forma, y pelearse con la herramienta para que haga algo que no es lo suyo se paga siempre: en Lambda con proxies y troceo, en Fargate con capacidad ociosa esperando un pico que no llega. Como casi todo en AWS, no hay una mejor herramienta, hay la mejor herramienta para la forma de tu problema.

Un LLM no tiene tests unitarios, y eso es el problema

Cuando escribes una función normal, un test unitario fija su contrato: entra esto, sale aquello, y si alguien lo rompe el pipeline te avisa. Con un feature basado en LLM ese contrato se difumina. El mismo prompt con el mismo input puede dar respuestas distintas, y un cambio aparentemente inofensivo —reordenar dos frases del system prompt, subir de una versión del modelo a la siguiente— puede degradar casos que ni sabías que dependían de ese detalle.

El error mental es tratar el prompt como código estable y el modelo como una dependencia fija. No lo son. El prompt es un parámetro que ajustas constantemente y el modelo es una dependencia que cambia debajo de ti sin avisar. Sin una batería de casos que corras en cada cambio, estás desplegando a ciegas y descubriendo las regresiones a través de los usuarios. Que es la peor forma de descubrirlas.

El eval mínimo: un dataset dorado y una métrica que te importe

No hace falta una plataforma de evals para empezar. Hace falta un archivo con casos representativos y una función que puntúe. Un caso es un input real, la salida esperada (o una propiedad que la salida debe cumplir) y opcionalmente por qué está ahí. Yo los saco de tres sitios: ejemplos que sé que funcionan, casos límite que me preocupan, y sobre todo los bugs reales que reporta la gente —cada regresión de producción se convierte en un caso de eval para que no vuelva a pasar.

type EvalCase = {
  name: string;
  input: MatchInput;
  // Una aserción sobre la salida, no una igualdad exacta:
  // con LLMs comparar strings palabra por palabra es inútil.
  expect: (output: MatchOutput) => boolean;
};

const cases: EvalCase[] = [
  {
    name: 'candidato senior con stack exacto sale primero',
    input: seniorReactExacto,
    expect: (out) => out.ranked[0].id === 'cand_42',
  },
  {
    name: 'no inventa habilidades que no están en el CV',
    input: cvSinKubernetes,
    expect: (out) => !out.ranked[0].reasons.includes('Kubernetes'),
  },
];

Fíjate en que no comparo la salida entera carácter a carácter. Con un LLM eso está condenado a fallar por diferencias irrelevantes de redacción. Lo que compruebo son propiedades: que el candidato correcto quede arriba, que no aparezca una habilidad alucinada, que el formato sea parseable. Cada aserción codifica algo que de verdad me importa del comportamiento, no la forma exacta del texto.

Puntuar lo subjetivo: cuándo uso un LLM como juez

Muchas salidas no se pueden verificar con un if. "¿Es esta explicación del match clara y fundamentada?" no es una propiedad booleana obvia. Para eso uso un segundo LLM como evaluador: le paso el input, la salida y una rúbrica concreta, y le pido una nota con justificación. Funciona sorprendentemente bien para detectar degradaciones grandes, y es mucho más barato que revisar cientos de salidas a mano.

Pero elegí usar LLM-como-juez con los ojos abiertos, no como bala de plata. Tiene sesgos conocidos: tiende a premiar respuestas largas, favorece el estilo sobre el fondo, y si le pides que puntúe su propio modelo se vuelve indulgente. Lo trato como un filtro ruidoso, no como la verdad: sirve para cazar caídas grandes de calidad entre versiones, no para afinar si algo pasó de 8,2 a 8,4. Para las propiedades que sí puedo verificar con código, uso código, que es determinista y gratis.

💡 Cada bug de LLM que llega a producción es un caso de eval que te faltaba. Antes de arreglar el prompt, añade el caso que falla a tu dataset. Así el arreglo queda blindado y esa regresión concreta no puede volver nunca.

Ejecutar los evals donde duele: antes de desplegar

Un dataset de evals que corres cuando te acuerdas no sirve de nada. El valor aparece cuando se ejecuta automáticamente en cada cambio que toque el prompt, el modelo o la lógica de orquestación. Lo enganché al pipeline como un paso más: si la tasa de aciertos sobre el dataset cae por debajo de un umbral, el despliegue se para igual que si fallara un test.

async function runEvals(cases: EvalCase[]) {
  const results = await Promise.all(
    cases.map(async (c) => ({
      name: c.name,
      passed: c.expect(await runFeature(c.input)),
    })),
  );

  const passed = results.filter((r) => r.passed).length;
  const rate = passed / results.length;

  console.table(results);
  if (rate < 0.9) {
    throw new Error(`Evals por debajo del umbral: ${rate}`);
  }
}

El umbral no es 100% a propósito. Con LLMs hay casos genuinamente ambiguos donde un fallo ocasional es tolerable, y exigir verde perfecto te lleva a sobreajustar el prompt a tu dataset. Prefiero un umbral alto pero realista y vigilar la tendencia: si la tasa lleva tres versiones bajando, hay un problema aunque cada versión pasara el corte.

Dónde pongo el esfuerzo hoy

Si tuviera que dar un solo consejo a alguien que mete su primer LLM en un producto, sería este: monta los evals antes de pulir el prompt, no después. Es tentador dedicar el tiempo a la parte creativa de redactar instrucciones ingeniosas, pero sin una forma de medir estás optimizando a ciegas. Elegí invertir en el arnés de evaluación antes que en el prompt perfecto porque el arnés se paga solo en la primera regresión que caza, y su valor crece con cada caso que le añades. El prompt lo reescribiré diez veces; los evals me dicen cuál de esas diez versiones es mejor.

El problema real no es el modelo, es el borde

Un LLM dentro de un producto no vive solo: su salida alimenta una función, una consulta o una llamada a otra API. Ese punto de contacto entre lenguaje natural y código tipado es el borde frágil. Si el modelo devuelve texto libre, el borde se llena de parseo defensivo: buscar el primer {, contar llaves, quitar los ```json, capturar el JSON.parse que revienta. Cada una de esas líneas es deuda que se rompe en cuanto el modelo decide ser conversacional.

Durante un tiempo intenté resolverlo con prompt engineering. "Responde solo con JSON válido, sin explicaciones." Ayuda, pero no garantiza nada: el prompt es una súplica, no un contrato. La lección que me llevó tiempo aceptar es que la fiabilidad no se pide, se impone en la capa de la API.

Function calling como contrato, no como truco

Los modelos modernos aceptan un esquema de herramienta o de respuesta y se comprometen a devolver algo que encaja en ese esquema. Eso cambia el juego: en vez de describir el formato en prosa, lo declaro como estructura y el modelo rellena los huecos. Dejo de parsear intenciones y empiezo a recibir datos.

Lo modelo así: defino la forma que necesito, la paso como esquema de respuesta, y el resto de mi código asume que recibirá exactamente eso. El prompt vuelve a hablar de la tarea —qué extraer, cómo priorizar— y no de comas y comillas.

import { z } from 'zod';

const CandidateExtraction = z.object({
  seniority: z.enum(['junior', 'mid', 'senior', 'lead']),
  primary_stack: z.array(z.string()).max(8),
  years_experience: z.number().int().min(0).max(50),
  location: z.string(),
  open_to_remote: z.boolean(),
});

type CandidateExtraction = z.infer<typeof CandidateExtraction>;

Ese esquema es la fuente de verdad. De él sale el tipo de TypeScript, de él sale el esquema JSON que le paso al modelo, y contra él valido la respuesta. Una sola definición, tres usos.

Zod: la red que atrapa lo que el modelo no garantiza

Aquí viene el matiz que mucha gente se salta: que la API acepte un esquema no significa que el resultado sea correcto en el sentido que a mí me importa. El modelo puede devolver un JSON estructuralmente válido y semánticamente absurdo: un years_experience de 200, un stack con quince entradas duplicadas, un enum que no existía. La forma es correcta; el contenido, no.

Por eso valido siempre en el borde con Zod, aunque use structured outputs. No es cinturón y tirantes por paranoia: es que la garantía de la API y la garantía de mi dominio son cosas distintas. Zod me deja expresar la segunda —rangos, longitudes máximas, enums cerrados— y convierte una respuesta dudosa en un error que puedo manejar antes de que contamine la base de datos.

const raw = await callModelWithSchema(prompt, CandidateExtraction);
const parsed = CandidateExtraction.safeParse(raw);

if (!parsed.success) {
  // No propago basura: reintento con el error como contexto,
  // o caigo a un flujo manual. Nunca escribo sin validar.
  return handleInvalid(parsed.error);
}

await saveCandidate(parsed.data); // parsed.data ya es del tipo correcto

💡 Un LLM en producto no es una fuente de verdad, es una fuente de propuestas. La validación es lo que convierte una propuesta en un dato en el que confías.

Reintentos con el error como contexto

Cuando la validación falla, el instinto es reintentar con el mismo prompt. Malgastas tokens repitiendo el mismo error. Lo que funciona de verdad es reinyectar el fallo: le devuelvo al modelo qué esperaba y qué me dio, y le pido corregir. En la práctica, el 90% de los fallos de validación se resuelven en un solo reintento informado, porque casi siempre son deslices tontos —un campo que faltaba, un enum mal escrito— que el modelo corrige de inmediato cuando le señalas el punto exacto.

Le pongo un tope de reintentos, claro. Si tras dos intentos sigue sin encajar, el problema no es el modelo teniendo un mal día: es que la tarea está mal planteada o el esquema pide algo que el input no contiene. Ahí el fallo ruidoso es un regalo, porque me obliga a arreglar la causa en vez de esconderla.

El trade-off que acepté

Structured outputs no es gratis. Encorsetar al modelo en un esquema reduce su flexibilidad: para tareas realmente abiertas, donde no sé de antemano la forma de la respuesta, el esquema estorba más de lo que ayuda. Y añadir Zod más los reintentos es código y latencia que antes no tenía.

Elegí structured outputs igualmente porque en producto casi nunca quiero creatividad en el borde: quiero determinismo. Prefiero pagar en rigidez y en unas líneas de validación a cambio de que el resto de mi sistema pueda tratar la salida del LLM como trataría cualquier otra API tipada. Ese es el objetivo real: que el modelo deje de ser una excepción especial que todos rodean con cuidado y pase a ser un componente más, con su contrato y su manejo de errores, como cualquier otra pieza en la que ya confío.

Un módulo modela un concepto, no una lista de recursos

El error que cometí más veces fue crear módulos alrededor de "cosas que suelo desplegar juntas" en lugar de alrededor de un concepto con una frontera clara. Un módulo "servicio-web" que crea el servicio de ECS, su balanceador, su DNS, su base de datos y sus alarmas parece cómodo, pero acopla decisiones que cambian a ritmos distintos. El día que quieres un servicio sin base de datos, o con la base de datos compartida con otro, el módulo te pelea.

La regla que me funciona es que un módulo debe modelar un concepto que tenga sentido nombrar por sí solo. "Un servicio en Fargate" es un concepto. "Una cola SQS con su DLQ" es un concepto. "Todo lo que necesita el proyecto X" no lo es: es una composición, y las composiciones van en la raíz, no dentro de un módulo. Cuando cada módulo tiene una frontera conceptual limpia, componerlos es fácil y sustituir uno por otro no rompe el resto.

Los booleanos de configuración son deuda disfrazada

Cada vez que añades una variable enable_algo a un módulo, estás metiendo una bifurcación en su comportamiento. Con dos o tres flags todavía se entiende. Con ocho, tu módulo tiene cientos de combinaciones posibles y solo has probado las cuatro que usas. El resto son campos de minas esperando a alguien.

# El módulo que envejece mal: se configura con flags
# que activan ramas de comportamiento incompatibles.
module "servicio" {
  source          = "./modules/servicio"
  enable_https    = true
  enable_autoscaling = true
  enable_spot     = false
  enable_efs      = true
  # ...y así hasta que nadie sabe qué combinaciones funcionan
}

Prefiero módulos con menos opciones y más pequeños, y resolver la variación componiendo en lugar de configurando. Si un servicio necesita almacenamiento persistente y otro no, no meto un flag enable_efs: hago que el volumen sea un módulo aparte que conecto cuando hace falta. El módulo de servicio no sabe nada de EFS y no tiene una rama sin probar. La composición se ve en la raíz, donde debe verse, y no escondida tras un booleano.

Las salidas son el contrato, cuídalas como una API

Lo que un módulo expone en sus outputs es su interfaz pública, y cambiarla rompe a quien lo consume igual que romperías a los clientes de una API. Al principio exponía de todo "por si acaso", y acabé con módulos cuyos consumidores dependían de detalles internos que yo quería cambiar. Ahora trato las salidas con la misma disciplina que un contrato: expongo lo mínimo que un consumidor necesita para conectar este módulo con otro —un ARN, un id, un endpoint— y nada de la fontanería interna.

# Expón identificadores para componer, no recursos enteros.
output "service_arn" {
  value = aws_ecs_service.this.id
}

output "task_role_arn" {
  # Otros módulos adjuntan políticas a este rol;
  # ese es el punto de extensión que quiero ofrecer.
  value = aws_iam_role.task.arn
}

Exponer el ARN de un rol en vez del rol entero es un ejemplo pequeño pero importante: le doy al consumidor el punto exacto donde extender (adjuntar una política) sin abrirle el recurso completo para que manosee cosas que romperían mi módulo.

💡 Antes de añadir una variable a un módulo, pregúntate si la variación pertenece dentro del módulo o en quien lo compone. La mayoría de las veces pertenece fuera. Un módulo con pocas entradas y salidas claras se reutiliza; uno con veinte flags se copia y se pega.

El estado es donde se pagan los errores de diseño

En IaC el diseño no se prueba de verdad hasta que aplicas cambios sobre infraestructura existente, y ahí es donde el estado te pasa factura. Un módulo mal fronterizado se nota cuando un plan quiere destruir y recrear algo que solo querías tocar de refilón, porque moviste un recurso de sitio o cambiaste un count por un for_each. Migrando a OpenTofu aprendí a tratar la estructura del estado como parte del diseño, no como un detalle: los moved blocks existen precisamente para refactorizar sin destruir, y usarlos con cuidado es lo que te deja reorganizar módulos sin un susto en producción.

Elegí módulos pequeños y de frontera clara sabiendo el precio: hay más piezas que componer en la raíz y la composición es más verbosa que un mega-módulo con flags. A cambio, cada pieza es entendible, testeable y sustituible por su cuenta, y un cambio en una no amenaza con recrear media infraestructura. Para código que va a vivir años y sobre el que aplico cambios cada semana, esa previsibilidad vale mucho más que la comodidad de escribir menos líneas el primer día.

Dónde pongo el esfuerzo hoy

Si tuviera que resumir todo en una frase: diseña módulos pensando en cómo se van a componer y a cambiar, no en cuánto escribes hoy. La infraestructura como código no es un script que ejecutas una vez, es una base de código que mantienes, y sufre los mismos males que cualquier otra —acoplamiento, ramas sin probar, contratos que se rompen— con el agravante de que aquí un error puede tirar un servicio. Menos opciones, fronteras claras y salidas tratadas como API es lo que hace que un módulo siga siendo tuyo dentro de seis meses en vez de ser el trozo del repo que nadie quiere tocar.

El retriever solo puede recuperar lo que indexaste bien

Un RAG tiene dos mitades: recuperar los fragmentos relevantes y generar una respuesta a partir de ellos. La segunda mitad es la que se lleva toda la atención porque es donde vive el LLM vistoso. Pero la generación está limitada por lo que le llega: si el retriever te trae tres fragmentos mediocres, ningún modelo, por grande que sea, va a inventar el contexto que falta. Como mucho lo va a fingir, que es peor.

Y lo que el retriever puede recuperar depende por completo de cómo cortaste el texto. Un embedding representa el significado de un fragmento entero. Si ese fragmento mezcla dos ideas distintas, su vector queda en un punto intermedio que no representa bien a ninguna de las dos, y la búsqueda por similitud lo pasa por alto justo cuando lo necesitas. El problema no es el modelo de embeddings: es que le diste a codificar un trozo de texto sin una idea clara dentro.

Partir por caracteres es el error por defecto

La receta que trae casi todo tutorial es cortar cada 1000 caracteres con 200 de solape. Es cómodo y es lo que hice al principio. El problema es que 1000 caracteres no significan nada semánticamente: el corte cae a mitad de una frase, separa una definición de su ejemplo, o mete el final de una sección y el principio de la siguiente en el mismo chunk. Acabas con vectores que representan fragmentos partidos por la mitad.

El primer arreglo barato es partir por estructura, no por longitud. Los documentos ya vienen con fronteras semánticas: párrafos, encabezados, ítems de lista. Cortar respetando esas fronteras hace que cada chunk tenga una idea razonablemente completa dentro.

// En vez de trocear a ciegas cada N caracteres,
// respeta las fronteras naturales del documento
function chunkByStructure(markdown: string): string[] {
  // Parte por encabezados de sección primero
  const sections = markdown.split(/\n(?=#{1,3}\s)/);

  return sections.flatMap((section) => {
    // Si una sección es corta, es un chunk entero
    if (section.length <= 1200) return [section];
    // Si es larga, subdivide por párrafos, no por caracteres
    return section
      .split(/\n\n+/)
      .reduce<string[]>((acc, para) => {
        const last = acc[acc.length - 1];
        if (last && (last + '\n\n' + para).length <= 1200) {
          acc[acc.length - 1] = last + '\n\n' + para;
        } else {
          acc.push(para);
        }
        return acc;
      }, []);
  });
}

No es sofisticado, pero el salto de calidad respecto al corte ciego es inmediato porque cada vector pasa a representar una unidad de sentido y no un pedazo arbitrario.

El tamaño del chunk es un trade-off, no un número mágico

Aquí no hay un valor correcto, hay una tensión que tienes que resolver según tu caso. Chunks pequeños dan embeddings muy precisos —el vector representa una idea concreta— pero fragmentan el contexto: la respuesta a una pregunta puede quedar repartida en cinco trozos y el retriever solo te trae los tres más parecidos. Chunks grandes conservan contexto pero diluyen el embedding: cuanto más texto metes, más se promedia el significado y menos discrimina la búsqueda.

Mi regla práctica es partir de chunks medianos, del tamaño de un par de párrafos que traten un solo subtema, y ajustar mirando qué recupera el sistema en consultas reales. Si veo que las respuestas correctas quedan cortadas, subo el tamaño; si veo que se recuperan fragmentos que hablan de varias cosas a la vez, lo bajo. El solape entre chunks contiguos ayuda a que una idea a caballo entre dos trozos no se pierda, pero el solape no arregla un corte hecho en el sitio equivocado.

💡 No optimices el tamaño del chunk en abstracto. Escribe diez consultas reales de tu producto, mira qué fragmentos recupera el sistema para cada una, y ajusta a partir de eso. El eval manual de diez casos te dice más que cualquier heurística.

Metadatos y contexto: el chunk no vive solo

Un fragmento arrancado del medio de un documento pierde de dónde salió. "El plazo es de treinta días" no significa nada sin saber plazo de qué. Por eso a cada chunk le adjunto metadatos —título del documento, sección, fecha— y cuando puedo antepongo una línea de contexto al propio texto que se embebe, de modo que el vector también capture a qué pertenece el fragmento. Ese pequeño encabezado hace que fragmentos ambiguos se vuelvan recuperables por la consulta correcta.

Los metadatos además te dan filtrado previo. En pgvector puedo combinar la búsqueda por similitud con un WHERE sobre columnas normales, y acotar el espacio de búsqueda antes de comparar vectores.

SELECT id, contenido
FROM chunks
WHERE documento_tipo = 'contrato'
  AND idioma = 'es'
ORDER BY embedding <=> $1
LIMIT 5;

Filtrar por metadatos antes de ordenar por distancia no solo mejora la precisión: reduce el conjunto sobre el que corre la búsqueda vectorial y con ello la latencia.

Dónde pongo el esfuerzo hoy

Si tuviera que repartir el tiempo de nuevo, dedicaría la mayor parte a la fase de ingesta —cómo parto, qué metadatos guardo, cómo enriquezco cada chunk con su contexto— y mucho menos a probar modelos. El modelo de embeddings importa, y el LLM generador importa, pero ambos operan sobre lo que la ingesta les prepara. Elegí invertir en chunking en vez de en un modelo más grande porque el chunking es barato de iterar y su efecto es multiplicador: mejora cada consulta que el sistema atienda, hoy y en el futuro. A cambio, es trabajo poco vistoso y difícil de presumir. Me sale a cuenta igual.

Los estados imposibles no deberían ser representables

El patrón que más me cambió la forma de escribir código es este: si un estado no puede ocurrir en tu dominio, haz que tampoco pueda escribirse en tu tipo. El ejemplo canónico es el clásico "cargando / cargado / error". La versión ingenua lo modela con campos opcionales sueltos:

// El tipo permite estados que no tienen sentido:
// loading true y data presente a la vez, o error con data.
type State = {
  loading: boolean;
  data?: Resultado;
  error?: Error;
};

Ese tipo admite { loading: true, data: algo, error: otraCosa }, un estado que jamás debería existir pero que el compilador acepta encantado. Cada componente que lo consume tiene que acordarse de comprobar las combinaciones a mano, y el día que a alguien se le olvida, aparece un bug. La unión discriminada cierra la puerta:

// Ahora cada variante lleva exactamente los datos que tiene,
// y ninguna combinación imposible es representable.
type State =
  | { status: 'loading' }
  | { status: 'success'; data: Resultado }
  | { status: 'error'; error: Error };

Con esta versión, acceder a data sin comprobar antes que status es 'success' no compila. El compilador te obliga a tratar cada caso, y el estado "cargando con datos y error a la vez" simplemente no puede escribirse. No he añadido un solo test y he eliminado una familia entera de bugs.

Tipos marcados: no todos los strings son iguales

Un string puede ser un id de usuario, un email o un token, y para TypeScript son intercambiables. Eso significa que pasar un id donde iba un email compila sin queja, y ese error se descubre en tiempo de ejecución o nunca. Los tipos marcados (branded types) le ponen una etiqueta al tipo para que el compilador distinga cosas que estructuralmente son iguales pero conceptualmente no.

type UserId = string & { readonly __brand: 'UserId' };
type Email = string & { readonly __brand: 'Email' };

function enviarInvitacion(to: Email) { /* ... */ }

const id = 'usr_123' as UserId;
enviarInvitacion(id); // ❌ no compila: UserId no es Email

El truco es que el __brand no existe en tiempo de ejecución —es puro tipo, cero coste— pero fuerza a que un UserId y un Email no se confundan. Combinado con validación en la frontera (una función que valida un string y devuelve un Email marcado), consigues que a partir de ese punto el sistema de tipos garantice que lo que circula ya está validado. La validación deja de ser algo que "espero que alguien haya hecho antes".

💡 Cuando dudes entre validar en tiempo de ejecución o confiar en un tipo, haz ambas cosas una vez en la frontera: valida el dato de entrada y devuélvelo marcado. A partir de ahí el compilador propaga esa garantía gratis por todo el código, sin una sola comprobación más.

Dejar que la inferencia trabaje en lugar de anotar todo

Un error frecuente es anotar tipos en todas partes por costumbre, incluso donde TypeScript los infiere mejor que tú. Anotar de más no es más seguro: acopla tu código a nombres de tipo que luego cuesta cambiar, y a veces esconde con un tipo ancho lo que la inferencia habría dejado preciso. Prefiero anotar las fronteras —las firmas públicas de funciones, los contratos entre módulos— y dejar que la inferencia haga el trabajo dentro.

// `as const` hace que el tipo inferido sea exacto,
// no un `string[]` genérico.
const TAGS = ['IA', 'AWS', 'Frontend'] as const;
type Tag = (typeof TAGS)[number]; // 'IA' | 'AWS' | 'Frontend'

Ese patrón me deja tener una única fuente de verdad —el array TAGS— y derivar el tipo de ella. Si mañana añado un tag al array, el tipo se actualiza solo y todos los sitios que hacían un switch exhaustivo sobre Tag empiezan a dar error de compilación hasta que trato el caso nuevo. El dato y el tipo no se pueden desincronizar porque uno se deriva del otro.

El coste, porque siempre lo hay

Modelar el dominio con tipos ricos no es gratis. Las uniones discriminadas obligan a escribir más ramas explícitas, los tipos marcados añaden ceremonia en las fronteras, y hay un punto en el que insistir en expresar una invariante en el sistema de tipos produce firmas que nadie quiere leer. Elegí este estilo asumiendo ese coste porque en un panel que mantengo durante años el compilador es el único revisor que nunca se cansa ni se despista, y cada invariante que consigo expresar como un tipo es un test que no tengo que escribir ni mantener. Pero sé cuándo parar: si un tipo se vuelve más difícil de entender que el bug que previene, ahí una comprobación en tiempo de ejecución y un comentario honesto ganan.

Dónde pongo el esfuerzo hoy

Mi regla práctica es invertir en tipos allí donde el dominio tiene reglas que de verdad importan —qué estados son válidos, qué datos están validados, qué valores son intercambiables y cuáles no— y no gastar esfuerzo en tipar hasta el último detalle interno que la inferencia ya cubre. Usado así, TypeScript deja de ser una molestia que te pide anotaciones y se convierte en una herramienta de diseño: escribes el modelo una vez, y el compilador se encarga de que nadie, tú incluido dentro de seis meses, pueda usarlo mal sin enterarse.

Después de meses trabajando así en un monorepo con miles de commits — donde una parte importante del código pasa por flujos asistidos por IA — esto es lo que funcionó, lo que falló y lo que haría distinto desde el día uno.

La IA no reemplaza el criterio, lo exige

El primer error que cometimos fue tratar la IA como un desarrollador junior más: darle una tarea y confiar en el resultado. El código compilaba, los tests pasaban… y aun así rompía convenciones del proyecto que nadie había escrito en ningún documento, porque vivían en la cabeza del equipo.

La solución fue invertir el flujo: antes de generar código, generamos contexto. Documentamos las convenciones implícitas — cómo nombramos servicios, dónde viven los tipos compartidos, qué patrones de error usamos — en archivos que las herramientas leen en cada sesión. La IA es tan buena como el contexto que le das.

💡 Regla del equipo: si un patrón se corrige dos veces en code review, se documenta para la IA. La tercera vez no debería existir.

Qué automatizamos (y qué no)

No todo el trabajo se beneficia igual. Nuestra división quedó así:

• Automatizamos: scaffolding de módulos, tests unitarios de casos límite, migraciones repetitivas, refactors mecánicos entre paquetes, y la primera versión de cualquier CRUD.
• Asistimos: diseño de APIs, lógica de negocio y queries complejas — la IA propone, el humano decide.
• Nunca delegamos: decisiones de arquitectura, seguridad, permisos y todo lo que toca dinero o datos personales.

El code review cambió de forma

Revisar código generado por IA no es como revisar código humano. El código de IA se ve bien — está formateado, nombrado con sentido y comentado. El peligro está en lo que parece correcto. Por eso movimos el foco del review: menos estilo, más comportamiento.

// Checklist de review para código asistido por IA
// 1. ¿Los casos límite son reales o inventados?
// 2. ¿Reutiliza lo que ya existe o duplicó un helper?
// 3. ¿El manejo de errores sigue nuestro patrón?
// 4. ¿Hay tests que fallan si el comportamiento cambia?
// 5. ¿Tocó algo fuera del alcance del ticket?

El punto 5 resultó ser el más importante: las herramientas de IA tienden a «mejorar» código vecino que nadie les pidió tocar. Un diff limpio y acotado vale más que uno brillante y extenso.

Lo que haría diferente hoy

Empezaría por la documentación de contexto desde el primer día, no después del primer incidente. Y establecería una métrica simple que al final es la única que importa: no cuánto código genera el equipo, sino cuánto código sobrevive seis meses en producción sin ser reescrito.

La IA nos hizo más rápidos, sí. Pero el cambio real fue otro: nos obligó a hacer explícito todo el conocimiento que antes era tribal. Y eso habría valido la pena incluso sin la velocidad.

Por qué serverless tenía sentido aquí

No uso serverless por defecto. Lo uso cuando el patrón de carga es irregular y el equipo es pequeño. Este proyecto cumplía las dos cosas.

• Tráfico a ráfagas. El panel se usaba en ventanas concretas: cargas de contenido, actualizaciones de catálogo, consultas puntuales. Entre medias, casi nada. Pagar EC2 encendido para eso es quemar dinero.
• Cero equipo de plataforma. No había SREs. Con Lambda y DynamoDB no parcheo sistemas operativos, no gestiono escalado, no me despierto porque un disco se llenó.
• Aislamiento por evento. Cada request es una invocación. Un pico no tumba el servicio entero; escala hacia arriba y luego a cero.

El precio de esto son otras cosas: modelar bien DynamoDB desde el día uno, vigilar los cold starts y aceptar que estás casado con AWS. Vale la pena si eres honesto con esos costos.

Modelar DynamoDB: single-table y patrones de acceso

El error más común con DynamoDB es tratarlo como Postgres sin joins. No lo es. En DynamoDB modelas los patrones de acceso primero, y la tabla después.

Para el panel usé un diseño single-table: una sola tabla, con PK y SK genéricos, y varios tipos de entidad conviviendo. Los patrones que necesitábamos eran claros: traer un vehículo por id, listar vehículos por categoría, traer el contenido asociado a un modelo.

{
  "PK": "VEHICLE#corolla-2023",
  "SK": "METADATA",
  "type": "vehicle",
  "name": "Corolla",
  "year": 2023,
  "category": "sedan",
  "GSI1PK": "CATEGORY#sedan",
  "GSI1SK": "VEHICLE#corolla-2023"
}

La clave: el acceso por id va contra PK/SK, y el listado por categoría va contra un índice secundario global (GSI1PK/GSI1SK). Nada de escaneos completos de tabla. Cada consulta es un Query sobre una clave de partición conocida, que es lo único que DynamoDB hace barato y predecible.

Reglas que me ahorraron dolor:

1. Escribe la lista de patrones de acceso antes de tocar la tabla. Si aparece uno nuevo después, casi siempre es un GSI más, no un rediseño.
2. Prefijos en las claves (VEHICLE#, CATEGORY#) para que entidades distintas convivan sin chocar.
3. Nunca un Scan en el camino caliente. Si necesitas filtrar por algo, ese algo va en una clave.

Cold starts: reales, pero domesticables

Los cold starts existen y son molestos, pero en 2026 el drama está muy exagerado. En este panel, el backend eran funciones Node en Lambda detrás de API Gateway, y la latencia extra en el primer arranque nunca fue un problema de negocio: era una herramienta interna, no un checkout con SLA de milisegundos.

Aun así, lo que sí hago:

• Bundle pequeño. Menos dependencias que cargar, arranque más rápido. Empaquetar con esbuild y sacar lo que no uso importa más que cualquier truco.
• Cliente de DynamoDB fuera del handler, para reutilizar la conexión entre invocaciones calientes.
• Memoria como palanca de CPU. En Lambda la CPU escala con la memoria asignada; subir de 128 a 512 MB muchas veces sale más barato y más rápido, porque la función termina antes.

import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, QueryCommand } from "@aws-sdk/lib-dynamodb";

// Fuera del handler: se reutiliza entre invocaciones calientes.
const ddb = DynamoDBDocumentClient.from(new DynamoDBClient({}));

export const handler = async (event: { category: string }) => {
  const res = await ddb.send(
    new QueryCommand({
      TableName: process.env.TABLE_NAME,
      IndexName: "GSI1",
      KeyConditionExpression: "GSI1PK = :pk",
      ExpressionAttributeValues: { ":pk": `CATEGORY#${event.category}` },
    }),
  );
  return { items: res.Items ?? [] };
};

💡 Con serverless no pagas por servidores; pagas por diseñar bien tus patrones de acceso desde el primer día. Esa deuda de diseño no se refactoriza barato.

Amplify para el frontend y auth

El panel en sí lo entregamos con Amplify: hosting del frontend, auth con Cognito por debajo, y el pegamento entre el cliente y las Lambda. Para un panel interno con login, Amplify te quita semanas de plomería. No tienes que montar tú el flujo de sesiones ni el hosting con CI.

Es cómodo, con un precio: Amplify es opinado. Cuando quieres salirte de su camino feliz, la abstracción empieza a pesar y depurar lo que genera por debajo cuesta. Para el alcance de este proyecto, el intercambio fue bueno.

Infra como código y los trade-offs de operación

Todo esto vive en código. Nada de crear recursos a mano en la consola: tablas, funciones, roles IAM, todo declarado. Hoy, con la experiencia de gestionar la infra de JXBS en OpenTofu (ECS Fargate, colas, Secrets Manager, CI/CD), tengo aún más claro que el peor error es tener recursos que nadie sabe de dónde salieron. Si no está en código, no existe.

Lo bueno de este modelo, sin adornos:

• Sin servidores que parchear ni mantener.
• Escala a cero: sin tráfico, sin factura de cómputo.
• Menos superficie de operación para un equipo pequeño.

Lo incómodo, con la misma honestidad:

• Lock-in real. DynamoDB y Lambda no se migran a otro cloud sin reescribir.
• Depurar es distinto. No hay un servidor donde entrar; vives en logs y trazas.
• El coste puede sorprender si haces Scan o modelas mal: DynamoDB es baratísimo bien usado y carísimo mal usado.

Qué haría distinto hoy (2026)

Volvería a elegir serverless para este caso; la forma del problema no cambió. Pero cambiaría cosas:

• Menos Amplify, más control explícito. Hoy montaría el hosting y el auth de forma más directa y dejaría Amplify para prototipos, no para lo que va a vivir años.
• Empezaría en OpenTofu, no en la herramienta propietaria. Es lo que uso ahora en producción y no volvería atrás.
• Invertiría más temprano en observabilidad. Trazas distribuidas desde el día uno; en serverless, no verlas es volar a ciegas.

Serverless sin dolor no significa serverless sin decisiones. Significa tomar las decisiones difíciles al principio —modelado de datos, IaC, observabilidad— para no pagarlas de madrugada después.

Offline-first no es lo mismo que offline-tolerant

Una app offline-tolerant asume que la red es lo normal y el offline la excepción: cuando falla, muestra un error amable y espera. Una app offline-first invierte la premisa. La fuente de verdad inmediata es local; la red es un detalle de implementación que sirve para propagar y refrescar datos cuando está disponible.

En el evento de Toyota esto no era una decisión estética. Un promotor registrando datos de un cliente interesado no puede quedarse mirando un spinner porque el pabellón saturó la red móvil. La captura tenía que completarse siempre, guardarse localmente y salir a servidor cuando se pudiera. El backend era serverless en AWS —Amplify, Lambda y DynamoDB— pero desde el punto de vista del frontend, el servidor podía no existir durante minutos y la app seguía siendo plenamente usable.

Estrategias de caché en el service worker

El service worker es el corazón de una PWA offline-first. La clave está en no usar una sola estrategia, sino elegir por tipo de recurso:

• App shell (precache): HTML, JS, CSS y assets del cascarón se precachean en la instalación. La app arranca sin red.
• Stale-while-revalidate: para recursos que pueden estar un poco desactualizados (imágenes de catálogo, íconos). Sirvo la caché de inmediato y actualizo en segundo plano.
• Network-first con fallback a caché: para datos que quiero frescos si hay señal, pero que no pueden bloquear la experiencia si no la hay.

// sw.js — enrutado por tipo de recurso
self.addEventListener('fetch', (event) => {
  const { request } = event;
  const url = new URL(request.url);

  // Datos de API: network-first con fallback a caché
  if (url.pathname.startsWith('/api/')) {
    event.respondWith(
      fetch(request)
        .then((res) => {
          const copy = res.clone();
          caches.open('api-cache').then((c) => c.put(request, copy));
          return res;
        })
        .catch(() => caches.match(request))
    );
    return;
  }

  // Assets del catálogo: stale-while-revalidate
  if (url.pathname.startsWith('/catalog/')) {
    event.respondWith(
      caches.match(request).then((cached) => {
        const network = fetch(request).then((res) => {
          caches.open('catalog-cache').then((c) => c.put(request, res.clone()));
          return res;
        });
        return cached || network;
      })
    );
    return;
  }

  // App shell: cache-first
  event.respondWith(caches.match(request).then((c) => c || fetch(request)));
});

Escrituras pendientes en IndexedDB

Leer offline es fácil; escribir offline es donde está el verdadero trabajo. Cada captura de datos que hacía un promotor se guardaba primero en IndexedDB como una operación pendiente, con un id propio generado en el cliente (un UUID), un timestamp y el payload completo. La UI daba feedback inmediato: el registro quedaba guardado, punto. No esperaba al servidor.

Esa cola local es lo que convierte el offline en algo confiable. Nada vive solo en memoria; si el promotor cerraba la pestaña o se quedaba sin batería, la operación seguía ahí al reabrir.

💡 En offline-first la red no es la fuente de verdad, es solo un canal de sincronización. Si tu UI espera al servidor para confirmar algo, todavía estás construyendo una app offline-tolerant disfrazada.

Sincronización diferida cuando vuelve la señal

Cuando la conectividad regresaba, había que vaciar esa cola. Usé la Background Sync API para delegar ese trabajo al navegador: registro un evento de sync y el propio sistema decide cuándo hay red estable para ejecutarlo, incluso si la pestaña ya no está en primer plano.

// Al encolar una escritura, pido un sync diferido
async function queueWrite(record) {
  await idbPut('pending-writes', record); // guarda en IndexedDB
  const reg = await navigator.serviceWorker.ready;
  if ('sync' in reg) {
    await reg.sync.register('flush-writes');
  }
}

// En el service worker: vaciar la cola cuando el navegador lo permita
self.addEventListener('sync', (event) => {
  if (event.tag === 'flush-writes') {
    event.waitUntil(flushPendingWrites());
  }
});

async function flushPendingWrites() {
  const pending = await idbGetAll('pending-writes');
  for (const record of pending) {
    const res = await fetch('/api/leads', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Idempotency-Key': record.id, // el UUID del cliente
      },
      body: JSON.stringify(record),
    });
    if (res.ok) await idbDelete('pending-writes', record.id);
  }
}

Conflictos e idempotencia

El escenario que no puedes ignorar: la escritura sí llegó al servidor, pero la respuesta se perdió en la red antes de volver. El cliente cree que falló y reintenta. Sin protección, duplicas el registro.

La solución fue idempotencia con la clave del cliente. Ese UUID generado al capturar el dato viajaba como Idempotency-Key. En la Lambda, si ya existía un registro con esa clave, se devolvía el resultado existente en lugar de crear uno nuevo. Así, reintentar era seguro por diseño: mil reintentos producían un solo registro.

Para conflictos de edición sobre el mismo dato, la regla fue simple y explicable: last-write-wins por timestamp del cliente. No era CRDTs ni nada sofisticado, pero para el flujo del evento —capturas mayormente independientes— era suficiente y predecible.

La UX del estado de sincronización

Todo lo anterior es invisible para el promotor, y así debe ser casi siempre. Pero "casi" es la palabra clave. La persona en el stand necesita confianza, no detalles técnicos. Mostrábamos tres estados simples:

• Guardado (local, sin conexión todavía): un check y "guardado en el dispositivo".
• Sincronizando: un indicador discreto cuando la cola se estaba vaciando.
• Sincronizado: confirmación de que el dato ya vivía en el servidor.

También mostraba un contador de "pendientes por enviar". Eso le daba tranquilidad a alguien no técnico: sabía que nada se había perdido aunque no hubiera señal, y sabía cuándo todo estaba a salvo antes de cerrar el turno.

Qué haría distinto en 2026

Hoy repensaría un par de cosas. Primero, apoyarme más en librerías maduras en lugar de escribir tanto a mano: Workbox para las estrategias del service worker, y una capa como Dexie sobre IndexedDB en vez de la API cruda. Segundo, para la sincronización, evaluaría un motor local-first de verdad —algo con reconciliación basada en CRDTs cuando el flujo lo justifique— para no atarme a last-write-wins en casos con edición concurrente real. Y tercero, sería más deliberado con la observabilidad: registrar métricas de la cola (tamaño, edad de las operaciones, tasa de reintentos) para diagnosticar en campo, porque en un evento no tienes tiempo de abrir DevTools. La idea central, sin embargo, no la tocaría: la señal es opcional, el trabajo no.

Por qué me quedé en Postgres

La tentación de meter Pinecone, Weaviate o Qdrant es real. Pero cada datastore nuevo es otra cosa que operar, monitorear, respaldar y mantener consistente. En un producto de reclutamiento, la similitud semántica nunca vive sola: siempre la cruzo con datos estructurados. Ubicación, seniority, disponibilidad, si la vacante sigue abierta. Si los vectores están en otro sistema, cada búsqueda se convierte en dos consultas y un join hecho a mano en el código de la aplicación.

Teniéndolo todo en Postgres gano tres cosas concretas. Transacciones: cuando actualizo un candidato y su embedding, o ambos entran o ninguno. Joins: filtro por columnas estructuradas y ordeno por distancia vectorial en la misma consulta. Y simplicidad operativa: un backup, un punto de monitoreo, una migración de Prisma. Con ECS Fargate y OpenTofu, cada pieza extra de infraestructura se paga en tiempo de mantenimiento.

Cómo funcionan los embeddings, a nivel práctico

Un embedding es un vector de números que representa el significado de un texto. Textos parecidos quedan cerca en ese espacio; textos distintos, lejos. No necesito entender la geometría de alta dimensión para usarlo: le paso el texto a un modelo de embeddings, me devuelve un array de floats, y lo guardo.

Lo importante es qué texto le paso. Para un candidato no le doy el CV crudo entero: armo un resumen estructurado con experiencia, tecnologías y rol. Para una vacante, el título más los requisitos reales. Basura entra, basura sale: la calidad del embedding depende de la calidad del texto que lo genera, mucho más que del modelo.

Guardando vectores con pgvector

pgvector añade un tipo vector y operadores de distancia. La tabla se ve así:

CREATE EXTENSION IF NOT EXISTS vector;

CREATE TABLE candidate_embedding (
  candidate_id  UUID PRIMARY KEY REFERENCES candidate(id),
  embedding     vector(1536) NOT NULL,
  seniority     TEXT NOT NULL,
  location      TEXT NOT NULL,
  is_available  BOOLEAN NOT NULL DEFAULT true,
  updated_at    TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE INDEX ON candidate_embedding
  USING hnsw (embedding vector_cosine_ops)
  WITH (m = 16, ef_construction = 64);

El operador <=> es distancia coseno. Menor distancia, mayor similitud. Elijo coseno porque me interesa la dirección del vector, no su magnitud.

Índice: HNSW vs IVFFlat

pgvector ofrece dos tipos de índice y la diferencia importa. IVFFlat agrupa vectores en listas y busca solo en las más cercanas: se construye rápido y ocupa poco, pero su recall depende de cuántas listas visites y sufre si los datos crecen mucho. HNSW construye un grafo navegable por capas: da mejor recall con latencia más baja en consultas, a cambio de tardar más en construirse y consumir más memoria.

Me quedé con HNSW. En reclutamiento, un candidato relevante que no aparece es un fallo silencioso que nadie reporta pero que degrada el producto. Prefiero pagar en construcción de índice y RAM a cambio de recall estable. ef_construction controla la calidad del grafo al construir; en consulta, subir ef_search mejora recall a costa de latencia. Ahí está la palanca del trade-off, y la muevo según lo que mida, no por corazonada.

💡 La distancia coseno te dice qué se parece; no te dice qué sirve. Esa diferencia es todo el producto.

Búsqueda híbrida: por qué no confío solo en el coseno

Este es el punto que más me costó aprender. La similitud semántica es buena encontrando cosas parecidas, pero "parecido" no es "correcto". Un backend senior en Caracas y uno junior en otra zona horaria pueden tener embeddings cercanos porque comparten tecnologías. El coseno no sabe que la vacante exige seniority alto y presencia local.

Por eso hago búsqueda híbrida: la similitud vectorial es una señal, no el veredicto. Filtro con WHERE sobre columnas estructuradas y combino la distancia con un score estructurado.

SELECT
  c.candidate_id,
  1 - (c.embedding <=> $1::vector)              AS similarity,
  CASE WHEN c.seniority = $2 THEN 0.3 ELSE 0 END AS seniority_boost
FROM candidate_embedding c
WHERE c.is_available = true
  AND c.location = $3
ORDER BY (c.embedding <=> $1::vector)
         - CASE WHEN c.seniority = $2 THEN 0.3 ELSE 0 END
LIMIT 20;

El WHERE recorta el espacio a candidatos elegibles antes de rankear. La similitud semántica ordena dentro de ese conjunto, y un boost estructurado ajusta el orden final. Los pesos son configurables y los afino contra lo que el equipo de reclutamiento considera un buen match, no contra una métrica abstracta de coseno.

Chunking y mantener los embeddings frescos

Los CV largos no los meto de una sola pasada. Divido en secciones con sentido (experiencia, skills, educación) y así el embedding de "experiencia backend" no queda diluido por tres párrafos de hobbies. Es chunking pragmático, guiado por la estructura del documento, no por un tamaño fijo de tokens.

Frescura: un embedding es una foto del texto en un momento. Si el candidato actualiza su perfil o la vacante cambia requisitos, el vector queda obsoleto. Guardo un hash del texto de origen; si cambia, reencolo la regeneración. Así solo recalculo lo que de verdad cambió, y no quemo llamadas al modelo por gusto.

Costos y cuándo sí sacaría una DB vectorial

Generar embeddings cuesta por token, y ese es el gasto real, no el almacenamiento. Reencolar solo ante cambios de hash mantiene la factura bajo control. HNSW pesa en RAM, así que dimensiono la instancia de Postgres pensando en el índice, no solo en las filas.

¿Cuándo dejaría Postgres? Si llegara a cientos de millones de vectores con tráfico de búsqueda muy alto y sostenido, donde el índice ya no cabe cómodo en memoria y la latencia se vuelve el cuello de botella del negocio. A esa escala, un motor vectorial dedicado con sharding se justifica. Pero es una decisión que se toma con números reales de carga, no anticipándose a un problema que quizá nunca llega. Hasta ahí, Postgres con pgvector hace el trabajo y me deja un sistema con menos piezas que puedan romperse.

Por qué un solo backend dejó de escalar con nosotros

El problema nunca fue el rendimiento. Fue el acoplamiento y el radio de impacto de cada despliegue.

Cuando todo vive en un módulo raíz de NestJS, las fronteras se difuminan solas. Un servicio de candidatos empieza a importar algo del módulo de empresas "solo por ahora". Un guard pensado para administración se cuela en una ruta pública. Y como es un único proceso, todo comparte la misma configuración, el mismo pool de conexiones a PostgreSQL, el mismo ciclo de arranque.

Tres síntomas concretos nos empujaron a movernos:

• Radio de impacto en cada deploy. Un cambio en el portal de administración obligaba a redesplegar el backend entero. Si algo salía mal, se caía todo, incluido el portal público de candidatos que no había cambiado en semanas.
• Audiencias mezcladas. Distintos portales tienen distintos requisitos de autenticación, distintos límites de rate, distinta superficie de exposición. Meterlos en el mismo proceso significaba que la ruta más sensible definía el nivel de paranoia de todas.
• Cognición compartida. Cada persona del equipo tenía que cargar todo el dominio en la cabeza para tocar una parte pequeña.

Qué significa "backends por audiencia"

La idea es simple: un backend por portal. Uno para candidatos, uno para empresas, uno para administración. Cada uno es un servicio NestJS 11 independiente, con su propio despliegue, su propia configuración y su propia superficie de API. El frontend sigue siendo Next.js 15 con React 19, y cada portal habla con su backend.

Lo que no cambia es la base de datos ni el dominio. Seguimos con PostgreSQL + pgvector y Prisma. El truco está en que el código compartido —entidades, lógica de dominio, utilidades, el cliente de Prisma— vive en paquetes del monorepo (Turborepo + pnpm), no duplicado en cada servicio.

apps/
  candidates-api/        # NestJS 11 — puerto candidatos
  companies-api/         # NestJS 11 — puerto empresas
  admin-api/             # NestJS 11 — puerto administración
  web-candidates/        # Next.js 15
  web-companies/         # Next.js 15
packages/
  domain/                # lógica de dominio pura, sin NestJS
  database/              # Prisma client + repos
  auth/                  # módulo de auth reutilizable
  config/                # carga y validación de env

La regla que nos salvó: los paquetes de packages/ exponen clases y funciones; los apps/ deciden cómo cablearlas. El dominio no sabe en qué backend corre.

Las trampas de pnpm + inyección de dependencias que nadie menciona

Aquí es donde perdí horas. NestJS asume que un provider es un singleton dentro de su contenedor. pnpm, con su estructura de node_modules estricta y sus symlinks, puede romper esa suposición sin decir nada.

El primer golpe: instancias de provider duplicadas. Si un paquete compartido declara un provider y dos módulos distintos lo importan por caminos ligeramente diferentes, terminas con dos instancias. Un "singleton" que no lo es. Lo notas cuando un caché en memoria o un pool de conexiones se comporta de forma inconsistente.

La causa casi siempre es la misma: el token del provider no es idéntico entre importadores, o la dependencia compartida quedó instalada en dos sitios del árbol.

El patrón que lo evita: un módulo dinámico global con un token explícito, declarado una sola vez.

// packages/database/src/database.module.ts
import { Global, Module, DynamicModule } from '@nestjs/common';
import { PrismaService } from './prisma.service';

export const PRISMA = Symbol('PRISMA'); // token estable y único

@Global()
@Module({})
export class DatabaseModule {
  static forRoot(): DynamicModule {
    return {
      module: DatabaseModule,
      providers: [{ provide: PRISMA, useClass: PrismaService }],
      exports: [PRISMA],
    };
  }
}

Cada app llama a DatabaseModule.forRoot() una vez en su módulo raíz. El token es un Symbol exportado, así que no hay ambigüedad de string ni riesgo de colisión.

Las otras dos que me mordieron:

• Peer deps, no deps directas. Los paquetes compartidos declaran @nestjs/common y @nestjs/core como peerDependencies, nunca como dependencias normales. Si un paquete trae su propia copia de NestJS, sus decoradores y metadatos viven en otro realm y la DI simplemente no los reconoce. En pnpm-workspace.yaml, apoyarse en el catálogo para fijar una sola versión ayuda mucho.
• Fronteras de módulo, no de carpeta. Un paquete puede exportar código; que sea un @Module de NestJS es una decisión aparte. Mantuvimos packages/domain libre de NestJS —clases y funciones puras— y solo packages/auth y packages/database exponen módulos. Así el dominio se reusa sin arrastrar el contenedor de DI a todas partes.

💡 En un monorepo, un "singleton" solo lo es si el token es idéntico y la dependencia está instalada una sola vez. pnpm no te avisa cuando no se cumple: te lo cuenta en producción.

Cómo compartir dominio sin volver a acoplarlo

El riesgo obvio de partir el monolito es reconstruir el acoplamiento dentro de los paquetes. Un paquete shared que lo sabe todo es el monolito con otro nombre.

Lo que funcionó:

• El dominio no importa infraestructura. packages/domain no conoce Prisma ni NestJS. Recibe interfaces; las apps inyectan implementaciones.
• Un paquete, una responsabilidad. auth, database, config por separado. Si dudas de a qué paquete pertenece algo, probablemente pertenece a la app.
• Sin dependencias entre backends. candidates-api nunca importa de companies-api. Si necesitan hablar, es por API o por un contrato compartido en packages/, jamás por import directo.

Desplegar varios servicios en ECS Fargate

Cada backend es un servicio propio en ECS Fargate: su task definition, su imagen, su auto-scaling. La CI/CD la gestionamos con OpenTofu, así que añadir un backend es declarar un módulo nuevo, no clicar en una consola.

Turborepo nos da el otro pilar: builds afectados. Solo se construye y despliega lo que cambió. Tocar admin-api no reconstruye candidates-api. Ese fue el objetivo original —reducir el radio de impacto— y aquí se vuelve real.

El detalle que cuida el bolsillo: cada servicio dimensiona su CPU y memoria según su carga. El portal de candidatos y el de administración no tienen por qué pagar el mismo tamaño de tarea.

Hacerlo sin un big-bang

No reescribimos nada de golpe. Extrajimos primero un backend —el de menor riesgo— dejando el monolito sirviendo al resto. Portal por portal, movimos rutas al nuevo servicio y apuntamos el frontend correspondiente. El monolito fue encogiendo hasta desaparecer.

Lo que le diría a mi yo del pasado

Dibuja las fronteras de audiencia desde el día uno, aunque todo viva en un solo proceso al principio. Separar módulos con límites claros es barato; desenredar un monolito acoplado es caro. Y trata la inyección de dependencias en un monorepo pnpm como lo que es: un tema de identidad de instancias, no de imports. Fija las versiones, usa tokens explícitos, mantén el dominio puro. El resto se deja llevar.

Los tokens son el contrato, no un detalle

Antes de hablar de componentes hay que hablar de tokens, porque son lo primero que rompes sin darte cuenta. Un token es una decisión de diseño con nombre estable: un color, un espaciado, una escala tipográfica. Si un portal escribe #2563eb a mano y otro usa var(--color-primary), no tienes un design system, tienes dos sistemas que coinciden por accidente.

Yo trato los tokens como el contrato público. Los consumidores no piden colores en hexadecimal; piden intención semántica.

:root {
  /* Primitivos: no se usan directamente en componentes */
  --blue-600: #2563eb;
  --gray-900: #111827;
  --space-2: 0.5rem;
  --space-4: 1rem;

  /* Semánticos: esto es lo que el consumidor toca */
  --color-action: var(--blue-600);
  --color-text-strong: var(--gray-900);
  --radius-control: 0.5rem;
}

[data-theme="dark"] {
  --color-text-strong: #f9fafb;
}

La capa semántica es lo que me permite hacer theming sin tocar un solo componente. Cambio el mapeo, no la firma. Y esa separación entre primitivos y semánticos es la que evita que alguien acople su portal a un azul concreto que mañana quiero mover.

La API del componente es una promesa

Con React 19 y TypeScript, la firma de un componente es un contrato tan serio como el de una API HTTP. Cada prop que expongo es algo que tendré que sostener durante versiones. Por eso prefiero composición sobre configuración: en lugar de un <Card> con veinte props booleanas, expongo piezas que se combinan.

// Mal: configuración que crece sin fin
<Card title="..." footer withBorder elevated dense hasIcon />

// Mejor: composición, el consumidor arma su caso
<Card>
  <Card.Header>...</Card.Header>
  <Card.Body>...</Card.Body>
  <Card.Footer>...</Card.Footer>
</Card>

Dos reglas que no negocio. La primera: no filtrar el DOM interno. Si expongo un className que se pega a un <div> cualquiera y mañana ese <div> desaparece, rompo a todo el que dependía de esa estructura. Prefiero exponer puntos de extensión explícitos (asChild, slots, variantes tipadas) antes que dejar que la gente estilice mis entrañas. La segunda: las props estables son sagradas. Renombrar variant a kind "porque suena mejor" no es un refactor, es romper a seis equipos.

💡 Un design system no se mide por cuántos componentes tiene, sino por cuánta gente puede construir encima sin escribirte un mensaje.

Versionar dentro del monorepo sin hacer daño

Turborepo y pnpm hacen que todo conviva, y eso tiene una trampa: es demasiado fácil "subir todo" a la vez. Yo uso changesets con semver de verdad. Un cambio de color semántico es un patch. Una prop nueva opcional es un minor. Quitar una prop, renombrarla o cambiar el DOM que alguien podría estar seleccionando es un major, y un major exige aviso, guía de migración y a veces un periodo de convivencia con la versión anterior.

Lo que evito religiosamente es el "bump everything" reflejo. Si toco solo el Button, no quiero forzar a que un portal que ni lo usa se recompile y revalide. El versionado granular es lo que mantiene la confianza: cuando actualizas, sabes qué te va a doler antes de que duela.

Accesibilidad de fábrica y el lado social

En Acid Tango, en Madrid, empujé WCAG 2.1 AA como estándar de equipo, y esa experiencia cambió cómo construyo librerías. La mejor accesibilidad es la que el consumidor recibe gratis. Si mi Dialog gestiona el foco, el Escape, el aria-modal y el retorno del foco al disparador, entonces cada portal es accesible sin que su desarrollador sepa nada de ARIA. El teclado, el manejo de foco y el contraste no son features opcionales: son el suelo.

Pero la parte más difícil no es técnica, es social. Un design system tiene gobernanza aunque nadie la escriba. Yo intento que sea explícita: quién decide qué entra, cómo se propone un componente nuevo, y —lo más incómodo— cómo se dice que no. Digo que no cuando algo sirve a un solo portal; eso vive en el portal, no en el core. Para onboarding de un componente nuevo pido tres cosas: un caso de uso real repetido, documentación con ejemplos copiables, y accesibilidad resuelta antes de mezclar. Sin ejemplos, la gente reinventa; y cada reinvención es una grieta en el contrato.

Qué haría distinto en 2026

Documentaría antes de codear. Durante un tiempo la documentación llegaba después, y eso es tarde: si no puedes explicar la API en un ejemplo corto, la API está mal. Hoy escribiría el ejemplo de uso primero y dejaría que él dictara la firma.

También sería más agresivo con la deprecación graduada. Marcar una prop como @deprecated en TypeScript, dejarla funcionar unas versiones y avisar en cada build es infinitamente más amable que un major sorpresa. Un design system maduro no se mide por lo rápido que cambia, sino por lo predecible que es al hacerlo.