El esqueleto es Modularizing React Applications with Established UI Patterns, la serie que Juntao Qiu, de Thoughtworks, publicó en martinfowler.com en febrero de 2023. No traduzco el original tal cual, sino que lo vuelvo a contar con mis palabras, y todas las figuras del artículo vienen de ese texto. Encima añado los resultados de descargar el repositorio de ejemplo del autor y ejecutar la comprobación de tipos y los tests, además de otros materiales que tratan el mismo problema.

React es una view library

Cuando uno aprende React, la idea más atractiva es que la UI es una función pura que convierte datos en DOM. Hasta cierto punto es cierto. Pero en el momento en que envías una petición al servidor o navegas a otra página, el component deja de ser puro. Si a eso se le suman state global y state local enredados, el código se complica enseguida.

La respuesta del autor es cambiar de perspectiva. No existe un tipo de software aparte llamado "aplicación React". React es una library para dibujar UI, y dónde poner los cálculos o las reglas de negocio nunca fue asunto suyo. Lo que hay encima es una app de JavaScript normal y corriente. Entonces se puede usar tal cual el diseño que se viene usando desde la época de las GUI de escritorio, en particular la división del código en tres layers: presentation, domain y data.

Una app frontend real tiene, además de la view, router, local storage, varios niveles de caché, peticiones de red, integración con servicios externos e inicio de sesión, seguridad, logging y ajustes de rendimiento. Si todo eso se mete en components y hooks, en un mismo archivo la línea que pide el estado del pedido va seguida de una línea que recorta los espacios iniciales de un string, y después viene una línea que navega a otra pantalla. Quien lee tiene que ir y volver cambiando de nivel de abstracción todo el tiempo.

Las razones para dividir se resumen en dos. La pantalla cambia más a menudo que las reglas de negocio. Y si separas ambas, solo tienes que pensar en una cosa a la vez. La segunda razón es la que Martin Fowler da en PresentationDomainDataLayering como la mayor ventaja de esta separación: como se puede pensar en los tres temas de forma relativamente independiente, se reduce el alcance al que hay que prestar atención.

Cinco etapas en el crecimiento de una app

Antes de entrar en la refactorización, el autor muestra con cinco figuras cómo cambia la estructura a medida que crece la app. Lo importante es qué provoca el paso a la etapa siguiente. No es un momento fijo, sino que la incomodidad que aparece en una etapa llama a la siguiente. Los colores significan lo mismo en las cinco figuras. Verde claro es un container component con state, verde oscuro es un presentational component que solo dibuja, morado es un hook, azul es un domain object y naranja es infraestructura como la red.

Al principio, un solo component tiene la petición de red, el state, los cálculos y el render. En una app pequeña o en un proyecto de un solo uso esto basta, y como el código se parece al HTML, hasta es fácil de leer. Cuando el código que recorre una lista para crear elementos se mezcla con el que configura components externos y empieza a costar tiempo leer qué está pasando, se pasa a la etapa siguiente.

Cuando la pantalla crece, se dividen los components siguiendo la forma del HTML resultante. Se separan components que solo dibujan, pero en el component superior siguen quedando la petición de red, el código que transforma la respuesta a la forma que necesita la pantalla y el código que reúne los datos que se envían al servidor. Ninguno de los tres es UI y, sin embargo, están dentro del component.

Después se extraen el state y sus cambios a un custom hook. Entonces queda dentro del hook un cálculo puro que no es ni side effect ni state.

Si ese cálculo se saca a un objeto que no tiene nada que ver con React, aparece un domain object. Aquí van la conversión de formatos de datos, las comprobaciones de null y los valores por defecto. Cuando los objetos se multiplican, empiezan a hacer falta la herencia o el polimorfismo.

Por último, cuando aparecen objetos que no pertenecen a la UI y a los que tampoco les importa si los datos vienen del servidor, del local storage o de una caché, se agrupan aparte en una model layer.

Viendo solo las figuras, resulta abstracto. Recorramos estas cinco etapas una vez con código real. El ejemplo que eligió el autor es la pantalla de pago de un pedido en línea.

Partir de una sola pantalla de pago

Los métodos de pago vienen de la configuración del servidor y cambian según el país. Si el servidor devuelve al menos uno, se añade al final el pago en efectivo y se deja seleccionado por defecto; si no devuelve ninguno, no se muestra nada.

El código inicial tiene la forma que se ve a menudo en los tutoriales. Hace fetch dentro de useEffect, transforma la respuesta a la forma que necesita la pantalla, añade el pago en efectivo y dibuja la lista de radios. Lo de abajo es mi versión resumida.

export const Payment = ({ amount }: { amount: number }) => {
  const [paymentMethods, setPaymentMethods] = useState<LocalPaymentMethod[]>([]);
 
  useEffect(() => {
    fetch(url)
      .then((res) => res.json())
      .then((methods: RemotePaymentMethod[]) => {
        if (methods.length === 0) return setPaymentMethods([]);
        const extended = methods.map((m) => ({ provider: m.name, label: `Pay with ${m.name}` }));
        extended.push({ provider: "cash", label: "Pay in cash" });
        setPaymentMethods(extended);
      });
  }, []);
 
  return (
    <div>
      {paymentMethods.map((method) => (
        <label key={method.provider}>
          <input type="radio" defaultChecked={method.provider === "cash"} />
          {method.label}
        </label>
      ))}
      <button>${amount}</button>
    </div>
  );
};

A este tamaño no es un problema. Pero para modificar este component hay que entender cuatro cosas a la vez: cómo se inicia la petición de red, cómo se transforman los datos del servidor a la forma que conoce la pantalla, cómo se dibuja un método de pago y cómo se dibuja toda la zona de pago. Cuando el código crece, quien lo lee tiene que ir y venir entre esas cuatro sin parar.

Hooks y pure components

Lo primero que se extrae es el state y el fetch. La señal para decidir es simple. Cuando el código que no tiene que ver con el render supera la mitad del cuerpo del component, se saca a un hook. usePaymentMethods se encarga del fetch y la transformación, y el component solo dibuja el array que le da el hook.

Lo segundo es el JSX que dibuja la lista. Cuando ves un bloque que se puede dibujar recibiendo solo props, lo separas en un component. PaymentMethods es un pure component que recibe un único array de métodos de pago, así que es fácil de testear y reutilizar. Aunque más adelante se le añada un callback onSelect para avisar de la selección, sigue siendo pure porque no toca el state de fuera.

const usePaymentMethods = () => {
  const [paymentMethods, setPaymentMethods] = useState<LocalPaymentMethod[]>([]);
  useEffect(() => { /* 위의 fetch와 변환 */ }, []);
  return { paymentMethods };
};
 
export const Payment = ({ amount }: { amount: number }) => {
  const { paymentMethods } = usePaymentMethods();
  return (
    <div>
      <PaymentMethods paymentMethods={paymentMethods} />
      <button>${amount}</button>
    </div>
  );
};

El autor llama a ambas operaciones Extract Function, del catálogo de refactorizaciones, porque en React un component también es una función. Lo importante es que no se introdujo ningún concepto nuevo: solo se dividió una función en dos.

Con esto parece que ya está, pero todavía quedan dos sitios. Dentro de la view está la decisión "si es efectivo, se selecciona por defecto", y dentro del hook hay una función anónima que transforma la respuesta a la forma de la pantalla. El autor llama logic leak a estas reglas de negocio que se escapan hacia la view y el hook.

Reglas reunidas en un domain object

La tercera señal es cuando las decisiones sobre los mismos datos están repartidas entre la view y el hook. Las decisiones y transformaciones que se escaparon se reúnen en una sola class, PaymentMethod. Como conté en el modelo de dominio de este blog, se trata de poner las reglas junto a los datos.

class PaymentMethod {
  constructor(private remote: RemotePaymentMethod) {}
  get provider() { return this.remote.name; }
  get label() { return this.provider === "cash" ? "Pay in cash" : `Pay with ${this.provider}`; }
  get isDefaultMethod() { return this.provider === "cash"; }
}
 
const convertPaymentMethods = (methods: RemotePaymentMethod[]) =>
  methods.length === 0
    ? []
    : [...methods.map((m) => new PaymentMethod(m)), new PaymentMethod({ name: "cash" })];

Ahora el radio de la view le pregunta al objeto con defaultChecked={method.isDefaultMethod}. El pago en efectivo por defecto también se expresa como una instancia más de la misma class. Como lo que da el servidor y lo que añade la app tienen la misma forma, la view no necesita distinguirlos.

El autor señala como ventaja de esta estructura que los tests se vuelven más fáciles. El original se queda en esa frase, pero es más rápido ver con código cuánto más fáciles. Lo de abajo es un test que escribí yo. No hay React, ni renderer, ni mock de fetch.

test("서버가 준 결제 수단 끝에 현금 결제를 기본값으로 붙인다", () => {
  const methods = convertPaymentMethods([{ name: "apple" }, { name: "google" }]);
 
  expect(methods.map((m) => m.label)).toEqual(["Pay with apple", "Pay with google", "Pay in cash"]);
  expect(methods.filter((m) => m.isDefaultMethod).map((m) => m.provider)).toEqual(["cash"]);
});
 
test("서버가 아무것도 주지 않으면 현금 결제도 보여 주지 않는다", () => {
  expect(convertPaymentMethods([])).toEqual([]);
});

Para comprobar la misma regla en el código inicial había que hacer render del component, interceptar el fetch y esperar a que se dibujaran los radios. En cuanto la regla sale a un objeto, el test se convierte en una línea con una llamada a función.

Otra ventaja es que, cuando llega un requisito nuevo, ya está decidido adónde va. En este punto la estructura de archivos es esta.

src
├── components
│   ├── Payment.tsx
│   └── PaymentMethods.tsx
├── hooks
│   └── usePaymentMethods.ts
└── models
    └── PaymentMethod.ts

Si la estructura aguanta de verdad solo se sabe cuando llega un requisito nuevo. Aquí el autor añade una funcionalidad más.

La función de donación y el hook como state machine

El nuevo requisito es redondear hacia arriba el importe del pedido y donar la diferencia a una organización benéfica. Si el pedido es de 19,80 dólares, se pregunta si se quiere donar 0,20 dólares y, si se acepta, el botón muestra 20 dólares.

El autor, a propósito, mete al principio el state de aceptación y el cálculo dentro del component de pago. Al entrar de golpe el marcado de la casilla, la bifurcación del texto y el cálculo del total, el component vuelve a pesar. El orden para ordenarlo es el mismo que vimos antes. El state y el cálculo van al hook useRoundUp, el armado del texto a una función helper y el marcado de la casilla al component DonationCheckbox.

export const useRoundUp = (amount: number) => {
  const [agreeToDonate, setAgreeToDonate] = useState(false);
 
  const { total, tip } = useMemo(() => ({
    total: agreeToDonate ? Math.floor(amount + 1) : amount,
    tip: parseFloat((Math.floor(amount + 1) - amount).toPrecision(10)),
  }), [amount, agreeToDonate]);
 
  const updateAgreeToDonate = () => setAgreeToDonate((v) => !v);
  return { total, tip, agreeToDonate, updateAgreeToDonate };
};

toPrecision(10) es una parte cuyo motivo el original no explica. Lo ejecuté en Node 24 y 20 - 19.8 dio 0.1999999999999993. Es un mecanismo para quitar el error de coma flotante.

El autor ve este tipo de hook como "una state machine detrás de la view". Cuando llega un evento desde la UI, crea un state nuevo, y el state nuevo vuelve a provocar un render. Los hooks se crearon en origen para que varios components compartieran logic, pero la postura del autor es que, aunque solo se usen en un sitio, vale la pena extraerlos porque dejan al component concentrado en el render. Añado una cosa: como señala la documentación oficial de React en Reusing Logic with Custom Hooks, lo que comparte un custom hook es la logic que maneja el state, no el state en sí. Esta state machine se crea por separado, una por cada component que llama al hook.

Cuando se termina de ordenar, el component de pago llama a dos hooks y coloca dos components hijos y un botón. Se añadió una funcionalidad, pero el papel del component de pago no cambió.

Reglas por país y shotgun surgery

El siguiente requisito es que la unidad de redondeo cambie según el país. En Japón es de 100 yenes y en Dinamarca de 10 coronas. El autor, diciendo que "parece un arreglo fácil", muestra primero a propósito el camino de recibir el código de país como prop y meter bifurcaciones.

// useRoundUp 안
total: agreeToDonate
  ? countryCode === "JP" ? Math.floor(amount / 100 + 1) * 100 : Math.floor(amount + 1)
  : amount,
 
// 체크박스 문구 helper 안
const currencySign = countryCode === "JP" ? "¥" : "$";
 
// 버튼 JSX 안
<button>{countryCode === "JP" ? "¥" : "$"}{total}</button>

La misma comprobación countryCode === "JP" entró en tres sitios, uno en el hook, otro en el helper y otro en el botón. Al añadir Dinamarca hay que volver a tocar los tres, y cuando el operador ternario ya no da abasto aparece una tabla que busca el símbolo de moneda por código de país. Esa tabla también acaba referenciándose por separado en varios sitios. Este olor, en el que un solo cambio obliga a modificar varios módulos a la vez, se llama shotgun surgery.

Lo que distingue esta etapa de las tres anteriores es que la señal para decidir no viene del código, sino de las peticiones de cambio. Si solo miras el código actual, tres bifurcaciones no son difíciles de leer. El problema se ve cuando cuentas cuántos sitios hay que tocar para añadir un país más. Entonces, ¿adónde hay que reunir las bifurcaciones dispersas?

Las diferencias por país reunidas con Strategy

La respuesta del autor es convertir en objeto la propia diferencia entre países. Primero, con Extract Class y Replace Conditional with Polymorphism, crea una interface y una implementación por país.

interface PaymentStrategy {
  getRoundUpAmount(amount: number): number;
  getTip(amount: number): number;
}
 
class PaymentStrategyAU implements PaymentStrategy { /* 1달러 단위 */ }
class PaymentStrategyJP implements PaymentStrategy { /* 100엔 단위 */ }

Una vez hechas, lo único que cambia entre implementaciones es el símbolo de moneda y la función de redondeo; el resto, como getTip, es idéntico. Así que el autor fusiona las implementaciones en una sola class con Inline Class y recibe solo lo que cambia por el constructor. Se puede recibir el algoritmo de redondeo como función, sin crear una subclass por país, porque en JavaScript las funciones son valores. Lo de abajo es mi versión resumida del resultado.

class CountryPayment {
  constructor(readonly currencySign: string, private roundUp: (n: number) => number) {}
  getRoundUpAmount(n: number) { return this.roundUp(n); }
  getTip(n: number) { return parseFloat((this.getRoundUpAmount(n) - n).toPrecision(10)); }
}
 
const japan = new CountryPayment("¥", (n) => Math.floor(n / 100 + 1) * 100);
japan.getRoundUpAmount(3312); // 3400
japan.getTip(3312);           // 88

Ahora el hook y el component no saben nada del país. Reciben este único objeto y se limitan a usar strategy.getRoundUpAmount(amount) y strategy.currencySign. Para añadir un país basta con crear un objeto más, y no hay que tocar ningún archivo.

Pasar por una interface y luego volver a fusionar puede parecer un rodeo innecesario. Yo creo que es la parte del original de la que más se puede aprender. El polimorfismo no era el objetivo, sino una herramienta para hacer visibles lo común y lo diferente, y en cuanto se vio que la diferencia se reducía a una función, se quitó la jerarquía de classes. Más difícil que introducir un patrón es decidir cuándo volver a quitarlo.

Sacar el fetch del hook

Lo último que se extrae es el fetch y la transformación dentro de usePaymentMethods. Un hook es un concepto de React, así que se queda del lado de la view. Si le añades error handling y retry, el hook se hincha enseguida, y si te mudas a otra view library, el hook no sirve. En cambio, una función normal se puede usar en cualquier sitio.

const fetchPaymentMethods = async () => {
  const response = await fetch(`${API}/payment-methods?countryCode=AU`);
  return convertPaymentMethods(await response.json());
};
 
export const usePaymentMethods = () => {
  const [paymentMethods, setPaymentMethods] = useState<PaymentMethod[]>([]);
  useEffect(() => {
    fetchPaymentMethods().then(setPaymentMethods);
  }, []);
  return { paymentMethods };
};

El autor escribe que esta función funciona como una Anti-Corruption Layer o un Gateway. Quiere decir que, aunque cambie la estructura de la respuesta del servidor, lo que hay que tocar se queda en esta única función. Pero los dos nombres no son lo mismo. El Gateway de Fowler es un objeto que envuelve en un solo lugar el acceso a un sistema externo, mientras que Anti-Corruption Layer es un término que viene del DDD de Eric Evans y designa la frontera que traduce un modelo externo con otro sistema de significados para que no contamine el tuyo. Como la respuesta del servidor en este ejemplo es solo { name } y casi no hay diferencias de significado que traducir, creo que Gateway es el nombre más preciso. Ese mismo lugar se convierte en una Anti-Corruption Layer cuando el servidor es un sistema legacy de otro equipo y el propio significado de "método de pago" es distinto.

La estructura final es esta. El render está en los components, el state en los hooks, las reglas en los domain objects y las peticiones de red en funciones.

El autor señala cinco ventajas de dividir así. Es más fácil encontrar dónde está un defecto. Es más fácil reutilizar y combinar código. Es más fácil de leer. Añadir funcionalidades no hace tambalear el conjunto. Y como la domain logic no conoce la view, se puede cambiar solo la view layer. Sobre la última, el propio autor advierte que en la mayoría de los proyectos es algo muy raro. Vale la pena recordar también que ninguna de las cinco viene con mediciones.

Hasta aquí llega el argumento del original. Pero cuando ejecutas este código de verdad, aparecen cosas que en el artículo no se veían.

Lo que se ve al ejecutar el ejemplo

Descargué el repositorio de ejemplo del autor (16 commits, último commit de186c5) y ejecuté tsc --noEmit y los 7 tests. Ambos pasaron, y los helpers cuya definición falta en el original estaban en src/utils.ts del repositorio. Pero al mirar la estructura de cerca encontré tres cosas que conviene saber antes de copiarla.

Una Strategy que se crea de nuevo en cada render

El component de pago recibe la Strategy como prop y, si no se le pasa, crea el valor por defecto con new. Y useRoundUp mete esa Strategy en la dependency de useMemo.

export const Payment = ({
  amount,
  strategy = new PaymentStrategy("$", roundUpToNearestInteger),
}: { amount: number; strategy?: PaymentStrategy }) => {
  const { total, tip } = useRoundUp(amount, strategy); // 안에서 [agreeToDonate, amount, strategy]
  // ...
};

En JavaScript, los default parameters se evalúan en cada llamada. Y useMemo compara las dependencies con Object.is. Cuando se juntan las dos cosas, se crea una instancia nueva en cada render y el memo recalcula cada vez. Hice render de la misma estructura cuatro veces en React 18: con el valor por defecto el cálculo se ejecutó 4 veces, y pasando la misma instancia, 1 vez. El App.tsx del repositorio no pasa Strategy (<Payment amount={19.9} />), así que la ruta de ejecución de la app es exactamente la del valor por defecto.

El cálculo de este ejemplo son unas pocas sumas, así que no tiene coste. El problema es la estructura. Ni el artículo ni el repositorio definen quién crea la Strategy ni dónde se pasa, y solo los tests crean instancias de Japón y Dinamarca. Yo dejaría las instancias como constantes a nivel de module y las sacaría por código de país para pasarlas.

const strategies = {
  AU: new CountryPayment("$", (n) => Math.floor(n + 1)),
  JP: new CountryPayment("¥", (n) => Math.floor(n / 100 + 1) * 100),
} as const;
 
<Payment amount={amount} strategy={strategies[countryCode]} />

El fetch del repositorio no tiene dependency array

El useEffect del código del original tiene [], pero el usePaymentMethods del repositorio no tiene dependency array desde el primer commit hasta el último. Un effect sin array se vuelve a ejecutar en cada render. Cuando llega la respuesta, cambia el state con un array nuevo, eso provoca un render y el effect vuelve a hacer fetch. Como convertPaymentMethods devuelve un array nuevo cada vez, no se detiene.

Cambiando fetch por un mock que responde de inmediato y contando las llamadas durante 300 ms en Jest, en cuatro mediciones salieron 152, 225, 231 y 233. Con [] es 1. Los tests del repositorio solo comprueban que el texto aparece en pantalla, así que no detectan esta repetición y pasan todos. A quien escribió el código siguiendo el original no le pasa; solo afecta a quien usa el repositorio tal cual.

La race que aparece en cuanto el código de país llega como prop

El fetch effect del código del original tampoco tiene cleanup. Synchronizing with Effects, de la documentación oficial de React, dice que si haces fetch dentro de un effect, una respuesta anterior que llega tarde puede pisar la más reciente, así que hay que descartar las respuestas anteriores con un flag ignore. El original solo hace fetch una vez al hacer mount, así que de momento no hay problema. Pero en cuanto el countryCode=AU de la URL se recibe como prop, aparece una dependency y se abre la race. Si yo copiara esta estructura, la escribiría así desde el principio.

useEffect(() => {
  let ignore = false;
  fetchPaymentMethods(countryCode).then((methods) => {
    if (!ignore) setPaymentMethods(methods);
  });
  return () => { ignore = true; };
}, [countryCode]);

Una cosa más: el redondeo del original es Math.floor(amount + 1), así que si el importe ya es entero sube 1 más. Un pedido de 20 dólares pasa a 21. El original solo pone como ejemplo 19,80 dólares y 3312 yenes, así que no se puede saber si es intencionado. Si lo llevas a un servicio real, primero hay que decidir en qué se diferencia de Math.ceil.

Cuándo usar esta estructura

El propio autor dice que dividir no es una regla fija. Un component pequeño y cohesionado se entiende mejor en un solo archivo, y lo que hay que vigilar es que el archivo crezca hasta no poder entenderse. Una app de Todo o una app de un solo formulario puede meterlo todo en components sin problema, y aclara que hizo el ejemplo complicado a propósito para mostrar muchos patrones. Otros materiales ponen salvedades en la misma dirección.

En el mismo artículo sobre layering, Fowler dice que esta separación solo se use en unidades relativamente pequeñas. Tener view, model y data como carpetas de primer nivel está bien en un sistema pequeño, pero si alguna crece demasiado, hay que dividir el primer nivel por dominio y dentro de él por layer. Si copias tal cual las carpetas components/, hooks/ y models/ que vimos antes como estructura de primer nivel de una app grande, acabas con la forma que Fowler dice que hay que evitar.

Dan Abramov tiene una trayectoria parecida. En 2015 propuso dividir en presentational y container components, y en 2019 añadió al principio del artículo una actualización diciendo que ya no recomendaba dividirlos así. La razón era que los Hooks hacen lo mismo sin una división arbitraria, y añadió que había visto demasiadas veces cómo se imponía de forma dogmática sin necesidad. La extracción de hooks del original se parece a lo que dice esa actualización. No hay un component aparte llamado container: Payment, que llama a los hooks, cumple también ese papel.

Sobre el fetch, la documentación oficial de React va un paso más allá. You Might Not Need an Effect dice que extraer la fetch logic a un custom hook facilita migrar después a una estrategia mejor, pero como primera opción recomienda el fetching integrado del framework o una client cache como TanStack Query. Si sacas el fetch a una función normal como en la última etapa del original, puedes pasar esa función tal cual como queryFn de TanStack Query, y la race y las llamadas repetidas de la sección anterior quedan a cargo de la library. Creo que esta es la ventaja más práctica, y el original la menciona en una sola frase. Cómo agrupar claves y funciones lo traté aparte en queryKey.

En resumen, mi juicio es este. El orden del original (hook, pure component, domain object, Strategy, network client) vale la pena seguirlo tal cual, porque en cada etapa la incomodidad de esa etapa se convierte en el motivo de la siguiente. Pero no hace falta llegar hasta el final: basta con ver de qué etapa es la incomodidad que tienes ahora y pararte ahí. Si hay mucho código que no tiene que ver con el render, hasta el hook; si la misma decisión está dispersa, hasta el domain object; si un solo cambio te obliga a tocar varios archivos, hasta Strategy. Y si usas Strategy, decide primero dónde se crean las instancias, y si dejas el fetch en un effect, escribe primero el cleanup y las dependencies. Estas dos cosas que el original omite fueron lo primero que se rompió cuando lo copié de verdad.

No hay una respuesta correcta, pero espero que tú también te pares a pensar de qué etapa es la incomodidad que está sufriendo tu código ahora mismo.

El primer uso que me llamó la atención fue la automatización del navegador. Browserbase abrió un PR que conecta Jev al act() de Stagehand. La estructura era enviar el árbol de accesibilidad de la página como state y preguntar, con opciones cerradas, «cuál es el siguiente elemento que hay que pulsar». En 40 tareas, la mediana de act() bajó de 1,97 segundos a 0,46, y de 147 acciones solo 4 volvieron a un LLM. El punto donde un script de Playwright se rompe en cuanto cambia un selector quedó cubierto por una llamada que devuelve una sola probabilidad. Mientras escribo esto, el PR todavía no se ha fusionado.

La línea que trazó ese PR es la pregunta de este artículo. Acepta la respuesta de Jev a partir de una probabilidad de 0,7 y, si no la alcanza, se la pasa a un LLM. ¿Puedo fiarme de la probabilidad que devuelve ese modelo y trazar con ella una línea en el código?

Con el benchmark de otros no basta para decidirlo, así que quiero verificarlo con mis propios datos. Este blog tiene una compuerta que bloquea los extranjerismos transcritos al hangul. La regla dice que 피커 debe escribirse picker, pero la expresión regular solo atrapa la mitad segura, y las palabras que viven dentro de un compuesto o ya están asentadas en coreano, como 멀티스레드 o 콜 스택, las decido yo a mano cada vez. Solo hay dos respuestas, revertir o dejar, quien sabe decide en un segundo, y el aprobado o el rechazo tiene que decidirse dentro de un script de build sin que nadie lo revise. Tiene la misma forma que la decisión de selector de Stagehand.

Así que el orden es este: qué devuelve Jev, de qué entrenamiento sale esa probabilidad, qué números aparecen cuando le paso mi compuerta y dónde se pueden usar esos números.

Un modelo que no genera texto

La fecha de publicación es el 15 de septiembre de 2026. La empresa no lo llama LLM; lo sitúa en una categoría nueva: System One Model. En este artículo los llamo modelos de decisión. Su fundador, Diogo Almeida, participó en OpenAI como cuarto autor del artículo de InstructGPT. Estuvo en el equipo que creó el método del que ChatGPT desciende en línea directa, y ahora está en el lado que señala los límites de ese método.

Jev no genera frases. Le das de antemano la forma de la respuesta, elige dentro de ella y devuelve además una probabilidad. Solo hay tres tipos de pregunta.

El endpoint también es uno solo. Envías a POST /v1/systemone un state (el contenido que se evalúa), un model y unas questions (el mapa de preguntas), y llega la respuesta. Puedes meter varias preguntas sobre el mismo state en una sola petición, y añadir preguntas apenas alarga el tiempo de respuesta.

Por qué es rápido se explica con la asimetría entre prefill y decode que recogí en cómo funcionan los tokens. Un LLM es lento porque exprime la salida token a token, de forma secuencial, y Jev no tiene esa etapa de decode. Lee la entrada una vez en paralelo y lee la probabilidad directamente. Por eso no hay tarifa alguna de tokens de salida y solo se cobra la entrada, a $0.042 por millón de tokens.

Hay un análisis de un desarrollador llamado Archer Hume que llamó unas 10,000 veces a la API y reconstruyó el comportamiento desde fuera. Con 360 tokens de entrada la mediana fue 57.5ms; con 29,835 tokens, 218ms; y con 1,500 preguntas metidas, 610ms. De todo ello, la evidencia más directa es la observación de que una respuesta con 200 opciones volvía a la misma velocidad que una de 2. Significa que escribir la respuesta no cuesta tiempo.

Decisiones que nadie mira

La velocidad y el precio llaman la atención, pero la pregunta que Almeida lanzó en su artículo de presentación iba por otro lado: si los modelos llevan años siendo sobrehumanos conversando, ¿adónde ha ido toda la automatización?

Su respuesta es que se trata de dos clases de trabajo distintas. Un chatbot, un copilot y un agente de programación tienen como objetivo satisfacer a la persona que mira desde al lado. Las decisiones que se ejecutan en silencio en un servidor y que nadie mira no tienen ese objetivo. Si llamamos assistant a lo primero y automation a lo segundo, todos los modelos publicados hasta hoy se hicieron para lo primero.

Ya hice una distinción parecida al ordenar el diseño de harness. Dentro de un sistema de agentes hay incontables decisiones que nadie mira. ¿Paso esta petición a una persona? ¿Puedo ejecutar este comando? Ahora mismo se las preguntamos todas a un LLM caro. La otra mitad que mi compuerta de expresiones regulares no cubre también es una decisión de ese tipo.

El hueco que dejó RLHF

Pero ¿por qué hacía falta un método de entrenamiento nuevo? ¿No basta con pedirle solo sí/no a un modelo de los de siempre?

La pista está en la calibración. Si la exactitud es qué porcentaje aciertas, la calibración es si sabes qué porcentaje vas a acertar, y la métrica que mide ese desajuste es el ECE (expected calibration error). Es la media de la diferencia entre la probabilidad declarada y la tasa real de acierto en cada tramo de probabilidad, ponderada por la proporción de muestras, así que 0 es la perfección. Pero hay un caso en que esta escala se desajustó tras pasar por RLHF (reinforcement learning from human feedback), que optimiza la preferencia humana. En la Figure 8 del informe técnico de GPT-4, el ECE del modelo preentrenado era 0.007, y el del modelo tras el post-training, 0.074, más de diez veces peor. El informe no da la causa, y yo tampoco encontré una fuente primaria que la establezca. La definición y hasta dónde se conoce la causa los dejé explicados aparte en Calibración y exceso de confianza en los LLM.

Aun así, el ECE por sí solo no basta. Un predictor constante que estampa 0.6 en todas las entradas también tiene ECE 0 si su tasa real de acierto es del 60%. Si la probabilidad solo es honesta pero no se separa caso por caso, no hay sitio donde trazar la línea. Por eso, al margen de la calibración, hay que mirar también si la probabilidad de verdad se separa, y «la proporción que se puede automatizar dentro de un presupuesto de error», que usaré más adelante, es la métrica que reúne esas dos cosas en una sola cifra.

Desde el punto de vista del software, lo que importa es esta parte. Si la probabilidad es honesta y se separa, se puede trazar la línea. Sale una estructura en la que por encima de 0.95 se procesa automáticamente y por debajo se pasa a una persona.

TypeSafe dice haber abierto un tercer camino apuntando a ese lugar: RLHF, que optimiza la preferencia humana; RLVR (reinforcement learning with verifiable rewards), que optimiza respuestas correctas que una máquina puede puntuar; y RLCD, que según ellos optimiza decisiones calibradas.

Ahora bien, de RLCD lo único publicado son tres líneas de contrato de salida. A fecha de 23 de septiembre de 2026, cuando escribo este artículo, no hay artículo ni informe técnico en ninguna parte de la documentación ni del artículo de presentación de TypeSafe. Existe por separado un artículo de ICLR 2024 que usa la misma sigla, pero ahí significa reinforcement learning from contrastive distillation, un método distinto. Conviene no mezclarlos al buscar.

Qué es en realidad confidence

Entonces, ¿es honesto el número que devuelve Jev? Antes de responder hay que ver una cosa. El número que devuelve no es uno solo.

Las respuestas de Choice y Score traen juntos probabilities y confidence. Lo primero es una distribución de probabilidad sobre todas las opciones; lo segundo, un único número entre 0 y 1. Cuando pones un umbral en el código, la mano va primero hacia confidence.

Este valor no lo produce el modelo. El archivo _utils/confidence_metrics.py de system-one-adapter-python, publicado por la organización TypeSafe, tiene 32 líneas en total, y la parte de Choice es así.

def choice_confidence(probs: list[float]) -> float:
    """Scale peak choice probability from uniform to certainty."""
    if len(probs) == 1:
        return 1.0
 
    normalized_probs = _normalize(probs)
    uniform_probability = 1.0 / len(normalized_probs)
    return (max(normalized_probs) - uniform_probability) / (1.0 - uniform_probability)

No hay llamada al modelo ni parámetros aprendidos. Entra un vector de probabilities y sale un número real. Escrito como fórmula es c = (p_max − 1/K) / (1 − 1/K), y si hay tres opciones y la probabilidad máxima es 0.8, da 0.7.

Este repositorio no es el servidor Jev de producción, sino una implementación alternativa que imita la misma API con un LLM. Así que esto por sí solo no permite afirmarlo con rotundidad. Pero hay dos pruebas más que apuntan a la misma fórmula. La página sobre confidence de la documentación oficial de TypeSafe describe este valor como "a statistic computed from the probability distribution" y en su código de demostración incluye (3 × largest probability − 1) / 2 como fórmula aproximada para tres opciones. Con K igual a 3 coincide con la fórmula de arriba. Y un registro de auditoría de afirmaciones dejó anotado que, en la API real, con una respuesta a la que se dieron solo dos opciones, ambas incorrectas, y cuya ganadora valía 0.52, el confidence llegó como 0.04. Con K igual a 2, (0.52 − 0.5) / (1 − 0.5) = 0.04. Coincide con la fórmula.

En el mismo repositorio, Score usa directamente otra fórmula: divide la distancia absoluta media respecto al nivel más frecuente entre la que daría una distribución uniforme y luego lo resta de 1. La documentación no publica la fórmula de Score. Es decir, bajo un mismo nombre, confidence, hay dos fórmulas, y si cambia el tipo el mismo número significa otra cosa. Que Noul no tenga confidence obedece a la misma razón: no hay distribución que plegar.

La documentación tampoco lo esconde. Incluso indica que, si quieres usar otro cálculo, te dará el probabilities completo para que lo hagas a tu manera. Está escrito; el problema está en usarlo sin leerlo.

Pero la tabla comparativa del artículo de presentación pega ambas cosas. Dice "Calibrated: higher confidence means higher accuracy". Quien lo lee entiende que confidence es el valor calibrado, cuando la afirmación de calibración recae en realidad sobre probabilities.

Cuánto se abre esta distinción en cifras es algo que ya se ha medido. Una medición independiente de la calibración publicada por un desarrollador llamado scienthoon midió por separado el ECE que sale al leer confidence como «probabilidad de acertar». En OpenBookQA es 0.035; en HellaSwag, 0.078; y en un conjunto sintético, 0.18. Las probabilidades originales de esos mismos conjuntos eran 0.024, 0.029 y 0.107, respectivamente. En los tres conjuntos, el lado de confidence sale peor.

El porqué del empeoramiento está en la fórmula. Con K fijo, c es una transformación monótona creciente de p_max, así que conserva el orden. El poder discriminativo se mantiene y basta con reescribir el umbral. Lo que se rompe no es la información, sino la escala. Si K cambia de una pregunta a otra, aparece un problema más: también cambia el factor de estiramiento. El mismo p_max de 0.8 se convierte en 0.6 con dos opciones y en 0.75 con cinco. En una carga de trabajo donde se mezclan números de opciones distintos, eso se vuelve un problema en cuanto usas un único umbral.

La calibración cambia según la distribución

Entonces, ¿se puede confiar en el lado de probabilities?

Hay publicado un registro de mediciones hechas llamando de verdad a Jev. En el repositorio de Kev, la implementación de reproducción de código abierto que hizo Jared Palmer, hay un directorio runs/jev-*, y usage.json deja constancia, con "model": "typesafe-ai/jev", de que se trata de llamadas reales pasadas por Vercel AI Gateway. Si se suman los seis directorios jev-* con su usage.json, entre el 18 y el 20 de septiembre de 2026 se hicieron 5,364 llamadas, con 2,418,260 tokens de entrada. De los siete conjuntos de abajo, scienthoon se importó convirtiendo los archivos de resultados de ese desarrollador, así que no está incluido en este total.

Que el precio cobre realmente solo la entrada se confirma en otro sitio. El autor del benchmark de phishing lo anotó mirando el dashboard de TypeSafe. De los 4.56 millones de tokens de dos ejecuciones, 3.66 millones fueron de entrada y 900,000 de salida, y el cargo fue de $0.15, una cifra que coincidía con calcular solo la entrada.

Si se sacan del report.json de ese mismo directorio las métricas de los siete conjuntos de evaluación y se ordenan, queda así. Abajo, la confianza no es el campo confidence, sino el máximo de probabilities. El exceso de confianza es 평균 확신도 − 정확도 (confianza media menos exactitud) y en total son 5,743 casos. Los valores son los del bloque clean, que excluye de la puntuación de exactitud las entradas «desconocido», aquellas cuya base de juicio se ha borrado.

Se leen dos cosas.

Primera: el ECE se mueve casi diez veces. Va de 0.011 a 0.105. Mismo corrector, mismo modelo. «Está calibrado» no es una propiedad del modelo, sino una relación entre el modelo y la distribución. Que la calibración se venga abajo cuando cambia la distribución es un resultado ya conocido. Lo nuevo aquí es que la misma forma aparece también en un modelo que presenta la calibración como objetivo de entrenamiento.

El 0.105 del conjunto con mayor ECE es incluso mayor que el 0.074 del GPT-4 post-RLHF que vimos antes. Ahora bien, estos dos no deben leerse como un ranking. Las tareas son distintas, y el ECE es un estimador cuyo valor se mueve según en cuántos tramos se divida y en qué tramo se acumulen las muestras, de modo que enfrentar cifras salidas de correctores distintos no constituye una comparación válida.

Segunda: el ECE medido se explica casi por completo con el exceso de confianza. La diferencia entre ambas columnas está, en los siete casos, entre 0.002 y 0.011. Como el ECE es la media ponderada de las brechas por tramo, no puede ser menor que el exceso de confianza global; que esa diferencia sea casi 0 significa que el signo del desajuste de cada tramo se inclina en una sola dirección. No es ruido que se cruce y se cancele entre tramos.

Por qué ocurre se ve leyendo la tabla en vertical. Si quitamos semif, seis valores de confianza media se apelotonan entre 0.851 y 0.906. En ese mismo rango, la exactitud se mueve entre 0.753 y 0.857, el doble de ancho. La confianza apenas se mueve aunque cambie la distribución; solo se mueve la exactitud. La diferencia que queda es directamente el ECE.

Otro benchmark muestra cómo se manifiesta esta propiedad en la práctica. En una medición sobre 2,000 correos de phishing con Claude Haiku 4.5 como grupo de control, la exactitud de Jev fue del 62.6% y la de Haiku del 81.3%. Pero lo que más llama la atención es el ECE. El ECE que reporta el repositorio es 0.154 para Jev y 0.097 para Haiku, y si el registro de auditoría de afirmaciones vuelve a medir el valor P(phishing) de Jev en 10 tramos de 0 a 1, sale 0.170. Se lea como se lea, el modelo que presenta la calibración como objetivo de entrenamiento perdió en calibración frente a un LLM hecho con RLHF. El mismo autor sacó un 91.6% solo con una regla de lista de hosts de enlaces.

