$ man how-to/claude-md-vs-agents-md-vs-cursorrules

CLAUDE.md es para Claude Code. AGENTS.md es un estandar multi-herramienta. .cursorrules es para Cursor IDE. Los tres sirven el mismo proposito: darle a la herramienta de AI contexto e instrucciones especificas del proyecto para que produzca mejor resultado. La diferencia es alcance y formato. Si solo usas una herramienta de AI, usa el archivo de configuracion de esa herramienta. Si usas multiples herramientas - y la mayoria de profesionales serios lo hacen - necesitas una estrategia para mantenerlos sincronizados sin triplicar tu carga de mantenimiento.

PATTERN

CLAUDE.md es el archivo de configuracion de Anthropic para Claude Code. Se carga automaticamente al inicio de la sesion y permanece en contexto durante toda la conversacion. Ubicacion: raiz del repositorio para nivel de proyecto, ~/.claude/CLAUDE.md para global, y directorios anidados para nivel de modulo. Claude Code fusiona todos los niveles aplicables. Formato: Markdown plano. Encabezados, viñetas, bloques de codigo, tablas. No se necesita sintaxis especial. Claude lo lee como cualquier otro documento. Caracteristicas unicas: soporta importaciones @path/to/file que se expanden inline. Soporta multiples niveles (global, proyecto, directorio). Tiene un comando dedicado /init que auto-genera un archivo inicial desde tu codebase. Mejor para: convenciones de codigo, comandos de build/test, reglas de seguridad, arquitectura del proyecto, pasos de despliegue e instrucciones de comportamiento como "nunca hagas commit de archivos .env" o "ejecuta tests antes de marcar una tarea como completa." Los mejores archivos CLAUDE.md tienen menos de 200 lineas. Usan instrucciones especificas y verificables ("usa indentacion de 2 espacios" no "formatea el codigo correctamente"). Apuntan a archivos en lugar de copiar contenido ("ver docs/ARCHITECTURE.md para el diagrama completo del sistema" no pegar el diagrama inline).

PATTERN

AGENTS.md es un estandar abierto emergente pensado para funcionar con todas las herramientas de codigo AI - no solo Claude Code. Fue diseñado por la comunidad como un archivo de configuracion agnóstico de herramientas. Ubicacion: raiz del repositorio, similar a CLAUDE.md. Formato: Markdown con secciones estructuradas. Tipicamente incluye: descripcion del proyecto, resumen de arquitectura, estandares de codigo, instrucciones de testing y configuraciones especificas por herramienta. Filosofia: escribe tus instrucciones una vez, haz que cada herramienta de AI las lea. En lugar de mantener archivos separados para Claude Code, Cursor, Copilot y Windsurf, mantén un AGENTS.md y deja que cada herramienta lo analice. Revision de realidad: la adopcion aun es temprana. Claude Code lee CLAUDE.md nativamente. Cursor lee .cursorrules nativamente. El soporte de AGENTS.md varia. Algunas herramientas lo respetan, otras lo ignoran. El estandar es prometedor pero aun no es universal. Mejor para: equipos que usan multiples herramientas de AI y quieren una unica fuente de verdad para instrucciones del proyecto.

PATTERN

.cursorrules es el archivo de instrucciones a nivel de proyecto de Cursor IDE. Se carga cuando abres un proyecto en Cursor. Ubicacion: raiz del repositorio como .cursorrules (archivo unico) o directorio .cursor/rules/ para multiples archivos de reglas con patrones glob. Formato: texto plano o Markdown. El enfoque .cursor/rules/ usa archivos .mdc con frontmatter YAML que especifica que patrones de archivos activan la regla. Caracteristicas unicas: activacion de reglas basada en glob (las reglas solo se cargan cuando editas archivos que coinciden), reglas solicitadas por el agente que se cargan bajo demanda, e integracion con los modos composer y chat de Cursor. Mejor para: flujos de trabajo especificos de Cursor, reglas basadas en patrones de archivos (cargar convenciones de TypeScript solo al editar archivos .ts) y equipos que estandarizan Cursor como su IDE. Limitacion: .cursorrules solo funciona en Cursor. Si alguien en tu equipo usa una herramienta diferente, no obtiene ningun beneficio de estos archivos.

PRO TIP

Mantener tres archivos de configuracion separados con la misma informacion es una pesadilla de mantenimiento. Aqui esta el enfoque que funciona: CLAUDE.md es tu configuracion principal. Es la mas detallada porque Claude Code es el mas capaz siguiendo instrucciones complejas y multi-paso. Escribe tu contexto completo del proyecto, convenciones y flujos de trabajo aqui. AGENTS.md es una referencia cruzada simplificada. Enlaza a CLAUDE.md para detalles. Incluye solo las instrucciones universales que toda herramienta deberia seguir: estandares de codigo, requisitos de testing, resumen de arquitectura. .cursorrules maneja reglas especificas de Cursor. Activacion por patrones de archivos, preferencias de edicion inline, instrucciones del modo composer. No dupliques lo que ya esta en CLAUDE.md. La estructura: CLAUDE.md - Configuracion completa del proyecto (200 lineas) AGENTS.md - Subconjunto universal + enlaces a CLAUDE.md (50 lineas) .cursor/rules/*.mdc - Reglas especificas de Cursor por patron de archivos (archivos por regla) De esta manera, cuando las convenciones cambian, actualizas CLAUDE.md. AGENTS.md apunta a el. .cursorrules solo contiene comportamiento especifico de Cursor que no aplica en otro lugar. Si solo usas Claude Code: solo mantén CLAUDE.md. Omite los demas hasta que los necesites.