Mis agentes de programación olvidan el repo. Les hice un mapa

Mis agentes de programación olvidan el repositorio entre sesiones, así que les doy una ruta de lectura fija. Cuatro capas de texto plano muestran qué está vigente, qué decisiones están cerradas y dónde vive el código. Así, el agente usa menos espacio de contexto para redescubrirlo, aunque mantener el mapa actualizado sigue siendo lo más difícil.

¿Qué es un sistema de gestión de contexto? Una ruta de lectura fija

Para un cambio de facturación, mi sistema de gestión de contexto envía al agente a un índice que señala dos documentos y una carpeta. Esa ruta de lectura fija evita una búsqueda sin rumbo por todo el repositorio, de modo que el agente empieza por los archivos que probablemente sean relevantes.

La documentación de Claude Code explica por qué importa tener siempre el mismo punto de partida: «Cada sesión de Claude Code empieza con una ventana de contexto nueva» [1]. El agente empieza sin conocer el repositorio y no puede llevar lo aprendido a la siguiente sesión. La continuidad tiene que venir de información que pueda volver a encontrar.

El mapa no intenta almacenar todo lo que el agente podría necesitar. Un archivo de instrucciones que se carga automáticamente señala el estado actual, las decisiones anteriores y las ubicaciones relevantes del código, mientras que el agente carga los detalles solo cuando la tarea los necesita. La primera selección importa porque se convierte en la base de todas las decisiones posteriores.

¿Cuánto cuesta una sesión en blanco? Tokens y precisión

Una sesión en blanco cuesta calidad y tokens porque el agente debe entender el sistema antes de modificarlo. Si ese aprendizaje depende de coincidencias de palabras clave, es fácil que pase por alto detalles importantes y entregue un cambio que parezca razonable, pero esté equivocado. La búsqueda también consume contexto antes de que empiece el trabajo solicitado.

Cargar más archivos no resuelve el problema por sí solo, porque el modelo no mantiene el mismo nivel de atención durante toda una ventana de contexto larga. Chroma Research probó 18 modelos y observó que el rendimiento bajaba a medida que aumentaba la entrada, incluso en tareas que los mismos modelos resolvían bien con un prompt corto [2].

Los contextos largos fallan de varias formas, no solo cuando se quedan sin espacio. Drew Breunig explica que los errores iniciales pueden afectar al razonamiento posterior, que las acciones anteriores distraen al modelo y que distintas partes de la entrada pueden contradecirse. También cita un estudio de Databricks en el que Llama 3.1 405B empezó a perder precisión alrededor de los 32.000 tokens; los agentes perdían eficacia después de los 100.000 tokens incluso en modelos con ventanas de un millón [3].

El equipo de ingeniería de Anthropic describe la misma limitación como un presupuesto de atención [4]. En la práctica, cada token dedicado a entender el repositorio deja menos atención para el cambio solicitado.

Las cifras de mi repositorio principal hacen inevitable esa elección. Sus 418 archivos markdown contienen unos 7 MB de texto, y leerlos todos requeriría entre 5,7 y 8,75 veces una ventana de contexto de 200.000 tokens, según el método de estimación. El agente tiene que leer una parte, así que uso un orden documentado en vez de dejar que las primeras coincidencias decidan por él.

Cuatro capas de texto plano mantienen los datos actuales por encima del historial

En cada sesión, el sistema lleva al agente por cuatro capas: reglas, estado actual, decisiones e historial opcional. Los archivos normales del repositorio hacen que todas sean fáciles de inspeccionar, revisar y actualizar, algo que para mí importa más que un sistema de búsqueda sofisticado.

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

cada sesión

• AGENTS.md reglas y orden de lectura, carga automática

apunta a

el mapa

• STATE.md estado actual, se lee primero
• INDEX.md documentos que requiere la tarea

dirige hacia

la tarea

• Documentos de área y código solo lo que toca el cambio
• decisions/ por qué funciona así
• sessions/ historial, nunca autoridad

El archivo de reglas va primero porque los agentes lo cargan automáticamente. La Agentic AI Foundation presenta AGENTS.md como un estándar abierto que utilizan más de 60.000 proyectos de código abierto [5], mientras que Claude Code lee CLAUDE.md. La documentación de Claude Code recomienda el puente que uso: convertir CLAUDE.md en un enlace simbólico a AGENTS.md y mantener el archivo compartido por debajo de 200 líneas [1].

Al principio mantenía un archivo distinto para cada herramienta, pero sus reglas fueron divergiendo. El enlace simbólico eliminó esa fuente de diferencias al dar el mismo archivo a ambas herramientas y dejarme una sola copia que actualizar.

