La mecánica de los modelos, en su justa medida

Lo que vas a poder hacer

entregable · lo que construyes

Un diagnóstico A/B controlado con evidencias

Una hora después de empezar una buena sesión, tu agente propone el enfoque que ya le dijiste que había fallado. Vuelve a pedir una ruta de archivo que le diste hace veinte mensajes. Repite un resumen que escribió él mismo. He visto a uno anunciar, en plena tarea, que necesitaba descansar.

El reflejo es comprar un modelo más grande. Esa es la respuesta equivocada más cara de este curso. Te cobra cada mes y deja el verdadero fallo donde estaba.

No necesitas entender los transformadores para dirigir un agente, igual que no necesitas conocer el interior del motor para conducir. Necesitas lo suficiente para interpretar las luces de aviso. Eso es este módulo, en sustitución de los cuatro módulos teóricos del curso anterior.

Cinco mecanismos: tokens, atención, predicción del siguiente token, no determinismo y fundamentación. Un propósito. Mirar un mal resultado y saber en diez segundos si es un problema de contexto que puedes corregir ahora o un límite real al que debes adaptar el diseño. Cuando el resultado empeore, sospecha primero del estado del contexto.

Tokens: un presupuesto, no un almacén

Un token es un fragmento de una palabra. Los modelos no leen letras ni palabras completas: leen tokens, cada uno de unos tres cuartos de palabra en promedio. «Diagnosis» podría ser dos tokens. Una ruta de archivo podría ser cinco.

Todo lo que el modelo puede ver a la vez está en un fondo fijo llamado ventana de contexto. Tus instrucciones, la conversación hasta ese momento, los archivos que cargó, los resultados que devolvieron las herramientas y las reglas que tu arnés, es decir, la aplicación en la que se ejecuta tu agente, incorpora antes incluso de que escribas nada. Todo en un solo fondo.

Ese fondo es un presupuesto, no almacenamiento. En muchos arneses, la entrada y la respuesta salen de la misma asignación, así que una entrada repleta deja menos espacio para responder. El fallo no se parece en nada a una pérdida de memoria. La respuesta se corta a mitad de frase, o el resumen cubre la primera mitad del trabajo y omite la segunda, y tú buscas un error en una tarea que simplemente se quedó sin espacio.

La ventana parece almacenamiento, así que el instinto es llenarla. El siguiente mecanismo explica por qué eso falla.

Atención: lo que realmente te cuesta añadir contexto

Para producir el siguiente fragmento de texto, el modelo no lee tu contexto de arriba abajo. Pondera los tokens entre sí y determina qué importa ahora. Esa ponderación es la atención.

El costo que eso tiene dentro del modelo depende de la arquitectura y la implementación, y los proveedores cambian ambas. Quédate con la parte útil y deja a un lado la aritmética. Más contexto puede dificultar la identificación de la señal, y un diagrama simplificado no es una ley de escalado para citar a los demás.

Si llenas la ventana, repartes una capacidad fija de ponderar la relevancia entre ruido que dejó de importarte hace cuarenta minutos.

Idea claveCargar menos supera a cargar más. Un contexto conciso no es una concesión para ahorrar dinero: es la forma de obtener una respuesta más precisa. 8,000 tokens del material exacto superan a 80,000 tokens de «por si acaso».

Esto tiene un nombre: degradación del contexto. La señal se deteriora a medida que se acumula basura, y esa basura es reconocible. Enfoques que abandonaste. Caminos sin salida que descartaste. Volcados de herramientas que nadie leyó. Tres versiones de un archivo cuando solo la última es válida.

El detalle que cambia cómo depuras es que la degradación empieza mucho antes de que se llene la ventana. La gente espera un aviso de contexto lleno, pero para entonces el daño empezó miles de tokens antes. Si tratas ese indicador como una medida de salud, discutirás durante una hora con una sesión que ya estaba contaminada.

Se vuelve más evidente cuando la respuesta es una cifra. Dale a un agente un libro contable completo y pídele una cifra: un contexto más largo no vuelve la respuesta más vaga. Vuelve más segura una respuesta equivocada, porque una gran pila de cifras de aspecto real le da a un total incorrecto mucho material con el que aparentar respaldo.

