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

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

Objetivos de aprendizaje:

Enunciar qué es la compactación y cómo se implementa: cuando una conversación se acerca al límite de la ventana, se le entrega el historial de mensajes al modelo para que lo resuma y luego se reinicia una ventana nueva a partir de ese resumen

Escribir la instrucción de resumen y la lista de qué conservar y qué descartar de una compactación, siguiendo la regla: preservar decisiones arquitectónicas y bugs sin resolver, descartar resultados de herramientas redundantes

Distinguir los papeles de la compactación y de las notas estructuradas, y diseñar un esquema de notas escritas sobre la marcha para un agente de tarea larga

Requisitos: Terminaste las Lecciones 1 a 3 de este curso y sabes escribir 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 3 << | Siguiente: Lección 5 >>

Una tarea que una sola ventana no aguanta

Empecemos por una escena con la que vas a toparte pronto. Tomas el arnés que escribiste a mano en el curso 7 de esta serie, «Fundamentos del arnés de agente: bucles y control», y lo apuntas a una tarea de depuración: arreglar una condición de carrera que solo aparece bajo concurrencia. El agente lee archivos, ejecuta pruebas, edita código, vuelve a ejecutar las pruebas — cuarenta y tantos turnos después la tarea sigue sin terminar, pero el historial de mensajes se ha hinchado más allá de los cien mil tokens y la ventana está a punto de llenarse.

Las cuatro válvulas de control del curso 7 (turnos máximos, presupuesto, detección de giro en vacío, la válvula de aprobación) no sirven de nada aquí. Gobiernan el «no dejes que el bucle se desboque», pero el bucle se está portando bien: la tarea misma es simplemente larga. Eso no es un accidente; es la naturaleza del bucle: "An agent running in a loop generates more and more data that could be relevant for the next turn of inference"¹ (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) — resultados de herramientas, conclusiones intermedias, intentos fallidos, todo amontonándose en el historial de mensajes.

Y la ventana no es gratis. Un modelo que analiza grandes volúmenes de contexto echa mano de un «presupuesto de atención», y "Every new token introduced depletes this budget by some amount."¹ (cada nuevo token introducido agota ese presupuesto en cierta medida). Cuantos más tokens se acumulan, peor se le da al modelo recordar con precisión: "as the number of tokens in the context window increases, the model's ability to accurately recall information from that context decreases"¹ (a medida que aumenta el número de tokens en la ventana de contexto, la capacidad del modelo de recordar con precisión información de ese contexto disminuye) — una pendiente suave hacia abajo más que un precipicio, pero cuesta abajo al fin y al cabo, así que "context, therefore, must be treated as a finite resource with diminishing marginal returns."¹ (el contexto, por tanto, debe tratarse como un recurso finito con rendimientos marginales decrecientes). La documentación de buenas prácticas de Claude Code lo dice de forma más directa — "Claude's context window fills up fast, and performance degrades as it fills," y "The context window is the most important resource to manage."² (la ventana de contexto de Claude se llena rápido y el rendimiento se degrada a medida que se llena; la ventana de contexto es el recurso más importante que hay que gestionar).

Cuando una tarea se alarga más de lo que una sola ventana aguanta, tienes dos armas: la compactación y las notas estructuradas. Esta lección trabaja las dos.

Compactación: resumir y luego abrir una ventana nueva

La compactación es exactamente lo que dice el nombre: "taking a conversation nearing the context window limit, summarizing its contents, and reinitiating a new context window."¹ (tomar una conversación que se acerca al límite de la ventana de contexto, resumir su contenido y reiniciar una ventana de contexto nueva). Fíjate en la última parte: no metes el resumen de vuelta en la conversación vieja para seguir apretujando; reinicias. La ventana vieja se abandona entera y la nueva viaja ligera, cargando solo el prompt del sistema y el resumen.

La implementación es más llana de lo que suena: es "passing the message history to the model to summarize and compress the most critical details."¹ (pasarle el historial de mensajes al modelo para que resuma y comprima los detalles más críticos). Lo que significa que la compactación es en sí misma una llamada extra al modelo. En código se ve más o menos así (formatHistory solo une el arreglo de mensajes en texto plano legible; se omite la implementación):