Desde el archivo de reglas, cada sesión pasa al resumen del estado. Este muestra qué está en producción, qué sigue en curso y, sobre todo, qué no se ha verificado. La última categoría evita que el agente trate como un hecho un trabajo sin terminar o una suposición que nadie ha comprobado.

Después del resumen están las decisiones y el historial. El proyecto ADR define un registro de decisión arquitectónica como un documento sobre una decisión importante de arquitectura [6]; en mi sistema, cada registro explica tanto la decisión como su motivo. Mi repositorio acumuló 74 registros en ocho semanas y, cuando una decisión cambia, un registro nuevo sustituye al anterior en vez de reescribirlo. Los registros de sesión cumplen otra función: forman un historial al que solo se añaden entradas y que el agente puede consultar, pero nunca como fuente de la situación actual.

Un solo orden de autoridad resuelve las respuestas contradictorias

Esas capas solo sirven si el agente sabe resolver los conflictos entre ellas. Por eso, todos los puntos de entrada al repositorio indican el mismo orden de autoridad: el código prevalece sobre los registros de decisiones, estos sobre el resumen y el resumen sobre el historial. Cuando una búsqueda encuentra cinco respuestas escritas en momentos distintos, el agente puede seguir la fuente de mayor rango y actualizar o señalar las demás.

Mantener el historial fuera de la ruta de lectura normal tiene un efecto práctico importante. Los registros de sesión representan el 73 % de todos los bytes de documentación del repositorio, así que excluirlos reduce la estimación de leerlo todo de 8,75 ventanas de contexto a unas 2,3. La documentación actual sigue siendo considerable, pero al agente le resulta mucho más fácil recorrerla.

¿Cómo mantengo actualizados los archivos de contexto? Los cambio junto con el código

Trato la documentación como parte del cambio de código. Cuando el código modifica un dato de la arquitectura, el mismo commit debe actualizar el documento correspondiente en vez de dejarlo para una limpieza posterior. El archivo de instrucciones indica esta regla al principio y la repite en la comprobación final del agente, cuando resulta más difícil pasarla por alto.

En mi repositorio, los agentes siguieron esa comprobación con más constancia que las personas. Después de ampliar la regla a la documentación para usuarios, la proporción de commits de UI que actualizaban los documentos correspondientes subió del 12,3 % al 31,9 %. Un 31,9 % está lejos de ser un cumplimiento fiable, pero multiplica por 2,6 el resultado anterior, y la mayoría de los fallos vino de cambios que ningún agente controló de principio a fin.

Para la información que cambia entre sesiones, uso una segunda regla: antes de detenerse, el agente escribe un registro breve y actualiza el resumen. Pasar a otra tarea activa la misma rutina. Sin ese momento explícito, las actualizaciones que parecen fáciles de hacer más tarde también son fáciles de olvidar.

Por qué dejé de usar embeddings y servidores MCP de memoria

Dejé de usar ambos porque recuperar información no era el problema. Los sistemas encontraban datos relevantes, pero no podían determinar de forma fiable si seguían vigentes. Mi servidor MCP de memoria y el índice vectorial devolvían a menudo el tema correcto de un mes anterior, porque un embedding creado antes de un refactor no sabe que la arquitectura ha cambiado.

Cada solución añadía otra fuente de información que debía mantener, lo que recreaba el problema que intentaba resolver. Varios frameworks de memoria de código abierto sumaban otra preocupación: su implementación no siempre coincidía con el comportamiento descrito en el README. Cuando tuve que verificar tanto la vigencia de los datos como la implementación, dejé de evaluarlos. Los agentes alojados plantean la misma pregunta sobre qué persiste entre sesiones, algo que trato en qué guarda la Agents API de OpenAI y qué asume el harness de Codex.

Anthropic recomienda mantener en el contexto identificadores ligeros, como rutas de archivos y consultas, y cargar los detalles solo cuando el agente los necesita [4]. Los archivos de texto encajan bien con ese método porque se pueden buscar, comparar y revisar en el mismo pull request que el código que describen. Un revisor puede detectar un archivo markdown antiguo; un índice de embeddings desactualizado es mucho más difícil de inspeccionar.

¿Qué costó el sistema? Menos lectura, más mantenimiento

El sistema mantuvo la carga inicial automática en el 0,22 % de la documentación de mi repositorio, pero no mantuvo esa documentación al día. Una auditoría de julio de 2026 descubrió que el resumen había crecido 9,5 veces en 26 días y contenía un aviso obsoleto.