La solución es quitar y dar trazabilidad, y sirve para cualquier tarea larga cuya salida no puedas comprobar a simple vista. Divide el trabajo por sublibros contables para que cada ejecución lea menos. Haz que el modelo cite la celda fuente exacta de cada cifra. Comprueba que las partes sumen un total que ya conoces. Mantén cualquier escritura en el archivo real sujeta a aprobación humana. Una ventana más grande no hace nada de eso.

Predicción del siguiente token: por qué una respuesta incorrecta suena como una correcta

El modelo hace una cosa. Predice el siguiente token más probable dado todo lo que hay en su contexto. No está consultando nada ni contrastando un hecho con una fuente.

Cuando tu contexto contiene la información correcta, «lo más probable» y «lo que es cierto» coinciden la mayor parte del tiempo. Cuando falta algo, se separan y nada en el mecanismo lo detecta.

El modelo produce de todos modos la continuación más probable a partir de un vacío, y la suposición llega con el mismo tono seguro que una respuesta correcta. Eso es una alucinación. No es mentir. Es rellenar un hueco que dejaste abierto, sin forma de señalar que está adivinando.

La fecha de corte del conocimiento es el mismo fallo con una fecha. El entrenamiento terminó en algún momento, así que todo lo posterior es un hueco como los de tus propios archivos, rellenado con la misma seguridad. Una respuesta desactualizada sobre una herramienta que cambió el mes pasado es un modelo que responde desde antes del cambio. Por eso cada informe de error registra la fecha de corte junto al prompt, y todo lo sensible al tiempo se fundamenta en fuentes en lugar de preguntarse sin más.

Eso te da tres causas, cada una con su mecanismo. El ruido acumulado que diluye la relevancia es degradación del contexto. Un vacío en lo que recibió el modelo, ya sea de tus archivos o por la fecha de su entrenamiento, es falta de contexto, y aparece como ficción expresada con seguridad. Dos reglas que se contradicen son la causa que provocan tus propios archivos.

No determinismo: la misma entrada, dos veces, dos respuestas

Ejecuta el mismo prompt dos veces y puedes obtener dos respuestas distintas. El muestreo añade aleatoriedad a propósito. La temperatura, el esfuerzo de razonamiento, las herramientas que estaban disponibles y las propias reglas incorporadas por el arnés pueden cambiar entre ejecuciones sin que toques nada.

Eso es lo que desperdicia tardes. Si tu referencia cambia, no puedes distinguir una solución real de una tirada con más suerte. Dos ejecuciones que parecen buenas no demuestran nada por sí solas.

Así que, cuando estés diagnosticando en lugar de trabajando, fija lo que tu arnés te permita fijar, normalmente un archivo de entrada guardado y los controles de muestreo que ofrezca. Ejecuta ambos casos en las mismas condiciones de sesión, no uno hoy y otro mañana. Escribe el resultado esperado antes de mirar cualquiera de las salidas, porque una comprobación de finalización inventada después se adapta a lo que hayas obtenido.

Registra los ajustes incluso cuando no puedas fijarlos. «Esfuerzo de razonamiento desconocido, valor predeterminado del arnés» es evidencia real. Un campo vacío no lo es.

Fundamentación: recuperación, herramientas y formato, y lo que ninguna demuestra

Tres cosas añaden material externo a un contexto, y las tres se confunden con pruebas.

La recuperación añade evidencias seleccionadas, y «seleccionadas» es la palabra importante. Algo eligió qué pasajes incorporar, ese selector tiene sus propios modos de fallo y el modelo responde con seguridad a partir de lo que llegó, incluidos tres párrafos equivocados recuperados sin que se informara de ningún error.

Una llamada a una herramienta añade una operación y un resultado. Demuestra que se ejecutó la operación. No demuestra que el resultado responda a tu pregunta ni que el modelo lo haya interpretado correctamente.

