Just-in-time y progressive disclosure

3.1El problema

Activaste el flag lab_n3 y Magallanes amaneció inflado. El catálogo de 40 tools ya lo curaste en L2. Pero queda la otra mitad del lastre.

El system prompt de Magallanes arrastra el índice completo de la biblioteca del lab. Cada documento del corpus aparece ahí: título más resumen, cientos de entradas, "por si acaso". La idea parecía prudente. Que el agente lo tenga todo delante para no quedarse corto.

Mira lo que ocurre en un run. El encargo pide tres subtemas. Magallanes toca cinco, quizá diez documentos del índice. Los demás —la inmensa mayoría— no se leen, no se citan, no se usan. Y aun así los pagas todos, en cada turno, contra el mismo attention budget que viste en N0·L1.

Eso es renta permanente por inventario muerto. El índice no caduca al final del run; vuelve a entrar en el siguiente, y en el siguiente.

En esta lección le das la vuelta al patrón. En vez de meter el catálogo entero por adelantado, dejas una referencia ligera y el agente carga lo que necesite cuando lo necesite. Y decides, con números del harness, dónde trazar esa frontera.

3.2Qué vas a poder hacer

Al terminar serás capaz de:

• Distinguir conocimiento precargado (upfront) de carga just-in-time, y explicar qué renta paga cada uno.
• Convertir el corpus precargado de Magallanes en un mapa ligero más recuperación bajo demanda, midiendo el antes y el después con count_tokens.
• Decidir la frontera upfront-vs-JIT para tres encargos distintos con una plantilla de decisión.
• Criticar dos diseños extremos —todo upfront vs JIT puro— y proponer el híbrido que la evidencia respalda.

Necesitas saber antes:

• De L2 (Curar el toolset): con qué validaste que consolidar tools no rompió la selección. Lo recuperamos en 3.3.
• De N0·L1 (El mito de la ventana infinita): por qué los tokens que "caben" no son neutrales. También en 3.3.
• El esqueleto congelado de Magallanes: el grafo de LangGraph y sus 3 tools (buscar, leer, escribir_seccion).

3.3Recupera

Antes de seguir, responde de memoria. Esto reactiva lo anterior y lo engancha con lo nuevo.

1. De L2: cuando consolidaste 12 variantes de búsqueda en una sola buscar, ¿con qué comprobaste que la selección de tool no había empeorado?
2. De N0·L1: el system prompt "cabe" en la ventana. ¿Por qué no es neutral meter el índice entero de todos modos?
3. ¿Qué tool de Magallanes ya hace, hoy, carga bajo demanda de un documento concreto?

3.4El concepto

El patrón concreto: el mapa, no el territorio

Empieza por la imagen. Un guía de montaña no memoriza cada sendero del macizo antes de salir. Lleva un mapa: una hoja ligera que dice qué valles hay y por dónde se entra. El detalle de cada sendero lo consulta al llegar.

Magallanes inflado hace lo contrario. Memoriza el macizo entero —cada documento— antes de dar un paso. Le sobra casi todo en cada salida.

Tu cambio es ese: el territorio memorizado pasa a ser un mapa ligero. Una línea por colección —qué hay y cómo descubrirlo— en vez del índice completo. Y buscar/leer recuperan el detalle al llegar.

Just-in-time: referencias ligeras, carga al vuelo

Aquí está el término. Just-in-time (JIT) es el patrón en el que el agente guarda referencias ligeras y carga los datos al contexto en tiempo de ejecución, no por adelantado.

Anthropic lo describe así (verbatim): los agentes JIT "maintain lightweight identifiers (file paths, stored queries, web links, etc.) and use these references to dynamically load data into context at runtime using tools". · fuente: corpus D.3.

La analogía del mapa funciona, con un límite. Dónde falla: un mapa de papel es estático; las referencias ligeras se generan y refinan durante el run. Por eso necesitas el segundo concepto.

Progressive disclosure: descubrir por exploración

Progressive disclosure es revelar el contexto por capas, conforme la exploración lo va pidiendo, en vez de volcarlo todo de una vez.

