Te apuesto una pera a que, como programador (o persona común y corriente), alguna vez has visto un archivo .md. ¿No me crees? ¿Crees que perdí mi apuesta? Pues lamento decirte que te he ganado aun cuando ni siquiera sepas lo que es un archivo .md — porque estás leyendo uno en este mismo momento.
Por qué le pedimos a la IA que escriba el README y ya
Últimamente veo que, como programadores, le decimos a la IA "oye, escribe el README de mi app, muchas gracias de antemano", y no está mal — no te estoy diciendo que lo escribas tú mismo con el formato que quieras. Pero, ¿sabes lo que dice? ¿Lo leíste antes de subirlo a tu repo de GitHub? De eso quiero que hablemos hoy.
¿Qué es realmente un archivo .md?
Es sencillo: un archivo .md es simplemente un tipo de archivo de marcado ligero que sirve para dar formato a tus textos (títulos, negritas, cursivas, listas, etc). Son muy utilizados porque su estructura es fácil de entender, y son los que usa GitHub —el repositorio de código más grande del mundo— para mostrar documentación. Si quieres profundizar en su estructura, puedes revisar esta introducción a Markdown.
Al ser tan sencillos de crear y leer, las IA entienden perfectamente qué están leyendo y qué escriben. Y precisamente por eso se convierten en un archivo muy importante.
El favor mal explicado
Imagina que le pides a un familiar que te ayude con un favor. Si se lo dices todo de golpe, probablemente ni entienda qué le estás pidiendo. Por ejemplo: "oye, en mi cajón está un cuaderno que se me olvidó traer a la universidad, ¿me lo puedes traer, porfa?". Tu familiar estará dispuesto a ayudarte, pero, ¿qué cajón debe buscar? ¿Qué cuaderno debe llevar? ¿Cuánto tiempo tiene?
Es mejor dejar instrucciones detalladas: "en mi cuarto, entrando hay una mesita de noche, la que está del lado derecho de la cama, no la del izquierdo. En el tercer cajón de arriba hacia abajo hay un cuaderno verde lima. ¿Me lo puedes traer urgente, porfa? Tengo que entregarlo a las 11 am." Es mucho más detallado, le da contexto a tu familiar y elimina lugar a equivocaciones.
Los archivos .md —a nivel de código y documentación— funcionan igual. En programación y en la web sirven para escribir documentación, blogs (como este) y muchas cosas más. Pero, ¿sabes para qué más sirven? Para nuestro mejor amigo tecnológico: la IA.
Por qué esto también aplica a la IA
En proyectos de programación la cantidad de archivos es gigante. Puedes tener miles o millones de archivos regados por todo lado, conectados entre sí por la modularización, y perdiéndote incluso a ti mismo entre tanta cantidad de código. A la IA le pasa algo similar: no se pierde exactamente, porque va a intentar darte una solución así tenga que dar vueltas hasta cumplir lo que le pides — pero eso consume el uso que podrías destinar a pedirle algo más.
Ahora imagina a la IA como ese familiar del ejemplo anterior. Si le dices "uy, mira que tengo un bug en alguna parte del código, ahí veras tú cómo le haces para encontrarlo", probablemente se quede dando vueltas buscando un solo archivo, consumiendo tokens y gastando energía en algo que podrías resolver más rápido con el contexto correcto. Y eso no es todo: ¿cómo puede saber de qué trata tu código si nadie se lo explica? Para eso también sirven los archivos .md.
Los archivos que deberías conocer
Hablemos de algunos que son importantes:
README.md: tal vez el más famoso del grupo. No es solo para que quien entra a tu GitHub diga "wow, qué repo tan bonito" (nadie se fija en eso). Es más para que encuentren cómo funciona el código sin tener que leerlo entero: instrucciones de instalación, contexto corto de la aplicación, comandos y demás información relevante, tanto para desarrolladores como para la IA. Puedes revisar un ejemplo real en GitHub.CONTEXT.md: ha tomado bastante fuerza desde que llegó la IA. Sirve para entregarle contexto sobre cómo quieres que trabaje, escriba código, y de qué trata tu app. La IA está pensada para revisar este documento antes de hacer cualquier cosa y entender el contexto de tu aplicación. Lo escribes una vez y la IA lo lee siempre. Aquí puedes detallar la arquitectura, la stack de tecnologías, cuál es el "corazón" del proyecto, estándares de código y más. Es un archivo cambiante: lo actualizas cada vez que agregas nuevas funcionalidades. Puedes revisar una plantilla real de CONTEXT.md.AGENTS.md/CLAUDE.md: parecido al CONTEXT, pero sirve para darle reglas de comportamiento e invariantes a tu IA — qué comandos ejecutar para que tu proyecto funcione, qué convenciones seguir. Por ejemplo, yo siempre pongo que deje el código documentado en primera persona y bien detallado; así, cuando reviso lo que implementó, es mucho más sencillo entender qué quería hacer. Vale la pena mencionar que AGENTS.md ya no es solo una convención informal entre desarrolladores: es un estándar abierto que adoptaron GitHub Copilot, Cursor, OpenAI Codex y Google Jules, entre otros. Puedes revisar el estándar oficial de AGENTS.md, un ejemplo real en producción, o esta colección curada de archivos CLAUDE.md.ARCHITECTURE.md: de los de la vieja escuela. Importantísimo cuando trabajas con más personas, o incluso para que tú mismo no olvides la arquitectura de tu software. Aquí escribes cómo funciona realmente tu aplicación: dónde se guardan los datos, cómo se estructuran tu backend y frontend, la filosofía y el diseño de arquitectura que quieres seguir. La IA puede leerlo y entender por qué debe respetar ese diseño y por qué los archivos van donde van. Puedes revisar un ejemplo real de ARCHITECTURE.md.DOCS/CHANGELOG.md: aquí se guarda documentación (como el funcionamiento de una API) y el registro de cambios de la aplicación. Así, tanto la IA como los desarrolladores entienden el porqué de una decisión y cuándo se tomó. Puedes revisar Keep a Changelog, el estándar más usado para este tipo de archivo.
Y como estos, hay muchos más. No se trata de que ahora tengas que seguir una lista de pasos al pie de la letra para construir un software sostenible. Es simplemente una cuerda que le dejas a alguien —incluso a ti mismo— para que, cuando caiga en ese "pozo de sentirse perdido", pueda salir de forma más sencilla.
No es una receta grabada en piedra
Espero que hayas entendido la importancia de estos archivos, y que te tomes el tiempo de leer los .md de algún proyecto en el que participas, o de los tuyos propios. No dejes que los templates de README se queden siempre igual. En vez de pedirle a la IA que haga lo mismo una y otra vez, escribe una sola vez un ARCHITECTURE.md, un AGENTS.md y un README.md bien pensados. O simplemente dile a la IA que te ayude a escribirlos, los lees, le pides cambios, y creas los archivos definitivos que te ayudarán a mantener tu código de forma más sencilla. No está escrito en mármol, así que tampoco le tengas miedo a cambiarlos.
Hacer documentación es mucho más sencillo de lo que era hace unos años. Afortunadamente, la IA puede recoger información de lo que escribiste y dejar documentado correctamente todo lo que hay en tu código, de forma que sea más sencillo tanto para ti, como para otros devs, como para la propia IA.
Y es que la IA es una herramienta que nos ayuda a potenciar al máximo nuestro trabajo, y a corto plazo no se va a ir. La IA llegó para quedarse. Y de eso hablaremos en nuestro próximo artículo.
Ten una feliz semana, y no desesperes por el avance.