JAVASCRIPT

const COMPACT_INSTRUCTION = `Abajo está el registro de trabajo completo de un agente hasta ahora.
Comprímelo en un resumen de traspaso para que una sesión totalmente nueva continúe esta tarea.
El resumen debe conservar:
1. Las decisiones arquitectónicas ya tomadas y el razonamiento detrás de ellas
2. Los problemas todavía sin resolver (bugs, errores, puntos de atasco) y hasta dónde ha
   llegado la investigación
3. Los detalles clave de implementación de los cambios ya hechos (qué archivos y funciones
   cambiaron, y por qué)
Lo siguiente se puede descartar, o reducir a una conclusión de una línea:
- Resultados de herramientas redundantes (retornos crudos de leer el mismo archivo una y otra vez,
  o de repetir las mismas pruebas)
- La crónica completa de los intentos intermedios que después se descartaron
`;

async function compact(client, messages) {
  const resp = await client.messages.create({
    model: "claude-sonnet-5",
    max_tokens: 2000,
    messages: [{
      role: "user",
      content: COMPACT_INSTRUCTION + "\n\n" + formatHistory(messages),
    }],
  });
  const summary = resp.content[0].text;
  // Reiniciar: el historial de la ventana nueva es solo este resumen (el arnés deja el prompt del sistema tal cual)
  return [{
    role: "user",
    content: "Aquí tienes un resumen de traspaso del trabajo previo; continúa desde aquí:\n\n" + summary,
  }];
}

Empalmarlo en aquel bucle del curso 7 requiere una sola idea más: al inicio de cada turno, revisa el uso de tokens del historial de mensajes y, en cuanto se acerque al límite, llama a compact() y reemplaza el arreglo messages entero con el valor de retorno. Construir esto de verdad dentro del arnés — cómo fijar el umbral de disparo, qué hacer cuando la compactación falla — es el material práctico de la Lección 6; por ahora, basta con tener clara la mecánica.

El arte de la compactación: qué conservar, qué descartar

La parte difícil de la compactación no es «cómo resumir», sino «qué conservar y qué descartar». La dirección en realidad está clara: "preserves architectural decisions, unresolved bugs, and implementation details while discarding redundant tool outputs."¹ (preserva decisiones arquitectónicas, bugs sin resolver y detalles de implementación, mientras descarta resultados de herramientas redundantes).

¿Por qué esa disyuntiva? Imagina al agente «despertando» en la ventana nueva; ese resumen es toda su memoria. El costo de comprimir en la dirección equivocada es concreto: digamos que tu instrucción de resumen solo dice «resume brevemente el contenido de la conversación», y el modelo deja caer sin darle importancia que «hay una condición de carrera sin terminar en orders/service.js» — el agente despierta viendo únicamente registros marcados como «completo», así que o declara el trabajo terminado o hurga en cosas que ya arreglaste. Una compactación, y cuarenta turnos de trabajo se acaban de descarrilar.

Dale la vuelta: los resultados de herramientas redundantes es el blanco más jugoso. Un grep devuelve 200 líneas coincidentes; la señal útil ya quedó capturada en la conclusión del paso siguiente, «acotado a la función updateStatus». Las 200 líneas crudas que se quedan ahí solo queman presupuesto de atención y no le agregan casi ningún valor de decisión al siguiente movimiento.¹

Una autocomprobación práctica: después de escribir la instrucción de resumen, toma una conversación larga real y compáctala una vez; luego responde tres preguntas usando solo el resumen — «qué debería pasar a continuación», «qué decisiones están cerradas», «qué huecos siguen sin tapar». Si las tres salen limpias, las reglas de conservar y descartar de tu instrucción aprueban; si alguna se queda en blanco, vuelve y parchea esa regla de conservación.

La compactación en producción: autocompactación y /clear