Si se mira la misma métrica en varios conjuntos, la amplitud queda más clara. La proporción que se puede automatizar con un presupuesto de error del 5% es 0.486 en el conjunto scienthoon, 0.695 en transfer-v9 y 1.000 en semif. El corrector de Kev anota que este valor es el máximo obtenido eligiendo el umbral dentro de la muestra, y no una garantía de error tras el despliegue. Ninguna de ellas debe citarse como si fuera una especificación del modelo.

La compuerta de transcripciones

Leer el benchmark de otro y medir sobre mis propios datos son cosas distintas. Así que hice pasar de verdad por el modelo la compuerta del principio.

Todavía no tengo una clave de API de Jev. En su lugar ejecuté en local el Kev-9B que mencioné antes. Es una implementación de reproducción que monta un LoRA de rank 16 y una pointer head sobre Qwen3.5-9B-Base, con licencia Apache-2.0. Las cifras de abajo no son las de Jev. Los datos de entrenamiento de Kev son tareas de decisión en inglés, y en la medición de su propio autor Kev-9B queda por detrás de Jev incluso en tareas en inglés: su proporción de automatización con un presupuesto de error del 5% va de 0.45 a 0.57, mientras que la de Jev es 0.70, y en MMLU-Pro es 0.52 frente a 0.84. Además, la propia documentación de TypeSafe declara sobre Jev que el inglés es su lengua principal de entrenamiento y el CJK no está al mismo nivel.

El conjunto de evaluación lo saqué de 18 artículos en coreano de este repositorio. El criterio de verdad de las etiquetas es con qué grafía escribe este repositorio esa palabra de forma consistente. Es decir, no es el consenso de la comunidad de documentación técnica coreana, sino la costumbre de este blog; en las palabras donde ambas cosas divergen, el modelo puede acertar según el criterio de la comunidad y fallar según este.

• Conjunto de la compuerta, 102 frases: Son palabras que la compuerta ya conoce. Los positivos son 23 frases contrafácticas en las que palabras que el texto escribe en inglés, como calendar, picker o adapter, se han devuelto a su transcripción en hangul; los negativos son 79 frases en las que aparecen de verdad palabras que write-post.md declara como excepción, como 리렌더링 o 콜 스택. Aquí la compuerta de expresiones regulares actual acierta el 100% por definición.
• Conjunto en reserva, 60 frases: Son palabras que la compuerta no ha visto nunca. Es lo que en machine learning se llama conjunto held-out. Los positivos son 30 casos en los que loader, mutation y prefill, que el texto escribe solo en inglés, se han devuelto a su transcripción; los negativos son 30 casos con 리듀서, 스냅샷 y 런타임, que el texto escribe solo en hangul. Aquí la expresión regular no atrapa ni un solo positivo.

Dejo dicho de entrada el desequilibrio de que los positivos son frases contrafácticas escritas por mí y los negativos son frases reales. Y la muestra efectiva no es el número de frases, sino el número de palabras. Como la etiqueta se decide por palabra, las frases en las que aparece la misma palabra no son observaciones independientes. El conjunto de la compuerta tiene 24 palabras distintas y el conjunto en reserva, 13.

La tabla de abajo agrega solo una pregunta noul, la que pregunta «¿hay que devolver esta palabra al inglés?». Metí cuatro preguntas en la misma petición, pero las otras tres eran la forma negativa, una variante de Choice y un juicio sobre compuestos cuya etiqueta no conseguí fijar bien, así que no las mezclo aquí. La proporción de automatización con presupuesto del 5% es la proporción máxima que se obtiene cortando desde la confianza más alta hacia abajo sin que el error del tramo superior pase del 5%.

La línea base de clase mayoritaria es la puntuación que se obtiene sin leer la frase, estampando siempre la etiqueta más frecuente. El modelo queda por debajo de eso.

La última fila es la respuesta de este experimento. En el conjunto en reserva, por muy alto que pusiera el umbral, no hubo ni una sola decisión que pudiera procesarse automáticamente dentro de un 5% de error.

Mirando la distribución de predicciones se ve qué ocurrió. El modelo respondió «hay que devolverla» en las 162 frases. En las 37 palabras distintas, todas. Acertó todos los positivos y falló todos los negativos. Por eso el 0.500 del conjunto en reserva no es habilidad: es la cifra que sale porque el conjunto está equilibrado.

Y con eso la confianza media era 0.876. En el conjunto de la compuerta, el 49% superó una confianza de 0.9, y el acierto real de ese tramo es 0.240.

Tampoco se cumplió la identidad estructural. Al sumar las probabilidades de «¿hay que devolverla?» y «¿hay que dejarla como está?», en el conjunto de la compuerta salió una media de 1.655, y las 102 frases se desviaron de 1 en más de 0.1.

Es así por diseño. Las dos preguntas son evaluaciones separadas que no se leen entre sí, y la propia TypeSafe incluye en su página sobre jaggedness un ejemplo en el que refund 0.72 y not_refund 0.47 suman 1.19.

El punto que engancha en la práctica es este. Un umbral ajustado para Noul no debe trasladarse a Choice. Siendo el mismo juicio, las frases en las que la conclusión difería fueron entre el 14% y el 17%.

Si fuera un modelo que dice que sí a cualquier cosa que le preguntes, este resultado no significaría nada. Empecé por comprobar eso.

Lee coreano, dice «no» y separa 0.02 de 0.98. No es un sesgo global de complacencia. Lo que esto descarta llega hasta ahí. Queda la posibilidad de que la redacción misma de la pregunta de la compuerta sea mala.

El resultado de meter las reglas en el state

Entonces, ¿cambia algo si le doy directamente el conocimiento que hace falta para decidir? El método de adaptación a un dominio que recomienda la documentación de TypeSafe es este: sin tocar los pesos, envías el material de referencia dentro del state.

Cogí los párrafos de reglas que ya están escritos en write-post.md, los metí también en el state y volví a ejecutarlo. La entrada pasó de 100 tokens por frase a 450. El conjunto de la compuerta es una filtración, porque ese material de referencia enumera por su nombre tanto las palabras de la compuerta como las excepciones. Por eso ese lado es el grupo de control que sirve para ver «si al menos lee el material de referencia», y la prueba de verdad es el conjunto en reserva.

La latencia corresponde a inferencia local en un M2 Max, así que no está en el mismo eje que la latencia de la API de Jev que vimos antes. Lo que hay que mirar aquí no es el valor absoluto, sino el factor de 2.4 que aparece al meter el material de referencia.

En el conjunto en reserva, que está equilibrado, la exactitud por frase pasó de 0.500 a 0.500: no se movió en absoluto. Por palabra incluso bajó, de 7/13 a 5/13.

El salto de 0.225 a 0.676 en el conjunto de la compuerta no es una mejora de habilidad. Antes respondía «se devuelve» en las 102 frases, y al darle el material de referencia solo respondió así en 12. Los negativos subieron de 0/79 a 68/79, pero los positivos se hundieron de 23/23 a 1/23. En ese conjunto los negativos ganan por 79 a 23, así que una constante del tipo «déjalo casi siempre» recibe automáticamente una puntuación más alta. No aprendió a distinguir: cambió la inclinación.

Eso no significa que el modelo no lea las frases. Con las mismas frases de las mismas palabras, al darle el material de referencia las predicciones se dispersaron frase a frase. La desviación típica de 로더 subió de 0.096 a 0.217, y la de 뮤테이션 de 0.042 a 0.236. Lee, pero no distingue.

Y este resultado también sacude la interpretación de la sección anterior. Si un solo texto del state da la vuelta por completo a la salida, el «devolverlas todas» de la primera ejecución podría no ser un límite del modelo, sino una carencia en la redacción de la pregunta. Este artículo no ha podido descartar esa posibilidad.

Una cosa sí mejoró de forma visible. La suma de las probabilidades de «se devuelve» y «se deja» se acercó, en el conjunto en reserva, de 1.508 a 0.963, y las frases que se alejaban mucho de 1 bajaron de 59 a 18. Pero la exactitud no se movió. Que las probabilidades de dos preguntas encajen entre sí y que esas probabilidades sean correctas son cosas distintas.

El lugar de los modelos de decisión

Visto hasta aquí, es fácil inclinarse a concluir que toda esta categoría de modelos es inútil, pero poner uno al lado de otro los benchmarks publicados dice que no es así.

Solo la fila de rerank es una métrica de calidad de ranking de búsqueda, así que está en un eje distinto del de la exactitud de las demás filas.

Dentro de la distribución, una expresión regular o un clasificador ya ajustado gana o empata. Es el mismo lugar en el que, en mi conjunto de la compuerta, la expresión regular ganó por 1.000 a 0.225. Si puedes reunir etiquetas, entrenar un modelo pequeño sale más barato, más rápido y más exacto. Eso es algo que se hace desde hace mucho.

La brecha se abre cuando la distribución es nueva y no hay etiquetas. En el spam fuera de la distribución, 98.6% frente a 73.0%. El clasificador ajustado se viene abajo ante una forma que no ha visto nunca, y este aguanta. El lugar de los modelos de decisión son las decisiones para las que no se pueden reunir datos, etiquetarlos y entrenar. Es el sitio donde cada situación es nueva, no se logran reunir etiquetas y aun así hay que decidir en cuestión de segundos.

Este marco explica también por qué falló mi discriminación de transcripciones. Lo que esa decisión necesita no es razonamiento general, sino el conocimiento de dominio concreto de qué palabras se han asentado en la documentación técnica coreana, y para una implementación de reproducción de 9B entrenada con tareas de decisión en inglés eso no está fuera de la distribución: sencillamente no existe en ella. Ahí está la razón de que tampoco funcionara darle las reglas por escrito.

En un artículo de TechCrunch, Armin Ronacher, CTO de Earendil, la empresa que hace el harness Pi, dijo lo siguiente.

At the end of the day, it delegates the hallucination problem a little bit to the user.

No ha eliminado la alucinación: ha pasado la decisión al desarrollador. La documentación de TypeSafe también escribe que la calibración es una propiedad que se cumple sobre un conjunto de predicciones y no una garantía de que una respuesta individual sea correcta, y bajo la barra del 0% de tasa de alucinación del artículo de presentación, en el apartado Nuance, se lee "Our number is not empirical". El formato está garantizado; el contenido no.

Los 194 proyectos de jevable

Como en mis datos falló, fui a ver dónde lo usan los demás. jevable.com es una curación independiente en la que un desarrollador llamado Nikunj revisa y reúne los proyectos con Jev que aparecen en X. A fecha de 23 de septiembre de 2026 son 194, y las fechas de alta se concentran entre el 16 y el 20 de septiembre de 2026. 152 entraron en un solo día, el 18 de septiembre. Tres días después del lanzamiento.

Si en vez de por categoría se reagrupan por «qué se le pregunta», salen tres formas. Las cifras de abajo son las que cada autor escribió en su propia publicación.

Primera, clasificación y enrutamiento. Clasificar 1,500 correos, clasificar documentos fiscales, clasificar 1,891 anuncios de la competencia en 19 segundos por $0.12, 14 typed checks sobre un único diff de PR, detectar publicidad en las notificaciones de Android, clasificar 26 planos de construcción en 2.9 segundos. Es la misma forma que la compuerta de transcripciones del principio. Como decía la tabla de la sección anterior, son lugares donde las etiquetas se acumulan cada día, así que con el tiempo un clasificador pequeño entrenado con tus propias etiquetas gana o empata. La ventaja de Jev está en el primer día, cuando no hay etiquetas.

Segunda, bucles de selección de acciones. Un browser agent enganchado a Browser Use que terminó una búsqueda de vuelos en 7 segundos por $0.0039, un computer use que maneja el Mac por voz, un juego que cada vez que Mario muere hace fork de la VM en cuatro ramas y elige la que sobrevive, un motor de expresiones faciales que decide en cada mensaje diez cosas de un personaje 3D, como la boca, las cejas y la mirada. El action space cambia en cada paso, así que no se pueden reunir etiquetas, y la decisión tiene que bajar por debajo del segundo. Es el mismo lugar en el que la diferencia se abrió con el spam fuera de la distribución. Creo que también por eso Games es la categoría más grande, con 39. Un juego es un bucle de selección de acciones en el que equivocarse tiene vuelta atrás.

Tercera, interfaces que muestran la probabilidad al usuario. Ask Jev, que devuelve solo el veredicto en lugar de una respuesta; JevForm, un formulario ramificado que elige la siguiente pregunta por probabilidad; Upweight, que reordena la portada de Hacker News con seis deslizadores como profundidad técnica y drama. Como el umbral no está metido en el código y es una persona quien lee la probabilidad, es donde menos pesa la exigencia de calibración que este artículo ha puesto en cuestión.

Una cosa llama la atención. De las 194 descripciones, 30 anotan el coste y 53 la velocidad, pero solo 7 anotan la exactitud o una línea de base. Los resúmenes solo recogen el inicio de cada post, así que es una cota inferior, pero la dirección está clara. Que es rápido y barato se sabe el primer día; si acierta, solo se sabe midiendo, y los que miden son pocos. Uno de esos 7 es jevcal. Su autor dice que todo el mundo elige el umbral a ojo, y la herramienta devuelve el umbral y la proporción de procesamiento automático a partir de tus datos y la exactitud objetivo. Es exactamente el procedimiento que recomienda la sección siguiente, convertido en herramienta.

Cómo trazar la línea

La conclusión de este artículo es esta. No leas como una especificación la probabilidad que devuelve el modelo: mídela tú mismo sobre tus propios datos y traza ahí la línea.

El procedimiento para medir es este. Reúnes un centenar largo de casos etiquetados, construyes una tabla de tasa real de acierto por tramo de probabilidad y vas bajando el umbral desde arriba mirando la tasa de error del tramo superior. Si has fijado un presupuesto de error, la cobertura máxima que respeta ese presupuesto es justamente la proporción que puedes automatizar. Que en mi experimento el acierto real del tramo con confianza de 0.9 o más fuera 0.240 salió a la luz con 102 frases.

Una escala desajustada suele poder arreglarse. Si el exceso de confianza está repartido de forma uniforme por todos los tramos, una sola temperatura lo corrige casi del todo. Kev hizo justamente eso y bajó su ECE de 0.106 a 0.042. El problema es que ajustar esa temperatura exige tener las etiquetas de esa distribución, y eso es exactamente lo que no hay en producción. Además, la temperatura no puede cambiar el orden de las probabilidades, así que la proporción automatizable no sube en la misma medida. Por eso el orden importa más que la escala, y la cobertura bajo presupuesto de error es una métrica más práctica que el ECE.

Si hubiera clavado en el código el 0.9 que la documentación usa en su ejemplo, esta compuerta habría corregido mal, en silencio, 38 casos. Como no salta ningún error, es un fallo difícil de advertir. La documentación de TypeSafe también escribe, justo debajo de ese ejemplo, que lo pruebes con tus propios datos. Lo que acaba clavado en el código no suele ser la frase de debajo, sino el número de arriba.

Aunque no tengas clave, medir puede empezarse hoy mismo. Kev está publicado bajo Apache-2.0 y corre en un portátil.

Me gustaría que contaras cuántas llamadas del servicio que operas le preguntan solo sí/no a un modelo grande. Antes de mover esas llamadas a un modelo de decisión, te recomiendo medir primero dónde habría que trazar la línea después de moverlas. Yo pude decidir no tocar la compuerta porque respeté ese orden. Cuando consiga una clave de Jev pienso volver a pasar el mismo conjunto, y si entonces cambia la conclusión, también lo escribiré.

Me gusta el código declarativo. Abrir un overlay, cerrarlo y hacer trabajo asíncrono dentro de él es una secuencia que, en mi opinión, debería gestionar el propio overlay. Cuando quien llama guarda isOpen y lo enciende y apaga, el código que maneja el estado acaba en un lugar distinto del componente que lo dibuja.

Pero los modales de las pantallas de las que me ocupaba en la empresa eran justo lo contrario. Si un modal estaba abierto vivía en un store global, quien llamaba lo abría y quien llamaba lo cerraba. También era quien llamaba el que escribía el código que cerraba el modal y los callbacks que recibían su resultado. Por eso estuve mucho tiempo pensando cómo llevar esto hacia algo declarativo, y al final lo reescribí.

Mientras hacía ese trabajo miré overlay-kit. Se parecía a la interfaz que yo buscaba. Este artículo recoge la interfaz declarativa de overlay-kit y cómo diseñé el sistema de modales interno.

El modal que guardaba en estado

En mi artículo sobre gestión de estado puse el indicador de apertura de un modal como el ejemplo más simple de estado local. Escribí que es estado que se usa dentro de un solo componente y que el exterior no necesita ni tiene derecho a conocer. Sigo pensando que es cierto. Pero en cuanto tienes decenas de tipos de modal, se superponen entre sí y deben devolver un valor a quien los llamó, ese estado deja de quedarse dentro del componente.

El código que heredé guardaba la lista de modales abiertos en un store global. Como es código de la empresa, el ejemplo siguiente conserva la estructura y cambia los identificadores.

const [openPopup, closePopup] = useModalStore(
  useShallow((state) => [state.openPopup, state.closePopup]),
);
 
const handleAddNote = useCallback(() => {
  openPopup(PopupType.ADD_NOTE, {
    itemId,
    onClose: () => closePopup(PopupType.ADD_NOTE),
    onSubmit: (note) => {
      closePopup(PopupType.ADD_NOTE);
      saveNote(note);
    },
  });
}, [closePopup, openPopup, itemId]);

Tres cosas de este código me incomodaban.

Primera: hay que sacar la función de apertura de un hook. openPopup y closePopup son valores que se seleccionan del store, así que solo se pueden obtener dentro de un componente. Eso significa que el código que abre un modal no puede salir del componente. Para abrir un modal desde un sitio donde no puedes usar hooks, como un interceptor de respuestas de la API o un guard del router, tienes que ir pasando esa función como argumento.

Segunda: el resultado vuelve por callbacks. Si se guardó la nota o si el usuario simplemente cerró el diálogo llega por dos ramas distintas, onSubmit y onClose. Todo lo que quieras hacer después de abrir el modal entra dentro de un callback. Y si tienes que abrir dos modales seguidos, aparece un callback dentro de otro callback.

Tercera: cerrar es responsabilidad de quien llama. Es quien llama el que invoca closePopup(PopupType.ADD_NOTE). El modal no se cierra a sí mismo: el lado que lo abrió recuerda de qué tipo de modal se trata y lo cierra. Por eso la misma constante aparece tres veces en una sola función.

Lo que las tres tienen en común es que abrir un único modal obliga a quien llama a escribir tres clases de código: el que lo abre, el callback que recibe el resultado y el que lo cierra.

Si decidir qué mostrar es tarea de quien llama, aquí quien llamaba cargaba además con todo lo que venía después. En particular, closePopup(PopupType.ADD_NOTE) señala su objetivo con una constante de texto. Escribir la constante de otro modal sigue pasando la comprobación de tipos porque pertenece al mismo enum, y se cierra el modal equivocado.

Una interfaz que espera un resultado

Entonces, ¿cuál de las tres se puede quitar? La respuesta a la que llegué fue convertir la apertura de un modal en una llamada a función y hacer que esa función devuelva una Promise con el resultado.

const result = await openModalAsync('ADD_NOTE', { itemId });
if (result.reason !== 'confirmed') return;
 
await saveNote(result.value);

Cambiaron tres cosas. La función de apertura pasó a ser una función de módulo en lugar de un hook, así que se puede llamar fuera de un componente. El resultado pasó a ser un valor de retorno en lugar de un argumento de callback, así que el trabajo posterior se quedó dentro del flujo de la función que llama. Y cerrar pasó a ser tarea del propio componente del modal.

Como el tipo de retorno es Promise<ModalResult<V>>, el final del modal se concentró en un único valor.

Una Promise termina una sola vez. Resolver una Promise ya resuelta no hace nada, así que todos los motivos por los que un modal puede terminar tienen que caber en ese único valor. Por eso dividí reason en cinco casos: el usuario confirmó, el usuario canceló explícitamente, se cerró sin valor, fue reemplazado por un modal nuevo del mismo tipo, o se cerró a la fuerza en una limpieza general. Con un solo booleano, «cancelado» y «se desmontó la pantalla entera» serían el mismo valor, y en los flujos que necesitan limpieza hay que distinguir esos dos casos.

En la dirección contraria, si nunca la terminas, quien llama espera para siempre. No pasa nada cuando un callback no se invoca, pero un await simplemente no regresa. Por eso, cada vez que aparecía un camino nuevo para quitar un modal de la pantalla, tenía que comprobar si ese camino también terminaba la Promise. El reemplazo y el cierre forzado tienen cada uno su propio reason justamente por eso.

El punto de llamada de overlay-kit

El punto de llamada de overlay-kit, de toss, tiene este aspecto.

const confirmed = await overlay.openAsync<boolean>(({ isOpen, close }) => (
  <ConfirmDialog
    open={isOpen}
    onConfirm={() => close(true)}
    onCancel={() => close(false)}
  />
));

Hay tres puntos que me parecieron una buena interfaz.

Qué se abre está en el punto de llamada. Mi versión pasa una clave de texto, 'ADD_NOTE'. Qué componente es esa clave lo sabe un archivo de registry: un archivo que contiene un único objeto que empareja cada clave de texto con la función import() que carga ese modal.

export const modalImporters = {
  ADD_NOTE: () => import('.../add-note-modal'),
  CONFIRM: () => import('.../confirm-modal'),
  // 모달 종류만큼 이어진다
} as const;

overlay-kit escribe el JSX ahí mismo. Quien lee el código sabe qué va a aparecer sin tener que ir a ese archivo.

El tipo del resultado se decide en el punto de llamada. El argumento de tipo de openAsync<boolean> es a la vez el tipo del argumento de close y el tipo del resultado del await. No hace falta declarar un tipo de resultado por modal y registrarlo en una tabla.

Cerrar y eliminar están separados. El controlador recibe cuatro props: overlayId, isOpen, close y unmount. close pone isOpen en false y deja el componente donde está. unmount es lo que realmente lo elimina. La guía oficial sobre abrir y cerrar overlays lo explica así.

Esta diferencia se debe a que, al usar close, el overlay se mantiene en memoria para poder mostrar su animación de cierre.

Mi versión no tiene esa distinción. Al cerrar, sale de la lista de inmediato. Eso significa que estaba dejando las animaciones de cierre en manos de la librería de componentes, y que solo trataba con pantallas donde eso era posible.

De overlay.open al render

Cuando te gusta una interfaz, lo siguiente que te preguntas es qué hay dentro. Para que una sola función de módulo dibuje un componente dentro del árbol de React, algo tiene que unir ambos lados.

Eventos y reducer

overlay.open no cambia el estado. Emite un evento.

// packages/src/event.ts
const open = (controller: OverlayControllerComponent, options?: OpenOverlayOptions) => {
  const overlayId = options?.overlayId ?? randomId();
  const componentKey = randomId();
  const dispatchOpenEvent = createEvent('open');
 
  dispatchOpenEvent({ controller, overlayId, componentKey });
  return overlayId;
};

Quien lo recibe es OverlayProvider. El provider tiene un useReducer, se suscribe al evento y mete ADD en el reducer. Lo que hay que mirar con atención aquí es que isOpen entra como false.

// packages/src/context/provider/index.tsx
const [overlayState, overlayDispatch] = useReducer(overlayReducer, {
  current: null,
  overlayOrderList: [],
  overlayData: {},
});
 
const open: OverlayEvent['open'] = useCallback(({ controller, overlayId, componentKey }) => {
  overlayDispatch({
    type: 'ADD',
    overlay: { id: overlayId, componentKey, isOpen: false, isMounted: false, controller },
  });
}, []);

Y en el frame siguiente al montaje del controlador mete OPEN para poner isOpen en true.

// packages/src/context/provider/content-overlay-controller.tsx
useEffect(() => {
  requestAnimationFrame(() => {
    overlayDispatch({ type: 'OPEN', overlayId });
  });
}, [overlayDispatch, overlayId]);

Aquí hubo una parte que no coincidió con lo que esperaba.

El estado no está fuera de React. Como es una API que abre mediante una función de módulo, supuse que el store también estaría a nivel de módulo, pero en realidad es un useReducer dentro del provider. Lo único que está fuera de React es el bus de eventos, y ese no guarda estado. Los overlays se renderizan como hermanos junto a los children del provider. No usa createPortal ni importa react-dom.

Hay algo más que llama la atención. Desde el punto de llamada es una sola línea, overlay.open(), pero dentro hay un procedimiento con un orden fijo: emitir un evento, meter ADD en el reducer, esperar un frame y volver a meter OPEN. Una interfaz declarativa no elimina el código imperativo: lo mueve al otro lado de una frontera.

El lado que abre y el lado que cierra

El requestAnimationFrame que acabamos de ver y la separación entre close y unmount de la sección anterior parecen cosas distintas a primera vista. En realidad son dos mecanismos que tapan los dos extremos de la misma restricción.

Esa restricción es que una transición de CSS solo funciona si tanto el estado inicial como el final se renderizan de verdad. La guía de transiciones CSS de MDN advierte sobre los elementos recién añadidos al DOM.

This is treated as if the initial state had never occurred and the element was always in its final state.

El fallo aparece con dos formas. Al abrir no hay estado inicial, así que no se ejecuta; al cerrar el elemento desaparece antes de que se pinte el estado final, así que tampoco.

La última fila explica por qué el lado que cierra queda en manos de quien usa la librería. En el lado que abre, la librería conoce la constante: basta con un frame. En el lado que cierra, la librería no puede saber si la animación dura 200 o 400 milisegundos.

El cierre entregado como unmount

Lo que sostiene el lado que cierra está en el reducer. CLOSE solo invierte, dentro de overlayData, el valor isOpen, y no toca overlayOrderList. El provider renderiza recorriendo esa lista, así que el componente sigue vivo mientras permanezca en ella. Solo se desmonta cuando REMOVE lo saca.

Dicho esto, rAF no siempre es necesario. react-transition-group no ejecuta la transición de entrada en el primer montaje de forma predeterminada. La salta incluso cuando in ya es true, y hay que activar appear. El rAF de overlay-kit cambia isOpen de false a true después del montaje, lo que cubre ese caso.

Veinte líneas envueltas en una Promise

openAsync no es una implementación aparte, sino una capa fina alrededor de open.

// packages/src/event.ts
const openAsync = async <T>(controller: OverlayAsyncControllerComponent<T>, options?: OpenOverlayOptions) => {
  return new Promise<T>((_resolve, _reject) => {
    open((overlayProps, ...deprecatedLegacyContext) => {
      const close = (param: T) => {
        _resolve(param);
        overlayProps.close();
      };
      const reject = (reason?: unknown) => {
        _reject(reason);
        overlayProps.close();
      };
      const props: OverlayAsyncControllerProps<T> = { ...overlayProps, close, reject };
      return controller(props, ...deprecatedLegacyContext);
    }, options);
  });
};

Todo lo que hace es sustituir el close que llega al controlador. El close original no recibe argumentos; este recibe uno, resuelve la Promise con él y después llama al close original. Esta es también la razón por la que el tipo del resultado se decide en el punto de llamada. T es a la vez el tipo del argumento de close y el tipo de la Promise.

Aun así, esta estructura tiene un agujero. La resolución solo ocurre cuando se llama a close. Por eso, si quitas un overlay únicamente con unmount, la Promise se queda pendiente para siempre. Está registrado en el issue #169 y creo que hay que arreglarlo, pero el issue sigue abierto.

Que la resolución ocurra en close tiene otra implicación. Es el momento en que empieza el cierre, no el momento en que termina la animación de cierre. Eso da igual en un flujo que pide confirmación y luego llama a una API, pero en un flujo que pide confirmación y luego abre el siguiente modal, el segundo sube mientras el primero todavía está desapareciendo.

Donde el diseño dio la vuelta completa

Seguí el historial de commits para explorar cómo llegó aquí el diseño, y descubrí que la estructura no fue así desde el principio. La 1.0 usaba la misma combinación de eventos y reducer que hoy. La 1.2.0 movió el estado a un store externo a nivel de módulo que se leía con useSyncExternalStore, y la 1.8.0 lo devolvió a un reducer.

El motivo de la vuelta atrás está escrito en el issue #148.

useSyncExternalStore resolves tearing issues, but it doesn't work well with suspense.

Cuando obtener datos dentro de un overlay lo hacía suspender, React avisaba de que un componente había suspendido mientras respondía a una entrada síncrona. El objetivo original de pasar a un store externo era poder leer el estado del overlay sin un hook, y el PR de entonces dice sin rodeos que el objetivo no se logró de la forma prevista. Al final el objetivo se resolvió con un hook y solo el mecanismo de almacenamiento volvió a su sitio original.

Lo que me llevo de este registro no es una conclusión, sino un criterio. Poner el estado fuera de React libera desde dónde puedes llamar, a cambio de abrir la puerta a desencajarse de la planificación de React. overlay-kit dejó fuera solo el punto de llamada y mantuvo el estado dentro.

Al reabrir con el mismo id

Algo me llamó la atención leyendo el reducer. Justo al principio de ADD hay esta rama.

