¿AGENTS.md o CLAUDE.md? ¿Qué contienen realmente esos 592 repositorios destacados?

La guía de ciclo de vida de desarrollo nativo para IA de Anthropic reorganiza las seis etapas del suministro de software alrededor de agentes de programación. La etapa 3 exige un artefacto concreto: CLAUDE.md, un archivo de conocimiento a nivel de repositorio que se actualiza cada vez que un agente repite el mismo error. Una encuesta realizada en los repositorios públicos con más estrellas evaluó hasta qué punto ese consejo se aplica en la práctica, y la respuesta es sorprendente. CLAUDE.md lidera en cantidad de archivos pero pierde en contenido.

Los números clave

El 8 de septiembre de 2026, una investigación analizó los 592 repositorios con más estrellas seleccionados de seis clasificaciones de lenguajes (TypeScript, Python, Go, Rust, Java y JavaScript, después de eliminar duplicados). Se buscó CLAUDE.md y varios archivos relacionados.

• 165 repositorios (27.9%) contienen un CLAUDE.md.
• 94 de esos 165 (57.0%) no contienen ningún tipo de conocimiento del repositorio; son enlaces de redirección.

De esos 165, 94 (57.0%) no poseen ningún conocimiento sobre repositorios. Se trata de redirecciones.

209 repositorios, el 35.3%, contienen un AGENTS.md, y el 93.8% de ellos tiene contenido real.

En aquellos donde existen ambos archivos (132 repositorios), 89 apuntan a AGENTS.md desde CLAUDE.md. Solo 10 lo hacen en sentido inverso.

Solo el 5.9% cuenta con un .claude/settings.json, que es donde se configuran los ganchos de la Etapa 3 del playbook.

Los archivos CLAUDE.md significativos tienen un tamaño mediano de 3,934 bytes, y el más grande alcanza los 66,176.

Si se excluyen las redirecciones, solo el 12.0% de los repositorios principales tiene un CLAUDE.md con contenido real. Un AGENTS.md significativo aparece en el 33.1% de ellos.

Para quienes adopten ahora este manual, las conclusiones son mixtas. Los agentes sí necesitan un archivo de conocimiento bien gestionado y controlado por versiones, pero el manual indica el archivo incorrecto. En todos estos repositorios, CLAUDE.md se ha convertido en un complemento de compatibilidad que se coloca delante de AGENTS.md, un archivo neutral desde el punto de vista del proveedor que es leído por todos los agentes de programación principales. Los proyectos que ya resolvieron este problema escribieron su conocimiento una sola vez en AGENTS.md y dejaron un indicador de una línea detrás.

Cómo se realizó el conteo

El marco de muestreo fue una captura del ranking público de GitHub: los 100 repositorios con más estrellas en cada uno de los seis idiomas, que se redujeron a 592 repositorios únicos tras la eliminación de duplicados. Se solicitó un conjunto fijo de rutas desde raw.githubusercontent.com en la versión HEAD, sin clave API, sin autenticación y sin scraping. La única pregunta era si existía un archivo y qué decía. Luego se descargaron todos los contenidos de CLAUDE.md y AGENTS.md, 374 archivos distribuidos en 242 repositorios, y se leyeron a mano.

Fue al leerlos cuando el esquema inicial falló. Resultó que el CLAUDE.md promedio tenía solo dos líneas, por lo que el 27,9% por sí solo casi no significa nada.

Qué contienen esos archivos

Ninguna de las formas comunes representa conocimiento real:

• Un enlace simbólico de git. El archivo tiene nueve bytes, solo el texto AGENTS.md sin un salto de línea al final, ya que git almacena un enlace simbólico como un bloque que contiene su destino. openclaw, dify, ant-design, moby, home-assistant, superset, Stirling-PDF y nushell son ejemplos.
• Una sola línea de importación, @AGENTS.md, de once bytes, que Claude Code resuelve al cargarlo. n8n, supabase, grafana, nuxt, storybook, prometheus, traefik, ruff y pdf.js funcionan de esta manera.
• Una oración en prosa. En lazygit equivale a una instrucción para leer primero AGENTS.md y seguir sus indicaciones. La CLI de Google Workspace dice lo mismo, pero de forma más extensa.

Algunos casos límite son importantes para cualquiera que construya un clasificador. Docusaurus cuenta con un encabezado seguido de la importación y nada más. Jest, en cambio, hace referencia a .github/copilot-instructions.md. Ansible está formado por tres líneas de importación sin ningún texto explicativo. Zed enlaza simbólicamente a un archivo llamado .rules.