La herramienta que usas a diario tiene una referencia lista. Claude Code "automatically compacts conversation history when you approach context limits, which preserves important code and decisions while freeing space"² (compacta automáticamente el historial de conversación cuando te acercas a los límites de contexto, lo que preserva código y decisiones importantes mientras libera espacio) — la misma mecánica del compact() escrito a mano de arriba, solo que productizada, con el disparo y las reglas de conservar y descartar ya resueltos.

Pero la compactación no es la única opción. Si estás cambiando a una tarea nueva sin relación con la anterior, el contexto viejo no solo es inútil: es dañino, porque "Long sessions with irrelevant context can reduce performance."² (las sesiones largas con contexto irrelevante pueden reducir el rendimiento). Llegado ese punto, la documentación dice "Run /clear between unrelated tasks to reset the context window entirely"² (ejecuta /clear entre tareas sin relación para reiniciar por completo la ventana de contexto) — sin resumir, sin preservar, un reinicio total. El razonamiento es simple: la compactación cuesta una llamada al modelo y carga con el riesgo de equivocarse al decidir qué conservar y qué descartar; para una tarea sin relación, limpiar de plano sale más barato y más limpio. La compactación sirve al «la misma tarea todavía no termina», mientras que /clear sirve al «ahora estoy haciendo otra cosa».

Esa documentación tiene además una línea que vale la pena tener a mano: "A clean session with a better prompt almost always outperforms a long session with accumulated corrections."² (una sesión limpia con un mejor prompt casi siempre supera a una sesión larga con correcciones acumuladas). Traducido: cuando el historial de una sesión es sobre todo «no, inténtalo otra vez» y «sigue mal», el valor histórico para el paso siguiente es probablemente negativo — reabrir una sesión y incorporar la lección directamente en un prompt nuevo suele ganarle a arrastrar todo ese lastre.

Notas estructuradas: escribir el estado clave fuera de la ventana

La compactación tiene una debilidad de fábrica: es reactiva. Esperas a que la ventana esté casi llena y solo entonces miras atrás y resumes, así que lo que sobrevive depende por entero del juicio de ese momento — y el juicio puede fallar. ¿Hay alguna manera de preservar la información mientras está fresca?

Sí, y es llana: "the agent regularly writes notes persisted to memory outside of the context window."¹ (el agente escribe con regularidad notas que se persisten en memoria fuera de la ventana de contexto). "Like Claude Code creating a to-do list, or your custom agent maintaining a NOTES.md file."¹ (como Claude Code creando una lista de pendientes, o tu agente propio manteniendo un archivo NOTES.md). Retoma aquella tarea inicial de la condición de carrera; un juego de notas que aprueba se ve más o menos así:

MARKDOWN

# NOTES.md — Arreglar condición de carrera del servicio de pedidos

## Decisiones tomadas
- Framework de pruebas: se cambió a vitest (decidido en el turno 3, motivo: las fixtures de prueba existentes dependen de él)

## Sin resolver
- orders/service.js updateStatus tiene una condición de carrera:
  dos peticiones concurrentes modificando el mismo pedido, la última escritura pisa a la primera
- Ya se intentó: mutex en proceso -> funciona con una sola instancia, falla en despliegue multiinstancia

## Siguiente paso
- Probar bloqueo optimista a nivel de base de datos (agregar campo version a orders)

El cableado es algo que aprendiste en el curso 7: dale al agente una herramienta de escritura de archivos y luego agrega un requisito al prompt del sistema — «cada vez que tomes una decisión importante, descubras un problema nuevo o termines una etapa, actualiza NOTES.md primero y después continúa». De ahí en adelante, el estado clave de la ventana tiene una copia de respaldo fuera de la ventana. No importa cómo se compacte o se reinicie la ventana: las notas están en disco, y lo primero que hace la ventana nueva es leerlas de vuelta.

Este truco no es exclusivo de tareas de programación. "Claude playing Pokémon demonstrates how memory transforms agent capabilities in non-coding domains."¹ (Claude jugando Pokémon demuestra cómo la memoria transforma las capacidades del agente en dominios que no son de programación). El sistema de investigación multiagente de Anthropic hace lo mismo para tareas largas: "agents summarize completed work phases and store essential information in external memory."³ (los agentes resumen las fases de trabajo completadas y guardan la información esencial en memoria externa).