// packages/src/context/reducer.ts
case 'ADD': {
  if (state.overlayData[action.overlay.id] != null && state.overlayData[action.overlay.id].isOpen === false) {
    const overlay = state.overlayData[action.overlay.id];
    if (overlay == null || overlay.isOpen) {
      return state;
    }
    return {
      ...state,
      current: action.overlay.id,
      overlayData: { ...state.overlayData, [action.overlay.id]: { ...overlay, isOpen: true } },
    };
  }
  // ...

Si abres un overlay indicando un overlayId, haces close y luego lo vuelves a abrir con el mismo id, entras en esta rama. Pero el valor de retorno reutiliza el objeto overlay existente.

Nada usa nunca el action.overlay entrante ni su controller.

Leerlo no me bastaba para estar seguro, así que cloné el repositorio de la librería y le añadí una prueba yo mismo. Preparé dos componentes que dibujan contenidos distintos y los abrí en orden con el mismo id.

const ControllerA = ({ isOpen }: { isOpen: boolean }) => (isOpen ? <div data-testid="b">AAA</div> : null);
const ControllerB = ({ isOpen }: { isOpen: boolean }) => (isOpen ? <div data-testid="b">BBB</div> : null);
 
overlay.open(ControllerA, { overlayId: 'id-close' });
overlay.close('id-close');
overlay.open(ControllerB, { overlayId: 'id-close' });

Estos fueron los resultados, ejecutados con vitest sobre la rama main en la versión 1.9.0 de overlay-kit.

La tercera fila es un comportamiento que la documentación describe como una función, así que salió como esperaba. El problema es la primera fila.

El JSX nuevo se ignora

Aquí comprobé una cosa más. Más abajo, en el mismo reducer, hay este comentario.

/**
 * @description Brings the overlay to the front when reopened after closing without unmounting.
 */
overlayOrderList: [...state.overlayOrderList.filter((item) => item !== action.overlay.id), action.overlay.id],

Dice que reabrir después de cerrar trae el overlay al frente. Pero como la rama anterior llega antes a return, esta línea no se ejecuta en esa situación. Apilé dos overlays, hice close sobre el de abajo, lo volví a abrir y el orden del DOM no cambió.

Un comportamiento que contradice el comentario

Eso sí, no comprobé si esto se manifiesta como un problema visible en pantalla. La prueba solo miró el orden del DOM y, como la mayoría de las librerías de diálogos usan su propio z-index o portales, el orden del DOM no equivale al orden visual.

Mi versión expone esta misma situación como una opción. Al reabrir un modal del mismo tipo, quien llama elige si conservar el existente o reemplazarlo con props nuevas. Si elige el reemplazo, la Promise existente termina como replaced. Esta es una de las razones por las que antes dividí el tipo del resultado en cinco ramas.

Aquí es donde divergen los dos diseños. Mi enfoque trata los modales como datos. Como la clave de texto y las props viven en un store, se pueden reemplazar o actualizar más tarde. overlay-kit trata los modales como funciones. El controlador es un closure, así que una vez guardado no hay forma de cambiar su contenido desde fuera.

El precio del JSX en el punto de llamada

Entonces, ¿escribir JSX en el punto de llamada es siempre mejor que usar una clave de texto? Creo que no. Hay tres precios que pagar.

La división de código deja de ser lo predeterminado. Escribir JSX en el punto de llamada significa que quien llama importa ese componente. Si el modal es una pantalla de edición pesada y solo unos pocos usuarios pulsan ese botón, ese peso entra en el bundle de la pantalla de listado.

React.lazy sí funciona dentro de un controlador. Lo medí igual que en la prueba anterior: el módulo no se cargaba antes de open y, al abrirlo, primero aparecía el fallback de Suspense y después se renderizaba el contenido.

const Heavy = React.lazy(() => import('./HeavyModal'));
 
overlay.open(({ isOpen, close }) => isOpen ? (
  <Suspense fallback={<Spinner />}><Heavy onClose={close} /></Suspense>
) : null);

Así que la diferencia no está en si es posible, sino en cuál es el valor predeterminado.

En mi versión todos los valores del archivo de registry son funciones import(), así que la división de código queda forzada por la estructura. Con overlay-kit hay que escribirla a mano en cada punto de llamada.

Quien usa la librería tiene que decidir dónde llamar a unmount. Si solo llamas a close y te quedas ahí, la información del overlay permanece en memoria. La documentación oficial advierte de esto y da indicaciones separadas sobre dónde enganchar unmount en cada sistema de diseño. MUI y Mantine tienen un callback para cuando termina la transición, así que basta con engancharlo ahí, pero para las librerías que no lo tienen la documentación dice que pongas un temporizador con la duración de la animación. Que esas indicaciones estén repartidas por librería es en sí mismo el coste de esta decisión.

Los overlays se renderizan donde está el provider. Como no usa portales, el mismo código funciona en React Native, lo cual es una ventaja. A cambio, el contexto proporcionado por debajo de OverlayProvider no es visible dentro de un overlay. Al abrir un modal que depende del contexto del router o de un formulario, conviene comprobar esto primero.

Hasta dónde llega la palabra declarativo

Después de escribir hasta aquí, hay algo que me inquieta. Empecé este artículo llamando declarativa a esta interfaz, y sin embargo overlay.openAsync(...) es una llamada a función se mire como se mire.

Empecemos por la definición. La documentación de React traza la línea así.

In React, you don't directly manipulate the UI--meaning you don't enable, disable, show, or hide components directly. Instead, you declare what you want to show, and React figures out how to update the UI.

La analogía del mismo documento es más nítida. Lo imperativo es ir cantando cada giro a quien conduce el coche; lo declarativo es subirse a un taxi y decir el destino.

Una interfaz declarativa no elimina el procedimiento imperativo: lo mueve al otro lado de una frontera y le pone nombre a esa frontera. El interior de overlay-kit que hemos visto es exactamente eso. El punto de llamada es una línea, mientras que dentro corre un procedimiento que emite un evento y hace dos dispatch.

Veamos entonces dónde aplica cada proyecto la palabra. La documentación de overlay-kit llama imperativo al enfoque anterior. Lo que señala es el código que guarda el indicador de apertura con useState y lo invierte en un manejador de eventos. Lo que llama declarativo es el lado que trata el overlay como una acción y no como estado. El artículo sobre código declarativo del blog técnico de toss define la palabra de forma más amplia: el código declarativo es código con un nivel de abstracción más alto, y un hook que abstrae la acción de mostrar un overlay es un ejemplo de ello.

Por eso decidí estrechar la palabra así: quien llama no escribe el código que cierra. Cuándo cerrar, y qué queda en pantalla mientras se cierra, lo decide el overlay; quien llama escribe solo qué mostrar y qué espera recibir de vuelta.

Con este criterio, el código escrito con useState que guarda isOpen y el código que mantiene una lista de modales abiertos en un store global mientras quien llama los cierra están del mismo lado. Solo cambia dónde se guarda; en ambos, quien llama escribe la instrucción de cierre.

Para terminar

Lo que arreglé en el código de la empresa no fue, al final, dónde se guardaba el estado. Fue quién escribe el código que cierra.

Incluso cuando usábamos un store global, el estado ya estaba fuera del componente, pero las instrucciones que abrían y cerraban seguían en el punto de llamada. Solo tras cambiar a un único await esas instrucciones se metieron dentro del modal.

overlay-kit llegó al mismo lugar y luego dio un paso más: pone también en el punto de llamada qué se muestra. Creo que esa interfaz se lee bien. Y, al escribir esto, aprendí cuánto cuesta ese paso.

Era la diferencia entre tratar un modal como una función y tratarlo como datos. Escribir JSX en el punto de llamada convierte al controlador en un closure, y el contenido de un closure no se puede cambiar desde fuera una vez guardado. De esa estructura sale el JSX ignorado al reabrir con el mismo id. Tratarlo con una clave de texto convierte al modal en un valor guardado en un store que puedes reemplazar, actualizar y dividir en chunks, pero quien llama solo llega a conocer un nombre.

Creo que la sensación de que te gusta la interfaz de una librería es una señal bastante fiable. Aun así, conviene poner en palabras al menos una vez a qué apunta exactamente esa sensación. Si no lo haces, no puedes distinguir si lo que te gustó fue la interfaz o la reputación de quienes usan la librería. Animo a quien lea esto a hacer ese ejercicio una vez con alguna librería que esté usando ahora mismo.

Tuve que ordenar primero estos conceptos mientras ponía a prueba las afirmaciones de Jev, un modelo de decisión presentado por TypeSafe AI. En lugar de frases, Jev devuelve una probabilidad para cada opción y presenta la calibración como su objetivo de entrenamiento. Para examinar esa afirmación, primero necesitaba saber qué es la calibración y por qué se desajusta en los modelos existentes.

Exactitud y calibración

Primero hay que separar exactitud y calibración. La exactitud es qué porcentaje aciertas; la calibración es si sabes qué porcentaje vas a acertar. Si reúnes solo los días en los que se anunció un 70% de probabilidad de lluvia y resulta que de cada diez llovió siete veces, esa previsión está bien calibrada. No significa que su exactitud sea alta. Significa que conoce sus propios límites. Un modelo que solo acierta el 60% saca la nota máxima en calibración si dice de sí mismo que acierta el 60%.

La escala puede desviarse en dos direcciones. Si la probabilidad que declara el modelo es mayor que su tasa real de acierto, se llama overconfidence; si es menor, underconfidence. Si pones la probabilidad declarada en el eje horizontal y la tasa real de acierto de cada tramo de probabilidad en el eje vertical, se ve de un vistazo dónde se separan las dos. Un gráfico dibujado así se llama reliability diagram.

Si la curva cae sobre la diagonal, el modelo acertó tanto como dijo. Cuanto más cae por debajo de la diagonal, menos acierta en relación con la probabilidad que declara.

La métrica que mide ese desajuste es el ECE (expected calibration error). Según la definición de Guo et al. 2017, es la media, ponderada por la proporción de muestras de cada tramo, de la diferencia entre «la probabilidad declarada» y «la tasa real de acierto» en cada tramo de probabilidad, y 0 es la perfección. El código de abajo transcribe esa fórmula. Compara un modelo que acierta 6 de 10 preguntas cuando dice 0.6 cada vez y cuando dice 0.95 cada vez.

// Guo et al. 2017 의 식 (3). 구간은 등간격 10개(논문 실험은 15개), 경계는 왼쪽 닫힘
function ece(preds, M = 10) {
  const bins = Array.from({ length: M }, () => ({ n: 0, hit: 0, conf: 0 }))
  for (const { p, correct } of preds) {
    const b = bins[Math.min(M - 1, Math.floor(p * M))]
    b.n++
    b.hit += correct ? 1 : 0
    b.conf += p
  }
  return bins.reduce(
    (sum, b) => (b.n ? sum + (b.n / preds.length) * Math.abs(b.hit / b.n - b.conf / b.n) : sum),
    0,
  )
}
 
// 10문제 중 6문제를 맞힌다
const answers = Array.from({ length: 10 }, (_, i) => ({ correct: i < 6 }))
console.log(ece(answers.map((a) => ({ ...a, p: 0.6 }))).toFixed(3)) // 매번 0.6 이라고 말할 때
console.log(ece(answers.map((a) => ({ ...a, p: 0.95 }))).toFixed(3)) // 매번 0.95 라고 말할 때

Este es el resultado de ejecutarlo con Node v24.16.0 el 2026-10-08.

0.000
0.350

La exactitud es 0.6 en ambos casos. Solo cambió la probabilidad declarada, y aun así el ECE sube de 0 a 0.35. Pero como la fórmula toma un valor absoluto, el ECE mide solo el tamaño del desajuste, no su dirección. Un modelo que dice 0.25 cada vez y acierta igualmente 6 preguntas también obtiene un ECE de exactamente 0.35. Para saber si es overconfidence o underconfidence hay que mirar el reliability diagram o la confianza media menos la exactitud.

La función objetivo de RLHF

Entonces, ¿por qué se desajusta esta escala en un modelo pulido con retroalimentación humana? Primero hay que ver qué optimiza RLHF (reinforcement learning from human feedback). El esqueleto de construir un modelo de recompensa a partir de comparaciones de preferencias humanas salió de Christiano et al. 2017; uno de los primeros trabajos que lo llevó a modelos de lenguaje fue Ziegler et al. 2019, e InstructGPT lo aplicó al seguimiento de instrucciones. Lo que se empuja hacia arriba es la puntuación de un modelo de recompensa que imita la preferencia humana. Los trabajos con modelos de lenguaje suman a la recompensa una KL penalty que impide que el modelo se aleje demasiado del que había antes de empezar el aprendizaje por refuerzo, e InstructGPT además mezcló gradientes de los datos de preentrenamiento (PPO-ptx), pero lo que empuja hacia arriba sigue siendo esa puntuación.

Para un chatbot, la preferencia humana es el objetivo correcto. El problema es que esa preferencia se inclina a evitar el tono que revela incertidumbre. Zhou et al. 2024 mostraron, en cuatro conjuntos públicos de datos de preferencia, que los anotadores eligen menos las respuestas con atenuadores como "I'm not sure, maybe". La diferencia era pequeña pero significativa. Eso sí, no eligieron más las respuestas con expresiones que refuerzan la certeza. Leng et al. 2025 mostraron que los modelos de recompensa dan más puntuación a las respuestas que declaran una cifra de confianza alta, sin importar su calidad real. Ambos resultados se refieren a expresiones de confianza dentro del texto (verbalized confidence), no a probabilidades de tokens. TypeSafe, que propone un método de entrenamiento para sustituir a RLHF, también señala en su propia guía introductoria que RLHF puede premiar alucinaciones que suenan seguras (confident-sounding hallucinations). Es la postura de quien vende la alternativa.

Las curvas de calibración de GPT-4

En las probabilidades de los tokens también se ha observado un desajuste en la misma dirección. La Figure 8 del cuerpo del informe técnico de GPT-4 coloca lado a lado los reliability diagrams del modelo preentrenado y del modelo post-training, y su leyenda dice así:

Right: Calibration plot of the post-trained GPT-4 model on the same subset of MMLU. The post-training hurts calibration significantly.

El eje horizontal es la probabilidad (logprob) que el modelo asignó a cada una de las opciones A, B, C y D en preguntas de opción múltiple de MMLU, y el eje vertical es la tasa real de acierto en ese tramo. Según las cifras impresas en la Figure 8, el ECE del modelo preentrenado es 0.007 y el del modelo que pasó por PPO (el algoritmo de aprendizaje por refuerzo que se usa en RLHF para actualizar el modelo hacia puntuaciones más altas del modelo de recompensa) es 0.074. Empeoró más de diez veces.

En el panel derecho (PPO) de la Figure 8, las barras de 0.4 en adelante quedan por debajo de la diagonal, pero los tramos entre 0.1 y 0.3 quedan, al contrario, por encima. Las barras entre 0.1 y 0.9 se amontonan planas en una tasa real de acierto de aproximadamente 0.3 a 0.5, así que aunque suba la probabilidad que declara el modelo, la tasa de acierto apenas la sigue. En el 0.074 también se mezclan esos tramos de underconfidence. Y, como señalan Guo et al., un reliability diagram no muestra cuántas muestras caen en cada tramo, de modo que no se puede suponer que la distancia de una barra a la diagonal sea proporcional a lo que ese tramo aporta al ECE.

Este panel se diferencia del diagrama conceptual de arriba en dos cosas. Primero, no se limita a caer por debajo de la diagonal como la curva del diagrama conceptual, sino que la cruza una vez. Segundo, mete en los tramos las probabilidades de las cuatro opciones, así que también se aparta de la definición del código de arriba, que mide la probabilidad de la única respuesta elegida. Por eso no comparo el 0.074 con el 0.35 del código de arriba en la misma escala.

Entonces, ¿por qué empeoró? El cuerpo del informe solo dice que el modelo preentrenado estaba bien calibrado y que la calibración se redujo tras el post-training; no da una causa. Una pista está en Kadavath et al. 2022, de Anthropic. Las políticas RLHF que entrenaron a partir de sus propios modelos de lenguaje parecían, a simple vista, muy mal calibradas. El artículo dijo que no era sorprendente, porque el RL fine-tuning tiende a concentrar las predicciones en los comportamientos que reciben más recompensa. Fue un experimento breve añadido al margen, no el tema central. Sin embargo, al aplicar una sola temperatura, T=2.5, a todas las evaluaciones, los problemas de calibración quedaron en gran parte resueltos en tres evaluaciones. La temperatura es un valor que divide los logits; si es mayor que 1, deja intacto el orden de las respuestas y solo aplana la distribución de probabilidad. Yo leo el hecho de que un solo valor lo resolviera en gran parte como señal de que el desajuste no estaba concentrado en unos pocos tramos, sino que era toda la distribución estrechada hacia un lado. El artículo añadió además la salvedad de que un entrenamiento RL más intenso podría distorsionar la calibración de maneras que no se arreglan así.

Este es un resultado sobre modelos de Anthropic, así que no se puede trasladar directamente como causa de la Figure 8. Los estudios de la sección anterior también trataban expresiones de confianza dentro del texto. No encontré una fuente primaria que conecte directamente el resultado de que las personas evitan el tono inseguro con el desajuste en las probabilidades de los tokens.

La probabilidad que recibe tu código

La probabilidad de la Figure 8 es la probabilidad logarítmica de un token. Para recibir un valor del mismo tipo, según la especificación de la API de OpenAI, pones logprobs en true en una petición de Chat Completions y con top_logprobs eliges, entre 0 y 20, cuántos candidatos recibir en cada posición de token. El valor que obtienes pidiendo al modelo que diga un número de confianza junto con su respuesta es confianza expresada con palabras, y es un valor distinto de la probabilidad del token.

Los estudios sobre estos dos valores comparan pares distintos. Tian et al. 2023 informaron de que, dentro de modelos RLHF como ChatGPT, GPT-4 y Claude, la confianza expresada con palabras solía estar mejor calibrada que las probabilidades condicionales, y que en tres benchmarks a menudo reducía el ECE en torno a un 50% relativo. Eso sí, en esta comparación la probabilidad condicional de los modelos cuyos pesos no son públicos no era la probabilidad de tokens de la API, sino una estimación: la proporción de veces que salió la respuesta al muestrear 10 veces la misma pregunta. Leng et al., que vimos antes, informaron de que, frente a los modelos anteriores a RLHF, los modelos RLHF muestran más overconfidence en la confianza que expresan con palabras. Ambos resultados pueden ser ciertos a la vez. Y 0.074 es el valor que obtuvo el modelo post-training de GPT-4 de 2023 en un subconjunto de MMLU, así que no se puede trasladar tal cual a los modelos que llamas hoy por la API.

Para cerrar

En resumen, la calibración no trata de qué porcentaje aciertas, sino de si sabes qué porcentaje vas a acertar, y el ECE es la cifra que mide el tamaño de ese desajuste. Para ver la dirección hay que mirar el reliability diagram o la confianza media menos la exactitud. RLHF empuja hacia arriba la puntuación de un modelo de recompensa que imita la preferencia humana. Kadavath et al. consideran que esa optimización tiende a estrechar las predicciones hacia lo que más recompensa recibe. Hay estudios que muestran que las personas eligen menos las respuestas que revelan incertidumbre y que los modelos de recompensa dan más puntuación a las respuestas que declaran una cifra de confianza alta, sin importar la calidad. En GPT-4, el ECE quedó registrado pasando de 0.007 a 0.074 tras el post-training, pero OpenAI no llegó a escribir la causa. Como la calibración también sale distinta según si la probabilidad que recibe tu código es una probabilidad de tokens o una confianza expresada con palabras, sea cual sea, tienes que volver a medirla con tus propios datos.

Si las probabilidades de Jev, un modelo de decisión que presenta la calibración como objetivo de entrenamiento, son de verdad honestas se trata en Modelos de decisión, Jev y Kev.

Ojalá que tú también, antes de fijar en el código como umbral la probabilidad que devuelve un modelo, compruebes al menos una vez para qué se entrenó ese modelo y si su escala se sostiene con tus propios datos.

Mientras desarrollo, dedico tanto tiempo a averiguar qué hay que construir como a escribir código. Intercambio requisitos con el product manager, ajusto pantallas con el diseñador y pregunto a quien conoce el dominio qué significa cada término. Y he comprobado varias veces que el coste de que ese proceso falle es mucho mayor que el coste de escribir mal el código.

Hace poco leí Las actividades diarias de un líder de ingeniería, escrito por James Samuel. El autor divide el trabajo de un líder en seis apartados y el primero que aborda es la recopilación de información. Su razón es que toda decisión, toda dirección y toda acción dependen de una comprensión precisa de lo que está ocurriendo ahora mismo.

Aunque quiero asumir un rol de liderazgo algún día, lo que pensé al leer ese pasaje fue algo distinto. Si lo primero que aborda un líder es recopilar información, el equivalente para quien está en la ejecución es entender los requisitos. La forma en que manejo hoy los requisitos será la forma en que maneje mañana la información de una organización.

No pretendo hablar de liderazgo en este artículo. Hablo de qué estaba haciendo mal al comunicarme con otras disciplinas desde mi puesto actual y de qué puedo usar como herramienta. Empezando por la conclusión: llegué a pensar que este problema no es solo una cuestión de actitud. Existe una formulación alternativa, llamada ubiquitous language, y vale la pena ver de qué se trata.

La misma palabra, significados distintos

En su artículo sobre Bounded Context, Martin Fowler pone el ejemplo de una compañía eléctrica. Buena parte de los desajustes que he vivido tenían esta forma.

Aquí la palabra «meter» significaba cosas sutilmente distintas en diferentes partes de la organización: ¿era la conexión entre la red y una ubicación, entre la red y un cliente, o el contador físico en sí?

here the word 'meter' meant subtly different things to different parts of the organization: was it the connection between the grid and a location, the grid and a customer, the physical meter itself

La misma palabra, «meter», significaba cosas sutilmente distintas según el departamento de la organización. Y Fowler añade que esa confusión no es una casualidad de ese caso concreto: dice haber visto repetirse la misma confusión con palabras polisémicas como Customer o Product.

Esto no ocurrió porque los asistentes a la reunión fueran malos en las reuniones. Cuando una organización contiene contextos distintos, es natural que la misma palabra se bifurque, y si se deja pasar, acaba bifurcando también el código.

El trasfondo técnico de esta historia lo traté una vez en Modelo de dominio. Allí hablaba de cómo expresar el modelo dentro del código. En este artículo trato la etapa anterior a que ese modelo exista, la de la conversación entre personas.

Una palabra con dos significados

Pero ¿por qué se repite esto de forma estructural? Hay dos líneas de explicación.

Una viene de la estructura organizativa. El artículo How Do Committees Invent?, que Mel Conway publicó en Datamation en 1968, sostiene que, en la medida en que una organización no puede cambiar con flexibilidad su estructura de comunicación, esa organización estampa su propia imagen en todos los diseños que produce. La única frase que suele citarse como ley de Conway es en realidad una formulación que el propio autor elaboró más tarde, y esta descripción del texto de 1968 me resulta más directa.

Lo que leí en clave práctica en esa frase es la expresión «estampa». Significa que la bifurcación de los términos no termina en la conversación, sino que permanece en los artefactos. El «meter» anterior es exactamente eso. Si cada uno construye manteniendo un entendimiento distinto del alcance de «meter», esa diferencia no queda en el acta de la reunión, sino en los nombres de las tablas, en los campos de la respuesta de la API y en los textos de la pantalla. Y a partir de ahí, el coste de arreglarlo no admite comparación con el de mantener una conversación más.

Aquí se separa lo que quien está en la ejecución puede hacer de lo que no. Cambiar la estructura de comunicación de la organización queda fuera de su alcance. Pero hacer visibles los límites de los términos sí se puede hacer desde el puesto actual. Consiste en anotar qué alcance tiene una palabra en este documento y en indicar explícitamente cuándo difiere de la palabra que usa otro equipo. Todas las herramientas que veremos después son dispositivos que facilitan ese trabajo.

La otra explicación es algo más de fondo. Desde la ciencia cognitiva, la colaboración solo se sostiene sobre un trasfondo compartido. Grounding in Communication, escrito por Herbert Clark y Susan Brennan en 1991, arranca con el ejemplo de un dúo de piano. Los dos intérpretes no pueden ni empezar a coordinarse sin presuponer una cantidad enorme de información compartida, es decir, common ground. Aquí common ground significa conocimiento mutuo, creencias mutuas y supuestos mutuos. Y los autores afirman con rotundidad que toda acción colectiva se construye sobre el common ground y su acumulación.

La perspectiva a la que llegué tras poner ambas líneas una junto a otra es esta. Que los términos se desajusten no es un accidente, es el estado por defecto. Estar alineados es la excepción, el estado que hay que mantener pagando un coste. Entonces la pregunta práctica pasa a ser quién paga ese coste y cómo.

Vigilancia activa

En Domain-Driven Design, publicado en 2003, Evans presenta un patrón llamado ubiquitous language, o lenguaje compartido. Suele resumirse como poco más que «que developers y expertos de dominio usen los mismos términos», pero al leer el libro original la receta es mucho más concreta. Pide que el equipo tome el modelo como columna vertebral del lenguaje y se comprometa a usar ese lenguaje con insistencia en toda la comunicación del equipo y en el código. Y la frase que viene a continuación fue la más importante para mí.

Los expertos de dominio objetan a los términos o estructuras que resultan torpes o inadecuados para transmitir el entendimiento del dominio, mientras que los developers vigilan la ambigüedad o la inconsistencia que hará tropezar al diseño.

Domain experts object to terms or structures that are awkward or inadequate to convey domain understanding, while developers watch for ambiguity or inconsistency that will trip up design.

Los expertos de dominio objetan a los términos y estructuras torpes o insuficientes para transmitir el entendimiento del dominio, y los developers vigilan la ambigüedad o inconsistencia que derribará el diseño.

Al leer esa frase corregí mi comprensión de mi propio papel. Hasta entonces me consideraba un receptor en las reuniones de requisitos. Pensaba que mi trabajo era recibir con exactitud lo que se decidiera en producto e implementarlo. Pero la parte que Evans asigna al developer no era la recepción. Es detectar la ambigüedad y devolverla. Eso no es cooperación pasiva, es vigilancia activa.

(Por cierto, Fowler tradujo esta frase en su artículo como «Domain experts should object ... developers should watch». El libro original no lleva verbo modal. Es una diferencia menor, pero el original se lee de forma más categórica: el tono no es que convenga hacerlo, sino que hacerlo es la definición del patrón.)

¿Y cómo se detecta la ambigüedad? Evans también responde a eso: usar los términos repetidamente en la conversación es lo que revela las diferencias de interpretación. Yo leí esa frase así. La ambigüedad no se encuentra leyendo documentos con lupa. Por muy cuidadosamente que se lea una especificación, no aflora el hecho de que «meter» tiene varios significados. Esa palabra tiene que usarse repetidamente contra casos concretos para que se bifurque. El momento en que surge una pregunta como «¿Qué entienden los demás por meter?» es justamente ese punto.

El principio del mínimo esfuerzo colaborativo

Puede que conozcamos este método y aun así no lo practiquemos. Entonces, ¿por qué no preguntamos una y otra vez?

Volvamos al artículo de Clark y Brennan. Los autores dan el nombre de grounding al proceso de convertir lo dicho en parte del common ground. Y proponen un principio sobre cómo se comporta la gente durante ese proceso: el principio del mínimo esfuerzo colaborativo (the principle of least collaborative effort). Nace de la observación de que a la gente no le gusta trabajar más de lo necesario.

Aquí aparece el pasaje importante.

Según el principio del mínimo esfuerzo colaborativo, la gente debería intentar hacer grounding con el menor esfuerzo conjunto necesario. Pero qué es lo que cuesta esfuerzo cambia drásticamente según el medio de comunicación.

By the principle of least collaborative effort, people should try to ground with as little combined effort as needed. But what takes effort changes dramatically with the communication medium.

El punto donde recae el esfuerzo cambia drásticamente según el medio. Una técnica de confirmación disponible en un medio puede ser directamente imposible en otro o, aun siendo posible, mucho más costosa. Los autores señalan en particular que, en los medios donde el interlocutor no recibe lo dicho de inmediato, el coste de confiar en que otro corrija el malentendido se vuelve muy alto, así que el hablante tiende a evitarlo.

Conviene precisar algo aquí. Este artículo se escribió en 1991 y los medios que compararon los autores son la conversación cara a cara, el teléfono, las cartas o el contestador automático. No trata Slack ni Notion. El marco de que el coste del grounding varía según el medio es de los autores; aplicarlo a los canales de trabajo asíncronos de hoy es interpretación mía.

Aplicado así, se explica por qué yo no preguntaba una y otra vez. En un entorno donde recibes la especificación como texto y la confirmas como texto, enviar un mensaje de confirmación en cada punto ambiguo es caro. No sabes cuándo llegará la respuesta y temes que preguntar varias veces te haga parecer alguien que no ha entendido. Así que uno se desliza de forma natural hacia su propia interpretación.

Conviene distinguir aquí dos fuerzas. Una es que el medio encarece la confirmación, y eso es lo que dicen Clark y Brennan. La otra es el temor a parecer incompetente por preguntar varias veces, y eso no es lo que predice su principio, sino que pertenece a la seguridad psicológica de la que hablaremos después. Con precisión: lo que predice el principio del mínimo esfuerzo colaborativo es que se elegirá una forma más barata de confirmar, no que se dejará de confirmar. Renunciar a confirmar y pasar a la suposición no es el principio operando, es el grounding fracasando. Y el hecho de que esa interpretación fuera errónea aflora cuando la implementación ya está terminada.

Alcanzar un nivel suficiente

Entonces, ¿hay que preguntar por cada ambigüedad? No es realista y nunca he visto a nadie hacerlo. El artículo también ofrece un criterio para esta pregunta: el grounding criterion. Designa el estado en que ambas partes creen mutuamente que el oyente ha entendido lo que quería decir el hablante hasta un nivel suficiente para el propósito actual. Los autores lo preceden con la observación de que la comprensión perfecta es imposible de entrada.

La razón por la que este criterio me resultó práctico es que rebaja el objetivo. No hace falta entender los requisitos a la perfección. Basta con poder confiar mutuamente en que se entienden lo suficiente para lo que se va a hacer. Y los autores dicen que, si cambia el propósito, el criterio debe cambiar con él.

En la práctica, esto se convierte en el criterio para calibrar la intensidad de la confirmación. Si en una sesión que aún explora la dirección te enrocas en «¿Qué significa meter aquí?», la conversación no avanza. Lo que hace falta en esa etapa es acordar qué se quiere hacer y por qué, no fijar los valores límite. Al contrario, justo antes de entrar en implementación esa pregunta tiene que salir sí o sí. Ahí hay que poder confiar en que ambos están imaginando el mismo alcance para «meter»; si no, el código se apila sobre una premisa equivocada.

Por eso, ante la misma ambigüedad, la trato de forma distinta según la etapa en la que estoy. En la etapa de exploración la anoto en una lista y sigo; justo antes de implementar abro esa lista y voy cerrando los puntos uno a uno. Aplazar la confirmación y renunciar a ella son cosas distintas.

Hay una herramienta que combina bien en este punto. Team Topologies, de Matthew Skelton y Manuel Pais, distingue tres modos de interacción entre equipos: collaboration, cuando durante un periodo definido se descubre algo nuevo en conjunto; X-as-a-Service, cuando una parte provee y otra consume; y facilitation, cuando una parte ayuda y mentoriza a la otra.

En origen es una discusión sobre diseño organizativo, pero me pareció práctico reducirlo a la escala de una sola reunión. Si cada parte cree que esta conversación está en un modo distinto, la reunión se descarrila. Si el product manager cree que es una sesión para comunicar lo ya decidido mientras el developer cree que es una sesión para descubrir juntos, las preguntas del developer suenan a objeción y no a colaboración. También ocurre al revés. Si el developer vino a recibir una especificación cerrada y el product manager todavía estaba explorando, el developer se frustra porque no hay especificación.

Por eso últimamente confirmo esto al principio de la reunión: «¿Esto sigue abierto o es una sesión para confirmar lo que ya está decidido?». Esa sola pregunta cambia el carácter de todo lo que viene después. Es lo mismo que ajustar el grounding criterion al propósito.

Cuando la resolución no coincide, la conversación gira en vacío

Aun con el modo alineado, queda un problema. Otro desajuste que he vivido a menudo es hablar con resoluciones distintas.

Los requisitos que el product manager entrega en prosa suelen ser demasiado abstractos. De una frase como «que el usuario pueda consultar cómodamente su historial de reservas» no se deduce cuántas pantallas hay ni qué lleva a dónde. Al contrario, la maqueta del diseñador es demasiado concreta. El color de los botones y los márgenes ya están decididos, así que resulta difícil discutir precisamente si este flujo es el correcto.

Shape Up, escrito por Ryan Singer en Basecamp, señala este problema con precisión: empezar por wireframes o por maquetas visuales concretas te encierra en detalles innecesarios e impide explorar tan ampliamente como haga falta. Por eso, lo que propone Shape Up es una representación intermedia. Se llama breadboarding y toma prestado el concepto de la ingeniería eléctrica. Una breadboard es un prototipo que tiene todas las piezas y el cableado del aparato real, pero ningún diseño industrial. Por eso solo se dibujan tres cosas: los lugares a los que se puede navegar (places), aquello que el usuario puede accionar (affordances) y las líneas de conexión que muestran a dónde lleva esa acción al usuario (connection lines).

La razón por la que valoro esta técnica es que es un artefacto que puede producir el developer. En lugar de pedirle al product manager que escriba con más detalle o de esperar la maqueta del diseñador, puedes dibujar allí mismo el flujo tal como lo has entendido y devolverlo con un «lo he entendido así, ¿es correcto?». Es una forma concreta de ejecutar la vigilancia de la que hablaba Evans, la de devolver la ambigüedad. Y visto desde la sección anterior, es un dispositivo que abarata el grounding. Un dibujo sustituye varias rondas de confirmación por texto.

Pero esta resolución cuesta más de sostener de lo que parece. Mientras dibujas el flujo, acabas bajando de forma natural a cosas como «¿no sería mejor poner este botón abajo a la derecha?». A mí me ha pasado varias veces. Una vez que bajas así, la pregunta que se estaba discutiendo, es decir, si este flujo es el correcto, desaparece en silencio. Si decides la posición de los botones cuando el flujo todavía no está cerrado, toda esa discusión se tira por completo cuando el flujo cambie después.

Por eso en esta etapa intento mantener un dibujo deliberadamente malo. Si solo hay rectángulos, flechas y nombres, la otra persona ni se plantea señalar detalles y responde únicamente al flujo. Que el dibujo tenga poco acabado es, en esta herramienta, una función. (Contener las ganas de dibujarlo bonito cuesta más de lo que parece)

Que el propio nivel de abstracción pueda ser una herramienta de colaboración enlaza con lo que traté en Abstracción. Allí hablaba del nivel de abstracción del código; en la conversación existe lo mismo.

Separar reglas, ejemplos y preguntas

Otra manera de igualar la resolución es estructurar la propia discusión.

Veamos Example Mapping, presentado en 2015 por Matt Wynne, que lideró el proyecto Cucumber. Él diagnostica que la razón por la que a muchos equipos les cuesta discutir requisitos es que, al no haber estructura, la discusión se alarga y se vuelve aburrida. Y por eso dejan de hacerla con regularidad y con coherencia. A mí me pasaba exactamente eso: cuando una reunión de requisitos se alarga, la siguiente intentas acabarla rápido, y si la acabas rápido las ambigüedades se quedan tal cual.

Example Mapping divide la discusión en tarjetas de cuatro colores. La amarilla es la historia que se está tratando, la azul es la regla o criterio de aceptación, la verde es el ejemplo concreto que ilustra esa regla y la roja es la pregunta cuya respuesta nadie conoce.

De todas ellas, creo que la tarjeta roja es la clave. Las otras tres son técnicas de ordenación, pero la roja es el dispositivo que convierte el «no lo sé» en un producto oficial de la reunión. Decir que no se sabe deja de ser un acto que retrasa la reunión y pasa a ser un resultado que la reunión debe producir.

Por qué esto importa se ve claro al imaginar el caso contrario. En una reunión sin tarjetas rojas, encontrarse con un punto ambiguo deja dos opciones: enrocarse ahora y alargar la reunión, o seguir adelante e interpretarlo uno mismo más tarde. Como vimos en la sección anterior, la gente suele elegir lo segundo. Pero con una tarjeta a mano aparece una tercera opción. Anotarlo y seguir, sin que desaparezca. La reunión continúa y la ambigüedad permanece en la lista.

La tarjeta verde cumple un papel parecido. Cuando solo se escribe la regla, todo el mundo asiente; en el momento en que alguien intenta escribir un ejemplo concreto que la ilustre, las interpretaciones se separan. Es el «usarlos repetidamente en la conversación revela las diferencias» de Evans trasladado al formato de reunión. Si pides que se añadan tres ejemplos por cada regla, en uno de ellos suele salir un «espera, ¿y en este caso qué pasa?». (Por mi experiencia, la reunión en la que esa pregunta no aparece no es una reunión en la que todos entendieron, sino una en la que cada uno entendió algo distinto)

Con una idea parecida existe también Three Amigos, usado desde hace tiempo en el ámbito de BDD. Consiste en que las tres perspectivas de negocio, desarrollo y pruebas plantean cada una una pregunta distinta, y el glosario de Agile Alliance resume esas preguntas como qué problema se intenta resolver, cómo se construirá una solución para resolverlo y qué pasa con esto, qué podría llegar a ocurrir. Qué le sucede a una reunión donde la tercera pregunta nunca aparece probablemente no haga falta explicarlo.

Crear un proceso para comprobar lo que no se sabe

Ahora bien, ¿por qué nos cuesta tanto sacar la tarjeta roja? Aquí no hay manera de esquivar el tema de la seguridad psicológica.

El artículo que Amy Edmondson publicó en Administrative Science Quarterly en 1999 es el estudio que estableció formalmente el concepto de seguridad psicológica de equipo. (El propio artículo señala como raíz el trabajo de Schein y Bennis de 1965.) Define la seguridad psicológica de equipo como la creencia compartida de que el equipo es un lugar seguro para asumir riesgos interpersonales. Decir que no se sabe, expresar desacuerdo y admitir un error entran ahí. El artículo estudió 51 equipos de una empresa manufacturera y mostró que la seguridad psicológica se asocia con el comportamiento de aprendizaje y que ese comportamiento media entre la seguridad psicológica y el rendimiento del equipo.

Pero la frase que me pareció más práctica de ese artículo no fue la definición, sino la que viene justo después.

En su mayor parte, esta creencia tiende a ser tácita: se da por sentada y ni los individuos ni el equipo en su conjunto le prestan atención directa.

For the most part, this belief tends to be tacit—taken for granted and not given direct attention either by individuals or by the team as a whole.

Esta creencia suele ser tácita y ni los individuos ni el equipo le prestan atención directa.

A partir de aquí es una conjetura mía. Lo que dice el artículo llega hasta que la creencia es tácita; la receta de que por tanto basta con crear un formulario no está en el artículo. Dicho esto, he visto varias veces que lo tácito no cambia por declaración. Decir «somos un equipo donde se puede preguntar lo que no se sabe» no cambia gran cosa por sí solo. Por eso creo que la tarjeta roja de la sección anterior importa. Si conviertes el «no lo sé» en una casilla dentro de un formulario, rellenarla pasa a ser procedimiento en lugar de valentía.

Cabe una objeción, por supuesto. En un equipo que no es seguro, la casilla de la tarjeta roja se quedará simplemente vacía. Es una crítica justa y no pretendo afirmar que esta herramienta genere seguridad. Pero si la casilla existe, al menos el hecho de que esté vacía se vuelve visible. Aparece un lugar donde preguntar si está vacía porque nadie tiene dudas o porque cuesta decirlas.

La misma idea está incorporada en formatos de documento reales. Si miras el Bounded Context Canvas creado por la comunidad DDD, es una herramienta colaborativa para diseñar y documentar un contexto, y su reparto de casillas resulta interesante. Nombre y propósito, clasificación estratégica, rol de dominio, comunicación entrante y saliente, y luego Ubiquitous Language, decisiones de negocio, Assumptions, métricas de verificación y Open Questions.

Hay una casilla aparte para escribir el lenguaje compartido, otra para los supuestos y otra para las preguntas abiertas. La descripción del canvas dice que el propio acto de escribir el propósito obliga a formular con claridad un pensamiento difuso y coloca a todo el equipo en la misma página.

Creo que este planteamiento es el enfoque más realista para los problemas de comunicación. En vez de intentar cambiar la actitud de las personas, crear una casilla para aquello que cuesta decir. Una buena estructura no exige que la gente lo haga bien, sino que se lo pone fácil.

Por qué esto no es una cuestión de gusto

Llegados aquí, cabe una reacción: está bien, pero al final esto es «comuniquémonos con empeño», ¿no? ¿Y eso no es cuestión de carácter?

Yo también lo pensé durante un tiempo. Pero sobre esta parte hay datos.

Cuando DORA aborda la cultura organizativa, toma la clasificación del sociólogo Ron Westrum: pathological, orientada al poder; bureaucratic, orientada a las reglas; y generative, orientada al resultado. Y la documentación oficial de DORA resume así sus hallazgos.

Una cultura organizativa de alta confianza que enfatiza el flujo de información es predictiva del rendimiento en la entrega de software.

organizational culture that is high-trust and emphasizes information flow is predictive of software delivery performance

Una cultura organizativa de alta confianza que enfatiza el flujo de información predice el rendimiento en la entrega de software. No dice que los equipos que se comunican bien estén de mejor humor, sino que es una variable que se mueve junto al rendimiento.

Ahora bien, «predecir» no debe leerse aquí como causalidad. Los datos de DORA proceden de una encuesta en la que los mismos participantes respondieron sobre cultura y sobre rendimiento, y es una correlación a nivel organizativo. Queda la posibilidad de que quien está satisfecho con su organización puntuara alto en ambas cosas, y de una relación a nivel organizativo no se deriva de inmediato una receta sobre cómo debe comportarse un individuo. Así que hasta aquí llega lo que permite decir este material: el flujo de información no vive solo en el terreno del gusto, está en un lugar donde se mueve junto al rendimiento.

El mismo documento recoge también las tres propiedades de la buena información según Westrum: responde a la pregunta que necesita quien la recibe, llega en el momento oportuno y se presenta de forma que quien la recibe pueda usarla con eficacia. Merece la pena fijarse en que las tres sitúan el criterio en quien recibe. Compartir mucho no es lo que hace bueno un flujo de información.

El Project Aristotle de Google es otra fuente citada con frecuencia. Según lo publicado en reWork, estudiaron 180 equipos, aplicaron más de 35 modelos estadísticos a cientos de variables y propusieron cinco factores que influyen en la efectividad de un equipo: seguridad psicológica, fiabilidad, estructura y claridad, significado e impacto. Y la conclusión fue que importaba más cómo trabajaba junto ese equipo que quién estaba en él.

Aun así, quiero señalar una cosa. La página oficial declara que enumera los cinco factores por orden de importancia y coloca la seguridad psicológica en primer lugar. Pero las expresiones de magnitud del tipo «primero de forma abrumadora», que aparecen a menudo en artículos que citan esta investigación, no están en esa página. Que exista un orden y que uno arrase sobre los demás son cosas distintas. Por eso en este artículo no afirmo nada sobre la magnitud. Para argumentar la importancia de la seguridad psicológica, lo preciso es apoyarse en el artículo original de Edmondson de la sección anterior.

De vuelta al tema del liderazgo

Volvamos al artículo citado al principio.

Al abordar en primer lugar la recopilación de información, James Samuel dice que los métodos de la etapa de ejecución dejan de funcionar. Como colaborador individual tienes la imagen completa de tu propio trabajo, pero cuando asumes responsabilidad sobre personas ya no puedes usar el método anterior. Por eso señala como capacidad necesaria la de filtrar el ruido y sintetizar la información en una imagen coherente de la realidad, porque ningún manager puede procesarlo todo.

Sentí que esto es lo mismo que las tres propiedades de la buena información de Westrum que vimos antes. No se trata de recopilar mucho, sino de convertirlo en algo utilizable. Y eso no se diferencia de lo que estoy haciendo ahora al trabajar con requisitos. Extraer las partes ambiguas de las frases de una especificación, redibujarlas como breadboard para confirmarlas y dejar lo que no se sabe como tarjeta roja es exactamente el ejercicio de filtrar el ruido y construir una imagen coherente.

También se me quedó lo que el autor dice sobre la toma de decisiones: esperar a tener certeza es en sí mismo una decisión y conlleva un coste. Esperar a que los requisitos sean del todo claros es igual. Por eso el grounding criterion, suficiente para el propósito actual en vez de comprensión perfecta, se convierte en el criterio práctico.

Para terminar

En resumen.

El fallo de comunicación con otras disciplinas no suele ser solo una cuestión de actitud. Cuando una organización contiene contextos distintos, que la misma palabra se bifurque es el estado por defecto, y estar alineados es la excepción que hay que mantener pagando un coste. La forma de pagar ese coste es el lenguaje compartido, y dentro de él la parte del developer no es transcribir los requisitos, sino vigilar la ambigüedad y devolverla.

Pero devolverla exige esfuerzo, y la gente intenta minimizarlo. Así que, en lugar de apoyarme en la voluntad, decidí usar tres cosas: confirmar primero en qué modo está esta conversación, dibujar el flujo en la resolución intermedia entre la prosa y la maqueta y devolverlo, y crear dentro del formato de reunión una casilla para anotar lo que no se sabe. Ninguna de las tres exige corregir la actitud; las tres facilitan hacerlo.

Todavía no soy líder y nada de lo que he escrito aquí lo he verificado desde ese puesto. Con otro tamaño de equipo u otra cultura organizativa habrá cosas que no funcionen. Pero hay algo de lo que creo poder estar seguro ahora. La manera en que maneje la información más adelante no será algo que aprenda de nuevo, sino el hábito con el que hoy manejo los requisitos, crecido a otra escala. Por eso últimamente intento avergonzarme menos que antes de preguntar en una reunión «¿qué quieres decir con eso?».

Si a quien lee esto le viene a la cabeza alguna palabra de una reunión reciente ante la que asintió sin estar realmente seguro, le recomiendo usar esa palabra una vez más la próxima vez. Al usarla repetidamente, aflora.

Mientras terminaba el artículo anterior sobre cómo ahorrar tokens, hubo una pregunta que no dejaba de rondarme. Creo que el centro de gravedad está pasando del trabajo sobre prompts individuales a la técnica de vaciar y seleccionar información —context engineering—. Al cerrar aquel texto, la siguiente pregunta surgió de forma natural: entonces, ¿qué viene después del contexto?

Hay que ser prudente al hablar de «la dirección futura». El futuro admite innumerables caminos; por eso, aquí nos centramos en ordenar el cambio de énfasis que puede leerse en fuentes primarias ya publicadas. Aunque inevitablemente haya cierta inferencia, espero que el texto se lea desde perspectivas diversas.

Del prompt al contexto

Empecemos por aclarar los términos. Durante un tiempo, el gran tema del sector fue el prompt engineering. La cuestión era cómo redactar bien una única instrucción para el model: cómo diseñar indicaciones claras, buenos ejemplos y el formato de salida.

Después creció la unidad de trabajo. Cuando se generalizaron los agentes que operan durante decenas de turnos, dejó de importar solo un prompt y pasó a ser crucial cómo componer todo el contexto que el modelo ve en cada turno (system prompt + definiciones de herramientas + historial de conversación + resultados de búsqueda + memoria). A esto lo llamamos context engineering. Anthropic articuló este marco en septiembre de 2025 con «Effective context engineering for AI agents», y el estudio sobre context rot publicado ese mismo año por el equipo de Chroma (Hong et al.) añadió evidencia cuantitativa. Con 18 modelos, entre ellos GPT-4.1, Claude 4, Gemini 2.5 y Qwen3, mostraron que el rendimiento se degrada de forma desigual a medida que crece la entrada, incluso en tareas tan sencillas como copiar palabras literalmente. La suposición habitual de que un modelo trata igual el token número 100 y el número 10,000 no se sostiene en la práctica. La conclusión no fue «cuanto más largo el contexto, mejor», sino «cómo se coloca la información importa tanto como qué contiene». Esto impulsó el paso de llenar a seleccionar y ayudó a que el término se asentara con rapidez.

Conviene señalar un malentendido habitual. El prompt engineering no fue sustituido por el context engineering. Escribir buenos prompts sigue siendo fundamental; el context engineering se parece más a un concepto superior construido sobre esa base. (Que el interés pase de escribir buen código a diseñar buenos sistemas no vuelve innecesario el coding.) La descripción exacta no es «cambiamos una cosa por otra», sino «se amplió incluyéndola».

Volvamos entonces a la pregunta: ¿esa ampliación terminó en el contexto? No parece que sea así.

El blog de ingeniería de Anthropic

Creo que la forma más honesta de intuir una dirección es leer en orden cronológico qué publican quienes realmente están impulsando el campo. Si seguimos el blog de ingeniería de Anthropic después de «Effective context engineering» (septiembre de 2025), los títulos por sí solos ya dibujan hacia dónde siguió moviéndose el centro de gravedad.

• Octubre de 2025, Equipar agentes con Agent Skills
• Noviembre de 2025, Code execution with MCP: agentes más eficientes
• Noviembre de 2025, Effective harnesses for long-running agents
• Enero de 2026, Demystifying evals for AI agents
• Enero de 2026, Diseñar evaluaciones técnicas AI-resistant
• Febrero de 2026, Cuantificar el ruido de infraestructura en evaluaciones de agentic coding
• Marzo de 2026, Harness design for long-running application development
• Abril de 2026, Scaling Managed Agents: separar cerebro y manos
• Mayo de 2026, Cómo contener a Claude en todos los productos

Visto con algo de distancia, los términos se agrupan en tres ramas: harness, eval y containment. Lo interpreto como un debate que sube un nivel desde cómo llenar y vaciar el contexto hacia cómo diseñar, medir y controlar el sistema de agentes completo. (Naturalmente, existe la limitación de que son las prioridades de una empresa. Aun así, dado el peso que tiene en el ecosistema de coding agents, cuesta reducirlas a los intereses de un único vendor.)

Veamos cada rama.

harness

La palabra harness puede resultar poco familiar. Literalmente es un arnés: el equipo que se coloca a un caballo para dirigir su fuerza. En un agente de IA, harness designa todo el armazón que rodea al model desde fuera y lo pone a trabajar: qué tools puede usar y en qué orden, cómo recuperarse de un fallo, hasta dónde llegan sus permisos y cuándo se detiene el loop.

Si context engineering pregunta «¿qué le mostramos al model?», el diseño de harness pregunta «¿cómo hacemos que el model se mueva dentro de ese entorno?». Está una capa más afuera. Si el model fuera una persona recién contratada y muy capaz, el contexto serían los materiales de trabajo que recibe, mientras que el harness sería el entorno y el manual de procedimientos. La misma persona puede rendir de forma irregular en un espacio caótico y llegar mucho más lejos, con idénticas capacidades, sobre un proceso bien diseñado.

La importancia se ve con claridad en un fracaso al que se enfrentó directamente el equipo de ingeniería de Anthropic. Colocaron su mejor coding model, Opus 4.5, sobre Claude Agent SDK, le dieron solo instrucciones de alto nivel como «crea un clone de claude.ai» y lo ejecutaron durante varias sesiones. Aunque el model era inteligente, no produjo una app de nivel production. Los fallos se repetían de dos maneras. En una, la sesión intentaba terminar todo de una vez, agotaba el contexto a mitad de la implementación y dejaba a la siguiente una función a medio construir. En la otra, una sesión posterior veía que «ya se ha avanzado bastante» y declaraba que había terminado pese al trabajo pendiente. (Es como una tarea larga repartida por turnos entre varias personas, donde cada relevo carece por completo de los recuerdos del anterior.)

La solución no fue hacer más inteligente al model, sino cambiar el armazón. La primera sesión recibió un prompt exclusivo para preparar el entorno (initializer agent), desplegó más de 200 especificaciones funcionales en feature_list.json y creó init.sh para iniciar el servidor de desarrollo, además de un log de progreso (claude-progress.txt). Cada sesión posterior (coding agent) se ocupaba exactamente de una función, dejaba un estado limpio mediante un git commit y notas de progreso, y terminaba. La siguiente leía primero ese progress file y el git log para saber «hasta dónde llegó el turno anterior» y continuar desde allí. Era el mismo model, pero el resultado cambió al colocarlo sobre este armazón. El harness, no el model, decidió el éxito. (Curiosamente, las recetas de Anthropic no son nuevas. Las listas de funciones, los commits pequeños, las notas de progreso y los smoke tests ejecutados siempre son exactamente lo que hace a diario una persona con experiencia en desarrollo. Un buen armazón para un agente se parece, en definitiva, a incrustar buenos hábitos de engineering en el entorno.)

La conexión con el ahorro de tokens también es clara. El aislamiento de subagentes, la reducción de definiciones de tools y el model routing tratados en el artículo anterior parecen técnicas independientes si se observan por separado. Juntas, sin embargo, son partes de cómo se diseña un único harness. Decidir a qué model lane se envía cada tarea, qué tools permanecen activas y dónde se aísla la exploración verbose forma parte del diseño de harness. El ahorro se parece más a un efecto secundario de ese diseño.

Sin embargo, el diseño de harness encierra una trampa peculiar: cuanto mejor diseñado está el armazón, más probable es que envejezca cuando mejora el model. Un harness es, en esencia, un conjunto de supuestos sobre «lo que el model no puede hacer por sí solo»; en cuanto puede hacerlo, esos supuestos se convierten en carga. Un caso de Anthropic lo ilustra exactamente. Sonnet 4.5 tendía a apresurarse para terminar cuando se acercaba al límite de contexto —context anxiety—, así que el armazón incorporó un mecanismo de context reset. Al usar el mismo armazón con Opus 4.5, aquel hábito había desaparecido y el reset cuidadosamente añadido se volvió peso muerto. Cada vez que el model se hace un poco más capaz, alguna parte del armazón puede caducar.

De ahí surge una idea adicional: en lugar de perfeccionar un armazón concreto, diseñar interfaces que permanezcan estables aunque el armazón cambie. Managed Agents de Anthropic sigue esta dirección, cuyas raíces están, sorprendentemente, en los sistemas operativos. El OS ha resistido durante décadas porque virtualizó el hardware en abstracciones como procesos y archivos, creando por adelantado un recipiente para programas que aún no existían. Una línea de read() funciona igual con un disco de la década de 1970 que con un SSD actual. Aplicado a los agentes, el mismo razonamiento los divide en tres piezas: el cerebro que decide (Claude y el harness), las manos que actúan (sandbox de ejecución de código y tools) y el session log que registra mediante append todo lo ocurrido. Al separarlas, si muere el container, el cerebro puede tratarlo como un error de tool call; y si muere el harness, puede despertar desde el último punto del session log. Como efecto secundario también bajaron el coste y la latencia. Al iniciar containers solo cuando eran realmente necesarios, Anthropic afirma que el time to first token (TTFT) cayó cerca de un 60% en la mediana y, en p95, más de un 90%. (Aquí volvemos a encontrarnos con el artículo sobre tokens. Allí se recomendaba poner delante las partes estáticas para aprovechar prompt caching; decidir «cómo disponer el contexto para mejorar el cache hit rate» es precisamente la tarea del harness que acompaña a este cerebro.)

eval

La segunda rama fue la que más me interesó personalmente. Como si se hubieran puesto de acuerdo, los artículos de comienzos de 2026 convergen en la evaluación (eval).

La razón resulta natural. ¿Con qué comprobamos si el contexto está bien compuesto, el harness bien diseñado o el coste realmente reducido? Cuanto más largas y complejas son las tareas que un agente resuelve de forma autónoma, más difícil es revisar a simple vista cada una y decidir «¿esto funcionó bien?». La base de la confianza acaba desplazándose hacia la medición. Por eso han pasado al primer plano preguntas como «¿cómo diseñar la evaluación de agentes?», «¿cómo eliminar el ruido de la propia evaluación?» o «¿cómo tratar el eval awareness, cuando el model detecta que lo evalúan y cambia su conducta?».

Evaluar agentes es difícil porque no se parece a una pregunta y respuesta de una sola vez. Un agente llama a tools y cambia estados a lo largo de varios turnos, de modo que un error se propaga y acumula. Además, los resultados varían entre ejecuciones aun con la misma entrada. Anthropic divide esta no determinación en dos métricas. pass@k es la probabilidad de acertar al menos una vez en k intentos, por lo que crece al aumentar los intentos. pass^k es la probabilidad de acertar los k intentos, por lo que disminuye. En generación de código que solo necesita funcionar una vez importa pass@1; en un agente de atención al cliente que debe funcionar siempre, pass^k es fundamental. (Con una tasa de éxito per-trial del 75%, la probabilidad de tres éxitos seguidos es 0.75³, cerca del 42%. Así de grande es la distancia entre «suele funcionar» y «funciona siempre».)

¿Con qué se puntúa entonces un intento? El mismo artículo distingue tres tipos de grader. Los code-based (tests superados, static analysis y validación de tool calls) son rápidos, baratos y objetivos, pero débiles en tareas abiertas con varias respuestas válidas. Los model-based (LLM-as-judge y puntuación mediante rubric) captan matices de calidad, pero son no deterministas y deben calibrarse periódicamente con evaluación humana. Los human-based son los más exactos, pero lentos y caros. En la práctica se combinan los tres, preferiblemente con evaluación determinista como base y la del model como apoyo. Hay otra distinción. Un capability eval pregunta «¿qué puede lograr este agente?», por lo que comienza con puntuaciones bajas y ofrece una pendiente que subir. Un regression eval pregunta «¿sigue haciendo lo que antes hacía?», por lo que debe mantenerse casi en el 100%; una bajada indica que algo se rompió.

Aquí hay una trampa que se pasa por alto con sorprendente frecuencia: una puntuación baja puede ser culpa de la evaluación, no del agente. Anthropic cuenta que Opus 4.5 obtuvo inicialmente un 42% en CORE-Bench. Al investigar encontraron evaluaciones rígidas que esperaban «96.124991…» y marcaban «96.12» como incorrecto, especificaciones ambiguas y tareas estocásticas imposibles de reproducir. Tras corregir bugs y repetir con un scaffold de restricciones más flexibles, la puntuación subió al 95%. Por eso insisten en un principio: no aceptes la puntuación sin más; lee tú mismo el transcript (registro de ejecución). Si un frontier model realiza 100 intentos y obtiene un 0%, normalmente el problema está roto, no es que el model sea incapaz.

También resulta interesante que, al avanzar la medición, la propia línea de base se mueve deprisa. En SWE-bench Verified —benchmark destacado de coding agents que usa issues reales de GitHub y puntúa si pasan los tests—, los frontier models pasaron de la franja del 30% a más del 80% en 1 año. A esas alturas, todos los problemas fáciles están resueltos, la puntuación toca techo (saturation) y aparece una paradoja: grandes mejoras de capacidad solo se reflejan en pequeñas diferencias. Según se cuenta, una startup de code review desestimó al principio un model nuevo tras mirar solo evaluaciones one-shot; no vio bien la mejora hasta que adoptó evaluaciones de agentes con tareas más largas y complejas. Por eso un eval no se crea una vez y se da por terminado: es un activo vivo que debe reemplazarse continuamente por versiones más difíciles. (Anthropic lo compara con el «Swiss cheese model» de la ingeniería de seguridad. Una loncha con agujeros no basta, pero al superponer evaluación automática, production monitoring y revisión humana de transcripts, el fallo que atraviesa una capa queda atrapado en la siguiente.)

containment

La tercera rama tiene un carácter algo distinto. No trata del coste ni del rendimiento, sino de seguridad y control.

Cuantas más herramientas maneja un agente y mayor es su autonomía, más crece el alcance de un solo error —su blast radius—. Para un agente capaz de borrar archivos, enviar solicitudes externas y ejecutar acciones privilegiadas en nombre de alguien, «¿dónde detenemos el daño cuando se equivoca?» importa tanto como «¿qué tan bien lo hace?». En este contexto puede leerse el protagonismo que Anthropic dio en mayo de 2026 a su artículo sobre containment en todos sus productos. Divide el riesgo de los agentes en tres ramas: user misuse, cuando un usuario solicita algo dañino con malicia o descuido; model misbehavior, cuando el modelo actúa por sí mismo sin que nadie se lo pida; y external attacks que llegan mediante herramientas, archivos o redes. Una observación interesante es que hacer más inteligente al modelo no se limita a reducir el riesgo. Los modelos menos capaces interpretan mal la situación y cometen errores obvios; los más capaces se equivocan menos, pero encuentran mejor rutas inesperadas para sortear restricciones que nadie escribió de forma explícita.

El punto central es el límite de «supervisar cada acción con una persona». Claude Code buscó inicialmente la seguridad pidiendo aprobación para cada escritura, ejecución y acceso a la red, pero la telemetría mostró que los usuarios aceptaban sin más cerca del 93% de las solicitudes. Cuantas más ventanas aparecen, menos atención recibe cada una: surge la approval fatigue. Una defensa probabilística basada en clics humanos siempre conservará agujeros. El centro de gravedad pasa de «vigilar lo que hace el agente» a «limitar lo que puede hacer desde el principio». Las defensas se apilan en tres capas: la capa de entorno, con sandbox, VM y control de egress; la capa del model, con system prompts y classifiers; y la capa de contenido externo, con MCP, plugins y resultados de búsqueda. El principio esencial es instalar primero la capa de entorno, que bloquea de manera determinista. No porque las defensas del model sean débiles. De hecho, en el benchmark de Gray Swan para prompt injection, la tasa de éxito de un ataque único ronda el 0.1%, un resultado de primera categoría. Pero con 100 intentos adaptativos sube al 5–6%, y una defensa probabilística no puede alcanzar por naturaleza un 100% de aciertos. Por eso se añade al final una frontera dura. (La introducción de un sandbox a nivel de OS redujo las solicitudes de aprobación en un 84%. El mecanismo de seguridad redujo la fricción.)

Aunque parezca alejado del ahorro de tokens, comparte la misma raíz. Ambos preguntan «¿qué le damos al agente y hasta dónde?» Anthropic muestra bien la conexión con dos casos. En uno, el red team interno hizo phishing a un empleado para que ejecutara Claude Code con un prompt malicioso. Una instrucción oculta le hizo leer ~/.aws/credentials y enviar el contenido fuera mediante POST; de 25 intentos, funcionó 24 veces. Como el usuario había escrito directamente la instrucción, el classifier del model no vio nada sospechoso. Lo impidieron la frontera ambiental que mantenía las credenciales fuera del sandbox y el control de egress, no un model inteligente. El segundo caso es más sutil. Una allowlist de egress permitió correctamente api.anthropic.com, pero un archivo plantado por un atacante usó su propia API key para llamar a la API de carga de archivos de Anthropic, y los datos salieron hacia la cuenta atacante. El sandbox funcionó perfectamente, pero aun así hubo fuga. La lección fue entender la allowlist no como un «filtro de destinos», sino como «permiso para todas las capacidades disponibles en ese dominio». (Anthropic repite este principio: los hypervisors, filtros de syscall y runtimes de containers ya verificados resistieron; lo que se rompió fueron los componentes que ellos mismos habían construido encima.) Retirar tools de MCP que no se usan pertenece al mismo contexto: ahorra coste y reduce la attack surface. Mantener un diseño ligero no solo lo hace más barato y preciso, sino también más seguro.

En resumen

Las tres ramas se pueden condensar en una frase. La unidad de atención se expande un nivel cada vez: del prompt (una instrucción), al contexto (qué mostrar en cada turno), y luego al sistema de agentes completo (cómo operarlo, medirlo y contenerlo). Harness responde a «¿cómo hacerlo funcionar?», eval a «¿cómo sabemos si funcionó bien?» y containment a «¿cómo lo detenemos si funciona mal?».

Conviene insistir: estas tres ramas son un cambio de énfasis que el autor infiere de materiales ya publicados, no una predicción del tipo «esto será el estándar en la segunda mitad de 2026». Algunas corrientes crecerán y otras se integrarán bajo nombres diferentes. Lo claro es que ni el prompt ni el contexto desaparecerán: permanecerán como partes de un marco mayor. El campo ha avanzado añadiendo una capa sobre las anteriores, no borrando palabras viejas con otras nuevas, y es probable que siga haciéndolo.

Empezamos hablando de costes y llegamos hasta aquí. El artículo anterior recomendaba abrir el libro de cuentas de tokens; este propone dar un paso más. Conviene examinar a la vez cómo verificamos el ahorro (eval), sobre qué armazón puede repetirse (harness) y hasta dónde es seguro ese armazón (containment). Al final, lo que más perdure probablemente no será una técnica de ahorro concreta, sino el hábito de medir y controlar el propio sistema.

Este texto es una reescritura de una retrospectiva que escribí en junio de 2026. La idea que encabezaba el artículo original, "siete pickers con una sola API, más pequeños que un único calendario de una biblioteca competidora", resultó, al volver a comprobarla, medio falsa y medio irrelevante como diferenciador. Por eso lo reorganizo en este orden: por qué lo construí, en qué se diferencia de las opciones existentes y cuál es su definición técnica.

Adelanto la conclusión: lo que distingue a Kalyx no es el número de componentes, sino su modelo de valor. Las versiones de referencia son @kalyx/react 1.4.7 y @kalyx/core 1.4.8 (MIT, solo React 19), y los fragmentos de código proceden del repositorio de GitHub en main a fecha de 2026-09-16 (0bb302e).

Quería usar los selectores de fechas de forma declarativa

Tenía dos motivos para construirlo. Quería usar bibliotecas de fechas complejas y difíciles de manejar de una manera más declarativa y sencilla, y quería aprender cómo se construye por dentro una biblioteca así. "Difícil de manejar" es algo vago, así que volví a revisar las definiciones de tipos de cada biblioteca para ver si los puntos donde me atasqué siguen presentes en sus últimas versiones.

Una API que activa modos con props

react-datepicker activa la selección de hora con showTimeSelect, la de mes con showMonthYearPicker, la de año con showYearPicker y la de rango con selectsRange. Es una estructura en la que un mismo componente se convierte en otra cosa según la combinación de props. El coste se ve en los tipos. En las definiciones de tipos de la 9.1.0, según el valor de selectsRange, la firma de onChange se bifurca.

// react-datepicker/dist/index.d.ts (발췌)
    selectsRange?: true;
    selectsMultiple?: false | undefined;
    formatMultipleDates?: never;
    onChange?: (date: [Date | null, Date | null], event?: React.MouseEvent<HTMLElement> | React.KeyboardEvent<HTMLElement>) => void;

Es una union bien hecha, pero las ramas se multiplican a medida que crecen los modos, y quien la usa tiene que deducir qué combinación está activa solo por los nombres de las props. (Tiene la misma forma que "una abstracción que agrupa mal aumenta el acoplamiento", de lo que hablé en el artículo sobre abstracción.) Yo quería que "un campo de entrada, un popover y un calendario" se leyeran en la propia estructura del JSX.

Dónde se filtran los tipos de valor y la zona horaria

react-datepicker y react-day-picker intercambian objetos Date nativos. Es cierto que ambos tienen una prop timeZone que acepta zonas IANA. react-datepicker necesita date-fns-tz como peer opcional y la de react-day-picker es experimental, pero en cualquiera de los dos casos el tipo del valor sigue siendo Date. Como un Date se interpreta en la zona horaria local del entorno de ejecución, en Seúl new Date(2026, 3, 15) pasado por toISOString() da 2026-04-14T15:00:00.000Z. Eliges el 15 de abril y el servidor ve el 14. La issue "Date Selected is One Day Off" de react-datepicker se abrió en septiembre de 2017 y se cerró en diciembre de 2025.

En el otro extremo, Ark UI y React Aria usan objetos @internationalized/date como CalendarDate y ZonedDateTime. La semántica es precisa, pero en una app donde el estado de los formularios y las respuestas del servidor son todo cadenas, aparece código de conversión en cada frontera.

El soporte de zonas horarias también puede quedar atado a la biblioteca de fechas que elijas. En el código de los adaptadores de MUI X Date Pickers 9.13.0, los adaptadores de dayjs, Luxon y Moment tienen isTimezoneCompatible = true, y la familia date-fns tiene false. Una app que usa date-fns tiene que incorporar otra biblioteca de fechas para poder usar la prop timezone.

Los modos estaban repartidos en combinaciones de props, los valores en objetos Date cuya interpretación depende del entorno de ejecución y el soporte de zonas horarias en la elección de la biblioteca de fechas. Era difícil expresar la intención en una sola declaración.

Aprender construyendo

Un selector de fechas parece pequeño, pero contiene aritmética de calendario, locales, zonas horarias y horario de verano (DST), navegación por teclado y SSR. Por eso me puse como objetivo que, desde el lado de quien lo usa, se entendiera qué se está construyendo con solo mirar el JSX, y que, desde el lado de quien lo construye, el código fuera lo bastante acotado como para poder explicar dónde se convierten los valores.

Entonces, ¿de verdad no había ninguna biblioteca que ya resolviera estas necesidades?

En qué se diferencia de las opciones existentes

La respuesta corta es que sí la había. Empecé convencido de que no existía ninguna biblioteca headless con varios pickers, pero al investigar de nuevo esa premisa resultó falsa.

El modelo de valor que eligió cada opción

Lo siguiente se comprobó el 2026-09-16 instalando la última versión de npm y revisando las definiciones de tipos y la documentación oficial. La columna de tamaño se midió con el mismo método que explico más abajo.

react-day-picker indica en su guía oficial que "DayPicker does not include a built-in time picker". El tamaño de MUI incluye @mui/material y emotion, así que si tu app ya usa MUI, el aumento es mucho menor.

Ya existen opciones headless completas

Las filas importantes de la tabla son Ark UI y React Aria. Ark UI ofrece selección simple, múltiple y de rango, además de selección por mes y año, con una API de composición en dot notation como DatePicker.Root. React Aria es la implementación de Adobe centrada en la accesibilidad. Así que el hueco de Kalyx es más estrecho de lo que pensaba al principio.

Ya existen opciones headless completas. Sin embargo, Ark UI y React Aria intercambian valores como objetos @internationalized/date y ofrecen la entrada de hora como campos segmentados. Kalyx fija los valores como cadenas de instante UTC que viajan tal cual en JSON, y reúne en la misma API de composición un TimePicker basado en listas y pickers de mes, año y semana.

Aun así, "los valores son cadenas, y eso está bien" es un argumento débil. Un CalendarDate también se convierte en cadena con un solo toString(). El diferenciador no es el formato, sino el contrato de que esa cadena siempre es un momento real (un instante) y nunca se mezcla con una celda del calendario (una coordenada), y los tests que lo hacen cumplir.

Volví a medir el tamaño del bundle con un mismo método

El tamaño del bundle del badge del README no era una cantidad comparable con la de otras bibliotecas. Los aproximadamente 19.5KB del badge corresponden a un único archivo de @kalyx/react en dist, y ese archivo deja @kalyx/core, @kalyx/adapter-date-fns y @floating-ui/react como imports externos. Había puesto esa cifra junto a las cifras de otras bibliotecas que incluían sus dependencias.

Así que lo volví a medir todo con esta pregunta: "¿cuánto crece el bundle cuando una app consumidora añade una línea de import?"

echo "import { DatePicker } from '@kalyx/react'; export default DatePicker;" > entry.jsx
npx esbuild entry.jsx --bundle --minify --format=esm --platform=browser \
  --external:react --external:react-dom --external:react/jsx-runtime | gzip -6 | wc -c

Medido el 2026-09-16 con esbuild 0.28.2; KB son bytes divididos entre 1024. En react-datepicker excluí el CSS. React Aria Components lo medí dos veces: con los 12 exports necesarios para montar un único DatePicker (DatePicker, DateInput, Calendar, Popover, Dialog, etc.) y con 14 exports que añaden rango y hora (incluidos DateRangePicker, RangeCalendar y TimeField).

En las mismas condiciones, hay una sola afirmación verdadera. Un DatePicker (18.9KB) tiene un tamaño parecido al de DayPicker (20.0KB), y los siete juntos (25.6KB) pesan más. (E incluso así, DayPicker es solo el calendario, mientras que Kalyx DatePicker incluye también el campo de entrada y el popover.) El tamaño es sensible a la combinación de imports y al nivel de gzip, así que conviene leerlo como orden de magnitud, y el tamaño no es la razón principal para elegir Kalyx.

Una definición técnica de Kalyx

Kalyx es un selector de fechas headless para React que fija todas las entradas y salidas como cadenas de instante UTC, confina la conversión entre coordenadas de calendario e instantes a dos funciones y comprueba ese viaje de ida y vuelta con tests de propiedades en todas las zonas horarias que conoce el runtime.

Esta es la API del lado del consumidor. value y onChange usan string | null, y displayTimezone decide en el calendario de qué zona se muestra.

<DatePicker value={iso} onChange={setIso} displayTimezone="America/New_York">
  <DatePicker.Input />
  <DatePicker.Popover>
    <DatePicker.Calendar />
  </DatePicker.Popover>
</DatePicker>

Los valores son instantes y las celdas del calendario son coordenadas

Por Kalyx circulan dos tipos de cadenas ISO con el mismo formato. Una coordenada es una celda de la cuadrícula del calendario; se escribe como YYYY-MM-DDT00:00:00.000Z, pero no tiene noción de zona horaria. El cálculo de la cuadrícula se hace solo en UTC, así que no depende del entorno de ejecución. Un instante es el valor que sale por onChange: el momento real que corresponde a la medianoche de ese día en displayTimezone. El mismo 15 de enero es 2026-01-15T05:00:00.000Z en Nueva York y 2026-01-14T15:00:00.000Z en Seúl.

Solo dos funciones de @kalyx/core unen ambos mundos: civilMidnightFromUtcDay, que convierte una coordenada en instante, y su inversa, calendarDayFromInstant. Esta última lee "qué día es ese instante en esta zona" y lo vuelve a escribir como coordenada de medianoche UTC.

// packages/core/src/utils/timezone.ts:187-190
export function calendarDayFromInstant(iso: ISODateString, timeZone: string): ISODateString {
  const p = partsInTimezone(new Date(iso), timeZone);
  return new Date(Date.UTC(p.year, p.month - 1, p.day)).toISOString();
}

La regla es de dirección. Al elegir una celda y confirmar el valor, la coordenada pasa a instante; al decidir a partir del valor guardado qué mes mostrar y dónde poner el foco, el instante pasa a coordenada. El selectDate del Root de DatePicker convierte, valida las restricciones con el instante convertido y, si pasa, confirma.

// packages/react/src/components/DatePicker/Root.tsx:182-194
const normalized =
  coordinate && displayTimezone
    ? civilMidnightFromUtcDay(coordinate, displayTimezone)
    : coordinate;
 
if (normalized && isDateDisabled(normalized, disabledRules, adapter, displayTimezone)) {
  return;
}
 
if (!isControlled) {
  setUncontrolledValue(normalized);
}
onChange?.(normalized);

No es el único punto de llamada. Si buscas en packages/react/src, las dos funciones aparecen repartidas por el Root y el Calendar de DatePicker, RangePicker y DateTimePicker, por Presets, por las utilidades de navegación con teclado y por seis hooks headless. Aun así, todo camino que confirma una celda de fecha o decide la vista pasa por una de las dos. La confirmación de una hora la hace setTimeInTimezone, que por dentro convierte con la misma función interna, resolveCivilDateTime.

Este contrato se protege con tests basados en propiedades (property-based tests). Para toda coordenada c y toda zona z, debe cumplirse calendarDayFromInstant(civilMidnightFromUtcDay(c, z), z) === c.

// packages/core/src/__tests__/timezone.property.test.ts:86-94
it('round-trips every UTC calendar coordinate through civil midnight', () => {
  fc.assert(
    fc.property(utcCalendarCoordinate(), zone(), (coordinate, timeZone) => {
      const instant = civilMidnightFromUtcDay(coordinate, timeZone);
      expect(calendarDayFromInstant(instant, timeZone)).toBe(coordinate);
    }),
    RUNS,
  );
});

fast-check genera fechas aleatorias entre 2020 y 2045 y las combina con 14 zonas representativas, como Kathmandu (+5:45), Kiritimati (+14) y Niue (-11), durante 300 ejecuciones. El test inmediatamente siguiente comprueba el mismo viaje de ida y vuelta 12 veces por zona para todas las zonas que devuelve Intl.supportedValuesOf('timeZone'). En mi Node 24.16 local, esa lista tiene 418 zonas. La 1.4.8 añadió un test exhaustivo que compara, en cada cambio de horario, la conversión de las horas límite con una implementación de Temporal.

Entonces, ¿por qué no hacer que la biblioteca normalice por sí sola a instante un "2026-01-15T00:00:00.000Z" que pase el usuario? Ese camino está cerrado, porque con la cadena sola no se puede saber si es una coordenada o un instante. Si al valor de Seúl 2026-01-14T15:00:00.000Z, que ya es un instante, se le vuelve a aplicar civilMidnightFromUtcDay, se obtiene 2026-01-13T15:00:00.000Z; en zonas con offset positivo como Seúl, la fecha sigue retrocediendo un día en cada render. (El valor de Nueva York no cambia si se vuelve a aplicar.) Cambiarlo por startOfDayInTimezone, que da el mismo resultado por muchas veces que se aplique, elimina el desplazamiento, pero ya no cumple su función original de convertir coordenadas en instantes.

Así que renuncié a normalizar y fijé el contrato en la documentación. Quien usa el picker debe devolverle tal cual el valor que este emitió. Siendo sincero, es un coste que traslado a los consumidores, y como ISODateString es un alias de string, el compilador tampoco lo impide.

Resolver el DST solo con Intl

Para convertir una coordenada en instante hay que saber cuándo es, en UTC, "las 00:00 de ese día en esa zona", pero el offset solo se puede obtener si ya conoces el instante. Además, en los días de cambio de horario la hora local puede no existir (spring forward) o existir dos veces (fall back).

Kalyx lo resuelve sin una biblioteca como date-fns-tz. Pregunta a Intl.DateTimeFormat(...).formatToParts "qué hora es este momento UTC en esa zona" para medir el offset, y lee ese offset en dos puntos: un día antes y un día después de la hora pedida.

// packages/core/src/utils/timezone.ts:251-254, 259
const candidate = (probeEpoch: number) =>
  civilEpoch - getTimezoneOffsetMinutes(new Date(probeEpoch).toISOString(), timeZone) * 60_000;
const epochBefore = candidate(civilEpoch - 86_400_000);
const epochAfter = candidate(civilEpoch + 86_400_000);
 
if (epochBefore === epochAfter) return new Date(epochBefore).toISOString();

civilEpoch es la hora local deseada leída como si fuera UTC. Los offsets están dentro de ±14 horas, así que un día antes y un día después dan el offset de cada lado de cualquier cambio cercano. Si ambos coinciden no hay cambio y basta con dos llamadas a formatToParts; como la cuadrícula la llama una vez por cada una de sus 42 celdas, esta vía rápida es la que determina el coste. (Supone como mucho un cambio en 48 horas, algo que se cumple en todas las zonas de 2020 a 2045.)

Si difieren, vuelve a leer ambos candidatos en esa zona y comprueba cuál coincide con la hora pedida (timezone.ts:261-279). En el solapamiento del fall back coinciden los dos, así que elige el más temprano, construido con el offset anterior al cambio; en el hueco del spring forward no coincide ninguno, así que elige ese mismo lado y avanza la hora la duración del hueco. Este es el resultado de ejecutarlo de verdad.

"Los huecos avanzan y la ambigüedad toma la más temprana" coincide con el valor por defecto de disambiguation, "compatible", que describe la documentación de Temporal.ZonedDateTime en MDN. Por qué falla la fila de Londres en la 1.4.7 lo explico más adelante.

La frontera del adaptador son 21 métodos de cadenas

Si core calcula las zonas horarias, ¿de qué se encargan date-fns o dayjs? De la aritmética de fechas y el parsing. Esa frontera, DateAdapter, tiene 21 métodos, y todos los argumentos de fecha y valores de retorno son cadenas ISO.

// packages/core/src/types.ts:71-102 (발췌)
export interface DateAdapter {
  parse(value: string, format?: string): string;
  format(iso: string, formatStr: string, timezone?: string): string;
  addDays(iso: string, n: number): string;
  isSameDay(a: string, b: string, timezone?: string): boolean;
  startOfDay(iso: string, timezone?: string): string;
  today(timezone?: string): string;
  // addMonths, isBefore, startOfMonth, getYear 등 15개
}

Los métodos que reciben zona horaria son cuatro, format, isSameDay, startOfDay y today, e incluso esos cuatro delegan el cálculo en core. El format del adaptador de date-fns, si recibe timezone, llama directamente a formatInTimezone de core (packages/adapter-date-fns/src/index.ts:112-115). Por eso, uses el adaptador que uses, las respuestas sobre zonas horarias salen del mismo código, y los tres adaptadores (date-fns, dayjs, luxon) toman de @kalyx/core/test-helpers la función runAdapterConformanceTests y la ejecutan cada uno para comprobar que dan las mismas respuestas.

Los dos entry points también se separan sobre esta frontera. El entry por defecto, @kalyx/react, llama a setDefaultAdapter(DateFnsAdapter) al cargarse el módulo, así que funciona nada más instalarlo (packages/react/src/index.ts:9-11). @kalyx/react/headless no hace esa llamada y se empaqueta por separado, así que no entra código de date-fns.

La forma de esta frontera tuvo un precio. En junio de 2026 abandoné un adaptador de Temporal. El valor de Temporal está en que los tipos llevan consigo el significado, como PlainDate y ZonedDateTime, pero si la frontera es una cadena, ese significado no puede atravesarla. Envolverlo solo lo aplanaría en una cadena, así que concluí que no aportaba ganancia de corrección. Visto ahora, el problema de la sección anterior, "coordenadas e instantes son el mismo string", es justo el que Temporal resuelve en el sistema de tipos con PlainDate e Instant. La frontera de cadenas facilitó cambiar de adaptador, pero a cambio cerró el camino de resolverlo con tipos.

Siete pickers que combinan tres contextos

Kalyx tiene siete pickers: DatePicker, RangePicker, TimePicker, DateTimePicker, MonthPicker, YearPicker y WeekPicker. Lo importante no es el número, sino que los siete no son implementaciones independientes. Solo hay tres contextos: DatePickerContext, RangePickerContext y TimePickerContext.

El Root de MonthPicker se limita a cambiar el formato de visualización por defecto a yyyy-MM y a pasar selectionGranularity="month" a la implementación del Root de DatePicker (MonthPicker/Root.tsx:11-20). El selectDate de DatePicker, cuando la granularity es month, pliega la coordenada al día 1 de ese mes y después pasa por la misma conversión y validación de restricciones que vimos antes. DateTimePicker proporciona los dos contextos superpuestos.

// packages/react/src/components/DateTimePicker/Root.tsx:401-402
<DatePickerContext.Provider value={dateContext}>
  <TimePickerContext.Provider value={timeContext}>{children}</TimePickerContext.Provider>

Por eso DateTimePicker.Calendar es el mismo componente que DatePicker.Calendar y no sabe dentro de qué picker está. Una corrección en un sitio llega a todos los pickers que usan ese componente, y un defecto en un sitio también. Esta base compartida es además la razón de que un solo DatePicker supusiera el 74% del total en el gráfico anterior.

Lo que costó mantener el contrato

Los tres meses desde la 1.0 los dediqué más a verificar este contrato que a nuevas funcionalidades, y aparecieron tres defectos que los tests basados en ejemplos habrían dejado pasar. El primero lo encontró un test de propiedades, el segundo una revisión cruzada del código y el tercero la verificación de este artículo.

Una hora del 1 de octubre en Sydney

El primero fue que la propiedad "leer en esa zona el resultado de startOfDayInTimezone da 00:00:00" se rompió en Australia/Sydney. La implementación de entonces medía el offset una sola vez. Sydney pasa de +10 a +11 a las 02:00 del 1 de octubre de 2034, y las 00:00 de ese día todavía son +10, así que la respuesta correcta es 2034-09-30T14:00:00.000Z. Pero "el punto en que las 00:00 del 1 de octubre se leen como UTC" cae después del cambio, así que devolvía +11, y el resultado eran las 23:00 del día anterior. Este contraejemplo sigue ahí como test de regresión (timezone.property.test.ts:276).

Un test que solo pasaba en Seúl

El segundo salió de una revisión cruzada el 3 de agosto de 2026. El código que decide qué celda del calendario marcar como seleccionada convertía dos veces. La celda ya era una coordenada, pero convertía a fecha de esa zona tanto la celda como el valor guardado. Esto fue lo que produjo elegir "15 de enero".

En las zonas con offset positivo los dos desplazamientos se compensaban y por casualidad acertaba, y los tests existentes solo cubrían Seúl. En la misma revisión apareció también una infracción en la dirección contraria. Al decidir qué mes mostrar, se aplicaba startOfMonth directamente a un instante, así que si en Seúl se pasaba el 1 de enero como valor, se abría el calendario de diciembre.

Los mecanismos son distintos, pero la regla incumplida es una sola: convertir una única vez por dirección, con la función que corresponde a esa dirección.

Este incidente amplió los tests de propiedades de ida y vuelta de core de "unas cuantas zonas representativas" a "todas las zonas que conoce el runtime". (Los tests de componentes del lado de React siguen usando zonas representativas como America/New_York.) Los defectos que solo aparecen donde cambia el signo no se atrapan con muestras.

La 01:30 de Londres que se resolvía tarde

El tercero surgió al extender a otras zonas la tabla de DST de este artículo. La 1.4.7 empezaba a medir el offset en el punto donde la hora pedida se lee como UTC, y en las zonas cuyo offset tras el cambio es 0 o más, ese punto ya está después del cambio, así que convergía en el offset tardío. Al contrastar con temporal-polyfill todos los cambios de 2020 a 2045 en 418 zonas, en 1908 de los 3395 cambios con solapamiento se elegía la hora más tardía, repartidos en 84 zonas. (Los 3394 cambios con hueco eran todos correctos, y Nueva York, con offset negativo, acertaba por casualidad.)

En #226 lo cambié para leer un día antes y uno después, lo publiqué como @kalyx/core 1.4.8 y dejé la misma comparación como timezone.dst-oracle.test.ts. (temporal-polyfill solo se usa en los tests.) El comentario del código que decía erróneamente 'earlier' ahora dice 'compatible'. Otra vez, las muestras estaban concentradas en un solo signo.

Los 3KB invertidos en corrección

Estas correcciones costaron código. Kalyx fija en la CI un techo para el bundle del entry por defecto, y un PR que lo supera falla un check obligatorio. Ese techo empezó en 12KB y subía 1KB cada vez que entraba una funcionalidad, y en agosto de 2026, al rehacer por completo la corrección de zonas horarias y restricciones, lo subí de 17KB a 20KB de una vez.

El tamaño era un argumento de venta que aparecía en el badge del README. Un selector de fechas que se desplaza un día en zonas con offset negativo no sirve, sea pequeño o grande.

Si tengo que elegir entre pequeño y correcto, elijo correcto. Ahora el techo va justo. Según el documento del mapa de bytes del bundle del repositorio con fecha 2026-09-11, dist/index.cjs medido con el gzip por defecto de Node ocupa 20 259 B frente a un techo de 20 480 B, con un margen de 221 B. (Es el tamaño del propio archivo con las dependencias como externas, así que es una cantidad distinta de la del gráfico anterior.) La próxima funcionalidad tendrá que recuperar bytes antes de poder entrar.

Una conclusión distinta de la inicial

Lo que yo quería era usar bibliotecas de fechas complejas de forma declarativa. Al construirlo, descubrí que ya existían APIs de composición declarativas y opciones headless completas. La diferencia que quedaba estaba más adentro. Fijar el valor como un único instante, reducir la conversión entre coordenadas e instantes a dos funciones y proteger ese viaje de ida y vuelta con tests en todas las zonas horarias. El manejo del DST basado en Intl, la frontera de adaptador con cadenas y los siete pickers construidos con tres contextos son consecuencias de esa decisión.

Desde el objetivo de aprender, lo más importante que aprendí fue cómo afirmar que algo es "correcto". La comparación de bundles del artículo original medía cantidades distintas, y el test que pasaba en Seúl fallaba en Nueva York. Si no se anota también qué se midió y con qué muestra se comprobó, los números se convierten fácilmente en presunción.

Los límites también están claros. Soy el único maintainer, solo soporta React 19, y las descargas de npm de @kalyx/react entre el 5 y el 11 de septiembre de 2026 fueron 200, de las cuales 156 se concentraron en el día en que se publicó la 1.4.7. El problema de no poder separar coordenadas e instantes con tipos solo se contiene con documentación, y tampoco he decidido si garantizar como API pública los puntos de contacto para estilos, classNames y los atributos data-*. En accesibilidad tiene los roles grid en calendarios, combobox en campos de entrada y listbox en listas de horas, con navegación por flechas, Home/End y PageUp/PageDown, y la CI ejecuta las comprobaciones de jest-axe de 8 archivos de test, pero todavía no tengo base para decir que esté tan probada como React Aria.

Por eso, si tu app ya usa MUI, conviene mirar primero MUI X; si lo prioritario es la entrada por segmentos y una accesibilidad probada, React Aria; y si solo necesitas un calendario, react-day-picker. Si alguna vez has sufrido fechas que se desplazan un día en formularios donde los valores viajan como JSON, me alegraría que entonces le echaras un vistazo a Kalyx, y si conoces una solución mejor, te agradecería que me lo contaras en una GitHub Issue.

pnpm add @kalyx/react

En el Playground del sitio de documentación puedes probar los siete pickers y cambiar tú mismo la configuración de locale y timezone.

Al principio me centraba más en los resultados y el proceso que en el rendimiento y el costo. Como los resultados generados por la IA tenían bastantes fallos, había que verificarlos; y como necesitábamos obtenerlos rápido, muchas personas, incluido yo, comprábamos más tokens o pasábamos a una suscripción superior cuando se agotaban. Yo también lo hice. (De hecho, durante los primeros meses ni siquiera presté atención a cuánto estaba gastando en tokens.)

Sin embargo, con el tiempo empecé a ser cada vez más consciente del uso de tokens. Para las personas, la cuota mensual pesaba; para las empresas, crecían las dudas sobre los costos laborales y operativos. En MCP y function calling expliqué el protocolo que conecta a los agentes con sistemas externos; en Cuatro niveles de inteligencia de código, las herramientas de búsqueda de código y GitHub Trending; y en Archivos de contexto, los archivos de reglas que leen los agentes. Así, mis artículos hasta ahora se han centrado más en qué herramientas existen y cómo aprovecharlas bien. Sigo pensando que esos temas importan, pero con el tiempo el costo terminará siendo la pregunta que más interese.

En otro artículo, Cómo funcionan los tokens, expliqué qué son exactamente, cómo los crea BPE y qué ocurre dentro de un transformador cuando prompt caching reduce el precio unitario. Sobre esa base, aquí veremos primero cómo se factura el costo y dónde nacen las ineficiencias, después ordenaremos patrones de ahorro comprobados. Los patrones principales van acompañados del uso de tokens que medí yo mismo ejecutando la misma tarea con distintas estrategias.

¿De dónde surge el costo de los tokens?

Veamos de forma breve y directa cómo se generan los costos de tokens y cómo los proveedores los facturan.

Todo el texto que enviamos —prompt del sistema, definiciones de herramientas, historial de conversación y mensajes del usuario— se convierte en tokens de entrada, mientras que la respuesta del modelo se convierte en tokens de salida. Para el modelo, cada llamada es una entrada nueva que nunca ha visto. Da igual si la conversación fue ayer o si la llamada anterior ocurrió hace un minuto: en la nueva llamada se vuelve a enviar todo el contenido como entrada. (Este hecho tan simple es la clave del costo: el modelo no tiene memoria y nosotros se lo contamos todo otra vez.)

Aquí aparece otra variable. Volver a transmitir desde cero la parte estática de una llamada repetida es caro, por lo que los principales proveedores de LLM introdujeron prompt caching. La entrada estática se guarda una vez en caché y, en llamadas posteriores, los tokens leídos desde allí se cobran mucho más baratos. (En Cómo funcionan los tokens expliqué el mecanismo interno: cómo BPE crea tokens y cómo la caché reutiliza la KV cache del transformador para reducir el precio. Aquí nos centraremos en cómo ese mecanismo se traduce en costo.)

Tokens de entrada, tokens de salida y tokens de caché

Veamos cuatro campos del objeto usage que devuelve el SDK de Anthropic.

• input_tokens la parte de la entrada enviada que excluye las lecturas de caché
• output_tokens la respuesta generada por el modelo
• cache_creation_input_tokens los tokens guardados por primera vez en caché en esta llamada
• cache_read_input_tokens los tokens releídos desde una caché existente

A cada campo se le aplica una tarifa distinta. Los tokens de salida son los más caros y los leídos desde caché, los más baratos. Según la documentación oficial de Anthropic, una lectura de caché cuesta 0,1 veces la tarifa base de entrada, exactamente un 10 %. La escritura cuesta 1,25 veces la tarifa base con un TTL (Time To Live, periodo de validez de la caché) de cinco minutos y 2 veces con un TTL de una hora. Es decir, se paga un poco más en la primera llamada y se ahorra un 90 % a partir de la segunda.

La caché también tiene varias restricciones poco conocidas. El mínimo de tokens almacenables varía según el modelo e incluso según la versión de una misma familia. De acuerdo con Anthropic, Sonnet 4.6 y Opus 4.8 exigen 1.024 tokens, Opus 4.7 exige 2.048, y Haiku 4.5 junto con los antiguos Opus 4.5/4.6 exigen 4.096. Un prompt más corto no se almacena aunque se añada cache_control, sin mostrar ningún aviso. Una solicitud admite como máximo cuatro puntos de corte cache_control, y la caché se lee jerárquicamente en el orden tools → system → messages. Por eso, cambiar una sola definición de herramienta al principio invalida toda la caché posterior.

El descuento del 90 % nace de reutilizar entre llamadas la KV cache del transformador, mecanismo que expliqué en detalle en Cómo funcionan los tokens. Desde la perspectiva del costo, basta recordar algo: solo hay acierto de caché cuando el prefijo coincide exactamente. Por eso hay que poner el contenido estático al principio y el contenido dinámico que cambia en cada llamada al final. Incluso un solo carácter de una marca temporal al inicio del prompt invalida toda la caché que viene después.

Surge entonces una duda natural: «Pero la entrada cambia en cada turno de una conversación, ¿no debería romperse la caché casi siempre?». La respuesta corta es no. La entrada conversacional no se reescribe como un bloque nuevo en cada turno; sigue una estructura append que conserva lo acumulado al principio y solo agrega la nueva intervención al final. Una vez fijados el prompt del sistema, las herramientas y las preguntas y respuestas anteriores, permanecen intactos; solo se añade la pregunta más reciente. Si comparamos desde el inicio la entrada actual con la anterior, la primera diferencia siempre está en esa nueva pregunta final. La entrada completa cambia, pero casi todo el prefijo sigue igual y la caché sobrevive. (Solo se rompe en cada turno cuando un diseño defectuoso inserta valores dinámicos al principio. Herramientas como Claude Code y opencode mantienen fijo el inicio y anexan al final, por lo que el usuario no debe configurar nada. Los errores ortográficos tampoco afectan por la misma razón: aparecen al final, fuera del prefijo ya almacenado.)

Comparación de proveedores de IA

Al reunir las tarifas oficiales de Anthropic, OpenAI y Google vigentes en junio de 2026, el patrón se ve de inmediato. (Precios en USD por millón de tokens, con los modelos más habituales en flujos de programación.)

En los tres proveedores, los tokens de salida cuestan entre cinco y seis veces más que los de entrada. Por tanto, una respuesta más larga eleva rápidamente el costo aunque diga lo mismo. Dentro de una misma gama, la diferencia de precio entre modelos también llega a ser de tres a seis veces. La aritmética señala tres principios centrales: pedir respuestas más breves, usar un modelo más barato si produce la misma respuesta y almacenar en caché la entrada estática. (Otro cálculo resulta revelador. Si reutilizamos 100 veces un contexto estático de 10.000 tokens, con la tarifa base de GPT-5.5 cuesta $5 y leído desde caché cuesta $0.50. La caché ahorra $4.5 en esas 100 reutilizaciones y, como la primera escritura casi no tiene recargo, empieza a compensar desde la segunda llamada.)

Diferencias entre los mecanismos de caché

Aunque los descuentos sean similares, el diseño interno cambia según el proveedor. Entender esas diferencias facilita decidir una política.

La filosofía de cada proveedor queda clara. Anthropic pide marcar explícitamente qué se almacena, cobra una pequeña prima en la primera llamada (1,25 veces) y después ofrece un gran descuento. Al poder controlar la posición del prefijo, la tasa de lecturas resulta predecible. OpenAI automatiza todo: desde 1.024 tokens la entrada se almacena sin costo adicional, pero el usuario tiene menos control. Google ofrece ambos sistemas y cobra almacenamiento separado cuando el usuario gestiona la caché de forma explícita. La caché implícita conviene para reutilizaciones breves y frecuentes; la explícita con almacenamiento, para contextos grandes que deben conservarse una hora o más.

Definiciones de herramientas y tokenizadores

Hay otras dos variables con un impacto sorprendentemente grande.

La primera son las definiciones de herramientas. Cuando hay varios servidores MCP conectados, cada llamada incluye todos los nombres y esquemas de parámetros —más adelante mediremos cuánto infla esto el costo—. Incluso con las mismas herramientas, cambiar solo el modelo altera el gasto. La documentación de Anthropic muestra que la longitud del prompt de sistema para herramientas varía: con tool_choice: auto, Sonnet 4.6 y Haiku 4.5 usan unos 497 tokens, Opus 4.7 usa 675 y Opus 4.8 baja a 290. Antes del model routing conviene comprobar cuánto expande el modelo actual las definiciones, porque la diferencia puede ser considerable.

La segunda es la eficiencia del tokenizador, que divide el texto humano en unidades procesables por el modelo. Como vimos en Cómo funcionan los tokens, un mismo texto puede producir cantidades distintas según el tokenizador. o200k_base de OpenAI usa muchos menos tokens que cl100k_base con textos no ingleses, y Anthropic indica que, tras adoptar un nuevo tokenizador desde Opus 4.7, el mismo texto puede facturarse con hasta un 35 % más de tokens que en modelos anteriores. Elegir solo por tarifa puede hacer que el costo reaparezca por ineficiencia del tokenizador. Una comparación honesta multiplica precio unitario por cantidad esperada de tokens.

La diferencia destaca especialmente en coreano. Al tokenizar las mismas frases con dos tokenizadores de OpenAI, las oraciones técnicas en inglés dieron la misma cantidad, pero cl100k_base utilizó entre un 31 y un 43 % más tokens para el coreano que o200k_base. Un párrafo coreano de 167 caracteres llegó a convertirse en 169 tokens con el sistema antiguo: más tokens que caracteres. En promedio, cada carácter coreano consumió más de un token.

El tokenizador antiguo fragmenta el coreano de forma agresiva a nivel de bytes, mientras que el nuevo agrupa expresiones frecuentes como «개발» o «입니다» en un único token. Así, aun con la misma tarifa, una carga de trabajo centrada en coreano puede costar más de 1,5 veces solo por la eficiencia del tokenizador.

Llegados aquí surge otra pregunta: «¿Dónde estamos generando exactamente toda esta ineficiencia?».

Patrones habituales que desperdician tokens

El desperdicio es sorprendentemente común incluso cuando creemos usar bien la IA. Los patrones que he observado en mi trabajo y entre otros desarrolladores se agrupan así.

Demasiados servidores MCP y definiciones de herramientas

Ya lo mencioné, pero merece repetirse. Una vez conectados servidores MCP como Linear, GitHub, Notion, Figma, Slack o Sentry, rara vez se eliminan. Los esquemas sin usar inflan la entrada en cada llamada. Para resolverlo, Claude Code activa por defecto MCP Tool Search: al iniciar la sesión solo carga los nombres y descripciones de servidores, y el esquema completo aparece cuando el modelo llama realmente a la herramienta.

Medí el tamaño de la diferencia. Con 27 herramientas MCP de una sesión de Claude Code —10 de Serena, ocho de cuatro integraciones OAuth de claude.ai, dos de Figma y siete de agentmemory— envié el mismo mensaje de usuario con dos configuraciones. Una no tenía MCP; la otra tenía las 27 conectadas pero no disponibles para el modelo. En ambos casos hubo cero llamadas a herramientas.

Con la misma pregunta, el mismo modelo y una respuesta equivalente, la entrada pasó de 41 → 10,335 (+10,294) tokens en Opus 4.7. El costo por llamada subió de $0.0048 → $0.0563, unas 12 veces, y el aumento de 250 veces en la entrada añadió +783ms de latencia por la carga de prefill. Más llamativo que el importe fue que era un costo pagado en cada llamada aunque el usuario no usara ninguna herramienta MCP en ese turno. Ese es el costo que evita Tool Search. (Desde esta medición, depuro continuamente los servidores MCP que no uso.)

Acumulación de contexto y Lost in the Middle

Arrastrar una conversación larga no solo aumenta los tokens de entrada por llamada: también reduce la precisión. El artículo «Lost in the Middle» del equipo de Liu en Stanford cuantificó una curva en U: los modelos recuperan mejor la información clave al principio o al final y empeoran cuando queda enterrada en medio. Es la peor combinación: gastar más tokens para obtener una respuesta peor. Como el cálculo de self-attention crece con el cuadrado de los tokens, la atención disponible para cada uno se diluye al alargarse el contexto. El centro se debilita primero porque los datos de entrenamiento suelen concentrar la información importante en los extremos.

Si profundizamos, la forma en que el modelo trata la «posición» contiene dos tendencias que entierran el centro. Suenan técnicas, pero la intuición es sencilla.

Primero, el modelo escucha más a los tokens cercanos. RoPE (Rotary Position Embedding), la representación posicional usada por la mayoría de modelos abiertos actuales, conecta más débilmente dos tokens cuanto más separados están: un decay effect en el que la señal se desvanece con la distancia. Por eso los tokens lejanos reciben menos atención.

Segundo, el modelo envía demasiada atención al primer token. Debe repartir siempre el 100 % de su atención —softmax obliga a que los pesos sumen 1— y, cuando no hay nada especial que atender, tiene que desechar el sobrante en algún lugar, normalmente el primer token. Este fenómeno se llama attention sink. (El equipo de Xiao en el MIT lo cuantificó por primera vez en StreamingLLM. No ocurre porque el primer token sea importante, sino porque funciona como desagüe de atención sobrante.)

Juntas, ambas tendencias concentran la atención en los dos extremos —los tokens recientes cercanos y el primero—, mientras que la información del centro recibe el trato más débil. No es un fallo de un modelo concreto. LLaMA, Mistral y Qwen usan mecanismos de la familia RoPE, y se cree que Claude y GPT emplean enfoques similares. Lost in the middle es, por tanto, un sesgo común de la arquitectura moderna de transformadores.

Más recientemente, el fenómeno se denomina context rot. Un análisis del equipo de Chroma sometió a 18 modelos de frontera —GPT-4.1, Claude 4, Gemini 2.5 y Qwen3, entre otros— a la misma tarea NIAH (needle in a haystack). Cuando la entrada creció de 10k a más de 100k tokens, la precisión cayó entre un 20 y un 50 % según el modelo. Los 18 empeoraron y la familia Claude lo hizo más lentamente. Anthropic también lo explica como un problema de «presupuesto de atención» derivado de la atención n², que se consume entre los tokens. Mantener ligero el contexto reduce costos y protege la precisión.

Llamar subagent sin criterio

Delegar todo porque los subagent son útiles es otra trampa. Un subagent comienza en un contexto separado, así que paga desde cero el costo fijo del prompt de sistema y las herramientas. Si se delega un comando breve de shell o una consulta simple de git, ese arranque puede superar cualquier ahorro en el contexto principal. Según el informe de Anthropic sobre su sistema multiagente, un agente usa unas cuatro veces más tokens que un chat normal y un sistema multiagente unas quince veces más. Delegar solo tiene sentido si la mejora de precisión justifica ese costo.

La misma trampa aparece al conectar herramientas MCP. Cada herramienta activa añade su esquema al prompt del sistema en cada turno y se factura aunque no se use. «Activarlo todo por si acaso» puede parecer más seguro, pero las mediciones dicen otra cosa.

Probé precisión y costo con el mismo lote de preguntas sobre el código del reconciler de facebook/react v19, dividido en tres configuraciones:

• Sin herramientas
• Una herramienta (CodeGraph, Serena, ripgrep o grep básico)
• Las cuatro herramientas conectadas a la vez

Destacaron tres resultados. (Aquí recall indica cuán completas fueron las respuestas correctas.)

• Sin herramientas obtuvo un recall medio de solo 0,31, lo que confirma que las herramientas aportan valor.
• Solo Serena (LSP) logró 1,00 de recall por $0.38, la estrategia individual más eficiente.
• Las cuatro herramientas conectadas bajaron el recall a 0,89 y elevaron el costo a $0.47. En preguntas multi-hop, su puntuación coincidió con CodeGraph solo (0.78 / 0.88) hasta el segundo decimal: el modelo tendió a una herramienta y heredó sus debilidades.

Un principio sirve tanto para subagent como para las herramientas: el costo extra solo compensa cuando mejora la precisión. Elegir la herramienta adecuada para el dominio es más barato y preciso que activarlas todas por si acaso.

Entonces, ¿qué métodos comprobados permiten ahorrar tokens? ¿Existen estrategias que funcionen de verdad?

Formas comprobadas de ahorrar tokens

Cada patrón ataca un eje distinto: algunos reducen la entrada, otros abaratan la misma entrada y otros asignan el mismo trabajo a un modelo más económico. Veámoslos uno a uno.

Prompt caching

Es el efecto más inmediato. Como vimos, las lecturas de caché cuestan 0,1 veces la tarifa base de entrada. Tras pagar una pequeña prima de escritura de 1,25 veces en la primera llamada, la misma sección estática puede reutilizarse desde la segunda a una décima parte del precio.

Desde la perspectiva del ahorro, hay un punto clave: en cualquier sistema de caché, las partes casi idénticas entre llamadas —herramientas, fragmentos de código y contexto RAG— son precisamente las almacenables. El beneficio se mantiene si esos bloques no se mezclan con contenido dinámico, como la pregunta actual o el resultado recién llegado de una herramienta. Al llamar directamente a la API, agrupar lo estático al principio y lo dinámico después logra casi todo el ahorro. En Claude Code u opencode, la propia herramienta ordena esos bloques.

Agrupar trabajo asíncrono con Batch API

Cuando una llamada no necesita terminar de inmediato, Batch API es la forma más sencilla de reducir la tarifa. Anthropic, OpenAI y Google descuentan un 50 % tanto en entrada como en salida a cambio de entregar el resultado en un máximo de 24 horas. En Anthropic, la mayoría de los lotes termina en menos de una hora, pero el SLA es de 24 horas. La llamada no cambia y el precio se reduce a la mitad, por lo que el costo de adopción es mínimo.

Ese 50 % resulta especialmente interesante porque se acumula multiplicativamente con otros ahorros. Anthropic dice de forma explícita que los descuentos de caché y lote se combinan. Para entrada estática: tarifa estándar × 0.5 (lote) × 0.1 (lectura de caché) = 0.05 veces, es decir, un 5 % del precio estándar. La clave es que se multiplican, no se suman.

Calculé la diferencia. Supongamos 100 trabajos con 10.000 tokens de contexto estático, 500 de entrada dinámica y 1.000 de salida. Con las tarifas de Opus 4.8, comparé cuatro estrategias.

Solo la caché reduce el costo un 57 %, solo el lote un 50 %, y ambos juntos hasta un 79 %. Se multiplican en la parte estática en lugar de sumarse. (La salida no se almacena y solo recibe el 50 % del lote; cuanto mayor sea su proporción, menor será el ahorro total respecto al 79 %. Cuanto más pese la entrada estática, mayor será el efecto.) Hay muchos trabajos donde nadie necesita esperar ante la pantalla: indexación nocturna, evaluación de artículos antes de publicar, extracción de datos e informes periódicos.

No todo puede aplazarse. Batch no encaja cuando el tiempo de respuesta aporta valor, como en la sesión principal de un agente de programación o un chat interactivo. Separar el trabajo en «resultado inmediato» y «resultado antes del siguiente día laboral» puede reducir la factura a la mitad.

Aislar trabajo verbose con un subagent

En palabras de la documentación oficial de Claude Code, un subagent «opera en su propia ventana de contexto aislada; las llamadas y resultados intermedios permanecen dentro del subagent y solo el mensaje final vuelve al padre». Delegar una tarea verbose deja así solo un resumen limpio en el contexto principal. Según el artículo de Anthropic sobre context engineering, aunque un subagent use decenas de miles de tokens explorando, suele devolver al padre un resumen comprimido de 1.000 a 2.000. El beneficio para el contexto principal es claro.

Una tarea verbose produce una enorme cantidad de tokens para encontrar una respuesta de una línea. Ejecutar pruebas, buscar documentación y analizar registros son ejemplos típicos.

Hay que aclarar un malentendido: un subagent no reduce automáticamente el costo total. El informe de Anthropic dice que los agentes usan unas cuatro veces más tokens que un chat y los sistemas multiagente unas quince veces más. Un subagent protege la precisión y el costo de un contexto principal largo al extraer de él la salida verbose; no es magia que siempre reduzca el gasto. Por eso solo conviene delegar si el ahorro de limpieza del contexto supera el costo de arranque. Para tareas cortas, es más barato que el padre actúe directamente.

También importa el dominio. El informe de Anthropic afirma que, en su evaluación interna, un líder Opus 4 con subagent Sonnet 4 mejoró un 90,2 % frente a un único Opus 4. Pero la mejora no es uniforme. El mismo informe advierte que los dominios donde los agentes deben compartir contexto o tienen muchas dependencias no encajan bien, y señala la programación como caso exacto. La investigación permite explorar direcciones independientes en paralelo; el código vive en un grafo de dependencias. (Si usa una configuración multiagente para programar, conviene comprobar si el flujo realmente es exploración paralela. Un agente único con un subagent de exploración aislado puede ser una base más segura.)

compact y progressive disclosure

El comando /compact de Claude Code comprime toda la conversación en un resumen y reinicia con un contexto nuevo. Según Anthropic, no es un simple recorte sino un resumen semántico: conserva el trabajo en curso y los cambios recientes, y elimina salidas repetitivas que probablemente no vuelvan a consultarse. A diferencia de /clear, que borra todo, /compact deja un resumen. Cuando la ventana llega cerca del 95 %, auto-compact hace lo mismo automáticamente. Ordenar una sesión larga corta la acumulación de entrada.

Mirando más adentro, /compact es solo la última etapa que el usuario puede activar; antes funciona una tubería automática de cuatro etapas. Según el estudio externo «Dive into Claude Code», query.ts revisa estas cinco etapas antes de cada llamada.

• Budget Reduction recorta las partes de cada salida de herramienta que superan el límite.
• Snip elimina el historial más antiguo en el eje temporal.
• Microcompact realiza una compresión fina sin perder conciencia de caché.
• Context Collapse reproyecta el historial muy largo en read-time para reducir su dimensión.
• Auto-Compact activa la compresión semántica al 95 % como último recurso.

Las etapas superiores son más ligeras y baratas; las inferiores, más pesadas pero eficaces. El diseño reconoce que una sola estrategia no resuelve toda presión de contexto. Invocar /compact equivale aproximadamente a adelantar la última etapa automática.

La misma idea aparece en la arquitectura Skills de Claude Code. Si /compact reduce el contexto ya acumulado, la carga en tres fases de /skills evita que se acumule desde el principio.

Según Anthropic, una skill se carga en tres fases. Al inicio solo entran su nombre y descripción breve —unos 100 tokens—. El cuerpo (SKILL.md, menos de 5.000 tokens) se carga cuando se activa. Si se ejecutan scripts o recursos mediante bash, solo vuelve la salida; el código no entra al contexto. Por eso instalar decenas de skills apenas aumenta el contexto inicial.

Model routing: un modelo más barato para la misma respuesta

La entrada de Opus 4.8 cuesta cinco veces la de Haiku 4.5. Usar el modelo mayor para toda búsqueda simple, exploración o resumen breve desperdicia dinero. Encaminar según dificultad —Haiku → Sonnet → Opus— y reservar Opus para razonamiento pesado se está volviendo estándar. La investigación RouteLLM de LMSYS mostró un router que conservó el 95 % de la calidad de GPT-4 reduciendo al 14 % las llamadas al modelo fuerte, aunque el benchmark era de razonamiento general y no de programación.

El ecosistema también se ha asentado. Entre las pasarelas comerciales están OpenRouter, Martian y NotDiamond; en código abierto, RouteLLM de LMSYS y capas de observabilidad de costos como LiteLLM y Bifrost. En Anthropic, el argumento de selección de modelo del Agent SDK, el campo model del subagent de Claude Code —Explore usa Haiku por defecto— y el comando /model sirven para este routing. Hay una salvedad: al llamar directamente a una API, esta no evalúa la dificultad para elegir modelo. Las API de Anthropic, OpenAI y Google ejecutan exactamente el nombre indicado. El routing automático es una opción de producto, como Auto de Cursor, el modo auto de ChatGPT u openrouter/auto. Para ahorrar así hay que construirlo con una pasarela o clasificador.

Eso no significa que convenga añadir cualquier router automático. Auto Router de OpenRouter, que cambia el modelo en cada llamada, choca con prompt caching. La caché efímera de Anthropic solo acierta con el mismo modelo y prefijo. Si cambia la clave del modelo, falla la clave de caché: se pierde el descuento del 90 % y es habitual ahorrar con routing para devolverlo en fallos de caché. Por eso OpenRouter recomienda stickiness mediante session_id.

El patrón práctico es simple: no clasificar cada llamada, sino dividir estáticamente por tipo de tarea. El campo model de subagent sigue este patrón. Explore usa siempre una vía Haiku para explorar código; revisión usa una vía Opus. Dentro de cada vía se repiten modelo, prompt y herramientas, y cada modelo acumula su propia caché. Que «routing se vuelve estándar» significa cada vez más una bifurcación estática por tarea con «coordinador + ejecutor», no un clasificador por llamada. Así conviven routing y caché.

Cursor Composer 2.5

Es una vía distinta de ahorro, pero también puede usarse un agente como Cursor. Composer 2.5, modelo propio de Cursor publicado el 18 de mayo de 2026, se basa en el checkpoint abierto Kimi K2.5 de Moonshot AI y fue ajustado para programación. Cursor afirma que en sus benchmarks alcanza un rendimiento comparable a Claude Opus 4.7 por cerca de una décima parte del precio. La tarifa publicada es $0.50 de entrada y $2.50 de salida, un orden de magnitud por debajo de $5.00 y $25.00 de Opus 4.8.

Como Cursor midió su propio modelo, es prudente no tomar las cifras absolutas como definitivas. Importa la tendencia: un modelo menor especializado en código puede rendir de forma comparable a uno de frontera general en la misma tarea y reducir el costo en un orden de magnitud. Es una de las tendencias de ahorro más claras de 2026.

Lo más interesante es que no solo baja la tarifa: cuando el modelo se diseña junto con un IDE, también reduce la propia entrada. Composer y Cascade están entrenados para consumir con eficiencia el contexto que envía el IDE —archivo actual, archivos vecinos y símbolos indexados—. Así se reduce la inflación causada cuando un modelo general pide más archivos y repite operaciones de grep y lectura. Baja un orden de magnitud la tarifa y también un poco la cantidad de tokens, por lo que el ahorro real puede superar la diferencia de precio.

Sacar el contexto fuera del contexto

Una de las tendencias más interesantes de 2026 es cargar «solo lo necesario, cuando sea necesario». Anthropic lo llama contexto just in time (JIT). En vez de incluir todos los recursos por adelantado, el agente conserva referencias ligeras como rutas o consultas y recupera el material mediante herramientas cuando lo necesita. Claude Code sigue este patrón al leer archivos bajo demanda con glob y grep en lugar de cargar toda la base de código.

memory tool y context editing, publicados por Anthropic con Sonnet 4.5, siguen la misma filosofía. La «memoria» de memory tool no es el historial de conversación que vive en la ventana y desaparece al cerrar la sesión, ni un archivo como CLAUDE.md escrito por una persona y cargado al inicio. memory tool es una herramienta con la que el modelo escribe y lee archivos directamente.

En detalle, las interfaces son sencillas. memory tool permite a Claude crear, leer, actualizar y borrar archivos en un directorio dedicado de la infraestructura del usuario. El modelo trata las notas como un sistema de archivos común. Alojarlo en la infraestructura del usuario es decisivo: ofrece memoria persistente fuera de la ventana entre sesiones y deja al usuario controlar almacenamiento y retención. La memoria de sesión es volátil dentro del contexto; esta permanece fuera. context editing actúa en dirección opuesta: al acercarse al límite, elimina resultados antiguos de herramientas que ya no se consultan, mantiene la conversación y permite ejecutar el agente más tiempo.

En la evaluación de Anthropic, ambas herramientas mejoraron el rendimiento un 39 % sobre la línea base y context editing por sí solo un 29 %. En una evaluación de búsqueda web de 100 turnos, el consumo cayó un 84 %. (Son benchmarks del proveedor, pero la dirección es clara: diseñar cómo vaciar el contexto importa cada vez más que llenarlo.) Esto coincide con la tubería de /compact: /compact reduce lo que está dentro; memory tool crea almacenamiento fuera. Se complementan.

Conclusión

En conjunto, el ahorro se reduce a tres ejes: enviar menos para el mismo trabajo, pagar menos por la misma entrada y asignar la misma respuesta a un modelo más barato. Prompt caching, Batch API, aislamiento con subagent, /compact, memory tool y context editing, model routing y modelos especializados solo difieren en qué eje atacan. La dirección de 2026 puede resumirse así: el centro de gravedad pasa de llenar el contexto a vaciarlo y seleccionarlo, es decir, a context engineering. Como muestra context rot, un contexto ligero mejora el costo y la precisión.

No existe una única respuesta correcta. Cada equipo trabaja distinto, e incluso para una misma persona la estructura de costos cambia al escribir prosa o código. Pero algo es seguro: con un ecosistema tan rápido, asumir que «el patrón que funcionó ayer funcionará hoy» resulta cada vez más arriesgado. Seguir modelos, herramientas y tarifas nuevas, y adquirir el hábito de validarlos con un pequeño POC en el propio flujo, quizá sea la forma de ahorro más discreta y duradera. Recomiendo a cada lector revisar al menos una vez su propia contabilidad de tokens. (Para entender la raíz de estas estrategias, conviene leer también BPE y KV cache en Cómo funcionan los tokens.)

Queda una pregunta. Si ya sabemos vaciar y seleccionar el contexto, ¿qué sigue? Los trabajos publicados desplazan el foco un paso más allá, hacia el sistema de agentes completo: cómo operarlo (diseño del harness), cómo medir si funcionó bien (eval) y cómo confinarlo cuando falla (containment). Curiosamente, cuando la actitud de «mídelo con un POC» de este artículo escala al sistema, se convierte exactamente en eval. Exploraré esa dirección en Más allá del contexto.

Hasta ahora he escrito sobre todo acerca de cómo aprovechar bien las herramientas de IA, cuáles están de moda y por qué. Sin embargo, mientras preparaba el artículo sobre cómo ahorrar tokens, volví a reparar en algo: para hablar de reducir costes, primero hay que entender «qué es un token y cómo se factura», pero nunca había explicado con rigor esa base. (Al escribir la guía de ahorro, la parte dedicada al funcionamiento de los tokens creció lo suficiente como para merecer un artículo propio.)

Este texto ofrece, por tanto, los fundamentos antes de entrar en las técnicas de ahorro. Veremos qué es exactamente un token si no es una palabra ni un carácter (BPE), en qué forma entra en el modelo (embedding), por qué la salida cuesta más que la entrada (prefill/decode), de qué parte del Transformer —la arquitectura de la red neuronal— nace el ahorro de prompt caching (KV cache) y por qué un contexto más largo resulta más caro (el coste cuadrático de la atención). Si buscas medidas prácticas, después puedes continuar con Cómo ahorrar tokens.

Un token no es una palabra ni un carácter

Empecemos por el hecho más básico: un token no es una palabra ni un carácter. Es una unidad de un vocabulario que el modelo construye comprimiendo secuencias de caracteres frecuentes en los datos de entrenamiento.

Nuestra intuición al preguntar «¿cuántas palabras tiene esta frase?» no coincide con la forma en que un modelo divide el texto. El modelo agrupa como una sola unidad combinaciones de caracteres que suelen aparecer juntas y segmenta el texto entrante según ese vocabulario. Por eso una palabra puede corresponder a un único token o dividirse en varios.

El algoritmo que construye ese vocabulario es BPE, una base común a casi todos los LLM modernos.

El algoritmo BPE

BPE (Byte Pair Encoding o codificación por pares de bytes) amplía un vocabulario fusionando repetidamente el par de símbolos adyacentes que aparece con mayor frecuencia en un símbolo nuevo.

Lo curioso es que no nació para el procesamiento del lenguaje natural. Philip Gage propuso BPE por primera vez en 1994 como técnica de compresión de datos. El método sustituía el par de bytes más frecuente por un byte que no apareciera en los datos y almacenaba aparte, en una tabla, las reglas de sustitución.

El equipo de Sennrich, de la Universidad de Edimburgo, trasladó la idea al problema del vocabulario en la traducción neuronal. En «Neural Machine Translation of Rare Words with Subword Units», publicado en 2015 y presentado en ACL 2016, resolvieron con BPE la incapacidad de un vocabulario fijo para manejar palabras raras o desconocidas. La idea consiste en representar las palabras como combinaciones de fragmentos subword más pequeños en vez de memorizarlas enteras; así, incluso una palabra ausente del vocabulario puede codificarse con piezas conocidas.

El proceso es sorprendentemente sencillo.

1. Al principio, cada carácter individual es un token.
2. Se busca en el corpus el par de tokens adyacentes más frecuente.
3. Se fusiona ese par en un token nuevo y se sustituyen por él todas sus apariciones en el corpus.
4. Se repiten los pasos 2 y 3 hasta alcanzar el tamaño de vocabulario objetivo.

Así, aunque al principio cada carácter es un token, combinaciones frecuentes como «th», «the» o «tion» acaban fusionándose en tokens únicos. Cuanto más habitual es un patrón, más probable es que forme un bloque mayor.

La familia GPT lleva la idea un paso más allá con BPE a nivel de bytes. Primero convierte el texto en un flujo de bytes UTF-8 y después aplica BPE. De este modo, el vocabulario base puede empezar con solo 256 entradas —una por cada byte posible— y aun así codificar cualquier texto representable en UTF-8 sin tokens desconocidos. Ya sean emojis, caracteres chinos o símbolos especiales, siempre existe al menos una representación a nivel de byte.

El mismo texto, distinto número de tokens

Debido a esta estructura, un mismo texto puede producir cantidades de tokens muy distintas según el tokenizer, la herramienta que divide el texto escrito por personas en unidades que el modelo puede procesar. Según cómo se haya entrenado el vocabulario, una misma frase puede descomponerse en piezas más pequeñas o en bloques mayores.

Los datos que OpenAI publicó junto con GPT-4o muestran bien la diferencia. El nuevo tokenizer o200k_base de la familia GPT-4o representa el mismo texto con menos tokens que cl100k_base, empleado por GPT-4. En inglés es alrededor de 1,1 veces más eficiente, pero la brecha crece en otros idiomas. En los ejemplos breves publicados, el número de tokens bajó unas 1,4 veces en chino y japonés, 1,7 veces en coreano y hasta 2,9 veces en hindi. (Desde la perspectiva de quien usa coreano, resulta llamativo que el salto generacional del tokenizer se perciba mucho más que en inglés.)

En una perspectiva más amplia también hay diferencias entre idiomas. En el análisis de Yennie Jun con cl100k_base, una frase con el mismo significado casi siempre usa menos tokens en inglés, mientras que los idiomas con sistemas de escritura propios suelen necesitar más. El hindi y el bengalí pueden usar cinco veces más tokens que el inglés, y el birmano más de diez veces. El coreano y el chino también se tokenizan en más piezas que el inglés, aunque sin llegar a esos extremos.

De aquí se desprende una consecuencia práctica importante. Al introducir un nuevo tokenizer a partir de Opus 4.7, Anthropic indicó en su documentación oficial de precios que «el mismo texto puede facturarse con hasta un 35 % más de tokens que en modelos anteriores». Aunque el precio por token no cambie, la factura aumenta en la misma proporción que el número de tokens. Una comparación honesta entre modelos debe mirar no solo la tarifa, sino la tarifa multiplicada por el número de tokens previsto.

Pero estos tokens segmentados no entran en el modelo como caracteres o palabras literales. ¿Qué forma adopta entonces un token como entrada del modelo?

Cómo entran los tokens en el modelo

Las redes neuronales no pueden trabajar directamente con texto. En último término, un modelo solo calcula con números; más exactamente, con vectores, es decir, conjuntos de números. Por eso, antes de entrar en el modelo, los tokens pasan por varias etapas que los convierten en valores numéricos.

El orden es el siguiente.

1. Texto → tokens: un tokenizer BPE divide el texto en fragmentos de token.
2. Token → token ID: cada token se asigna a un ID entero que indica su posición en el vocabulario. Por ejemplo, si " the" es el token número 1.234, su ID será 1234.
3. Token ID → vector de embedding: el ID selecciona la fila correspondiente de la matriz de embeddings. Esta matriz es una tabla enorme de tamaño vocabulary size × model dimension (d_model); cada token ID corresponde a una fila, es decir, a un vector. Podemos imaginar ese vector como unas coordenadas que contienen el «significado» del token.
4. Añadir información posicional: por sí misma, la autoatención desconoce el orden de los tokens. Es decir, vería «yo te quiero» y «te yo quiero» como lo mismo. Por ello se inyecta información posicional en cada vector de token para comunicar el orden de la secuencia.

Como la explicación resulta abstracta solo con palabras, he añadido una herramienta interactiva para experimentar con las cuatro etapas. Al cambiar la frase o pulsar un token, se puede seguir su recorrido desde el ID hasta el vector de embedding y ver cómo la información posicional produce el vector de entrada final. (Solo se muestran unas pocas dimensiones, pero conviene recordar que el vector real de GPT-4 tiene 12.288.)

La dimensión del modelo (d_model) es la longitud del vector que representa un token. En el artículo original del Transformer era 512, pero en los LLM actuales es mucho mayor. (Incluso Llama 2 7B usa 4.096 dimensiones.) Una dimensión mayor permite expresar con más riqueza diferencias sutiles de significado, a costa de más cálculo y memoria.

La forma de introducir información posicional también ha cambiado. El Transformer original sumaba a los embeddings vectores de posición construidos con funciones seno y coseno. RoPE (Rotary Position Embedding), estándar de facto en los LLM abiertos actuales, inyecta en cambio la posición relativa durante el cálculo de la atención al rotar los vectores Query y Key. (El mecanismo cambia, pero el objetivo es el mismo: dotar al Transformer de sentido del orden.)

En resumen, el flujo es texto → tokens → token IDs → vectores de embedding (+ información posicional) → entrada del Transformer. El «número de tokens» de una factura corresponde a la segunda etapa de este proceso: cuántos tokens produjo la segmentación del texto.

Ya sabemos cómo se crean los tokens y en qué forma entran en el modelo. Pero cuando este los procesa, ¿por qué cuestan tan distinto la entrada y la salida, y cómo puede abaratarse el envío repetido de una misma entrada?

Por qué la entrada es barata y la salida es cara

Quien haya trabajado con tokens probablemente se lo haya preguntado: en las tablas de precios, los tokens de salida cuestan varias veces más que los de entrada. En Anthropic, la tarifa de salida es exactamente cinco veces la de entrada en todos los modelos. (Opus cuesta $5 de entrada y $25 de salida; Haiku, $1 y $5.) Si es el mismo token, ¿por qué cambia el precio según entre o salga?

La respuesta es que el modelo procesa los tokens de maneras completamente distintas en la entrada y la salida. La inferencia de un LLM tiene dos etapas.

• prefill (procesamiento de la entrada): procesa todos los tokens de la instrucción a la vez y en paralelo. Contenga 1.000 o 10.000 tokens, la GPU los recorre conjuntamente y calcula los vectores K/V (Key/Value) de cada uno. El cálculo total es considerable, pero el paralelismo mejora la eficiencia por token.
• decode (generación de la salida): genera los tokens de la respuesta en secuencia, de uno en uno. Tras producir uno, lo añade a la entrada y genera el siguiente. El ciclo continúa hasta completar la respuesta.

Esta asimetría crea la diferencia de coste. Según el análisis de rendimiento de inferencia de Databricks, prefill es una etapa limitada por el cálculo, mientras que decode está limitado por el ancho de banda de memoria. Durante decode, para producir cada token hay que volver a leer de la memoria de la GPU todos los pesos del modelo, y cada pasada solo genera un token. Gran parte de la enorme capacidad de cálculo de la GPU queda ociosa. (En palabras de Databricks, se paga por mantenerla funcionando sin utilizar el cálculo disponible.)

En otras palabras, los tokens de entrada se procesan eficientemente juntos mediante prefill paralelo, mientras que los de salida deben extraerse ineficientemente de uno en uno. Factores comerciales como la demanda o el margen también pueden influir en el precio, pero esta ineficiencia de decode forma parte de su fundamento técnico. «Recibir una respuesta corta» no es, por tanto, un consejo de ahorro genérico: reduce directamente la etapa más cara.

¿Hay forma de hacer que decode sea al menos un poco menos ineficiente? Aquí entra en juego KV cache.

Cómo el almacenamiento en caché reduce el precio

Prompt caching guarda una vez la entrada estática en una caché para que las llamadas siguientes la lean a un precio mucho menor. Según la documentación oficial de Anthropic, una lectura cuesta 0,1 veces la tarifa base de entrada: exactamente un 10 %. La escritura cuesta 1,25 veces con un TTL (Time To Live, periodo de validez de la caché) de cinco minutos y 2 veces con un TTL de una hora. Se paga un poco más en la primera llamada y se ahorra un 90 % desde la segunda.

Pero ¿cómo puede reducirse el precio un 90 %? ¿Y por qué es tan estricta la condición de que «el prefijo coincida exactamente»? Ambas respuestas aparecen al mirar dentro del Transformer.

KV cache

Al procesar los tokens de entrada, el modelo crea los vectores Query/Key/Value (Q/K/V) correspondientes. La autoatención calcula puntuaciones de atención mediante el producto escalar de Query y Key y usa esas puntuaciones para obtener una suma ponderada de los valores. Es el cálculo que determina cuánto debe «consultar» un token a los demás.

Aquí es donde decode plantea el problema descrito antes. Para crear cada nuevo token, el modelo necesita los K/V de todos los tokens anteriores. Recalcularlos desde cero en cada paso repetiría indefinidamente el mismo trabajo.

KV cache elimina esa duplicación. Almacena los K/V ya calculados y, al generar un token nuevo, lee y reutiliza desde la caché los K/V anteriores en lugar de volver a calcularlos. Dentro de una secuencia, el coste de producir un token adicional pasa así de O(n²), que recalcularía toda la secuencia en cada paso, a O(n), que solo lee la caché. (En rigor, hablamos del coste por paso; la idea esencial es sencilla: no recalcular lo ya calculado.) Esta es también la razón por la que decode está limitado por la memoria: cada paso debe leer de nuevo el KV cache desde la memoria.

Reutilización entre llamadas

Si KV cache nació para acelerar decode dentro de una respuesta, prompt caching propone reutilizar esa estructura de memoria no solo dentro de una llamada, sino también entre una llamada y la siguiente.

Los K/V de un prefijo estático —una instrucción del sistema, definiciones de herramientas o fragmentos de código cuyo comienzo cambia poco— permanecen en la memoria de la GPU durante un TTL de cinco minutos o una hora. Si la siguiente llamada empieza con el mismo prefijo, el modelo omite por completo el cálculo de sus K/V y los lee directamente de la caché. En sentido estricto, la tarifa de los tokens de entrada no baja por arte de magia: desaparece el trabajo de GPU necesario para calcularlos. La reducción del 90 % refleja ese cálculo evitado.

Al entender el mecanismo, también se entiende la exigencia de coincidencia exacta del prefijo. Un acierto de caché se decide comparando el hash acumulativo del prefijo. Como la autoatención es causal, cambiar un solo token anterior modifica los K/V de todos los tokens posteriores. Basta con añadir una marca temporal al principio de la instrucción para que su valor cambie en cada llamada, el hash deje de coincidir y toda la caché posterior quede invalidada.

Anthropic lee la caché con la jerarquía tools → system → messages. Por eso, cambiar una sola definición de herramienta al principio invalida toda la caché que viene detrás. La conclusión es simple: el contenido estático debe ir primero y el contenido dinámico que cambia en cada llamada, al final.

La caché también tiene restricciones menos conocidas. El mínimo de tokens que admite depende del modelo e incluso de la versión dentro de una misma familia. Una instrucción más corta que el umbral no se guarda, sin aviso, aunque el almacenamiento en caché esté activado. (Como esos mínimos y las políticas de cada proveedor afectan directamente al diseño de costes, los explico con las tablas de precios en la guía de ahorro de tokens.)

Por qué la ventana de contexto impone un límite de tokens

El último concepto imprescindible es la ventana de contexto: el número máximo de tokens que un modelo puede aceptar a la vez. Entender el motivo de este límite también aclara la conocida advertencia de que «un contexto más largo cuesta más».

La clave está en la estructura de cálculo de la autoatención. La atención hace que cada token consulte una vez a todos los demás. Con n tokens hay n × n pares, por lo que el cálculo y la memoria de la autoatención crecen con el cuadrado de la longitud n de la secuencia. Al duplicar los tokens, el coste de la atención se cuadruplica. (Conviene precisar que no todo el modelo es O(n²); lo es la etapa de atención.)

Las estimaciones de Hugging Face muestran lo acusada que es esta subida cuadrática. Con atención estándar sin optimizar, almacenar solo la matriz de puntuaciones requiere unos 50 MB para una entrada de 1.000 tokens, cerca de 19 GB para 16.000 tokens y casi 1 TB para 100.000.

El KV cache también ocupa memoria en proporción al número de tokens. Conforme crece el contexto, los K/V que hay que conservar se acumulan linealmente. En definitiva, el límite de la ventana de contexto es una frontera física fijada por el modelo: más allá, la memoria y el cálculo dejan de ser manejables.

Por eso, arrastrar sin cambios una conversación larga no consiste solo en sumar tokens de entrada. El coste de la atención crece al cuadrado y, al acercarse al límite, también disminuye la precisión con que el modelo maneja la información. (Esta pérdida de precisión está directamente relacionada con la degradación del contexto, tratada en la guía de ahorro; mantener un contexto ligero beneficia tanto al coste como a la calidad de las respuestas.)

Conclusión

En conjunto, el funcionamiento de los tokens se resume en unos pocos hechos. Un token es una unidad de vocabulario que BPE crea agrupando patrones frecuentes; tras asignarse a un token ID, se convierte en un vector de embedding y entra en el modelo. La entrada se procesa de una vez mediante prefill paralelo, mientras que la salida es más cara porque debe extraerse token a token; KV cache reduce esa ineficiencia reutilizando los K/V. La caché no abarata por magia, sino porque el Transformer evita recalcular K/V ya obtenidos, y de esta estructura se deriva la estricta condición de que el prefijo sea idéntico. Por último, un contexto más largo cuesta más porque el coste de la atención crece con el cuadrado del número de tokens.

Con esta base, la economía de los tokens se ve con mucha más claridad. Acortar la salida, organizar la instrucción para no romper la caché, mantener ligero el contexto o pasar a un modelo más barato cuando ofrece la misma respuesta son estrategias asentadas en estos principios. Si has llegado hasta aquí para entender el mecanismo, te recomiendo seguir con la guía de ahorro de tokens y comprobar cómo estas ideas reducen los costes reales.

Este artículo está pensado para quienes tienen CLAUDE.md, AGENTS.md, SKILL.md y .cursor/rules acumulados en un mismo proyecto y no tienen claro cuándo se lee cada uno ni qué escribir en él. Al terminar, conocerás las diferencias entre estos archivos, cómo los cargan los agentes y un criterio respaldado por un estudio de ETH Zurich: escribir solo la información que el agente no puede inferir.

Trabajo como desarrollador frontend y utilizo Claude a diario. Con el tiempo, apareció un CLAUDE.md en la raíz del proyecto, junto a un AGENTS.md que alguien había creado; .cursorrules seguía olvidado en un rincón y yo mismo terminé creando una carpeta .claude/skills/ siguiendo algún artículo que había visto. (Cuando me di cuenta, había unos cinco archivos con contenidos parecidos).

Agentes sin memoria persistente

Los agentes de codificación con IA tienen una limitación fundamental: carecen de memoria persistente. Cada sesión empieza desde cero y, en la conversación siguiente, no recuerdan las convenciones acordadas ayer ni la estructura de carpetas explicada una hora antes. Los archivos de contexto son el mecanismo más sencillo para resolver este problema. Si colocamos en el proyecto un archivo que se lea automáticamente al comenzar cada sesión, no tendremos que repetir siempre las mismas explicaciones.

El problema es que cada herramienta creó por separado archivos basados en la misma idea. Claude Code lee CLAUDE.md; Cursor, .cursorrules (actualmente deprecated y sustituido por la recomendación de usar .cursor/rules); GitHub Copilot, .github/copilot-instructions.md; y OpenAI Codex, AGENTS.md. Si un equipo utiliza varias herramientas, termina copiando el mismo contenido en cuatro lugares distintos.

CLAUDE.md

CLAUDE.md es un archivo que Claude Code lee automáticamente al iniciar una sesión. Según la documentación oficial de Anthropic (code.claude.com/docs/en/memory), Claude Code busca CLAUDE.md en tres niveles.

• Memoria de usuario (~/.claude/CLAUDE.md): valores globales predeterminados que se aplican a todos los proyectos de la máquina
• Memoria del proyecto (CLAUDE.md en la raíz del proyecto): se incluye en git y la comparte todo el equipo
• Memoria local (CLAUDE.md en un subdirectorio): solo se carga adicionalmente al trabajar en ese directorio

Cuando existen los tres niveles, Claude los lee todos y los concatena (concatenate). No elige uno solo según su prioridad, sino que los más específicos se añaden encima, como en el cascade de CSS. (Se combinan; no se reemplazan). Por tanto, distribuir reglas sobre un mismo tema entre varios niveles puede generar conflictos. (La documentación oficial de Anthropic indica que el comportamiento no está garantizado cuando hay conflictos).

Hay un detalle que suele pasarse por alto: lee todos los CLAUDE.md que encuentra al ascender desde el directorio de trabajo actual hasta la raíz del repositorio. Así, si trabajamos dentro de packages/ui/ en un monorepo, se cargan tanto el CLAUDE.md de la raíz como packages/ui/CLAUDE.md. (Es una capacidad potente, pero también implica que el contexto puede crecer sin que nos demos cuenta).

AGENTS.md

AGENTS.md es un estándar creado para resolver la proliferación de archivos específicos de cada herramienta que acabamos de describir. En diciembre de 2025, OpenAI donó este estándar a la Agentic AI Foundation (AAIF) de la Linux Foundation. Según el anuncio de la Linux Foundation, la AAIF la cofundaron Anthropic, Block y OpenAI, y sus proyectos fundacionales son tres: MCP de Anthropic (el protocolo que conecta a los agentes con sistemas externos), goose de Block y AGENTS.md de OpenAI. El sitio oficial (agents.md) afirma que más de 60.000 repositorios open source han adoptado este archivo.

La lista de herramientas compatibles lo deja aún más claro. OpenAI Codex, Google Jules, VS Code, GitHub Copilot, Cursor, JetBrains Junie, Aider, Devin, Zed, Factory, Warp, goose, opencode, Amp, RooCode, Gemini CLI, Kilo Code, Phoenix, Semgrep, Ona, Windsurf y Augment Code, entre muchas otras, lo admiten. GitHub Copilot empezó a ofrecer compatibilidad nativa con AGENTS.md en agosto de 2025. Un detalle interesante es que la compatibilidad nativa de Claude Code con AGENTS.md sigue siendo una active feature request. Claude Code continúa tratando CLAUDE.md como su archivo principal.

Aunque se lo llame estándar, cabe dudar de si realmente se está adoptando. La prueba más sólida es el dogfooding (usar uno mismo el estándar que ha creado).

• En la raíz de la rama canary de Vercel/Next.js hay un AGENTS.md. En realidad, es un enlace simbólico a CLAUDE.md, que contiene la estructura del monorepo, iteraciones de 1-2 segundos mediante pnpm --filter=next dev, guías para probar tanto Turbopack como Webpack, el script pr-status y reglas para gestionar variables de entorno y secretos. El hecho de que create-next-app haya pasado a generar juntos AGENTS.md y CLAUDE.md en los proyectos nuevos responde a la misma tendencia.
• El propio repositorio OpenAI/codex mantiene su propio AGENTS.md.

En términos estratégicos, una práctica se está consolidando como la opción habitual: usar AGENTS.md como única fuente de verdad (single source of truth) y reducir CLAUDE.md a una línea que haga referencia a AGENTS.md, más las instrucciones exclusivas de Claude Code. Así desaparece la duplicación y no se pierde nada, porque Claude Code lee ambos archivos.

SKILL.md

SKILL.md tiene una naturaleza distinta de los dos archivos anteriores. Si CLAUDE.md y AGENTS.md son instrucciones persistentes que siempre están presentes en el contexto, una Skill es una capacidad on-demand que solo se invoca cuando hace falta.

Las Skills se organizan por carpetas. Cada carpeta contiene un SKILL.md, los scripts que ejecuta la Skill y documentos Markdown adicionales. Claude solo carga esa carpeta cuando la tarea actual coincide con la description de la Skill. Esto se denomina progressive disclosure (divulgación progresiva), un concepto que Jakob Nielsen formuló en el campo de la UX en 1995: trasladar las funciones avanzadas o poco frecuentes a pantallas secundarias para que el usuario se concentre en una sola tarea cada vez, reduciendo la carga cognitiva y los errores. En el contexto de Claude Skills, designa el mecanismo de «incorporar al contexto el contenido de una Skill únicamente cuando se necesita». Como resultado, el coste de la ventana de contexto puede reducirse de forma drástica.

El frontmatter de SKILL.md contiene varios campos propios.

• description: explica en qué situaciones se necesita la Skill y actúa como trigger para que el modelo decida si debe invocarla
• allowed-tools: limita las herramientas que pueden utilizarse dentro de la Skill (por ejemplo, "Read, Glob, Grep, Bash(python:*)")
• disable-model-invocation: true: impide que el modelo la invoque; solo el usuario puede activarla mediante un comando slash. Se usa para operaciones con efectos secundarios, como deployments o commits
• user-invocable: false: no aparece en el menú slash del usuario y solo Claude puede invocarla autónomamente como conocimiento de fondo

Claude Skills se lanzó simultáneamente en Claude.ai, Claude Code, API y Agent SDK el 16 de octubre de 2025. El 18 de diciembre de 2025, Anthropic presentó la propia especificación de Skills como estándar abierto (agentskills.io). Simon Willison llegó a afirmar: «Skills are awesome, maybe a bigger deal than MCP». La razón es que su formato es mucho más sencillo que MCP y, al mismo tiempo, resuelve mediante progressive disclosure el problema del coste de la ventana de contexto.

MCP (Model Context Protocol), con el que aquí se comparaban las Skills, es un protocolo estándar que conecta al agente con sistemas externos como Slack, GitHub o una base de datos para que pueda invocarlos. Si los archivos de contexto tratan de qué contarle al agente, MCP trata de qué permitirle hacer. En qué se diferencia MCP de function calling lo he explicado aparte en MCP y function calling.

Las herramientas que reducen el coste de que un agente encuentre el código relevante (Repomix, Aider, CodeGraph, Serena) reducen costes distintos según lo a fondo que entiendan el código. Esa comparación la he recogido aparte en Cuatro niveles de inteligencia de código.

Archivos de otras herramientas

El archivo .cursorrules de Cursor está deprecated desde la versión 0.43. La recomendación oficial actual consiste en colocar varios archivos dentro del directorio .cursor/rules/; esos archivos usan la extensión .mdc. Cada archivo .mdc tiene frontmatter YAML.

• description: referencia que usa el agente para determinar la pertinencia de la regla
• globs: adjunta automáticamente la regla (auto-attach) cuando se incluye en la conversación un archivo que coincide con el patrón
• alwaysApply: si es true, se incluye siempre en todas las conversaciones (y se ignora globs)

GitHub Copilot ha evolucionado en una dirección similar. Las instrucciones globales del repositorio se colocan en .github/copilot-instructions.md; cuando se necesita scope por ruta, se crean archivos .github/instructions/*.instructions.md y se especifica un glob mediante la clave applyTo: del frontmatter. (Copilot code review ofrece compatibilidad oficial con path-scoped instructions desde septiembre de 2025).

Las demás herramientas, además de Cursor y Copilot, convergen en patrones parecidos. Podemos resumirlas así.

Resulta especialmente interesante el archivo CONVENTIONS.md de Aider. Como la documentación oficial indica que el archivo completo se incorpora al contexto en cada solicitud, recomienda explícitamente «mantenerlo por debajo de 200 líneas». (En cierto modo, Aider detectó pronto esta limitación y la comunica claramente a sus usuarios).

MEMORY.md

Al margen de los archivos anteriores, hay otro patrón que aparece cada vez con más frecuencia: MEMORY.md. No es un estándar oficial, sino una convención surgida orgánicamente en la comunidad para registrar decisiones y errores a lo largo del tiempo.

## 2026-04-10
Pages Router에서 App Router로 이전. 신규 라우트는 App Router 컨벤션 사용.
 
## 2026-04-22
Prisma 쿼리 결과에 optional chaining 쓰지 말 것 — null은 if-check로 명시적 처리.
(이전에 옵셔널 체이닝으로 null을 흘려보내 프로덕션 이슈 발생.)

Si CLAUDE.md o AGENTS.md contienen las reglas vigentes en el presente, MEMORY.md recoge la historia de por qué se crearon esas reglas. (Son complementarios, no sustitutos).

Cómo leen estos archivos los agentes

Hasta ahora hemos repasado qué archivos existen. Sin embargo, hay una pregunta que se omite con sorprendente frecuencia: ¿dónde y cómo leen exactamente estos archivos los agentes? Comprender este mecanismo permite entender mucho mejor el resultado de ETH Zurich que veremos después: que los archivos de contexto no se siguen demasiado bien.

Empecemos por un hecho esencial. CLAUDE.md no se inyecta como system prompt, sino como user message. La documentación oficial de Anthropic lo explica de la siguiente manera.

El contenido de CLAUDE.md se entrega como un mensaje del usuario después del system prompt, no como parte del propio system prompt. Claude lo lee e intenta seguirlo, pero no hay garantía de que lo cumpla estrictamente.

CLAUDE.md content is delivered as a user message after the system prompt, not as part of the system prompt itself. Claude reads it and tries to follow it, but there's no guarantee of strict compliance.

En otras palabras, no es una regla obligatoria, sino «contexto de referencia». La guía oficial recomienda utilizar mecanismos separados, como un hook PreToolUse, cuando se quiere imponer un comportamiento concreto.

El orden de carga se acumula de broad → specific. En concreto: managed policy (configuración de la organización) → configuración global del usuario (~/.claude/CLAUDE.md) → proyecto (./CLAUDE.md) → configuración local (./CLAUDE.local.md). Dentro del mismo directorio, primero se carga CLAUDE.md y después CLAUDE.local.md. Podemos aprovechar que las instrucciones más cercanas se leen al final para que las reglas más específicas tengan mayor peso gracias al recency bias de los LLM.

Aquí entra en juego la interesante sintaxis @import. Si se escribe @path/to/file en cualquier parte del contenido de CLAUDE.md, el archivo correspondiente se despliega en ese lugar y se carga junto con él. La profundidad recursiva máxima es de 4 hops, y las rutas relativas se resuelven tomando como referencia el archivo que contiene el import. Por eso, la recomendación oficial consiste en tender un puente mediante @AGENTS.md. Si dejamos CLAUDE.md prácticamente vacío y solo escribimos @AGENTS.md, Claude Code leerá AGENTS.md de forma natural. (Es la solución más limpia mientras CLAUDE.md todavía no admita AGENTS.md de manera nativa).

También conviene considerar los tokens. CLAUDE.md no tiene un límite explícito de tokens, por lo que se carga entero si existe. Sin embargo, la recomendación oficial es no superar las 200 líneas por archivo. Cuando se superan las 200 líneas, la documentación advierte: «consume more context and may reduce adherence». Es interesante que, en Claude 4.x, el mero hecho de activar tool use añade automáticamente 346 tokens al special system prompt (con tool_choice: auto). El contexto se consume casi sin que nos demos cuenta.

Cursor emplea otro método. Las reglas de .cursor/rules/*.mdc funcionan en cuatro modalidades.

• Always Apply: se incluye siempre en todos los chats; ignora globs/description
• Apply Intelligently (Agent Requested): el agente lee description, evalúa su pertinencia e incorpora la regla
• Apply to Specific Files (Auto Attached): se activa cuando entra en el contexto un archivo que coincide con el patrón glob
• Apply Manually: el usuario la invoca explícitamente mediante @rule-name

Las demás herramientas siguen otros enfoques. OpenAI Codex recorre desde la raíz del repositorio git hasta cwd, reúne todos los AGENTS.md y los inyecta justo antes del prompt del usuario. GitHub Copilot inserta .github/copilot-instructions.md con una prioridad intermedia en la ventana de contexto: «después de edit context y explicit references, pero antes de loosely related open files». Incluso con un mismo archivo AGENTS.md, el momento de carga, la prioridad y las reglas de merge difieren según la herramienta, por lo que no hay garantía de que las tres lo interpreten exactamente del mismo modo.

Queda, sin embargo, una pregunta fundamental: ¿por qué los modelos solo siguen parte de las instrucciones presentes en el contexto? Decir simplemente que «las instrucciones son largas» no basta. Detrás de este fenómeno hay una limitación estructural de los LLM.

Alucinaciones y olvido del contexto

Si alguna vez hemos visto a un agente de IA confundir el contexto de una conversación u olvidar al final algo que se le había indicado claramente al principio, hemos presenciado una forma de alucinación (Hallucination). En general, al hablar de alucinaciones pensamos primero en «inventar hechos inexistentes», pero académicamente se dividen en tres categorías. El estudio de 2023 de Yue Zhang et al. («Siren's Song in the AI Ocean») distingue entre conflicto con la entrada (generar algo distinto de lo indicado explícitamente por el usuario), conflicto con el contexto (contradecir algo generado anteriormente por el propio modelo) y conflicto factual (no coincidir con el conocimiento del mundo). Ignorar instrucciones de un archivo de contexto no corresponde al tercer tipo, sino al primero: al procesar la entrada, el modelo trata parte de la información como si no existiera.

El problema más profundo es que estas alucinaciones son imposibles de eliminar por completo. Un equipo de la National University of Singapore lo demostró matemáticamente mediante teoría del aprendizaje. Ningún LLM puede aprender todas las funciones computables; por tanto, mientras se utilice como solucionador de problemas general, inevitablemente alucinará en algún punto.

El efecto de la posición también es importante. Un equipo de Stanford demostró experimentalmente que los modelos consultan mejor la información pertinente cuando está al principio o al final de la ventana de contexto, y que el rendimiento desciende notablemente cuando queda enterrada en el medio. Esto se relaciona directamente con los archivos de contexto. CLAUDE.md queda insertado en algún punto intermedio del orden de carga y, cuanto más se alarga la conversación, más se desplazan sus instrucciones hacia «el medio» del contexto. Es la otra cara del recency bias ya mencionado: la franja intermedia del efecto primacy-recency es la más vulnerable.

Al reunir todos estos fenómenos, aparece una imagen clara. Un archivo de contexto no es más que texto insertado fuera del sistema antes del primer turno del usuario. No obliga al modelo a tomar decisiones; es simplemente otro bloque de tokens que cae en la ventana de contexto. Cuanto más largo es el archivo y más se prolonga la conversación, más se desplazan sus instrucciones hacia «el medio» y menor es la probabilidad de que se consulten. Los resultados de ETH Zurich cuantifican esta limitación estructural.

El estudio de ETH Zurich

Mucha gente habrá pensado: «Entonces, ¿lo mejor será escribir todo lo posible en estos archivos?». Sin embargo, un estudio reciente contradice frontalmente esta intuición: el trabajo de ETH Zurich que hemos venido mencionando.

El equipo de ETH Zurich publicó en febrero de 2026 el artículo «Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?». Midió cuatro agentes —Claude Code (Sonnet-4.5), Codex (GPT-5.2 / GPT-5.1 mini) y Qwen Code— usando un benchmark de 138 tareas reales de ingeniería de software en Python (AGENTBENCH) y SWE-bench Lite. Los resultados fueron sorprendentes.

• Los archivos de contexto generados automáticamente por un LLM redujeron la tasa de éxito de las tareas aproximadamente un 0,5 % en SWE-bench Lite y un 2 % en AGENTBENCH
• Incluso los archivos escritos por personas solo lograron, de media, una mejora marginal cercana al 4 %
• Añadir archivos de contexto incrementó el coste de inferencia por instancia en más de un 20 %
• En modelos más potentes (GPT-5.2), el efecto de los archivos de contexto fue aún menor (cuanto más potente es el modelo, mayor es su conocimiento paramétrico y más probable que el contexto adicional actúe como ruido)

Hubo, no obstante, una excepción: especificar herramientas no estándar. Por ejemplo, al mencionar en el contexto uv, el gestor de paquetes de Python, la frecuencia con la que el agente utilizaba uv pasó de 0,01 a 1,6 veces por instancia: un aumento aproximado de 160 veces.

La recomendación de Aider de «no superar las 200 líneas» ofrece una orientación práctica basada en que «el archivo entra siempre en el contexto», mientras que el estudio de ETH Zurich demuestra cuantitativamente que «los archivos de contexto largos reducen estadísticamente el rendimiento». A mi juicio, sus implicaciones prácticas son las siguientes.

• Los archivos de contexto enormes generados automáticamente pueden hacer más daño que bien. Si metemos a la fuerza estándares de código, arquitectura y workflows en un CLAUDE.md de 300 líneas, el agente seguirá algunas partes e ignorará el resto. Esa inconsistencia puede producir resultados peores que no tener contexto.
• Lo que sí debemos escribir es «información que no puede inferirse»: herramientas no estándar, convenciones propias del proyecto y fallos anteriores. El modelo ya conoce las buenas prácticas generales de programación.
• Conviene usar AGENTS.md como fuente única, reservar CLAUDE.md para instrucciones breves específicas de la herramienta y separar los workflows detallados en Skills.

En conclusión

Los archivos de contexto cambian de una herramienta a otra en nombre, ubicación y momento de lectura. Solo en este artículo hemos visto CLAUDE.md, AGENTS.md, SKILL.md, Cursor rules, copilot-instructions.md y MEMORY.md, y qué herramienta admite qué archivo no deja de cambiar. Memorizar una lista de archivos se queda obsoleto enseguida.

Por eso, mi objetivo aquí no era recomendar un formato de archivo concreto, sino desarrollar la capacidad de ver cómo leen los agentes estos archivos. Cuando sabemos por qué CLAUDE.md se inyecta como user message, por qué cada herramienta lee de forma distinta el mismo AGENTS.md y por qué las instrucciones se debilitan en la mitad del contexto, al aparecer un formato nuevo de archivo de contexto podemos identificar rápidamente «cuándo se carga y con cuánta fuerza actúa».

Al final, queda una intuición transmitida por el estudio de ETH Zurich: el modelo ya sabe muchas cosas. Meter de todo a la fuerza en un archivo de contexto no hace que el agente lo siga mejor. Es preferible conservar solo aquello que el modelo probablemente desconozca —convenciones propias del proyecto, herramientas no estándar y errores del pasado— y retirar lo demás. Escribir un archivo de contexto largo y escribirlo bien son dos problemas diferentes.

A quienes lean este artículo les recomiendo que, antes de ampliar CLAUDE.md a cientos de líneas, investiguen al menos una vez cuándo, dónde y con cuánta fuerza leen ese archivo las herramientas que ya utilizan. Creo que esa comprensión constituye una base sólida, cambien como cambien los formatos de archivo.

Este artículo es para desarrolladores que han visto a un agente gastar tokens repitiendo grep y lecturas de archivos en una base de código grande, y que dudan qué herramienta añadir, como Repomix, CodeGraph o Serena. Estas herramientas se dividen en cuatro niveles según lo profundamente que entienden el código (context packing, el repo map de tree-sitter, el grafo de conocimiento y LSP), y cada nivel reduce el costo de búsqueda en un lugar distinto. Para el grafo de conocimiento incluyo el benchmark de su creador; para los otros tres niveles, mediciones hechas en el propio repositorio de este blog.

Desde que vi codegraph en GitHub Trending y lo instalé yo mismo, cada vez que encuentro una herramienta nueva me pregunto con qué principio ahorra tokens. Muchas de las herramientas de este artículo también las conocí por primera vez en GitHub Trending, que suelo revisar por semana, filtrando por TypeScript y Python.

Herramientas de inteligencia de código

Antes de cambiar código, un agente primero busca dónde está el código relevante. Es un bucle: busca con grep, lee archivos, filtra y vuelve a hacer grep. En el benchmark de CodeGraph que veremos más adelante, el lado que respondía sin la herramienta usó hasta 43 tool calls para una sola pregunta. Las herramientas de inteligencia de código son intentos de reducir este costo de búsqueda.

Pero "costo" no designa una sola cosa. Los tokens que procesó el modelo, el número de tool calls y los tokens que siguen en la context window cuando termina el trabajo se mueven por separado. En cada nivel, este artículo mira cuál de los tres reduce.

Divido estos intentos en los cuatro niveles (tiers) de abajo, según lo profundamente que cada herramienta entiende el código. No hay una clasificación establecida en la industria; la agrupación es mía. Todos los valores medidos en este artículo se obtuvieron el 2026-10-08 en el commit 36e5cfa de este repositorio, y los tokens se contaron con o200k_base de tiktoken. Los valores difieren de los del tokenizador de Claude, así que sirven para comparar, no como cifras absolutas.

Empaquetado de contexto

La solución más simple parte de la idea: "meterlo todo en una sola context window". No construye grafos ni hace indexación. Simplemente serializa todo el repositorio en un bloque de texto y se lo entrega entero al modelo.

La herramienta representativa es Repomix. Su formato de salida por defecto es XML, y su README enlaza la documentación de Anthropic sobre etiquetas XML. Tiene CLI, versión web, extensión de navegador y servidor MCP.

La ventaja de GitIngest es que no requiere instalación. Si cambias github.com por gitingest.com en una URL de GitHub, todo el repositorio se convierte en una sola página de texto. code2prompt (creado por Mufeed VH), una CLI en Rust, permite cambiar el formato de salida con plantillas.

rtk (rtk-ai/rtk) va en una dirección algo distinta. Mientras las herramientas anteriores empaquetan todo el repositorio de una vez, rtk comprime la salida de los comandos de CLI que ejecuta el agente. Es un único binario hecho en Rust que se registra en los hooks de varios agentes, como Claude Code, Cursor, Copilot, Gemini CLI y Codex, de modo que cuando el agente llama a git status, ejecuta rtk git status en su lugar. Aplica filtering, grouping, truncation y deduplication a más de 100 comandos. El hook de rtk solo toma como objetivo las tool calls de Bash. Read, Grep y Glob de Claude Code pasan de largo.

La magnitud de la reducción hay que leerla con cuidado. El README de rtk dice que reduce la salida de Bash hasta en un 90%, y añade enseguida que eso no significa reducir la factura un 90%. Desde el lado del modelo, la salida de un comando es parte de los tokens de entrada, y los tokens de entrada son parte de la factura, así que la reducción se diluye en cada paso. La cifra que destaca el sitio oficial es un 56% de media, en los comandos que rtk reescribe. Si las herramientas anteriores reducen el texto que entra, rtk reduce el texto que vuelve como resultado de las tool calls.

El límite de este nivel es que los repositorios grandes chocan con el tope de tokens. Empaquetar solo los 109 archivos del src/ de este blog ya da 94.596 tokens. Eso todavía cabe en la ventana, pero un repositorio con miles de archivos llegaría al límite enseguida. Repomix responde a esto con --compress. Según el README, usa Tree-sitter para conservar las firmas de funciones y clases y descartar los cuerpos de implementación.

# repomix 1.18.1, 이 리포 커밋 36e5cfa, 2026-10-08
npx -y repomix@1.18.1 src -o out.xml              # Total Tokens: 94,596 tokens
npx -y repomix@1.18.1 src --compress -o out.xml   # Total Tokens: 30,320 tokens

Se redujo un 68%. Los comentarios se quedan, así que visit-counter.ts, con JSDoc largo, solo pasó de 1.642 a unos 1.220 tokens, un 26%. La versión comprimida conserva las sentencias import y las firmas, pero desaparecen las llamadas dentro de los cuerpos de las funciones. En el texto se ve qué archivo importa qué, pero no se puede preguntar quién llama a quién. Por eso la frontera entre este nivel y el siguiente está menos en si la herramienta ve la sintaxis que en si se le pueden preguntar relaciones.

Mapa del repositorio con tree-sitter

El siguiente nivel usa tree-sitter para analizar la estructura del código, pero sin levantar un servidor de índices aparte.

Lo que construye tree-sitter, la herramienta en la que se apoya este nivel, es un CST (Concrete Syntax Tree), un árbol que representa la estructura del código fuente. La documentación oficial de tree-sitter también dice que construye un concrete syntax tree. Es un árbol que conserva como nodos incluso los paréntesis y la puntuación, y es el árbol con el que trabajan las herramientas de abajo.

tree-sitter es un generador de parsers de código abierto y una biblioteca de parsing incremental (incremental). La code navigation de GitHub usa tree-sitter. Como solo vuelve a parsear la parte editada, cambiar una línea en el editor no vuelve a parsear todo el archivo; solo corrige la parte del árbol que cambió. Esa ventaja es de los editores, donde las ediciones no paran. Aider, más abajo, mantiene una caché basada en la hora de modificación de los archivos para no volver a parsear los que no cambiaron.

Aider, una herramienta de programación en pareja con IA que se usa en la terminal, es el ejemplo representativo de este enfoque. Aider usa tree-sitter para extraer de cada archivo las definiciones y referencias de funciones, clases y métodos. Luego construye un grafo con los archivos como nodos. Cuando el archivo A referencia un identificador definido en el archivo B, se crea una arista de A a B.

Para elegir los archivos importantes de este grafo, Aider usa PageRank. PageRank es un algoritmo que da más puntuación a un nodo cuantos más enlaces recibe y cuanto más pesan. Aider usa una variante llamada personalized PageRank, que inclina la puntuación hacia los nodos elegidos. Después mete en el presupuesto de tokens las definiciones y firmas de los archivos mejor clasificados.

Qué entra en el presupuesto cambia con la conversación actual. En repomap.py de Aider, el peso de una arista es la raíz cuadrada del número de referencias multiplicada por un factor. Los identificadores mencionados en la conversación reciben x10, y los identificadores en camelCase, snake_case o kebab-case de 8 o más caracteres también x10. Los que empiezan por _ y los definidos en más de 5 archivos reciben x0,1 cada uno, y las aristas que salen de los archivos añadidos ahora al chat reciben x50. Los archivos del chat, los mencionados en la conversación y aquellos cuya ruta o nombre de archivo coincide con un identificador de la conversación también reciben puntuación de personalization en PageRank.

El presupuesto tampoco es fijo. La documentación de Aider da 1k como valor por defecto de --map-tokens, pero el código recorta un octavo del límite de entrada del modelo a un valor entre 1.024 y 4.096. Y cuando no hay archivos en el chat, lo amplía hasta --map-multiplier-no-files (por defecto 2) veces. Lo comprobé con el src/ de este repositorio. La versión 0.86.1 que ejecuté y el commit enlazado arriba tienen el mismo código de ranking. Los maps impresos se contaron con o200k_base, incluidas las tres líneas de texto de guía que añade Aider.

# aider-chat 0.86.1, 리포 루트에서 시작한다, 2026-10-08
mkdir /tmp/aidermap && cp -R src /tmp/aidermap/ && cd /tmp/aidermap && git init -q && git add -A && git commit -qm init
# 키는 더미 값이다. --show-repo-map 은 map 만 출력하고 LLM 을 부르지 않는다
export OPENAI_API_KEY=dummy
aider_map() { uvx --python 3.12 --from aider-chat==0.86.1 aider --no-check-update --analytics-disable --no-gitignore --model gpt-4o "$@"; }
aider_map --show-repo-map                                              # Repo-map: using 4096 tokens
aider_map --map-tokens 1024 --show-repo-map                            # Repo-map: using 1024 tokens
aider_map --map-tokens 1024 --show-repo-map src/lib/filter-posts.ts    # 이 파일을 채팅에 올린 상태

El límite de entrada de gpt-4o es de 128k, así que un octavo se recortó a 4.096, y con el chat vacío el map salió dentro del doble de eso. Al añadir un archivo al chat, el map se encogió hasta caber en el presupuesto; de los 27 archivos anteriores solo quedaron 10, y entraron como nuevos PostList.tsx y SearchModal.tsx. Un repo map no es un resumen fijo del repositorio, sino un extracto ajustado a la conversación de ese momento.

Hay una herramienta más que vale la pena mencionar en este nivel: ast-grep (ast-grep/ast-grep). Es una CLI de búsqueda estructural y rewrite basada en tree-sitter, y hace coincidir nodos del árbol sintáctico en lugar de texto. Por ejemplo, el patrón console.log($A) atrapa todas las llamadas a console.log con un solo argumento, sin importar cómo sean los saltos de línea o los espacios. Lo que atrapa es la misma estructura sintáctica. No sabe el tipo de $A ni de dónde viene el nombre console. También existe un servidor ast-grep-mcp, con el que se puede hacer que un agente use búsqueda estructural en lugar de grep de texto.

Knowledge Graph

El tercer nivel va un paso más allá. Parsea de antemano toda la base de código, construye un grafo de conocimiento y lo guarda en disco; luego el agente lanza consultas a ese grafo guardado. El ejemplo del que más se habla es una herramienta llamada CodeGraph.

La estructura que describe el README de CodeGraph es sencilla. Parsea el código con tree-sitter para extraer símbolos, aristas e información de archivos, y los guarda en una base de datos SQLite local. La búsqueda por nombre pasa por el índice FTS5 de SQLite. El agente consulta este grafo a través de MCP. En los pasos que describe el README no aparece ningún LLM. Por eso entiendo que esta extracción es determinista (deterministic), es decir, que el mismo código siempre da el mismo resultado.

Si un LLM resume el código para construir el grafo, los resultados pueden variar incluso con el mismo código, y pueden colarse alucinaciones. En cambio, si se parsea directamente el árbol sintáctico, las relaciones entre símbolos se extraen solo según las reglas de la gramática del lenguaje, sin margen para ese tipo de interpretación.

FTS5 (SQLite Full-Text Search 5), que aparece aquí, es una extensión de búsqueda de texto completo que SQLite ofrece en forma de tabla virtual. Según la documentación de SQLite, está incluida en la amalgamation desde la 3.9.0 (2015-10-14); se crea una tabla con CREATE VIRTUAL TABLE ... USING fts5(...) y se consulta con el operador MATCH. Permite tener un índice de texto completo en un solo archivo SQLite sin levantar un motor de búsqueda aparte como Elasticsearch.

Pero ser determinista no es lo mismo que ser completo. El mismo README registra el reconocimiento de rutas de los frameworks que dependen de convenciones y reflexión entre un 74,1% para Django y un 83,9% para ASP.NET, y lo llama el límite del análisis estático (honest static-analysis ceiling). El mismo código da el mismo resultado, pero a ese resultado le pueden faltar aristas.

El benchmark lo midió CodeGraph mismo. La nueva medición del 2026-08-05 en el mismo README ejecutó Claude Opus 4.8 en modo headless y planteó una pregunta de arquitectura a cada uno de 7 repositorios de código abierto. El lado con CodeGraph MCP activado redujo el costo medio un 44%, los tokens procesados un 62% y las tool calls un 88%. Esta nueva medición impidió en ambos lados llamar a la CLI codegraph desde Bash. En un entorno de medición sin ese bloqueo, el lado sin la herramienta encontró y usó la CLI en 26 de 28 ejecuciones, y el README aclara que las cifras publicadas antes se obtuvieron sin este bloqueo.

El tamaño del ahorro no siguió al tamaño del repositorio. En las preguntas en las que el lado sin la herramienta usó de 28 a 43 tool calls, el costo bajó entre un 57 y un 78%, y en Gin, que terminó en 7, quedó casi igual. VS Code, con unos 11k archivos, dio un 71%, y Excalidraw, con unos 640, un 78%. El README lo atribuye a la cantidad de búsqueda que exigía cada pregunta. Como hay una sola pregunta por repositorio, solo leo de ahí la dirección.

El README también registra una cifra en sentido contrario. Los tokens procesados bajan, pero al final de una sesión de varios turnos, los resultados de retrieval que siguen en la context window son alrededor de un 80% mayores del lado de CodeGraph en el conjunto de los 7 repositorios. La diferencia varía según el repositorio; solo en VS Code son 67k frente a 18k tokens, unas 3,7 veces. Devuelve el texto fuente denso de una vez, y ese texto se queda en la ventana. CodeGraph redujo las tool calls y los tokens procesados a cambio de dejar más en la ventana.

Cursor tomó otro camino y luego cambió de rumbo. La indexación que describía la entrada del blog de Cursor de enero de 2026 no era un grafo sintáctico sino búsqueda semántica basada en embeddings vectoriales. Dividía los archivos en chunks localmente, se sincronizaba con el servidor mediante hashes de Merkle tree y convertía los chunks en embeddings para la búsqueda semántica. En julio de 2026, un Community Support Engineer de Cursor respondió en el foro: "Semantic/embeddings indexing is being turned down in favor of grep-based retrieval". En el mismo hilo, otro miembro del equipo escribió que, a medida que los modelos aprendieron a usar bien grep, la antigua ruta de búsqueda semántica dejó de ayudar de forma significativa. Hoy la documentación de Cursor dice que Instant Grep construye y consulta su índice en tu máquina y no guarda embeddings de tu base de código para la búsqueda.

LSP

El último nivel depende directamente de un servidor de lenguaje. Si tree-sitter sabe "que un símbolo existe", LSP sabe "qué es ese símbolo".

LSP (Language Server Protocol) es un protocolo abierto basado en JSON-RPC que estandariza la comunicación entre editores y herramientas de análisis de lenguaje (autocompletado, ir a la definición, buscar referencias, refactorización, etc.). En 2016, Microsoft, Red Hat y Codenvy anunciaron su colaboración. La idea central es "no reimplementar un analizador de lenguaje para cada editor; tener un servidor por lenguaje y que todos los editores le pregunten". rust-analyzer y pyright de Python son servidores LSP, mientras que TypeScript usa typescript-language-server, que envuelve en LSP a tsserver, que habla su propio protocolo.

Serena (oraios/serena) es un servidor MCP de este nivel. A 2026-10-08 tiene 30.093 stars, y el repositorio se creó en marzo de 2025. La idea central de Serena cabe en una línea: mostrarle al agente el código como símbolos. Sus herramientas principales incluyen find_symbol, find_referencing_symbols y get_symbols_overview. Se puede elegir uno de dos backends. El predeterminado es un servidor de lenguaje que implementa LSP (gratuito/de código abierto); la otra opción es un plugin de pago que usa el análisis de código del IDE de JetBrains (con prueba gratuita).

Medir en este repositorio muestra de dónde sale la diferencia. Busqué los usos de isHiddenPost (src/lib/filter-posts.ts:12), que filtra las entradas privadas, de dos formas. El lado de texto es grep.

# 커밋 36e5cfa, 2026-10-08. 이 글도 같은 이름을 담고 있어 content/ 는 뺐다
git grep -n isHiddenPost -- ':!content'   # 16줄, 파일 9개
git grep -n -C1 isHiddenPost -- ':!content'   # 같은 16곳을 앞뒤 1줄과 함께

En el lado LSP se llamó a find_referencing_symbols de Serena. La búsqueda de referencias de LSP pregunta por posición (archivo, línea y columna), no por nombre, así que esta herramienta también recibe a la vez name_path, el nombre del símbolo, y relative_path, el archivo donde está la definición. En lugar de levantar Serena como servidor MCP, la herramienta se llamó directamente desde Python sobre el mismo commit.

# serena 3b99f8b, 커밋 36e5cfa, 2026-10-08. 리포 루트에서 실행한다
# uvx --python 3.12 --from git+https://github.com/oraios/serena@3b99f8b024dafd58c962ea6e74f37c8a730ef532 python refs.py
from serena.agent import SerenaAgent
from serena.config.serena_config import SerenaConfig
from serena.tools.symbol_tools import FindReferencingSymbolsTool
agent = SerenaAgent(project=".", serena_config=SerenaConfig().with_headless_mode_overrides())
agent.execute_task(lambda: None)  # 언어 서버가 뜰 때까지 기다린다
tool = agent.get_tool(FindReferencingSymbolsTool)
print(agent.execute_task(lambda: tool.apply(name_path="isHiddenPost", relative_path="src/lib/filter-posts.ts")))

La salida es una sola línea de JSON. Este es solo el primer elemento. Los números de línea empiezan en 0.

{"src/lib/filter-posts.ts": {"Function": [{"name_path": "filterPublishedPosts", "body_location": {"start_line": 22, "end_line": 24}, "content_around_reference": "...  22:export function filterPublishedPosts(posts: Post[]): Post[] {\n  >  23:  return posts.filter(post => !isHiddenPost(post))\n...  24:}"}]}, ...

Serena devolvió 10 referencias. Deja fuera la definición en filter-posts.ts:12, y para las líneas de import de tres archivos devuelve el propio archivo como símbolo (File). Las 11 ubicaciones de código que encontró grep son estas 10 más la línea de la definición. Este nombre es único en el repositorio, así que grep no omitió ni añadió ninguna ubicación de código. Las 5 ubicaciones de más que encontró grep eran frases de documentos que explican esta función: el CLAUDE.md de la raíz, los archivos de .claude/commands/ audit.md y write-post.md, y, en docs/research/snapshot-20260816/, las copias que quedan de CLAUDE.md y write-post.md.

Serena devuelve cada referencia con una línea antes y otra después. Por eso grep se ejecutó de dos formas, git grep -n, que solo devuelve números de línea, y git grep -n -C1, que también devuelve una línea antes y otra después, y las tres salidas se contaron completas con o200k_base.

Frente a un grep que devuelve una línea antes y otra después, Serena usa 683 tokens menos. La diferencia sale de no devolver las 5 ubicaciones en documentos. Pero Serena añade a cada referencia el nombre del símbolo y la información de ubicación en JSON, así que, mirando solo el lado del código, usa de hecho 159 tokens más. Y los 892 tokens de Serena superan los 703 de git grep -n, que solo devuelve números de línea. Lo que ahorra el nivel LSP en este repositorio no es el resultado de la búsqueda, sino el paso siguiente: leer líneas o archivos cercanos tras ver el resultado de grep.

En ese paso siguiente, si el agente leyera enteros los 9 archivos que encontró grep, leería 47.034 tokens: 3.716 de los 4 archivos de código y 43.318 de los 5 documentos. Eso es una cota superior. En una sesión real, CLAUDE.md probablemente ya esté en el context y no se vuelva a leer. Con un nombre común como isLocale, los resultados podrían diferir incluso en las ubicaciones de código.

Conclusión

En resumen, los cuatro niveles se separan según lo profundamente que entienden el código, y reducen costos distintos. Context packing entrega el código como texto, e incluso con --compress conserva solo la sintaxis y reduce los tokens que entran. El repo map de tree-sitter sabe que un símbolo existe, pone un tope de presupuesto a los tokens que entran, y la conversación de ese momento decide con qué se llena. El grafo de conocimiento guarda las relaciones de antemano y reduce las tool calls y los tokens procesados, pero según la medición del propio proveedor, lo que queda en la ventana incluso aumentó. LSP sabe qué es un símbolo; en este repositorio no devolvió el mismo nombre en los documentos, pero a cambio añadió metadatos a cada resultado. Lo que ahorra no está en el resultado de la búsqueda, sino en la lectura que viene después.

Por eso, al elegir una herramienta, primero miro qué costo es el problema ahora, más que la profundidad del nivel. Si la ventana es pequeña y las sesiones largas, miro lo que queda; si los viajes de ida y vuelta son lentos, el número de tool calls; si en el repositorio los documentos y el código comparten nombres, cuántos archivos acabo leyendo tras un resultado de grep. Leo que Cursor quitara la búsqueda semántica por embeddings y pasara a un índice de texto local (Instant Grep) como una señal de que un índice caro no siempre supera la propia capacidad de búsqueda del modelo.

Si estas herramientas reducen el costo de que un agente encuentre código, cuántas reglas del proyecto que el agente debe conocer desde el principio escribir, y en qué archivo, es otro problema. Lo trato en Archivos de contexto.

Este artículo está pensado para quienes usan servidores MCP con Claude Code o Cursor, pero les cuesta explicar en qué punto se separa MCP del function calling de las API de LLM. La respuesta corta es que MCP no sustituye a function calling. La aplicación host convierte la lista de herramientas que recibe de un servidor MCP en el parámetro tools de function calling y devuelve al servidor MCP la llamada que elige el modelo. Al terminar, sabrás de qué parte del protocolo surge cada una de las cuatro diferencias que MCP añade encima, qué diferencias sobreviven a la revisión 2026-07-28 y qué superficie de ataque abre esa estructura.

Trabajo como desarrollador frontend y uso Claude a diario, pero cada vez que añadía un servidor MCP, nunca tenía del todo claro cómo entraban esas herramientas en el campo de visión del modelo.

MCP (Model Context Protocol)

MCP (Model Context Protocol) resuelve la cuestión de «qué debe poder hacer el agente».

Veámoslo con más detalle. Para que un agente de IA envíe un mensaje a Slack, debe poder llamar a la Slack API. Para crear una issue de GitHub, debe poder llamar a la GitHub API. Para consultar Postgres, debe gestionar una conexión con la base de datos. MCP agrupa todas estas integraciones con sistemas externos bajo un protocolo estándar. (Significa que clientes y servidores se conectan siguiendo la misma especificación).

MCP es un estándar abierto que Anthropic presentó por primera vez el 25 de noviembre de 2024. El 9 de diciembre de 2025, Anthropic donó MCP a la Agentic AI Foundation (AAIF) de la Linux Foundation. La AAIF la cofundaron Anthropic, Block y OpenAI.

MCP es un protocolo construido sobre JSON-RPC. JSON-RPC 2.0 es un protocolo RPC (Remote Procedure Call) stateless y ligero que utiliza JSON como wire format. Es independiente de la capa de transporte, por lo que puede funcionar sobre HTTP, TCP o la entrada y salida estándar. Este artículo toma como referencia la revisión 2025-11-25, en la que MCP es un protocolo stateful que establece una sesión por cada conexión. Qué cambió en la revisión posterior lo veremos después de recorrer el flujo de llamadas.

Seis primitivas

La visión general de la especificación 2025-11-25 enumera tres funciones que ofrecen los servidores y tres que ofrecen los clientes. Este artículo llama primitivas a estas seis. Aquí, una primitiva no tiene nada que ver con los tipos primitivos de JavaScript (como string o number); se refiere a un tipo básico de interacción definido por el protocolo.

Primitivas del lado del servidor

• Tool (model-controlled): una acción cuya invocación decide el propio modelo. Estas acciones pueden tener efectos secundarios (side effects)
• Resource (application-controlled): datos identificados por una URI. La especificación solo tiene resources/read para leer su contenido y ningún método para escribir. Cómo se incorporan esos recursos al contexto lo decide la aplicación host
• Prompt (user-controlled): una plantilla reutilizable que el usuario activa explícitamente, por ejemplo con un comando de barra

Primitivas del lado del cliente

• Sampling: un mecanismo que permite al servidor pedir en sentido inverso una completion al LLM del cliente, lo que vuelve bidireccional la relación entre cliente y servidor. Sirve para que un servidor que necesita generar texto mientras ejecuta una herramienta use el modelo del cliente sin tener su propia clave de API. En la revisión 2026-07-28 quedó deprecated, es decir, con su eliminación prevista
• Roots: información sobre los límites del espacio de trabajo con la que el cliente le dice al servidor «hasta aquí llega el área en la que puedes trabajar»
• Elicitation: una función que permite al servidor pedir al usuario datos adicionales de forma estructurada mientras ejecuta una herramienta

Esta distinción importa porque quién decide invocar o proporcionar algo es distinto. Un Tool se ejecuta por decisión del modelo, así que una invocación errónea implica riesgo, mientras que un Prompt lo elige el usuario de forma explícita. Un Resource lo elige la aplicación por defecto, pero la especificación también permite implementaciones que incluyen recursos automáticamente, según heurísticas o la selección del modelo. Las tres primitivas del lado del cliente van en sentido contrario: el servidor pide y el cliente decide si responde.

Dos mecanismos de transporte

Hay dos mecanismos de transporte estándar, y la especificación también permite otros transportes personalizados (MAY). El primero es stdio, que ejecuta el servidor MCP como un subproceso local y se comunica mediante la entrada y salida estándar. Es adecuado para herramientas que funcionan localmente, como el sistema de archivos o git. El segundo es Streamable HTTP, que añade streaming SSE (Server-Sent Events) sobre HTTP POST y GET para lograr una comunicación casi bidireccional. SSE es una forma de que el servidor envíe datos al cliente en una sola dirección a través de una conexión HTTP. Es adecuado para escenarios que ocurren a través de la red, como servidores remotos, autenticación OAuth, conexiones de varios clientes y despliegues en la nube.

Flujo mediante el que un LLM invoca herramientas MCP

Ya que hemos visto las primitivas y los transportes, sigamos el flujo de cómo un LLM descubre e invoca realmente una herramienta MCP.

En la revisión 2025-11-25, al iniciarse una conexión se produce el siguiente handshake. A fecha de 2026-10-08, el SDK de TypeScript 1.32.1 y la versión 2.3.1 de la línea v2 también siguen este orden con su configuración por defecto.

• Cliente → servidor: solicitud initialize (envía la versión de protocolo admitida y las capabilities del cliente)
• Servidor → cliente: respuesta initialize (capabilities del servidor y, opcionalmente, el campo instructions)
• Cliente → servidor: notificación notifications/initialized
• Cliente → servidor: solicitud tools/list → recibe la lista de herramientas disponibles
• (Después) El LLM decide invocar una herramienta → el cliente envía tools/call → recibe el resultado

En la respuesta initialize, el campo instructions es donde el servidor envía un texto sobre cómo deben usarse sus herramientas. La línea instructions de la salida de la demo, más abajo, muestra ese valor.

Entonces, ¿cómo entra la propia definición de la herramienta en el campo de visión del LLM? La definición de una herramienta MCP tiene esta forma de JSON Schema.

{
  "name": "get_weather",
  "description": "Get current weather information for a location",
  "inputSchema": {
    "type": "object",
    "properties": { "location": { "type": "string" } },
    "required": ["location"]
  }
}

El host convierte la lista recibida con tools/list en el parámetro tools de la Anthropic Messages API o en el parámetro tools de OpenAI function calling, y la incluye en la llamada a la API del LLM. En el caso de Anthropic, cuando llega el parámetro de herramientas, se añade automáticamente un special system prompt para que el modelo entienda cómo invocarlas. Su longitud depende del modelo. En la tabla de la documentación que consulté el 2026-10-08, los modelos actuales añadían entre 286 y 675 tokens con tool_choice: auto.

Cuando el LLM decide que debe invocar una herramienta, su respuesta incluye un bloque tool_use ({"type": "tool_use", "name": ..., "input": ...}) y el stop_reason de la respuesta termina en tool_use. El host lo recibe, envía tools/call al servidor MCP real, recibe el resultado, lo coloca en un bloque tool_result del siguiente mensaje user y lo envía de nuevo al LLM. Este bucle se repite hasta que stop_reason cambia de tool_use a otro valor, como end_turn o max_tokens. Lo que solemos llamar «el agente trabajando» se parece mucho a una sucesión de estos bucles de llamada, resultado y nueva llamada.

Si lo dibujamos, no hay ninguna línea entre el modelo y el servidor MCP. El modelo solo ve las definiciones que recibió mediante tools, y el servidor MCP recibe las solicitudes del host, no del modelo. Lo que une los dos protocolos es el host del centro.

Ejecuté esta conversión para ver lo corta que es en realidad. Se ejecutó el 2026-10-08 con Node v24.16.0, @modelcontextprotocol/sdk 1.32.1 y zod 4.6.5. En lugar de stdio, el transporte es InMemoryTransport, que conecta servidor y cliente dentro de un mismo proceso, y no se llamó a ningún LLM. El bloque tool_use se construyó a mano con la forma que muestra la documentación de Anthropic.

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
import { z } from "zod";
 
// MCP 서버: 도구 하나와 instructions 를 둔다
const server = new McpServer(
  { name: "weather", version: "1.0.0" },
  { instructions: "Use get_weather for current conditions only." }
);
server.registerTool(
  "get_weather",
  { description: "Get current weather information for a location", inputSchema: { location: z.string() } },
  async ({ location }) => ({ content: [{ type: "text", text: `${location}: 15C, partly cloudy` }] })
);
 
// 호스트: 같은 프로세스 안에서 서버와 잇고, 클라이언트가 보내는 메서드 이름을 찍는다
const [clientT, serverT] = InMemoryTransport.createLinkedPair();
const send = clientT.send.bind(clientT);
clientT.send = (m) => { console.log("C->S", m.method, m.params?.protocolVersion ?? ""); return send(m); };
await server.connect(serverT);
const client = new Client({ name: "demo-host", version: "1.0.0" });
await client.connect(clientT);
console.log("instructions:", client.getInstructions());
 
// 1. tools/list 결과를 LLM API 의 tools 파라미터 모양으로 바꾼다
const { tools } = await client.listTools();
const anthropicTools = tools.map((t) => ({ name: t.name, description: t.description, input_schema: t.inputSchema }));
const openaiTools = tools.map((t) => ({ type: "function", name: t.name, description: t.description, parameters: t.inputSchema }));
console.log("anthropic:", JSON.stringify(anthropicTools[0]));
console.log("openai:", JSON.stringify(openaiTools[0]));
 
// 2. 모델이 이런 tool_use 블록을 돌려줬다고 가정한다. input 이 그대로 tools/call 의 arguments 가 된다
const toolUse = { type: "tool_use", id: "toolu_demo", name: "get_weather", input: { location: "Seoul" } };
const result = await client.callTool({ name: toolUse.name, arguments: toolUse.input });
console.log("tool_result:", JSON.stringify({ type: "tool_result", tool_use_id: toolUse.id, content: result.content }));
await client.close();

La salida de node post-demo.mjs es esta.

C->S initialize 2025-11-25
C->S notifications/initialized 
instructions: Use get_weather for current conditions only.
C->S tools/list 
anthropic: {"name":"get_weather","description":"Get current weather information for a location","input_schema":{"type":"object","properties":{"location":{"type":"string"}},"required":["location"],"$schema":"http://json-schema.org/draft-07/schema#"}}
openai: {"type":"function","name":"get_weather","description":"Get current weather information for a location","parameters":{"type":"object","properties":{"location":{"type":"string"}},"required":["location"],"$schema":"http://json-schema.org/draft-07/schema#"}}
C->S tools/call 
tool_result: {"type":"tool_result","tool_use_id":"toolu_demo","content":[{"type":"text","text":"Seoul: 15C, partly cloudy"}]}

La conversión de la definición de la herramienta no es más que renombrar campos. El inputSchema de MCP pasa a ser input_schema en Anthropic y parameters en OpenAI. La salida también muestra que el SDK añade $schema al esquema. La dirección contraria es igual de corta. El tool_use.input de Anthropic es un objeto, así que entra tal cual en tools/call como sus arguments. En el lado del resultado, los bloques de texto tienen la misma forma y pasan tal cual, pero los resultados de imagen o de error tienen otra forma, así que el helper de MCP del SDK de Anthropic los convierte por separado. La forma de OpenAI de arriba es el formato de la Responses API. Los arguments de una llamada que devuelve OpenAI son una cadena JSON, así que hay que pasarlos una vez por JSON.parse antes de entregarlos. El código de arriba solo construye un bloque tool_use con la forma de Anthropic, así que este paso de parse no aparece en la salida.

Cuatro cosas que añade MCP

Entonces, ¿qué añade MCP a function calling? Según la revisión 2025-11-25, son cuatro cosas.

• Descubrimiento dinámico: la lista de herramientas no se conoce en tiempo de compilación, sino que se obtiene en tiempo de ejecución con tools/list. El servidor puede avisar con notifications/tools/list_changed de que la lista cambió durante la conexión
• Stateful session: la conexión se establece con initialize y las solicitudes se intercambian dentro de ella. No hay un mensaje JSON-RPC de cierre específico; la sesión termina cerrando el transporte
• Primitivas además de Tool: Resource, Prompt, Sampling, Roots y Elicitation se exponen mediante capability negotiation. La capability negotiation es el paso de initialize en el que cada lado anuncia las funciones que admite
• Bidireccionalidad: el servidor puede pedir en sentido inverso una completion al LLM del cliente mediante Sampling (deprecated en la revisión 2026-07-28)

Después de la revisión 2026-07-28

A fecha de 2026-10-08, la revisión que el sitio oficial abre como latest es la revisión 2026-07-28, y en ella cambió la mitad de esta lista. Primero, desaparecieron el handshake formado por initialize y notifications/initialized y las sesiones a nivel de protocolo. En su lugar, cada solicitud lleva en _meta la versión del protocolo y las capabilities del cliente. Ese campo es un espacio que MCP reserva para adjuntar metadatos aparte de los parámetros propios del mensaje. Los servidores MUST implementar server/discover. Es una RPC que devuelve las versiones del protocolo que admite el servidor, sus capabilities y su información, y el cliente puede llamarla antes de cualquier otra solicitud para comprobar de antemano las versiones y capabilities admitidas.

Las solicitudes que antes enviaba primero el servidor se sustituyeron por un patrón llamado Multi Round-Trip Requests (MRTR). En lugar de enviar una solicitud aparte, el servidor devuelve un resultado intermedio que indica que necesita más datos (input_required), y el cliente completa esos datos y vuelve a enviar la solicitud original.

Sampling y Roots quedaron deprecated junto con Logging. Siguen en la especificación y funcionan, pero las implementaciones nuevas no deberían adoptarlos, y la especificación recomienda integrarse directamente con las API de los proveedores de LLM en lugar de usar Sampling.

Aun así, el comportamiento por defecto de los SDK sigue siendo el antiguo. El SDK de TypeScript 1.32.1 tiene 2025-11-25 como constante de versión más reciente y no conoce la revisión 2026-07-28, y la 2.3.1 admite esta revisión, pero su negociación de versión por defecto es legacy. La primera línea de la salida de arriba, initialize 2025-11-25, es el resultado.

Lo que queda de las cuatro, entonces, es el descubrimiento dinámico y las primitivas además de Tool (Resource, Prompt, Elicitation). El descubrimiento dinámico también cambió un poco de forma: las notificaciones de cambio de lista solo llegan a los clientes que se suscriben (opt-in) al stream subscriptions/listen. Al final, el punto en que MCP se separa de function calling está menos en las sesiones o la bidireccionalidad y más en un contrato para intercambiar la lista de herramientas y el contexto en tiempo de ejecución.

Cuando la API es el cliente MCP

El MCP connector (beta) de Anthropic muestra cuánto de este contrato llega al modelo. Es una función con la que la Messages API se conecta directamente a un servidor MCP remoto, y la sección Limitations de su documentación dice que, de las funciones de la especificación MCP, "only tool calls are currently supported", y que "Local STDIO servers cannot be connected directly". La misma documentación indica que, si necesitas servidores locales, prompts o resources de MCP, gestiones tú la conexión con un SDK de MCP y uses los helpers de conversión del SDK de Anthropic.

Es decir, cuando MCP se consume en la capa de function calling, solo queda Tool. Resource y Prompt solo tienen sentido si hay un host que los lleve a la pantalla o al contexto. La guía de function calling de OpenAI también presenta una forma de usar la funcionalidad de un servidor MCP como built-in tool. La guía MCP servers de OpenAI solo explica cómo listar y llamar herramientas, y no dice si admite Resource o Prompt.

La superficie de ataque del descubrimiento dinámico

Las descripciones de las herramientas y los resultados de sus invocaciones llegan, a través del host, al contexto del modelo. Así que, escriba lo que escriba ahí el servidor, el modelo lo lee. Los dos ataques representativos nacen de ahí.

• Tool Poisoning Attack (TPA): un ataque al que Invariant Labs dio nombre y del que publicó una PoC en abril de 2025. Si se ocultan instrucciones maliciosas en la descripción (description) de una herramienta de un servidor MCP, el modelo lee ese texto, que el usuario no ve, y puede seguirlo sin que el usuario lo sepa.

• Rug Pull: un ataque, descrito por Invariant Labs en la misma publicación, en el que el servidor cambia la definición de una herramienta después de que el usuario la aprobó. Como en el ejemplo de Elena Cross citado por Simon Willison, apruebas el día 1 una herramienta de aspecto seguro y, para el día 7, esa herramienta ha cambiado para enviar tus claves de API a un atacante; ocurre porque las definiciones de herramientas se obtienen del servidor en tiempo de ejecución y no en el momento de la instalación. La especificación de tools recomienda (SHOULD) una UI que muestre qué herramientas se exponen al modelo, pero no exige volver a aprobar una definición modificada, así que esa nueva aprobación queda en manos del host.

Conclusión

En resumen, MCP no sustituye a function calling; es un estándar que se apoya sobre él. El modelo sigue invocando herramientas mediante el parámetro tools y el bucle de tool_use, y el host traduce entre los dos protocolos. En la revisión 2025-11-25, lo que añadía MCP era el descubrimiento dinámico, una stateful session, primitivas además de Tool y llamadas que van del servidor al cliente. Al desaparecer las sesiones y quedar Sampling deprecated en la revisión 2026-07-28, lo que queda es un contrato para intercambiar la lista de herramientas y el contexto en tiempo de ejecución. Por ese contrato, los ataques que envenenan las definiciones de herramientas o las cambian en silencio surgen en el mismo lugar. Cuando añadas otro servidor MCP, te recomiendo comprobar no solo qué puede hacer ese servidor, sino también si tu host te avisa cuando cambian sus definiciones.

Si MCP trata de qué permitir hacer al agente, qué contarle es tarea de archivos de contexto como CLAUDE.md o AGENTS.md. Cómo lee el agente esos archivos y hasta qué punto se respetan sus instrucciones se trata en Archivos de contexto.

Hoy las herramientas de IA (Claude, ChatGPT, Cursor, Gemini, Copilot) ya forman parte integral de nuestro trabajo. La velocidad de desarrollo ha crecido exponencialmente, pero, para ser franco, tengo la impresión de que la calidad final de los servicios no ha avanzado al mismo ritmo. Cada vez es más habitual encontrarnos con tantos errores nuevos como funcionalidades añadidas, y también escuchar: «No sé por qué esto terminó así».

Cuando desarrollamos con tanta rapidez, dejamos de examinar el código línea por línea con el mismo detenimiento. Precisamente por eso, considero aún más necesario contar con los fundamentos necesarios para orientar a la IA en la dirección correcta. Para mantener la calidad del resultado, debemos ser capaces de detectar los problemas del código generado por la IA y volver a guiarla hacia el objetivo deseado. Entre esos fundamentos se encuentran el desarrollo desde la perspectiva del dominio, la abstracción, el TDD (Test-Driven Development, desarrollo guiado por pruebas), el uso adecuado de librerías y la optimización del rendimiento.

Sin embargo, cada vez que pregunto a colegas de frontend y de otras áreas de TI «¿cuál es la tarea más difícil del desarrollo frontend?», la respuesta más frecuente es siempre la misma: «Gestionar el flujo del estado».

En este artículo trataré de explicar por qué gestionar el flujo del estado resulta tan difícil y qué criterio e intuición conviene desarrollar para hacerlo bien.

¿Qué es el estado (State)?

Antes de entrar de lleno en el tema, empecemos por la pregunta más básica: ¿qué es exactamente eso que llamamos «estado»?

Mientras estudiaba desarrollo frontend, solía leer artículos de hoseung.me. Allí se define el estado como «todos los datos que pueden afectar a la UI». El número de «me gusta», los productos del carrito, si un modal está abierto, los valores introducidos, la información del usuario autenticado, la pestaña seleccionada, los resultados de búsqueda o el estado de carga: todo eso es estado.

La documentación oficial de React ofrece una definición algo más formal. El propio título de la página es "State: A Component's Memory", que podríamos desarrollar como «el mecanismo mediante el cual un componente retiene datos entre renderizados y hace que React dispare un nuevo renderizado cuando esos datos se actualizan». Es decir, son datos que no desaparecen con el paso del tiempo, que se actualizan a raíz de algún evento y que, al hacerlo, provocan que la UI vuelva a dibujarse. Hay otro punto importante: el estado está aislado en cada instancia del componente. Aunque haya diez instancias del mismo componente en una página, cada una conserva su propio estado independiente. Este hecho se relaciona directamente con la cuestión que veremos más adelante: «¿dónde debe residir el estado?».

Ambas definiciones apuntan a lo mismo: el estado es «un valor que cambia con el tiempo y afecta al renderizado». Una constante que no cambia no es estado. Un token de diseño primitivo fijado en build time no es estado, mientras que el modo oscuro que activa o desactiva el usuario sí lo es. (En rigor, el valor se resuelve según el estado del tema oscuro o claro; por tanto, es más preciso considerar que la «selección del tema» es el estado y que el token es el espejo en el que ese estado se refleja).

Conviene señalar algo más: no todo el estado vive en los componentes. Parte vive en cookies; otra, en localStorage, sessionStorage o IndexedDB; y otra, en la URL. Cuando traemos al cliente datos que residen en el servidor y los almacenamos en caché, también se convierten en una forma de estado. Incluso la posición de scroll o el stack del historial que mantiene el navegador deben tratarse a veces como estado, porque determinan el comportamiento de nuestra aplicación.

¿Por qué es tan difícil?

Pensemos primero en términos sencillos por qué cuesta tanto manejar el estado. ¿No bastaría con crear el estado necesario, llevarlo hasta donde haga falta y gestionar bien sus actualizaciones y su reinicialización?

Con esta pregunta en mente, abramos una página del servicio en el que estamos trabajando.

¿Cuántos componentes contiene? Incluso una página sencilla puede tener desde decenas hasta cientos de componentes organizados en forma de árbol. Cada componente puede mantener su propio estado, compartirlo con componentes hermanos o recibirlo de su padre. El estado también se transfiere entre páginas; parte debe sobrevivir a una recarga y parte debe desaparecer al cerrar la pestaña.

La verdadera razón por la que el estado es difícil de gestionar es esta: no podemos ver de un vistazo dónde se declaran todos esos estados, cómo se actualizan ni cuándo desaparecen. Cuantos más componentes con funciones similares aparecen, más difícil resulta nombrar el estado y rastrear el código que lo modifica.

Así se forma una telaraña invisible. Un clic en el componente A invalida los datos de B; esa invalidación cierra la UI de C; y al cerrarse C desaparece el contenido de un formulario. Si esta cadena no está expresada explícitamente en ninguna parte del código, cuando depuramos un error tenemos que reconstruir la telaraña en nuestra cabeza.

Entonces, ¿cómo podemos ordenar esa telaraña? A mi juicio, el primer paso consiste en reconocer que «existen distintos tipos de estado».

No todos los estados son iguales

Kent C. Dodds divide el estado entre Server Cache (información que reside en el servidor y que el cliente conserva para acceder a ella rápidamente) y UI State (estado que solo existe en la UI para controlar el comportamiento de la interfaz). A menudo cometemos errores al agrupar ambos.

La documentación oficial de TanStack Query lo define como una librería de server-state que gestiona operaciones asíncronas entre el servidor y el cliente, mientras que herramientas como Redux, MobX y Zustand son librerías de client-state. (Aunque pueden almacenar datos asíncronos, hacerlo resulta ineficiente).

La idea central es clara: Server State y Client State son problemas distintos. Server State es asíncrono, puede ser modificado por otros usuarios y, con el tiempo, pasa a estar stale. Client State es síncrono, está bajo nuestro control y desaparece al recargar la página. (Para ser exactos, cuando la página se descarga, el runtime de JavaScript se reinicia y tanto el árbol de componentes como el estado alojado en la memoria heap son liberados. Por eso, al montarse de nuevo, useState vuelve a comenzar desde su valor inicial). Si intentamos gestionar ambos con la misma herramienta, tendremos que implementar por nuestra cuenta patrones como la invalidación de caché, la actualización en background o las actualizaciones optimistas.

Doy un paso más y clasifico el estado del frontend en siete categorías. Conviene aclarar de antemano que estas siete categorías no se separan limpiamente sobre un único eje. Mezclan ubicación de almacenamiento, origen, ciclo de vida y función, por lo que un mismo estado puede pertenecer a varias categorías a la vez. No pretenden ser una taxonomía perfecta, sino preguntas que debemos plantearnos al decidir cómo gestionar el estado.

• Estado local (Local State): Estado usado solo dentro de un componente o de un subárbol reducido
• Estado global (Global State): Estado que debe compartirse en toda la aplicación
• Estado del servidor (Server State): Estado cuya fuente de verdad es el servidor y cuya copia en el cliente es una caché
• Estado del formulario (Form State): Estado temporal que existe mientras el usuario introduce datos
• Estado de la URL (URL State): Estado compartible que vive en la barra de direcciones y sobrevive a una recarga
• Estado externo (External State): Estado fuera de React, como cookies, localStorage, sessionStorage e IndexedDB
• Guard de estado (State Guard): Lógica que bloquea, permite o valida accesos y acciones según combinaciones de estado, en lugar de ser estado por sí misma

Además, existen estados de flujo que conviene modelar con una máquina de estados y estados colaborativos en tiempo real basados en WebSocket o CRDT.

Veamos, una por una, por qué cada categoría requiere herramientas diferentes y con qué criterio debemos abordarla.

Estado local (Local State)

Es el tipo de estado más sencillo. Solo se utiliza dentro de un componente y, desde fuera, no hay necesidad ni motivo para conocerlo. Algunos ejemplos son si un modal está abierto, el estado on/off de un botón toggle, el estado de hover o el término de búsqueda que se está escribiendo.

function SearchBox() {
  const [query, setQuery] = useState("");
  return <input value={query} onChange={(e) => setQuery(e.target.value)} />;
}

Hasta aquí, probablemente todo resulte familiar. Sin embargo, la verdadera dificultad del estado local reside en decidir «dónde debe ubicarse este estado».

En su artículo sobre State Colocation, Kent C. Dodds señala que la gente está acostumbrada a «elevar» el estado (lift up), pero rara vez vuelve a «colocarlo cerca» (colocate) cuando el código cambia.

Elevar el estado es algo que hacemos de forma natural cuando varios componentes hermanos necesitan compartirlo. Como ambos deben ver los mismos datos, trasladamos el estado al padre común y lo pasamos hacia abajo mediante props.

El problema aparece cuando esos componentes hermanos dejan de necesitarlo. No solemos volver a bajar el estado hacia los hijos. Como resultado, el componente padre termina acumulando estados que en realidad no le conciernen y, cada vez que vuelve a renderizarse, todo el árbol de hijos se renderiza con él.

Por eso, el primer criterio para el estado local es: para ganar velocidad y simplicidad, coloca el estado tan cerca como sea posible del código que lo utiliza. Si un estado solo se usa en uno de los hijos de un componente, no hay razón para que lo mantenga el padre. Movámoslo al interior de ese hijo. El padre será más ligero.

Estado global (Global State)

El estado global debe ser accesible desde cualquier parte de la aplicación. La información de autenticación, el tema, el idioma o las notificaciones (toasts) son posibles candidatos.

La diferencia entre el estado local y el global no se reduce a «dónde viven». Lo que cambia es el contrato de acceso. El estado local establece el contrato de que «solo tiene sentido dentro de este componente»; el global, en cambio, publica en todo el código el contrato de que «este valor puede consultarse con este nombre desde cualquier lugar de la aplicación». La esencia del estado global es que ese contrato resulta costoso.

Crear un estado global equivale, en realidad, a añadir una dependencia implícita en toda la aplicación.

Estado del servidor (Server State)

Guardamos en el estado del cliente los datos recibidos mediante una API, gestionamos manualmente la carga y los errores con valores boolean y terminamos preguntándonos: «¿por qué escribo siempre el mismo boilerplate?».

Tanner Linsley, principal responsable de TanStack, afirma: «Client State es síncrono y predecible. Server State es asíncrono, se comparte entre varios componentes y exige gestionar con cuidado el caching, las actualizaciones en background y los estados de error». Es decir, Server State es una especie esencialmente distinta de Client State. No deben tratarse con la misma herramienta.

La complejidad de Server State no se debe a las herramientas, sino a la propia naturaleza de los datos.

Los datos que ve el cliente pertenecen al servidor. Lo que conserva el cliente no es más que un snapshot de un momento concreto. Con el paso del tiempo, esos datos acumulan staleness. Además, son asíncronos, pueden fallar y atraviesan estados como pending, error y success.

La propiedad esencial más importante es que nada garantiza que las respuestas regresen en el mismo orden en que se enviaron las solicitudes. Imaginemos que escribimos rápidamente «react» en un campo de búsqueda. Las solicitudes r → re → rea → reac → react se envían en ese orden, pero si la respuesta de «react» llega primero y después llega la de «rea», la pantalla mostrará los resultados de «rea». Para evitar este problema hay que ocuparse de los riesgos de concurrencia (race conditions), implementando cada vez a mano un AbortController o el seguimiento de los ID de solicitud.

Estado de formulario (Form State)

Los formularios albergan un tipo de estado peculiar. Mientras el usuario escribe, cambia intensamente; pero, una vez enviado, normalmente desaparece. No se comparte con ningún otro lugar y, en la mayoría de los casos, tampoco tiene otro destino en el que almacenarse.

El problema es que ese «cambio intenso» resulta costoso. Si cada pulsación provoca un nuevo renderizado de React, en los formularios grandes el retraso al escribir puede llegar a ser perceptible. Además, un formulario no se limita a «guardar valores». Dentro de él conviven y cambian al mismo tiempo muchos tipos de estado: validación, dirty check, estado de envío, mensajes de error y flujos de varios pasos.

En un formulario de varios pasos, como un proceso de pago en tres etapas, se espera que «el progreso sobreviva incluso a una recarga a mitad del proceso». Si mantenemos los valores del formulario únicamente con useState, la recarga los eliminará todos. Lo natural es almacenarlos en sessionStorage (persistencia temporal por pestaña) o en la URL (para pasos que puedan compartirse). Es decir, según los requisitos de su ciclo de vida, Form State se combina con External State o URL State.

Estado de URL (URL State)

Supongamos que en una página de búsqueda estamos filtrando por categoría, orden y número de página. Si mantenemos esos estados con useState, aparecen tres problemas a la vez.

• Al recargar, todos los filtros se reinician
• Aunque compartamos la URL con otra persona, esta verá la página sin los filtros aplicados
• Al pulsar «Atrás», no regresaremos a los filtros anteriores

Para resolver estos problemas, resulta natural colocar el estado en la URL. La URL es, por sí misma, un almacenamiento persistente gratuito que ya admite recargas, uso compartido e historial.

/products?category=shoes&sort=price-desc&page=2

Esa única línea contiene el estado completo de «la segunda página de la categoría de zapatos, ordenada por precio descendente». No hace falta mantenerlo por separado con useState.

Entonces, ¿cuándo conviene gestionar el estado en la URL? La URL es una interfaz pública. No debemos incluir en ella contraseñas, tokens de autenticación ni notas temporales que el usuario no quiera mostrar a otras personas. Tampoco conviene insertar directamente valores que cambian con demasiada frecuencia —como un término de búsqueda que se actualiza con cada pulsación—, porque el stack del historial se llenará de basura. En esos casos debemos aplicar el cambio después de un debounce y reservar push para cuando corresponda, usando replace en las actualizaciones que no deban añadir una entrada al historial.

Los valores de la URL son siempre strings. Los números, valores boolean, arrays y objetos deben pasar por un proceso de serialización y deserialización. Además, la URL debe seguir las reglas de percent-encoding, por lo que caracteres como &, =, el coreano o los espacios reciben un tratamiento especial. Implementarlo manualmente una y otra vez pronto se convierte en una fuente de errores.

const params = new URLSearchParams(location.search);
const page = Number(params.get("page") ?? "1");
params.set("page", String(page + 1));
navigate(`?${params.toString()}`);
 
const [page, setPage] = useQueryState("page", parseAsInteger.withDefault(1));

Librerías como nuqs resuelven ambos problemas mediante el concepto de parser. Parsers como parseAsInteger, parseAsBoolean y parseAsJson se encargan a la vez de la serialización, la deserialización y los tipos. Son compatibles con la mayoría de los entornos, incluidos Next.js (tanto App Router como Pages Router), React Router v6/v7, TanStack Router y Remix.

¿Significa eso que podemos insertar en la URL todo el estado que queramos? Al margen de los problemas de serialización y tipos, queda una última restricción. RFC 7230 no fija un límite exacto, pero recomienda que «los servidores admitan al menos 8.000 octetos» (unidad que designa inequívocamente un byte formado por ocho bits en redes y comunicaciones de datos). Los límites también varían entre navegadores: los navegadores modernos suelen admitir desde 8 KB hasta decenas de miles de caracteres, pero el procesamiento de OG y enlaces compartidos de buscadores y redes sociales, así como algunos gateways, puede truncarlos alrededor de los 2 KB. Por tanto, no introduzcamos datos ilimitados en la URL. Lo seguro es conservar allí únicamente los filtros esenciales que deban poder compartirse y delegar el resto en sessionStorage o en almacenamiento del lado del servidor.

Estado externo (External State)

React solo conoce el estado que hay en su interior. Sin embargo, nuestra aplicación se comunica sin cesar con el mundo exterior a React. Los estados que viven en ese mundo sobreviven y cambian con independencia del ciclo de vida de React. Aquí, External State se refiere a Cookie, localStorage,sessionStorage,IndexedDB.

¿Cómo elegir el almacenamiento apropiado? Suelo evaluarlo desde cuatro perspectivas: duración, capacidad, sincronía y seguridad.

Para los tokens de autenticación, la recomendación de OWASP prioriza las cookies HttpOnly + Secure. Como JavaScript puede acceder a localStorage, en cuanto se produce una vulnerabilidad XSS, el token queda directamente expuesto. Algunas guías de seguridad recomiendan un patrón híbrido: guardar el access token en memoria y el refresh token en una cookie HttpOnly. Para datos persistentes, no sensibles y que cambian con poca frecuencia se utiliza localStorage; para datos que deben desaparecer junto con la pestaña, sessionStorage. IndexedDB suele emplearse para caché offline, grandes volúmenes de datos y archivos.

Cookie y Web Storage (local/session) solo almacenan strings. Para guardar un objeto hay que pasar por JSON.stringify/JSON.parse. Pero JSON tiene limitaciones.

JSON.stringify({ when: new Date() });
// → { "when": "2026-05-19T..." } — Date becomes a string
 
JSON.stringify({ map: new Map([["a", 1]]) });
// → { "map": {} } — Map is lost entirely
 
JSON.stringify({ value: undefined });
// → "{}" — the undefined field is omitted

Date se convierte en string al hacer un round trip por JSON, mientras que Map, Set y undefined pueden perder datos. Con el comportamiento predeterminado, BigInt hace que JSON.stringify lance un TypeError, por lo que la serialización falla por completo. Al guardar objetos en almacenamiento externo, debemos tener siempre presente qué tipos pueden desaparecer, transformarse o hacer fallar la serialización y añadir un adaptador cuando sea necesario.

La verdadera dificultad de External State es que React no detecta automáticamente sus cambios. Aunque escribamos un valor en localStorage, los componentes de React no vuelven a renderizarse. Normalmente existen tres patrones para resolverlo.

• Envolverlo en un custom hook (useLocalStorage) y sincronizar el estado externo con el estado de React. Es una solución ligera, pero si la implementamos nosotros mismos debemos cubrir todos los casos límite: múltiples pestañas, SSR, tearing, etc.
• Usar el hook useSyncExternalStore, incorporado en React 18, para «sincronizarnos con un estado externo a React». Esto permite garantizar que no se produzca tearing durante el renderizado concurrente. Es la herramienta estándar para conectar localStorage, las API del navegador y los stores externos.
• Aprovechar librerías existentes, ya que las librerías de estado ofrecen como funcionalidad de primera clase la integración con almacenamiento externo, como el middleware persist de Zustand o atomWithStorage de Jotai.

Añadamos otro criterio: en el momento en que llevamos External State a React, la responsabilidad de sincronizarlo recae sobre nosotros. ¿Qué ocurre si se actualiza desde otra pestaña? ¿Si el servidor modifica una cookie? ¿Si el usuario manipula localStorage directamente desde las herramientas de desarrollo del navegador? Estas situaciones suelen convertirse en algunas de las mayores fuentes de errores.

Guard del estado (State Guard)

La última categoría es algo diferente. No es estado en sí mismo, sino la lógica que bloquea, permite o valida un flujo a partir de una combinación de estados.

El ejemplo más habitual es el Auth Guard.

function ProtectedRoute({ children }) {
  const { isAuthenticated, isLoading } = useAuth();
 
  if (isLoading) return <Spinner />;
  if (!isAuthenticated) return <Navigate to="/login" replace />;
  return children;
}

Aquí, el estado isAuthenticated controla el flujo de routing. Eso es precisamente la lógica de un guard. Existen varios tipos: Auth Guard (autenticación), guards de autorización (roles o permisos específicos), guards de flujo (ramificación al entrar) y guards de validación (activación de etapas), entre otros.

La lógica de guards tiende a concentrarse en un único lugar. Es habitual que un componente reúna condiciones como «si no ha iniciado sesión, ir a la página de login; si no tiene permisos, mostrar un 403; si el carrito está vacío, ir a la página de productos; si el usuario está suspendido, mostrar el aviso de suspensión». Cuanto más crece el guard, más difícil resulta depurar qué condición bloqueó el flujo y dónde.

Un buen guard solo comprueba una cosa. La combinación se realiza mediante Composition.

<AuthGuard>
  <RoleGuard role="admin">
    <FlowGuard require={["cartHasItems"]}>
      <CheckoutPage />
    </FlowGuard>
  </RoleGuard>
</AuthGuard>

Cada guard toma una única decisión y la composición queda a cargo de la estructura del árbol. Añadir un guard nuevo no requiere modificar los existentes.

Al diseñar guards, hay algo que debemos pensar incluso más que en el bloqueo: decidir adónde enviar al usuario y qué hacer después. Un guard que solo bloquea y no ofrece fallback termina en una pantalla en blanco o un spinner infinito.

El error más común consiste en que «el contenido protegido parpadea brevemente antes de que termine la comprobación asíncrona del guard». La validación del token de autenticación y la consulta de permisos suelen ser asíncronas; durante ese intervalo, isAuthenticated puede adoptar temporalmente el valor undefined o false. Si no tratamos explícitamente el estado de carga, el contenido protegido puede quedar expuesto durante ese instante o el usuario puede ser redirigido erróneamente a la página de login.

// Ignores loading and handles only missing data => incorrect
if (!user) return <Navigate to="/login" />;
 
// Treat loading as a first-class state (early return) => correct
if (isLoading) return <Spinner />;
if (!user) return <Navigate to="/login" replace />;
return children;

Al implementar guards de autorización se utilizan habitualmente dos modelos.

• RBAC (Role-Based Access Control): asigna permisos por rol. Por ejemplo: «admin puede ver la información de todos los usuarios». Es sencillo y rápido, pero el número de roles se dispara a medida que aumenta la granularidad
• ABAC (Attribute-Based Access Control): determina los permisos mediante una combinación de atributos. Por ejemplo: «si el usuario es autor de la publicación, pertenece al mismo equipo o es admin». Tiene una gran capacidad expresiva, pero es difícil de implementar y depurar

Como muestra la guía de RBAC de TanStack Router, se recomienda el patrón de colocar los guards en beforeLoad, en el nivel del router. La clave es que las comprobaciones de autorización no estén dispersas por el código, sino que puedan expresarse como datos (listas de roles y permisos). Así, un cambio en la política de permisos se limita a un cambio de datos.

Conclusión

Recapitulemos. La gestión del estado no es difícil porque las librerías lo sean. Es difícil porque a menudo olvidamos que existen distintos tipos de estado y porque resulta fácil pasar por alto que cada tipo exige herramientas y formas de pensar diferentes.

Mantener el estado local lo más cerca posible; cuestionar una vez más si el estado global es realmente global; tratar Server State como caché; separar los formularios del dominio; aprovechar la URL de forma más activa; ser conscientes de la responsabilidad que implica el almacenamiento externo; y dividir los guards en unidades pequeñas que puedan componerse. Esos son los fundamentos para trabajar con las siete categorías.

Y el criterio que opera por encima de ellas puede condensarse, en última instancia, en cuatro preguntas.

• ¿Dónde está la Single Source of Truth de estos datos?
• ¿Es un valor que puede calcularse o un valor que realmente debemos almacenar?
• ¿Hay alguna combinación imposible entre estos estados?
• ¿Este estado debe estar realmente en esta ubicación?

Plantearnos estas preguntas cada vez que construimos una pantalla nueva, revisamos una PR o recibimos código generado por la IA es, a mi juicio, la forma más segura de desarrollar criterio e intuición.

Como decía al principio, la IA permanecerá a nuestro lado durante mucho tiempo. Cada vez dedicaremos menos tiempo a revisar el código línea por línea. Pero, precisamente por eso, será más valiosa la capacidad de responder a pequeñas preguntas como «¿dónde debe residir este estado?». Pedirle a la IA «añade aquí otro useState» es fácil. Sin embargo, comprender qué hilo añade esa línea a la telaraña de nuestra aplicación depende únicamente del criterio de quien lee el código.

No existe una única respuesta correcta. Pero hay una diferencia evidente entre «crear estado sin saber qué es el estado» y «crearlo siendo conscientes de su tipo y ubicación». Espero que, la próxima vez que los lectores de este artículo vayan a escribir una línea de useState, se detengan un instante y se pregunten: «¿a qué categoría de estado pertenece esto?».

Está pensada para desarrolladores frontend cuyas reglas de negocio, como el cálculo de impuestos o la comprobación del estado de una declaración, están repartidas entre componentes, hooks y utils, de modo que cada cambio de regla obliga a buscar y corregir varios archivos. Al terminar, sabrás cómo mover esas reglas a funciones puras que no dependen de React y con qué criterio decidir dónde detener esa separación.

Todos los ejemplos usan el cálculo del impuesto sobre la renta, un dominio que me interesa.

¿Dónde debe estar la lógica de dominio en el frontend?

Antes de responder, pongámonos de acuerdo en un término. En esta entrada, un modelo de dominio reúne los conceptos de negocio junto con las reglas que operan sobre ellos. Es distinto de un modelo de datos, como el tipo de una respuesta de la API, que solo define la forma en que viajan los datos. Esta diferencia es también la razón por la que, cuando los componentes dependen directamente de la estructura de la respuesta, todo el frontend se tambalea cada vez que cambia el esquema del backend. En qué se diferencian los cuatro términos (dominio, modelo de dominio, objeto de dominio y modelo de objetos de dominio) lo explico aparte en Términos de dominio.

Khalil Stemmler, muy interesado en el diseño de software, sostuvo al principio que «la lógica de negocio no pertenece al frontend», pero más adelante revisó su postura y afirmó que «casi todo lo que hacemos arquitectónicamente en el backend también podemos y debemos hacerlo en el frontend».

Estoy de acuerdo. Por supuesto, el frontend no debe convertirse en la única fuente de verdad (Single Source of Truth) de la lógica de negocio. Ese es el papel del backend. Pero en el frontend también existe, sin duda, lógica de dominio propia del frontend.

Pensemos en un caso en el que «hay que mostrar en tiempo real la devolución estimada en función de la información introducida por el usuario». Si esta lógica de cálculo solo existe en el backend, habría que llamar a la API cada vez que el usuario corrigiese un solo dígito del importe de sus ingresos. La UI se detendría durante todo el viaje de ida y vuelta por la red y, si el usuario escribe rápido, se dispararía una cantidad enorme de peticiones innecesarias. Incluso con debounce, un retraso de varios cientos de milisegundos basta para romper la experiencia de una «vista previa en tiempo real». En última instancia, el frontend no tiene más remedio que realizar directamente los cálculos que requieren una respuesta inmediata, por lo que existe lógica que solo puede ejecutarse en el frontend.

Cuando la lógica de dominio se mezcla con el componente

Tomemos como ejemplo una pantalla de vista previa del impuesto sobre la renta global. Cuando el usuario introduce la información sobre sus ingresos, se muestra en tiempo real la cuota estimada. Este es un ejemplo habitual de código en el que se mezclan la lógica de dominio y la lógica de UI.

function TaxPreviewPage() {
  const [총수입, set총수입] = useState(0);
  const [경비율, set경비율] = useState(0.641); 
  const [인적공제대상인원, set인적공제대상인원] = useState(1); 
 
  const 종합소득금액 = 총수입 - 총수입 * 경비율;
 
  const 소득공제합계 = 인적공제대상인원 * 1_500_000;
  const 과세표준 = Math.max(0, 종합소득금액 - 소득공제합계);
 
  let calculatedTax = 0;
  if (과세표준 <= 14_000_000) {
    calculatedTax = 과세표준 * 0.06;
  } else if (과세표준 <= 50_000_000) {
    calculatedTax = 과세표준 * 0.15 - 1_260_000;
  } else if (과세표준 <= 88_000_000) {
    calculatedTax = 과세표준 * 0.24 - 5_760_000;
  } else if (과세표준 <= 150_000_000) {
    calculatedTax = 과세표준 * 0.35 - 15_440_000;
  } else {
    calculatedTax = 과세표준 * 0.38 - 19_940_000;
  }
 
  const 기납부세액 = 총수입 * 0.033;
  const refundOrPayment = 기납부세액 - calculatedTax;
 
  return <div>...</div>;
}

¿Se aprecia el problema? Las reglas de negocio fijadas por la legislación fiscal —«deducción personal de 1,5 millones de wones por persona», «ocho tramos impositivos progresivos» y «retención del 3,3 %»— están incrustadas directamente en un componente de React. La legislación fiscal cambia cada año; si estas reglas están dispersas por los componentes, cada reforma obliga a buscar todos los lugares que hay que modificar. Si además existen escenarios E2E gestionados por el equipo de QA, el coste de las pruebas tampoco será menor.

Al final, resulta difícil distinguir la lógica de vista de la lógica de negocio, y el código acaba enredado entre innumerables condicionales y hooks personalizados.

Separemos la lógica de dominio

Tomemos prestado un principio central del enfoque de Clean Architecture de Alex Bespoyasov: separar la lógica de dominio en funciones puras que no dependan de ningún framework.

El dominio es el núcleo que distingue una aplicación de otra. Puede entenderse como aquello que no cambiaría si migrásemos de React a Angular.

The domain is the core that distinguishes one application from another. You can think of the domain as something that won't change if we move from React to Angular.

Refactoricemos el ejemplo anterior del cálculo de impuestos.

Primero definimos los tipos y las reglas del dominio para cohesionar la información relacionada.

export interface Income {
  grossAmount: number;
  expenseRate: number;
}
 
export interface Deductions {
  personalCount: number;
  pensionPaid: number;
  additionalDeductions: number;
}
 
const PERSONAL_DEDUCTION_PER_PERSON = 1_500_000;
const WITHHOLDING_RATE = 0.033;
const TAX_BRACKETS = [
  { limit: 14_000_000, rate: 0.06, progressiveDeduction: 0 },
  /** ...구간들... **/
] as const;

