AGENTS.md vs CLAUDE.md en 2026: árbol de decisión de 5 preguntas

Si estás por añadir el primer archivo de instrucciones para un agente de código a tu repositorio en 2026, el primer minuto de la decisión pesa más de lo que parece. Elegir AGENTS.md, CLAUDE.md, o ambos, cambia qué herramientas te van a leer, qué se comparte con el equipo, y cómo escala cuando el repositorio crece.

Este artículo no es una comparación abstracta. Es un árbol de decisión de 5 preguntas que puedes ejecutar hoy sobre tu repositorio, con las specs oficiales de 2026 al lado, para que la elección no tenga que volver a discutirse en tres meses.

Antes del árbol: qué son cada uno en 2026

AGENTS.md es un formato Markdown abierto y vendor-neutral que se coloca en la raíz del proyecto. La spec actual (2026) no requiere ningún campo, no usa frontmatter YAML, y su gobernanza pasó a la Agentic AI Foundation bajo la Linux Foundation. Lo leen nativamente OpenAI Codex, Cursor, GitHub Copilot coding agent, Gemini CLI, Windsurf, Aider, Zed, Factory, Jules, Devin, Amp, y más de una docena de herramientas adicionales.

CLAUDE.md es la convención de Anthropic para Claude Code. Se carga desde varias ubicaciones a la vez (global, proyecto, subdirectorios, personal no versionado), y todos los archivos aplicables se concatenan en el contexto, no se sobrescriben entre sí. Esta parte es importante: CLAUDE.md no es una config con jerarquía de precedencia, es un conjunto de instrucciones aditivo que Claude Code lee entero.

La diferencia estructural, en una frase: AGENTS.md es un archivo compartido entre agentes, CLAUDE.md es una cadena de archivos específica de un agente.

Árbol de decisión: 5 preguntas para elegir hoy

Ejecuta estas preguntas en orden. En la mayoría de los casos, la respuesta a la pregunta 3 ya te resuelve el resto.

Pregunta 1: ¿Vas a usar más de un agente distinto en el mismo repositorio?

Si en tu equipo hay personas usando Codex, Cursor, Copilot, o Windsurf en paralelo con Claude Code, la respuesta natural es AGENTS.md como base compartida. Es el único formato que los va a leer a todos sin duplicación.

Si tu equipo es homogéneo y todos usan solo Claude Code, ir directo a CLAUDE.md es más simple y aprovecha la carga jerárquica que Claude Code hace de forma nativa.

Pregunta 2: ¿Necesitas instrucciones que varíen por subdirectorio?

Un monorepo con paquetes distintos (backend, frontend, infra) suele necesitar reglas locales: convenciones de test en backend/, reglas de estilo en frontend/, prohibiciones concretas en infra/. CLAUDE.md está diseñado exactamente para esto: pones un CLAUDE.md en cada subdirectorio y Claude Code los concatena todos según qué archivos toca.

AGENTS.md, en cambio, se piensa como un archivo por proyecto. La spec no impide poner un AGENTS.md por subdirectorio, pero el soporte real varía entre agentes. Codex y Cursor lo respetan de forma parcial; otros solo leen el de la raíz.

Si necesitas granularidad por subdirectorio y usas Claude Code, CLAUDE.md gana esta pregunta.

Pregunta 3: ¿El archivo debe versionarse o quedar fuera del repositorio?

Aquí hay una asimetría clara. CLAUDE.md tiene una ubicación explícita para instrucciones personales que no van a git: .claude/CLAUDE.md (a nivel de proyecto, no versionado) y ~/.claude/CLAUDE.md (global del usuario). AGENTS.md no define una convención equivalente. Todo lo que vive como AGENTS.md en un repositorio se asume compartido.

Si necesitas separar “reglas del equipo” de “atajos personales”, CLAUDE.md te da una separación oficial. Si todo lo que quieres documentar es de equipo, AGENTS.md es suficiente.

Pregunta 4: ¿Tu principal restricción es de seguridad o de estilo?

