Lo que realmente leen los agentes de código: archivos de instrucciones, no tu documentación (2026)

Los archivos de instrucciones son la superficie de documentación dominante

Desglosado, el 60.5% se divide en dos categorías. Los archivos de instrucciones de los agentes son "el tipo de documento más utilizado (1,074 eventos, 35.4%)" y "se encuentran entre los archivos que se modifican con más frecuencia en las pull requests de los agentes". Las notas de trabajo de los agentes (planes, directorios thoughts/, registros de verificación) representan el 25.1%.

Frente a eso, las referencias de API obtienen 40 eventos, el 1.3% de las interacciones con la documentación. El propio resumen del artículo sobre esta brecha: los archivos de instrucciones reciben aproximadamente 27 veces más interacciones que las referencias de API.

La recomendación que extraen los autores es estrecha y práctica: "Para los proyectos que asignan recursos de documentación limitados para dar soporte a los colaboradores agentes, esta diferencia sugiere priorizar la corrección y claridad de los archivos de instrucciones". No "deja de escribir documentación de API"; estas sirven a humanos y herramientas que este estudio no observó. Simplemente, si estás decidiendo a qué dedicar una hora en beneficio de los agentes, AGENTS.md es donde está el tráfico.

Los agentes no siguen tus enlaces

Este punto socava silenciosamente el consejo que dan casi todas las herramientas. "Las lecturas de documentación suelen ir seguidas de más lecturas (probabilidad de transición de 0.270), mientras que la acción de seguir referencias (Follow-reference) no se ha registrado en absoluto".

Que no se haya registrado en absoluto significa cero casos observados de un agente navegando por una referencia de un documento a otro. La conclusión de los autores es cuidadosamente cautelosa: "Este patrón motiva el estudio de documentos autocontenidos con una estructura recuperable localmente, en lugar de asumir que los agentes navegan por una documentación ricamente interconectada. Sin embargo, esto no establece que la higiene de los enlaces no tenga consecuencias en el comportamiento".

Vale la pena reflexionar sobre esto si tus archivos de instrucciones son principalmente punteros. "Consulta docs/architecture.md para ver el razonamiento" puede ser una frase bien estructurada sobre la que nada actúa.

Consultar la documentación está desacoplado de editar el código

Aquí el artículo es escrupuloso con su propia incertidumbre, y el resumen honesto es que el acoplamiento no está resuelto en lugar de estar ausente. La probabilidad de transición adyacente de una lectura de documentación a una edición de código es de 0.002. El lift no ajustado de tres eventos es de 1.05, esencialmente nada. Un modelo ajustado por etapas lo sitúa por encima de la unidad, en un OR de 1.33 [1.09, 1.62]. La creación de documentación va en sentido contrario: elevada sin ajustar con un lift de 1.67, pero "su intervalo ajustado incluye la unidad". Como dicen los autores, "Ninguna de las conexiones es consistente en todas las especificaciones".

Así que los agentes leen, y luego principalmente razonan o vuelven a leer. La transición más fuerte dentro del lóbulo de consulta es una lectura de vuelta a sí misma con 0.270 (IC 0.232–0.307); su movimiento de salida más fuerte es hacia el razonamiento con 0.245 (IC 0.205–0.295).

Nadie valida contra la documentación, y consultarla se correlaciona con menos pruebas

"No se observó ninguna secuencia de validación explícita basada en la documentación, y la consulta se asocia con menos pruebas inmediatas (lift de 0.23, IC de clúster 0.08–0.45; OR ajustado de 0.39 [0.25, 0.60])". En otro lugar, de forma rotunda: "cero eventos de validación".

Esa es una correlación en datos observacionales, no una afirmación causal, y los autores no hacen ninguna. Pero significa que la idea popular de que la documentación debe escribirse para que un agente pueda verificar su trabajo contra ella describe algo que no ocurrió aquí en absoluto.

Los agentes leen la documentación porque deciden hacerlo, no porque estén atascados

La consulta es autoiniciada el 70.2% de las veces y motivada por fallos solo el 7.5%; la documentación retroalimenta el lóbulo de consulta en solo el 5.4% de los episodios de fallo. Y la documentación sigue al código en lugar de precederlo: "entre las pull requests de múltiples commits que cambian ambos, el código se toca primero 4.7 [veces] más a menudo que la documentación".