Después de excluir todos los archivos cuyo único contenido es una redirección, 71 de los 592 repositorios cuentan con un CLAUDE.md que contiene información sobre el repositorio, lo que representa el 12.0%. Esos 71 archivos son reales y algunos de ellos son bastante grandes: la mediana es de 3,934 bytes, el percentil 90 es de 19,506 y el máximo es de 66,176. Proyectos como bun, pytorch, swc, gstack y 3x-ui mantienen guías operativas reales que abarcan comandos de compilación, mapas de repositorios, filosofía de pruebas y reglas aplicables a directorios específicos.

Dónde reside realmente el conocimiento

En AGENTS.md, y por una amplia ventaja. Su tasa de contenido sustantivo es del 93,8 %, con 196 de los 209 archivos, frente al 43,0 % en CLAUDE.md. Esa asimetría es lo que marca la diferencia. Un repositorio que crea un AGENTS.md casi siempre lo llena de contenido. Un repositorio que crea un CLAUDE.md, con mayor frecuencia, sirve como puente hacia otro lugar.

Los 132 repositorios que contienen ambos archivos dejan claro esta dirección:

• En 89 de ellos, CLAUDE.md es el indicador y AGENTS.md alberga el contenido.
• En 10, los roles están invertidos: AGENTS.md redirige y CLAUDE.md es el archivo real. Pytorch, bun, milvus, anki y litellm se encuentran entre ellos.
• 31 mantienen contenido sustantivo en ambos, lo que significa que el mismo conocimiento institucional se conserva dos veces.
• 2 tienen indicadores en ambos, lo que implica la existencia de un tercer archivo en algún lugar.

Por lo tanto, las redirecciones fluyen aproximadamente en una proporción de nueve a uno hacia el archivo neutral con respecto al proveedor. Un resultado unidireccional suele ser un artefacto de medición, por lo que se buscó intencionadamente el caso opuesto. Éste existe, pero solo en minoría.

Aceptación por idioma

La diferencia entre los idiomas es lo suficientemente grande como para planificar en consecuencia. CLAUDE.md primero, AGENTS.md segundo:

• TypeScript: 46.5% y 53.5%.
• Rust: 33.3% y 43.4%.
• Go: 32.3% y 37.4%.
• Python: 25.5% y 31.6%.
• JavaScript: 19.0% y 23.0%.
• Java: 10.3% y 22.7%.

AGENTS.md lidera en todos los lenguajes. Java muestra la mayor brecha, ya que un repositorio tiene más del doble de probabilidades de contar con AGENTS.md en comparación con CLAUDE.md, mientras que los proyectos en TypeScript tienen más de cuatro veces más probabilidades que los de Java de tener CLAUDE.md. En los seis lenguajes en total, el 43.2% de los repositorios más importantes cuenta con algún archivo de instrucciones para agentes, ya sea AGENTS.md, CLAUDE.md, .cursorrules o el archivo de instrucciones de Copilot. El de Copilot está presente en el 9.3%. La convención .cursorrules prácticamente ha desaparecido de este grupo, con solo un 0.5%, lo cual sirve como recordatorio claro de cuán rápido puede desaparecer una costumbre específica de un proveedor.

El resto del stack de Etapa 3

Los equipos de plataforma deben leer esta parte con atención. La guía no solo requiere un archivo de conocimiento: combina archivos de conocimiento, habilidades y ganchos, y los ganchos son la capa de control que evita acciones peligrosas durante las compilaciones.

Solo 35 de los 592 repositorios (5.9%) cuentan con un .claude/settings.json, y solo 32 de ellos (5.4%) lo tienen junto con un CLAUDE.md. Es el documento de documentación, que es simplemente un archivo al que cualquiera puede escribir, el que ha sido adoptado por la gente. La capa de control, aquella que realmente determina qué puede hacer un agente, existe en aproximadamente uno de cada dieciocho repositorios. Un playbook cuya seguridad depende de hooks describe algo que casi nadie ha creado aún.

Límites de los datos

• La muestra proviene de repositorios públicos clasificados por número de estrellas. Un playbook como este se despliega en repositorios empresariales privados, que no son visibles. La adopción allí podría ser mayor y más sistemática.
• Se trata de una sola captura, hecha en HEAD el 8 de septiembre de 2026. La adopción avanza rápidamente, por lo que en un mes los porcentajes ya no serán exactos, y la tendencia es más importante que el nivel actual.

