Claude Code ya lee AGENTS.md: qué cambia en tu proyecto

El 18 de septiembre Claude Code soltó en su changelog una línea que parece un detalle de nada.

La versión 2.1.277 añade soporte para AGENTS.md. Traducción: en un proyecto donde no hay ningún CLAUDE.md, Claude Code lee el AGENTS.md y tira de ahí. Y el archivo que usa se puede cambiar desde /config, en la opción "Project instructions".

Eso es todo lo que dice el anuncio. Una frase. Pero si llevas tiempo abriendo carpetas donde cada herramienta de IA te pide su propio archivo de instrucciones, esa frase te interesa más de lo que parece.

¿Qué es exactamente lo que ha cambiado?

Hasta ahora, la manera de decirle a Claude Code cómo trabajar en un proyecto era el CLAUDE.md. Ese archivo en la raíz de la carpeta donde le explicas las reglas: qué es este proyecto, cómo quieres que escriba, qué no puede tocar, dónde va cada cosa.

Es la pieza que separa un Claude Code que va dando palos de ciego de uno que se comporta como alguien que lleva meses en tu proyecto. Ya lo conté entero en cómo escribir tu CLAUDE.md.

Lo que cambia con la 2.1.277 es el plan B. Si abres una carpeta y ahí no hay CLAUDE.md pero sí hay un AGENTS.md, Claude Code no se queda a ciegas. Lee ese.

Fíjate en la condición, porque es la mitad de la noticia: en un proyecto sin CLAUDE.md. No es que ahora lea los dos. No es que los junte. Es un sustituto para cuando el primero no está.

¿Y si ya tengo mi CLAUDE.md montado?

Pues no tienes que hacer absolutamente nada.

Si tu proyecto tiene CLAUDE.md, el comportamiento es el de siempre. Ese archivo manda, tus reglas siguen ahí, y el AGENTS.md ni entra en escena. Puedes cerrar esta pestaña y seguir con tu vida.

Esto es importante decirlo porque cada vez que sale una novedad en Claude Code hay gente que entra en pánico pensando que se le va a romper el sistema que lleva meses afinando. Aquí no. Es una puerta nueva, no un cambio en la que ya usabas.

Lo que sí puedes hacer, si te apetece, es elegir. El anuncio dice que el archivo de instrucciones del proyecto se cambia desde /config, en la entrada "Project instructions". O sea que la decisión la tienes tú en un menú, no escondida en un fichero de configuración que hay que buscar con linterna.

¿A quién le sirve esto de verdad?

Sobre todo a dos perfiles.

El primero: el que trabaja con más de un agente. Si en tu día a día no solo usas Claude Code, sino que abres otras herramientas de IA sobre la misma carpeta, hasta ahora acababas con la misma información duplicada en varios archivos. Y duplicar información es la manera más rápida que existe de que se te desincronice. Cambias una regla en uno, se te olvida el otro, y a los quince días tienes dos verdades distintas conviviendo en la misma carpeta.

El segundo: el que se mete en un proyecto que ya existe y no es suyo. Bajas una carpeta, la abres con Claude Code, y resulta que ahí dentro ya hay un AGENTS.md escrito por otra persona. Antes eso era un archivo más que Claude Code veía como texto cualquiera. Ahora lo lee como instrucciones del proyecto.

Si te dedicas a meter Claude Code en proyectos que ya tienes montados, esa diferencia se nota el primer día.

Lo que el changelog no dice

Y aquí toca frenar, porque la línea del anuncio es corta y hay tres cosas que no aclara.

No dice qué pasa si en la misma carpeta están los dos archivos y tú fuerzas el AGENTS.md desde /config. Dice cuál se lee por defecto cuando no hay CLAUDE.md, y dice que se puede cambiar. El resto no lo cuenta.

No dice nada sobre el formato interno del AGENTS.md ni sobre si hay que escribirlo distinto. El anuncio habla de qué archivo se lee, no de cómo escribirlo.

Y no dice nada de los archivos anidados ni de los personales. Si tienes instrucciones repartidas por subcarpetas, el changelog no entra ahí.

Lo digo porque en este tipo de novedades es facilísimo rellenar los huecos con lo que uno supone. Y luego te pasas media tarde peleándote con un comportamiento que nadie prometió. Si necesitas saberlo con certeza, la documentación oficial vive en claude.com/product/claude-code.

¿Debería cambiar mi CLAUDE.md por un AGENTS.md?

Mi respuesta corta: si solo usas Claude Code, no.

No ganas nada. Tienes un archivo que funciona, que Claude Code lee sin que tengas que tocar ninguna opción, y que además es el que aparece en los noventa tutoriales que hay por internet. Cambiar el nombre de un archivo que funciona para quedar más moderno es de las cosas más tontas que puedes hacer con tu tarde.

Si trabajas con varios agentes sobre la misma carpeta, ahí sí me lo pensaría. Tener un solo archivo de instrucciones que lean todos te quita la tarea silenciosa de mantener dos versiones de lo mismo. Y la tarea silenciosa es la peor de todas, porque no te avisa cuando la estás incumpliendo. Simplemente un día tu agente hace algo raro y tardas media hora en entender que estaba leyendo las reglas viejas.

Ojo con una cosa, eso sí: si te pasas a AGENTS.md, el contenido sigue teniendo que ser bueno. Cambiar el nombre del archivo no arregla unas instrucciones vagas. Si tu archivo dice "escribe bien y no rompas nada", da igual cómo se llame. Ahí es donde pasa el trabajo de verdad, y por eso dejé escritas unas plantillas de CLAUDE.md que sirven igual de base tanto si el archivo se llama de una manera como de otra.

Lo que a mí me parece

Me gustan estos cambios pequeños más que los anuncios con vídeo y música épica.

Esto no añade una función nueva que tengas que aprender. Quita una fricción que ni sabías que tenías: la de que cada herramienta te pidiera su propio papelito con las normas. El trabajo de escribir las reglas del proyecto sigue siendo tuyo. Lo único que ha cambiado es que ahora ese trabajo puede vivir en un archivo que no lleva el nombre de una sola marca.

Y si acabas de aterrizar en todo esto y lo de los archivos de instrucciones te suena a chino, empieza por Claude Code para no programadores y vuelve a esto cuando tengas tu primer proyecto abierto. Sin proyecto, esta novedad no te toca en nada.

Si no sabes por dónde meterle mano a la IA en tu trabajo, empieza por saber en qué punto estás. Tengo un test rápido en ¿Cuál es tu nivel de IA? que te lo dice en cinco minutos. Y si lo que quieres es montar tu web con Claude Code de principio a fin, eso lo tienes en Crea tu web con Claude Code.