.cursorrules vs CLAUDE.md vs AGENTS.md: ¿Qué archivo de reglas IA necesitas?

Cada herramienta de codificación IA quiere un archivo Markdown con las reglas de tu proyecto. Pero todas quieren un archivo Markdown diferente.

Si usas múltiples herramientas IA (y la mayoría de los desarrolladores lo hacen), esto se vuelve confuso rápidamente. Aquí está la guía definitiva sobre qué archivos necesitas y qué va en cada uno.

Los archivos de un vistazo

Archivo	Herramienta	Ubicación	Alcance
AGENTS.md	Universal (todas las herramientas)	Raíz del proyecto	Reglas compartidas para todos los agentes IA
CLAUDE.md	Claude Code	Raíz del proyecto	Instrucciones específicas de Claude
.cursor/rules/*.md	Cursor	Directorio .cursor/rules/	Reglas específicas de Cursor
.github/copilot-instructions.md	GitHub Copilot	Directorio .github/	Instrucciones específicas de Copilot
.windsurf/rules	Windsurf	Directorio .windsurf/	Reglas específicas de Windsurf
JULES.md	Google Jules	Raíz del proyecto	Instrucciones específicas de Jules

AGENTS.md: El estándar universal

Ideal para: equipos que usan múltiples herramientas IA, proyectos de código abierto

AGENTS.md es lo más cercano a un estándar universal. Ahora se usa en más de 60.000 repositorios y está gestionado por la Agentic AI Foundation de la Linux Foundation (junto con MCP y goose).

Pon aquí tus instrucciones compartidas — cosas que cada herramienta IA debería saber:

• Estructura y arquitectura del proyecto
• Comandos de compilación y prueba
• Convenciones de estilo de código
• Patrones comunes y antipatrones
• Dependencias y pasos de configuración

Todas las principales herramientas de codificación IA leerán AGENTS.md, convirtiéndolo en la única fuente de verdad para las instrucciones IA de tu proyecto.

CLAUDE.md: La memoria de Claude Code

Ideal para: usuarios de Claude Code, equipos que estandarizan en Anthropic

CLAUDE.md se lee automáticamente al inicio de cada sesión de Claude Code. Soporta algunas funciones específicas de Claude como persistencia de memoria y contexto de sesión.

Usa CLAUDE.md para:

• Ajustes de comportamiento específicos de Claude
• Funciones que solo Claude Code soporta
• Anular o extender AGENTS.md para Claude

El patrón recomendado: reglas compartidas en AGENTS.md, adiciones específicas de Claude en CLAUDE.md.

.cursorrules / .cursor/rules/: El enfoque de Cursor

Ideal para: usuarios de Cursor, equipos que usan Cursor como su IDE principal

Cursor originalmente usaba un único archivo .cursorrules, luego evolucionó a un directorio .cursor/rules/ para un control más granular. Cada archivo en el directorio es una regla separada que Cursor aplica.

Usa las reglas de Cursor para:

• Comportamiento específico del agente Cursor
• Reglas para los modos Composer y Agent de Cursor
• Instrucciones específicas por tipo de archivo (ej: reglas diferentes para .tsx vs .py)

copilot-instructions.md: La convención de GitHub

Ideal para: usuarios de GitHub Copilot, flujos de trabajo centrados en GitHub

GitHub Copilot lee .github/copilot-instructions.md para instrucciones a nivel de proyecto. Sigue la convención de GitHub de poner la configuración en el directorio .github/.

La configuración recomendada

Para la mayoría de los proyectos, necesitas como máximo dos archivos:

Si usas una herramienta IA:

Simplemente usa el archivo nativo de esa herramienta (CLAUDE.md para Claude Code, .cursor/rules/ para Cursor, etc.).

Si usas múltiples herramientas IA:

1. AGENTS.md --- todas las reglas compartidas (arquitectura, comandos de compilación, convenciones)
2. Archivo específico de la herramienta --- solo para funciones únicas de esa herramienta

Estructura de ejemplo:

your-project/
  AGENTS.md              # Compartido: comandos de compilación, arquitectura, convenciones
  CLAUDE.md              # Específico de Claude: preferencias de memoria, uso de herramientas
  .cursor/rules/style.md # Específico de Cursor: comportamiento del Composer
  .github/copilot-instructions.md  # Específico de Copilot

Qué incluir en tus reglas

Basado en el análisis de miles de repositorios, los archivos de instrucciones más efectivos incluyen:

Siempre incluir:

• Cómo compilar y ejecutar el proyecto
• Cómo ejecutar las pruebas
• Decisiones arquitectónicas clave
• Preferencias de estilo de código

A menudo útil:

• Lo que NO se debe hacer (las instrucciones negativas funcionan sorprendentemente bien)
• Explicaciones de la estructura de archivos
• Pasos comunes de depuración
• Comandos de gestión de dependencias

Omitir:

• Características obvias del lenguaje
• Cosas que la IA ya sabe
• Reglas excesivamente detalladas (empieza mínimo, añade según sea necesario)

Construir tus reglas IA con contexto web

Escribir buenos archivos de instrucciones IA a menudo requiere referenciar documentación externa, guías de estilo o patrones arquitectónicos. Aquí es donde tener contenido web en formato Markdown ayuda.

Por ejemplo, si tu proyecto sigue un patrón de API específico de una página de documentación, puedes:

1. Usar Save para convertir esa página de documentación a Markdown
2. Referenciar o extractar las secciones relevantes en tu AGENTS.md
3. Tu asistente de codificación IA ahora tiene el contexto completo

Lo mismo aplica para documentación de frameworks, guías de estilo, artículos de mejores prácticas y soluciones de Stack Overflow. El Markdown limpio es el formato con el que tanto tú como tus herramientas IA pueden trabajar más eficazmente.

La conclusión

El ecosistema de reglas de codificación IA todavía está evolucionando, pero el patrón es claro: todo es Markdown. Ya sea que uses una herramienta o cinco, las instrucciones IA de tu proyecto viven en archivos Markdown que están versionados, son legibles por humanos y analizables por máquinas.

Empieza con AGENTS.md para reglas universales, añade archivos específicos de herramientas según sea necesario, y mantén todo mínimo hasta que veas un problema recurrente que valga la pena resolver.

---

Save convierte cualquier página web a Markdown limpio — perfecto para construir el material de referencia y el contexto de documentación que tus asistentes de codificación IA necesitan. Prueba Save gratis.