DEV Community: Franchesco Romero

Tres capas de contexto para un agente de código, ordenadas por garantía

Franchesco Romero — Sun, 30 Aug 2026 18:09:58 +0000

Tres capas de contexto para un agente de código, ordenadas por garantía

Una migración tiró una columna. Las pruebas estaban en verde, la revisión estaba hecha, el deploy era de rutina. Setenta y ocho segundos después el panel de admin estaba regresando 500s. El agente que revisó esa migración no tenía forma de saber que el deploy rota dos tasks una a la vez, porque nada en el repo lo dice.

Cómo evité que Claude repitiera mis errores. - Speaker Deck

speakerdeck.com

TL;DR

Capa	Qué va en ella	Presente cuando	Obedecida
`CLAUDE.md`	Lo que el modelo no puede deducir leyendo el repo	Cada sesión, siempre	Casi siempre
Archivos de memoria	Un archivo por error cometido, con la razón	Cuando la recuperación lo juzga relevante	Casi siempre
Hooks de git y de herramientas	Reglas que no te puedes dar el lujo de que se salten	Cada corrida	No negociable

El orden es el punto. Cada capa cuesta más de configurar y da una garantía más fuerte. La mayoría de la gente trata de resolver todo en la capa uno, que es por lo que su CLAUDE.md tiene 600 líneas y va empeorando.

Dos números de los cinco meses, los dos medidos, los dos en:

CLAUDE.md fue de 180 líneas, llegó a su pico en 249, se podó a 129, y se queda en 145.
Los archivos de memoria fueron 12, 26, 36, 76, 91.

Los dos medidos el 21 de agosto de 2026. Corre los scripts en tu propio repo hoy y el conteo de memoria será más alto que el mío, porque esa capa nunca deja de crecer. Ese es el punto de ella.

La capa que escribo a mano se encogió. La capa que sale de los errores creció. Si las dos tuyas están creciendo, estás poniendo todo en la capa uno.

El incidente

21 de julio, 21:14. CloudWatch:

UndefinedColumnError: column listings.public_visibility does not exist
GET /api/v1/admin/marketplace
500 · 500 · 500 · 500 · 500 ...

La migración era correcta. El timing no. El backend corre dos tasks de Fargate y el rollout las reemplaza una a la vez, mientras que la migración corre antes de que las tasks nuevas estén sanas. Por setenta y ocho segundos el código viejo seleccionaba una columna que ya no existía.

El arreglo es el expand y contract de manual: deja de referenciar la columna en un deploy, tírala en uno posterior. Esa no es la parte interesante. La parte interesante es que pedí una revisión de esa migración y nunca le dije a nadie, humano o de otro tipo, cómo se despliega este proyecto. La topología de deploy no está en el código. No hay ningún archivo que diga "esto rota dos a la vez, con traslape".

El reflejo después de un incidente así es escribir un mejor prompt la próxima vez. Eso falla por una razón aburrida: un prompt se muere con la sesión.

Capa 1: lo que el modelo no puede deducir

La prueba de si una línea pertenece a CLAUDE.md es una oración.

Si el modelo lo puede deducir leyendo el repo, córtalo.

Claude lee tu manifiesto. No necesita que le expliques que usas React. El CLAUDE.md típico que encuentras en línea es en su mayoría una descripción del repo, que el agente deriva en dos tool calls y deriva mejor de lo que tú la escribiste, porque el repo es la verdad y tu descripción tiene cuatro meses de vieja.

Lo que sobrevive la prueba cae en cuatro formas, y todas son o una prohibición o una excepción:

## Base de datos

Nunca edites el schema a mano, siempre a través de migraciones.

Las migraciones que crean enums deben usar `op.execute()` crudo, no
`op.create_table` con un Enum nombrado: el paso de autogenerate se rompe.

`score_total` es una columna generada de Postgres. Nunca le asignes.

Las pruebas necesitan un Postgres real y el password no es el que está en el
README, que está viejo. Jálalo del secret manager del equipo.

Nota la última línea. Carga el puntero, no el secreto. Un CLAUDE.md se commitea, así que una credencial nunca va dentro de uno. Nombrar dónde vive el valor es todo el valor de la línea, y no cuesta nada.

Podar es una mejora medible

La parte contraintuitiva: un CLAUDE.md de 600 líneas rinde peor que uno de 100 líneas. Estos no son hechos que se acumulan, son instrucciones compitiendo por la atención. Cada línea irrelevante diluye las que importan.

El mío creció a 249 líneas en once días, que es lo que pasa cuando tratas el archivo como documentación de onboarding. El 5 de abril lo corté a 129. A lo largo de los cuatro meses siguientes se fue de vuelta a 145 y nada se rompió.

El truco práctico es hacer que el agente audite su propio contexto. Abre el archivo y pregunta:

¿Qué en este archivo puedes deducir leyendo el repo?

Luego borra eso. Vas a borrar más de lo que esperas.

Capa 2: un error, un archivo, con la razón

CLAUDE.md es lo que sabías de antemano. La memoria es lo que aprendiste crasheando. Si tu CLAUDE.md crece cada vez que algo se rompe, estás usando la capa equivocada.

Aquí está el archivo que salió de los 78 segundos, textual excepto por el
frontmatter:

Una migración que hace DROP o RENAME de una columna sale en el mismo deploy que el código que deja de usarla, pero el backend corre 2 tasks de Fargate y las rota una a la vez, y la migración corre antes de que las tasks nuevas estén sanas.

**Por qué:** el rolling deploy significa que el código viejo y el nuevo sirven simultáneamente. Cualquier cambio de schema que no sea compatible hacia atrás con la imagen anterior rompe ese traslape. Pegó el 2026-07-21: `/admin/marketplace` tronó por ~78 segundos.

**Cómo aplicar:** los cambios aditivos (ADD COLUMN con un default, CREATE INDEX) son seguros de un jalón. Los destructivos necesitan expand/contract: el deploy A deja de referenciar la columna, el deploy B la tira. Un RENAME es un DROP más un ADD.

Tres partes, todas obligatorias: qué pasa, por qué pasa, qué hacer. Sin la tercera es una queja, no una regla.

La razón no es opcional

Esta es la parte que la gente se salta, y saltársela es lo que hace que estos archivos se vuelvan superstición.

"Nunca hagas DROP COLUMN en una migración."

Esa regla nunca tira una columna. Ni en un proyecto de una sola instancia, ni en desarrollo. No tiene idea de dónde aplica, así que aplica en todos lados y se te atraviesa.

"Nunca hagas DROP COLUMN en un solo deploy, porque el rolling
 deploy tiene dos versiones del código sirviendo a la vez."

Esa sabe que un job de una sola instancia está bien, y se da cuenta por su cuenta de que un RENAME es un DROP disfrazado. La razón convierte una prohibición en un modelo mental, y un modelo mental generaliza a casos que nunca escribiste.

La otra cosa que vale la pena decir: yo no escribí ese archivo. Dije "esto acaba de pasar, guárdalo para que no se repita" y el agente lo escribió. Escribir la memoria es trabajo del modelo. Decidir que algo merece una es tuyo, y la prueba es si te va a morder otra vez. Un typo no. Una propiedad del sistema que no está escrita en ningún lado, sí.

Capa 3: cuando casi siempre no es suficiente

Las capas uno y dos funcionan bien. Pero son instrucciones a un modelo, y un modelo tiene una tasa de olvido distinta de cero. Para la mayoría de las reglas esa tasa es irrelevante. Para unas cuantas no lo es.

Tenía una regla de que cada funcionalidad visible al usuario se documenta en una guía que lee el lado no técnico del equipo. Vivió en CLAUDE.md por seis meses y se seguía casi siempre. Casi siempre resultó significar que la guía iba tres funcionalidades atrasada y nadie lo notó hasta que alguien la necesitó.

USER_VISIBLE_PATHS=(
    '^backend/app/api/v1/admin/'
    '^backend/app/services/billing/'
    '^frontend/src/pages/admin/'
)

# ¿tocó algo visible pero no la guía?
if ! echo "$STAGED" | grep -qx 'docs/team-guide.md'; then
    echo "✗ commit bloqueado" >&2
    # e imprime la salida de emergencia:
    #   git commit --no-verify
    exit 1
fi

El bash no es la parte interesante. Dos decisiones de diseño lo son.

El mensaje de error documenta la salida. Un hook del que no te puedes salir obstruye el primer caso legítimo, y alguien lo desinstala esa semana. El mensaje está escrito para la persona que va a estar aquí a las once de la noche sin paciencia para acordarse de una bandera.

La lista de rutas es deliberadamente conservadora. Los falsos positivos se descartan con una bandera. Una funcionalidad visible saliendo en silencio no se descarta, se descubre meses después.

Elegir la capa

No "cuál es la mejor". Cuánto cuesta la falla.

Si la regla	Ponla en	Porque
Es una preferencia de estilo	`CLAUDE.md`	Un fallo ocasional no le hace daño a nadie
Vino de un incidente específico	Memoria	Necesita la razón y el alcance
Se descubre semanas después	Hook	Nadie va a revisar. Se acumula
Cuesta dinero o uptime	Hook	El fallo ocasional deja de ser aceptable

No tengo una tasa de falla medida para ninguna capa y no la voy a inventar. El argumento es costo esperado, no frecuencia. Es el mismo cálculo que ya usas para decidir si algo se lleva una prueba automatizada.

Una nota sobre los subagentes

Adyacente, y muy malentendido: un subagente cuesta más tokens totales, no menos. Paga por su propio system prompt, su propia copia de CLAUDE.md y sus propios schemas de herramientas, y luego su resumen te regresa como input.

Lo que ahorras es ventana de contexto principal, que es un recurso distinto y a veces el que de verdad te falta. Vale la pena cuando la exploración abarca módulos que no conoces, o cuando las investigaciones pueden correr en paralelo.
No vale la pena para una tarea que toca tres archivos que ya identificaste.

Qué hacer el lunes

Tres cosas, menos de una hora en total.

Abre tu CLAUDE.md y pregúntale al agente qué es redundante. "¿Qué en este archivo puedes deducir leyendo el repo?" Borra eso.
La próxima vez que algo se rompa, archívalo mientras está caliente. Antes de arreglarlo, con la razón. Es cuando lo tienes fresco y cuando menos ganas tienes de escribirlo.
Escoge una regla y conviértela en un hook. La que duele si se resbala. Una. Con su salida documentada en el mensaje de error.

El modelo no recuerda. Tu repositorio sí.

Construyendo un recomendador de emparejamiento de expertos

Franchesco Romero — Mon, 24 Aug 2026 00:03:34 +0000

La forma del problema

Un directorio es una superficie: el miembro lo abre y adivina.
Un recomendador es una superficie de empujar: el sistema propone y tiene que justificarse. La justificación es la parte difícil, y es donde vive la estadística.

Tres restricciones hicieron esto distinto de un recomendador de contenido:

El item es una persona con capacidad finita. Un hilo se le puede recomendar a diez mil personas. Un experto no.
Una mala recomendación es cara de los dos lados. Quien pide desperdicia una petición, el experto desperdicia una hora, y los dos aprenden a ignorar la superficie.
La afirmación tiene que ser checable. "Quizá te guste este hilo" no necesita evidencia. "Esta persona está un nivel adelante de ti en diseño de sistemas" sí.

Recuperación: híbrida, fusionada con RRF

Tres recuperadores independientes sobre el conjunto de expertos elegibles, fusionados con Reciprocal Rank Fusion:

def rrf_fuse(*ranked_lists, k=60):
    """Fusiona listas de ids rankeadas. El score depende solo del rank, nunca
    de la escala propia del recuperador, que es el punto: la similitud coseno y
    un conteo de hilos resueltos no son números comparables."""
    fused = {}
    for lst in ranked_lists:
        for rank, key in enumerate(lst):
            fused[key] = fused.get(key, 0.0) + 1.0 / (k + rank)
    return fused

RRF es la primitiva correcta aquí por una razón que vale la pena decir: los recuperadores emiten cantidades incomparables. Uno regresa un coseno en [-1, 1], uno regresa un conteo entero de hilos resueltos, uno regresa un delta de nivel de escalera. Normalizarlos a una escala común requiere supuestos sobre sus distribuciones que nadie tiene a este volumen de datos.
RRF descarta las magnitudes y se queda solo con el orden, que es exactamente la información que sobrevive a una muestra chica.

k = 60 es la constante estándar de la formulación original de Cormack et al.
Aplana la cabeza: la diferencia entre el rank 1 y el rank 2 es
1/61 - 1/62 ≈ 0.00026, así que un recuperador no puede dominar por estar confiado, solo por estar consistentemente temprano a lo largo de las listas.

Scoring: un compuesto ponderado, con los pesos como datos

SCORE_WEIGHTS = {
    "compass_gap_fit": 0.30,   # explícito y direccional
    "semantic_fit":    0.20,   # coseno del embedding de perfil
    "skill_overlap":   0.15,   # tecnologías compartidas, ponderadas por rareza
    "capacity_fit":    0.15,   # también una compuerta dura
    "expert_quality":  0.12,   # rating, aceptación, experiencia que satura
    "specialty_match": 0.05,   # burda, pero muy poblada
    "fairness":        0.03,   # penalización de exposición amortiguada por log
}

Dos componentes valen la pena desempacar.

expert_quality satura. Un experto sin historial puntúa 0.5, no 0:

def expert_quality(*, avg_rating, completed, accepted, proposed):
    if completed == 0 and proposed == 0:
        return 0.5                      # prior neutral, no cero
    rating_part = ((avg_rating or 4.0) - 1.0) / 4.0
    acceptance  = accepted / proposed if proposed else 0.6
    experience  = 1.0 - math.exp(-completed / 5.0)
    return 0.5 * rating_part + 0.3 * acceptance + 0.2 * experience

La saturación exponencial sobre experience codifica que la diferencia entre 0 y 5 sesiones completadas es grande y la diferencia entre 40 y 45 es ruido.
Un término lineal habría hecho inalcanzables a los veteranos. El prior de 0.5 para los no probados es la decisión de cold start que deja crecer el pool de expertos más allá de quien haya ido primero; sin él, el sistema es un loop de rico se hace más rico por construcción.

fairness es exposición amortiguada por log.

def fairness_factor(times_recommended):
    return 1.0 / math.log(math.e + max(0, times_recommended))

ln(e + n) da exactamente 1.0 en n = 0 y decae lento. Una penalización lineal habría hecho irrecomendable a un buen experto después de un puñado de ciclos.

La parte que importa: esto es un problema de asignación

El instinto es computar un top-N por cada quien pide. Ese instinto está mal, y el modo de falla no es sutil.

Si cada quien pide escoge de forma independiente a su mejor experto, las mismas tres personas más fuertes juntan todas las peticiones. Son las que tienen los mejores ratings y el historial más profundo, así que ganan cada ranking, y dejan de contestar en un mes. El recomendador entonces destruye el recurso que existe para asignar.

Así que los pares se puntúan, y luego se asignan de forma global bajo una restricción de capacidad por experto:

def allocate(pairs, *, capacity, per_requester):
    """Asignación global greedy. Ordenada por score, cada par consume una unidad
    de la capacidad de su experto."""
    assigned = defaultdict(int)
    out = []
    for pair in sorted(pairs, key=lambda p: p["score"], reverse=True):
        if capacity.get(pair["expert_id"], 0) <= 0:
            continue
        if assigned[pair["requester_id"]] >= per_requester:
            continue
        capacity[pair["expert_id"]] -= 1
        assigned[pair["requester_id"]] += 1
        out.append(pair)
    return out

Esta es la aproximación greedy a un matching bipartito con restricción de grado. A esta escala (cientos de pares) la solución óptima vía scipy.optimize.linear_sum_assignment y la greedy difieren por ruido, y la versión greedy tiene una propiedad que la óptima no: es inspeccionable en un dry run, línea por línea, en orden de score. Cuando un operador pregunta "¿por qué esta persona obtuvo ese experto?", la respuesta es una sola pasada hacia abajo por una lista ordenada.

A quienes piden que la asignación no puede colocar no se les tira. Por construcción son aquellos cuyos mejores expertos están llenos, lo que los hace el insumo exacto para el clustering uno-a-muchos: agrúpalos por celda de escalera y propón una sola sesión.

La capa de datos, y la estadística que la hace defendible

La segunda capa responde "qué debería aprender después, y cuánto vale".
Compara la mediana de datos ponderada por fuente de los puntos de datos que reportan una habilidad contra los que no.

Esa oración contiene tres maneras de engañar a alguien. Las tres necesitaron una compuerta.

1. Ponderación por fuente con decaimiento exponencial por recencia

No todos los puntos de datos merecen voto igual. Cada fuente carga un peso de confianza y una corrección de sesgo, y cada punto decae con la edad:

COALESCE(cs.base_weight, 0.50)
  * (1 + COALESCE(cs.bias_correction_pct, 0) / 100.0)
  * POWER(0.5, EXTRACT(EPOCH FROM (now() - sdp.scraped_at)) / (:halflife * 86400.0))

Una vida media de 365 días significa que una publicación de dos años todavía cuenta, a un cuarto del peso de una fresca. El LEFT JOIN sobre la tabla de fuentes es deliberado: un punto de datos cuya fila de fuente nunca se registró cuenta en el default neutral de 0.50 en lugar de desvanecerse, porque tirar datos en silencio es peor que ponderarlos de forma conservadora.

El agregado es una mediana ponderada, no una media ponderada. Las
distribuciones de datos están sesgadas a la derecha y la cola es donde viven los errores de scraping; una sola cifra mal parseada mueve una media y no mueve una mediana.

def weighted_median(values, weights):
    pairs = sorted(zip(values, weights), key=lambda p: p[0])
    total = sum(max(0.0, w) for _, w in pairs)
    if total <= 0:                       # todos los pesos en cero: degrada a mediana simple
        mid = len(pairs) // 2
        return (float(pairs[mid][0]) if len(pairs) % 2
                else (float(pairs[mid - 1][0]) + float(pairs[mid][0])) / 2.0)
    half, acc = total / 2.0, 0.0
    for value, weight in pairs:
        acc += max(0.0, weight)
        if acc >= half:
            return float(value)
    return float(pairs[-1][0])

2. Estratificación, porque el número ingenuo mide antigüedad

Este es el confusor que hace inútiles a la mayoría de las afirmaciones de "la habilidad X paga Y% más". La gente senior sabe más herramientas. Compara a todos los que reportan Kubernetes contra todos los que no, y una parte grande del delta es nada más antigüedad filtrándose por la comparación.

Cada comparación por lo tanto pasa dentro de un estrato (rol, seniority, país, bucket de experiencia). Los buckets son burdos a propósito (0-2, 3-5, 6-9, 10+): estratos más finos matan de hambre a la muestra y el intervalo explota. Una habilidad cuyo efecto desaparece una vez estratificada se tira, no se reporta.

3. Un intervalo por bootstrap, no un estimado puntual

Un estimado puntual se lee como una promesa. El bootstrap por percentil re muestrea las dos cohortes con reemplazo, recomputa las medianas ponderadas, y toma los percentiles 5/95 de la distribución de deltas resultante:

def bootstrap_ci(with_vals, with_w, without_vals, without_w, n=1000, alpha=0.10):
    rng = random.Random(SEED)            # determinista: los mismos insumos deben
    deltas = []                          # producir el mismo intervalo en cada corrida
    for _ in range(n):
        a = [rng.choice(range(len(with_vals))) for _ in with_vals]
        b = [rng.choice(range(len(without_vals))) for _ in without_vals]
        med_a = weighted_median([with_vals[i] for i in a], [with_w[i] for i in a])
        med_b = weighted_median([without_vals[i] for i in b], [without_w[i] for i in b])
        if med_b > 0:
            deltas.append((med_a - med_b) / med_b * 100.0)
    deltas.sort()
    lo = deltas[int(math.floor((alpha / 2) * len(deltas)))]
    hi = deltas[min(len(deltas) - 1, int(math.ceil((1 - alpha / 2) * len(deltas))) - 1)]
    return round(lo, 2), round(hi, 2)

El bootstrap es la herramienta correcta porque la distribución muestral de una mediana ponderada de una distribución sesgada no tiene una forma cerrada limpia. El re muestreo esquiva la derivación por completo.

El RNG sembrado importa más de lo que parece. Un operador refrescando un dry run de admin no debe ver el número bambolearse; un intervalo de confianza que cambia al recargar es indistinguible de un bug.

Una fila se surge solo si las tres se cumplen:

significant = (ci_low > 0.0                  # el intervalo se queda de un lado del cero
               and premium >= min_pct        # bastante grande para valer el tiempo de una persona
               and premium <= claim_cap_pct) # no un outlier absurdo

Las filas no significativas de todos modos se computan y se guardan. La tabla de admin muestra qué se rechazó y por qué, porque un número que el sistema se negó a usar es tan interesante como uno que usó.

La medición que reencuadró el proyecto

Todo lo de arriba estaba en verde en CI. Luego la primera dry run contra producción:

requesters=82  experts=1  scored_pairs=82  affinity=3  office_hours=0

1 experto de 51. La causa:

requester_ids = {m.user_id for m in requesters}
eligible_experts = [
    m for m in experts
    if m.open_load < cap and m.user_id not in requester_ids   # <-- esto
]

La intención era "no emparejes a alguien consigo mismo". La implementación era "excluye a cualquier experto que sea también un candidato a pedir", y casi todos los expertos lo son, porque no tienen ninguna petición abierta propia.

Medido:

Roles activos elegibles como experto:                51
...que se apuntaron:                                 51
...bajo el tope de carga:                            51
...excluidos por ser también quienes piden:             50

El único sobreviviente era la única persona que resultó estar a media
interacción, y las tres propuestas apuntaban a ella. El sistema había
encontrado el modo de falla de burnout por su cuenta, en la primera corrida, a través de una línea pensada para prevenir un problema completamente distinto.

La guarda de auto emparejamiento ya existía por par, que es donde va.

Dos hallazgos más de la misma corrida:

Las cards podían salir sin razón. Solo 4 miembros tenían una colocación de escalera de competencias, así que el componente más pesado casi siempre era 0 y la señal sobreviviente era un coseno de embedding que nadie puede leer. Una propuesta tenía una lista de razones vacía. Una card que no puede decir por qué es peor que ninguna card.

El badge de tendencia disparaba con todo. La ingesta era reciente, así que casi cada publicación caía en la ventana de 30 días y la línea base de 90 días era una o dos filas:

golang   229 publicaciones  trend=2.00
go       155 publicaciones  trend=462.00
python   109 publicaciones  trend=62.40
aws       43 publicaciones  trend=61.50