La propia explicación de los autores es la parte interesante

Al encontrar un bucle que no coincide con cómo la literatura describe a los desarrolladores humanos, ofrecen dos mecanismos candidatos y se niegan a elegir:

"Los agentes pueden externalizar el razonamiento a archivos porque sus ventanas de contexto son limitadas, lo que convierte a la documentación en una forma de memoria de trabajo en lugar de una referencia; la prominencia de los planes y los directorios thoughts/ es consistente con esta posibilidad. Alternativamente, pueden no validar contra la prosa porque se invoca directamente un oráculo más barato, la suite de pruebas. En cualquier caso, no observamos que la prosa funcionara como una especificación".

Esa única hipótesis replantea todo el 60.5%: una gran parte de lo que los agentes "leen" pueden ser notas que ellos mismos escribieron diez minutos antes, porque no tenían otro lugar donde ponerlas. Lo que produce un problema para el que nadie tiene herramientas. "Los planes, los directorios thoughts/ y los registros de verificación se acumulan en los repositorios como artefactos duraderos. Las herramientas de higiene de repositorios, las listas de verificación de revisión de código y las métricas de calidad de la documentación actualmente no tienen categoría para ellos".

Definir bien los límites importa más que el titular, y la sección de limitaciones de este propio artículo es inusualmente directa.

El 60.5% es una proporción de las interacciones con la documentación, no de todo lo que leen los agentes. El denominador es 3,033 interacciones con la documentación de un total de 94,813 eventos de desarrollo. No es "el 60.5% de lo que lee un agente". Cualquiera que lo cite como una proporción de la actividad total del agente ha cambiado la afirmación.

Una cuarta parte de esa cifra es explícitamente provisional. Esta es la advertencia que la mayoría de los resúmenes de segunda mano omiten, y los autores la ponen por escrito: "La categoría agent_working_note (el 25.1% de los eventos de documentación y uno de nuestros hallazgos principales) se basa en la clasificación por modelo de lenguaje de 500 rutas ambiguas (98.4% de los eventos ambiguos), con 27 rutas que recurren a reglas de palabras clave. No se ha realizado ninguna validación humana de estas etiquetas... Hasta entonces, la proporción precisa de esta categoría debe tratarse como provisional". Añaden que el hallazgo cualitativo es más sólido que el número: los documentos de trabajo creados por agentes son "una clase grande y no categorizada previamente", visible en las rutas sin procesar, independientemente del porcentaje exacto.

Las tasas absolutas son límites inferiores. "La documentación se identifica por la ruta del archivo. Las docstrings, los comentarios en línea y la prosa incrustada en los archivos fuente son invisibles para nuestro instrumento". Los proyectos que favorecen la documentación dentro del código están subrepresentados, y los autores así lo indican.

No se midió por qué los agentes leen las cosas. "El propósito no se mide... por diseño, no analizamos las razones de los agentes para leer documentos específicos". El estudio informa sobre el desencadenante, el tipo de interacción y el resultado, no sobre la intención.

Es observacional, por lo que nada aquí dice que cambiar tus documentos cambie el comportamiento. Sobre la aplicabilidad (actionability) específicamente: "estos análisis no proporcionan evidencia de comportamiento consistente para el acoplamiento, y nuestro diseño observacional no puede mostrar que mejorar la aplicabilidad cambie el comportamiento".

Los autores rechazan la comparación más citable que tenían a su disposición. "Rechazamos explícitamente concluir que la recuperación basada en documentación sea más efectiva, a pesar de tener la estimación puntual más alta (63.6%). Con resultados observables para solo 11 episodios, el intervalo abarca del 35.4% al 84.8% y se superpone con cada alternativa". Ese es un equipo de investigación que deja un buen titular fuera de la mesa, y por eso vale la pena confiar en el resto.

Y se sitúa junto a trabajos que apuntan en otras direcciones. Otros estudios de 2026 midieron el efecto sobre el rendimiento de los archivos de contexto y lo encontraron débil o negativo; una línea separada midió las ganancias de la recuperación curada que escalan con la capacidad del modelo, el terreno en cuánta memoria deberías darle a un agente de IA. Este artículo no mide ninguna de las dos cosas; mide el comportamiento. Reconciliar ambos es un trabajo abierto, y un artículo de dos días antes argumenta que nuestra disciplina de medición no está lista para ello, analizado en ¿realmente mejora el rendimiento la memoria de los agentes?.

