El documento de transferencia: memoria del agente entre sesiones
El 21 de marzo de 2026, mi sitio en producción servía páginas con 14 segundos de carga después de que una purga de caché expusiera un cuello de botella de rendimiento. Investigué la causa raíz a lo largo de dos sesiones, identifiqué la ruta de código lenta, redacté un plan de solución y capturé todo en un documento de transferencia.
Un documento de transferencia lleva un diagnóstico a través de los límites de la sesión para que el agente que implementa herede la comprensión corregida en lugar de volver a derivar las mismas conclusiones erróneas. A diferencia de los tickets que dicen qué hacer, las transferencias registran qué se intentó, qué estaba mal y por qué los enfoques anteriores fallaron. La transferencia de la página de mercado sobrevivió a tres correcciones durante cuatro días y guió una implementación que redujo la carga de página de 14 segundos a 108 milisegundos.
El primer borrador de esa transferencia estaba equivocado. Apuntaba a la ruta de código incorrecta. Una revisión de código detectó que las páginas lentas medidas las servía market_hub(), no _fetch_market_data() como suponía la transferencia. La transferencia fue revisada.
El segundo borrador proponía parciales HTMX innecesarios para Apple Maps y el recuento de niveles. Una revisión detectó que Apple Maps firma las URL localmente (no hay solicitud saliente que diferir) y que el recuento de niveles debería provenir de una única consulta de agregación. La transferencia fue revisada de nuevo.
El tercer borrador proponía hacer el API del clima asíncrono, pero no especificaba que el cliente HTTP síncrono existente seguiría bloqueando el bucle de eventos incluso detrás de HTMX. La transferencia fue revisada por tercera vez.
Cuatro días después, una sesión diferente leyó la transferencia revisada tres veces e implementó la solución. Austin pasó de 14 290ms a 108ms. La implementación apuntó a la ruta de código correcta, usó el enfoque de consulta correcto y omitió los parciales HTMX innecesarios. Cada corrección de las tres revisiones ya estaba incorporada.
El documento de transferencia llevó un diagnóstico a lo largo de cuatro días y múltiples sesiones. Sin él, la sesión que implementaba habría empezado desde cero, habría hecho las mismas suposiciones erróneas, habría propuesto las mismas optimizaciones innecesarias y habría necesitado las mismas correcciones. La transferencia comprimió cuatro días de investigación en un documento que el agente que implementa leyó en segundos. Esto es gestión de la ventana de contexto aplicada a un problema específico: cómo transferir un diagnóstico a través de los límites de la sesión sin perder las correcciones que lo hacen preciso.
Qué contiene una transferencia
Un documento de transferencia no es un ticket. Un ticket dice qué hacer. Una transferencia dice qué se intentó, qué se aprendió, qué estaba mal y qué hacer a continuación. La diferencia es la memoria institucional.
La transferencia de la página de mercado contenía:
El diagnóstico. Mediciones de TTFB de renderizado en frío para seis páginas de mercado, que iban desde 381ms (Tokio, mercado pequeño) hasta 14 290ms (Austin, más de 500 empresas). Las mediciones demostraron que el problema escalaba con el número de empresas, lo que apuntaba a la forma de la consulta como el cuello de botella.
Las causas raíz, priorizadas. Cuatro causas raíz ordenadas por impacto: forma de la consulta (primaria), API del clima bloqueante (secundaria), escaneo completo de la tabla en una ruta de código diferente (terciaria) y cabeceras de caché faltantes (ya parcialmente abordadas). Cada causa raíz incluía rutas de archivos, números de línea y el patrón de código específico que causaba la ralentización.
Los giros equivocados. El primer borrador apuntaba a _fetch_market_data() en lugar de market_hub(). La transferencia registró este error y la corrección, para que la sesión que implementara no volviera a derivar la misma conclusión errónea. También registró los parciales HTMX descartados y por qué se descartaron: Apple Maps no tiene solicitud saliente, el recuento de niveles pertenece a la consulta de agregación.
El plan de implementación. Cinco pasos con ejemplos de SQL, criterios de aceptación e instrucciones de verificación. Paso 1: reemplazar la paginación del lado de Python con una consulta a la base de datos. Paso 2: añadir un parcial HTMX del clima con un cliente asíncrono. Paso 3: cachear la ruta de código secundaria. Paso 4: añadir cabeceras de caché de borde. Paso 5: volver a medir las mismas seis URL.
La publicación gestión de la ventana de contexto explica por qué este nivel de especificidad importa: cada ambigüedad en la transferencia es una decisión que el agente que implementa debe volver a derivar, consumiendo presupuesto de contexto y arriesgándose a la misma conclusión errónea.
Las minas del contexto. El contexto de la plantilla compartida incluye una búsqueda autenticada del saldo de monedas en cada página, incluidas las que nunca lo renderizan. La transferencia señaló esto como una preocupación de corrección de caché: s-maxage sin las cabeceras Vary adecuadas podría servir datos de autenticación obsoletos a usuarios anónimos.
Por qué fallan los tickets
Un ticket para el mismo trabajo diría: “Las páginas de mercado son lentas. Optimiza la consulta del hub de mercado”. La sesión que implementara necesitaría:
- Descubrir qué ruta de código sirve las páginas de mercado (no es obvio sin leer el router)
- Perfilar la ruta de código para encontrar el cuello de botella
- Considerar varios enfoques de optimización
- Implementar uno
- Descubrir que el enfoque tiene un efecto secundario (corrección de caché con datos de autenticación)
- Revisar el enfoque
Los pasos 1-3 ya estaban hechos en las sesiones de investigación. La transferencia lleva ese trabajo hacia adelante. Un ticket lo descarta.
El modo de fallo no es pereza. El modo de fallo es la pérdida de contexto a través de los límites de la sesión. La sesión de un agente de IA comienza con una ventana de contexto limpia. No recuerda lo que descubrió la sesión anterior. Este es el mismo problema que aborda el contexto es arquitectura a nivel de sistema: lo que pones en la ventana de contexto determina la calidad de la salida. Un ticket proporciona un objetivo. Una transferencia proporciona un objetivo más la comprensión acumulada necesaria para alcanzarlo correctamente.
El historial de revisiones importa
El historial de revisiones de la transferencia es tan valioso como su contenido actual. La transferencia de la página de mercado registró tres revisiones con marcas de tiempo y razones:
- Capturado: 2026-03-21T17:24 (investigación original)
- Revisado: 2026-03-21T18:20 (correcciones de la revisión de código: ruta de código incorrecta, HTMX innecesario)
- Revisado: 2026-03-25T06:30 (implementación completa, corrección de consulta desplegada)
El historial de revisiones le dice a la sesión que implementa: “este diagnóstico fue cuestionado y corregido. La versión actual incorpora esas correcciones”. Una transferencia sin revisiones podría estar equivocada. Una transferencia con tres revisiones ha sido sometida a prueba de estrés.
Los giros equivocados son parte del valor. Una transferencia que dice “consideramos y rechazamos el HTMX /_map porque Apple Maps firma las URL localmente” ahorra a la sesión que implementa proponer la misma optimización, que se revise y que se rechace. La transferencia adelanta el rechazo.
Cuándo escribir una transferencia
No toda tarea necesita una transferencia. Un arreglo de bug que toma una sesión no necesita persistencia entre sesiones. Una transferencia es valiosa cuando:
La investigación es costosa. Perfilar un cuello de botella de rendimiento, rastrear una vulnerabilidad de seguridad, depurar una interacción entre múltiples sistemas. Si la investigación tomó un esfuerzo significativo, la transferencia preserva ese esfuerzo.
La implementación ocurrirá en una sesión diferente. Si terminas la investigación hoy pero implementarás mañana, la transferencia cubre la brecha. Sin ella, la sesión de mañana empieza desde cero.
El diagnóstico no es obvio. Si la solución correcta requiere entender por qué tres alternativas aparentemente razonables están equivocadas, la transferencia captura esa comprensión. El sistema de contexto compuesto explica cómo las transferencias encajan en la acumulación más amplia del conocimiento del proyecto. Un ticket que dice “arregla la consulta” no explica por qué la consulta necesita una corrección específica.
Varias personas (o agentes) podrían trabajar en ello. La transferencia es un documento de comprensión compartida. Cualquier sesión que la lea hereda el contexto completo de la investigación.
Las transferencias como contexto compuesto
Una transferencia es un depósito en el sistema de contexto compuesto. Cada transferencia captura el tiempo de diagnóstico y lo convierte en un artefacto reutilizable. La sesión que implementa retira el diagnóstico a un costo casi nulo.
Con el tiempo, las transferencias se acumulan en un historial de investigación. La transferencia de la página de mercado hace referencia al incidente de purga de caché, las mediciones de nightcheck, la guarda destructiva de API y el sistema de revisión de código. Cada uno de estos es en sí mismo un producto de sesiones anteriores. La transferencia los conecta en una narrativa que una nueva sesión puede seguir.
La transferencia no reemplaza la comprensión. La sesión que implementa todavía necesita leer el código, escribir la solución y verificar el resultado. La transferencia reemplaza el redescubrimiento. La sesión no necesita descubrir lo que ya se sabe. La arquitectura del agente Ralph usa las transferencias como el mecanismo principal de persistencia entre sesiones para su bucle de ejecución nocturno. El hub de ingeniería de IA documenta cómo las transferencias encajan en la infraestructura más amplia de hooks, skills y sistemas de memoria que hacen que el desarrollo asistido por agentes se componga con el tiempo.
Preguntas frecuentes
¿Qué tan larga debe ser una transferencia?
Lo suficientemente larga para capturar el diagnóstico, los giros equivocados y el plan de implementación. Lo suficientemente corta para que un agente pueda leerla en una sola carga de contexto. La transferencia de la página de mercado tenía 103 líneas. La mayoría de las transferencias tienen entre 50 y 150 líneas.
¿Dónde almacenas las transferencias?
En el directorio de memoria del proyecto: ~/.claude/projects/{project}/memory/handoff-{topic}.md. El sistema de memoria carga los archivos relevantes según las descripciones del frontmatter, por lo que las transferencias son descubribles por sesiones futuras sin referencia explícita.
¿Las transferencias reemplazan a la documentación?
No. La documentación describe cómo funciona el sistema. Una transferencia describe qué se aprendió sobre un problema específico y qué hacer al respecto. La documentación es permanente. Una transferencia es consumida por la sesión que implementa y luego se convierte en contexto histórico.
¿Qué pasa si la transferencia queda desactualizada?
El campo de estado de la transferencia rastrea esto. Las transferencias activas se marcan como PLANNED o IN PROGRESS. Las transferencias completadas se marcan como RESOLVED con el hash del commit de implementación. Las transferencias desactualizadas son visibles como contexto histórico, pero no son accionables.
Fuentes
Este artículo se basa en la transferencia de rendimiento de la página de mercado (handoff-market-page-perf.md), que guió la corrección de la forma de consulta desplegada el 25 de marzo de 2026. La transferencia sobrevivió a tres ciclos de revisión durante cuatro días e informó una implementación que logró una mejora de rendimiento de 132x. Referenciado en Contexto compuesto.