A continuación, separamos la lógica de dominio en funciones puras.

Separamos en la función computeFullTax la lógica anterior para calcular los ingresos, las deducciones, la base imponible, la cuota y la devolución. A su vez, dividimos cada etapa en pequeñas funciones puras. Si inferimos el tipo del resultado con ReturnType<typeof computeFullTax>, no hace falta declarar otra interfaz.

Después, el componente se limita a «usar» la lógica de dominio.

import { computeFullTax } from "../domain/tax";
 
function TaxPreviewPage() {
  const [income, setIncome] = useState<Income>({
    grossAmount: 0,
    expenseRate: 0.641,
  });
  const [deductions, setDeductions] = useState<Deductions>({
    personalCount: 1,
    pensionPaid: 0,
    additionalDeductions: 0,
  });
 
  const result = computeFullTax(income, deductions);
 
  return (
    <div>
      <IncomeForm value={income} onChange={setIncome} />
      <DeductionForm value={deductions} onChange={setDeductions} />
      <TaxResultSummary result={result} />
    </div>
  );
}

¿Qué ha cambiado?

• La tabla de ocho tramos impositivos progresivos (TAX_BRACKETS) está reunida en un único lugar, por lo que, cuando cambie la legislación fiscal, solo habrá que modificar domain/tax.ts.
• El flujo de cálculo está cohesionado en una sola función, computeFullTax, lo que permite ver de un vistazo el proceso completo. (Se ha agrupado para simplificar el ejemplo, pero en un proyecto real conviene dividirlo más según su propósito: cálculo de ingresos, cálculo de deducciones, cálculo de la cuota, etc.).
• El componente se concentra únicamente en «cómo mostrarlo». Aunque cambien los tipos impositivos, no hace falta modificar el componente.
• Aunque se migre de React a otro framework, domain/tax.ts no cambia.

