Cada sesión de tu agente empieza en blanco. Dale un mapa

Un sistema de gestión de contexto es un conjunto de archivos de texto plano, versionados en el repo, que le da a un agente de IA recién arrancado un mapa: qué leer primero, dónde vive la verdad actual, qué decisiones están cerradas. El mío pasó por varias reconstrucciones. Esta es la versión que sobrevivió, con sus costes medidos incluidos.

¿Qué es un sistema de gestión de contexto?

Un conjunto de archivos que le dice al agente dónde mirar en lugar de obligarlo a buscar: un archivo de instrucciones que cada sesión carga sola, y que apunta a los pocos documentos que dicen qué es verdad ahora mismo, qué se decidió y por qué, y dónde vive el código de cada área.

La condición de partida que lo justifica está escrita en la propia documentación de Claude Code: “Cada sesión de Claude Code empieza con una ventana de contexto nueva” [1]. Cada sesión es un empleado nuevo con amnesia. Uno capaz, pero que nunca ha visto tu repo y nunca recordará haberlo visto.

La comparación a la que siempre vuelvo es Google Maps. Cuando pido un cambio de facturación en un repo con mapa, la primera lectura del agente lo enruta: el archivo de reglas apunta a un índice, el índice tiene una fila para facturación, la fila nombra dos documentos y una carpeta. Va allí. Sin el mapa, hace grep, abre lo que coincida y monta su imagen del sistema con los cinco archivos que casualmente vio primero.

Esa imagen es el producto. Todo lo que el agente haga después hereda de ella.

¿Qué cuesta de verdad una sesión en blanco?

Dos cosas: calidad y tokens. Un agente que se orienta a golpe de palabras clave entiende el sistema demasiado por encima y entrega cambios plausibles pero equivocados. Y la propia orientación quema la ventana de contexto antes de que empiece el trabajo real, que resulta ser la mitad más cara.

El contexto no es un recurso plano que se pueda gastar sin más. Chroma Research evaluó 18 modelos y encontró que el rendimiento se degrada a medida que crece la entrada, incluso en tareas que un prompt corto resuelve sin problema [2]. Drew Breunig catalogó cómo falla: contextos que se envenenan con errores anteriores, que distraen al modelo hacia repetir acciones pasadas o que chocan internamente; cita un estudio de Databricks donde la corrección empieza a caer hacia los 32.000 tokens con Llama 3.1 405B, y agentes degradándose pasados los 100.000 tokens en modelos con ventanas de un millón [3]. El equipo de ingeniería de Anthropic llama al presupuesto por su nombre, atención: cada token gastado en orientarse es atención que el modelo ya no tiene para el cambio que le pediste [4].

Mi repo principal hace la aritmética concreta. Su corpus de documentación son 418 archivos markdown, unos 7 MB de texto. Leerlo entero costaría entre 5,7 y 8,75 veces una ventana de contexto de 200.000 tokens, según el método de estimación. No cabe, y ninguna hoja de ruta de modelos hace que quepa con elegancia. Así que la pregunta nunca fue si el agente lee un subconjunto. Es quién elige ese subconjunto: el agente, por la suerte del grep, o yo, por diseño.

Cuatro capas y una frase

El sistema en el que aterricé son cuatro capas de texto plano. No tiene nada de ingenioso, y después de ver fallar las versiones más ingeniosas (más abajo van), considero que eso es la ventaja.

AGENTS.md            # the rules; auto-loaded (CLAUDE.md is a symlink to it)
docs/
  STATE.md           # current truth: live, in flight, not yet verified
  INDEX.md           # the router: which docs to read for which task
  decisions/         # one numbered file per decision; superseded, never edited
  sessions/          # history: what happened when, explicitly not authority

El archivo de reglas es la puerta de entrada porque es el único que los agentes cargan por sí solos. AGENTS.md es un estándar abierto usado por más de 60.000 proyectos open source [5]; Claude Code lee CLAUDE.md en su lugar, y su documentación recomienda exactamente el puente que yo uso, un symlink, junto con un objetivo de tamaño de menos de 200 líneas [1]. El mío pasó sus primeras semanas como dos archivos separados mantenidos desde dos herramientas distintas, y las reglas divergieron en silencio hasta que el symlink acabó con el problema por construcción. Un archivo, todos los agentes, deriva imposible.

