AGENTS.md & CLAUDE.md: El nuevo README para agentes de codificación IA

Si has usado un asistente de codificación IA recientemente, probablemente has notado algo: todos quieren un archivo Markdown.

GitHub Copilot lee .github/copilot-instructions.md. Cursor lee .cursor/rules/. Claude Code lee CLAUDE.md. Windsurf lee .windsurf/rules. Jules de Google lee JULES.md. ¿Y el estándar universal? AGENTS.md — ahora utilizado por más de 60.000 repositorios de código abierto y administrado por la Agentic AI Foundation de la Linux Foundation.

Markdown ha pasado de ser un formato de documentación al sistema operativo para agentes de codificación IA.

¿Qué es AGENTS.md?

AGENTS.md es un archivo Markdown de formato abierto y simple que vive en tu repositorio y actúa como paquete de briefing para los agentes de codificación IA. Piénsalo como el complemento de README.md:

• README.md es para humanos: inicios rápidos, descripciones de proyectos, badges
• AGENTS.md es para agentes IA: pasos de compilación, comandos de prueba, convenciones de codificación, decisiones arquitectónicas

El agente lee el archivo más cercano en el árbol de directorios, por lo que el más cercano tiene prioridad. Cada subproyecto puede incluir instrucciones personalizadas.

¿Qué es CLAUDE.md?

CLAUDE.md es específicamente para Claude Code de Anthropic. Se lee automáticamente al inicio de cada sesión y contiene instrucciones específicas del proyecto que de otro modo tendrías que repetir en cada prompt.

Un buen CLAUDE.md típicamente incluye:

• Contexto del proyecto: Una línea que orienta a Claude sobre lo que hace el proyecto
• Estilo de código: Tus preferencias de formato, convenciones de nombres, patrones a seguir
• Comandos: Cómo ejecutar pruebas, compilar, lintear y desplegar
• Notas de arquitectura: Decisiones clave que Claude debe respetar

El enfoque recomendado: pon las instrucciones compartidas en AGENTS.md (para que todos los herramientas IA se beneficien), luego añade funciones específicas de Claude en CLAUDE.md.

El panorama completo de los archivos de instrucciones IA

Aquí están todas las principales herramientas de codificación IA y sus convenciones Markdown:

Herramienta	Archivo	Formato
GitHub Copilot	.github/copilot-instructions.md	Markdown
Cursor	.cursor/rules/*.md	Markdown
Claude Code	CLAUDE.md	Markdown
Windsurf	.windsurf/rules	Markdown
Google Jules	JULES.md	Markdown
Universal	AGENTS.md	Markdown

¿Notas el patrón? Todo es Markdown. Sin excepción.

Por qué ganó Markdown

Markdown es el formato perfecto para los archivos de instrucciones de agentes porque:

1. Los LLMs lo entienden de forma nativa — es el formato más común en sus datos de entrenamiento
2. Es legible por humanos — los desarrolladores pueden revisar y editar instrucciones fácilmente
3. Es versionable — vive en git junto a tu código
4. Es ligero — sin sobrecarga de análisis, sin necesidad de herramientas especiales
5. Es universal — funciona con cualquier herramienta IA, editor y plataforma

Como dijo Visual Studio Magazine: en la IA agéntica, todo gira en torno a Markdown.

Mejores prácticas para escribir instrucciones de agentes

Basadas en el análisis de miles de repositorios:

Empieza mínimo. Añade reglas solo cuando notes que el agente comete el mismo error repetidamente. Las instrucciones demasiado detalladas pueden confundir más que ayudar.

Sé específico con los comandos. No digas “ejecuta las pruebas” — di pnpm test o pytest -x tests/.

Documenta tu arquitectura. Si tu proyecto usa un patrón específico (como el paso de mensajes entre un content script y un service worker), explícalo. El agente no puede inferir decisiones arquitectónicas solo del código.

Incluye lo que NO se debe hacer. Las instrucciones negativas son sorprendentemente efectivas: “Nunca modificar el esquema de base de datos directamente” o “No usar class components, siempre usar hooks.”

El papel de Save en este mundo

Si estás creando archivos de instrucciones para agentes, probablemente también estás guardando material de referencia de la web: páginas de documentación, respuestas de Stack Overflow, README de GitHub, referencias de API.

Save convierte cualquiera de estas fuentes web a Markdown limpio con un clic — perfecto para construir el contexto que tus agentes IA necesitan. Guarda una página de documentación, pega el Markdown en tu AGENTS.md o documentos de referencia, y tu asistente de codificación IA tendrá instantáneamente el contexto que necesita.

El flujo de trabajo:

1. Encuentra documentación útil o ejemplos de código en la web
2. Haz clic en Save para convertir a Markdown
3. Referencia o incluye en tus archivos de instrucciones de agentes
4. Tu asistente de codificación IA mejora con cada guardado

El futuro: Markdown como superficie de control de la IA

Microsoft y GitHub están tratando ahora Markdown como una superficie de control estable y auditable para el comportamiento de la IA. Ya no es solo documentación — es la interfaz entre la intención humana y la ejecución de la IA.

Estamos viendo que los archivos Markdown cumplen tres roles distintos:

1. Documentación: Explica un sistema a los humanos
2. Instrucción: Restringe y dirige el comportamiento de la IA
3. Skill: Agrupa instrucciones con recursos para que los agentes puedan repetir flujos de trabajo

Esta tendencia solo se está acelerando. A medida que los asistentes de codificación IA se vuelven más capaces, los archivos Markdown que los guían se vuelven más importantes.

---

Save convierte cualquier página web a Markdown limpio con un clic. Perfecto para construir bibliotecas de referencia, capturar documentación y crear contexto para tus flujos de trabajo de codificación IA. Prueba Save gratis.