Lección 05 — Mantené vivo el contexto entre sesiones

Le pedís a Claude Code que implemente una funcionalidad completa. Corre 30 minutos, hace la mayor parte del trabajo, pero el contexto se está agotando. Iniciás una sesión nueva para continuar y descubrís que no recuerda qué decisiones se tomaron, por qué se eligió la opción A sobre la B, qué archivos ya se modificaron ni en qué estado están las pruebas. Dedica 15 minutos a reexplorar el proyecto y puede terminar siendo inconsistente con el enfoque anterior.

Imaginate un artesano que olvida todo cada mañana al despertar. Tendría que volver a familiarizarse con toda la obra: qué pared está a medio construir, por qué se eligieron ladrillos rojos en lugar de azules, dónde llegaron las cañerías. Peor todavía, podría arrancar una ventana que ya se instaló ayer, simplemente porque no recordaba que estaba hecha.

Esta lección explica por qué los agentes “se quedan en blanco” durante tareas largas, y cómo la persistencia estructurada del estado los convierte en un artesano que lleva un diario confiable: sigue siendo amnésico, pero el diario recuerda todo.

Las ventanas de contexto no son infinitas

Esto no se resuelve con actualizaciones de modelos. Aunque las ventanas crezcan a un millón de tokens, las tareas complejas las van a agotar igual. Los agentes no solo generan código: entienden bases de código, rastrean su propio historial de decisiones, procesan salidas de herramientas y mantienen el contexto de la conversación. Toda esa información crece más rápido que la expansión de la ventana.

Hay un problema más profundo: la información que produce el agente no tiene la misma importancia. Los pasos de razonamiento intermedio contienen el por qué de las decisiones. La salida final solo contiene el qué: el código. Las estrategias de compaction suelen preservar lo segundo y perder lo primero. La sesión siguiente ve el código pero no sabe por qué está escrito así, y puede “optimizar” una decisión de diseño deliberada.

Anthropic descubrió algo importante en su investigación de agentes de larga duración: cuando los agentes perciben que el contexto se está agotando, exhiben convergencia prematura: se apuran a terminar el trabajo actual, saltean pasos de verificación o eligen una solución simple sobre la óptima. Lo llaman ansiedad de contexto.

Qué pasa cuando se rompe la continuidad

flowchart TD
    subgraph SIN["Sin artefactos de continuidad"]
        S1["Sesión 1<br/>Analiza 3 enfoques<br/>Elige el B"] --> X["Fin de sesión<br/>El razonamiento se pierde"]
        X --> S2["Sesión 2<br/>Reexplora 15 min<br/>Elige el A"]
        S2 --> S3["Sesión 3<br/>Reimplementa lo hecho"]
        S3 --> BAD["Código redundante<br/>Decisiones contradictorias<br/>Defectos ocultos"]
    end

flowchart TD
    subgraph CON["Con artefactos de continuidad"]
        T1["Sesión 1<br/>Trabaja"] --> W["Antes de cerrar:<br/>PROGRESS.md<br/>DECISIONS.md<br/>commit"]
        W --> T2["Sesión 2<br/>Lee, verifica, continúa<br/>3 min de arranque"]
        T2 --> W2["Actualiza artefactos"]
        W2 --> T3["Sesión 3..."]
        T3 --> GOOD["Trabajo acumulativo<br/>Decisiones consistentes"]
    end

Los cuatro daños concretos:

Decisiones que se revierten sin querer. La sesión anterior gastó presupuesto analizando tres enfoques y eligiendo el B. El agente de esta sesión no conoce ese análisis y puede decidir de nuevo con información incompleta.

Trabajo duplicado. El agente no está seguro de si cierto trabajo ya se completó y lo hace de nuevo. O peor: hace la mitad, descubre un conflicto con la implementación existente y tiene que rehacerlo.

Deriva de objetivos. A lo largo de varias sesiones, la dirección de implementación puede desviarse silenciosamente de los requisitos originales. Como el teléfono descompuesto: después de diez personas, “traeme un café” se convierte en “compráme una cafetera”.