Una razón necesita un denominador que valga la pena dividir. El arreglo es un conteo mínimo de línea base antes de que se afirme una tendencia siquiera, y una cota sobre la razón.

La lección de frecuencia inversa, aprendida tres veces

Esta es la parte con el mayor valor de transferencia, porque la misma idea estadística tuvo que aplicarse en tres niveles distintos y cada nivel se veía bien hasta que se inspeccionó.

Nivel 1: lift, en el minero de adyacencia

La adyacencia de habilidades es minería clásica de reglas de asociación sobre habilidades co-ocurrentes en publicaciones de vacantes. Para una regla
A -> B:

soporte = conteo de transacciones que contienen las dos
confianza = P(B | A) = soporte / conteo(A)
lift = confianza / P(B)

La confianza sola es inútil, y la razón es instructiva. Linux co-ocurre con todo, así que P(Linux | lo que sea) es alta y cada regla apunta a Linux. El lift divide por la tasa base: si saber A no sube la probabilidad de B por encima del azar, el lift es 1 y la regla no carga información.

lift = confidence / (singles[consequent] / total)
if lift < min_lift:      # 1.15
    continue

Reglas que sobrevivieron sobre datos reales, ordenadas por confianza * lift:

laravel        -> php            conf=0.73  lift=11.33  support=8
terraform      -> kubernetes     conf=0.75  lift=9.25   support=9
rails          -> ruby           conf=0.78  lift=7.94   support=7
react native   -> react          conf=1.00  lift=5.48   support=7
gcp            -> aws            conf=0.73  lift=6.15   support=16

Esas se leen bien para un humano, que es la única validación disponible a este tamaño de muestra.

Una trampa que vale la pena registrar: las primeras pruebas unitarias de esto eran degeneradas. Un corpus donde el antecedente aparece en cada transacción tiene lift 1.0 por construcción, así que nada puede ser significativo jamás.

Los fixtures tuvieron que reescribirse para incluir publicaciones que no contuvieran ningún lado de la regla. Un corpus de mercado es diverso; un corpus de prueba tiene que serlo también, o no prueba nada.

Nivel 2: frecuencia de documento, en la señal de tema

El riel salió y casi cada card decía:

Comparten temas: introduccion-plataforma.

La distribución de frecuencia de tags lo explica:

talento-tecnologico        27 hilos   50.0%
introduccion-profesional   17 hilos   31.5%
introduccion-plataforma    14 hilos   25.9%
espacio-relajacion          4 hilos    7.4%
servidores-caseros          4 hilos    7.4%
ai-local-vs-nube            2 hilos    3.7%

Tres tags cubren la mitad de un corpus de 54 hilos, luego un acantilado a 7%.

Este es el problema de Linux otra vez, un nivel arriba: un tag sobre la mitad del corpus no carga información sobre un par. Los tags por encima de 20% de frecuencia de documento se tiraron del scoring y del copy.

Ese arreglo hizo el copy menos vergonzoso sin hacerlo significar nada, lo que lleva al tercer nivel.

Nivel 3: el vocabulario era la ontología equivocada

Existían nueve tags en total. Ninguno de ellos era una tecnología.
Eran secciones del foro: un tablero de anuncios, dos áreas de introducción, un espacio fuera de tema. Ningún umbral de frecuencia puede rescatar una señal que está midiendo lo equivocado. Compartir "introducciones" significa que las dos personas se presentaron.

La señal técnica que sí existía era el tech_stack del perfil:

python 11 · aws 8 · docker 7 · node.js 7 · typescript 7
git 6 · react 6 · fastapi 5 · kubernetes 3 · terraform 3

Flaca (20 de 83 miembros) pero real, y nombra cosas que un experto puede enseñar. El componente de tema se reemplazó por completo, normalizado por el menor de los dos stacks para que un stack de 30 items no pueda diluir un buen match de 3-de-4, y extendido a través de las reglas de adyacencia minadas para que quien pide sobre Python conecte con un experto sobre FastAPI con la regla como la justificación declarada.

Y luego, predeciblemente, el nivel 3 tuvo su propio nivel:

También trabaja con python.

Python está en 11 de 20 stacks. El mismo problema, tercera recursión. La resolución esta vez no fue un filtro duro, porque a diferencia de una sección de foro, Python es una habilidad enseñable real y ponerla en cero descarta traslape genuino.

Las habilidades ubicuas se bajan de peso a un quinto en lugar de tirarse, el copy nombra las habilidades más raras
primero, y un stack compartido solo justifica una card cuando al menos una habilidad compartida es poco común:

weight_of = lambda sk: 0.2 if sk in common_skills else 1.0

Una habilidad compartida rara ahora le gana a una ubicua 1.0 a 0.2, que es lo que pone a Terraform encima de Python en el ranking en lugar de debajo por accidente de quién lista más tecnologías.

La generalización: cada vez que una señal es un traslape de conjuntos, pregúntate cuál es la tasa base de cada elemento antes de dejar hablar al traslape. El lift, el IDF, y este bajado de peso de habilidades son la misma corrección con tres nombres distintos.

Afinado de pesos como learning to rank offline

Los pesos compuestos se guardan en config, no en código, y hay una dry run que propone un rebalanceo a partir de los resultados calificados de los propios miembros:

correlations = {k: safe_corr(np.asarray(per_key[k]), y) for k in keys}

Tres decisiones deliberadas alrededor de ella:

La clase positiva es una sesión agendada, no un click. Un click en un hilo es barato; convertir una propuesta en una sesión de verdad agendada no.

Optimizar por clicks afinaría el ranking hacia la curiosidad en lugar de hacia sesiones que pasan.

La propuesta es una mezcla conservadora, nunca el vector crudo derivado de la correlación:

blended = {k: BLEND * corr_w.get(k, 0.0) + (1.0 - BLEND) * current.get(k, 0.0)
           for k in current}

Con BLEND = 0.5 y un piso de 30 muestras, una semana flaca no puede mover el ranking.

Nada se aplica automáticamente. Un operador previsualiza y aplica de forma explícita. Auto aplicar una correlación computada sobre decenas de muestras es como un ranker oscila.

Trampas

Trampa 1: la restricción de unicidad que creó duplicados. Las filas son únicas por (requester, expert, cycle_key), lo cual es correcto por ciclo y mal a través de ellos. El cron semanal escribió un segundo ciclo encima del primero y el riel de inmediato se dobló:

riel para <miembro>:
   <experto-a>  0.3997
   <experto-a>  0.3871   <--
   <experto-b>  0.3589
   <experto-b>  0.3462   <--

Arreglado en dos lugares, porque cualquiera solo deja un hoyo: la lectura se colapsa con DISTINCT ON (expert_id) quedándose con la mejor fila, y un ciclo nuevo reemplaza las propuestas sin tocar de los viejos para que la tabla no pueda crecer una card por persona por semana para siempre. Solo se tiran las filas no mostradas; cualquier cosa que un miembro vio es historial de embudo.

Trampa 2: el CTA que no hacía nada. El riel se renderizaba dentro de la misma página a la que enlazaba su botón, así que el click actualizaba el query string y la página se quedaba ahí. Peor, el enlace no cargaba id de match, así que una petición enviada nunca podía reportar de vuelta y la máquina de estados nunca podía avanzar más allá de CLICKED. La tasa de aceptación, la única métrica sobre la que se juzga el rollout y la que está cableada a la alarma, se habría leído como cero para siempre. El botón muerto se habría
reportado en un día; la métrica muerta se habría creído por semanas.

Trampa 3: una auto-recomendación latente. Cero filas en producción tenían requester_id = expert_id, pero el clustering uno-a-muchos escogía su experto del pool completo sin excluir el cluster, y esas filas cargan al primer miembro del grupo como quien pide. Podía apuntarse a sí mismo. Simplemente nunca había
disparado porque ningún cluster había alcanzado el umbral.

Lecciones

Mide contra datos de producción antes de confiar en un diseño. La primera dry run contra filas reales invalidó más del diseño que todas las pruebas juntas. Córrela antes de que se emita nada, no después.
Un recomendador para un recurso finito es un problema de asignación. El top-N por usuario es la forma equivocada y su modo de falla es destruir el lado de la oferta. La restricción de capacidad va en la asignación, no en un post filtro.
Chequea la tasa base de cualquier señal de traslape de conjuntos. El lift, la frecuencia de documento y la rareza de habilidad son la misma corrección. Una señal compartida por la mitad de la población no carga información sobre un par, no importa qué tan cierta sea.
Antes de afinar un umbral, verifica el vocabulario. Se gastaron dos rondas en cortes de frecuencia para un conjunto de tags que no contenía ninguna tecnología en absoluto. Pregúntate qué son las etiquetas antes de preguntar qué tan comunes son.
Un intervalo de confianza es una decisión de producto, no un detalle de estadística. El intervalo, el piso de muestra y la cota de efecto son lo que se para entre una correlación y una promesa que los datos no pueden cumplir. Muestra el rango, declara la muestra, y niégate a imprimir el número cuando las compuertas fallan.
Siembra el bootstrap. Un número que cambia al recargar es indistinguible de un bug, y destruye la confianza del operador más rápido que estar mal una vez.
Instrumenta la conversión antes de publicar la superficie. Un botón muerto se reporta en un día. Una métrica muerta se cree por un mes.
Publica el motor a oscuras. Emisión apagada por default y una dry run como la acción de admin por default significaron que cuatro bugs significativos se encontraron con datos reales y cero notificaciones enviadas.

Cómo mantener siempre disponibles las sesiones de tu agente de código remoto (parte 2)

Franchesco Romero — Wed, 19 Aug 2026 00:53:33 +0000

La Parte 1 construyó una caja siempre encendida para una sesión de remote-control de Claude Code y terminó con una alarma que convierte seis días de silencio en quince minutos. Esa alarma atrapa una caja muerta. Esta es la secuela, y la caja de aquí nunca estuvo muerta. Estaba active, su token estaba fresco, y en cada reinicio imprimía:

Take this session with you and pick up right where you left off on any device.
Open the Code tab in the Claude mobile app, or visit claude.ai/code in a browser.

y la sesión no estaba en claude.ai/code. Nunca se había registrado. El banner de arriba se imprime al arrancar, antes de que haya pasado lo que anuncia, así que le mintió al monitoreo, me mintió a mí cuando lo "arreglé", y casi se mintió hasta meterse en este blog post como el arreglo. Este post es sobre la diferencia entre un proceso que dice que está listo y una sesión que de verdad lo está.

TL;DR

	Lo que creía	Lo que era cierto
Causa raíz	el registro se puso viejo a lo largo de ~6 días de uptime	nunca se registró, el CLI se colgó en un prompt interactivo sin TTY
El "arreglo"	reinicia el servicio; el banner regresa; el heartbeat en verde	el reinicio imprimió el banner otra vez y aun así no se registró
La señal de salud que construí	grep del journal por `claude.ai/code`	ese string es el banner de pre-registro, verde para un proceso colgado
La señal real		la URL registrada (`claude.ai/code/session_…`), que solo se imprime después del registro

Placeholders, como en la parte 1: myapp, appuser, acme/myapp.

El síntoma

La sesión simplemente no estaba en la lista de claude.ai/code, mientras que todo en la caja decía que debería estar:

$ systemctl is-active claude-remote-control
active
$ stat -c %y ~/.claude/.credentials.json
2026-07-28 02:54:11          # token refrescado hace horas, la auth está bien
$ aws cloudwatch describe-alarms --alarm-names myapp-agent-box-down \
    --query 'MetricAlarms[].StateValue' --output text
OK

Así que hice lo obvio: reinicié el servicio. Imprimió el banner, el proceso subió, el heartbeat se puso verde, y la sesión seguía sin estar ahí. Ese es el momento en el que vale la pena detenerse. Cada señal que tenía decía sano, y el producto real (una sesión que puedo abrir desde un navegador) no existía.
Un reinicio que produce un banner no es un reinicio que produce una
sesión.

Conseguir una señal que no puede mentir

systemctl is-active reporta que el proceso existe. El banner reporta que el proceso arrancó. Ninguno reporta que la caja se registró con el punto de encuentro hospedado, lo único que mete la sesión en la lista. Para ver eso, pídele al CLI que escriba su propio log de debug y lee lo que de verdad pasa:

claude remote-control --name myapp-cloud --continue --debug-file /tmp/rc.log --verbose

Dos fallas cayeron de inmediato, y ninguna era "vieja":

Take this session with you and pick up right where you left off on any device.
Open the Code tab in the Claude mobile app, or visit claude.ai/code in a browser.
The session keeps running on this machine. ... Press Ctrl+C to stop.

Enable Remote Control? (y/n)

El proceso imprime el banner y luego se bloquea en un prompt interactivo.
Bajo systemd no hay TTY que lo conteste, así que espera ahí para siempre: active, banner emitido, registro ni siquiera intentado. Los CLI recientes agregaron esta confirmación; la caja de la parte 1 es anterior a ella.

Y cuando le di una y, la segunda falla:

Error: No recent session found in this directory or its worktrees.
Run `claude remote-control` to start a new one.

--continue, la bandera de la parte 1 que mantiene el marcador estable reanudando la misma sesión, da error duro cuando no hay sesión que reanudar. En una caja cuyo historial de sesión local se había borrado en una reconstrucción, --continue no era una optimización; era un arranque que solo podía fallar.

El arreglo real: contesta el prompt, y no dependas de que una sesión exista

Las dos fallas viven en una línea, así que el arreglo es una línea, un wrapper en ExecStart:

ExecStart=/bin/bash -c 'cd /home/appuser/myapp; \
  echo y | /home/appuser/.local/bin/claude remote-control --name myapp-cloud --continue || \
  echo y | /home/appuser/.local/bin/claude remote-control --name myapp-cloud'

Tres cosas se ganan su lugar:

echo y contesta el prompt. Importa que el proceso siga corriendo después de que su stdin se cierra (verificado, sí lo hace), así que un echo de una sola vez basta; sin yes inundando el pipe, sin sleep infinity manteniéndolo abierto.
--continue || <nuevo> trata de reanudar (marcador estable) y cae de vuelta a una sesión nueva cuando no hay nada que reanudar. Como echo y cierra limpio, un --continue fallido de verdad regresa y corre el fallback; un sleep infinity aquí colgaría el pipeline en el camino de falla y reintroduciría el atoro silencioso exacto.
Sin $@ ni $VAR en ExecStart. systemd expande ${} y $VAR pelón él mismo, y mutila $@; la jugada segura es repetir la ruta en lugar de factorizarla en una variable.

Ahora el log de debug muestra lo que el banner solo fingía:

[bridge:init] Resuming session session_01Pp8… on environment env_01Vp…
[bridge:init] Registered, server environmentId=env_01Vp…
[bridge:title] server title: myapp-cloud

Registered. Ese es el recibo. El banner era el menú.

Defensa en profundidad, todavía vale la pena conservarla

El wrapper arregla el outage. Dos guardas del primer borrador de este trabajo se quedan, porque endurecen la caja contra otras maneras en que la sesión puede caducar:

Reciclado diario. RuntimeMaxSec=86400 rebota la unidad cada 24h; Restart=always la trae de vuelta y --continue reanuda la misma sesión, así que el marcador aguanta. Si un registro alguna vez se pone viejo en un uptime largo, esto le pone tope al radio de impacto en un día en lugar de confiar en
que viva para siempre. TimeoutStopSec=20 mantiene cada reciclado rápido, ya que el CLI ignora SIGTERM por ~90s.

Escritura de vuelta de credenciales. La parte 1 señaló que el CLI rota su refresh token y la captura del secreto se pudre. Un helper chico empuja el token vivo de vuelta a Secrets Manager en cada corrida del watchdog, protegiendo con fuerza contra escribir un archivo local malformado encima de un secreto bueno, para que una instancia reemplazada ya no arranque sin autenticar.

El health check al que engañó el mismo banner

Aquí está la parte que arde. La primera versión del chequeo de readiness, la que se suponía atrapaba justo este estado de "arriba pero sin registrar", hacía esto:

# MAL: hace match al banner de pre-registro, así que está verde para un proceso colgado
journalctl -u claude-remote-control --since "${AGE}s ago" | grep -q "claude.ai/code"

claude.ai/code está en el banner que se imprime antes del prompt en el que el proceso estaba colgado. El chequeo que construí para detectar la falla quedaba satisfecho por la falla. Es el bug original vestido con el disfraz de su propio arreglo.

La sesión registrada imprime una línea distinta, una URL con un id de sesión o de environment:

Continue coding in the Claude mobile app or https://claude.ai/code/session_01Pp8…

El discriminador entre "anunciada" y "registrada" es un solo carácter: lo que sigue a code. El banner dice code in a browser; la cosa real dice code/session_… o code?environment=…. Así que haz match a eso:

# solo una sesión REGISTRADA imprime una URL con '/' o '?' después de 'code'
journalctl -u claude-remote-control --since "${AGE}s ago" | grep -qE 'claude\.ai/code[/?]'

Con el chequeo corregido el heartbeat significa lo que dice: active, lo bastante joven para haberse registrado, y una URL de registro en su propio log.
Cualquier otra cosa degrada el latido a DEGRADED y reinicia, y DEGRADED no hace match al filtro OK de la parte 1, así que un estado que no se va a auto-sanar de todos modos le suena a la alarma existente.

Callejones sin salida (los dos el mismo error)

Checar por una conexión de red abierta. La sonda de readiness intuitiva: seguramente una sesión registrada sostiene un socket al punto de encuentro. Medido en la caja sana: cero sockets establecidos. Una sesión registrada inactiva no mantiene ninguno. El chequeo reiniciaría una caja funcionando en cada tick.
Grep del banner de arranque. Cubierto arriba. Verde antes de que el trabajo esté hecho.

Los dos fallan de la misma manera: afirman sobre algo que es cierto antes de
que pase la cosa real. Un socket que quizá todavía no esté ahí; un banner que
está ahí demasiado pronto. El arreglo en los dos casos es afirmar sobre el
artefacto que existe solo después del éxito: la línea Registered, la URL
con un id.

Lecciones

Un banner es un menú, no un recibo. Cualquier mensaje de "ya puedes hacer X" impreso al arrancar es una intención, no una confirmación. Los health checks tienen que indexarse en el artefacto que existe solo una vez que X de verdad pasó.
Reiniciar hasta que reaparezca el mensaje feliz no es verificación. Vi el banner, vi el heartbeat ponerse verde, y seguí adelante, dos veces. El mensaje era el mismo las dos veces porque nunca dependió del éxito.
Los prompts interactivos son minas en cajas sin atender. Una sola compuerta (y/n) nueva, incontestable sin un TTY, convierte en silencio un servicio que funciona en uno colgado. Dale la respuesta explícitamente; no asumas que un servicio hereda la de tu terminal.
Las banderas de conveniencia tienen modos de falla. --continue mantiene un marcador estable y falla duro cuando no hay nada que continuar. En una caja que se puede reconstruir desde nada, "reanudar" necesita un "o arranca de nuevo" al lado.
Cuando no hay API de estado, afirma sobre el log de éxito, el específico. No el banner optimista. La línea que solo el camino exitoso puede producir.

Arquitectura de 10 agentes, 1k users, presupuesto: dos pizzas al mes

Franchesco Romero — Sun, 16 Aug 2026 23:36:58 +0000

Arquitectura de 10 agentes, 1k users, presupuesto: dos pizzas al mes - Speaker Deck

Construir sistemas multi-agente no tiene que ser caro. En esta sesión comparto cómo diseñé una arquitectura con 10 agentes de IA sirviendo a más de 1,00…

speakerdeck.com

Este post es el acompañamiento de mi charla en el AWS Summit CDMX 2026 (DEV302). No es un truco de free tier ni una demo de juguete: son 8 o 9 decisiones de ingeniería, cada una medida, que convierten el camino default (unos 250 dólares al mes) en algo que cabe en dos pizzas. Voy a mostrarte los números y el código.

Para que sea concreto uso un caso ficticio llamado Aula, una plataforma de cursos en línea con unos 1,000 estudiantes. El conocimiento ya existe: dudas resueltas, material de cada lección, ejercicios. Diez agentes convierten ese conocimiento en respuestas fundamentadas en el historial. Aula no es un producto real, pero los números sí salen de un sistema real.

El caso: qué hacen los diez agentes

Cinco flujos que ve el estudiante:

Una duda ("no entiendo los closures"), que devuelve una explicación fundamentada en el historial.
Una entrega (sube un ejercicio), que devuelve feedback editable, no la respuesta.
Qué sigue ("¿qué estudio después?"), que devuelve la siguiente lección más un plan de 3 pasos.
Buscar ("¿ya lo preguntaron?"), que devuelve dudas similares ya resueltas.
Resumen de un hilo largo, que devuelve los puntos clave.

Diez agentes en total: classifier, extractor, retriever, enricher, synthesizer, drafter, summarizer, recommender, action_plan y quality_judge. Cada uno es una clase, no un framework. Ahí empieza la historia de costo.

El camino default cuesta 22 pizzas

Si sigues el tutorial que la mayoría encuentra, armas esto: Amazon Bedrock Agents, AgentCore, Amazon OpenSearch Serverless, un NAT Gateway, un Application Load Balancer, Amazon RDS Proxy y AWS X-Ray. Suma unos 250 dólares al mes. Diecisiete pizzas solo de piso fijo, antes de la primera petición.

El reto no es recortar. Recortar es fácil. El reto es sostener el mismo sistema, en producción, seguro, manejable y escalable, gastando lo que dos pizzas. Voy a cotizar cada decisión en pizzas que se comería de tu factura. Una rebanada son unos 1.75 dólares (unos 30 pesos). Una pizza son 8 rebanadas, unos 14 dólares. El tope: dos pizzas, 16 rebanadas, unos 28 dólares al mes.

Decisión 1: un modelo por tarea (el 90/10)

La palanca más grande, y la que no te vende nadie, es el tier por agente. No todos los pasos necesitan el modelo premium.

7 agentes en Amazon Nova Lite (clasificar, extraer, condensar, recomendar, evaluar).
2 agentes en Amazon Nova Pro, solo los que producen lo que LEE el estudiante (synthesizer y drafter).
1 agente con Amazon Titan Embeddings (el retriever, que no es un LLM de chat).

El resultado medido: el 90% de las llamadas al modelo van al tier económico, y el costo baja a unos 0.004 dólares por duda. Si todo corriera en Nova Pro, sería cerca de 10 veces más.

¿Y la calidad? No es fe. Un shadow run midió que Nova Lite clasifica con un 98.5% de acuerdo contra Nova Pro en esa tarea. El tier se elige por dificultad, no por default.

