Tu agente no ha leído tu carpeta
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.
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.
- AGENTS.md
- tasks/
- to-do/
- T10-webinar.md
- in-progress/
- done/
- 1Respuesta inmediata
No hace falta llamar a ninguna herramienta. Quién eres está en AGENTS.md, que se cargó antes de que preguntaras.
- 2No está en AGENTS.md: tiene que buscarlo
Primero busca y después lee el archivo. Necesita dos llamadas a herramientas para poder responder.
- 3La respuesta está en el archivo que ha abierto
Solo sabe qué es la tarea 10 porque ha ido a leerla.
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.
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 archivosse 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
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.