Brecha de verificación. Los resultados de verificación de la sesión anterior —qué tests pasan, cuáles fallan, por qué— no se registraron. La nueva sesión tiene que reejecutar toda la verificación para entender el estado actual.

Conceptos clave

• Las ventanas de contexto son finitas: no importa el tamaño (128K, 200K, 1M), las tareas largas las van a agotar. Después hay que hacer compaction (perdiendo información) o reset (sesión nueva). Ambas pierden algo.
• Artefactos de continuidad: archivos de estado persistido que permiten a una sesión nueva retomar sin ambigüedad. Forma básica: registro de progreso + registro de verificación + próximas acciones.
• Costo de reconstrucción: el tiempo que una sesión nueva necesita para alcanzar un estado ejecutable. Un buen harness lo comprime de 15 minutos a 3.
• Deriva (drift): la brecha entre la comprensión del agente y el estado real del repositorio. Cada límite de sesión introduce deriva; sin control, se acumula.
• Ansiedad de contexto: convergencia prematura cuando el agente se acerca a los límites percibidos de contexto.
• Compaction vs reset: la compaction resume el contexto dentro de la misma sesión (conserva el qué, puede perder el por qué); el reset abre una sesión nueva reconstruyendo desde artefactos persistidos (limpio, pero depende de la completitud de los artefactos).

Un diario para el artesano amnésico

Enfoque central: tratá al agente como un ingeniero brillante con amnesia. Antes de que termine su turno, debe escribir la información crítica para que el agente del turno siguiente pueda retomar rápido.

Herramienta 1: archivo de progreso (PROGRESS.md)

# Progreso del proyecto

## Estado actual
- Último commit: abc1234 (feat: endpoint de preferencias de usuario)
- Estado de tests: 42/43 pasando (falla test_pagination_edge_case)
- Lint: limpio

## Completado
- [x] Modelo de usuario y migración de base de datos
- [x] Endpoints CRUD básicos
- [x] Integración del middleware de autenticación

## En progreso
- [ ] Paginación (90% — falla un test de caso borde)

## Problemas conocidos
- test_pagination_edge_case devuelve 500 con conjuntos de resultados vacíos
- Falta confirmar si los usuarios eliminados aparecen en los listados

## Próximos pasos
1. Corregir el bug del caso borde de paginación
2. Agregar el parámetro de query "incluir usuarios eliminados"
3. Actualizar la documentación de la API

Herramienta 2: registro de decisiones (DECISIONS.md)

No hacen falta documentos de diseño detallados: solo qué decisión, por qué y cuándo.

# Decisiones de diseño

## 2026-08-15: Redis para el caché de preferencias de usuario
- Razón: alta frecuencia de lectura (en cada llamada de API), volumen de datos chico
- Alternativa descartada: vista materializada de PostgreSQL (la alta frecuencia
  de cambios hace que el costo de mantenimiento no valga la pena)
- Restricción: TTL de caché de 5 minutos, invalidación activa en escritura

Herramienta 3: commits de git como puntos de control

Hacé commit después de completar cada unidad atómica de trabajo. Los mensajes deben explicar qué se hizo y por qué. Son snapshots de estado gratuitos y versionados automáticamente.

Herramienta 4: rutinas de entrada y salida

Especificá en AGENTS.md el fichaje de entrada y salida:

## Al iniciar sesión (fichar entrada)
1. Leer PROGRESS.md para conocer el estado actual
2. Leer DECISIONS.md para las decisiones importantes
3. Ejecutar `make check` para confirmar que el repo está consistente
4. Continuar desde la sección "Próximos pasos" de PROGRESS.md

## Antes de terminar la sesión (fichar salida)
1. Actualizar PROGRESS.md
2. Ejecutar `make check` para confirmar estado consistente
3. Commitear todo el trabajo completado

Estrategia mixta

No todas las tareas necesitan un reset de contexto. Las tareas cortas (menos de 30 minutos) pueden completarse dentro de una sesión. Las largas deben usar archivos de progreso y registros de decisiones. Criterio de decisión: si una tarea necesita más del 60% de la ventana, empezá a preparar la entrega.