La instantánea es lo que el archivo de reglas ordena leer primero en cada sesión: qué está en producción, qué está a medias y, lo más valioso en la práctica, qué no está verificado. Un agente que sabe que algo no está verificado deja de fiarse de ello. Los registros de decisiones son el patrón ADR, un archivo que captura una sola decisión y su razonamiento [6]; mi repo acumuló 74 en ocho semanas, y una decisión nueva reemplaza al archivo viejo en lugar de editarlo, así que el rastro se mantiene honesto. El historial es la pila de logs de sesión, solo de añadir, a la que se le permite ser enorme precisamente porque a nada se le permite depender de ella.

Una sola frase mantiene unidas las capas, repetida en cada puerta de entrada del repo: el código gana a los registros de decisiones, los registros ganan a la instantánea, la instantánea gana al historial. Ese orden es el sistema de verdad. Una búsqueda por palabra clave en un repo de este tamaño devuelve cinco resultados de cinco épocas; la frase le dice al agente cuál gana y que los perdedores se corrigen o se señalan, nunca se creen en silencio.

cada sesión

• AGENTS.md reglas y orden de lectura, se carga solo

apunta a

el mapa

• STATE.md verdad actual, se lee primero
• INDEX.md qué documentos para esta tarea

enruta hacia

la tarea

• Docs de área y código solo lo que toca el cambio
• decisions/ por qué es como es
• sessions/ historial, nunca autoridad

La capa de historial desterrada se gana la caja más pequeña del diagrama con un número: los logs de sesión son el 73 % de todos los bytes de documentación de ese repo. Quítalos del escenario de leerlo todo y el corpus restante baja de 8,75 ventanas de contexto a unas 2,3. Declarar el historial no autoritativo no es orden. Es lo que hace navegable el resto.

¿Qué evita que el mapa mienta?

Una regla, sobre todo: los docs son parte del cambio. Un cambio que altera un hecho de arquitectura actualiza el documento afectado en el mismo commit, no en una limpieza que nunca llega. El archivo de instrucciones del agente lo dice, y lo repite en una autocomprobación justo en el momento en que el agente decide que ha terminado, porque es cuando las instrucciones tienen su atención con fiabilidad.

Funciona mejor con máquinas de lo que jamás funcionó con humanos, por una razón poco halagadora: el agente ejecuta de verdad la comprobación prescrita. Cuando amplié la regla para cubrir también la documentación de cara al usuario, la proporción de commits que tocaban UI y actualizaban los docs correspondientes en el mismo commit pasó del 12,3 % al 31,9 %. No es cumplimiento total, pero sí 2,6 veces más, y los fallos se concentran donde ningún agente era dueño del cambio de principio a fin.

El segundo hábito es más barato: el agente escribe un log de sesión corto y refresca la instantánea antes de parar, por iniciativa propia, tratando “el usuario ya pasó a otra cosa” como señal de cierre. La documentación que espera a que alguien tenga ganas de documentar no sobrevive al contacto con un martes cualquiera.

¿Por qué no embeddings o un servidor MCP de memoria?

Porque eso fue lo que probé primero, y fallaba siempre igual: recuperar nunca fue lo difícil, lo difícil era la frescura. Un servidor MCP de memoria con un índice vectorial delante de mis repos devolvía una y otra vez el tema correcto del mes equivocado, y un embedding de la arquitectura de marzo no tiene forma de saber que el refactor del martes lo invalidó. Cada uno de esos montajes era además un segundo sistema cuya veracidad ahora me tocaba mantener, que es exactamente el fallo que el mapa existe para evitar. Y en varios de los frameworks de memoria open source que evalué, la distancia entre lo que prometía el README y lo que el código imponía era tan grande que dejé de evaluar.

La guía de context engineering de Anthropic aterrizó donde yo: mantener en contexto identificadores ligeros, rutas de archivo y consultas, y dejar que el agente cargue el detalle justo a tiempo en lugar de precomputar todo lo que podría necesitar [4]. Los archivos planos tienen la propiedad que más importa para esa estrategia: envejecen a la vista. Se les puede hacer grep y diff, y revisarlos en el mismo pull request que el código que describen. Un markdown caducado al menos se ve caducado. Un índice de embeddings caducado engaña con total confianza.

Los costes honestos, medidos