Cuando se separa la lógica de dominio, las pruebas se vuelven sorprendentemente sencillas. Esto es especialmente importante en el dominio fiscal, donde la precisión de los cálculos es, literalmente, el dinero del usuario.

Las funciones puras que contienen cálculos fiscales no necesitan React Testing Library, ni render, ni screen.getByText. Basta con proporcionar una entrada y comprobar la salida. Casos como «tipo del 6 % hasta 14 millones de wones», «si la base imponible es 0 wones, la cuota también es 0» o «devolución para un autónomo con 30 millones de wones de ingresos» pueden expresarse con un it de una sola línea. Las pruebas unitarias del dominio establecen de forma natural el criterio para separar componentes y, además, el código de prueba actúa como documentación.

Modelo de dominio anémico (Anemic Domain Model)

En el apartado anterior separamos la lógica de cálculo. Sin embargo, la lógica de dominio también incluye reglas de transición de estado y comprobaciones de permisos. Preguntas como «¿se puede editar ahora esta declaración?», «¿se puede presentar?» o «¿se puede cambiar el tipo de reclamación?» pertenecen a esta categoría. Al separar estas reglas es fácil caer en una trampa que Martin Fowler denominó modelo de dominio anémico (Anemic Domain Model).

Un modelo de dominio anémico es aquel en el que los tipos están bien definidos en el lenguaje del dominio, pero las reglas que operan sobre ellos se han dispersado fuera del dominio. Veamos como ejemplo el dominio de una declaración de impuestos (Filing). El tipo está limpio.

// types/filing.ts
export interface TaxFiling {
  id: string;
  status: "draft" | "submitted" | "reviewing" | "completed" | "amended";
  taxYear: number;
  filingType: "regular" | "late" | "amendment";
  determinedTax: number;
}

Pero las reglas para decidir y realizar transiciones sobre este tipo están incrustadas en otros lugares.

// utils/filingHelpers.ts
export function canAmendFiling(filing: TaxFiling) {
  return filing.status === "completed" && filing.filingType !== "amendment";
}
 
// components/FilingDetail.tsx
function FilingDetail({ filing }: { filing: TaxFiling }) {
  // 같은 도메인 규칙을 컴포넌트 안에 다시 작성한다
  const canEdit = filing.status === "draft" || filing.status === "reviewing";
  // ...
}
 
// hooks/useSubmitFiling.ts
export function handleSubmitFiling(filing: TaxFiling) {
  if (filing.status !== "draft") return;
  // ...
}

La misma regla de dominio existe con formas distintas en tres lugares: utils, un componente y un hook. Si en este estado llega un requisito como «cambian las condiciones para presentar una reclamación», habrá que recorrer el código en busca de todos los lugares que deben modificarse, y cualquier omisión provocará una decisión incorrecta en alguna parte del sitio. Fowler criticó este tipo de código por ser «poco más que código procedimental revestido con una apariencia orientada a objetos».

La solución es la misma que aplicamos a la lógica de cálculo en el apartado anterior: poner las reglas junto al tipo.

export interface TaxFiling {
  id: string;
  status: FilingStatus;
  taxYear: number;
  filingType: FilingType;
  determinedTax: number;
}
 
export type FilingStatus =
  | "draft"
  | "submitted"
  | "reviewing"
  | "completed"
  | "amended";
 
export type FilingType = "regular" | "late" | "amendment";
 
// 도메인 규칙은 도메인 옆에 둔다
export function canEdit(filing: TaxFiling): boolean {
  return filing.status === "draft";
}
 
export function canSubmit(filing: TaxFiling): boolean {
  return filing.status === "draft" && filing.determinedTax >= 0;
}
 
export function canAmend(filing: TaxFiling): boolean {
  return filing.status === "completed" && filing.filingType !== "amendment";
}

Ahora las reglas relacionadas con las declaraciones se gestionan en un único lugar, domain/filing.ts. Cualquier componente puede llamar a canAmend(filing) y, si cambia una regla, basta con modificar este archivo. La clave es entender el tipo y las reglas que operan sobre él como una sola unidad. Dejar solo el tipo en la carpeta del dominio y extraer las reglas a utils es una separación parcial que puede parecer limpia, pero sigue siendo anémica.

