Qué es un README.md y para qué sirve

Abres una carpeta que hiciste hace medio año y ahí están: ocho archivos con nombres que en su momento tenían todo el sentido del mundo. index.html, final.html, final-2.html. ¿Cuál era el bueno?

El README.md existe para eso. Es un archivo de texto, de los que viste en qué es un archivo md, con un nombre acordado por todo el mundo: se llama así, en mayúsculas, para que sea el primero de la lista y el primero que se lee.

El cartel de la puerta

Piensa en el letrero de un local. No explica el negocio entero ni cuenta la historia del dueño. Dice si estás en la puerta correcta, qué se hace ahí adentro y a qué hora. Eso es un README: lo mínimo para que alguien que llega sin contexto sepa dónde está parado.

Y es lo primero que se ve de verdad, no es una manera de hablar. Cuando entras a una carpeta desde la terminal, ahí está, arriba de todo:

$ lsREADME.mdhorarios.mdindex.html$ cat README.md# Barbería La EsquinaLa página del negocio. Un solo archivo, no necesita instalar nada.## Cómo se veDoble clic en index.html.

Las mayúsculas del nombre no son grito: hacen que quede arriba cuando la lista se ordena por nombre. Es una convención vieja y la respeta todo el mundo.

Las tres preguntas que contesta

Qué es esto, cómo se usa, y a quién le pregunto si algo falla. Con esas tres respuestas el README ya está haciendo su trabajo, y la mayoría de los buenos no tienen mucho más.

La tercera parece la menos importante y es la que más se agradece. Un número de teléfono, un correo, o incluso una línea que diga «esto lo armó Ana en septiembre» le ahorra media hora a quien venga después. Aunque quien venga después seas tú.

El README de la barbería

Así se ve uno completo. A la izquierda lo que escribes, a la derecha lo que se ve cuando alguien lo abre en un visor:

# Barbería La Esquina

La página del negocio, en un solo archivo. **No necesita instalar nada.**

## Cómo se ve

Doble clic en `index.html`. Se abre en el navegador.

## Qué cambiar

- el número de WhatsApp, al final de `index.html`

- los precios, en la sección de precios

## Quién sabe de esto

Julio, el dueño. Y Ana, que armó la página.

Nueve líneas. Le tomó cinco minutos escribirlas y contestan las tres preguntas. Si mañana Julio le pide a un agente que le cambie los precios, lo primero que va a leer el agente es este archivo, y va a saber dónde tocar sin preguntar.

Lo que no va en el README

El historial de todo lo que hiciste, las ideas para el futuro y las discusiones sobre por qué elegiste una cosa u otra. Nada de eso es malo, simplemente no va en el cartel de la puerta: un README de cuatro pantallas ya no lo lee nadie, y entonces deja de servir para lo único que servía.

Tampoco van las decisiones que le das al agente. Ese es otro archivo y otra conversación: el archivo donde tomas las decisiones del proyecto. La diferencia entre los dos es de destinatario. El PROYECTO.md es lo que tú decides, escrito para que el agente lo respete. El README es lo que cualquiera necesita saber al llegar, escrito para personas.

Quién lo lee primero

Un amigo al que le pasas la carpeta. Tú mismo, en marzo, cuando no te acuerdes de nada. Y el agente, que abre la carpeta y busca justamente ese archivo antes de tocar nada, porque Markdown es lo que mejor lee.

Escribe el tuyo hoy, aunque sea de cinco líneas. Es el único archivo de un proyecto que se paga solo la primera vez que alguien lo abre.