En julio de 2026 hice una auditoría de solo lectura de todo el aparato en mi repo principal, un monorepo en producción de unas 277.000 líneas de TypeScript trabajado por tres herramientas de agente distintas. La versión corta: la estructura aguanta, la disciplina de prosa no.

de los docs se autocarga

0,22 %

un archivo de reglas de 15,5 KB frente a un corpus de 7 MB

una ventana de 200K para leerlo todo

8,75×

5,7× con la estimación por palabras

crecimiento de la instantánea en 26 días

9,5×

de 75 líneas a 711, y nunca encogió

La distancia entre las dos primeras cifras es todo el diseño: el agente parte del 0,22 % y navega hacia fuera. La tercera cifra es el fallo permanente del diseño. La instantánea nació con el mandato de ser un archivo pequeño sobrescrito en el sitio, y en su lugar creció 9,5 veces en menos de un mes. Peor: en el momento de la auditoría su afirmación de cabecera era falsa. Avisaba de que había una pila de commits pendientes de push cuando el push había ocurrido días antes. El archivo que cada sesión lee primero afirmaba un dato caducado con total confianza.

No fue la única mentira que la auditoría sacó a la luz. La primera vez que sincronicé documentación contra código, el doc del esquema decía de 20 a 25 tablas donde el código tenía 34, y la pasada borró documentación de funcionalidades que nunca existieron. De 2.873 enlaces relativos en los docs, 82 estaban rotos. Y mi regla tipográfica favorita se mantiene con exactamente cero violaciones en las cadenas de UI, donde un test la impone, mientras que la rompe más o menos la mitad de los archivos de docs, donde no la impone nada. El patrón es limpio: una regla en prosa se pudre en proporción a su distancia de un test. Las únicas partes deterministas de todo el sistema son un symlink de nueve bytes y el comprobador de tipos. El registro de decisión que adoptó la estructura lo dijo desde el principio: “Esto reduce la tasa de fallo, no la elimina”.

El problema que no he resuelto es la dosis. Con muy poco en el mapa, el agente adivina; con demasiado, he reconstruido la degradación de contexto largo de aquella curva de Chroma con mis propios archivos [2]. Reajusto el equilibrio cada pocas semanas, y sospecho que lo haré siempre.

La versión light que uso en el trabajo

Todo lo anterior es mi montaje de proyectos personales, y no lo llevaría a un empleador sin cambios. En entornos profesionales, en mi experiencia, tanto aparato de agente se lee como vibe coding, y los equipos que quieren la IA como herramienta de productividad y no como autora autónoma tienen poco apetito por un repo que parece construido para la máquina. Justo o no, la percepción es parte de la ingeniería.

Así que en el trabajo uso la misma idea disfrazada de lo que también es de verdad: documentación bien hecha. Una puerta de entrada clara, docs de área con nombres estables, un índice que dice qué vive dónde. Archivos markdown que un compañero nuevo agradecería, y que de paso funcionan como mapa para el agente.

La división tiene una causa estructural, no solo óptica. En el trabajo las decisiones se toman fuera del repo, en reuniones y en el tablero, así que una capa del repo que reclamara autoridad sobre decisiones mentiría por omisión desde el primer día. En los proyectos personales no hay fuera: si una decisión no queda escrita en el repo, deja de existir en cuanto termina la sesión. La versión hardcore no es disciplina extra por gusto. Es lo que necesita un repo cuando es el único sitio donde algo puede vivir.

Por dónde empezaría

Un archivo de reglas de menos de 200 líneas que fije las convenciones y el orden de lectura; la documentación de Claude Code sugiere ampliarlo cada vez que el agente comete el mismo error dos veces [1], que es además el mejor disparador de mantenimiento que conozco. Un archivo de estado al que apunte. Un índice la semana en que los docs dejen de caber en una pantalla. Registros de decisiones la primera vez que el agente reabra algo que cerraste hace un mes, y una carpeta de historial el día que quieras un registro sin querer fiarte de él.

Después, trata el mapa como código. Cuando el agente se equivoca igual dos veces, el bug suele estar en el mapa, y el arreglo es una frase en el archivo correcto. La última pieza que escribí defendía backends lo bastante pequeños para que un agente los tenga en la cabeza. Esto es el mismo argumento, apuntado a todo lo que el código no puede decir de sí mismo. El agente nunca dejará de empezar en blanco. El mapa es lo que evita que eso salga caro.