División del trabajo: la compactación como red, las notas como rutina

Pon las dos armas lado a lado y la división del trabajo se aclara. La compactación es pasiva: se dispara cuando la ventana se acerca a su límite, en un momento que tú no eliges, y pierde información — lo que sobrevive depende del juicio de conservar y descartar de ese instante. Las notas son activas: escribes el estado clave en el momento en que nace, el contenido no se pierde, y el costo son unas pocas líneas de escritura a archivo cada vez. En una frase: las notas son la rutina diaria, la compactación es la red de seguridad.

Las dos no chocan; se refuerzan. Cuanto más diligentes sean tus notas, más leve es la consecuencia de que la compactación deje caer algo — si el resumen se salta un detalle, las notas todavía lo tienen. Yendo en la otra dirección, tener a la compactación como red significa que las notas no tienen que ser exhaustivas, solo cubrir las pocas categorías que «el agente debe saber al despertar».

El sentido de la proporción también importa. No toda tarea se gana esta maquinaria: la guía de Anthropic es "you should consider adding complexity only when it demonstrably improves outcomes."⁴ (habría que considerar agregar complejidad solo cuando mejora los resultados de forma demostrable). Fíjate en el verbo: considerar. Es una postura de sopesar, no una prohibición. Para una tarea que termina en diez turnos, tanto la compactación como las notas son piezas de repuesto; empieza con el bucle más simple y agrégalas cuando de verdad choques con el techo.

Dos límites finales, para que no pierdas tiempo buscando respuestas que esta lección no cubre:

La persistencia entre sesiones de los archivos de notas — cómo organizarlos, cómo recuperarlos en una sesión nueva, el mantenimiento a largo plazo — es el tema del curso 5 de esta serie, «Memoria y estado del agente». Esta lección solo se ocupa de cómo las notas aligeran la carga de la ventana dentro de una misma tarea larga.
Manejar tareas de horizonte largo tiene en realidad tres movimientos: "compaction, structured note-taking, and multi-agent architectures,"¹ (compactación, toma de notas estructurada y arquitecturas multiagente), todos apuntados a que los agentes puedan "maintain coherence, context, and goal-directed behavior over sequences of actions."¹ (mantener coherencia, contexto y comportamiento dirigido a objetivos a lo largo de secuencias de acciones). Los dos primeros ya están; el tercero — repartir la tarea entre subagentes que llevan ventanas limpias — es la Lección 5.

Resumen

Compactación = cuando una conversación se acerca al límite de la ventana, "passing the message history to the model to summarize and compress the most critical details,"¹ y luego "reinitiating a new context window"¹ a partir de ese resumen — reiniciar, no anexar de vuelta a la conversación vieja
El arte de la compactación está en la elección de qué conservar y qué descartar: "preserves architectural decisions, unresolved bugs, and implementation details while discarding redundant tool outputs";¹ comprime en la dirección equivocada y el agente despierta sin recordar qué estaba haciendo
Claude Code "automatically compacts conversation history when you approach context limits, which preserves important code and decisions"²; entre tareas sin relación se usa /clear para un reinicio total — "A clean session with a better prompt almost always outperforms a long session with accumulated corrections"²
Notas estructuradas: "the agent regularly writes notes persisted to memory outside of the context window" (lista de pendientes, NOTES.md);¹ la compactación es red de seguridad pasiva y con pérdidas, las notas son externalización activa escrita sobre la marcha
Los tres movimientos para tareas de horizonte largo son "compaction, structured note-taking, and multi-agent architectures";¹ los dos primeros ya están en mano, el tercero es la Lección 5. La persistencia de notas entre sesiones es el tema del curso 5 de esta serie, «Memoria y estado del agente»

>> Lección 5: Subagentes y aislamiento de contexto