Un archivo no constituye una práctica real. Un CLAUDE.md sustantivo solo demuestra que alguien lo escribió; no ofrece evidencia de que alguien lo mantenga ni de que la calidad de las respuestas del agente haya mejorado. Los trabajos publicados cuestionan si estos archivos realmente ayudan a los agentes de programación, y esta medida no dice nada al respecto.

El archivo settings.json es un indicador aproximado de los hooks y no un censo completo. Cualquier hook definido en otras ubicaciones queda sin ser detectado, lo que hace que el 5.9% sea un valor mínimo.

La decisión sobre dónde trazar el límite entre lo indicativo y lo sustantivo es subjetiva. La cantidad eliminada fue de 120 caracteres de texto adicional después de quitar los títulos, las importaciones y las oraciones de redirección. Se auditaron manualmente los catorce archivos más cercanos a ese umbral, y el archivo sustantivo más próximo, lazydocker, contiene 172 caracteres de verdaderas banderas de compilación. Al cambiar el umbral, también cambia esa cifra. Una segunda verificación en 25 repositorios frente a los archivos reales reveló que los errores ocurren en una sola dirección: el clasificador a veces considera como sustantivo una redirección cuando esta está formulada como instrucción para el agente en lugar de como indicación sobre dónde se encuentra la documentación, como ocurre en zeroclaw. Por lo tanto, el 57,0% representa un mínimo, y la verdadera proporción de contenido indicativo es ligeramente mayor.

También hubo un caso casi ocurrido que merece ser mencionado. La primera evaluación indicó que el 27,9% de los repositorios más importantes había adoptado CLAUDE.md, y esa información habría sido publicada. Fue el valor mediano de dos líneas lo que impidió su publicación.

Respuestas prácticas

¿Qué archivo debería contener el contenido? La evidencia favorece a AGENTS.md, con CLAUDE.md reducido a un enlace. La mayoría de los repositorios que utilizan dos archivos (89 de 132) hacen exactamente eso. Permanece una copia del conocimiento, y los agentes que nunca buscan un nombre de archivo específico para Claude aún pueden leerlo.

¿Lee Claude Code directamente AGENTS.md? No, a diferencia de CLAUDE.md, que sigue una convención de nomenclatura específica, y esa diferencia es la razón por la cual existe el patrón de punteros. En la práctica funcionan dos formas: un enlace simbólico de git llamado CLAUDE.md que apunta a AGENTS.md, o la importación mediante @AGENTS.md. El proyecto new-api incluso advierte en su propio CLAUDE.md que la importación no siempre se carga de manera fiable, y recomienda que el agente abra el archivo directamente.

¿Es buena o mala una tasa de adopción del 27.9%? Mejor de lo esperado para una convención tan reciente, pero peor de lo que sugiere el playbook. Otros dos datos son más reveladores: el 12.0% de los repositorios cuenta con archivos CLAUDE.md que contienen contenido real, y solo el 5.4% combina uno de ellos con ganchos de aplicación de reglas.

¿Por qué 31 repositorios mantienen ambos archivos como válidos? Nunca se midió la diferencia entre las copias, lo cual constituye claramente el siguiente estudio a realizar. El conocimiento institucional duplicado se convierte en un problema cuando las copias difieren, y las herramientas no emiten ninguna advertencia.

¿Pueden otros repetir esto? Sí. La muestra proviene de una clasificación pública de estrellas; la herramienta son solicitudes HTTP sin autenticación dirigidas a raw.githubusercontent.com, y el clasificador cabe en aproximadamente 40 líneas de código.

Una verificación final para quienes gestionen un repositorio con un agente de programación integrado: la última vez que cambió una orden de compilación, ¿el archivo de conocimiento del agente también se modificó en el mismo commit, o apareció la orden obsoleta tres sesiones después?

Lecturas relacionadas

• Formato de Conocimiento Abierto: Memoria portátil para agentes de programación de IA — Cómo el Formato de Conocimiento Abierto almacena el conocimiento de los agentes como archivos Markdown vinculados, cómo difiere de CLAUDE.md y MCP, y cómo comenzar a usarlo.
• Estructurando proyectos de Claude Code para que los agentes se mantengan enfocados en repositorios grandes — Seis patrones para bases de código extensas: archivos CLAUDE.md en capas, habilidades, subagentes, reglas de denegación, árboles de trabajo dispersos y complementos de language-server que mantienen el contexto del agente limpio.