Anthropic, de nuevo verbatim: este patrón "allows agents to incrementally discover relevant context through exploration… file sizes suggest complexity; naming conventions hint at purpose; timestamps can be a proxy for relevance". · fuente: corpus D.3.

Lee con cuidado. La metadata de una referencia —nombre, tamaño, fecha— ya es información barata que orienta sin cargar el contenido. El nombre insinúa el propósito; el tamaño, la complejidad; la fecha, la relevancia. El agente selecciona qué abrir sin haber abierto nada.

Es común confundir JIT con progressive disclosure. La diferencia: JIT es cuándo cargas (al vuelo, no por adelantado); progressive disclosure es cómo descubres qué cargar (por capas, leyendo metadata antes que contenido). Van juntos, pero no son lo mismo.

Por qué este giro: la experiencia de Claude Code

No es teoría de pizarra. Claude Code pasó por exactamente esta decisión y cambió de bando.

Boris Cherny, de Anthropic, lo contó así (verbatim, X, ~31 ene 2026): "Early versions of Claude Code used RAG + a local vector db, but we found pretty quickly that agentic search generally works better. It is also simpler and doesn't have the same issues around security, privacy, staleness, and reliability." · fuente: corpus D.3.

Léelo despacio. Empezaron con RAG y una base vectorial —el patrón de preindexar— y la búsqueda agéntica les funcionó mejor. Enumeran problemas concretos del enfoque pre-indexado: seguridad, privacidad, datos rancios, fiabilidad. La staleness importa: un índice precargado envejece; una búsqueda al vuelo lee el estado actual.

El modelo híbrido: ni todo upfront ni todo JIT

Cuidado con leer esto como un absoluto. Claude Code no precarga cero. Usa un híbrido.

Anthropic, verbatim: "CLAUDE.md files are naively dropped into context up front, while primitives like glob and grep allow it to navigate its environment and retrieve files just-in-time". · fuente: corpus D.3.

Es decir: algo entra por adelantado por velocidad (el CLAUDE.md), y el resto se explora al vuelo con herramientas. La frontera entre lo uno y lo otro depende de la tarea. Eso es lo que vas a aprender a trazar.

Y hay un matiz anti-dogma que debes respetar. Upfront también tiene su sitio. Anthropic, sobre contextual retrieval (2024): si la base de conocimiento es menor de 200K tokens, meterla entera en el prompt con caching es legítimo; RAG se reserva para lo más grande. · fuente: corpus D.4. No siempre gana JIT. Gana la frontera razonada por tamaño y uso.

El mismo principio para catálogos de tools

Lo que acabas de ver para documentos vale igual para tools. El catálogo de 40 que curaste en L2 también se puede servir bajo demanda.

Anthropic midió un caso extremo en "Code execution with MCP". Presentó las tools como código en un filesystem, leídas on-demand. La cifra (verbatim): "This reduces the token usage from 150,000 tokens to 2,000 tokens—a time and cost saving of 98.7%". · fuente: corpus D.4. El catálogo no entra entero; el agente lee solo la definición que necesita.

Hay variantes documentadas del mismo principio:

• Una tool search_tools con niveles de detalle: el agente busca la herramienta antes de cargarla. · fuente: corpus D.4.
• MCP-Zero (arXiv:2506.01056): routing semántico jerárquico; selección correcta entre ~3.000 tools sobre 248K tokens de catálogo, con −98% de tokens en APIBank. · fuente: corpus D.4.
• Agent Skills (Anthropic, post 16 oct 2025): progressive disclosure en 3 niveles —nombres y descripciones, luego el SKILL.md completo, luego archivos suplementarios—. Los token counts por skill que circulan son mediciones de un tercero (SwirlAI sobre el repo oficial), no cifras de Anthropic. · fuente: corpus D.4.

El trade-off honesto

JIT no es magia. Tiene su factura.

Cargar al vuelo añade latencia y pasos de exploración: un turno extra para buscar antes de leer. Upfront compra velocidad —todo ya delante— al precio de la renta permanente de 3.1.

