CLAUDE.md es un archivo de texto en tu repositorio con las reglas del proyecto que un agente de código como Claude Code lee al empezar cada sesión. AGENTS.md cumple el mismo papel en muchas otras herramientas. Ahí va lo que el código no dice: convenciones, comandos útiles y qué no tocar. Suele cargarse entero cada vez, así que conviene corto.
Una pregunta de la app. Elige una respuesta.
Tu archivo de instrucciones dice «corre los tests antes de terminar». ¿Qué logras?
Es una guía: el agente puede saltársela. Por eso igual revisas si hay resultados.
Son cosas distintas. El archivo dice cómo trabajar; los permisos, qué acciones están permitidas.
Si la herramienta lee ese archivo, orienta su trabajo. Ayuda mucho, pero no reemplaza mirar el resultado.
Lo que un agente de código no puede adivinar leyendo los archivos. Una convención: «los montos se guardan en centavos, como número entero; nunca con decimales». Un límite: «la carpeta de facturación electrónica la mantiene otro equipo: no la edites». Un comando que no es obvio, como el que arma la app para probarla.
Lo que sobra: lo que el agente ve solo (qué librerías usa el proyecto ya está en sus archivos), manuales largos y reglas para una tarea que se hace una vez al mes. Y nunca claves ni contraseñas: el archivo suele vivir en el repo y lo lee cualquiera que tenga acceso.
El archivo entra en la ventana de contexto antes de que escribas tu primer pedido, y se queda ahí toda la sesión. Con números de ejemplo: un CLAUDE.md de 400 líneas puede rondar los 5.000 tokens que viajan en cada sesión, se usen o no. Además, entre tantas reglas, las importantes pesan menos.
Una prueba útil para cada línea: si la borras, ¿el agente se equivocaría? Si no, sobra. Las instrucciones largas para una tarea puntual, como publicar una versión nueva, suelen quedar mejor en una skill, que se carga sólo cuando hace falta.
Lo que dice el archivo orienta al agente, pero no lo ata. En una sesión larga, con mucho texto encima, puede pasar por alto una regla que siguió al principio. Escribirla en mayúsculas o repetirla tres veces no la vuelve automática.
Si algo tiene que pasar siempre, que no dependa de su memoria: muchas herramientas permiten configurar scripts que corren solos ante un evento (en algunas se llaman hooks) y permisos que bloquean acciones. Y lo que hizo de verdad lo ves en el diff, no en el archivo de reglas.
«Lo escribo una vez y listo.» Si cambias un comando y el archivo no, el agente seguirá usando el viejo. «Todas las herramientas leen el mismo archivo.» No: cuál lee cada una depende de la herramienta y su configuración. Si tu equipo usa varias, revisa que no haya dos versiones que se contradigan: en AGENTS.md está cómo compartir uno solo.