--- title: "Tu agente no ha leído tu carpeta" description: "Abrir una carpeta en Claude Code o Codex no hace que sus archivos aparezcan en la mente del modelo. Empieza sabiendo casi nada y tiene que ir a leerlos. Eso es bueno, y convierte `AGENTS.md` en el archivo más importante que escribirás." date: 2026-10-10 language: es canonical: https://gduv.club/es/articles/agent-folder-context source: gduv.club --- Cuando alguien empieza a trabajar con un agente dentro de una carpeta, da por hecho que conoce todo lo que hay en ella. Tus notas, los archivos de tus clientes, el proceso que documentaste el mes pasado. Está todo ahí, así que seguro que lo ha leído. Pero no. Al abrir una conversación nueva, **el agente apenas sabe** qué hay en tu carpeta. Sabe que la carpeta existe y que puede mirar dentro. ## Qué tiene realmente al empezar Al recibir el primer mensaje, el modelo tiene una lista breve de cosas: - las instrucciones que la aplicación le ha dado (cómo debe comportarse y cómo usar cada herramienta), - las descripciones de las herramientas que puede utilizar, - uno de tus archivos, si lo has creado: `AGENTS.md`, - y tu mensaje. **Eso es todo**. Para encontrar cualquier otra cosa de la carpeta, tiene que buscarla: listar los archivos, hacer búsquedas y abrir los que parezcan pertinentes. Cada paso requiere una llamada a una herramienta, igual que cuando busca en la web. Lo muestro en mi taller con una carpeta que contiene 20 archivos de tareas. En una conversación nueva, pregunto de qué trata la tarea 10. No responde de inmediato. Busca en la carpeta, encuentra el archivo, lo lee y entonces contesta. Funciona, pero **ha tenido que ir a buscar la información**. | Frame | Total | What it holds | | :--- | :--- | ---: | | Tu primer mensaje | 7,625 tokens | instrucciones de la aplicación, descripciones de las herramientas, AGENTS.md, tu pregunta | | Busca en la carpeta | 7,845 tokens | instrucciones de la aplicación (cached), descripciones de las herramientas (cached), AGENTS.md (cached), tu pregunta (cached), resultado de la búsqueda | | Abre un archivo | 8,395 tokens | instrucciones de la aplicación (cached), descripciones de las herramientas (cached), AGENTS.md (cached), tu pregunta (cached), resultado de la búsqueda (cached), task-10.md | _Las cantidades son ilustrativas y varían según la aplicación. Lo importante es lo que falta: de una carpeta con 20 archivos de tareas, solo llega al modelo el que ha abierto._ ## Por qué eso es bueno Al principio resulta frustrante. Sería cómodo que el agente lo supiera todo sin más. Pero piensa en lo que costaría. Cada mensaje que envías incluye todo lo que recibe el modelo: las instrucciones de la aplicación, las descripciones de las herramientas, tus archivos y toda la conversación hasta ese momento. Si se cargara toda tu carpeta cada vez, pagarías por todo ese contenido en cada mensaje y el modelo tendría que encontrar el único párrafo pertinente entre todo lo demás. Los modelos más recientes pueden procesar mucho texto, hasta cerca de un millón de tokens en algunos casos. Pero tener más espacio no hace que todo resulte útil. El texto adicional es ruido y puede confundir al modelo, igual que te confundiría a ti. Intento que cada token incluido tenga un motivo para estar ahí. Así que el hecho de que el agente no conozca tu carpeta es lo que te permite controlarlo. Tú decides qué debe saber siempre y organizas el resto para que encuentre las cosas enseguida. ## `AGENTS.md` es tu espacio garantizado `AGENTS.md` es un archivo de texto sin formato que está en la raíz de tu carpeta. La aplicación lo lee al principio de cada conversación y lo incluye en el contexto del modelo, junto con sus propias instrucciones. Es el único lugar donde algo queda siempre presente. La prueba que suelo hacer es abrir una conversación nueva y preguntar: «¿Quién soy?». Si tu función está en `AGENTS.md`, responde enseguida, sin abrir ningún archivo. Lo mismo ocurre con una regla como «responde siempre con tres viñetas». Inclúyela ahí y la seguirá en todas sus respuestas. - **You:** ¿Quién soy? - **Agent:** Eres Alex Martin, responsable de marketing de contenidos en Northwind. Llevas el blog, la newsletter y LinkedIn de la empresa. [1] - **You:** ¿De qué trata la tarea 10? - **Tool call:** `search_files` (query: "task 10") [2] - **Tool call:** `read_file` (tasks/to-do/T10-webinar.md) - **Agent:** La tarea 10 es el seminario web para propietarios de clínicas: elegir una fecha, invitar a dos clientes como ponentes y preparar la página de inscripción. [3] . **Respuesta inmediata**: No hace falta llamar a ninguna herramienta. Quién eres está en AGENTS.md, que se cargó antes de que preguntaras. . **No está en AGENTS.md: tiene que buscarlo**: Primero busca y después lee el archivo. Necesita dos llamadas a herramientas para poder responder. . **La respuesta está en el archivo que ha abierto**: Solo sabe qué es la tarea 10 porque ha ido a leerla. _La misma conversación, dos preguntas. La respuesta a la primera está en AGENTS.md. La segunda hay que ir a buscarla._ Antes, Claude Code solo leía un archivo llamado `CLAUDE.md`. Las versiones recientes también leen `AGENTS.md`, que es el nombre que usan Codex y la mayoría de las demás herramientas, así que un mismo archivo sirve para todas. Si parece que no lo está cargando, pregúntale al agente qué instrucciones ha leído. He escrito más sobre cómo mantener un único archivo para todas las herramientas en [mantén tus repositorios independientes del entorno de ejecución](/articles/harness-agnostic-workspaces). ## Qué debe incluir y qué no Mi regla es sencilla. Si algo no resulta útil para casi todos los mensajes, no debería estar en `AGENTS.md`. Un archivo largo consume tokens en cada mensaje y esconde las reglas importantes. **En AGENTS.md** (útil para la mayoría de los mensajes) - Quién eres: tu función y tu equipo - La empresa, en dos o tres líneas - Reglas de trabajo: "di claramente cuándo no tienes seguridad", "explica cómo has obtenido una cifra" - Cómo quieres las respuestas: primero una conclusión en una línea y después los detalles - Un mapa de la carpeta - Una tabla de habilidades, con dónde encontrar cada una - Una tabla de herramientas, con cuándo usar cada una **En otros archivos** (se consultan cuando la tarea lo requiere) - La descripción completa de la empresa y los detalles de los productos - Información sobre clientes y proyectos - Cómo redactar una publicación de LinkedIn o preparar un informe para un cliente - Notas de reuniones, exportaciones y borradores - Cualquier cosa que solo necesites una vez al mes _AGENTS.md es una página. Su función es indicar qué se cumple siempre y dónde está todo lo demás._ La segunda columna no es menos importante. Simplemente, **no hace falta consultarla en cada mensaje**. `AGENTS.md` apunta a ella ("para cualquier asunto relacionado con un cliente, lee primero su `information.md`"), y el agente la abre cuando la tarea lo requiere. Así es como se consigue trabajar rápido con una carpeta grande. ## Pruébalo Abre una conversación nueva en tu carpeta y pregunta: "¿Quién soy y qué instrucciones has cargado al iniciar esta conversación?" Si la respuesta es imprecisa, es que falta `AGENTS.md` o no incluye lo importante. Pídele al agente que te ayude a redactarlo. Después, procura que **no ocupe más de una página**.