Normaliza esto: no hay regla universal. Quien te diga "siempre JIT" o "siempre precarga todo" vende dogma, no ingeniería. Hay una frontera razonada por tarea. Una colección pequeña que tocas en cada run, con caching, puede ir upfront. Un corpus enorme que rozas un poco pide JIT. La mayoría está en medio, y se decide midiendo.

Lo que NO es JIT

JIT no es vaciar el system prompt y "que el agente explore desde cero". Eso te ahorra tokens y te cuesta turnos: el agente no sabe ni qué colecciones existen, así que tantea a ciegas. Dejar un mapa ligero —saber qué hay y cómo descubrirlo— es lo que hace barata la exploración. Sin mapa, JIT degenera en búsqueda al azar.

JIT tampoco es RAG con otro nombre. RAG preindexa y recupera de un índice construido de antemano; la staleness de ese índice es justo uno de los problemas que Cherny enumera. JIT con exploración agéntica lee el estado actual del entorno al vuelo. · fuente: corpus D.3.

3.5Míralo funcionar

Vamos a des-precargar Magallanes. Sacas el índice del system prompt, dejas un mapa ligero, y mides la diferencia con count_tokens. Tres piezas: el system antes, el system después, y la auditoría que compara.

Antes de leerlo línea a línea, lee el bloque entero de corrido. Lo difícil no es ninguna línea suelta; es ver que solo cambia el system. count_tokens lo audita igual que en L1.

El antes: el índice completo precargado

Así llega Magallanes con el flag activo. El system prompt arrastra cada documento de la biblioteca.

1# system_inflado.py — el corpus entero precargado (la avería del flag lab_n3)
2# Cada documento de la biblioteca, con título y resumen, dentro del system prompt.
3SYSTEM_INFLADO = """Eres Magallanes, un agente de investigación.
4Biblioteca disponible (índice completo):
5- doc-001 · "Rutas atlánticas del s. XVI" · Resumen: análisis de las corrientes...
6- doc-002 · "Financiación de expediciones" · Resumen: contratos de la Corona...
7- doc-003 · "Tripulaciones y mortalidad"  · Resumen: registros de enrolamiento...
8# ... cientos de entradas más, una por documento del corpus ...
9- doc-487 · "Cartografía portuguesa"      · Resumen: portulanos y su precisión...
10"""

El problema no es la redacción. Es que entra entero, en cada turno, y casi ningún run toca casi ningún doc-.

El después: el mapa ligero

Ahora la versión JIT. El índice sale. Queda una línea por colección: qué hay y cómo descubrirlo. La recuperación la hacen buscar y leer.

1# system_jit.py — referencias ligeras, no el contenido
2# Una línea por COLECCIÓN: qué contiene y cómo llegar a ella. El detalle se carga al vuelo.
3SYSTEM_JIT = """Eres Magallanes, un agente de investigación.
4Biblioteca disponible (mapa de colecciones; usa `buscar` para descubrir y `leer` para cargar):
5- "rutas"        · navegación y corrientes atlánticas (~120 docs). Busca por tema o autor.
6- "financiacion" · contratos, costes y patrocinio de expediciones (~90 docs).
7- "tripulacion"  · enrolamiento, mortalidad y oficios a bordo (~110 docs).
8- "cartografia"  · portulanos, instrumentos y precisión cartográfica (~160 docs).
9Para cualquier dato concreto: `buscar(query)` devuelve doc_ids; `leer(doc_id)` carga el documento.
10"""

Tres cosas de este mapa:

• No es el vacío. Magallanes sabe qué cuatro colecciones existen, de qué van y cuántos documentos hay. Eso es la metadata barata de progressive disclosure: el tamaño insinúa volumen; el nombre, propósito. · fuente: corpus D.3.
• El detalle se carga al vuelo. buscar descubre los doc_id relevantes; leer trae el contenido. Son las tools congeladas: no inventamos nada.
• La frontera está aquí. El mapa va upfront (barato, orienta la exploración). El contenido va JIT (caro, casi nunca se usa entero).

La auditoría: medir el antes y el después

Igual que en L1, mides el coste estático con count_tokens —la cuenta de tokens del contexto antes del primer turno—. Comparas los dos system prompts con las mismas tools.