Profundización en la ansiedad de contexto

La investigación de marzo de 2026 de Anthropic reveló manifestaciones específicas: en Sonnet 4.5, cuando el contexto se acerca al límite de la ventana, el agente muestra un fuerte comportamiento de convergencia prematura.

Estrategia	Ventaja	Desventaja
Compaction — resumir la conversación temprana dentro de la misma sesión	Mantiene la continuidad; el agente ve el qué	El por qué se pierde en los resúmenes; no elimina la ansiedad de contexto
Reset de contexto — sesión nueva reconstruida desde artefactos	Estado mental limpio, sin ansiedad de “se me acaba el tiempo”	Depende de la completitud de los artefactos de entrega

Dato relevante de Anthropic: para Sonnet 4.5, la ansiedad de contexto es lo suficientemente severa como para que la compaction por sí sola no alcance —el reset se vuelve un componente crítico del harness—. Para Opus 4.5, el comportamiento está muy reducido y la compaction puede gestionar el contexto sin depender de resets.

Conclusión de diseño: el harness necesita un entendimiento específico del modelo objetivo, no una plantilla de talla única.

Fuente: Anthropic — Harness design for long-running application development

Ejemplo del mundo real

Un agente fue encargado de implementar un sistema de blog con autenticación: 12 puntos de funcionalidad, estimadas 5 sesiones.

Sin diario: la sesión 1 implementó el modelo de usuario y las rutas básicas. La sesión 2 empezó sin recordar el contrato de interfaz del middleware de autenticación, dedicando ~15 minutos a inferir la intención de diseño anterior. Para la sesión 3, la deriva acumulada hizo que el agente empezara a reimplementar funcionalidades ya completadas. Para la sesión 5, el repositorio contenía mucho código redundante pero la funcionalidad central de autenticación todavía no pasaba las pruebas end-to-end.

Con diario: archivos de progreso, registros de decisiones, registros de verificación y checkpoints de git, con actualización automática al final de cada sesión.

Métrica	Sin diario	Con diario
Tiempo de reconstrucción por sesión	~15 min	~3 min (−78%)
Puntos de funcionalidad completados	7 de 12 (58%)	12 de 12 (100%)
Tasa de defectos ocultos	43%	8%

Ideas clave

• Las ventanas de contexto son un recurso finito. Las tareas largas van a abarcar sesiones, y las sesiones van a perder información.
• La solución no son ventanas más grandes: es mejor persistencia del estado.
• Tratá al agente como un ingeniero con amnesia: antes de terminar el turno, escribí qué se hizo, por qué y qué sigue.
• El costo de reconstrucción es la métrica clave. Un buen harness lleva a las sesiones nuevas a un estado ejecutable en menos de 3 minutos.
• Estrategia mixta: tareas cortas dentro de la sesión, tareas largas con artefactos estructurados.

Ejercicios

1. Medición de pérdida de continuidad: elegí una tarea que necesite al menos 3 sesiones. Sin artefactos de continuidad, registrá cuánto contexto gasta el agente al inicio de cada sesión en averiguar qué pasó. Después creá un archivo de progreso y compará.
2. Diseño de plantilla de entrega: diseñá una plantilla mínima con cuatro campos —estado del repo (commit hash), estado de ejecución (tasa de tests), bloqueadores y próximas acciones—. Dejá que una sesión nueva restaure el estado solo con esa plantilla y registrá las ambigüedades.
3. Experimento de estrategia mixta: en una tarea de 5 sesiones, compará (a) siempre sesión nueva + archivos de progreso, (b) todo lo posible en una sesión con compaction, (c) estrategia mixta. Compará tiempo de reconstrucción, completitud y consistencia de decisiones.

Lecturas adicionales

• Anthropic: Effective Harnesses for Long-Running Agents
• Anthropic: Harness design for long-running application development
• OpenAI: Harness Engineering
• Lost in the Middle: How Language Models Use Long Contexts

---

Anterior: Lección 04 — Dividí las instrucciones entre archivos · Siguiente: Lección 06 — Inicializá antes de cada sesión