La salida estructurada te da un formato que puedes validar, y merece la pena porque una comprobación de esquema la puede hacer una máquina y no depende de una impresión. Pero un formato válido solo dice que están los campos y que los tipos son correctos. Un objeto JSON perfectamente formado y lleno de cifras inventadas supera todos los validadores que tengas.

Una comprobación detecta la prueba falsa más común. Una cita no es respaldo. Un agente adjuntará un enlace que es real y no contiene la afirmación. Así que, cuando un hecho lleve una fuente, comprueba que la fuente realmente lo dice, al menos en los hechos sobre los que vayas a actuar.

Ninguna de las tres elimina la necesidad de verificar. La acotan, siempre que sepas qué parte sigue siendo tuya.

El mito de la ventana grande

Intentarán venderte el tamaño de la ventana constantemente. Un millón de tokens. Dos millones. La promesa es que una ventana lo bastante grande convierte la gestión del contexto en un problema de otro.

No lo hace. El límite anunciado y el límite utilizable son cifras distintas, porque la capacidad de recordar, la calidad de la recuperación, cuánto contenido vuelcan tus herramientas y cómo está construida la tarea cambian el punto en que baja la calidad. Prueba cualquier afirmación sobre ventanas grandes con el trabajo que realmente haces y registra tu propio umbral de fallo en lugar de una cifra de una página de marketing.

El extremo contrario también falla. Comprime demasiado el contexto para ahorrar en la factura y obtendrás resultados peores, no más baratos, porque el modelo pierde cosas que necesitaba y pagas por rehacer el trabajo. El objetivo es el contexto adecuado, ni el máximo ni el mínimo.

AdvertenciaTrata «simplemente usa una ventana más grande» como una respuesta que no responde. El límite utilizable queda muy por debajo de la cifra de la caja, y recurrir a más ventana evita la única pregunta que vale la pena: qué hay realmente en el contexto ahora mismo.

El vocabulario de los fallos

Una tabla para tener abierta mientras trabajas. Cada fila es un síntoma que puedes observar y la primera pregunta que permite distinguir las causas.

Un límite real del modelo, el proveedor o la herramienta es una última hipótesis válida. No la prohíbas: ponla a prueba después de una reproducción limpia. Prohibirla es la forma de pasar tres días reescribiendo archivos de contexto para una tarea que el modelo no puede hacer.

El reflejo: sospecha primero del estado del contexto

Cuando la salida empeore, repasa esta lista antes de tocar el modelo.

1. ¿Entra en bucle, se obsesiona, vuelve a preguntar, se desvía o parece cansado? Degradación del contexto. Limpia: empieza de nuevo entre tareas no relacionadas. Retrocede: vuelve al punto anterior al camino equivocado. O compacta: reescribe la sesión de forma más concisa si sigues con el mismo problema. Elige según la situación.
2. ¿Obedeció una regla mientras incumplía otra o alternó entre dos comportamientos opuestos? Instrucciones contradictorias, normalmente dos archivos de contexto que discrepan. Un archivo de proyecto dice una cosa, uno global dice lo contrario, el agente elige uno y nunca te dice que tuvo que elegir. No aparece ningún error. Encuentra las dos reglas y elimina o reescribe una.
3. ¿Se equivoca con seguridad sobre tus detalles o inventa una ruta, una cifra o un hecho? Falta de contexto. Añade lo que falta, en el prompt o en un archivo, en lugar de discutir con la suposición. Discutir añade tokens y deja abierto el hueco.
4. ¿Falla de la misma manera en una sesión nueva con el contexto correcto cargado? Solo entonces es un límite real del modelo, la respuesta menos frecuente y la última a la que recurres. Divide la tarea hasta que quepa o encarga el paso difícil a una persona o a una herramienta real.

Una señal permite saltarse gran parte de esto. Si corriges al agente más de dos veces por el mismo problema en una sesión, el contexto ya está contaminado con enfoques fallidos, así que cada corrección añade ruido a algo que ya tiene demasiado. Deja de discutir. Limpia o retrocede.

RecuerdaUn agente que empeora casi nunca es un modelo más tonto. Es un contexto más sucio. Los operadores que avanzan más no son los que tienen el mejor modelo, sino los que pueden identificar el estado del contexto en diez segundos y aplicar la solución adecuada.

La prueba A/B controlada

Todo eso es una hipótesis hasta que reproduces el fallo a propósito. La prueba A/B convierte «parecía peor» en evidencia y es el entregable con el que se evalúa este módulo.

Envía esto a tu agente:

Ayúdame a ejecutar una prueba A/B controlada sobre un fallo de un agente.

Esta es la entrada que produjo el mal resultado:
[pega la entrada exacta, sin editar]

Así sería un resultado correcto:
[una frase que alguien que no estuvo aquí pueda comprobar]

Esta es la única variable que quiero cambiar:
[por ejemplo, eliminar la salida desactualizada de una herramienta / cargar el archivo que falta / empezar una sesión limpia]

Haz esto:
1. Reformula mi comprobación de finalización como una condición que una persona ajena pueda evaluar con sí o no. Si
   no se puede comprobar, dilo y reescríbela antes de continuar.
2. Confirma que estoy cambiando exactamente una variable. Si nombré más de una, sepáralas
   en pruebas distintas e indícame cuál ejecutar primero.
3. Ejecuta el caso A con la entrada original y después el caso B con el único cambio.
4. Dame una tabla: caso, valor de la variable, resultado de la comprobación de finalización y la
   línea de evidencia de cada salida que lo determina.
5. Nombra la única acción siguiente. No recomiendes un modelo ni una ventana más grandes.

// O hazlo por tu cuenta

A mano es más lento y enseña más, así que hazlo manualmente al menos una vez.

1. Guarda la entrada original en un archivo, sin editar. No una descripción: la entrada.
2. Escribe un resultado esperado antes de ejecutar nada, formulado para que otra persona pueda evaluarlo con sí o no.
3. Cambia una variable. Una. Con dos cambios no aprendes nada sobre ninguno.
4. Ejecuta ambos casos.
5. Guarda ambas salidas y los registros que te dé tu arnés.
6. Compara con la comprobación de finalización del paso dos, no con la impresión que te den las salidas.
7. Anota la siguiente acción, incluso cuando sea «ningún cambio, la diferencia era ruido».

El paso dos es el que la gente se salta, y saltárselo convierte una prueba en una impresión. Una comprobación de finalización inventada después de ver la salida siempre se cumplirá con ella.

No cambies de modelo por reflejo. Un cambio de modelo cambia el tokenizador, los datos de entrenamiento, la fecha de corte, el muestreo predeterminado y las reglas del sistema que el arnés pone a su alrededor, todo a la vez. Son cinco variables, no una, y el resultado no te dice nada que puedas reutilizar.

Una salvedad antes de medir. Los mecanismos descritos aquí se cumplen en los modelos actuales. Los límites concretos, no. Los tamaños de ventana, los nombres de modelos, el muestreo predeterminado y los nombres de comandos de sesión cambian al ritmo de los proveedores, probablemente antes de que termines este curso. Así que registra qué arnés, qué modelo y qué fecha hay detrás de cualquier cifra que anotes. Tu arnés y el proveedor de tu modelo publican cada uno una página de límites vigentes. Cuando cualquiera de ellas discrepe con algo de aquí, prevalece su documentación.

El prompt: diagnóstico de fallos

Este prompt convierte el reflejo en una rutina. Pegas una sesión real que salió mal y hace que el agente clasifique el fallo en exactamente una de las cuatro causas, cite las evidencias de tu transcripción y nombre una única acción correctiva. Prohíbe «un modelo más grande» y «una ventana más grande» como respuestas.

Ten preparada una cosa primero. Una sesión real en la que tu agente entró en bucle, ignoró una instrucción, se desvió o perdió el hilo. Nada hipotético. El diagnóstico solo es honesto cuando la evidencia es real. Pega también el archivo de contexto que estaba cargado entonces, porque las contradicciones que contiene son una causa raíz habitual e invisible si solo se ve la transcripción.

El prompt completo está en prompt-4-failure-diagnosis.md. Ejecútalo en tu arnés, lee la clasificación y contrástala con tu intuición. Cuando las dos discrepen, decide la transcripción.

Después de este módulo

Abre lessons.md, el archivo que empezaste en el Módulo 1, y añade una entrada de señales de fallo: el síntoma que viste, la causa que identificó el diagnóstico y la solución que funcionó, con el formato Síntoma → Causa → Solución. Añade una línea a tu índice MEMORY.md que apunte a él. En la parte de pago, desarrollarás esa semilla hasta convertirla en un mapa completo de síntomas y soluciones que tendrás abierto mientras trabajas.

Ese es el final de la parte gratis. Hiciste el cambio, configuraste tu arnés y tu primer archivo de contexto, aprendiste qué es realmente el bucle, convertiste el arnés en tu base de operaciones y ahora puedes diagnosticar tus problemas en lugar de culpar al modelo. Ya puedes conducir.

Pero ya has sentido el techo. Cada sesión sigue empezando de cero. Tu agente lo olvida todo en cuanto lo cierras, así que vuelves a darle el mismo contexto, explicas las mismas reglas y ves llegar la misma desviación con puntualidad.

Eso no es una limitación del modelo. Es un sistema que falta, y es lo primero que construye la parte de pago.

Siguiente: Módulo 5: memoria: archivos, no vectores.

// prompt

Diagnóstico de fallos

<task>
Diagnostica por qué salió mal esta sesión del agente y nombra la ÚNICA acción correctiva. No propongas un modelo más grande ni una ventana de contexto más grande como solución. Clasifica antes de recetar.
</task>

<what_happened>
[Pega la sesión en la que el agente empeoró. Incluye la instrucción u objetivo original y la parte de la transcripción en la que entró en bucle, ignoró una instrucción, repitió un enfoque fallido, se contradijo o afirmó estar confundido, cansado o haber terminado cuando no era así. Pega suficiente texto para que las evidencias estén ahí y no solo en tu resumen.]
</what_happened>

<my_context_files>
[Opcional, pero una señal importante: pega el CLAUDE.md o el archivo de instrucciones que se cargó para esta sesión. Las contradicciones aquí son una causa raíz habitual.]
</my_context_files>

<session_length>
[¿Cuánto tiempo llevaba aproximadamente esta sesión y cuántas tareas no relacionadas habías hecho en ella antes de que esto saliera mal? «Sesión nueva, primera tarea» frente a «dos horas, cuarta tarea distinta» cambia el diagnóstico.]
</session_length>

<classification_rules>
Clasifica el fallo en exactamente UNA de estas cuatro categorías. Si parecen encajar dos, elige la que más respalden las EVIDENCIAS e indica qué evidencia habría cambiado tu respuesta.

1. DEGRADACIÓN DEL CONTEXTO: deterioro de la relación señal-ruido de una sesión que duró demasiado o hizo demasiadas cosas. Señales: el agente entra en bucle, insiste en un enfoque que ya falló, vuelve a preguntar algo que ya se le dijo, se desvía de la tarea o imita fatiga («déjame descansar», «me estoy confundiendo»). La ventana NO tiene que estar llena. La degradación reduce la calidad antes de que se llene la ventana.

2. INSTRUCCIONES CONTRADICTORIAS: dos reglas entran en conflicto y el agente lo resolvió mal en silencio, sin ningún error. Señales: la salida obedece una regla mientras incumple otra, o el comportamiento alterna entre dos direcciones válidas pero opuestas. Es habitual cuando dos archivos de contexto (por ejemplo, uno de proyecto y uno global) dicen cosas contrarias.

3. FALTA DE CONTEXTO: el agente nunca tuvo un dato, archivo o restricción que necesitaba, así que rellenó el hueco con una suposición plausible. Señales: una afirmación segura que es sencillamente incorrecta sobre tus detalles, una ruta de archivo o API inventada, o un valor predeterminado razonable aplicado donde necesitabas una regla específica.

4. LÍMITE REAL DEL MODELO: la tarea supera de verdad lo que el modelo puede hacer en una pasada, independientemente del estado del contexto. Señales: falla de la MISMA manera incluso en una sesión nueva y limpia con todo el contexto correcto cargado. Esta es la respuesta menos frecuente. No recurras a ella primero.
</classification_rules>

<instructions>
1. Indica la clasificación: una de las cuatro anteriores.
2. Cita las evidencias concretas de <what_happened> que la respaldan. Cita las líneas reales, no una paráfrasis.
3. Si consideraste una segunda clasificación, dilo e indica qué inclinó la balanza.
4. Nombra la ÚNICA acción correctiva, y solo una:
   - DEGRADACIÓN DEL CONTEXTO → limpiar (entre tareas no relacionadas), retroceder (hasta antes del camino equivocado) o compactar (para seguir con el mismo problema recuperando señal). Indica cuál de las tres y por qué.
   - INSTRUCCIONES CONTRADICTORIAS → nombra las dos reglas exactas que chocan y cuál eliminar o reescribir en el archivo de contexto.
   - FALTA DE CONTEXTO → nombra el dato, archivo o restricción exacto que se debe añadir y dónde debe estar (el prompt, un archivo de contexto o uno de memoria).
   - LÍMITE REAL DEL MODELO → indica cómo dividir la tarea para que cada parte quepa o qué encargar a una persona o herramienta. Solo después de descartar las otras tres.
5. Añade una línea: la entrada de síntoma y solución que debo guardar, con el formato «Síntoma: ... → Causa: ... → Solución: ...».
</instructions>

<output_format>
Clasificación: [una de las cuatro]
Evidencia: [líneas citadas de la transcripción]
Segunda hipótesis (si la hay): [la segunda opción y qué me haría cambiar de opinión]
Acción correctiva: [la única solución, concreta]
Guarda esto: Síntoma: ... → Causa: ... → Solución: ...
</output_format>

<final_check>
Antes de responder: ¿recurriste a «un modelo más grande» o «una ventana más grande»? Si es así, descarta la respuesta y vuelve a clasificar. Casi nunca son la solución. El primer sospechoso es el estado del contexto, no la inteligencia del modelo.
</final_check>

Usa la documentación vigente de tu arnés, la aplicación en la que se ejecuta tu agente, para la detección de archivos, los permisos, la invocación, el acceso a herramientas y el comportamiento de aprobación. Registra el arnés, la versión, la fecha y el evento o comando exacto que probaste. Un ejemplo de un proveedor no es un contrato universal. No envíes, gastes, elimines, publiques ni cambies producción durante este laboratorio, salvo que la compuerta del módulo indique explícitamente que una persona debe aprobar una acción reversible sobre los archivos de prueba.

<task>
Diagnostica un fallo reproducible de la IA. No cambies de modelo hasta que las evidencias respalden esa elección.
</task>

<case>
Tarea: [tarea]
Resultado esperado: [condición comprobable]
Resultado observado: [fallo]
Arnés, proveedor, identificador, versión, fecha: [registro]
</case>

<instructions>
Comprueba en este orden:
1. Falta de contexto.
2. Instrucciones contradictorias.
3. Degradación del contexto.
4. Fecha de corte del conocimiento.
5. Fundamentación mediante recuperación o herramientas.
6. Salida estructurada o validación.
7. Temperatura o esfuerzo de razonamiento.
8. No determinismo.
9. Límite real del modelo, el proveedor o la herramienta.

Diseña una prueba A/B que cambie una variable.
No afirmes tener certeza sin evidencias.
</instructions>

<output_format>
Devuelve una tabla con:
Hipótesis | Evidencias a favor | Evidencias en contra | Prueba | Resultado | Siguiente acción

Después devuelve las entradas, las salidas y la comprobación de finalización guardadas de la prueba A/B.
</output_format>

Si tu arnés es diferente, sigue su documentación vigente. Registra el arnés, la versión y la fecha.

compuerta de dominio

• ▸Reproduje un fallo con una prueba A/B controlada
• ▸Registré evidencias antes de cambiar de modelo o proveedor