MemoryLake no formó parte de este estudio. Nada aquí evalúa una capa de memoria, la nuestra ni la de nadie.

"Los agentes ignoran tus archivos de instrucciones". Todo lo contrario de lo que descubrió. Los archivos de instrucciones son la superficie de documentación más leída por un amplio margen. Lo que es débil es el vínculo entre la lectura y la siguiente acción, una afirmación diferente, y la distinción que hemos trazado antes en por qué los agentes ignoran los archivos de instrucciones que escribiste: cargar no es seguir. Este artículo lo agudiza. Cargan, se leen mucho y, aun así, la lectura no determina de manera confiable el comportamiento.

"Así que la documentación no importa". El artículo dice que dos afirmaciones específicas carecen de respaldo conductual en este corpus: la aplicabilidad y la verificabilidad. No dice que la documentación sea inútil, y recomienda explícitamente invertir en la corrección de los archivos de instrucciones.

"Los agentes leen los documentos cuando se atascan". 7.5% motivado por fallos. La creencia que la distribución de desencadenantes contradice más directamente.

"La interconexión de enlaces no sirve para nada". Seguir referencias (Follow-reference) no se registró en estas trazas, y los autores se niegan a concluir que la higiene de los enlaces no tenga consecuencias. Esas son afirmaciones diferentes.

"Esto demuestra que los agentes necesitan un sistema de memoria". No demuestra nada de eso. Observa que los agentes escriben archivos que se asemejan a la memoria de trabajo y ofrece eso como una de las dos explicaciones candidatas para un patrón de comportamiento.

Si la hipótesis de la memoria de trabajo es correcta, entonces una parte de esos directorios thoughts/ y archivos de planes es un agente gestionando la memoria con la única herramienta que tiene: tu repositorio de git. Nada en tu proceso de revisión tiene una categoría para esos archivos. De ello se deduce lo siguiente.

Audita lo que se está acumulando. Busca en tu repositorio archivos de planes, directorios thoughts/ y registros de verificación creados por agentes. Decide, por directorio, si cada uno es un artefacto duradero o un borrador. La mayoría de los equipos descubren que han estado confirmando (committing) ambos sin darse cuenta.

Invierte la hora del archivo de instrucciones donde está el tráfico. La corrección y la claridad allí rinden más que el mismo esfuerzo en una referencia de API que un agente abre el 1.3% de las veces. Y dado que no se registró la acción de seguir referencias (Follow-reference), prefiere las declaraciones autocontenidas a los punteros para cualquier cosa que deba aplicarse.

Separa el direccionamiento del recuerdo. Un archivo de instrucciones está siempre activo y limitado por cada herramienta que lo lee, por lo que el conocimiento duradero (decisiones, restricciones, enfoques rechazados) es lo primero que se descarta. Luego, un agente lo reconstruye escribiendo un archivo de plan.

Esto último es para lo que sirve MemoryLake: memoria en forma de entradas que puedes leer, corregir y eliminar, consultadas cuando son relevantes en lugar de confirmadas en tu repositorio como un efecto secundario. La configuración consta de tres pasos.

Paso 1: Crea una clave de API

Inicia sesión en MemoryLake y crea una clave de API. Una sola credencial para todas las herramientas que conectes.

Paso 2: Sube tus primeras memorias

Entradas cortas, una afirmación cada una. Escribe el material que actualmente termina en un archivo de plan o en ninguna parte:

Decisiones con la restricción que las forzó. La categoría que un archivo de instrucciones establece como una regla y de la cual descarta la razón.

Enfoques ya rechazados aquí, y por qué. Los rechazos escritos son lo que evita que una nueva sesión vuelva a deducirlos, y volver a deducir es exactamente el trabajo que registran esos archivos thoughts/.

Hechos del entorno que nada anuncia. La prueba que solo falla en CI, el límite de velocidad no documentado, el requisito de orden entre dos migraciones.

Correcciones que has dado más de una vez. Si una persona tuvo que decirlo dos veces, pertenece a un lugar recuperable en lugar de a una conversación que ya terminó.