# El tier lo fija el agente, no el framework.
MODEL_LITE = "amazon.nova-lite-v1:0"   # 7 agentes
MODEL_PRO  = "amazon.nova-pro-v1:0"    # 2 agentes: lo que LEE el estudiante
MODEL_EMB  = "amazon.titan-embed-text-v2:0"  # 1 agente: retrieval

class DrafterAgent(BaseAgent):
    name, default_model = "drafter", MODEL_PRO

Ver code/base_agent.py y code/tier_routing.py.

Decisión 2: mata el piso fijo (ingreso y red)

Dos ausencias que casi nadie cuestiona, y que juntas valen casi 5 pizzas que no pago.

Amazon API Gateway, no Application Load Balancer. El ALB cuesta unos 16 dólares al mes fijos, pizza y media, llegue 1 persona o un millón. Amazon API Gateway HTTP API cobra por request: a 1,000 usuarios con tráfico modesto, cerca de 1.5 dólares al mes. Llega al contenedor por VPC Link y service discovery, sin ALB de por medio. ¿Cuándo sí ALB? Routing L7 sofisticado, WebSockets, o miles de peticiones por segundo.

AWS Fargate en subnet pública, no NAT Gateway. El NAT cuesta unos 33 dólares al mes fijos (3 pizzas) aunque el tráfico sea cero. Lo mío: subnet pública con IP pública y un security group que solo deja entrar al VPC Link. La IP es pública pero funcionalmente inalcanzable. Cuidado con el consejo de "usa VPC endpoints": 4 o 5 endpoints a 7 dólares cada uno salen más caros que el NAT. Valen por compliance, no por ahorro.

Decisión 3: usa lo que ya pagas

pgvector, no Amazon OpenSearch Service. A escala de miles de embeddings, pgvector basta y sobra. El menú arranca en OpenSearch a 174 dólares o más, entre 8 y 15 veces mi presupuesto, en una sola línea. Lo mío: CREATE EXTENSION vector en la misma Amazon RDS que ya pago. La pregunta correcta no es si pgvector es tan bueno, es si necesito lo que OpenSearch hace de más. A 3,000 vectores, no.

-- El retriever: distancia coseno con índice HNSW, prefiltrando por curso.
SELECT contenido, resolucion
FROM dudas_embedding
WHERE curso_id = :curso
ORDER BY embedding <=> :q
LIMIT :k;

Tus filas ya son la memoria. AgentCore Memory ofrece memoria semántica gestionada. Pero la memoria de Aula, qué respuestas sirvieron por tema, ya está en filas de Postgres. Leer 20 filas, agruparlas y meterlas al prompt como un bloque de historial son unas 120 líneas y 50 milisegundos. No gana por económico, gana por simplicidad y por no necesitar código nuevo.

Workers asyncio, no AWS Lambda por tarea. Los trabajos programados (reindex, resumen semanal, barrido de evaluaciones, recordatorios) corren como tareas asyncio dentro del contenedor de AWS Fargate que ya está prendido para la API. El break point honesto: con más de una réplica, un cron in process dispara doble, y ahí sí subes a Amazon EventBridge Scheduler apuntando a ECS RunTask (cerca de 0 dólares). Managed cuando el patrón lo justifica, no por default.

Decisión 4: observabilidad por log, no por traza

Latencia, tokens y costo por agente salen de una línea de log en formato EMF (Embedded Metric Format), que Amazon CloudWatch convierte en métrica sin ninguna llamada a la API en el hot path. AWS X-Ray a bajo volumen es casi gratis (unos 0.40 dólares), así que aquí el argumento no es el costo, es el acoplamiento: EMF no necesita SDK ni escala por traza, y tú decides qué métricas existen.

La trampa que sí cuesta dinero: meter un ID de alta cardinalidad (como student_id) como dimensión son miles de métricas custom, cientos de dólares al mes. Los IDs van al cuerpo del log, nunca a la dimensión.

# 1 línea EMF -> métrica en CloudWatch, sin PutMetricData.
def emit_emf(agent: str, model: str, latency_ms: float, cost_usd: float):
    print(json.dumps({
        "_aws": {"CloudWatchMetrics": [{
            "Namespace": "aula/Agents",
            "Dimensions": [["AgentName", "ModelUsed"]],
            "Metrics": [{"Name": "LatencyMs"}, {"Name": "CostUsd"}],
        }]},
        "AgentName": agent, "ModelUsed": model,
        "LatencyMs": latency_ms, "CostUsd": cost_usd,
    }))

Ver code/emf.py.

Decisión 5: seguridad y resiliencia sin inflar la factura

Seguridad. El input del usuario entra a un LLM, así que va como dato delimitado, no como instrucción. Salida estructurada más el juez como respaldo. IAM al mínimo: bedrock:InvokeModel solo sobre los ARNs de mis 2 modelos, no un comodín. Guardrails gestionados solo a escala (PII, toxicidad) o por compliance.

Resiliencia. El estudiante espera unos 2 segundos. Amazon Bedrock puede responder 429 en picos. La respuesta: retry con backoff acotado por el presupuesto de latencia (2 intentos máximo) y fallback de tier. Si Nova Pro está throttled, degrada a Nova Lite con la confianza más baja. Degrada, no revienta. Provisioned Throughput solo si el 429 es crónico, no para un pico.

async def invoke_resilient(prompt, primary=MODEL_PRO, fallback=MODEL_LITE, budget_ms=2500):
    for attempt in range(2):
        try:
            return await invoke(prompt, model=primary, timeout_ms=budget_ms)
        except ThrottlingException:
            await asyncio.sleep(min(0.2 * 2 ** attempt + jitter(), 0.6))
    # sigue throttled: degrada, no revienta
    return await invoke(prompt, model=fallback, confidence_penalty=0.15)

Ver code/resilience.py.

Dónde se va el costo, de verdad

Aquí está lo bonito de medir con EMF: puedes ver dónde vive cada dólar sin instrumentar nada extra.

Concepto	Rebanadas	Costo aprox
AWS Fargate ×2, 24/7	12	22 dólares
Amazon Bedrock (10 agentes)	2	3 dólares
EMF (métricas por log)	1	2 dólares
Amazon API Gateway	1	1 dólar
Total	16	~28 dólares

El 72% de la factura son los dos contenedores de AWS Fargate prendidos todo el tiempo. Todo lo demás junto son 5 rebanadas. La lección: el costo fijo que no usas es tu mayor fuga, y aquí ya está exprimido.

La parte honesta

Redondeo a 2 pizzas, pero son unos 2 y cuarto. El redondeo lo absorbe.
Las cifras del core (AWS Fargate, Amazon Bedrock, EMF) son medidas. Las de tool use en Aula son estimadas.
El costo real de este sistema no es dinero, es tiempo de ingeniería y seguridad. Medir cada decisión toma más trabajo que aceptar el default.

Lo contraintuitivo: baja al crecer

Costo por estudiante al mes, a 1,000 estudiantes: unos 2 centavos.

Como la factura es costo fijo (los contenedores no escalan con el uso), se reparte. Más estudiantes, menos por cabeza. Es lo opuesto a una arquitectura lineal por request. A 10 usuarios sale carísimo por cabeza; a 1,000 sale a 2 centavos, y sigue bajando.

Para llevar

El piso fijo que no usas es tu mayor fuga: NAT, ALB, OCU.
Usa lo que ya pagas: pgvector, asyncio, filas como memoria.
Haz coincidir el tier del modelo con la dificultad de la tarea (el 90/10).
El patrón de uso elige la herramienta, no el default.
La pregunta correcta no es "¿uso managed?", es "¿qué NO quiero mantener?".

Las slides, el código y las notas están en el repositorio. Si vas a construir agentes sobre Amazon Bedrock y el presupuesto importa, empieza por medir dónde se va cada dólar. Casi siempre es una sola cosa.

Demo: https://awssummitcdmx2026.elches.co/

elchesco / diez-agentes-dos-pizzas

Diez agentes en producción sobre Amazon Bedrock por el costo de dos pizzas al mes. Código de acompañamiento (AWS Summit CDMX 2026, DEV302).

Diez agentes en producción por el costo de dos pizzas al mes

Código de acompañamiento de la charla AWS Summit CDMX 2026 (DEV302): un sistema multi agente en producción sobre Amazon Bedrock, con Q&A, feedback de ejercicios, recomendaciones, búsqueda y resumen, para unos 1,000 usuarios, por unos 28 dólares al mes.

Post: Arquitectura de 10 agentes, 1k users, presupuesto: dos pizzas al mes
Slides: Speaker Deck

El caso es ficticio: Aula, una plataforma de cursos en línea con ~1,000 estudiantes. No es un producto real. Los números (latencia, costo por duda, picos de conexiones) salen de un sistema real. Los snippets son ilustrativos: muestran cada decisión de costo, no son un proyecto ejecutable completo.

Las decisiones, en código

Cada archivo es una decisión de la charla. Los marcados con 🔒 estaban en slides que oculté por tiempo, pero el código va aquí completo.

Archivo	Decisión

…

View on GitHub

Gracias por leer. Preguntas y correcciones son bienvenidas.

¿Cómo revertir una migración promovida a Aurora sin perder los datos nuevos?

Franchesco Romero — Sat, 25 Jul 2026 22:56:24 +0000

Migraste una base de datos MySQL de Amazon RDS a Amazon Aurora. La read replica de Aurora se puso al día, la promoviste, cambiaste el endpoint de la app, y ahora los writes aterrizan en Aurora.

Diez minutos después, o quizá tres horas después, algo anda mal y quieres regresar a la vieja instancia de RDS.

Aquí está la trampa. La vieja instancia de RDS está congelada en el momento en que hiciste el corte. Cada pedido, registro y edición que pegó en Aurora desde entonces no existe en RDS. "Revertir" de forma ingenua significa "tirar a la basura todo lo que pasó en la base de datos nueva". Y el arreglo de siempre, tomar una ventana de mantenimiento y recargar RDS desde Aurora, no escala: a 100 TB una recarga se mide en días, no en minutos.

Esta es la historia de construir una reversión que conserva los datos
nuevos, probarla en AWS real hasta que se rompió de maneras interesantes, y reducirla a un manual de operaciones que una persona cansada pueda seguir a las 3 de la mañana. Todo lo de abajo lo corrí en instancias desechables en una región aislada y las borré después.

TL;DR

La vieja instancia de RDS no debería ser un backup congelado. Hazla una réplica inversa viva de Aurora: después de promover Aurora, apunta RDS de vuelta a Aurora sobre replicación por binary-log para que siga tragándose cada write nuevo. La reversión es entonces "déjala terminar, luego cambia el endpoint".
Con la réplica inversa mantenida caliente, el tiempo de reversión es constante e independiente del tamaño de la base de datos: como 1 a 5 minutos a 1 GB y a 100 TB, porque haces el corte del delta, no de la base de datos.
La única compuerta que importa es Seconds_Behind_Source = 0. Llegar ahí significa que RDS tiene el 100% de los writes de la era Aurora. Hacer el corte antes pierde datos.
Dos rutas funcionan: replicación nativa por binlog (recomendada, barata, replica DDL) y AWS DMS (más manejada por consola, pero ignora en silencio DROP TABLE y unos cuantos ALTER). Las dos las validé en vivo.
Un "standby frío vacío" (una instancia lista pero sin datos) cuesta lo mismo por hora que una réplica caliente y te da la velocidad de reversión de no tener nada. Si pagas por mantener una caja corriendo, mantenla caliente.
Los filos que costaron tiempo real de debug: una regla de security group que falla en silencio, una edición de parameter group que es todo-o-nada, un stored procedure cuyo conteo de argumentos no es lo que los docs implican, y una regla de compatibilidad de versión que bloquea la migración de plano.

La forma del problema

La migración hacia adelante de RDS a Aurora es una cosa resuelta de un solo botón: creas una read replica de Aurora desde la instancia de RDS, esperas, promueves. AWS hace el snapshot y convierte por ti. Esa parte la tomo como dada.

La dirección interesante es hacia atrás. Una vez que Aurora es primaria y toma writes, la vieja instancia de RDS se va quedando más desactualizada cada segundo. Una reversión que importa tiene que responder una pregunta: ¿a dónde van los writes de la era Aurora? Si la respuesta es "a ningún lado, los perdemos", no es una reversión, es un desastre con pasos extra.

La respuesta que escala es invertir la replicación. Cuando RDS era la fuente y Aurora la réplica, los datos fluían de RDS a Aurora. Después de la promoción lo configuras al revés: Aurora es la fuente, RDS es la réplica.
Ahora RDS jala de forma continua todo lo que Aurora escribe. La vieja
instancia no está congelada, es un espejo caliente que siempre va un segundo o dos atrás de Aurora. Revertir se vuelve: detén Aurora, deja que RDS termine el último segundo, cambia el endpoint.

La parte elegante es el costo de la sincronización inicial. En el instante de la promoción, RDS ya es byte por byte igual a Aurora, porque era la fuente. Así que el enlace inverso no re-copia la base de datos. La siembras en la coordenada de la promoción y de ahí en adelante solo carga el delta.
Por eso el tamaño de la base de datos deja de importar.

Construyéndolo, y viéndolo romperse

Levanté el mundo post corte en instancias desechables: un clúster de Aurora MySQL como "prod nuevo", una instancia de RDS for MySQL como el objetivo de reversión, en una región aislada. Luego cableé la replicación inversa y la empujé por el camino feliz y por los caminos de falla.

Callejón sin salida 1: el security group que falla en silencio

Primer intento de arrancar la replicación, la réplica nada más se quedó ahí sentada:

Replica_IO_Running: Connecting
Source_Server_Id: 0
Last_IO_Errno: 0
Last_IO_Error:

Connecting, para siempre. Sin número de error, sin texto de error. El hilo de IO estaba tratando de alcanzar Aurora y no recibía nada, pero nada se reportaba. La causa: las dos bases de datos eran públicamente accesibles (para que mi cliente de SQL las alcanzara), lo que significaba que la réplica resolvía el endpoint de Aurora a su IP pública. La conexión de replicación entonces llegaba a Aurora desde la IP pública de la réplica, que el security group no permitía. Un drop silencioso, presentado como un esperanzado Connecting.

La lección no es "abre la IP pública". Es lo contrario. En producción, mantén las dos bases de datos privadas. Entonces el tráfico de réplica a fuente fluye sobre IPs privadas dentro de la VPC, y una sola regla de autorreferencia del security group lo cubre. La accesibilidad pública fue lo que creó el problema.

El camino feliz

Con la red arreglada, la mecánica funcionó exactamente como se anunciaba.
Escribe dos filas a Aurora, y en unos segundos aparecen en RDS. Detén el enlace, drena a cero lag, corre los dos procedimientos de reversión, y RDS se vuelve una primaria independiente que acepta writes mientras Aurora queda desacoplada. Cero datos perdidos. La secuencia completa está en el manual de operaciones al final.

Callejón sin salida 2: revertir demasiado pronto pierde exactamente lo que crees

Todo el diseño descansa en una sola disciplina, así que me obligué a verla fallar. Detuve la réplica, escribí dos filas más a Aurora, y luego "reverti" sin esperar a que la réplica se pusiera al día.

Aurora: 7 filas.
RDS después de revertir: 5 filas.

Las dos filas escritas durante la ventana se fueron. Esta es toda la razón por la que Seconds_Behind_Source = 0 es una compuerta dura y no una sugerencia. La reversión es sin pérdidas solo si congelas los writes en la fuente y dejas que la réplica drene a cero antes de hacer el corte.

Callejón sin salida 3: qué rompe de verdad la réplica

Esperaba que los writes divergentes en el objetivo rompieran la replicación ruidosamente. No lo hicieron. Las read replicas de RDS traen por default slave_exec_mode = IDEMPOTENT, que en silencio hace que la fuente gane un conflicto de primary key en lugar de dar error. Así que un write perdido en el objetivo de reversión se sobreescribe calladito, no se marca.

Lo que sí la rompe es el schema drift. Tiré una columna en el objetivo, luego escribí una fila en la fuente que usaba esa columna. El aplicador de SQL se detuvo en seco:

Last_SQL_Errno: 13146
Replica_SQL_Running: No

La réplica se congeló y se quedó atrás en silencio, todavía reportando un hilo de IO sano. La conclusión operativa: alarma sobre que Replica_SQL_Running voltee a No, no solo sobre el lag. Y durante la ventana de standby caliente, trata el objetivo como estrictamente solo lectura y congela el DDL en la fuente.

Callejón sin salida 4: el conteo de argumentos que los docs implican está mal

La variante GTID es la que quieres en producción, porque sobrevive a un failover de Aurora. Al configurarla, el stored procedure rechazó mi llamada:

ERROR 1318 (42000): Incorrect number of arguments for PROCEDURE
mysql.rds_set_external_master_with_auto_position; expected 6, got 5

El procedimiento toma seis argumentos: host, port, user, password,
ssl_encryption, y delay. Leyendo ejemplos que omiten el delay final, es fácil pasar cinco. Trampa relacionada: el tunable se llama gtid-mode con guion en el parameter group, mientras que gtid_mode con guion bajo es una vista de runtime de solo-lectura que rechaza modificaciones.

Callejón sin salida 5: la edición del parameter group que se aplicó a medias

Esta costó el más tiempo y produjo el síntoma más confuso. Después de
habilitar GTID, la replicación no arrancaba:

Got fatal error 1236 from source when reading data from binary log:
'Binary log is not open'

En Aurora, @@gtid_mode era ON, pero @@log_bin era 0. El binary logging estaba apagado, así que no había nada que replicar. La causa: había puesto binlog_format=ROW y dos parámetros de GTID en una sola edición del parameter group, y uno de los nombres de parámetro estaba mal. Un modify de parameter group es todo o nada. Toda la edición se rechazó, lo que en silencio dejó binlog_format en su default OFF. Los parámetros de GTID, puestos en una llamada posterior exitosa, estaban bien, que es por lo que el
estado se veía a medio arreglar.

El arreglo: pon binlog_format=ROW, reinicia el writer de Aurora, y
verifica @@log_bin = 1 y un SHOW MASTER STATUS no vacío antes de cablear la réplica. Aurora necesita el reinicio para de verdad abrir el binary log.

Una vez que eso quedó bien, el auto-posicionamiento de GTID funcionó de principio a fin:

Auto_Position: 1
Replica_IO_Running: Yes
Replica_SQL_Running: Yes
Seconds_Behind_Source: 0
Retrieved_Gtid_Set: <aurora-uuid>:1-3

La segunda ruta: AWS DMS

El binlog nativo es la ruta recomendada, pero AWS DMS vale la pena conocerlo porque es casi por completo manejado por consola. Corrí una tarea de full load más CDC de Aurora a una segunda instancia de RDS. Funcionó, y es rápido:

Métrica	Resultado
Full load, 2 tablas, 274 MB	20.2 s (como 48 GB/h en la instancia más chica)
CDC, un solo insert	propagado en menos de 12 s

Pero DMS tiene un hueco que el binlog no. Creé una tabla en Aurora (se replicó bien), luego la tiré:

Aurora: tabla ida.
Objetivo de DMS: tabla todavía ahí.

El CDC de DMS no replica DROP TABLE ni RENAME TABLE, e ignora unos cuantos ALTER. Sobre una ventana de reversión larga eso es schema drift silencioso. Usa DMS si quieres el flujo de consola y puedes vivir con la restricción; usa binlog si quieres que el DDL venga incluido.

Los números, y por qué el tamaño deja de importar

El punto de todo el ejercicio es que el tiempo de reversión se desacopla del tamaño de la base de datos. Dos tablas cuentan la historia. La primera es la ejecución de la reversión cuando la réplica caliente se mantiene corriendo:

Tamaño de la BD	Tiempo de reversión (réplica caliente)
1 GB	~1 a 2 min
100 GB	~1 a 3 min
1 TB	~1 a 5 min
100 TB	~1 a 5 min

Constante. La única variable es cuánto delta se apiló durante el incidente, y una instancia de clase producción drena eso a como 1 a 2 GB por minuto, así que hasta un backlog gordo de 10 GB se limpia en minutos de un solo dígito.

La segunda tabla es lo que pasa si no mantuviste la réplica caliente y tienes que reconstruir el fallback desde cero. Este es el camino a evitar:

Tamaño de la BD	Reconstruir vía DMS paralelo (~0.9 TB/h)	Reconstruir vía dump + restore (~60 GB/h)
100 GB	~7 min	~1.7 h
1 TB	~1.1 h	~17 h
100 TB	~4 a 5 días	inviable

A 100 TB la diferencia es minutos contra días. Ese es todo el argumento para mantener la vieja instancia caliente.

Un ancla medida para los números de reconstrucción: en una instancia de clase producción (32 vCPU, 256 GB) un insert lógico de un solo hilo corrió a como 1.2 GB por minuto, o 72 GB/h. El apply de binlog basado en filas y el restore lógico son del mismo orden de magnitud, que es sobre lo que están construidos los estimados de arriba. Las mediciones de instancia chica (un par de MB/s de apply de binlog, como 48 GB/h de full load de DMS) son pisos conservadores que escalan hacia arriba con el tamaño de la instancia.

La trampa del standby frío vacío

Un punto medio tentador es mantener una instancia de RDS aprovisionada y corriendo pero vacía, lista para llenarse bajo demanda. Suena ahorrador. Es lo peor de los dos mundos.

Una instancia vacía e inactiva cuesta lo mismo por hora que una réplica caliente, porque pagas por el cómputo, no por los datos. Pero una instancia vacía no tiene línea base, así que revertir significa cargar la base de datos entera en ella primero. Ese es el camino de reconstrucción lineal con el tamaño: minutos a 100 GB, días a 100 TB. Pagas precio completo de standby por la velocidad de reversión de no tener nada. Peor, estarías recargando desde Aurora, la base de datos de la que estás tratando de escapar, así que si el gatillo fue corrupción la copias fielmente.

Si estás pagando por mantener una caja corriendo como objetivo de reversión, mantenla caliente. Si de plano no puedes, la opción honesta es ningún standby y una reversión aceptada de varios días con pérdida alta, no una caja vacía que cuesta lo mismo que la buena opción.

El manual de operaciones

Todo el asunto en una oración: la vieja instancia de RDS es una copia viva que ha estado tragándose cada write de Aurora desde el corte, así que revertir es detener Aurora, dejar que RDS termine los últimos writes, cambiar el endpoint.

Configúralo una vez, cuando promuevas Aurora:

Agarra la coordenada de binlog de Aurora en el instante en que la app empieza a escribirle (SHOW MASTER STATUS).
Apunta RDS a Aurora desde esa coordenada (mysql.rds_set_external_master o la variante de auto-posición de GTID) y arranca la replicación.
Confirma Replica_IO_Running: Yes y Replica_SQL_Running: Yes. Déjala corriendo. Alarma sobre que el hilo de SQL se detenga. No le escribas a RDS y no cambies el schema en Aurora mientras corre.