Effective context engineering for AI agents — Anthropic Engineering — https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸ ↩⁹ ↩¹⁰ ↩¹¹ ↩¹² ↩¹³ ↩¹⁴ ↩¹⁵ ↩¹⁶ ↩¹⁷ ↩¹⁸
Best practices for Claude Code — Claude Code Docs — https://code.claude.com/docs/en/best-practices ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷
How we built our multi-agent research system — Anthropic Engineering — https://www.anthropic.com/engineering/multi-agent-research-system ↩
Building Effective AI Agents — Anthropic Engineering — https://www.anthropic.com/engineering/building-effective-agents ↩

Ejercicios

Tu agente de depuración lleva cuarenta y tantos turnos, y el historial de mensajes mezcla varias categorías: una decisión temprana de cambiarse a vitest, un bug de carrera descubierto a mitad de camino pero todavía sin arreglar, decenas de salidas repetidas de herramientas de lectura de archivos, y además los detalles clave de implementación de las dos funciones que arreglaste al final. La ventana está casi llena; el arnés está por disparar la compactación. Escribe la instrucción de resumen que le entregarías al modelo (puede ser en inglés) y, por separado, enumera fuera de la instrucción misma la «lista de conservar» y la «lista de descartar» correspondientes.

Nivel 1: Escribir la instrucción de resumen de una compactación

Criterios de finalización · marcado local

La instrucción de resumen exige explícitamente conservar: el bug de carrera sin resolver y el avance de la investigación, la decisión arquitectónica (cambiarse a vitest) y su razonamiento, los detalles clave de implementación de las funciones ya cambiadasLa instrucción de resumen exige explícitamente descartar o reducir a una conclusión de una línea: las salidas redundantes de lectura de archivos y otros retornos repetidos de herramientasLa instrucción explica que el propósito del resumen es reiniciar una ventana nueva (como contexto de apertura de una conversación nueva), no anexarse de vuelta a la conversación vieja

Alguien escribió esta función de «compactación» para el arnés y la llama cuando la ventana está casi llena:

Nivel 2: Diagnosticar la «amnesia después de compactar»

JAVASCRIPT

function compact(messages, keepLast = 10) {
  // Ventana casi llena: conserva el primer mensaje y los últimos 10, descarta el resto
  return [messages[0], ...messages.slice(-keepLast)];
}

Después de engancharla, el agente disparó la compactación en el turno 45. Entonces observaste dos síntomas: primero, en el turno 47 volvió a abrir el debate sobre «si el framework de pruebas debería ser node:test o vitest», una pregunta ya decidida en el turno 3 a favor de vitest; segundo, nunca volvió a mencionar el bug de carrera sin resolver registrado en el turno 5, y unos turnos después declaró la tarea terminada. Explica la causa de ambos síntomas y da un arreglo en dos capas.

Criterios de finalización · marcado local

Señala que este `compact()` es truncado puro, no resumen: conserva solo el primer mensaje y los últimos 10, borrando físicamente la decisión del turno 3 y el registro del bug del turno 5. Después de compactar, esas piezas de información ya no existen en el contexto, así que el agente vuelve a debatir decisiones zanjadas y no tiene manera de recordar bugs sin terminarArreglo de primera capa: reemplazar el truncado por resumen del modelo — entregarle el historial de mensajes al modelo para que lo comprima, con una instrucción que preserve explícitamente decisiones arquitectónicas, bugs sin resolver y detalles clave de implementación mientras descarta resultados de herramientas redundantes, y luego reiniciar una ventana nueva desde el resumenArreglo de segunda capa: agregar notas estructuradas — darle al agente una herramienta de escritura de archivos, exigirle que actualice un `NOTES.md` fuera de la ventana al tomar decisiones o descubrir problemas, y leer las notas después de compactar o reiniciar para recuperar el estado, de modo que el estado clave deje de depender del juicio del momento de la compactación

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

Una tarea que una sola ventana no aguanta

Compactación: resumir y luego abrir una ventana nueva

El arte de la compactación: qué conservar, qué descartar

La compactación en producción: autocompactación y /clear

Notas estructuradas: escribir el estado clave fuera de la ventana

División del trabajo: la compactación como red, las notas como rutina

Resumen

Footnotes

Ejercicios

Alguien escribió esta función de «compactación» para el arnés y la llama cuando la ventana está casi llena: