Agent Mentor Learn
Ingeniería de contexto: gastar una atención finita donde más rinde · Lección 3 de 6

Lección 3: Recuperación justo a tiempo: dejar que el agente busque su propio contexto

Objetivos de aprendizaje:

  • Usar el presupuesto de atención para ponerle precio al costo oculto de la precarga, y decidir si un material dado pertenece al contexto inicial
  • Describir cómo funciona la recuperación justo a tiempo: identificadores ligeros, metadatos como señal, contexto relevante descubierto de forma progresiva mediante la exploración
  • Dibujar la estrategia híbrida de un agente concreto: qué se precarga y qué se queda atrás como identificador para traerlo en tiempo de ejecución

Requisitos: Leíste las Lecciones 1 y 2, y tienes a mano el bucle del arnés del curso 7 de esta serie, «Fundamentos del arnés de agente: bucles y control» | Anterior: Lección 2 << | Siguiente: Lección 4 >>

Primero, resiste el impulso de meterlo todo

Digamos que estás construyendo un agente de preguntas y respuestas para una base de código: 200 archivos fuente en el repo, y los usuarios preguntan cosas como «dónde está definida esta función» o «qué se rompe si cambio esta configuración». La jugada obvia es leer los 200 archivos y pegarlos en el contexto inicial: las ventanas de contexto ahora son grandes, va a caber.

Cabe. Eso no quiere decir que corresponda. La Lección 1 cubrió por qué: los modelos analizan grandes volúmenes de contexto echando mano de un «presupuesto de atención», y "Every new token introduced depletes this budget by some amount."1 (cada token nuevo que se introduce agota ese presupuesto en cierta medida). La aritmética solo empeora a medida que avanzas: "as the number of tokens in the context window increases, the model's ability to accurately recall information from that context decreases."1 (a medida que aumenta el número de tokens en la ventana de contexto, disminuye la capacidad del modelo de recordar con precisión información de ese contexto). Lo que salva es que esto es una pendiente y no un escalón: "some models exhibit more gentle degradation than others, this characteristic emerges across all models," (aunque algunos modelos exhiben una degradación más suave que otros, esta característica emerge en todos los modelos) y juntos estos factores "create a performance gradient rather than a hard cliff."1 (crean un gradiente de rendimiento en vez de un acantilado abrupto). Lo que trae de vuelta la conclusión de la Lección 1, que vale la pena repetir aquí: "context, therefore, must be treated as a finite resource with diminishing marginal returns."1 (el contexto, por lo tanto, debe tratarse como un recurso finito con rendimientos marginales decrecientes).

De vuelta a esos 200 archivos. Un usuario hace una pregunta específica, y quizá dos o tres archivos son de verdad relevantes; los cien y pico mil tokens que cargan los otros 197 no son decorado inofensivo. Compiten por la atención con el contenido que importa, del mismo presupuesto. Peor todavía, el agente se ejecuta en un bucle, y "An agent running in a loop generates more and more data that could be relevant for the next turn of inference."1 (un agente que se ejecuta en un bucle genera cada vez más datos que podrían ser relevantes para el siguiente turno de inferencia). Si el contexto inicial ya está lleno en siete octavos, el bucle choca contra el muro después de un puñado de turnos.

Así que la pregunta pasa a ser: ¿cuándo pones el material directamente frente al modelo, y cuándo simplemente le dices dónde vive el material y dejas que vaya a buscarlo? De eso trata esta lección entera.

Las dos estrategias, lado a lado

Empecemos por enunciar cada una sin rodeos.

Precarga: antes de que empiece la inferencia, todo lo que pudiera necesitarse va al contexto inicial. El modelo lo ve todo en el turno uno y nunca tiene que recuperar nada.

Recuperación justo a tiempo: el contexto inicial no contiene material fuente, solo identificadores ligeros; el enfoque es "maintain lightweight identifiers (file paths, stored queries, web links, etc.)"1 (mantener identificadores ligeros: rutas de archivo, consultas guardadas, enlaces web, etcétera) y dejar que el agente cargue el contenido mediante herramientas en tiempo de ejecución, según se necesite.

PrecargaRecuperación justo a tiempo
Contexto inicialGrandePequeño
Cuándo llega el materialFrente al modelo en el turno 1Cuesta primero de uno a varios turnos de llamada a herramientas
A dónde van los tokensSobre todo a «podría servir»A «se necesita ahora mismo, seguro»
Modo de fallo típicoLa atención se diluye; el contenido clave se ahogaLa recuperación divaga y gira en vacío, quemando turnos y presupuesto

Piensa en cómo trabajas tú en realidad: no te memorizaste la base de código. Lo que llevas encima es «la lógica de autenticación vive en el directorio auth», «el parseo de configuración probablemente está en config.js»: un índice que apunta al contenido, y abres el archivo cuando necesitas el detalle. La recuperación justo a tiempo le entrega ese estilo de trabajo al agente.

Pero mira otra vez la última celda de esa tabla: la recuperación no es gratis. Cada búsqueda justo a tiempo es una ida y vuelta completa de llamada a herramienta: el modelo emite la llamada, el arnés la ejecuta, el resultado vuelve, el modelo razona de nuevo. En el curso 7 de esta serie, «Fundamentos del arnés de agente: bucles y control», le instalaste a tu arnés dos válvulas, máximo de turnos y tope de presupuesto; la recuperación gasta exactamente lo que gobiernan esas dos válvulas. Así que «siempre justo a tiempo» tampoco es la respuesta. Es una cuenta que hay que calcular, y el marco de disyuntivas que viene más adelante en esta lección hace la matemática.

Cómo funciona en realidad la recuperación justo a tiempo

Tres cosas la hacen andar: un conjunto de identificadores (para que el modelo sepa qué existe y más o menos dónde), unas cuantas herramientas de recuperación y un bucle que permita varios turnos de exploración. Puestas juntas, esto "allows agents to incrementally discover relevant context through exploration."1 (permite que los agentes descubran de forma incremental el contexto relevante mediante la exploración).

Esta es la parte que se subestima: los metadatos de los identificadores son en sí mismos señal. Los nombres de archivo y la estructura de directorios anuncian para qué sirve el contenido y qué tan relevante es probable que sea.1 No hace falta que abras tests/refund.test.js para saber qué hay adentro; un directorio legacy/ sin tocar hace dos años probablemente no sea el lugar por donde empezar. El artículo de Anthropic sobre su sistema de investigación multiagente pone la maniobra de fondo con nitidez: "The essence of search is compression: distilling insights from a vast corpus."2 (la esencia de la búsqueda es la compresión: destilar hallazgos de un corpus enorme). Cada paso de la recuperación justo a tiempo —listar un directorio, buscar una palabra clave, elegir un archivo— realiza esa compresión, estrechando «una franja ancha de tal vez relevante» hasta «el pedacito que de verdad tengo que leer».

Bajemos al código. Dale a ese agente de preguntas y respuestas sobre la base de código tres herramientas; las tres implementaciones son cortas:

Después escribe las definiciones de herramientas al estándar de la Lección 2: "self-contained," "extremely clear with respect to their intended use," con "minimal overlap in functionality":1 (autocontenidas, extremadamente claras respecto de su uso previsto, con superposición mínima de funcionalidad).

El prompt del sistema lleva solo las partes estables: el trabajo, el requisito de citar, las convenciones de comportamiento para la recuperación. Fíjate en que no aparece ni una línea de contenido de archivo:

Conecta esto a un repo pequeño de comercio electrónico, pregunta «¿dónde se calcula el monto de reembolso del pedido?», y una ejecución típica se ve así. (El contenido del repo es ilustrativo; la forma de cada llamada y el formato de cada retorno los fijan las implementaciones de arriba. El cuerpo del archivo del turno 3 es demasiado largo para imprimirlo, así que lo reemplaza un paréntesis de una línea).

Turno 1  list_files({ path: "." })      →  README.md         src/         tests/Turno 2  grep({ pattern: "Refund", path: "src" })      →  src/payments/refund.js:12:export function calculateRefundAmount(order, policy) {         src/orders/service.js:6:import { calculateRefundAmount } from "../payments/refund.js";         src/orders/service.js:88:  const amount = calculateRefundAmount(order, policy);Turno 3  read_file({ path: "src/payments/refund.js" })      →  (60 líneas en este archivo; devuelto completo)Turno 4  El modelo deja de llamar herramientas y responde directamente:         «El monto de reembolso se calcula en calculateRefundAmount en         src/payments/refund.js:12; el módulo de pedidos lo llama desde         src/orders/service.js:88.»

Mira lo que pasó entre los turnos 2 y 3. Grep devolvió tres líneas coincidentes, y el modelo no leyó los dos archivos. Del contenido de las líneas dedujo que la definición está en refund.js mientras que service.js es apenas quien la importa y la llama, así que abrió exactamente un archivo. Eso son los metadatos haciéndole al modelo su primera pasada de filtrado: "the metadata of these references provides a mechanism to efficiently refine behavior."1 (los metadatos de estas referencias proveen un mecanismo para refinar el comportamiento de manera eficiente). A lo largo de toda la trayectoria, lo que entró al contexto fue un listado de directorio, tres líneas de salida de grep y un archivo de 60 líneas, no 200 archivos.

Hay dos detalles más que premian una segunda mirada. El primero es el truncado incorporado en dos de las implementaciones: grep devuelve como máximo 50 líneas, read_file como máximo 400. La Lección 2 señaló que las herramientas deberían estar "returning information that is token efficient"1 (devolviendo información que sea eficiente en tokens): las herramientas de recuperación son las proveedoras del contexto, y el bucle solo sobrevive si las proveedoras le ponen tope a sus envíos. El segundo es el caso de fallo: si grep sigue saliendo vacío, el modelo puede buscar una y otra vez con palabras clave distintas. Ese es precisamente el escenario que la detección de giro en vacío y la válvula de presupuesto del curso del arnés existen para atrapar: explorar es bueno, explorar sin límite no.

Lo híbrido es el caso normal

Podrías esperar que la conclusión sea «gana la recuperación justo a tiempo». No lo es. Los sistemas reales rara vez se sientan en alguno de los dos polos; la forma común es un híbrido: "retrieving some data up front for speed, and pursuing further autonomous exploration at its discretion."1 (recuperar algunos datos por adelantado por velocidad, y llevar adelante más exploración autónoma a discreción).

Claude Code, que usas todos los días, es un ejemplo vivo: "CLAUDE.md files are naively dropped into context up front, while primitives like glob and grep" (los archivos CLAUDE.md se sueltan sin más en el contexto por adelantado, mientras que primitivas como glob y grep) sostienen la exploración justo a tiempo en tiempo de ejecución.1 La documentación oficial lo describe con llaneza: "CLAUDE.md is a special file that Claude reads at the start of every conversation."3 (CLAUDE.md es un archivo especial que Claude lee al inicio de cada conversación). Como se carga absolutamente cada vez, la documentación aconseja guardar ahí solo material que aplique de forma amplia y preguntarse de cada línea: "Would removing this cause Claude to make mistakes?"3 («¿quitar esto haría que Claude cometa errores?»). Si la respuesta es no, esa línea debería irse. La documentación pone la consecuencia sin rodeos: "Bloated CLAUDE.md files cause Claude to ignore your actual instructions!"3 (¡los archivos CLAUDE.md inflados hacen que Claude ignore tus instrucciones reales!).

Las Skills toman una tercera vía: "Claude loads them on demand without bloating every conversation."3 (Claude las carga bajo demanda sin inflar cada conversación). Pon esas tres en fila y te queda un retrato en niveles de una estrategia híbrida:

  • CLAUDE.md: estable, vinculante en cada turno → precargado al inicio;
  • Skills: capacidad especializada empaquetada, usada solo para tareas específicas → cargadas bajo demanda;
  • La base de código en sí: enorme, y cada vez solo se necesita una astilla → explorada justo a tiempo mediante glob y grep.

Cuando diseñas tu propio agente, estás dibujando una versión de ese mismo retrato: qué material se sienta en «la ranura de CLAUDE.md» y cuál en «la ranura de la base de código».

Un marco de disyuntivas que puedes aplicar de inmediato

Para cada material candidato, hazte dos preguntas:

  1. ¿Es estable? ¿El contenido se queda quieto con el tiempo, independiente de cualquier pregunta en particular?
  2. ¿Se usa en cada turno, o casi en cada turno?

Dos síes → precargar. Casos típicos: estándares de codificación, restricciones centrales del negocio, las reglas de conducta del agente, la estructura del directorio de primer nivel. Un material así suele ser pequeño también: si algo anunciado como «se necesita en cada turno» resulta ser enorme, empieza por dudar de que de verdad se necesite en cada turno.

Cualquier no → dejar un identificador y recuperar justo a tiempo. Casos típicos: el código fuente completo de un módulo (necesario solo para preguntas sobre ese módulo), tickets históricos (consultados solo al perseguir un fallo específico), un documento de diseño largo (abierto solo al alinear un enfoque).

Después pon el costo de la recuperación en la balanza y revisa el resultado una vez más: cada búsqueda agrega una ida y vuelta, agrega latencia, gasta presupuesto. Así que no empujes con terquedad hacia la recuperación un material pequeño y de uso frecuente: cambiar 600 palabras de espacio de precarga por un turno extra de list_files en cada sesión es un mal negocio. En el sentido contrario, precargar un script de 2000 líneas que probablemente ni salga a colación es puro quemar presupuesto de atención.1

La documentación de Claude Code pone lo que está en juego en una línea: "The context window is the most important resource to manage."3 (la ventana de contexto es el recurso más importante que hay que gestionar). La precarga y la recuperación justo a tiempo no son doctrinas rivales. Son las dos manos con las que gestionas ese recurso.

Esta lección se salta RAG, a propósito

Di «recuperación» y mucha gente salta directo a bases vectoriales, embeddings, pipelines de RAG. Esta lección deliberadamente no toca nada de eso: el README del curso traza la frontera, y «recuperación justo a tiempo» aquí quiere decir algo más llano: un agente que tiene herramientas de sistema de archivos y de búsqueda, y trae contenido bajo demanda.

Eso no es pereza pedagógica. Las rutas de archivo vienen con jerarquía y semántica de nombres de regalo, los resultados de grep son precisos y explicables, y el par ya alcanza para sostener un bucle completo de descubrir de forma incremental el contexto relevante mediante la exploración.1 La guía de Anthropic sobre construir agentes ofrece un sentido de la proporción que hace juego: "you should consider adding complexity only when it demonstrably improves outcomes."4 (habría que considerar añadir complejidad solo cuando mejora demostrablemente los resultados). Fíjate en el verbo: considerar. Es una postura de sopesar, no una prohibición. Para un agente de preguntas y respuestas sobre una base de código, recorrer el camino más simple (sistema de archivos más grep) hasta poder medir dónde se queda corto encaja mejor con esa postura que levantar recuperación vectorial el primer día.

Un hilo que dejamos colgando: por más disciplinada que sea tu recuperación justo a tiempo, un agente moliendo una tarea larga sigue acumulando resultados de herramientas turno tras turno,1 y la ventana de contexto se arrastra hacia su techo igual. En ese punto, ser bueno para «tomar menos» deja de alcanzar: también hay que ser bueno para tirar cosas y para anotar cosas. Eso es la Lección 4.

Resumen

  • «Cabe» no es una razón para precargar: cada token nuevo agota el presupuesto de atención, y a medida que crece el conteo de tokens declina el recuerdo preciso del modelo desde el contexto, un gradiente de rendimiento en vez de un acantilado abrupto; el contexto hay que gestionarlo como un recurso finito con rendimientos marginales decrecientes1
  • Cómo funciona la recuperación justo a tiempo: el contexto conserva solo identificadores ligeros (rutas de archivo, consultas guardadas, enlaces web), y las herramientas cargan el contenido bajo demanda en tiempo de ejecución; los metadatos de los identificadores —nombres de archivo, estructura de directorios— señalan relevancia por sí solos, lo que permite que los agentes descubran de forma incremental el contexto relevante mediante la exploración1
  • La recuperación no es gratis: cada búsqueda es una ida y vuelta de llamada a herramienta, que gasta latencia más los turnos y el presupuesto que gobiernan las válvulas de control del curso del arnés
  • Lo híbrido es el caso normal: recuperar algunos datos por adelantado por velocidad, y dejar que el modelo lleve adelante más exploración autónoma a discreción1. Claude Code es la referencia servida: CLAUDE.md soltado entero al inicio, las Skills cargadas bajo demanda, la base de código explorada sobre la marcha mediante glob y grep1 3
  • El marco son dos preguntas: ¿estable? ¿se necesita en cada turno? Dos síes quieren decir precargar, si no, dejar un identificador; no fuerces a la recuperación el material pequeño y frecuente, ni fuerces a la precarga el material grande y raro
  • «Recuperación justo a tiempo» en esta lección quiere decir traer bajo demanda mediante herramientas de sistema de archivos y de búsqueda, sin base vectorial de por medio; antes de traer maquinaria de recuperación más pesada, ten presente ese sentido de la proporción: considera añadir complejidad solo cuando mejora demostrablemente los resultados4

>> Lección 4: Compactación y notas: gestión de contexto para tareas largas

Footnotes

  1. Effective context engineering for AI agents — Anthropic Engineering — https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20

  2. How we built our multi-agent research system — Anthropic Engineering — https://www.anthropic.com/engineering/multi-agent-research-system

  3. Best practices for Claude Code — Claude Code Docs — https://code.claude.com/docs/en/best-practices 2 3 4 5 6

  4. Building Effective AI Agents — Anthropic Engineering — https://www.anthropic.com/engineering/building-effective-agents 2

Ejercicios

01

Estás diseñando el contexto de un agente interno de preguntas y respuestas para operaciones de guardia, y hay cinco materiales candidatos sobre la mesa:

Nivel 1: Ordenar un inventario de contexto
  1. El manual de guardia (unas 500 palabras: las líneas duras que toda respuesta debe respetar, como nunca entregar contraseñas de bases de datos de producción);
  2. Los 800 tickets históricos de incidentes (cada uno de unos cientos a unos miles de palabras);
  3. La estructura de primer nivel del catálogo de servicios (40 nombres de servicio más una línea de responsabilidad cada uno, unas 600 palabras);
  4. El script de despliegue completo de un servicio (unas 2000 líneas, relevante solo para preguntas de despliegue);
  5. Una tabla de correspondencia de palabras clave de alerta comunes a consultas de búsqueda de tickets (unas 30 líneas).

Con el marco de esta lección, ordena cada elemento en «precargar» o «dejar un identificador, recuperar justo a tiempo», y da una razón de una línea para cada uno.

Criterios de finalización · marcado local
02

Saca el bucle del arnés que escribiste en el curso 7 de esta serie, «Fundamentos del arnés de agente: bucles y control», registra las tres herramientas de esta lección (list_files, grep, read_file), apúntalas a un repositorio real tuyo y conviértelo en un agente de preguntas y respuestas. Requisitos:

Nivel 2: Agregar herramientas de recuperación a tu arnés
  • El prompt del sistema precarga solo información estable —trabajo, requisito de citar, convenciones de recuperación— y ningún contenido de archivo;
  • Las tres descripciones de herramientas son autocontenidas y no se superponen, y sus retornos están truncados;
  • Ejecuta una pregunta real, registra la trayectoria de llamadas a herramientas y revisa si muestra descubrimiento progresivo de lo grueso a lo fino.
Criterios de finalización · marcado local