1# auditar_jit.py — coste estático antes (índice completo) vs después (mapa ligero)
2# count_tokens audita el contexto estático ANTES del primer turno (corpus F.6.d).
3import anthropic
4from system_inflado import SYSTEM_INFLADO
5from system_jit import SYSTEM_JIT
6from toolset import TOOLS_CURADAS   # las ≤12 tools que dejaste en L2
7
8client = anthropic.Anthropic()
9MODELO = "claude-opus-4-5"
10SONDA = [{"role": "user", "content": "Investiga la ruta y la financiación del encargo."}]
11
12def coste_estatico(system: str) -> int:
13    # Devuelve input_tokens del contexto fijo: system + tools, sin historial todavía.
14    # count_tokens() → CountTokensResponse con campo .input_tokens
15    r = client.messages.count_tokens(
16        model=MODELO, system=system, messages=SONDA, tools=TOOLS_CURADAS,
17    )
18    return r.input_tokens  # int — token count del contexto estático
19
20antes   = coste_estatico(SYSTEM_INFLADO)
21despues = coste_estatico(SYSTEM_JIT)
22reduccion = 1 - despues / antes
23
24print(f"antes (índice completo): {antes:>6} tokens")
25print(f"después (mapa ligero):   {despues:>6} tokens")
26print(f"reducción del system:    {reduccion:>6.0%}")

Léelo de arriba abajo. coste_estatico llama a count_tokens con un system dado y las tools ya curadas, y devuelve input_tokens. Lo corres dos veces —inflado y JIT— y comparas. La sonda (SONDA) es fija: la única variable que cambia es el system prompt.

count_tokens es la herramienta de auditoría del nivel: cuenta el contexto estático sin lanzar el run. Es la misma firma que usaste en L1 para desglosar el coste fijo del agente inflado (corpus F.6.d).

El resultado: la cuenta

La salida es una comparación directa. Estos números son ilustrativos —tu corpus dará los suyos—; lo que importa es la forma del recorte:

antes (índice completo):   8420 tokens
después (mapa ligero):      890 tokens
reducción del system:        89%

El índice pesaba miles de tokens por turno. El mapa pesa cientos. Y la capacidad de Magallanes no cambia: sigue llegando a cualquier documento vía buscar/leer. Desapareció el inventario muerto, no el acceso.

La otra mitad: el sweep de fiabilidad

Recortar tokens no basta. Falta comprobar que la fiabilidad no se cayó. Eso lo mides con un sweep corto de 2 puntos —como el de N0·L4— sobre el mismo encargo: índice completo vs mapa ligero.

Dos puntos bastan aquí. Comparas la calidad del informe en cada configuración con la misma rúbrica del harness.

1# sweep_jit.py — 2 puntos: ¿el recorte del system degrada el informe?
2from harness import sweep   # el del context-sweep de N0·L4
3
4resultados = sweep(
5    encargo=ENCARGO_FIJO,            # mismo encargo en ambos puntos
6    variantes={
7        "indice_completo": SYSTEM_INFLADO,
8        "mapa_ligero":     SYSTEM_JIT,
9    },
10    points=2,                        # un run por variante
11)
12for nombre, r in resultados.items():
13    print(f"{nombre:>16}: quality={r.quality:.1f}/5")

La salida que buscas: la calidad no baja al pasar al mapa ligero.

 indice_completo: quality=4.2/5
     mapa_ligero: quality=4.3/5

Estos números son ilustrativos. Lo que importa es la lectura: el recorte del 89% en el system no penalizó la calidad del informe. Si el mapa ligero hubiera caído a 3.0/5, el recorte no valdría —habrías ahorrado tokens perdiendo fiabilidad—. El sweep es el que da licencia al recorte.

Self-explanation

Antes de leer la respuesta, intenta tú: ¿por qué dejamos un mapa ligero en vez de vaciar el system prompt entero y "que explore"?

3.6Hazlo tú

Andamiaje decreciente: primero decides la frontera con una plantilla; luego la justificas sin ella para tu propia configuración.

Ejercicio — la frontera upfront-vs-JIT para tres encargos

Tienes la misma biblioteca de Magallanes. Te llegan tres encargos distintos. Para cada uno, decide qué va upfront y qué va JIT. Usa esta plantilla de decisión:

Los tres encargos:

1. Repetitivo sobre una colección pequeña. Magallanes redacta cada semana un resumen de la colección "financiacion" (~90 docs, pequeña). Siempre la misma colección, siempre entera.
2. Exploratorio amplio. Una pregunta abierta que puede tocar cualquiera de las cuatro colecciones, sin saber de antemano cuáles.
3. Mixto. Un informe que siempre arranca de "rutas" (fija) pero amplía con lo que aparezca en las demás según el tema.

Para cada encargo: di la frontera y justifícala con los tres criterios.

Elaborative interrogation. Antes de decidir el encargo 1: ¿por qué una colección pequeña que se usa siempre es el caso que más empuja a upfront?

Ejercicio sin plantilla — tu configuración del checkpoint

Ahora sin andamio. Para tu configuración de Magallanes del checkpoint C3, traza la frontera y justifícala con datos del harness:

1. Di qué dejas upfront (mapa ligero, qué incluye) y qué va JIT.
2. Mide el coste estático antes y después con count_tokens.
3. Corre un sweep corto de 2 puntos y comprueba que el informe no empeora.

No hay solución cerrada. La frontera correcta es la que tu sweep no penaliza y que recorta el coste estático medido.

3.7Comprueba

Sin pistas. Gate de maestría: criticar dos diseños extremos y proponer el híbrido.

Un compañero te pide validar el diseño de contexto de un Magallanes. El caso: investigar un tema abierto sobre una biblioteca de ~480 documentos. Cada run toca entre 5 y 15, distintos cada vez.

Te trae dos propuestas extremas:

• Propuesta A — todo upfront con caching. Mete el índice completo de los 480 documentos en el system prompt y cachéalo. "El caching lo hace barato."
• Propuesta B — JIT puro sin nada precargado. System prompt vacío de biblioteca. "Que explore con buscar desde cero; cero renta."

Para cada propuesta: señala qué evidencia la critica. Luego propón el híbrido y justifícalo.

3.8Conecta

Acabas de cerrar la segunda partida del coste fijo de Magallanes. En L2 curaste las 40 tools; aquí des-precargaste el corpus. Las dos partidas que en L1 disparaban el coste estático ya están atacadas.

Esto alimenta la dimensión 3 de la rúbrica C3: JIT correcto más frontera razonada por la tarea. Reducir tokens no es suficiente. La rúbrica te pide defender por qué trazaste la frontera ahí, con los criterios de 3.6: volumen, frecuencia y coste de exploración.

Pero queda trabajo. Lo que ahora entra bajo demanda son tool results, y algunos son enormes. Cada leer() que dispara el JIT mete un documento entero al historial append-only —el arrastre por turno que mediste en N0·L3—. Des-precargar el corpus no impide que un solo leer() grande infle el run.

En L4 (Domar los tool results) pones límites, paginación y clearing a esas respuestas. Y hay un eco hacia N4: explorar mucho y devolver poco —lo que el JIT insinúa— es la semilla del aislamiento.

Cierra el arco de 3.1: tenías un agente que memorizaba el macizo entero antes de salir. Ahora lleva un mapa y consulta cada sendero al llegar. Misma capacidad, una fracción de la renta.

3.9Reflexiona

Tómate un minuto. Responder esto por escrito consolida mejor que releer.

• ¿Qué aprendiste? Resume en una frase la diferencia entre just-in-time (cuándo cargas) y progressive disclosure (cómo descubres qué cargar).
• ¿Qué sigue sin estar claro? ¿Tienes claro por qué upfront todavía tiene su sitio —el matiz de contextual retrieval bajo 200K tokens—? Si no, vuelve a 3.4.
• ¿Qué harías distinto? La próxima vez que alguien diga "metámoslo todo en el prompt por si acaso", ¿qué tres criterios le pondrías delante antes de aceptarlo?

Esto requiere práctica. La intuición de dónde trazar la frontera llega midiendo fronteras con count_tokens y el sweep, no leyéndolas. En L5 integrarás esta decisión con la curación de L2 y los results de L4 en el entregable de C3.