Las reglas de estilo (naming, formato, convenciones de test) son intercambiables entre formatos y no fuerzan una elección.

Las reglas de seguridad, en cambio, sí fuerzan una. Prohibiciones concretas del tipo “no leer .env”, “no ejecutar curl sin revisión”, “no hacer push directo a main”, tienden a ejecutarse con más fidelidad cuando están en un archivo que el agente reconoce nativamente. Claude Code cumple mejor prohibiciones escritas en CLAUDE.md porque las combina con su sistema de permisos y hooks (PreToolUse). Codex sigue mejor las reglas escritas en AGENTS.md porque su modelo de sandbox está construido asumiendo ese archivo.

Regla práctica: si tu principal preocupación son prohibiciones de seguridad, escribe en el archivo del agente que efectivamente vas a usar. La spec importa menos que el enforcement real.

Pregunta 5: ¿Necesitas que el archivo sirva también como documentación para humanos?

Ni AGENTS.md ni CLAUDE.md deberían intentar reemplazar al README.md. Los dos formatos existen porque el README.md es para personas y ese archivo es para agentes, y mezclar audiencias hace que ninguno de los dos lectores lea con atención.

Si te pillas escribiendo “esto también sirve para nuevos ingenieros humanos” en tu AGENTS.md, es señal de que el contenido pertenece al README.md. Extrae la parte humana y deja solo lo operacional para el agente.

Casos que se repiten

Después de haber consultado con varios equipos y de haberlo aplicado en mi propio repositorio, hay tres configuraciones que cubren la mayoría de los casos:

• Equipo pequeño, un solo agente (Claude Code): un CLAUDE.md en la raíz. Sin más. Si aparece necesidad de granularidad, se agregan CLAUDE.md en subdirectorios.
• Equipo mixto que usa Codex y Claude Code: AGENTS.md en la raíz con las reglas compartidas del equipo, y un CLAUDE.md corto que dice “aplica AGENTS.md y estas 3 preferencias específicas de Claude Code”. Evita la duplicación total.
• Monorepo grande: AGENTS.md en la raíz para lo transversal (build, test, commit) y CLAUDE.md por paquete para las reglas locales. Esta combinación aprovecha ambos formatos por lo que son mejores.

¿Pueden coexistir sin problemas?

Sí, y en 2026 es lo más común en equipos mixtos. Claude Code ignora AGENTS.md por defecto, y Codex ignora CLAUDE.md. Los dos archivos pueden convivir en la misma raíz sin conflictos técnicos.

El único problema real de coexistencia es la duplicación. Si el mismo estándar de test aparece en ambos archivos, va a divergir en el primer refactor y el equipo va a leer versiones distintas de la misma regla. La estrategia sana es: contenido compartido va en AGENTS.md, contenido específico de Claude Code va en CLAUDE.md, y CLAUDE.md puede referenciar AGENTS.md en lugar de repetirlo.

El error que se paga más caro

El error más caro no es elegir el formato equivocado. Es escribir instrucciones tan abstractas que ningún agente sabe qué hacer con ellas. “Sigue las buenas prácticas del equipo” no es una instrucción. “Nunca importes desde internal/ fuera de su paquete padre” sí lo es.

Si tuvieras que quedarte con una sola idea de este árbol, que sea esta: elegir entre AGENTS.md y CLAUDE.md es 20% del trabajo, escribir instrucciones concretas y auditables es el 80% restante. Ninguna spec te va a rescatar de un archivo lleno de generalidades.

Fuentes citadas (2026)

• Spec y ecosistema de AGENTS.md gobernado por la Agentic AI Foundation (Linux Foundation), con soporte nativo confirmado en OpenAI Codex, Cursor, GitHub Copilot coding agent, Gemini CLI, Windsurf, Aider, Zed, Factory, Jules, Devin, Amp
• Documentación de Anthropic sobre la jerarquía de CLAUDE.md: archivos globales, de proyecto y de subdirectorio se concatenan (no se sobrescriben) al contexto de Claude Code

---

ken imoto · WebRTC & Voice AI engineer · kenimoto.dev