CLAUDE.md y AGENTS.md: qué son, dónde van y cómo se escriben
El archivo de veinte líneas que evita explicarle tu proyecto a la IA cada mañana. Qué es, en qué carpeta va, cómo se escribe y una plantilla lista para copiar.
6 min de lectura · Datos comprobados el 20/9/2026
Si cada mañana empiezas la sesión explicándole a la IA con qué está hecho tu proyecto, dónde están las cosas y qué no debe tocar, estás pagando dos veces: tu tiempo y tus tokens. Y aun así te propone una librería que tu proyecto no usa.
Se arregla con un archivo de texto. No hay que programar nada.
Qué es
Es un archivo normal, como una nota. Lo escribes una vez, lo dejas en la carpeta de tu proyecto, y la herramienta lo carga para saber cómo trabajar. Es el contexto que dejas de repetir.
Claude Code lo busca con el nombre CLAUDE.md. Otras herramientas —Codex, Cursor, Copilot— leen el mismo contenido con otro nombre: AGENTS.md. Si usas varias, puedes tener los dos con lo mismo dentro.
Dónde va
En la carpeta principal de tu proyecto: la misma que abres al empezar a trabajar. Ahí van las reglas generales. Algunas herramientas leen además archivos en subcarpetas para reglas locales; revisa en la tuya qué carga y desde dónde.
mi-negocio/
├── CLAUDE.md ← aquí
├── package.json
├── src/
└── documentos/Cómo se crea
Sin terminal
En tu editor: Archivo → Nuevo, y «Guardar como» con el nombre CLAUDE.md dentro de la carpeta principal del proyecto. Respeta las mayúsculas.
Con terminal
Entra a la carpeta de tu proyecto con cd y escribe touch CLAUDE.md. Comprueba con ls que aparece junto al resto de archivos.
Compruébalo
Abre la herramienta dentro del proyecto y usa su mecanismo para ver qué archivos cargó; si aparece tu archivo, lo está leyendo.
Cómo se escribe
El formato se llama Markdown y se aprende en diez segundos: una almohadilla y una palabra hacen un título, y debajo escribes frases normales, como se las dirías a alguien que entra hoy a tu equipo. Eso es todo el formato.
# Proyecto
Tienda de café en línea, hecha con Shopify.
# Cómo se prueba
Abrir la tienda y hacer un pedido de prueba.Qué va dentro: los cuatro bloques
Con estos cuatro cubres lo importante. Una frase cada uno.
Los cuatro bloques
Proyecto
Qué es y con qué está hecho, en una frase. Si alguien nuevo lo leyera, sabría dónde está parado.
Cómo se levanta
El paso exacto que das tú para verlo funcionando: el comando y la dirección donde se abre.
Cómo se comprueba
Lo que decide si algo quedó bien: un comando de pruebas, una pantalla que se ve, un pedido de prueba. Es el bloque que más cambia el resultado: sin él, «ya quedó» es una opinión.
No se toca
Lo que nadie edita sin avisar: contraseñas, facturas, carpetas generadas, migraciones.
# Proyecto
Tienda de café en línea. Hecha con Shopify, los textos viven en Notion.
# Cómo se levanta
npm run dev · se abre en http://localhost:3000
# Cómo se comprueba
npm test debe quedar en verde · y hacer un pedido de prueba
# No se toca
.env · facturas/ · dist/ · migrations/Reglas que se puedan comprobar, no deseos
El error típico es llenar el archivo de buenas intenciones. La herramienta no puede obedecer lo que no se puede verificar.
Así no
«Escribe código limpio y bien organizado.»
Así sí
«Toda función nueva lleva su prueba, y npm test tiene que quedar en verde.»
Si una línea no se puede comprobar, no es una regla: es un deseo.
La regla de oro
Lo que corriges dos veces se convierte en una línea del archivo. Así crece: a partir de correcciones reales, no de lo que imaginas que podría hacer falta.
La primera vez que le dices «no toques la carpeta generada», es una corrección. La segunda, es una línea nueva en el bloque «No se toca».
Preguntas que nos hacen
¿Sirve si no programo? Sí. Es igual de útil para un proyecto de documentos, una hoja de cálculo con macros o un sitio en un creador visual: cambia «cómo se levanta» por «dónde está» y «cómo se comprueba» por «qué miro para saber que quedó bien».
¿CLAUDE.md o AGENTS.md? El contenido es el mismo. Usa el nombre que lea tu herramienta; si usas dos herramientas, ten los dos archivos.
¿Cuánto debe medir? Veinte líneas es una buena medida. Una pantalla sirve de objetivo de concisión, no de límite técnico.
¿Pongo contraseñas o claves para que las tenga a mano? Nunca. El archivo dice que .env no se toca; no copia lo que hay dentro.