Revierte, cuando lo decidas:

Detén que la app le escriba a Aurora.
SET GLOBAL read_only = ON en Aurora, para que nada se cuele.
Observa RDS hasta Seconds_Behind_Source = 0 con los dos hilos en Yes. Esta es la compuerta. Significa que RDS ahora tiene cada write de la era Aurora. Si un hilo dice No, párate y escala, no hagas el corte.
mysql.rds_stop_replication y luego mysql.rds_reset_external_master en RDS.
SET GLOBAL read_only = OFF en RDS.
Apunta el endpoint de la app a RDS. Vuélvela a levantar.

No hay deshacer después del paso 4. Una vez que el enlace se corta y RDS es escribible, las dos bases de datos son independientes. Que es exactamente por lo que el paso 3 no es opcional: es la garantía de que te estás llevando todos los datos de vuelta contigo.

Sesiones remotas siempre disponibles para tus agentes de codigo

Franchesco Romero — Sat, 25 Jul 2026 19:19:33 +0000

Una sesión de agente que sobrevive a cerrar la laptop, corriendo en una sola instancia EC2 chica que manejas desde el teléfono. Este post cubre tanto Claude Code como Kiro CLI, porque resuelven el problema de "alcanzar la sesión desde otro lado" de maneras completamente distintas, y esa diferencia decide la mayor parte de tu arquitectura.

TL;DR

	Versión ingenua	Después