El repositorio es un monorepo de producción con unas 277.000 líneas de TypeScript que utilizan tres herramientas de agentes distintas. La estructura cumplía su función al ofrecer a cada herramienta un punto de entrada breve y un orden de lectura coherente. La información que contenía esa estructura era mucho menos fiable. Cómo afrontan dos de los agentes de programación actuales las funcionalidades grandes es otra comparación: Claude frente a Codex en funcionalidades multiagente grandes.

de la documentación se carga al inicio

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 del resumen en 26 días

9,5×

de 75 líneas a 711, y nunca se redujo

Las dos primeras cifras muestran la ventaja del orden de lectura: el agente empieza con el 0,22 % de la documentación y solo carga más cuando la tarea lo exige. La tercera expone la debilidad persistente del sistema. STATE.md debía mantenerse pequeño y reescribirse en el mismo sitio, pero creció 9,5 veces en menos de un mes y, durante la auditoría, su aviso principal era incorrecto. Afirmaba que quedaban varios commits por subir aunque se habían subido días antes.

Ese aviso desactualizado no fue un fallo aislado. La documentación del esquema decía que el sistema tenía entre 20 y 25 tablas cuando el código tenía 34, y la auditoría eliminó documentación de funciones que nunca habían existido. También revisó 2.873 enlaces relativos de la documentación y encontró 82 rotos.

El patrón más claro fue la diferencia entre las instrucciones escritas y las comprobaciones automáticas. Una prueba aplica mi regla tipográfica a los textos de la interfaz, donde la auditoría no encontró infracciones, mientras que cerca de la mitad de los archivos de documentación incumplían la misma regla porque nada los comprobaba. En la práctica, el enlace simbólico y el comprobador de tipos eran los únicos mecanismos automáticos. El registro de decisión que introdujo el sistema ya indicaba este límite: «Esto reduce la tasa de fallos, pero no la elimina».

Todavía no he encontrado la cantidad adecuada de información que debe cargarse. Si los archivos iniciales contienen muy poco, el agente tiene que adivinar; si contienen demasiado, reproduzco el problema de contexto largo que midió Chroma Research [2]. El equilibrio cambia con el repositorio, así que lo ajusto cada pocas semanas en vez de dar la estructura por terminada.

En el trabajo conservo la ruta de lectura y elimino la ceremonia

En el trabajo mantengo la misma idea de una ruta de lectura, pero la presento como documentación normal del proyecto. El sistema completo pertenece a mis proyectos personales porque, según mi experiencia, muchos equipos interpretan tanta estructura específica para agentes como vibe coding en vez de documentación para desarrolladores.

En la práctica, la versión para el trabajo parece documentación convencional del proyecto: un punto de entrada claro, documentos estables para cada área y un índice que explica dónde encontrar cada cosa. Esos archivos markdown ayudan a los compañeros nuevos, y los agentes de programación también pueden seguirlos.

Las dos versiones difieren por algo más que la apariencia. En el trabajo, los equipos toman decisiones en reuniones y tableros de planificación, por lo que el repositorio no puede contener todo el historial de decisiones cuando buena parte se guarda fuera. Mis proyectos personales no tienen un registro externo equivalente; si no escribo una decisión en el repositorio, la siguiente sesión no puede encontrarla.

Cómo empezar: un archivo de reglas de menos de 200 líneas

Yo empezaría con un archivo de reglas de menos de 200 líneas que indique las convenciones del repositorio y el orden en que el agente debe leer los demás archivos. La documentación de Claude Code recomienda añadir una regla cuando el agente repite un error [1], que es también el criterio que uso para mantener el mío. Un fallo repetido significa que la ruta de lectura no explicó algo con suficiente claridad.

El resto puede llegar cuando aparezca la necesidad. Añade un archivo de estado y enlázalo desde las reglas; después, crea un índice cuando la documentación ya no quepa en una pantalla. Escribe el primer registro de decisión cuando un agente cuestione algo que ya habías cerrado y añade una carpeta de historial cuando necesites conservar trabajos anteriores sin presentarlos como información vigente. Una ruta de lectura clara también cambió lo bien que me funciona un modelo, algo que describo en mi flujo de trabajo con Opus 5, con planes claros y tareas pequeñas.

A partir de ahí, mantén los archivos con el mismo cuidado que el código. Mi artículo anterior defendía backends lo bastante pequeños para que un agente pudiera entenderlos; este sistema aplica la misma idea a la información que el código no explica por sí solo. El agente seguirá empezando cada sesión sin memoria, pero una ruta de lectura bien mantenida le permite encontrar el contexto correcto sin leer todo el repositorio.