Capa de transformación entre la respuesta de la API y el modelo de dominio

En un proyecto real hay que tener en cuenta otra cuestión: la estructura de las respuestas de la API del backend no siempre coincide con el modelo de dominio del frontend. Esto es aún más cierto en un servicio fiscal conectado con organismos públicos. Los datos de integración con Hometax, el portal de la Agencia Tributaria Nacional de Corea, están llenos de abreviaturas y códigos, por lo que es poco probable que lleguen con la misma forma que el modelo de dominio del frontend.

Para eso necesitamos una capa de transformación (Mapper). En lugar de llevar el tipo de la respuesta de la API directamente hasta el componente, primero lo depuramos y lo convertimos en un tipo de dominio. Basta con una función pura.

import type { Income } from "../domain/tax";
 
interface HometaxIncomeResponse {
  총수입금액: number;
  경비율: number;
  소득유형코드: string;
  // ... 나머지 약어 필드들
}
 
export function toIncome(response: HometaxIncomeResponse): Income {
  return {
    총수입_금액: response.총수입금액,
    경비_비율: response.경비율,
  };
}

De este modo, las abreviaturas y clasificaciones basadas en códigos de la respuesta de la API, como 총수입금액 y 경비율, se transforman en un único lugar para adaptarlas al dominio del frontend. Los valores que deben desplegarse como enum, como el código del tipo de ingreso, pueden resolverse con una pequeña lookup table dentro del mapper. Aunque cambien los nombres de los campos de la API de Hometax, solo habrá que modificar el mapper.

Funciones utilitarias y lógica de dominio

Al separar la lógica de dominio surge inevitablemente una pregunta: «¿esto no es una función utilitaria?»

Veamos, por ejemplo, estas dos funciones.

function formatCurrency(amount: number): string {
  return `${amount.toLocaleString()}원`;
}
 
function calculateTax(taxableBase: number): number {
  const bracket = TAX_BRACKETS.find((bracket) => taxableBase <= bracket.limit);
  return Math.floor(taxableBase * bracket.rate - bracket.progressiveDeduction);
}

formatCurrency es pura lógica de presentación (Presentation) que transforma un número en texto. Añadir la unidad «won» y los separadores de miles no es una regla de negocio, sino una decisión sobre cómo mostrar el valor al usuario. En cambio, calculateTax contiene una regla de negocio basada en la legislación fiscal: «aplicar ocho tramos impositivos progresivos». Es una regla del dominio que debe aplicarse de la misma forma incluso sin UI.

Este es el criterio que uso en la práctica.

Si esta lógica desaparece, ¿se rompe el negocio o solo se rompe la pantalla?

Si se rompe el negocio, es lógica de dominio; si solo se rompe la pantalla, es lógica de presentación. Esta pregunta permite trazar la mayoría de los límites.

Pero la realidad no es tan limpia. El caso más difícil es el de la lógica que parece de dominio, pero en realidad es de presentación.

Veamos el siguiente código. Como recibe un concepto de dominio llamado FilingStatus, se ha clasificado como lógica de dominio. Pero ¿lo es realmente?

// domain/filing.ts
function getStatusBadgeColor(status: FilingStatus): string {
  const colors: Record<FilingStatus, string> = {
    draft: "gray",
    submitted: "blue",
    reviewing: "yellow",
    completed: "green",
    amended: "purple",
  };
  return colors[status];
}
 
function getStatusDisplayText(status: FilingStatus): string {
  const labels: Record<FilingStatus, string> = {
    draft: "작성 중",
    submitted: "제출 완료",
    reviewing: "검토 중",
    completed: "신고 완료",
    amended: "경정청구",
  };
  return labels[status];
}

Aunque getStatusBadgeColor y getStatusDisplayText usan el concepto de dominio FilingStatus, su función es la presentación en pantalla. Si cambia el color de la insignia, el negocio no se rompe en absoluto. Si ponemos estas funciones en domain/filing.ts, el módulo de dominio crecerá cada vez más y la auténtica lógica de dominio acabará mezclada con la lógica de presentación.

Separar el modelo de dominio y el ViewModel

Hay una forma práctica de resolver este problema: separar el ViewModel en un archivo distinto dentro de la misma carpeta del dominio. En lugar de .ui.ts, usar el nombre .viewModel.ts enlaza de forma natural con el concepto de ViewModel del patrón MVVM. El propio nombre deja claro su papel como «capa que transforma los datos de dominio para adaptarlos a la pantalla».

domains/
└── filing/
    ├── filing.ts              # 순수 도메인 모델 + 도메인 로직
    ├── filing.viewModel.ts    # ViewModel (표현 변환 계층)
    ├── filing.test.ts         # 도메인 로직 테스트
    └── filingMapper.ts        # API ↔ 도메인 변환

Movemos tal cual getStatusBadgeColor y getStatusDisplayText a filing.viewModel.ts. También reunimos aquí transformaciones como getFilingTypeLabel(type: FilingType): string, que convierte los tipos de declaración en etiquetas coreanas. filing.ts se ocupa solo de las reglas de negocio y filing.viewModel.ts, solo de su presentación en pantalla.

La clave es la dirección de las dependencias. filing.viewModel.ts importa filing.ts, pero filing.ts nunca importa filing.viewModel.ts. El dominio no conoce la presentación; la presentación sí conoce el dominio. Puede verse como una versión reducida de la regla de dependencias (Dependency Rule) de Robert C. Martin.

He colocado en la misma carpeta los archivos que cambian juntos porque considero que deben estar en el mismo directorio. Si se añade un valor nuevo al tipo FilingStatus —por ejemplo, 'rejected'—, habrá que modificar tanto filing.ts como filing.viewModel.ts. Al encontrarse en la misma carpeta, el alcance del cambio resulta evidente.

Límites y cohesión

Tan importante como separar la lógica de dominio es decidir dónde trazar los límites. Estos son algunos de los problemas al definir límites que encuentro con frecuencia en proyectos reales.

Los datos que maneja un frontend proceden, a grandes rasgos, de cuatro fuentes.

• Datos del servidor: recibidos como respuesta de una API.
• Datos derivados: calculados a partir de los datos del servidor.
• Estado de la UI: destinado a controlar la pantalla y las interacciones del usuario.
• Entrada del usuario: datos que se están introduciendo en un formulario.

Si mezclamos los cuatro en un único tipo, contaminamos el modelo de dominio.

// 안티패턴: 모든 것이 섞인 타입
interface TaxFiling {
  // 서버 데이터 (도메인)
  id: string;
  status: FilingStatus;
  determinedTax: number;
 
  // 파생 데이터 (도메인)
  refundAmount: number;
  canAmend: boolean;
 
  // UI 상태 (표현)
  isExpanded: boolean;
  activeStep: number;
 
  // 임시 상태
  editingDeductions: Deduction[];
}

Este tipo mete en el mismo recipiente conceptos de dominio, estado de la UI y datos temporales. Cada vez que cambia activeStep, es como si se actualizase el dominio de la declaración. (Cambiar de paso en un formulario no es un evento de negocio).

La mejora consiste en separar los tipos según sus límites. El modelo de dominio solo contiene conceptos de negocio como id, status y determinedTax; el estado de la UI (FilingFormViewState) contiene únicamente controles de pantalla como isExpanded y activeStep; y el estado del formulario (DeductionEditForm), solo los datos temporales que se están introduciendo.

Así, cada tipo tiene un único motivo para cambiar. Los tipos de dominio solo se modifican cuando cambia la legislación fiscal; el estado de la UI, cuando cambia el diseño de la pantalla; y el estado del formulario, cuando cambia la UX de entrada.

Mantengamos juntas las cosas que cambian juntas

En el DDD de Eric Evans existe el concepto de Aggregate (agregado): «tratar un grupo de objetos relacionados como una sola unidad». No hace falta aplicarlo literalmente en el frontend, pero sí merece la pena adoptar su principio central: mantener juntos los datos y las reglas que cambian juntos.

En un servicio fiscal, por ejemplo, Income (ingresos) y ExpenseRate (coeficiente de gastos) siempre cambian juntos. Si cambia el tipo de ingreso, también cambia el coeficiente aplicable y se ve afectado el cálculo de la renta global. Por tanto, conviene cohesionarlos en un solo archivo, domain/tax.ts.

En cambio, TaxFiling (declaración) puede cambiar con independencia del cálculo de la cuota. Aunque cambien las reglas de transición de estado de una declaración, la lógica para calcular los tipos impositivos no se ve afectada. Por tanto, es correcto separarla en domain/filing.ts.

이렇게 묻자: "A가 변할 때 B도 반드시 변해야 하는가?"
  → Yes: 같은 모듈에 둔다 (Income + ExpenseRate + TaxBracket)
  → No: 분리한다 (Tax 계산 ↔ Filing 상태관리)

Class frente a estilo funcional

Llegados a este punto puede surgir una pregunta fundamental. Todos los ejemplos anteriores combinan interface y funciones puras; ¿no sería más natural expresar el dominio con Class para lograr una mayor cohesión?

Es cierto. Cuando se expresa un dominio mediante Class, los datos y el comportamiento quedan agrupados en un mismo objeto, por lo que la cohesión se hace visible directamente en la estructura del código.

class TaxFilingModel {
  constructor(
    public readonly id: string,
    public readonly status: FilingStatus,
    public readonly taxYear: number,
    public readonly filingType: FilingType,
    public readonly determinedTax: number,
  ) {}
 
  canEdit(): boolean {
    return this.status === "draft";
  }
 
  canAmend(): boolean {
    return this.status === "completed" && this.filingType !== "amendment";
  }
 
  canSubmit(): boolean {
    return this.status === "draft" && this.determinedTax >= 0;
  }
}
 
const filing = new TaxFilingModel(
  "F-001",
  "completed",
  2025,
  "regular",
  547200,
);
 
filing.canAmend();

Con Class, el comportamiento pertenece a los datos y el sujeto queda claro allí donde se utiliza. filing.canAmend() resulta intuitivo, como una frase en lenguaje natural. El sujeto (filing) y el verbo (canAmend) están unidos de forma explícita. Del mismo modo, al escribir jihoon.eat('감자탕') se lee de inmediato que «Jihoon come gamjatang».

En el estilo funcional, en cambio, queda así.

canAmend(filing);
eat("jihoon", "감자탕");

En el enfoque funcional, los datos existen fuera de la función. Las dos líneas anteriores reciben filing como argumento y ejecutan alguna operación. La función eat recibe jihoon y 감자탕 como datos y realiza la acción.

Como resultado, la relación entre sujeto y verbo es más débil. Para saber que la función canAmend está relacionada con TaxFiling, hay que abrir el archivo o consultar su firma de tipos. Si en un mismo archivo se mezclan funciones como canAmend(filing), canEdit(filing) y calculateTax(taxableBase), puede resultar difícil saber de un vistazo a qué dominio pertenece cada una.

Entonces, ¿deberíamos usar Class?

Sinceramente, la respuesta es «depende de la situación». Sin embargo, según mi experiencia, hay razones prácticas por las que Class no es una solución universal en un entorno React + TypeScript.

Fricción con la gestión del estado de React

La gestión del estado de React encaja de forma más natural con Plain Object. Aunque useState y useReducer pueden contener técnicamente cualquier valor, y Redux DevTools no elimina por sí mismo el prototipo de una instancia de Class, cuando el middleware de persistencia de Redux/Zustand guarda y restaura el estado como JSON, una instancia de Class pierde sus métodos y su prototipo en el ciclo JSON.stringify → JSON.parse y queda reducida a un plain object. El límite de props entre React Server Component y Client Component impone una restricción distinta: solo admite valores serializables (serializable) compatibles, por lo que una instancia arbitraria de Class no puede atravesarlo.

Veamos el siguiente código.

const [filing, setFiling] = useState(
  new TaxFilingModel("F-001", "draft", 2025, "regular", 0),
);

Actualizar el estado de React no hace que filing deje de ser una instancia de TaxFilingModel. Sin embargo, si la persistencia de Redux/Zustand lo guarda y restaura como JSON, el valor recuperado puede ser un plain object sin métodos, y una llamada desprevenida a filing.canAmend() puede provocar un error en tiempo de ejecución. Al pasarlo de React Server Component a Client Component, el fallo ocurre antes, porque una instancia de Class no es un valor de props serializable compatible.

Dificultad para garantizar la inmutabilidad

React detecta los cambios de estado mediante comparación de referencias (referential equality). Si un método de una instancia de Class modifica internamente el estado con algo como this.items.push(...), la referencia no cambia y React no activa un nuevo renderizado. Así que addDeduction(item) tendría que devolver siempre una instancia nueva, por ejemplo con return new DeductionList([...this.items, item]); pero entonces se diluye la ventaja de Class de «modificar un estado encapsulado». El resultado no es muy distinto de una actualización funcional.

Estrategias para lograr cohesión con el estilo funcional

Entonces, ¿cómo podemos mejorar en el estilo funcional el problema de cohesión débil que vemos en eat('jihoon', '감자탕')? Estas son tres estrategias que me han resultado eficaces.

Cohesionar mediante un namespace de módulo

Es la opción más intuitiva. Se convierte el propio archivo —el módulo— en una unidad de dominio y se usa un namespace al importarlo. Podemos reutilizar tal cual el archivo domain/filing.ts definido antes.