Las credenciales viven en	el volumen raíz de la instancia	Secrets Manager
Sobrevive al reemplazo de la instancia	no, re-login manual	sí, sin atender (~2 min)
Tiempo para notar una caja muerta	6 días (a mano)	15 min (alarma)
Clone fallido al arrancar	tragado por `\	\
Ciclo de vida acoplado a	el stack de producción	su propio stack

El costo es una instancia ARM on-demand chica más un volumen gp3 de 30 GB: revisa el precio de lista actual de tu región, pero es la parte más barata de todo esto.

Una instancia chica siempre encendida lo resuelve, con dos condiciones:
puedes alcanzar la sesión desde donde estés, y la caja regresa por su
cuenta cuando la infraestructura se mueve por debajo de ella. La segunda es de lo que este post trata en realidad.

Los dos modelos remotos

Esta es la bifurcación del camino, así que hazla bien antes de construir nada.

Claude Code tiene una sesión remota de primera mano. {% raw %}claude remote-control registra la sesión en curso con un punto de encuentro
hospedado, y la manejas desde claude.ai/code o la app móvil. La caja hace una conexión de salida nada más:

claude remote-control --name myapp-cloud --continue

--continue reanuda la misma sesión a través de reinicios del proceso, así que un enlace en marcadores se queda estable cuando el servicio rebota.
Esto necesita un CLI reciente: la caja de este post corría la 2.1.211. Al tener éxito imprime:

Take this session with you and pick up right where you left off on any device.
Open the Code tab in the Claude mobile app, or visit claude.ai/code in a browser.
The session keeps running on this machine. Use your other devices as a remote control. Press Ctrl+C to stop.

La consecuencia de seguridad es grande: sin puertos de entrada, sin SSH, sin listener público. El security group puede ser solo de salida.

Kiro CLI no tiene equivalente. Sus docs describen dos modos, ninguno de los cuales es una sesión remota:

Headless, para CI: kiro-cli chat --no-interactive "prompt", autenticado por KIRO_API_KEY. Los docs son explícitos en que "No es posible input del usuario a media sesión": un solo prompt, de principio a fin, sin reanudar.
Interactivo con persistencia local: las sesiones se auto-guardan por directorio y regresan con kiro-cli chat --resume (también --resume-picker, --resume-id <ID>, --list-sessions).

Así que para Kiro la sesión siempre encendida es algo que tú construyes:
mantén el proceso vivo en un multiplexor de terminal, y conéctate a él por SSM.

# en la caja, como el usuario de la app
tmux new-session -d -s agent 'kiro-cli chat'

# desde donde sea
aws ssm start-session --target "$INSTANCE_ID"
sudo -iu appuser tmux attach -t agent

--resume es la red de seguridad más que el mecanismo: si el proceso se muere, la conversación sigue en disco, indexada por el directorio de trabajo.

Lectura práctica: en un teléfono, Claude Code gana de calle, una pestaña de navegador le gana a un shell de SSM móvil conectándose a tmux. El modelo de Kiro le queda mejor a una laptop o tablet con una terminal de verdad. El resto de este post aplica a los dos, porque las partes difíciles (credenciales, recuperación, monitoreo) son idénticas.

Construir el lado de Claude Code

Una unidad de systemd, y el proceso mismo es la sesión. Como la conexión es de salida, no se requiere nada más.

ExecStart=/home/appuser/.local/bin/claude remote-control --name myapp-cloud --continue
Restart=always
RestartSec=30

La salud es lo que sea que diga systemd: systemctl is-active. Esa es toda la integración.

Construir el lado de Kiro

Kiro necesita que lo durable sea la terminal, no el proceso del agente, porque no hay sesión que re-registrar. Corre tmux bajo systemd y deja que el agente viva adentro:

[Unit]
Description=Kiro agent session (tmux)
After=network-online.target
Wants=network-online.target
StartLimitIntervalSec=0

[Service]
Type=forking
User=appuser
WorkingDirectory=/home/appuser/myapp
Environment=PATH=/home/appuser/.local/bin:/usr/local/bin:/usr/bin:/bin
ExecStart=/usr/bin/tmux new-session -d -s agent 'kiro-cli chat --resume'
ExecStop=/usr/bin/tmux kill-session -t agent
RemainAfterExit=yes
Restart=always
RestartSec=30

[Install]
WantedBy=multi-user.target

--resume en ExecStart es deliberado: si la caja reinicia, la sesión nueva de tmux se reconecta a la conversación que ya está en disco para ese directorio en lugar de arrancar en frío.

Conéctate desde donde sea por SSM, todavía sin puertos de entrada:

aws ssm start-session --target "$INSTANCE_ID"
sudo -iu appuser tmux attach -t agent

La salud significa algo distinto aquí, y este es el único lugar donde los dos caminos de verdad divergen. systemctl is-active sobre una unidad tmux de tipo forking te dice que tmux está vivo, no que el agente adentro lo esté. Pregúntale a tmux directo:

if sudo -u appuser tmux has-session -t agent 2>/dev/null; then
  PANES=$(sudo -u appuser tmux list-panes -t agent -F '#{pane_dead}' | grep -c '^0$')
  [ "$PANES" -gt 0 ] && heartbeat OK "tmux:$PANES" || fail "tmux session has no live pane"
else
  fail "tmux session missing"
fi

#{pane_dead} es el detalle que vale la pena guardar. Una sesión de tmux cuyo único panel ya salió sigue respondiendo has-session con éxito, así que el chequeo ingenuo reporta sano una sesión con un agente muerto adentro, la misma clase de falso negativo que el timer inerte de más adelante.

La historia de credenciales de Kiro es más simple en un aspecto: la auth headless es una sola API key en KIRO_API_KEY, sin flujo de navegador y sin expiración de sesión, que cae directo en el mismo patrón de Secrets Manager. Vale la pena tenerla en la caja aunque manejes de forma interactiva, porque hace útil la caja para one-shots por script:

kiro-cli chat --no-interactive --trust-all-tools "run the test suite and summarise failures"

Sé deliberado con --trust-all-tools en una máquina sin atender:
auto-aprueba cada tool call. --trust-tools=read,grep es el default más seguro para cualquier cosa agendada.

Si de plano prefieres no construir nada de esto para Kiro, AWS publica una muestra Kiro IDE Remote de un clic que pone el IDE completo en un escritorio remoto alcanzable desde un navegador, con Kiro CLI y el AWS CLI preinstalados. Más pesada que una instancia chica, y un perfil de costo distinto, pero se salta el armado.

El punto de partida, y qué tenía de malo

La caja original era una instancia EC2 definida dentro del stack del
backend de producción. El user-data instalaba el toolchain, clonaba el repo, escribía una unidad de systemd, y la dejaba deshabilitada a propósito: arrancar un agente sin autenticar nada más entra en crash-loop.
Un humano luego se metía por SSM una vez, iniciaba sesión de forma
interactiva, y habilitaba el servicio.

// Dentro del stack del backend de producción. Tres errores separados.
userData.addCommands(
  "sudo -u appuser bash -lc 'curl -fsSL https://example-agent-installer.sh | bash' || true",
  `sudo -u appuser bash -lc 'test -d ~/myapp || git clone https://github.com/acme/myapp.git ~/myapp' || true`,
  // ...archivo de unidad escrito aquí, a propósito sin habilitar...
  "systemctl daemon-reload"
);

Eso funcionó por meses. Luego se movió el AMI.

La instancia usaba MachineImage.fromSsmParameter(...) para seguir la imagen actual de Ubuntu 24.04. Cuando ese parámetro resolvió un AMI más nuevo, CloudFormation vio cambiar el ImageId, lo cual es un reemplazo, no una actualización. Instancia nueva, volumen nuevo, y todo lo del volumen raíz viejo se fue.

El reemplazo arrancó y se veía bien. No lo estaba:

+ sudo -u ubuntu bash -lc 'test -d ~/myapp || git clone https://github.com/acme/myapp.git ~/myapp'
Cloning into '/home/ubuntu/myapp'...
fatal: could not read Username for 'https://github.com': No such device or address
+ true

Un repo privado, clonado sobre https pelón, sin credenciales. || true
se lo tragó, cloud-init reportó un arranque limpio, y la falla era
invisible a menos que alguien leyera el log.

Las consecuencias se encadenaron. Sin repo, el WorkingDirectory de la unidad no existía, así que el servicio no podía arrancar aunque estuviera habilitado. No estaba habilitado, porque eso es un paso manual. Y el login del agente vivía solo en el volumen que se acababa de destruir:

$ systemctl status agent-remote-control
   Loaded: loaded (/etc/systemd/system/agent-remote-control.service; disabled; preset: enabled)
   Active: inactive (dead)

Seis días después alguien fue a usarla.

Tres fallas independientes, una causa raíz: cada camino de recuperación requería un humano, y nada decía que se necesitaba un humano.

Ronda 1: las credenciales van en un almacén de secretos, no en un volumen

Si la caja no puede re-autenticarse sola, cada reemplazo es un outage. Dos secretos, sembrados una vez por cuenta en lugar de por instancia:

/myapp/agent-box-github-token        -> string de token pelón
/myapp/agent-box-agent-credentials   -> blob JSON de credenciales

El script de bootstrap jala los dos, autentica, clona, y habilita el
servicio. Cada paso es idempotente, así que es seguro correrlo en cada arranque y en un timer.

log "1/5 GitHub auth"
if gh auth status >/dev/null 2>&1; then
  log "    already authenticated"
else
  GH_TOKEN_VALUE="$(secret "$GH_SECRET")"
  [ -n "$GH_TOKEN_VALUE" ] || fail "could not read $GH_SECRET"
  printf '%s' "$GH_TOKEN_VALUE" | gh auth login --with-token || fail "gh auth login failed"
  unset GH_TOKEN_VALUE
fi
gh auth setup-git >/dev/null 2>&1 || true

Dos detalles no obvios:

El script no se puede descargar. La jugada obvia es hacerle curl desde el repo en el user-data. Ese repo es privado, y el token que autorizaría la descarga es lo que el script instala. Circular. En su lugar, incrusta el script en el user-data: léelo en tiempo de synth y mételo en base64.
El alcance de IAM es exactamente dos ARNs. La caja obtiene secretsmanager:GetSecretValue sobre sus propios secretos de bootstrap y nada más. No tiene por qué leer el password de la base de datos.

role.addToPolicy(new iam.PolicyStatement({
  sid: "ReadBootstrapSecrets",
  actions: ["secretsmanager:GetSecretValue"],
  resources: [
    `arn:aws:secretsmanager:${region}:${account}:secret:/myapp/agent-box-github-token-*`,
    `arn:aws:secretsmanager:${region}:${account}:secret:/myapp/agent-box-agent-credentials-*`,
  ],
}));

Trampa 1: el blob de credenciales no es solo el token

Restaurar solo el token OAuth producía un servicio que arrancaba y se moría de inmediato:

Error: Unable to determine your organization for Remote Control eligibility. Run `claude auth login` to refresh your account information.

La funcionalidad de remote-control necesita contexto de cuenta, los
identificadores de la cuenta y de la organización, junto con el token.
Incómodamente, en macOS estos viven en dos lugares distintos: el token en el keychain de login, el objeto de cuenta en el propio archivo de config del CLI. Una restauración que lee solo uno de los dos se ve completa y falla en runtime.

Guarda los dos en un secreto y escríbelos a sus dos destinos en la caja:

if sec.get("oauthAccount"):
    d["oauthAccount"] = sec["oauthAccount"]
if sec.get("organizationUuid"):
    d["organizationUuid"] = sec["organizationUuid"]

Trampa 2: el diálogo de trust headless

Un CLI de agente pregunta si debería confiar en un workspace en el primer uso dentro de un directorio. Un servicio de systemd no tiene TTY y no puede contestar, así que entra en crash-loop en el prompt. Pre-configura la bandera:

e = d.setdefault("projects", {}).setdefault(workdir, {})
e["hasTrustDialogAccepted"] = True
e["hasCompletedProjectOnboarding"] = True
d["hasCompletedOnboarding"] = True

En esta es fácil perder una hora, porque el texto del error es sobre trust y no dice nada de TTYs.

Trampa 3: un heredoc se come tu pipe en silencio

La primera versión del paso de contexto de cuenta hacía pipe de un secreto hacia Python mientras también usaba un heredoc para el script:

# ROTO
secret "$CLAUDE_SECRET" | python3 - "$WORKDIR" <<'TPY'
sec = json.load(sys.stdin)

El heredoc es stdin. El pipe se descarta, y Python lee su propio código fuente como el payload JSON:

json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)

Escribe el secreto a un archivo mktemp con umask 077 y pasa la ruta como argumento.

Ronda 2: mantenerlo corriendo

Restart=always maneja el caso fácil: el proceso crasheó, arráncalo de nuevo.

[Unit]
Description=Agent remote-control session
After=network-online.target
Wants=network-online.target
StartLimitIntervalSec=0

[Service]
User=appuser
WorkingDirectory=/home/appuser/myapp
Environment=PATH=/home/appuser/.local/bin:/usr/local/bin:/usr/bin:/bin
ExecStart=/home/appuser/.local/bin/claude remote-control --name myapp-cloud --continue
Restart=always
RestartSec=30

[Install]
WantedBy=multi-user.target

StartLimitIntervalSec=0 importa más de lo que parece. Por default systemd se rinde después de una ráfaga de fallas rápidas y estaciona la unidad en failed permanentemente. En una caja sin atender eso convierte un problema de red pasajero en un outage que dura hasta que alguien se da cuenta, que es justo el modo de falla que estamos diseñando para que no pase.

Pero Restart=always no puede ayudar con los estados que de verdad mataron esta caja: credenciales faltantes, un clone borrado, una unidad dejada deshabilitada. Esos necesitan algo fuera de la unidad. Como el script de bootstrap es idempotente, el watchdog es nada más el bootstrap en un timer:

[Unit]
Description=Watchdog for the agent session

[Timer]
OnBootSec=60
OnCalendar=*:0/5
AccuracySec=30s
Persistent=true

[Install]
WantedBy=timers.target

Trampa 4: `OnUnitActiveSec` en una unidad que nunca ha corrido

El primer timer usaba OnUnitActiveSec=5min. Se instaló limpio, reportó habilitado, y nunca disparó: ese setting es relativo a la última activación de la unidad, y una unidad que nunca ha corrido no tiene siguiente disparo:

NEXT  LEFT  LAST                          PASSED     UNIT
-     -     Wed 2026-07-22 16:43:57 UTC   13ms ago   agent-bootstrap.timer

NEXT es -. Un watchdog que está inerte en silencio es peor que ninguno, porque se lee como cubierto. Usa OnCalendar de reloj de pared en su lugar.

Ronda 3: la parte que de verdad lo habría atrapado

Todo lo de arriba acorta el outage. Nada de eso acorta los seis días, porque una recuperación de la que nunca te enteras es indistinguible de ninguna recuperación.

El watchdog ya corre cada cinco minutos y ya sabe si el servicio está sano.
Haz que lo diga, en voz alta, a algún lugar fuera de la caja:

heartbeat() {
  local status="$1" detail="${2:-}"
  local stream ts
  stream="$(cat /var/lib/cloud/data/instance-id 2>/dev/null || hostname)"
  ts="$(date +%s)000"
  aws logs create-log-stream --region "$REGION" --log-group-name "$LOG_GROUP" \
    --log-stream-name "$stream" >/dev/null 2>&1 || true
  aws logs put-log-events --region "$REGION" --log-group-name "$LOG_GROUP" \
    --log-stream-name "$stream" \
    --log-events "timestamp=$ts,message=AGENT_BOX_HEARTBEAT $status $detail" \
    >/dev/null 2>&1 || log "WARN: heartbeat not delivered"
}

fail() { log "ERROR: $*"; heartbeat DOWN "$*"; exit 1; }

Un metric filter cuenta las líneas sanas, y la alarma dispara ante su
ausencia:

new logs.MetricFilter(this, "HeartbeatMetricFilter", {
  logGroup,
  metricNamespace: "myapp/AgentBox",
  metricName: "RemoteControlHeartbeat",
  filterPattern: logs.FilterPattern.literal('"AGENT_BOX_HEARTBEAT OK"'),
  metricValue: "1",
  defaultValue: 0,
});

new cw.Alarm(this, "RemoteControlDownAlarm", {
  alarmName: "myapp-agent-box-down",
  metric: new cw.Metric({
    namespace: "myapp/AgentBox",
    metricName: "RemoteControlHeartbeat",
    period: cdk.Duration.minutes(15),
    statistic: "Sum",
  }),
  threshold: 1,
  comparisonOperator: cw.ComparisonOperator.LESS_THAN_THRESHOLD,
  evaluationPeriods: 1,
  treatMissingData: cw.TreatMissingData.BREACHING,
}).addAlarmAction(new cwactions.SnsAction(alarmTopic));

treatMissingData: BREACHING es todo el diseño. El instinto es alarmar sobre una línea de error, pero cada modo de falla en este postmortem produjo cero logs: una instancia que nunca arrancó, un rol sin permisos, un watchdog que nunca disparó. La ausencia es la señal. Esta es la única alarma de la cuenta que no debe caer por default en NOT_BREACHING.

Dos detalles de apoyo. El heartbeat dispara también en el camino de falla, así que una corrida rota es tan visible como una sana: la alarma se indexa en la ausencia de OK, no en la presencia de DOWN. Y activating cuenta como sano, ya que es el estado normal por unos segundos después de cualquier reinicio:

STATE="$(systemctl is-active agent-remote-control 2>/dev/null)"
case "$STATE" in
  active|activating) heartbeat OK "$STATE" ;;
  *) fail "service is $STATE" ;;
esac

Cambia por el chequeo de tmux has-session + #{pane_dead} de antes para una caja de Kiro. Todo lo de aguas abajo (log group, metric filter, alarma, topic de SNS) es idéntico, porque la línea de heartbeat es el único contrato entre la caja y la alarma.

Ronda 4: deja de compartir ciclo de vida con producción

La caja original vivía en el stack del backend de producción. Eso es lo que la mató: un parámetro de AMI dentro de ese stack reemplazó la instancia. Cada deploy de producción también la detenía/arrancaba.

Una comodidad de desarrollo no tiene por qué compartir ciclo de vida con producción. Su propio stack, con un lookup de VPC en lugar de un export entre stacks, un export recrearía el acoplamiento que la separación existe para quitar:

export class AgentBoxStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props: Props) {
    super(scope, id, props);

    const vpc = ec2.Vpc.fromLookup(this, "Vpc", { vpcName: "myapp-vpc" });

    const alarmTopic = new sns.Topic(this, "AgentBoxAlerts", {
      topicName: "myapp-agent-box-alerts",
    });
    alarmTopic.addSubscription(new snssub.EmailSubscription("ops@example.com"));

    new AgentBox(this, "AgentBox", {
      appName: "myapp",
      vpc,
      githubRepo: "acme/myapp",
      alarmTopic,
    });
  }
}

Su propio topic de SNS, también. Importar el topic de producción metería el stack de vuelta justo en el grafo de dependencias.

El movimiento destruye y recrea la instancia, y el orden no es opcional si algún recurso tiene un nombre físico fijo. El rol de IAM aquí lo tiene:

npx cdk deploy MyApp-Backend    # borra la caja vieja y su rol de nombre fijo
npx cdk deploy MyApp-AgentBox   # los crea de nuevo

Al revés, el segundo deploy falla por un nombre de rol duplicado.

El resultado

La separación del stack destruyó la instancia y construyó una nueva desde cero, lo que reproduce la falla original exactamente. Esta vez nadie la tocó:

MyApp-AgentBox | 12/13 | CREATE_COMPLETE | AWS::EC2::Instance | AgentBox/Instance
MyApp-AgentBox | 13/13 | CREATE_COMPLETE | AWS::CloudFormation::Stack | MyApp-AgentBox
 ✅  MyApp-AgentBox
✨  Deployment time: 177.81s

Como dos minutos después, sin atender:

[agent-box-bootstrap] 1/5 GitHub auth
[agent-box-bootstrap] 2/5 Repo clone
[agent-box-bootstrap] 3/5 Agent credentials
[agent-box-bootstrap] 4/5 Account context + workspace trust
[agent-box-bootstrap] 5/5 Enabling the always-on service
[agent-box-bootstrap] done (active)
systemd[1]: Finished agent-bootstrap.service.
systemd[1]: agent-bootstrap.service: Consumed 2.954s CPU time, 52.5M memory peak

Y la alarma hizo su trabajo a lo largo de toda la ventana. Durante el hueco del arranque:

Threshold Crossed: no datapoints were received for 1 period and 1 missing
datapoint was treated as [Breaching].    ALARM

luego, por su cuenta, en cuanto aterrizó el primer heartbeat:

Threshold Crossed: 1 datapoint [1.0 (22/07/26 20:40:00)] was not less than
the threshold (1.0).    OK

Una alarma que dispara ante un outage real y se limpia sola sin ayuda es todo el entregable. La recuperación está padre; la alarma es lo que convierte seis días en quince minutos.

Lo que no ayudó

Fijar el AMI. Tentador, ya que el drift del AMI fue el gatillo. Pero solo cierra la única puerta: un reemplazo forzado por un cambio de tipo de instancia o una edición de user-data marcada como reemplazo borra el volumen igual, y heredas una imagen congelada sin parchar. Una vez que la caja se puede reconstruir sola, fijar compra muy poco.
Un volumen de datos persistente para el home. Una opción real, y sobrevive al reemplazo, pero vuelve las credenciales un copo de nieve otra vez. Una caja que se reconstruye desde un almacén de secretos es más fácil de razonar que una que depende de que un volumen sobreviva.
Mover la caja a su propio repo. Considerado y rechazado. La falla era clonar un repo privado sin credenciales; un repo separado no cambia eso, porque la caja de todos modos tiene que clonar el privado. Stack separado, mismo repo, esa fue la separación útil.

Lecciones

Diseña la alarma antes que la recuperación. Un auto-arreglo del que nunca te enteras es infalsificable. Los seis días no los causó un camino de reparación faltante; los causó una señal faltante.
Alarma sobre la ausencia, no sobre errores. La infraestructura muerta es callada. Cualquier monitor construido sobre hacer match a un string de error es ciego a las fallas totales que más importan.
|| true es una decisión de nunca enterarte. Va solo en pasos de verdad opcionales. En cualquier cosa de carga estructural convierte una falla ruidosa en una silenciosa, y un reporte de arranque limpio desde una máquina muerta es lo que hace que un outage dure días en lugar de minutos.
Las credenciales en el volumen de una instancia son un outage esperando un gatillo. Todo lo que pueda ser reemplazado, lo será. Pon las credenciales donde un reemplazo las pueda alcanzar.
Sabe cuáles cambios de config son reemplazos. Una edición de user-data es un detener/actualizar/arrancar sobre el mismo volumen; un cambio de ImageId lo destruye. La misma superficie de diff, un radio de impacto salvajemente distinto: lee el plan antes de desplegar.
La infraestructura de conveniencia no va en el stack de producción. No por costo, no por orden, por radio de impacto. Fue un deploy de producción el que destruyó la caja.
Un watchdog que nunca ha disparado no es un watchdog. Revisa el NEXT del timer. El monitoreo inerte es peor que ninguno, porque se cuenta como cobertura.

elchesco / blog-always-on-agent-box-code

Companion code — "Six days of silence: an always-on agent box for Claude Code and Kiro"

Reading order

Folder	Blog section	What is in it
`00-starting-point/`	The starting point, and what was wrong with it	The naive user-data, with the three mistakes intact
`01-bootstrap-from-secrets/`	Round 1	The idempotent bootstrap script + its IAM scope
`02-keep-it-running/`	Round 2	systemd units — Claude path, Kiro path, watchdog timer
`03-heartbeat-and-alarm/`	Round 3	Heartbeat emitter, both health checks, metric filter + alarm
`04-own-stack/`	Round 4	The isolated CDK stack
`05-dead-ends/`	Traps 3 and 4	Kept deliberately, with an explanation of why they fail
`06-final/`	The result	Cumulative final state of the script and the construct

Which agent path to use

The two agents differ only in what keeps the session alive and how you check its health. Everything else — secrets, bootstrap, watchdog, heartbeat, alarm, stack — is shared.

Claude Code	Kiro CLI
Remote

…

View on GitHub

Resolviendo los 404 de Google Search Console

Franchesco Romero — Sun, 19 Jul 2026 21:30:19 +0000

Tres semanas después de publicar un sitemap dinámico que orgullosamente listaba cada perfil de miembro, Google Search Console me dijo que esos perfiles eran un error. No con un error de plano, sino con dos veredictos más callados: Soft 404 y Duplicada sin canónica seleccionada por el usuario.

Esta es la historia de leer ese reporte, separar el ruido de la
única señal real, y el arreglo, que fue quitar páginas del índice, no agregarlas.

TL;DR

El reporte "Por qué las páginas no se indexan" de Google es ~80% benigno por diseño. Aprende a triarlo o vas a perseguir fantasmas.
Mis perfiles de miembros salieron marcados como Soft 404 (uno) y Duplicada sin canónica seleccionada por el usuario (otro). La misma causa raíz: el perfil público anónimo es deliberadamente flaco, un esqueleto con el username, todo lo demás es PII oculta a quien no ha iniciado sesión. Flaco + casi idéntico entre usuarios se lee como "página vacía" y "clúster de duplicados".
No puedes arreglar un Soft 404 enriqueciendo una página que por contrato no tienes permitido enriquecer. Así que el arreglo es noindex,follow en la captura, más sacar las URLs del sitemap (un sitemap que lista una URL noindex es una autocontradicción que Google va a señalar).
El modelo mental en una línea: una página que a propósito no tiene contenido para los visitantes anónimos no tiene nada que hacer en un índice construido para visitantes anónimos.

El reporte que lo empezó todo

El reporte de cobertura del índice, ordenado por número de páginas:

Razón	Fuente	Páginas
Descubierta, actualmente sin indexar	Sistemas de Google	55
Duplicada sin canónica seleccionada por el usuario	Sitio web	9
Página alternativa con etiqueta canónica correcta	Sitio web	3
Página con redirección	Sitio web	2
Rastreada, actualmente sin indexar	Sistemas de Google	2
Soft 404	Sitio web	1
Excluida por etiqueta 'noindex'	Sitio web	1
No encontrada (404)	Sitio web	1
Bloqueada por acceso prohibido (403)	Sitio web	1

Noventa y tantas URLs "sin indexar". El instinto es entrar en pánico. La primera jugada correcta es acomodar cada renglón en benigno-por-diseño o señal-real, porque la mayor parte de esta lista es Google trabajando exactamente como se pretende.

Triaje: qué ignorar

Antes de tocar código, clasifiqué cada renglón. La mayoría no necesitaba acción:

Página con redirección (2): http:// → https:// y www. → apex. Eso es canonicalización funcionando. Google me está diciendo que siguió la redirección e indexó el destino. Nada que arreglar.
Excluida por etiqueta 'noindex' (1): la página de reset de contraseña. Ese noindex lo pusimos a propósito. Una palomita verde vestida de advertencia.
No encontrada 404 (1): la raíz del origen de la API (el host api.). No tiene homepage; no debería indexarse. Un rastreador encontró un enlace a ella una vez. Inofensivo.
Bloqueada 403 (1): una URL detrás de auth que regresa 403 a los rastreadores sin sesión. Correcto.
Descubierta / Rastreada, actualmente sin indexar (57): el número grande y aterrador, y el más benigno de todos. Estas son las decisiones de crawl budget de Google mismo ("conocemos esta URL, no hemos priorizado indexarla"). No las arreglas directo; se resuelven conforme el sitio se gana la prioridad de rastreo a través de contenido y enlaces. Tratarlas como bugs es el clásico hoyo de conejo de Search Console.

Eso deja los únicos renglones que describen mis páginas portándose mal:
Duplicada sin canónica seleccionada por el usuario (9 + un 3
relacionado) y Soft 404 (1). Los dos, resultó, eran los mismos dos tipos de página.

Señal 1: las páginas de tag del blog (una falsa alarma, verificada)

Nueve de las URLs "Duplicada sin canónica" eran filtros de tag del blog: /blog?tag=TechCareers, /blog?tag=CloudComputing, y así. Las tres "Página alternativa con canónica correcta" tenían la misma forma
(/blog?tag=gestión, …).

El reflejo es "¡agrega etiquetas canónicas!". Pero revisé primero el
componente PageMeta, y ya hacía lo correcto:

function resolveCanonical(canonical?: string): string {
  if (canonical) return canonical;
  if (typeof window === "undefined") return SITE_URL;
  const { origin, pathname } = window.location;
  return `${origin}${pathname}`;          // nota: pathname, sin query string
}

La canónica se construye desde origin + pathname: el query string se descarta. Así que cada /blog?tag=X se auto-reporta con canónica /blog. Ese es el estado final buscado: los filtros de tag son vistas flacas y duplicativas que no deberían indexarse por separado; deberían consolidarse en /blog. La división 9-contra-3 es nada más Google a media reclasificación: algunas URLs ya se habían asentado en "página alternativa
con canónica correcta" (la cubeta deseada), el resto seguía en la cubeta genérica de duplicados de camino para allá.

Lección: antes de "arreglar" una advertencia de canónica, confirma qué canónica emite la página en realidad. La mitad de estas advertencias son Google reportando un estado transitorio de algo que ya hiciste bien. Cerré esta como funcionando-como-se-diseñó y seguí adelante.

Señal 2: los perfiles (el bug real)

Las dos URLs restantes eran perfiles de miembros:

/profile/rafael-ortiz → Soft 404
/profile/hectorC → Duplicada sin canónica seleccionada por el usuario

Un Soft 404 significa que la página regresa HTTP 200 pero parece un
no-encontrado: vacía, flaca, o de relleno. Para ver por qué Google lo
pensó, aquí está el cuerpo rastreable entero de la captura de un perfil:

body = (
    '<section class="mx-auto max-w-3xl py-8">'
    f"<h1>@{escape(username)}</h1>"
    f'<p class="text-xs text-white/50">{escape(meta_bits)}</p>'   # rol · miembro-desde
    '<p><a href="/">MEMBER COMMUNITY: tech community</a></p>'
    "</section>"
)

Un username, una etiqueta de rol, una fecha de ingreso, un enlace a home.
Eso es todo, y es deliberadamente eso. El perfil público que se le
muestra a un visitante sin sesión está anonimizado por privacidad: nombre real, bio, avatar, especialidad, país, enlaces, posts recientes son todos PII, ocultos para viewer=None. La captura pre-renderizada se construye justo desde esa vista anónima, a propósito, para que el rastreador nunca pueda exponer más de lo que ve un humano sin sesión.

Ahora los dos veredictos tienen sentido como una sola causa raíz:

Soft 404: la página es tan flaca que Google decide que no hay contenido real. A rafael-ortiz le tocó cruzar el umbral.
Duplicada sin canónica: quítale el username y cada captura de perfil es byte por byte el mismo esqueleto. Google agrupa las páginas casi idénticas y elige una representante; al resto le cae el veredicto de duplicada. A hectorC le tocó el palito corto.

Por qué los arreglos obvios están los dos mal

"Enriquece la página para que no sea flaca." No se puede. La flacura es una garantía de privacidad, no un descuido. Agregarle bio/avatar/posts a la captura filtraría PII a un HTML que los rastreadores sin sesión (y quien sea que vea el código fuente) pueden leer. La regla, la captura nunca expone más de lo que ve un humano sin sesión, es de carga estructural.

"Pon una canónica para que los duplicados se consoliden." Una canónica apunta los duplicados a una página representante. Pero no hay perfil representante: cada uno es una persona distinta con contenido (oculto) distinto. Y consolidar no tocaría el Soft 404. La canónica es la herramienta equivocada.

Así que ninguno de los dos arreglos orientados a indexar aplica. Lo que fuerza una pregunta más honesta: ¿estas páginas pertenecen a un índice de búsqueda siquiera? Una página que a un visitante anónimo le muestra nada más @username y un rol no tiene por qué rankear. Indexarla es puro ruido:
reportes de Soft 404, clústeres de duplicados, y crawl budget gastado
re-jalando esqueletos (alimentando esa pila de 55 URLs "Descubierta, sin indexar").

La respuesta es no. Sírvele la página a los humanos y a los desplegadores de enlaces en redes; dile a los rastreadores que no la indexen.

El arreglo: `noindex,follow`, y la contradicción del sitemap

Tres cambios.

1. Enséñale al core del pre-render a sobreescribir robots. El embudo compartido render_into_shell parcha el <head> del shell. Le di un argumento opcional robots que reemplaza quirúrgicamente el
<meta name="robots"> por default del shell:

if robots is not None:
    out = re.sub(
        r'<meta name="robots" content="[^"]*" />',
        f'<meta name="robots" content="{escape(robots)}" />',
        out,
        count=1,
    )

Default None → sin tocar, así que las capturas de blog / reportes /
eventos mantienen su index,follow. Solo los callers que se apuntan
cambian de comportamiento.

2. Apunta el adaptador de perfil.

return render_into_shell(
    shell_html,
    title=title,
    description=description,
    canonical=canonical,
    body_html=body,
    jsonld=_person_jsonld(profile, canonical),
    og_type="profile",
    robots="noindex,follow",
)

¿Por qué noindex,**follow** y no noindex,nofollow? Porque la página todavía enlaza hacia afuera (a home, y con el tiempo a contenido indexable). follow deja que el link equity fluya a través del perfil aunque el perfil mismo no se indexe. nofollow lo dejaría varado. La distinción importa: noindex es sobre esta página; follow es sobre las páginas a las que apunta.

3. Quita los perfiles del sitemap. Este es el paso que la gente se salta. Un sitemap es una lista de "por favor indexa estas". Un meta noindex es "por favor no indexes esta". Si una URL aparece en las dos, le entregaste a Google una contradicción, y va a sacar una advertencia nueva:

URL enviada marcada como 'noindex'. Acabas de cambiar dos advertencias por una nueva.

Así que el endpoint del sitemap de perfiles, y su entrada en el índice de sitemaps, salieron por completo:

<!--
  Sin sitemap-profiles.xml: las capturas de perfil anónimas son noindex,follow
  (esqueletos flacos de solo-username, PII oculta por diseño → Soft 404 / duplicada
  en GSC). Listarlas aquí chocaría con el meta noindex.
-->

La ironía no se me escapa: la pasada de SEO anterior agregó ese sitemap de perfiles. Me tomó tres semanas de datos de rastreo reales aprender que publicar un sitemap para páginas que un rastreador no debería querer era el instinto equivocado. Search Console es un maestro lento pero honesto.

Pruebas de regresión

Dos afirmaciones fijan el comportamiento. Primero, la captura voltea robots:

def test_profile_snapshot_is_noindex():
    html = render_profile_page(_anon_profile(), SHELL)
    assert '<meta name="robots" content="noindex,follow" />' in html
    assert '<meta name="robots" content="index, follow" />' not in html

Segundo, el endpoint del sitemap ya no existe (para que nunca pueda
derivar de vuelta en silencio a contradecir el meta):

async def test_sitemap_profiles_removed(client):
    resp = await client.get("/sitemap-profiles.xml")
    assert resp.status_code == 404

El fixture del shell de la prueba de noindex necesita la etiqueta
<meta name="robots"> real que carga el index.html de producción, algo fácil de olvidar, y sin ella el reemplazo de regex es un no-op silencioso que pasa por la razón equivocada.

Qué medir después

noindex es una señal, no un switch. Después de desplegar, vuelve a
renderizar las capturas vivas para que de verdad carguen el meta nuevo, luego en Search Console:

Validar corrección tanto en el item de Soft 404 como en el de Duplicada. Esto le dice a Google que re-rastree el conjunto afectado.
Observa los perfiles migrar a Excluida por etiqueta 'noindex': ese es el estado de éxito aquí, no un problema nuevo. Significa que Google vio el meta y obedeció.
Confirma que el conteo de "Descubierta, actualmente sin indexar" va bajando conforme el crawl budget deja de gastarse re-jalando esqueletos.

Espera semanas, no horas. Los cambios de cobertura del índice se propagan en la agenda de Google.

La conclusión

El reporte de índice de Google mezcla "tu
página está rota" con "Google trabaja como se pretende" con "Google todavía no llega a ella", y se ven casi idénticos. Acomodar cada renglón en benigno contra señal antes de abrir un editor me salvó de "arreglar" etiquetas canónicas que ya estaban correctas.

No toda página quiere estar indexada. Una página construida para
mostrarle nada a los visitantes anónimos no tiene por qué rankear, y
forzarla a un índice produce exactamente el ruido de Soft-404-y-duplicada que esperarías. La jugada madura de SEO a veces es sacar páginas fuera: noindex,follow en la página, y fuera del sitemap, juntos, para que las dos señales concuerden.

Alarmas que despiertan por causa real, no por un número random

Franchesco Romero — Sun, 19 Jul 2026 20:17:34 +0000

El escenario es un trabajo en segundo plano en una plataforma de
comunidad: un matcher nocturno que empareja items nuevos contra un pool de usuarios elegibles y escribe filas a una tabla matches. Pero la lección es general: cualquier alarma sobre un conteo de salida (items emparejados, correos enviados, registros procesados, recomendaciones generadas) tiene el mismo fallo.

elchesco / blog-cause-aware-alarms-code

Code companion — alarms that page on cause, not on a number

00-output-threshold-alarm/   the naive version: emitter + alarm that page on a COUNT
01-diagnose/                 read-only SQL that falsifies the alarm's hypothesis
02-instrument-the-emitter/   the pure classifier + the instrumented job
03-cause-aware-alarm/        same threshold, cause-accurate line + a benign metric
04-test-the-gate/            test the classification, not the plumbing

Reading order

00-output-threshold-alarm/ — what pages on a coincidence. Note the 3/3 streak hedge: a workaround for an ambiguous metric, not a fix.
01-diagnose/funnel.sql — before touching a threshold, confirm the alarm caught its stated failure. Here it hadn't: input + similarities were healthy; the pool was quota-capped.
02-instrument-the-emitter/ — move the intelligence to the emitter classify.py is the whole idea in one pure function; matcher.py shows the two counters that feed it.
03-cause-aware-alarm/ — the threshold is UNCHANGED. Only the log line got smarter. Plus an unalarmed metric for the benign nights.
04-test-the-gate/…

View on GitHub

TL;DR

	Alarma por umbral de salida	Alarma consciente de la causa
Qué vigila	"¿el conteo llegó a 0?"	"¿el conteo llegó a 0 por una razón rota?"
Dónde vive la lógica	el umbral en el CDK	el emisor (el trabajo mismo)
Despertadas falsas	cada mes, en agenda	ninguna observada
Noches-0 benignas	indistinguibles de una falla	registradas como una métrica aparte, sin alarma
Arreglo cuando dispara en falso	subir el umbral → quedar ciego	ya está correcto
Costo nuevo de AWS	$0 (derivado de logs)	$0 (derivado de logs)

Tres ideas hacen el trabajo:

Una alarma por conteo de salida confunde causas. count == 0 puede significar "roto" o "correctamente callado". Un solo umbral no los distingue.
Diagnostica antes de ajustar. Cuando una alarma dispara, primero pregunta si atrapó la falla que dice atrapar. Razona desde los datos, no desde la descripción de la alarma.
Mueve la inteligencia al emisor. Instrumenta el pipeline para que emita por qué el conteo fue 0. Deja la alarma tonta; haz lista la línea de log.

La trampa: un conteo no es un diagnóstico

La alarma original era una métrica derivada de logs de manual. El trabajo loguea una línea cuando termina con 0 resultados; un metric filter la cuenta; la alarma despierta ante una racha sostenida:

# 00-output-threshold-alarm/emit.py (la versión ingenua)
if scanned_items and created == 0:
    logger.warning("matcher_zero_results", items=len(scanned_items))

// 00-output-threshold-alarm/alarm.ts
new logs.MetricFilter(this, "ZeroResultsFilter", {
  logGroup, filterPattern: logs.FilterPattern.literal('"matcher_zero_results"'),
  metricNamespace: "myapp/Jobs", metricName: "MatcherZeroResults",
  metricValue: "1", defaultValue: 0,
});
new cw.Alarm(this, "ZeroResultsAlarm", {
  metric: zeroResultsMetric, threshold: 1,
  evaluationPeriods: 3, datapointsToAlarm: 3,  // 3 noches seguidas
});

El evaluationPeriods: 3 ya es una cobertura: alguien sabía que una sola noche 0 era varianza normal y exigió una racha antes de despertar. Esa cobertura es la pista. Compra tiempo; no arregla la ambigüedad. Si el conteo puede legítimamente quedarse en 0 por un rato, entonces "3 noches seguidas" no es "roto", es "ya esperamos tres noches". La alarma dispara de todos modos. Nada más te entrenaste a esperar más para la despertada falsa.

El problema real: created == 0 tiene (al menos) dos causas.

Roto. Un umbral o un embedding regresó y nada pasa la barra ya, la clásica falla de "regresa 0 para siempre". Esto debería despertar, fuerte, rápido.
Correctamente callado. El pool elegible es chico y cada candidato que podía emparejar ya lo hizo, o pegó contra una cuota mensual por usuario. El trabajo se está portando perfecto. Esto nunca debería despertar.

Paso 1: diagnostica antes de ajustar

El instinto cuando dispara una alarma "inestable" es subir el umbral o ensanchar la ventana. Resístelo. Primero responde una pregunta: ¿la alarma atrapó lo que dice que atrapó?

La propia descripción de la alarma culpaba a una regresión. Así que revisé las precondiciones de esa regresión directo, desde datos de producción, antes de tocar cualquier cosa:

-- 01-diagnose/funnel.sql: ¿está sano el input? (abreviado)
-- 1. ¿Hay items frescos para emparejar siquiera?
SELECT count(*) FROM items
 WHERE status='ACTIVE' AND embedding IS NOT NULL
   AND created_at > now() - interval '7 days';        -- sano: cientos

-- 2. ¿Los candidatos pasan el piso de similitud? (la barra "regresada")
--    Puntúa el item más nuevo contra el pool elegible.
SELECT max(1 - (u.embedding <=> :item_vec)) AS best_similarity
  FROM eligible_users u;                               -- sano: bien arriba del piso

-- 3. ¿Los usuarios elegibles ya fueron servidos este periodo?
SELECT tier, used, cap, count(*) n
  FROM usage_counters WHERE feature='matcher' AND period=:this_month
 GROUP BY tier, used, cap ORDER BY tier;               -- la respuesta

Los datos contaban una historia clara: input sano, similitudes sanas, y 9 de 11 usuarios servibles ya estaban en su tope mensual. Una ráfaga más temprano en el mes había consumido legítimamente la cuota del pool; las "0 noches" eran el pool sentado en su tope hasta el siguiente reinicio.
Ninguna regresión. La alarma había disparado sobre un sistema correcto.

Este es el paso de carga estructural y el que más fácil se salta. La alarma me entregó una hipótesis ("regresión"); los datos la falsearon. Todo lo que viene después solo vale la pena hacerlo porque me detuve a revisar.

Regla de dedo: la descripción de una alarma es una hipótesis, no un
diagnóstico. El primer trabajo de un humano de guardia (o de un agente)
es confirmar que la alarma atrapó su falla declarada, no silenciar el
síntoma.

Paso 2: nombra la falla con precisión

Antes de escribir código, escribe la oración que la alarma debería
codificar. La mía:

Despierta cuando el trabajo escaneó input real y candidatos elegibles
llegaron a la compuerta final con cuota de sobra, y aun así produjo 0
resultados.

Todo lo que esa oración excluye es, por construcción, un no-incidente:

0 porque ningún candidato llegó a la compuerta final → el pool ya estaba servido o inactivo. Callado.
0 porque cada candidato que llegó a la compuerta estaba bloqueado por cuota → demanda real, correctamente limitada por tasa. Callado.
0 porque candidatos llegaron a la compuerta, tenían cuota, y nada pasó → la barra está rota. Despierta.

Nota que esto es una afirmación sobre los estados internos del pipeline,
no sobre el conteo de salida. Lo que significa que la métrica de salida
nunca lo puede expresar. El emisor tiene que hacerlo.

Paso 3: mueve la inteligencia al emisor

La alarma se queda tonta, un umbral sobre un conteo. Hacemos lista la
línea de log haciendo que el trabajo clasifique su propia corrida de 0 resultados. Dos contadores baratos, acumulados conforme corre el pipeline, capturan la distinción:

# 02-instrument-the-emitter/matcher.py (forma)
class NightlyMatcher:
    def __init__(self, ...):
        self._reached_gate = 0      # candidatos que pasaron los pre-filtros
        self._quota_blocked = 0     # descartados SOLO por el tope por usuario

    async def _process_item(self, item):
        candidates = await self._prefilter(item)     # similitud, dedup, ...
        self._reached_gate += len(candidates)         # llegaron a la compuerta
        created = 0
        for c in candidates:
            if c.score < THRESHOLD:
                continue                              # encaje débil
            if not await self._has_quota(c.user_id):
                self._quota_blocked += 1              # demanda real, en tope
                continue
            await self._create_match(item, c)
            created += 1
        return created

El clasificador es una función pura, trivial de razonar y de probar:

# 02-instrument-the-emitter/classify.py
def classify_zero_result(reached_gate: int, quota_blocked: int) -> str:
    """¿Por qué una corrida que escaneó input real creó 0 resultados?"""
    if reached_gate == 0 or quota_blocked > 0:
        return "quiet"        # pool servido/inactivo, o la demanda pegó el tope
    return "regression"       # candidatos + cuota de sobra, nada pasó

Y la compuerta de emisión enruta a dos eventos de log distintos:

# 02-instrument-the-emitter/emit.py
if scanned_items and created_total == 0:
    if classify_zero_result(self._reached_gate, self._quota_blocked) == "quiet":
        logger.info("matcher_quiet_night",              # solo observ., sin despertar
                    reached_gate=self._reached_gate,
                    quota_blocked=self._quota_blocked)
    else:
        logger.warning("matcher_zero_results",          # la regresión real
                       reached_gate=self._reached_gate)

El metric filter de la alarma no cambia: sigue haciendo match a
"matcher_zero_results". Pero esa línea ahora solo aparece para la falla genuina. En una noche callada el trabajo emite matcher_quiet_night en su lugar, que no hace match al patrón de la alarma, así que la métrica publica su defaultValue de 0 y la racha se rompe. La despertada falsa desapareció no porque subimos un umbral, sino porque el emisor dejó de mentir sobre la causa.

Paso 4: mantén observable el camino benigno

"No despertar" no es "no registrar". Las noches calladas son una señal real: te dicen que el pool servible se está topando, lo cual es un dato de crecimiento, no un incidente. Así que el evento benigno recibe su propia métrica, sin alarma:

// 03-cause-aware-alarm/quiet-metric.ts: visibilidad, no una despertada
new logs.MetricFilter(this, "QuietNightFilter", {
  logGroup, filterPattern: logs.FilterPattern.literal('"matcher_quiet_night"'),
  metricNamespace: "myapp/Jobs", metricName: "MatcherQuietNight",
  metricValue: "1", defaultValue: 0,
});

Ahora el dashboard muestra las dos líneas: regresiones (que despiertan) y noches calladas (que no). Cuando alguien pregunta después "¿por qué cayeron
los matches en la segunda mitad del mes?", la respuesta es una gráfica, no una sesión forense de SQL. Y si las noches calladas suben de manera sostenida, esa es la señal para subir los topes o ensanchar la elegibilidad, una decisión de producto que la alarma vieja sepultaba bajo un incidente falso.

Las lecciones del umbral

No subas el umbral para silenciar una despertada falsa. Es el reflejo, y está al revés. Subirlo (o ensanchar la ventana) hace la alarma más lenta para atrapar la falla real mientras de todos modos termina disparando por la benigna. Cambias un falso negativo por un falso positivo demorado. Arregla la ambigüedad en su lugar; deja el umbral apretado.
Una cobertura en la config de la alarma es un olor. datapointsToAlarm: 3, evaluationPeriods: N, un sospechosamente redondo > 10: cada uno es a menudo un humano dándole la vuelta a una métrica ambigua. A veces es la decisión correcta (un solo throttle está bien; alarma sobre la ráfaga). Pero si la causa es ambigua, ninguna cantidad de contar rachas la resuelve. Pregúntate cuál de las dos tienes.
Alarma sobre la falla, mide el resto. Exactamente una señal debería despertar: el estado por el que despertarías a un humano. Todo lo de al lado, el cero benigno, el parpadeo reintentado, la demanda limitada por tasa, es una métrica sin acción de alarma. Despertar sobre estados ambiguos es como las alarmas terminan silenciadas.

Trampas

Los metric filters literales hacen match a subcadenas. Este me mordió. El FilterPattern.literal('"matcher_zero_results"') de CloudWatch hace match a cualquier evento de log que contenga esa cadena. Nombra el evento benigno matcher_quiet_night, no matcher_zero_results_ok: el segundo contiene el patrón de la alarma como subcadena y la dispararía de todos modos, derrotando en silencio todo el arreglo. Elige un token sin traslape.
defaultValue: 0 es lo que rompe la racha. El filter emite 0 por cada periodo sin línea que haga match. Ese es el mecanismo que le permite a una noche callada "publicar un 0" y reiniciar una alarma de datapoints consecutivos. Sin él, los datapoints faltantes dependen de treatMissingData y la lógica de racha se vuelve turbia. Consérvalo.
Prueba la compuerta, no la plomería. La prueba valiosa no es "¿sirve el metric filter?" (eso es trabajo de AWS). Es "¿el trabajo emite el evento correcto para cada estado interno?". Maneja el emisor y afirma la línea de log:

# 04-test-the-gate/test_emit.py
async def test_pages_only_on_regression():
    m = NightlyMatcher(...)
    m._process_item = fake(reached_gate=+3, quota_blocked=+0, created=0)
    with structlog.testing.capture_logs() as logs:
        await m.run()
    events = [e["event"] for e in logs]
    assert "matcher_zero_results" in events        # regresión → despierta
    assert "matcher_quiet_night" not in events

async def test_quiet_when_quota_capped():
    m = NightlyMatcher(...)
    m._process_item = fake(reached_gate=+3, quota_blocked=+3, created=0)
    with structlog.testing.capture_logs() as logs:
        await m.run()
    events = [e["event"] for e in logs]
    assert "matcher_quiet_night" in events         # demanda en tope → callado
    assert "matcher_zero_results" not in events

Una checklist reutilizable

Cuando una alarma dispara y sospechas que es ruido, antes de tocar un
umbral:

Confirma la falla declarada. ¿Los datos muestran la condición exacta que la alarma dice? Si no, la alarma está mal categorizando: un bug de diseño, no un problema de ajuste.
Enumera las causas del valor de la métrica. 0, 5xx, lento, profundidad de cola: lista cada razón distinta por la que llega al valor de la alarma. Si hay más de una, y difieren en si son incidentes, la métrica es ambigua.
Escribe la falla en una oración. En términos del estado interno del sistema, no de su salida. Si la métrica no puede expresar esa oración, el emisor debe hacerlo.
Mueve la lógica al emisor. Emite una señal distinta por causa. Despierta sobre la del incidente; mide el resto.
Cuida las colisiones de subcadena y el defaultValue. (Ve las trampas.)
Prueba la clasificación, no la alarma. Afirma que el emisor produce el evento correcto para cada estado.

La forma de todo esto

ANTES:  count == 0  ─────────────────────────► alarma ──► despierta (a veces mal)

DESPUÉS:  corrida termina en 0 ─► clasifica(estado interno) ─┬─ "regression" ─► línea warn ─► alarma ─► despierta
                                                             └─ "quiet"      ─► línea info ─► métrica (sin despertar)

Un principio: una alarma debería disparar por una causa, no por una
coincidencia. Cuando un solo valor de salida tiene múltiples causas, no
ajustes el umbral: empuja el diagnóstico río arriba, al código que ya sabe
por qué el número es lo que es, y deja que lo diga en la línea de log. La
alarma se queda como un umbral tonto. La inteligencia vive donde está el
contexto. Y el pager suena solo cuando algo de verdad anda mal.

El día que `pnpm audit` tumbó todos los deploys (y qué correr en su lugar)

Franchesco Romero — Sun, 19 Jul 2026 19:23:46 +0000

Un deploy de frontend falló. No había cambiado código en el pipeline, nose había subido ninguna dependencia, el lockfile era byte por byte
idéntico al del deploy que había pasado en verde 23 horas antes. El falló:

ERR_PNPM_AUDIT_BAD_RESPONSE  The audit endpoint (at
https://registry.npmjs.org/-/npm/v1/security/audits/quick) responded with
410: {"error":"This endpoint is being retired. Use the bulk advisory
endpoint instead."}

npm había retirado el endpoint al que pnpm audit hace POST. Mi compuerta de seguridad ahora estaba fallando por infraestructura, no por vulnerabilidades, y como era una compuerta dura, bloqueaba todos los deploys de frontend que iban detrás, incluyendo un arreglo de bug sin relación que estaba esperando para salir.

elchesco / blog-pnpm-audit-osv-scanner-code

Code companion — replacing a dead `pnpm audit` gate with osv-scanner

Reading order

00-dead-gate/ — what broke. Note it's a network call, not a local scan; when npm retired the endpoint it failed on infrastructure and blocked every deploy.
02-osv-scanner-step/ — scan pnpm-lock.yaml against the OSV DB. No endpoint to retire. But osv-scanner is blunt: it fails on any advisory across the whole lockfile, so we discard its exit code (|| true) and filter ourselves.
03-preserve-semantics/audit-prod-gate.mjs — re-impose the old flags --prod (runtime tree from pnpm ls --prod) and --audit-level high (CVSS ≥ 7 from the OSV report). Dev/build deps report but never block.
04-verify/split.sh — the test that matters: does it block the thing it should and pass the thing it should, on your real tree?

The two principles

A gate that fails on infrastructure is worse than no gate. It blocks good work while…

View on GitHub

TL;DR

	`pnpm audit --prod --audit-level high`	osv-scanner + filtro
Cómo obtiene los datos	POST al endpoint de audit de npm	escanea el lockfile contra la base de datos de OSV
Falla cuando retiran el endpoint	sí, bloquea todos los deploys	no (no hay endpoint)
Solo prod	integrado (`--prod`)	reconstruido desde `pnpm ls --prod`
Umbral de severidad	integrado (`--audit-level`)	reconstruido del CVSS en el reporte
Depende de	que npm mantenga viva una API legada	un binario de escáner versionado + una base de datos pública

Dos ideas:

Una compuerta que falla por infraestructura es peor que no tener compuerta..
No terceerices un chequeo de seguridad a un endpoint de un proveedor. Escanea un artefacto que tú controlas (el lockfile) contra una base de datos. Los endpoints se retiran; tu lockfile no.

Qué era `pnpm audit` en realidad

Parece un escaneo local. No lo es. pnpm audit serializa tu árbol de
dependencias, le hace POST al endpoint de audit del registry, y renderiza los advisories que regresen. El chequeo es una llamada de red a una API específica de npm:

POST https://registry.npmjs.org/-/npm/v1/security/audits/quick

npm deprecó ese endpoint (y su hermano /audits) en favor de una API más nueva de bulk-advisory, y con el tiempo puso los dos en HTTP 410 Gone. Cualquier herramienta que siga llamando al endpoint viejo, incluyendo el pnpm audit de un montón de imágenes de CI fijadas, ahora falla sin condición. No es "no se encontraron vulnerabilidades", no es "se encontraron algunas": es un error duro, en cada corrida.

La compuerta había estado en verde por meses. Nada de mi lado cambió. Un tercero retiró una API y mi pipeline de deploy se puso en rojo.

Los tres arreglos equivocados

Ponle || true. La forma más rápida de desbloquear. También la peor: convertiste una compuerta de seguridad en un comentario. No da ninguna protección y miente en verde para siempre. Si la compuerta no vale la pena arreglarla, bórrala, no dejes una decorativa en la que la gente confía.

Sube la versión de la herramienta. Sospecha razonable: quizá un pnpm más nuevo usa el endpoint nuevo. Lo revisé: tanto la versión fijada como la última le hacen POST al /audits/quick retirado. El endpoint ya no existe para nadie; subir de versión no lo conjura de vuelta. (Puede variar conforme pnpm migre, pero "ojalá la herramienta se haya movido a la API nueva" no es un plan.)

Agrega una lista de ignorados. Cámbiate a un escáner, luego suprime cada hallazgo que salte. Esto invierte la compuerta: ahora bloquea por default y tú justificas las excepciones con la mano, así que cada advisory nuevo, incluyendo el ruido de dev que el viejo flag --prod excluía gratis, se vuelve un triaje manual. La lista de negados crece, y el día que caiga uno real queda sepultado en el mismo movimiento con el que descartas el ruido.

El arreglo correcto mantiene la compuerta con sentido: la misma pregunta, otra fuente de datos.

Qué debería afirmar la compuerta en realidad

Antes de reemplazarla, escribe qué significaban los flags viejos, porque un escáner no los va a reproducir a menos que lo obligues:

pnpm audit --prod --audit-level high
             ▲            ▲
             │            └─ piso de severidad: solo HIGH/CRITICAL.
             │               MEDIUM/LOW se reportan, nunca bloquean.
             └─ alcance: solo dependencias de RUNTIME. Las de dev/build son
                ruidosas (bundlers, frameworks de pruebas, sus árboles
                transitivos) y no llegan a los usuarios.

Ese segundo flag es el que la gente olvida, y es de carga estructural. La mayor parte del ruido de CVEs en un proyecto de frontend vive en el árbol de dev. Un reemplazo que escanee el lockfile entero va a "encontrar más vulnerabilidades" y se va a sentir más minucioso, cuando en realidad nada más bloquea deploys por tooling de build que nunca llega a un usuario.

Preservar --prod no es un lujo: es la diferencia entre una compuerta que la gente respeta y una que rodean.

El reemplazo: escanea el lockfile, no un endpoint

osv-scanner lee pnpm-lock.yaml directo y checa cada paquete contra la base de datos de OSV. Ningún POST a npm, nada que retirar:

# 02-osv-scanner-step/audit.sh (forma)
osv-scanner scan source --lockfile=pnpm-lock.yaml --format=json > osv.json

Pero osv-scanner es tosco a propósito: reporta todos los advisories en toda severidad a lo largo del lockfile entero, y sale con código distinto de cero si encuentra cualquier cosa. Apúntalo a un proyecto real y va a fallar por una dependencia transitiva de solo-dev de baja severidad desde el día uno. Tal cual sale de la caja, es la trampa de "escanear el lockfile entero" de la sección anterior.

Así que no usamos su código de salida. Tomamos su JSON y le volvemos a imponer las dos reglas de la compuerta vieja nosotros mismos.

Preservando `--prod` y `--audit-level high`

Dos insumos, un script chico:

osv-scanner scan source --lockfile=pnpm-lock.yaml --format=json > osv.json || true
pnpm ls --prod --depth Infinity --json > prod.json
node audit-prod-gate.mjs   # sale con 1 solo ante un HIGH/CRITICAL de runtime

El || true en el escaneo: el "distinto de cero ante cualquier advisory" de osv-scanner mataría el paso antes de que corra mi filtro. Quiero sus hallazgos, no su veredicto.
pnpm ls --prod da el árbol de dependencias de runtime, el alcance de --prod, reconstruido. Lo que no esté ahí es de solo dev/build y no puede bloquear.

La compuerta en sí (archivo completo en la carpeta de código):

// 03-preserve-semantics/audit-prod-gate.mjs (núcleo)
const HIGH_CVSS = 7.0; // HIGH empieza en 7.0, CRITICAL en 9.0: los dos bloquean.

const prodNames = new Set();
(function walk(deps) {                       // aplana pnpm ls --prod
  for (const [name, info] of Object.entries(deps ?? {})) {
    prodNames.add(name);
    walk(info.dependencies);
  }
})(prodTree.dependencies);

const blocking = [];
for (const pkg of osv.results.flatMap((r) => r.packages)) {
  if (!prodNames.has(pkg.package.name)) continue;        // solo-dev → salta
  for (const g of pkg.groups ?? []) {                    // uno por advisory
    if (Number.parseFloat(g.max_severity) >= HIGH_CVSS)  // CVSS de OSV
      blocking.push(`${pkg.package.name}@${pkg.package.version} ${g.ids}`);
  }
}
process.exit(blocking.length ? 1 : 0);

groups[].max_severity es el puntaje CVSS que osv-scanner ya calculó: no re derivo la severidad, solo le pongo el umbral. La pertenencia a prod por nombre es conservadora a propósito: si un paquete aparece en cualquier parte del árbol de runtime, trato sus advisories como enviables. Mejor bloquear uno real que dejarlo pasar por un tecnicismo.

Verificar que hace lo correcto

El valor de una compuerta de seguridad está por completo en su
comportamiento en los bordes, así que prueba ambas direcciones contra el lockfile real. La mía encontró 8 advisories:

Total 2 packages affected by 8 known vulnerabilities
(0 Critical, 3 High, 3 Medium, 2 Low)
  undici     7.26.0   3× HIGH (CVSS 7.4–7.5)   ← solo-dev
  protobufjs 7.6.2    1× MEDIUM (CVSS 5.3)      ← runtime

De manera ingenua, "3 vulnerabilidades HIGH" suena a que la compuerta
debería gritar. No debería, y aquí está la prueba de que los dos filtros funcionan:

# 04-verify/split.sh
$ pnpm why undici --prod
   (empty)                         # undici NO está en el árbol de runtime → excluido
$ pnpm why protobufjs --prod
   protobufjs 7.6.2
   └─┬ amazon-chime-sdk-js         # runtime, pero MEDIUM < HIGH → debajo de la compuerta

Así que la compuerta pasa, correctamente. Los tres advisories HIGH están en tooling de build que nunca se envía; el único advisory de runtime está debajo del piso de severidad. Para probar que no solo está por encima, baja el umbral a 5.0 en local: entonces marca el protobufjs de runtime y falla. La compuerta discrimina; no está atorada en abierto.

Esta es la prueba que importa. No "¿corre el escáner?" sino "¿bloquea lo que debe y deja pasar lo que debe?", sobre tu árbol real.

Trampas

Descarta el código de salida del escáner, quédate con sus hallazgos. osv-scanner sale distinto de cero ante cualquier advisory. Si no le pones || true (o configuras lo suyo), falla el paso antes de que corra tu filtro de prod/severidad, y vuelves a bloquear por ruido del árbol de dev.
Fija la versión del escáner. releases/latest puede cambiar la forma de la salida o el comportamiento de falla por default entre corridas, justo la inestabilidad de la que estás tratando de escapar. Fija v2.4.0 (o la que sea), sube de versión a propósito.
Haz la descarga consciente de la arquitectura. Los runners ARM autoalojados y el ubuntu-latest x86 necesitan binarios distintos. case "$(uname -m)" in aarch64|arm64) … le gana a un _amd64 fijo a mano.
Decide qué significa un CVSS ausente. Algunos advisories no traen puntaje CVSS. parseFloat("") es NaN, así que no cruza el umbral y no bloquea. Es una decisión deliberada (empatar con el viejo comportamiento etiquetado por severidad), pero tómala a propósito, y loguea el conteo.
Que pnpm audit parezca local engaña a todos. Es una llamada de red. Trata cualquier "audit" que le llame a un registry como una dependencia de disponibilidad de tu pipeline, no como un chequeo local.

Lo que salté a propósito

Auditar dependencias de dev como compuerta bloqueante. No se envían. Las reporto (osv-scanner imprime las 8) pero solo bloquea un HIGH/CRITICAL de runtime, igual que el viejo --prod.
Subir versiones automático. Renovate/Dependabot es otro ciclo aparte. El trabajo de esta compuerta es detener un deploy malo, no abrir PRs.

La forma de todo esto

ANTES:  árbol de dependencias ─POST─► endpoint de npm audit ──► veredicto ──► compuerta
                                             │
                                        (retirado: 410) ──► compuerta en rojo para siempre

DESPUÉS:  pnpm-lock.yaml ──► osv-scanner ──► hallazgos JSON ─┐
          pnpm ls --prod ──► conjunto de paquetes de runtime ┴─► filtro
                                    (prod ∧ CVSS ≥ 7) ──► compuerta

Un principio, dos mitades. Una compuerta de seguridad debe fallar por
vulnerabilidades, no por el clima, así que escanea un artefacto que tú controlas contra una base de datos, no el endpoint de un proveedor que te puede dar 410 por debajo. Y cuando cambies de herramienta, migra la semántica, no solo el comando: los flags viejos codificaban decisiones reales (solo runtime, solo HIGH/CRITICAL), y un reemplazo que los suelta en silencio no es más minucioso, es una compuerta distinta y más ruidosa que la gente va a aprender a ignorar.

React Doctor marcó 1,249 problemas en una SPA de React. Cinco valían la pena arreglar

Franchesco Romero — Wed, 08 Jul 2026 00:00:04 +0000

React Doctor es un linter de cero instalación que escanea un codebase de React buscando problemas de correctitud, seguridad, accesibilidad,
rendimiento y mantenibilidad, luego los rankea y te entrega una lista de arreglos con forma de agente.

Este post es un reporte de campo: lo corrí sobre una SPA real de React 18 + Vite + TypeScript (~50 rutas, TanStack Query, react-hook-form) y separé lo que de verdad me atrapó.

El resultado honesto: 1,249 hallazgos, cinco que valía la pena arreglar, incluyendo dos bugs de seguridad reales. Los otros 1,244 fueron una mezcla de ruido, decisiones de criterio, y falsos positivos.

TL;DR

Categoría	Reportados	Vale la pena actuar	Por qué la brecha
Seguridad	18 warnings	2	13 eran sinks saneados en el servidor (falsos positivos); 1 mina de código muerto + 1 XSS real fueron el oro
Bugs	24 errores, 487 warnings	2	1 fuga de timer, 1 key/spread; ~27 `exhaustive-deps` piden criterio humano
Accesibilidad	434 warnings, 1 error	1	el 1 error (`aria-selected` faltante) era real; los 434 son ruido de `<Label>`/`<button type>`
Rendimiento	110 warnings	0	nada caliente; candidatos pero sin impacto medido
Mantenibilidad	176 warnings	0	opiniones de estilo tipo "componente grande"
Total	1,249	5	señal-a-ruido ≈ 1 en 250

El puntaje que imprimió: 39 / 100. Dos cosas que ese encuadre esconde: los cinco que sacó a la superficie eran de alto valor (una fuga de token en localStorage y un sink de XSS almacenado), y el conteo no es determinista: una segunda corrida del mismo commit reportó 1,254, no 1,249.

El veredicto en una línea: excelente generador de hipótesis, pésima
compuerta. Úsalo para encontrar candidatos, verifica cada uno contra el código, y nunca conectes el conteo al CI.

Qué es React Doctor

Un solo binario que corres por npx / pnpm dlx, sin agregar dependencia a tu proyecto, sin archivo de configuración obligatorio. Parsea tu src/, hace match contra un conjunto de reglas (sus familias: Seguridad, Bugs, Accesibilidad, Rendimiento, Mantenibilidad), e imprime:

un Top 3 de lo que cree que deberías arreglar primero,
un desglose por categoría con conteos de error/warning,
una advertencia de escala de migración cuando una regla abarca docenas de archivos,
un bloque de guía para agente: la herramienta está diseñada de manera explícita para ser manejada por un agente LLM, no solo leída por un humano.

Esa última parte es el punto. React Doctor no arregla nada. Emite
hipótesis rankeadas y le dice al agente que "lea el código relevante antes de confirmar o suprimir cada hallazgo". Tomada al pie de la letra, esa instrucción es el flujo de trabajo completo.

Cómo correrlo

Sin instalación. Desde la raíz del paquete del frontend:

# Top-3 + resumen por categoría
npx react-doctor

# Cada hallazgo con archivo:línea y la receta de arreglo
npx react-doctor@latest --verbose

# Acotar a un directorio (recomendado para un repo grande)
npx react-doctor@latest src/components

# Solo los archivos que cambiaron vs la rama base (el modo amigable con CI)
npx react-doctor@latest --verbose --scope changed

Si tu toolchain usa pnpm, pnpm dlx react-doctor es el equivalente. La primera corrida baja ~200 paquetes al caché de dlx; las corridas
siguientes son rápidas.

El default (sin flags) es la vista de triaje:

React Doctor v0.7.1

  Top 3 errors you should fix

  ✖ Bugs: Effect subscription or timer never cleaned up
    `setTimeout` creates a timer in useEffect without returning
    cleanup. Return a cleanup function so it does not leak
    after unmount.

    src/components/layout/SearchBar.tsx:114

  ...

  All 1249 issues

  Security › 18 warnings
  Bugs › 24 errors, 487 warnings
  Performance › 110 warnings
  Accessibility › 434 warnings
  Maintainability › 176 warnings

--verbose expande cada regla en cada archivo:línea más una URL de docs con una "receta de chequeo de falso positivo". Lee esa frase como una etiqueta de advertencia: la herramienta sabe que sus hallazgos necesitan triaje.

Los cinco que importaron

1. Un `setTimeout` en `useEffect` sin cleanup (bug real)

Arriba de la lista, y correcto. Un timer de focus creado al abrir, nunca limpiado:

// antes: el timer se fuga si el componente se desmonta dentro de los 50ms
useEffect(() => {
  if (open) {
    setRecentSearches(getRecentSearches());
    setTimeout(() => inputRef.current?.focus(), 50);
  } else {
    setQuery("");
  }
}, [open]);

// después: el cleanup limpia el timer pendiente
useEffect(() => {
  if (!open) {
    setQuery("");
    return;
  }
  setRecentSearches(getRecentSearches());
  const focusTimer = setTimeout(() => inputRef.current?.focus(), 50);
  return () => clearTimeout(focusTimer);
}, [open]);

Radio de impacto bajo (una llamada de focus de 50ms), pero una fuga real y un arreglo trivial. Esta es justo la clase en la que React Doctor es bueno: mecánica, local, verificable.

2. `JSON.stringify` hacia un sink de `<script>`: XSS almacenado (seguridad real)

Este solito justificó todo el ejercicio. El componente de SEO incrustaba JSON-LD de schema.org así:

{jsonLdPayloads.map((payload, i) => (
  <script key={i} type="application/ld+json">
    {JSON.stringify(payload)}
  </script>
))}

JSON.stringify no escapa HTML. Los payloads cargan campos
controlados por el usuario: un nombre de perfil para mostrar, el título de un post de blog. Un nombre de </script><img src=x onerror=alert(1)> se sale del elemento script. Y como estas etiquetas aterrizan en una captura de SEO pre-renderizada que se sirve a rastreadores y en visitas directas, es XSS almacenado, no reflejado.

El arreglo es un serializador que escapa los caracteres que pueden
terminar el elemento o el contexto de string de JS, cada reemplazo una secuencia \uXXXX válida de JSON para que el dato viaje de ida y vuelta sin cambiar:

export function serializeJsonLd(payload: Record<string, unknown>): string {
  return JSON.stringify(payload)
    .replace(/</g, '\\u003c')
    .replace(/>/g, '\\u003e')
    .replace(/&/g, '\\u0026')
    .replace(/\u2028/g, '\\u2028')
    .replace(/\u2029/g, '\\u2029');
}

<script key={i} type="application/ld+json">
  {serializeJsonLd(payload)}
</script>

La etiqueta que la propia React Doctor le puso a esta regla, "Unescaped JSON in HTML or script sink", fue precisa. La herramienta se ganó su lugar con este único hallazgo.

3. Un cliente axios muerto que acumulaba tokens en `localStorage` (seguridad real)

Regla: "Auth token in web storage". Apuntó a src/services/api/client.js:50:

// src/services/api/client.js (desde el primerísimo commit)
const refreshToken = localStorage.getItem('refresh_token')
const { data } = await apiClient.post('/auth/refresh', { refresh_token: refreshToken })
localStorage.setItem('access_token', data.access_token)

Guardar un access token, ya no digamos un refresh token, en localStorage lo expone a cualquier XSS en la página. Esto contradecía de frente el modelo de auth real de la app: access token solo en memoria, refresh vía una cookie HttpOnly, implementado en un archivo distinto (src/lib/axios.ts).

El detalle: este archivo nunca se importaba en ningún lado. Código muerto del scaffold inicial. No una fuga activa, pero un arma cargada. Quien autocompletara el import equivocado de client reintroduciría en silencio la vulnerabilidad exacta que el codebase se construyó para evitar.

Arreglo: bórralo.

grep -rIn "services/api/client" src   # → cero imports. Seguro de quitar.
git rm src/services/api/client.js

React Doctor encontró esto por patrón, no por alcanzabilidad. Que no pueda distinguir "sink vivo" de "mina muerta" es una limitación, pero aquí la mina muerta valía la pena quitarla igual.

4. `role="option"` sin `aria-selected` (a11y real, el único error de a11y)

De 435 hallazgos de accesibilidad, exactamente uno fue error, y estaba bien. Una opción de listbox sin estado de selección expuesto a la tecnología asistiva:

<button
  role="option"
  aria-selected={false}   // ← agregado
  onClick={() => handleSelect(u)}
>

El padre ya cargaba role="listbox"; la opción nada más nunca declaraba su estado. Un atributo.

5. `key` antes de `{...spread}` (menor, en el límite)

// marcado
<TourCard key={card.step} {...card} onCtaClick={...} />
// cambiado a
<TourCard {...card} key={card.step} onCtaClick={...} />

La regla: un spread puede sobrescribir key. En la práctica React extrae key de manera especial y avisa ante un key en el spread, así que el original difícilmente se iba a portar mal. Reordenar es inofensivo y satisface al linter, pero este es el más débil de los cinco: del tipo de hallazgo que arreglas de pasada, no uno por el que abrirías un PR por su cuenta.

Lo que marcó y era ruido

13 sinks de "HTML injection": todos falsos positivos

El grupo de Seguridad más grande, "HTML injection sink with dynamic
content ×13", listó cada dangerouslySetInnerHTML de la app:

  ⚠ Security: HTML injection sink with dynamic content ×13
    HTML is injected from a dynamic-looking source, which can
    become XSS if the value is user-controlled or unsanitized.

    src/components/dm/MessageBody.tsx:25
    src/pages/BlogPostPage.tsx:397
    src/pages/ThreadPage.tsx:523
    ... (10 more)

Cada uno de estos renderiza HTML que ya venía saneado del lado del
servidor (una pasada de nh3/ammonia en el backend), la frontera de confianza documentada de la app para contenido de blog, foro, y escrito por agentes. La herramienta ve el sink; no puede ver que el string llegó pre-saneado desde una API. Verificar el grupo me tomó más que arreglar los dos bugs reales. Los 13: descartados.

Esta es la debilidad de fondo de la herramienta. Un linter estático lee el sink, no el flujo de datos a través de la frontera de red, así que cada dangerouslySetInnerHTML legítimo es un warning que tienes que descartar a mano.

Ruido a escala de migración: `type` ×242, `<Label>` ×329

La propia React Doctor los marca como "muestrea antes de barrer":

  ⚠ Migration-scale change: sample before you sweep
    Button missing explicit type ×242 across 83 files
    Label missing associated control ×329 across 69 files
    Large component is hard to read and change ×62 across 60 files

<button> toma por default type="submit" dentro de un form, así que un type explícito faltante puede morder, pero 242 instancias son un codemod mecánico y un diff de 60 archivos que nadie va a revisar con cuidado. Real, de bajo valor, y peligroso de arreglar en masa de una sola pasada. Buena decisión de la herramienta ponerlos en cuarentena; buena decisión tuya no tocarlos en un PR de arreglo de bugs.

`exhaustive-deps` ×27: necesita un humano cada vez

Aquí la herramienta es inusualmente honesta, imprimiendo anti-guía dentro del hallazgo:

  ⚠ Bugs: Missing effect dependencies ×27
    → Don't blindly add missing dependencies. Read the hook
      callback first.

Una dependencia faltante a veces es un bug y a veces es intencional. No hay arreglo mecánico; cada uno de los 27 es una tarea de lectura de código. Útil como lista para irla trabajando, inútil como "arréglalo todo".

El conteo no es determinista

Dos corridas, el mismo commit, sin ediciones entre ellas:

run 1:  All 1254 issues   Bugs › 26 errors, 489 warnings
run 2:  All 1249 issues   Bugs › 24 errors, 487 warnings

Cinco hallazgos aparecieron y desaparecieron entre corridas idénticas. Eso solo descalifica al número crudo como compuerta de CI: un build que falla ante "issues > N" andaría parpadeando.

Qué sirve, qué no

Sirve	No sirve
Encontrar bugs locales y mecánicos (fugas de timer, cleanup faltante)	Distinguir un sink vivo de código muerto
Nombrar un sink de XSS real con precisión (el acierto del JSON-LD)	Ver el saneado del lado del servidor a través de la frontera de red
Cero instalación, cero configuración, un comando	Producir un número estable y compuertable (conteo no determinista)
Rankear un Top 3 que casi siempre vale la pena leer	Su propio puntaje (`39/100`) como métrica con significado
Emitir guía lista para agente + enlaces de docs por regla	Cualquier cosa que requiera flujo de datos o intención (modelo de auth, frontera de confianza)
Acotar a una ruta o `--scope changed`	Reglas a escala de migración: reales pero irrevisables en bloque

Cómo usarla de verdad

Acótala. La salida de todo el repo son 1,200+ líneas. Corre --verbose --scope changed en un PR, o apúntala a un solo directorio.
Dásela a un agente, no a un humano. La salida está hecha para eso: rankeada, con archivo:línea y una receta de arreglo por regla. Haz que el agente lea cada archivo marcado y etiquete el hallazgo como verdadero positivo / falso positivo / requiere revisión, con evidencia del archivo.
Verifica cada hallazgo de seguridad a mano. Dos de los míos eran reales, trece no, y la proporción era invisible desde el resumen.
Arregla los de alta confianza que preservan el comportamiento; anota el resto. La fuga de timer y el XSS salieron el mismo día. exhaustive-deps y las reglas de escala de migración se volvieron notas de backlog, no diff.
Nunca condiciones el CI al conteo crudo. Parpadea. Condiciona sobre tu subconjunto triado y confirmado si de plano tienes que condicionar algo.
Divide por familia de regla en PRs separados. Los arreglos de seguridad y un barrido de a11y tienen revisores distintos y riesgo distinto. No los amontones.

Lecciones

El costo del triaje es el costo real. Correr la herramienta tomó segundos; descartar 13 banderas de XSS falso positivo tomó más que escribir los dos arreglos reales y sus pruebas. Presupuesta para la verificación, no para el escaneo.
Un linter estático no puede ver tu frontera de confianza. Cada dangerouslySetInnerHTML legítimo alimentado por HTML saneado en el servidor es un falso positivo permanente. Eso no es un bug de la herramienta; es el techo del análisis estático.
El mejor hallazgo estaba en código muerto. El cliente de token en localStorage era inalcanzable, así que no había señal de runtime, ni falla de prueba, ni comentario de revisión que lo hubiera atrapado. El match por patrón encontró lo que un análisis de alcanzabilidad habría despriorizado.
Los nombres de regla precisos construyen confianza; un puntaje resumen la erosiona. "Unescaped JSON in HTML or script sink" era accionable. "39/100" no me dijo nada.
El no-determinismo mata el condicionamiento. Un conteo que cambia entre corridas idénticas puede informar a un humano pero nunca puede tronar un build.
Deja que la herramienta ponga en cuarentena su propio ruido. Su advertencia de "muestrea antes de barrer" fue lo más útil que imprimió: detuvo un PR de ruido de 60 archivos antes de que empezara.

Mover un agente de IA siempre encendido de un VPS de $24 a Fargate Spot

Franchesco Romero — Sun, 05 Jul 2026 00:14:19 +0000

Tienes un agente de IA auto alojado, del tipo que corre 24/7, se conecta a Slack/Telegram/WhatsApp, y sale a un sandbox de Docker a correr código. Vive en un VPS que pagas esté ocupado o inactivo. Esta es una migración paso a paso a AWS Fargate Spot: el mismo agente, ~60% menos, sin VM que parchar, y con el estado preservado.

Funciona para cualquier agente siempre encendido que se pueda contenerizar (OpenClaw, un bot de Discord, un trabajador programado).

elchesco / blog-agent-vps-to-fargate-spot-code

Code companion — move an always-on agent from a VPS to Fargate Spot

00-baseline/       inspect the VPS: how it runs, state, image, docker use
01-scaffold/       cluster Spot, log group, SG, EFS + access point, IAM roles
02-migrate-state/  presigned-S3 handoff + one-shot seeder task (extract + patch)
03-run/            gateway task def (EFS volume) + Spot service (ECS Exec on)
04-gotchas/        post-boot fixes: host paths, task-role Bedrock IAM, exec debug
05-cutover/        verify from inside, snapshot, delete the VPS (stops the bill)

Reading order

00-baseline/discover.sh — never guess the workload; inspect it.
01-scaffold/scaffold.sh — the AWS side, all cheap + reversible.
02-migrate-state/ — move the state dir onto EFS with no creds on the VPS.
03-run/ — run the official image on Spot, sandbox disabled.
04-gotchas/ — the two failures you will hit right after boot.
05-cutover/ — verify, then delete the VPS (a stopped one still bills).

Notes

No NAT gateway…

View on GitHub

TL;DR

	Antes (VPS)	Después (Fargate Spot)
Cómputo	VM de 2 vCPU / 4 GB, siempre facturada	tarea de 0.5 vCPU / 4 GB, Spot
Costo	$24/mes fijo	~$9/mes (tarea ~$8 + EFS ~$1)
Estado	disco de la VM	EFS (cifrado, persistente)
Sandbox de código	socket de Docker en el host	`mode: off` (la tarea es el aislamiento)
Operación	parchar la VM	imagen inmutable, redesplegar = revisión nueva

Cinco cosas, y el arreglo de cada una:

El sandbox de Docker del agente no va a correr en Fargate: no hay socket de Docker, no hay Docker dentro de Docker. Deshabilítalo; la tarea de Fargate ya es un contenedor aislado.
La migración del estado necesita EFS + un access point fijado al uid del contenedor, o el agente pierde sus sesiones en cada reinicio.
El lift-and-shift filtra rutas absolutas del host (/home/ubuntu/...) hacia config que el contenedor nuevo no puede escribir.
El agente usaba las credenciales implícitas de AWS del host: en Fargate usa el task role, que necesita los permisos de Bedrock (o S3, etc.).
Spot es lo correcto para un agente siempre encendido si se reconecta al reiniciar y su estado está en EFS. Normalmente sí lo hace; eso es ~65% menos.

Decide la forma antes de construir

Tres preguntas determinan el costo y la factibilidad:

¿Necesita tráfico de entrada? Los agentes que salen hacia afuera a plataformas de chat (long-poll / websocket) no necesitan balanceador de carga: sáltate el ALB (~$16/mes) por completo. Solo agrega uno si un canal empuja webhooks a una URL pública.
¿Cuánta RAM? Los agentes de solo-chat caben en 2 GB (0.25 vCPU / 2 GB es una combinación válida de Fargate, la más barata que llega a 2 GB). Si maneja un navegador headless, presupuesta 4 GB (necesita ≥0.5 vCPU).
¿Spot u on-demand? Spot es ~65% más barato pero la tarea puede ser reclamada (aviso de ~2 min) cada varios días. Para un agente que se reconecta al arrancar con el estado en EFS, eso es invisible. On-demand solo si una desconexión momentánea rompe algo frágil.

Una nota tosca pero importante: on-demand a 4 GB (~$28/mes) cuesta más que un VPS de $24. Los ahorros vienen de Spot. Ponle precio antes de comprometerte.

Paso 0: línea base, qué estás moviendo

No adivines la carga de trabajo, inspecciónala. Métete por SSH al VPS y contesta: ¿cómo corre el agente (systemd? un contenedor?), dónde está su estado, qué imagen, qué config, engendra contenedores de Docker?

# 00-baseline/discover.sh (abreviado)
systemctl list-units --type=service | grep -i myagent
docker ps -a --format '{{.Names}} | {{.Image}} | {{.Status}}'
ls -la ~/.myagent && du -sh ~/.myagent            # dir del estado + tamaño
docker inspect --format '{{.Config.User}}' <cid>  # uid del contenedor

Dos hallazgos cambiaron mi plan:

El agente corría nativo vía systemd, no como contenedor, así que no había imagen de gateway que levantar. Usaría la imagen oficial del proyecto y montaría el estado.
Engendraba un contenedor myagent-sandbox a través del socket de Docker del host para ejecutar código. Esa es la incompatibilidad del paso 3.

El estado era diminuto (~10 MB: config, memoria SQLite, sesiones de canales, workspace). Todo bajo un solo dir, así que toda la migración es "mueve este dir y apunta el contenedor a él".

Paso 1: armar el lado de AWS (sin secretos, todo reversible)

Reutiliza un cluster y una VPC existentes si los tienes; una subred pública con assignPublicIp da salida sin NAT gateway (~$32/mes ahorrados). Todo aquí es barato y borrable, constrúyelo antes de tocar el agente.

# 01-scaffold/scaffold.sh (abreviado, el archivo completo está en la carpeta compañera)
# 1. Habilita Spot en el cluster
aws ecs put-cluster-capacity-providers --cluster my-cluster \
  --capacity-providers FARGATE FARGATE_SPOT \
  --default-capacity-provider-strategy capacityProvider=FARGATE,weight=1

# 2. Grupo de logs
aws logs create-log-group --log-group-name /ecs/myagent

# 3. Security group: egreso a todo, NFS 2049 hacia sí mismo (tarea <-> EFS)
SG=$(aws ec2 create-security-group --group-name myagent \
  --description "myagent task + EFS" --vpc-id vpc-xxxx --query GroupId --output text)
aws ec2 authorize-security-group-ingress --group-id "$SG" \
  --protocol tcp --port 2049 --source-group "$SG"

# 4. EFS + un mount target por subred + un access point fijado al uid 1000
FS=$(aws efs create-file-system --encrypted --query FileSystemId --output text)
# ... espera a que esté disponible, create-mount-target en cada subred ...
aws efs create-access-point --file-system-id "$FS" \
  --posix-user Uid=1000,Gid=1000 \
  --root-directory 'Path=/myagent,CreationInfo={OwnerUid=1000,OwnerGid=1000,Permissions=0755}'

El access point es la parte que la gente se salta. Fija cada operación de archivo al uid del contenedor (aquí 1000, revisa el tuyo en el paso 0), para que el agente de verdad pueda escribir su estado, y le da un namespace a esta app en un sub-path del filesystem. Sin él te peleas con errores de permisos de NFS.

También necesitas dos roles de IAM (con trust a ecs-tasks.amazonaws.com):

execution role: AmazonECSTaskExecutionRolePolicy (jalar la imagen, escribir logs).
task role: lo que el agente tiene permitido hacer en tiempo de ejecución. Empieza vacío, recibe Bedrock en el paso 4. Agrega las acciones de SSM ahora para que puedas entrar con ECS Exec a depurar.

Paso 2: mover el estado a EFS

EFS solo es alcanzable desde adentro de la VPC, así que no puedes hacerle scp. El camino limpio: haz tar del estado en el VPS, pásalo a través de un objeto privado de S3, y corre una tarea "sembradora" de Fargate de una sola vez que monta EFS y extrae.

No hacen falta credenciales de AWS en el VPS: genera una URL PUT
prefirmada y hazle curl:

# 02-migrate-state/presign.py  ->  imprime una URL PUT prefirmada
# En el VPS (detén el agente primero para que SQLite/sesiones queden consistentes):
sudo systemctl stop myagent
sudo tar -C /home/user -czf /tmp/myagent.tgz .myagent
curl -T /tmp/myagent.tgz "<PRESIGNED_PUT_URL>"

Deja el agente detenido. Es tu rollback. También previene el conflicto de "la misma sesión corriendo dos veces" (una sesión de WhatsApp/Telegram no puede estar viva en dos lugares).

La tarea sembradora (imagen python:3.12-slim, con el access point de EFS
montado en /mnt) descarga, extrae quitando el dir de nivel superior para que el contenido aterrice en la raíz del mount, y parcha la config de paso:

# 02-migrate-state/seeder.py (abreviado)
tf = tarfile.open(fileobj=io.BytesIO(urllib.request.urlopen(url).read()))
for m in tf.getmembers():
    parts = m.name.split("/", 1)
    if parts[0] == ".myagent":            # quita el prefijo ".myagent/"
        m.name = parts[1] if len(parts) > 1 else "."
    if m.name and m.name != ".":
        tf.extract(m, "/mnt")

Como el access point fuerza el uid 1000, todo aterriza siendo propiedad del usuario del agente, sin necesidad de chown. Ve 02-migrate-state/ para la definición completa de la tarea sembradora y cómo hacerle run-task y leer sus logs.

Paso 3: correr el agente + la trampa del sandbox

Aquí está la incompatibilidad. Un agente que corre código engendrando
contenedores de Docker hermanos usa el /var/run/docker.sock del host. Fargate no tiene socket de Docker ni modo privilegiado. Opciones:

Deshabilita el sandbox de Docker: corre las herramientas dentro del proceso del gateway. En Fargate ese proceso es un contenedor endurecido, efímero, sin host: la tarea es la frontera del sandbox. Este es el más barato y simple.
Usa un backend de sandbox SSH/remoto apuntando a una caja aparte (agrega una máquina → costo).
Quédate con el sandbox de Docker → no puedes usar Fargate; usa ECS en EC2 (una instancia Spot chica conserva el socket de Docker).

Yo parché la config para deshabilitarlo:

# 02-migrate-state/seeder.py — parche del sandbox
def walk(o):
    if isinstance(o, dict):
        for k, v in o.items():
            if k == "sandbox" and isinstance(v, dict):
                v["mode"] = "off"
            walk(v)
    elif isinstance(o, list):
        [walk(x) for x in o]

Luego la definición de tarea del gateway monta el access point de EFS en el home del contenedor y corre la imagen oficial:

// 03-run/gateway-taskdef.json (campos clave)
"cpu": "512", "memory": "4096",
"volumes": [{ "name": "efs", "efsVolumeConfiguration": {
  "fileSystemId": "fs-xxxx", "transitEncryption": "ENABLED",
  "authorizationConfig": { "accessPointId": "fsap-xxxx" } }}],
"containerDefinitions": [{
  "name": "gateway",
  "image": "ghcr.io/example/myagent:VERSION",
  "environment": [{ "name": "HOME", "value": "/home/node" }],
  "mountPoints": [{ "sourceVolume": "efs", "containerPath": "/home/node/.myagent" }],
  "linuxParameters": { "initProcessEnabled": true }   // habilita ECS Exec
}]

Crea el servicio en Spot, una tarea, con ECS Exec encendido:

# 03-run/create-service.sh
aws ecs create-service --cluster my-cluster --service-name myagent \
  --task-definition myagent --desired-count 1 \
  --capacity-provider-strategy capacityProvider=FARGATE_SPOT,weight=1 \
  --network-configuration 'awsvpcConfiguration={subnets=[subnet-a,subnet-b],securityGroups=[sg-xxxx],assignPublicIp=ENABLED}' \
  --enable-execute-command

Paso 4: los dos arreglos que vas a pegar justo después de que arranca

La tarea va a llegar a RUNNING e incluso conectar sus canales, luego falla en la primera acción real. Dos razones, las dos porque un proceso nativo del host ahora es un contenedor bajo una identidad distinta.

Depurar sin stdout. Muchos agentes registran a archivos, no a stdout, así que CloudWatch está vacío. Usa ECS Exec. Meter comillas a través de execute-command es frágil, hazle base64 a tu script:

# 04-gotchas/ecs-exec.sh
B64=$(base64 -i diag.sh)
aws ecs execute-command --cluster my-cluster --task "$TID" --container gateway \
  --interactive --command "/bin/sh -c \"echo $B64 | base64 -d | sh\""

Arreglo 1: rutas absolutas del host. La config escrita en el VPS deja fijo /home/ubuntu/.myagent/.... El home del contenedor es /home/node, y no puede hacer mkdir /home/ubuntu → EACCES. Reescríbela en EFS y reinicia:

# 04-gotchas/fix-paths.sh — corre vía ECS Exec, luego detén la tarea para recargar
cd /home/node/.myagent
grep -rIl '/home/ubuntu' . | while read -r f; do
  sed -i 's#/home/ubuntu#/home/node#g' "$f"; done

Arreglo 2: la identidad ahora es el task role, no el host. En el VPS el agente llamaba a Bedrock (o S3, SES...) usando credenciales de ambiente. En Fargate el SDK usa el task role. Vas a ver:

assumed-role/myagent-task-role ... is not authorized to perform: bedrock:InvokeModelWithResponseStream

Adjunta exactamente lo que necesita. Para un agente de Bedrock (Claude/Nova), nota que los inference profiles enrutan a los foundation models a través de regiones, así que permites los dos:

// 04-gotchas/bedrock-policy.json
{ "Effect": "Allow",
  "Action": ["bedrock:InvokeModel", "bedrock:InvokeModelWithResponseStream",
             "bedrock:Converse", "bedrock:ConverseStream"],
  "Resource": [
    "arn:aws:bedrock:*:111122223333:inference-profile/*",
    "arn:aws:bedrock:*::foundation-model/anthropic.*",
    "arn:aws:bedrock:*::foundation-model/amazon.nova*"
  ]}

Los cambios de IAM aplican en la siguiente llamada, sin necesidad de
reiniciar.

Paso 5: verifica, luego haz el cambio

Verifica desde adentro antes de borrar nada. Métete con ECS Exec y revisa: el proceso está arriba, el estado migró, sin rutas del host perdidas, y que tiene conexiones de salida vivas:

# 05-cutover/verify.sh (abreviado)
cat /proc/1/cmdline | tr '\0' ' '                       # ¿gateway corriendo?
awk 'NR>1 && $4=="01"{c++} END{print c}' /proc/net/tcp   # conexiones establecidas
grep -rIl '/home/ubuntu' /home/node/.myagent            # debería estar vacío

Luego la prueba de verdad: mándale un mensaje al agente en su canal. Cuando responda limpio, haz el cambio:

# 05-cutover/teardown.sh
# 1. Toma un snapshot del VPS como fallback ANTES de borrar
aws lightsail create-instance-snapshot --instance-name myagent-vps \
  --instance-snapshot-name myagent-premigration
# 2. Borra el VPS: esto es lo que detiene la cuenta (una instancia Lightsail
#    *detenida* igual cobra; solo borrarla lo hace).
aws lightsail delete-instance --instance-name myagent-vps --force-delete-add-ons

Ese último punto es el que de verdad ahorra dinero: detener una instancia Lightsail no reduce su costo, tienes que borrarla. Conserva el snapshot (~$0.05/GB-mes) hasta que estés confiado, luego bórralo también.

Con qué te quedas

Un solo servicio Spot, una tarea, que se reconecta por su cuenta después de un reclamo de Spot, leyendo el estado desde EFS.
~$9/mes en lugar de $24, ~60% menos, sin VM que parchar.
Los redespliegues son una revisión nueva de la definición de tarea (sube el tag de la imagen); las ediciones de config son meterte con ECS Exec a la tarea, editar el dir de EFS, reiniciar.

El patrón se generaliza: cualquier agente siempre encendido, de salida, que se pueda contenerizar y con un dir de estado chico es un buen candidato para Fargate Spot. Las trampas (incompatibilidad del sandbox de Docker, access points de EFS, rutas del host filtradas, y el cambio de identidad de host→task-role) son las mismas cada vez. Arréglalas una vez y el descuento de ~65% de Spot es tuyo.

Una capa de prompts que se califica a sí misma por resultados, hace A/B testing de sus propias reescrituras, e intercambia al ganador casi sin despliegue

Franchesco Romero — Sat, 04 Jul 2026 22:42:33 +0000

Casi todo el "manejo de prompts" es una carpeta de archivos .txt y una revisión de código. Esto es lo opuesto: los prompts viven en la base de datos como filas versionadas, cada agente busca el actual en el momento de la petición, la calidad se puntúa a partir de lo que de verdad pasó (una publicacion fue aceptada, un borrador se publicó, no un LLM calificándose a sí mismo), y un ciclo diario reescribe a los perdedores, les hace A/B testing a las reescrituras, y promueve al ganador de manera automática.

elchesco / blog-self-improving-prompts-code

Code companion — a self-improving prompt layer

00-starting-point/     NOTES.md            prompts as constants — the baseline
01-versioned-rows/     models.py           PromptVersion / ABTest / PromptFeedback
                       register_prompt.py  publish a version (deactivate prior)
02-resolve-at-request/ resolve_prompt.py   drop-in for FOO_PROMPT.format(...)
                       select_version.py    A/B-aware version picker (+ usage++)
03-score-from-outcomes/ implicit_signals.py downstream outcomes -> success/failure
                       scorer.py           combined_score = explicit·0.4 + implicit·0.6
04-ab-routing/         start_test.py       register variant + open 90/10 test
05-pick-winner/        evaluate.py         min-samples / >=10pt / hard-stop -> promote
06-optimize-loop/      optimizer.py        rewrite underperformers -> PENDING suggestion
07-the-trap/           duplicate_running_abtests.py   the scalar_one_or_none crash + fix

The one idea

combined_score = explicit·0.4 + implicit·0.6

…

View on GitHub

TL;DR

El ciclo, una vez que un prompt está en el registro:

Etapa	Qué pasa	Dónde
Resolver	el agente busca el prompt activo en el momento de la petición (intercambiable en caliente)	`resolve_prompt`
Medir	explícito (👍/⭐) + implícito (resultado) → `combined_score`	recolector de feedback + trabajador implícito
Optimizar	a diario: reescribe a los de bajo rendimiento con un LLM → una sugerencia PENDING	optimizador de prompts
Probar	abre un A/B test 90/10, enruta el tráfico por versión	gestor de A/B
Promover	tras ≥50 muestras, el ganador por ≥10 pts → actívalo	gestor de A/B

La única idea que lo hace funcionar: combined_score = explícito·0.4 + implícito·0.6, donde lo implícito es un resultado de negocio real. El modelo nunca califica su propia tarea.

El punto de partida: prompts como constantes

La línea base que casi todos publican:

SUMMARY_PROMPT = """You are an expert reviewer. Summarise: {text}"""

async def summarise(text: str) -> str:
    return await llm(SUMMARY_PROMPT.format(text=text))

Dos problemas, los dos invisibles hasta que muerden:

Cambiar un prompt es un despliegue. Ajustar una coma en el system prompt significa un PR, un build, un rollout. Así que nadie itera: el prompt se queda sin mantener.
"¿El nuevo es mejor?" es una corazonada. Cambias la redacción, le echas un ojo a tres salidas, y publicas. No hay medición, así que no hay mejora, solo cambio.

Todo lo de abajo reemplaza "constante + corazonadas" con "fila + puntaje".

Capa 1: los prompts son filas versionadas

El prompt se vuelve dato. Una fila por (agent, prompt_type, version); una está marcada como activa.

class PromptVersion(Base):
    __tablename__ = "prompt_versions"
    agent_name: Mapped[str]
    prompt_type: Mapped[str]
    version: Mapped[int]
    prompt_text: Mapped[str]
    is_active: Mapped[bool]          # exactamente 1 TRUE por (agent, type), normalmente
    # calidad acumulada (llenada por el puntuador, Capa 3)
    usage_count: Mapped[int]
    avg_explicit_rating: Mapped[float]
    explicit_approval_rate: Mapped[float]
    implicit_success_rate: Mapped[float]
    combined_score: Mapped[float]
    performance_trend: Mapped[str]   # improving | stable | declining

Registrar una versión nueva desactiva a la activa anterior en la misma transacción, así que "publicar un prompt nuevo" es una escritura a la base de datos, no un despliegue:

async def register_prompt(self, *, agent_name, prompt_type, prompt_text, activate):
    current_max = await self._max_version(agent_name, prompt_type)
    if activate:
        await self.db.execute(
            update(PromptVersion)
            .where(PromptVersion.agent_name == agent_name,
                   PromptVersion.prompt_type == prompt_type,
                   PromptVersion.is_active.is_(True))
            .values(is_active=False)
        )
    self.db.add(PromptVersion(
        agent_name=agent_name, prompt_type=prompt_type,
        version=current_max + 1, prompt_text=prompt_text, is_active=activate,
    ))

Los prompts fijos que ya existían siembran el registro como versión 1, una vez (idempotente). Esa semilla es también el fallback, ve la siguiente capa.

Capa 2: los agentes resuelven el prompt en el momento de la petición

El intercambio que hace gratis la iteración. En lugar de
SUMMARY_PROMPT.format(...), el agente llama a un resolvedor que lee la fila actual:

async def resolve_prompt(db, *, agent_name, prompt_type, template_vars, fallback_text):
    """Reemplazo directo de `FOO_PROMPT.format(**vars)`, pero el texto viene del
    registro. Cae al constante fijo si el registro no tiene fila (despliegue
    fresco, o las tablas de aprendizaje todavía no están sembradas)."""
    try:
        text, version_id = await PromptRegistry(db).get_prompt(
            agent_name=agent_name, prompt_type=prompt_type, template_vars=template_vars,
        )
        return text
    except LookupError:
        return fallback_text.format(**template_vars)

Dos detalles que no son obvios:

El fallback es el prompt fijo. El registro es un override, nunca una dependencia dura. Un entorno de dev con las tablas de aprendizaje vacías se comporta exactamente como el código viejo basado en constantes. Puedes adoptarlo un agente a la vez.
get_prompt incrementa usage_count y regresa el version_id. Ese id se estampa en la traza de la petición, así que cuando un resultado aterriza después (Capa 3) se atribuye a la versión exacta del prompt que lo produjo. Sin ese enlace, nada de la puntuación significa algo.

Después de esta capa, cambiar un prompt en prod es un UPDATE (o una fila activa nueva), en vivo en la siguiente petición, sin despliegue. Lo cual levanta la pregunta de verdad: ¿cómo sabes que la fila nueva es mejor?

Capa 3: calidad desde los resultados, no desde las opiniones

Este es el meollo, y donde la mayoría de la "evaluación de prompts" se equivoca. Dos tipos de señal, ponderadas a propósito:

Explícita: el usuario te dice. Un 👍/👎 o una estrella del 1 al 5 sobre la salida. Honesta pero escasa y sesgada (la gente califica cuando está molesta). Vale la pena recolectarla, vale la pena ponderarla de menos.

Implícita: el mundo te dice. ¿La cosa que el agente produjo de verdad funcionó? Estos son eventos de negocio reales, atados de regreso a la versión del prompt vía la traza de la Capa 2:

# Las señales implícitas son resultados, no la autoevaluación del modelo:
#   blog_accepted        — la publicacion que el agente ayudó a proponer fue ACEPTADA
#   post_published      — el borrador que el agente escribió se publicó
#   message_converted   — el mensaje que el agente redactó convirtió un lead
#   doc_reuploaded — (negativo) el usuario re-subió → la primera pasada falló

Un worker recorre los resultados recientes y registra cada uno como un éxito/fracaso contra la versión que lo generó. Luego el puntuador acumula todo:

# combined_score = explícito·0.4 + implícito·0.6
explicit = (avg_rating / 5 * 100) * 0.75 + approval_rate * 0.25
implicit = implicit_success_rate            # 0–100, la verdad de combined = explicit * 0.4 + implicit * 0.6

Lo implícito pesa más que lo explícito (0.6 vs 0.4) a propósito. Un prompt que la gente dice que le gusta pero cuyas propuestas de blog nunca se aceptan es un peor prompt que uno tosco que sí consigue aceptaciones. Los resultados son la verdad de fondo; las calificaciones son una pista.

La misma pasada calcula una tendencia comparando el combined_score de hoy con el puntaje del mismo prompt de hace una semana (improving | stable | declining). La tendencia, no solo el puntaje absoluto, es lo que marca un prompt que se está pudriendo calladito mientras el mundo cambia a su alrededor.

El principio que vale la pena tatuarse en la pared: nunca dejes que el modelo califique su propia salida. "Pídele a GPT que califique esta respuesta del 1 al 10" mide fluidez, no utilidad. Ata el puntaje a algo que pase después de que la respuesta sale del sistema.

Capa 4: enrutamiento A/B por versión

Un prompt candidato nuevo no se activa: se registra como una variante y un A/B test enruta una rebanada del tráfico hacia él:

# start_test: registra la variante (NO activa), abre un test 90/10
variant = await registry.register_prompt(..., activate=False)
db.add(ABTest(agent_name=..., prompt_type=...,
              control_version_id=control.id, variant_version_id=variant.id,
              control_traffic_pct=90, variant_traffic_pct=10,
              min_samples=50, status="RUNNING"))

La resolución (Capa 2) revisa primero si hay un test RUNNING y tira los dados:

test = await running_test_for(agent_name, prompt_type)
if test:
    chosen = test.variant_version_id if randint(1, 100) <= test.variant_traffic_pct \
             else test.control_version_id
    return version_by_id(chosen)
return active_version(agent_name, prompt_type)   # sin test → la fila activa

90/10, no 50/50: una variante mala solo grava el 10% del tráfico mientras se prueba a sí misma o muere. El control sigue sirviendo el otro 90%.

Capa 5: declarar un ganador (o no)

La evaluación corre en un calendario. Las reglas son aburridas a propósito: lo aburrido es lo que te evita promover ruido:

if variant.usage_count < test.min_samples:        # < 50 usos
    return "not_enough_samples"                    # sigue esperando

diff = variant.combined_score - control.combined_score
if abs(diff) >= 10:                                # WINNER_DIFF_PTS
    winner = variant if diff > 0 else control
    activate(winner); test.status = "COMPLETED"    # promover — intercambio en caliente
    return "variant_win" if diff > 0 else "control_win"

if variant.usage_count >= 500:                     # HARD_STOP_SAMPLES
    activate(control); test.status = "COMPLETED"   # sin ventaja clara → quédate con el control
    return "inconclusive"

return "still_running"                             # todavía no hay suficiente separación

Tres umbrales, cada uno se gana su lugar:

min_samples = 50: por debajo de esto, un "gane" es puro azar. No mires todavía.
|diff| ≥ 10 puntos: una ventaja de 2 puntos es ruido. Exige una brecha real.
hard_stop = 500: si 500 usos no los pueden separar, son equivalentes; quédate con el titular y deja de desperdiciar tráfico. Sin un tope duro, los tests inconclusos corren por siempre.

La promoción es nada más activate(winner): el mismo intercambio en
caliente de una escritura de la Capa 1. El prompt nuevo está en vivo en la siguiente petición.

Capa 6: cerrar el ciclo, reescribir a los perdedores

Hasta ahora un humano todavía tiene que escribir la variante. La última pieza automatiza eso. Un optimizador diario encuentra a los de bajo rendimiento:

# de bajo rendimiento si CUALQUIERA:
#   usage_count >= 30 AND combined_score < 40          (suficientes datos, mal puntaje)
#   performance_trend == "declining" AND combined_score < 60   (pudriéndose)

…le pasa el prompt débil + sus puntajes a un LLM ("aquí hay un prompt y cómo le está yendo; reescríbelo para mejorar los resultados"), y archiva la reescritura como una sugerencia PENDING. El gestor de A/B (Capa 4) toma las sugerencias PENDING y abre tests. El ciclo ahora corre de punta a punta:

sembrar → resolver → medir (resultados) → optimizar (reescribir) → A/B → promover → resolver …

Un humano todavía aprueba lo que entra a un test: el optimizador sugiere, no auto despliega a prod. Pero la escritura, la puntuación, y la promoción son automáticas.

La trampa: un bug tumbó cada query

Una función de autoservicio empezó a fallar con:

Multiple rows were found when one or none was required

El selector de versión del resolvedor usaba scalar_one_or_none():

test = (await db.execute(
    select(ABTest).where(ABTest.status == "RUNNING",
                         ABTest.agent_name == name,
                         ABTest.prompt_type == ptype))
).scalar_one_or_none()          # ← lanza MultipleResultsFound con 2 filas

Nada en el esquema fuerza un único test RUNNING por prompt, y se habían abierto dos con 13 segundos de diferencia. De ahí en adelante, cada petición para ese prompt pegaba contra scalar_one_or_none(), encontraba dos filas, y lanzaba excepción. Peor, el resolvedor solo atrapaba LookupError, así que la excepción se pasó de largo el fallback y salió hasta el usuario.

Dos arreglos, los dos necesarios:

# 1) Tolera duplicados en lugar de tronar: elige el más nuevo, registra la anomalía.
tests = (await db.execute(
    select(ABTest).where(...).order_by(ABTest.created_at.desc())
)).scalars().all()
if len(tests) > 1:
    logger.warning("multiple_running_abtests", agent=name, type=ptype, count=len(tests))
test = tests[0] if tests else None

-- 2) De duplica el dato: cancela el test RUNNING más viejo.
UPDATE prompt_ab_tests SET status = 'CANCELLED' WHERE id = '<older>';

La lección se generaliza: scalar_one_or_none() es un crash latente en cualquier lado donde "solo debería haber uno" no es una restricción de la base de datos. Si el invariante no lo fuerza un índice único, la ruta de lectura tiene que tolerar la violación, no darla por descartada.

Lo que NO ayudó

Calidad autocalificada. Pedirle al modelo que puntúe su propia salida medía fluidez, nunca utilidad. Reemplazado por completo por los resultados de aguas abajo.
Splits A/B 50/50. Gravar la mitad del tráfico con una variante sin probar. 90/10 prueba una variante igual de bien con un décimo del radio de impacto.
El puntaje absoluto solo. Un prompt en 70 que va declinando es un problema más grande que uno estable en 60. La tendencia atrapó la pudrición que el puntaje escondía.
Suponer un solo test RUNNING. Sin restricción única → scalar_one_or_none era una bomba de tiempo.

Lecciones

Puntúa sobre resultados, no sobre opiniones. Todo el sistema se para sobre las señales implícitas: eventos reales atados a la versión del prompt. Todo lo demás es decoración.
Haz gratis el cambiar un prompt. Un registro + resolución en el momento de la petición convierte "cambiar un prompt" de un despliegue a una fila. La iteración gratis es la precondición para mejorar.
El override tiene que degradar al constante. Un fallback fijo significa que adoptas de manera incremental y nunca endureces una dependencia del ciclo.
Los umbrales aburridos le ganan a los ingeniosos. El mínimo de muestras, un requisito de brecha real, y un tope duro son lo que te evita promover ruido.
Radio de impacto chico para los cambios sin probar. 90/10, no 50/50.
Si no es una restricción de la base de datos, no es un invariante. Las rutas de lectura tienen que tolerar la segunda fila "imposible".