Paso 3: Conecta tu IA y tus agentes

Conecta las herramientas que utilizas. Se puede acceder a MemoryLake a través de MCP y de una API, por lo que los agentes nativos de MCP (entre ellos Claude Code, Codex y OpenClaw) se conectan apuntando al servidor MCP, mientras que otros asistentes leen la misma memoria a través de la API. Lo que recuperas no infla el archivo de instrucciones siempre activo y no termina en tu historial de commits.

Tres límites honestos, y el primero es el punto de este artículo. MemoryLake no formó parte de este estudio y este artículo no es evidencia de que una capa de memoria cambie el comportamiento de los agentes; el diseño es observacional y los autores son explícitos en que no puede mostrar que mejorar la documentación cambie lo que hacen los agentes. Solo contiene lo que tú o tus agentes escriban en ella. Y no limpia tu repositorio: auditar los archivos de planes que un agente ya ha confirmado es un trabajo manual.

Los archivos de instrucciones pasan a ser documentación de primera clase. Son la superficie más leída y, en la mayoría de los repositorios, reciben menos revisión que un README.

Las notas creadas por agentes se convierten en una categoría de revisión. En este momento no tienen ninguna: no hay herramientas de higiene, ni líneas en las listas de verificación, ni métricas de obsolescencia.

Los punteros dejan de ser un sustituto del contenido. No se registró la acción de seguir referencias (Follow-reference). Si una restricción importa, exprésala donde se necesita.

La documentación deja de ser tu plan de recuperación ante fallos. Los agentes la consultan de forma proactiva, no cuando están atascados, por lo que se parece más a una orientación que a un manual, y debería redactarse de esa manera.

Dedica tu mejor hora al archivo de instrucciones. Es el tipo de documento más leído en el corpus por un factor de aproximadamente 27 sobre las referencias de API.

Haz que cada declaración sea autocontenida. No se observó navegación por referencias. Asume que el lector se detiene en el archivo que abrió.

Dale un hogar y un ciclo de vida a las notas de trabajo de los agentes. Decide qué es duradero, qué es borrador y qué nunca debería haberse confirmado.

No confíes en la documentación como una superficie de verificación. Se observaron cero eventos de validación. Las pruebas son el oráculo al que realmente recurren los agentes.

Mantén el razonamiento fuera de los archivos siempre activos (cada herramienta los limita y el razonamiento es lo primero que se recorta, el problema analizado en por qué RAG no es memoria) y consolida las notas dispersas en algo consultable, la estructura de convertir los documentos del proyecto en memoria de IA.

Trata los hallazgos de comportamiento de un solo corpus como provisionales. Dos conjuntos de datos, documentación identificada por ruta, una categoría de notas de trabajo que los autores etiquetan como no validada. Útil, no definitivo.

¿Qué leen realmente los agentes de código? Según la evidencia de 557 sesiones y 33,097 pull requests: de manera abrumadora, los archivos escritos para ellos. Los archivos de instrucciones de los agentes y las notas de trabajo de los agentes representan el 60.5% de las interacciones con la documentación, la documentación técnica clásica el 10.6% y las referencias de API el 1.3%.

Pero la secuencia importa más que la proporción. Los agentes consultan la documentación por iniciativa propia en lugar de cuando están atascados, dan vueltas entre la lectura y el razonamiento en lugar de pasar al código, nunca navegan por una referencia a otro documento y nunca se les observó validar su trabajo contra la prosa. La propia interpretación de los autores es que una buena parte de esto puede no ser en absoluto una búsqueda de referencias, sino que las ventanas de contexto limitadas empujan a los agentes a externalizar el razonamiento en archivos, "lo que convierte a la documentación en una forma de memoria de trabajo en lugar de una referencia".

Si eso es correcto, la conclusión práctica no es "escribe mejor documentación". Es que tu repositorio se ha convertido silenciosamente en el bloc de notas de un agente, sin ningún proceso de revisión que lo sepa. Invierte en el archivo de instrucciones, porque ahí es donde están las lecturas. Haz que las declaraciones sean autocontenidas, porque nada sigue tus enlaces. Y dale al conocimiento duradero (decisiones, restricciones, enfoques ya descartados) un hogar que no sea un archivo siempre activo con un límite de bytes o un directorio thoughts/ que nadie revisa.